Baskets & State Management

A basket is a named collection of unspent transaction outputs tracked by a BRC-100 wallet. Baskets give applications a portable way to store user-local state as UTXOs while the wallet enforces permissions.

Baskets come from BRC-46 output tracking. When an app creates an output, it can ask the wallet to place that output into a basket:

1{
2  "outputs": [
3    {
4      "lockingScript": "<locking-script-hex>",
5      "outputDescription": "Application state output",
6      "satoshis": 1000,
7      "basket": "todo tokens",
8      "customInstructions": "{ ... }"
9    }
10  ]
11}

Later, the app can ask the wallet to list outputs in that basket. Spending an output removes it because the UTXO no longer exists. If an app no longer needs to track an unspent output, it can relinquish it without creating a spend.

Why Baskets Matter

Baskets let developers model application state as outputs instead of rows in an app-owned database.

• User-centered permissions: the wallet decides which app can inspect or use which basket.
• Portable state: another compatible app can request the same basket if the user approves.
• UTXO-native tokens: an output can be the token, document pointer, access grant, or workflow item.
• Less indexing work: local state can live with the user until it needs public discovery.

Three State Models

The same app can use all three. A marketplace might keep drafts in a local basket, send buyer/seller messages through MessageBox, and publish active listings to an overlay.

Local Basket Example

1. A to-do app creates one output per task.
2. Each output is placed in a todo tokens basket.
3. On launch, the app calls listOutputs for that basket.
4. Completing a task spends or relinquishes the output.

No server has to be the source of truth for the user's private task list.

Direct Peer-to-Peer Example

1. Alice creates an offer and sends it to Bob through MessageBox.
2. Bob reviews the offer and returns a signed response.
3. The two wallets exchange encrypted messages and payment tokens until the workflow is complete.

This pattern is useful when exactly two parties need coordination and the state is not meant to be globally searchable.

Overlay Example

1. A creator lists a digital item by creating a protocol-specific output.
2. A topic manager validates whether the output belongs in the marketplace topic.
3. Lookup services index valid outputs so apps can search current listings.
4. Buyers contact sellers or pay through the app's chosen protocol.

Use overlays when many users need a shared, queryable view of app state.

Developer Tips

• Name baskets clearly and consistently.
• Request only the baskets and output details your feature needs.
• Use customInstructions for spending hints your app will need later.
• Paginate listOutputs results for large baskets.
• Prefer relinquishOutput when the app should stop tracking an unspent output without spending it.
• Move public or multi-party state into overlays instead of overloading a user's local basket.

Related References

• BRC-46 output baskets
• BRC-100 wallet interface
• Wallet reference
• MessageBox client
• Overlay services