Basket and Custom Instructions Extension for Bitcoin Outpoints

Ty Everett ([email protected])

Abstract

This document defines a minimal extension to BRC-36 for associating a Bitcoin outpoint with a wallet basket and, optionally, with custom instructions whose meaning is defined by that basket. The purpose of this extension is to support interoperable wallet-managed output organization without standardizing wallet-internal classification systems or forcing a universal instruction schema.

Motivation

Modern wallets do more than merely store outputs. They organize outputs into permissioned collections, often called baskets, and attach application-relevant metadata needed to later interpret or spend those outputs. This pattern is reflected in BRC-46, BRC-100, and current Wallet Toolbox implementations.

The original version of BRC-37 used a broad spendingInstructions concept whose structure was left entirely to wallet software. That approach was too vague to provide meaningful interoperability. This revision keeps the extension intentionally small and precise: it standardizes basket association and optional custom instructions, while leaving basket-specific semantics to the basket itself and the higher-layer protocols that use it.

Specification

Extended Object

A BRC-37 object is a BRC-36 object extended with the following fields:

• basket (required): The basket with which the outpoint is associated.

• customInstructions (optional): Basket-defined custom instructions associated with the outpoint.

Semantics

• The basket field identifies the basket context in which the output is to be interpreted.

• The meaning of customInstructions, when present, is determined by the basket named in basket.

• BRC-37 does not define a universal schema for customInstructions.

• BRC-37 does not require every basket to use customInstructions.

• Software that understands a basket's semantics may interpret the corresponding customInstructions value. Software that does not understand that basket may still transport or store the value unchanged.

Scope Boundaries

BRC-37 does not standardize:

• wallet-internal state such as spendable or change

• wallet-specific classification fields such as purpose or type

• storage relations such as spending links, sequence bookkeeping, or script offsets

• a general schema for all possible spending metadata

Those concerns remain outside the scope of this specification unless separately standardized by another BRC.

Example Guidance

The following examples are non-normative and illustrative only.

Basket-Defined Meaning

A wallet may define a basket whose outputs all use the same customInstructions convention. Software that requests outputs from that basket can then interpret customInstructions according to the basket's documented semantics.

BRC-29 Example

In one possible implementation, outputs placed in the default basket may represent BRC-29 payments. In that context, customInstructions could contain a JSON-serialized object carrying payment-related context such as a sender identity key, derivation prefix, derivation suffix, or other information useful to the receiving wallet or application.

This example is illustrative only. BRC-37 does not require the default basket to behave this way, nor does it impose a universal JSON schema for such instructions.

Relationship to Other Standards

• BRC-36 defines the portable base output object.

• BRC-46 defines basket-oriented wallet behavior.

• BRC-100 defines the current interoperable wallet interface through which basket-associated outputs are commonly exchanged.

Example

{
  "outpoint": "7001295a287fee8e7ad5de58ed30bd61923977ddc9b7a44830ebb9a68b12dc39.0",
  "satoshis": 500,
  "lockingScript": "76a9148055582669432149141abcf887fced6881f7404288ac",
  "tx": "01010101...",
  "basket": "default",
  "customInstructions": "{\"senderIdentityKey\":\"03...\",\"derivationPrefix\":\"...\",\"derivationSuffix\":\"...\"}"
}

Implementation

Implementations of BRC-37 should adhere to the following guidelines:

• Preserve unknown customInstructions values unchanged when transporting or storing BRC-37 objects.

• Define basket-specific semantics in the protocol or implementation documentation for that basket.

• Avoid treating BRC-37 as a general container for arbitrary wallet-internal state.