Wallet Transaction Output Tracking (Output Baskets)

Ty Everett ([e-mail])

Abstract

We define an extension to BRC-1 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 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 transaction creation requests.

Motivation

Transaction outputs in Bitcoin take many forms, and serve many purposes. While BRC-1 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 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 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. 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:

{
  "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:

{
  "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:

{
  "basket": "todo tokens",
  "tags": ["open"],
  "tagQueryMode": "all",
  "include": "locking scripts",
  "includeCustomInstructions": true,
  "includeTags": true,
  "limit": 25,
  "offset": 0
}

The BRC-100 response is:

{
  "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:

{
  "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, 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.