BRC-37

Basket and Custom Instructions Extension for Bitcoin Outpoints

An output on its own says nothing about which application it belongs to or what it is for. This adds a way to tag one with the group it belongs to, and with instructions whose meaning that group defines.

Ty Everett5 May 2023changed 1 May 20263 min read

Why: Wallets need a common way to say which named group an output belongs to and to carry extra notes about it, without forcing every wallet to agree on what those notes mean.
What: BRC-37 is a small extension to the BRC-36 output object that adds a required basket name and an optional field for basket-defined custom instructions.
How: A developer adds a basket field naming the collection an outpoint belongs to, and, if that basket defines a convention for it, a customInstructions field whose contents only software that understands that basket needs to parse.

What this lets you do

Tag an outpoint with the basket it belongs to
Attach basket-specific custom instructions to an outpoint
Pass unrecognized customInstructions through unchanged instead of dropping them
Build basket-specific conventions, like a BRC-29 payment context, on top of a shared field
Interoperate across wallets without agreeing on a universal instruction schema

Written by claude-sonnet-5 from the specification text. Where the two differ, the original is correct.

Reference for an AI

Everything an assistant needs to answer questions about BRC-37 accurately, including what it depends on.

The specification

Read the original

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.

Was this helpful?

Summary