# Wallet Transaction Output Tracking (Output Baskets) Ty Everett () ## Abstract We define an extension to [BRC-1](/wallet/0001.md) that enables a wallet to facilitate the tracking of specific application-defined transaction outputs within baskets. A new set of messages across the abstract messaging interface facilitates applications' access to unspent outputs stored in these baskets, with a permission system similar to that described in [BRC-43](/key-derivation/0043.md) employed to regulate access by applications. Spending an output stored in a basket removes it, while new outputs can be added by specifying their basket as part of [BRC-1](/wallet/0001.md) transaction creation requests. ## Motivation Transaction outputs in Bitcoin take many forms, and serve many purposes. While [BRC-1](/wallet/0001.md) defines a way for applications to request the creation of transaction outputs by wallets, there is no way for applications to request that a wallet tracks these outputs. Enabling applications to request that wallets track outputs provides a number of advantages: First, applications may no longer need to rely on external data storage and retrieval systems, simplifying their architecture. Second, there is the potential to represent different types of Bitcoin-native tokens within specific baskets, and define protocols for manipulating specific types of tokens based on which baskets they are stored in. Finally, when permission to access a basket is decided by the user on a per-application basis, it facilitates a greater degree of control for users over their tokens, enabling multiple applications to access and use the same tokens. ## Status Note This specification remains the conceptual basis for wallet output baskets, but the legacy BRC-1/BRC-8 message shapes below have been superseded by the [BRC-100](/wallet/0100.md) wallet interface. New implementations MUST use BRC-100 `createAction`, `internalizeAction`, `listOutputs`, and `relinquishOutput` semantics for basket operations. The historical fields `includeEnvelope`, `amount`, `txid`, `vout`, `outputScript`, and `envelope` are deprecated in this context. Current wallet implementations return `outpoint`, `satoshis`, optional `lockingScript`, optional `customInstructions`, and optional [BRC-62](/transactions/0062.md) BEEF data through BRC-100. ## Specification ### Basket Naming A basket name is an application-defined identifier for a wallet-managed set of tracked outputs. In current BRC-100 implementations, basket identifiers are normalized by trimming whitespace and lowercasing the value, and must be between 1 and 300 UTF-8 bytes. Basket names beginning with `p` are reserved for future or installed permission modules as defined by [BRC-99](/wallet/0099.md). Wallets may also reserve implementation-internal admin basket names; wallet-toolbox uses `admin ...` baskets for permission-token storage and denies non-admin access. ### Inserting Outputs During Transaction Creation Applications insert new transaction outputs into baskets by providing `basket` on a BRC-100 `createAction` output: ```json { "description": "Create a todo token", "outputs": [ { "lockingScript": "76a914...88ac", "satoshis": 1, "outputDescription": "Todo token", "basket": "todo tokens", "customInstructions": "{\"unlock\":\"context\"}", "tags": ["open"] } ] } ``` The optional `customInstructions` value is retained by the wallet as application metadata for later spending. The optional `tags` array supports filtering and categorization within the basket. ### Internalizing Existing Outputs Into Baskets Applications or services can import an existing Atomic BEEF transaction using BRC-100 `internalizeAction`. To insert a specific output into a basket, the output metadata uses: ```json { "outputIndex": 0, "protocol": "basket insertion", "insertionRemittance": { "basket": "todo tokens", "customInstructions": "{\"unlock\":\"context\"}", "tags": ["open"] } } ``` The only current `internalizeAction` protocol strings are `wallet payment` and `basket insertion`. ### Listing Outputs Applications list basketed outputs with BRC-100 `listOutputs`. | Field | Required | Description | | --------------------------- | -------- | ----------------------------------------------------------------------- | | `basket` | yes | Basket whose tracked outputs should be returned | | `tags` | no | Tags used to filter outputs | | `tagQueryMode` | no | `any` or `all`; defaults to `any` | | `include` | no | `locking scripts` or `entire transactions` | | `includeCustomInstructions` | no | Include stored custom instructions | | `includeTags` | no | Include output tags | | `includeLabels` | no | Include labels on the containing actions | | `limit` | no | Maximum number of outputs to return; current validation defaults to 10 | | `offset` | no | Offset into the result set; negative offsets count back from the end | | `seekPermission` | no | Whether the wallet may seek user permission if needed; defaults to true | Example: ```json { "basket": "todo tokens", "tags": ["open"], "tagQueryMode": "all", "include": "locking scripts", "includeCustomInstructions": true, "includeTags": true, "limit": 25, "offset": 0 } ``` The BRC-100 response is: ```json { "totalOutputs": 1, "outputs": [ { "outpoint": "900b7e9ced44f8a7605bd4c1b7054b8fb958385998954d772820a8b81eabb56f.0", "satoshis": 1000, "lockingScript": "76a914...88ac", "spendable": true, "customInstructions": "{\"unlock\":\"context\"}", "tags": ["open"] } ] } ``` When `include` is `entire transactions`, the response may also contain a `BEEF` property carrying transaction data needed to validate or inspect the returned outputs. ### Removing Outputs From Basket Tracking Applications relinquish wallet tracking for a basketed output with BRC-100 `relinquishOutput`: ```json { "basket": "todo tokens", "output": "900b7e9ced44f8a7605bd4c1b7054b8fb958385998954d772820a8b81eabb56f.0" } ``` Relinquishment removes the wallet's basket tracking for the output; it is not a Bitcoin spend by itself. ### Permission Behavior Wallets may require user authorization before allowing an originator to insert, list, or relinquish basket outputs. Current wallet-toolbox permission behavior is specified in [BRC-116](/wallet/0116.md), including grouped basket permissions, admin basket restrictions, and P-basket module delegation. ## Implementations This functionality is implemented by current `bsv-blockchain/ts-sdk` BRC-100 wallet interfaces and `bsv-blockchain/wallet-toolbox` storage and permission layers. --- # Agent Instructions: Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter: ``` GET https://bsv.brc.dev/wallet/0046.md?ask= ``` The question should be specific, self-contained, and written in natural language. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.