Wallet Transaction Output Tracking (Output Baskets)
Ty Everett (ty@projectbabbage.com)
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.
Specification
We extend the BRC-1 Transaction Creation Request message so that, in addition to the normal script
and satoshis
fields defined in each element of the outputs
array, there is another basket
field. The new basket
field is a string comprising the name of the basket into which this output is to be inserted and tracked by the wallet. We specify that, when a wallet creates a transaction responsive to the Transaction Creation Request, it utilizes some internal storage and retrieval system (beyond the scope of this specification) to associate the specified output with the specified basket.
To allow applications to specify information that would later be needed to unlock and use outputs that are stored in baskets, an optional customInstructions
field can also be added when basket
is given. This field is retained by the wallet and included as part of the Transaction Outputs Response (defined below).
To facilitate permissioned access to baskets by applications, we stipulate that the wallet, upon receiving a transaction creation request, may prompt the user to grant permission for the application to use the basket. The method by which the wallet seeks the consent of the user is out-of-scope for this standard, but the process, if it occurs, must be facilitated by the wallet asynchronously between the receipt of the Transaction Creation Request and the furnishment of any Transaction Creation Response or Transaction Creation Error messages.
To facilitate access to the tokens stored within baskets by applications, we define a new set of messages across the abstract communications channel between the wallet and the application, as follows:
Transaction Outputs Request
This message constitutes a request by the application for a list of Bitcoin UTXOs that are responsive to the request. The message contains the following information:
Field | Required | Description |
---|---|---|
| yes | The basket from which outputs should be returned |
| no | Whether BRC-8 transaction envelopes are requested for the outputs |
| no | The maximum number of outputs to return |
| no | The number of outputs from the beginning of the list to skip |
| no | Always considered to be |
This provides the wallet with enough information to furnish the outputs requested by the application. Here is an example of a simple Transaction Outputs Request in JSON:
In this example, the application is stipulating that a maximum of 25 outputs from the todo tokens
basket are to be returned, including their BRC-8 transaction envelopes.
Transaction Outputs Response
The response comprises a list of transaction outputs currently in the specified basket. This is an array of objects where each object has the following fields:
Field | Description |
---|---|
| The number of satoshis in the transaction output |
| The TXID of the transaction that created the output, given as a hex string |
| The output index number of this output within the transaction that created it |
| The hex-encoded Bitcoin script program that locks the output |
| The spending instructions that were stored when the output was created |
| If envelopes were requested, the BRC-8 Transaction Envelope for this transaction |
Here is an example of a simple Transaction Outputs Response:
Transaction Outputs Error
If the Bitcoin wallet is unable to fulfill the Transaction Outputs Request for any reason, we specify that it should respond with a JSON-formatted Transaction Outputs Error. The fields for the object are specified as follows:
Field | Description |
---|---|
| This should always be a string comprising |
| A machine-readable error code. Extensions to this standard can define specific error codes and standardize additional fields. Codes are strings, for example |
| All errors must have a human-readable |
One example of a Transaction Outputs Error is given below:
Implementations
This functionality is implemented as part of the Babbage SDK, via the getTransactionOutputs
function.
Last updated