Transaction Labels and List Actions

• Ty Everett ([e-mail])

Abstract

BRC-65 extends the functionality of BRC-56 by introducing the ability to label Bitcoin transactions when they are created using the BRC-1 Transaction Creation Request. This extension allows applications to organize and categorize transactions for different purposes. BRC-65 also introduces the capability to list labeled transactions, providing applications with an easy way to retrieve specific sets of transactions based on their labels. This standardization improves interoperability between wallets and applications and enhances the user experience by enabling the display of transaction lists relevant to specific categories or actions.

Motivation

The motivation behind BRC-65 is to enhance the functionality of the Bitcoin wallet messaging layer defined in BRC-56 by introducing the ability to label transactions. This functionality allows applications to categorize and organize transactions based on specific criteria. By labeling transactions, applications can easily retrieve and display transaction lists that are relevant to specific actions or categories. This simplifies the user experience and enables users to quickly find, review, and analyze specific sets of transactions.

By defining a standard mechanism for labeling transactions and listing labeled transactions, BRC-65 promotes interoperability between wallets and applications. With this standardization, applications can expect consistent behavior across different wallets, making it easier for developers to create Bitcoin-powered applications without having to build custom wallet functionality. Furthermore, users can switch between wallets seamlessly without losing access to their labeled transactions.

Status Note

BRC-65 remains the conceptual standard for wallet action labels, but its original BRC-56/BRC-1 message shapes have been superseded by BRC-100. The singular label request field, skip pagination field, and BRC-8 envelope response model are deprecated for current wallets.

New implementations MUST use BRC-100 createAction, internalizeAction, and listActions behavior.

Specification

Labels

The labels field is an optional array on BRC-100 createAction and internalizeAction calls. Labels are application-defined strings used to organize wallet actions.

Current BRC-100 validation normalizes labels by trimming whitespace and lowercasing the value. A label must be between 1 and 300 UTF-8 bytes. The older restriction to letters, numbers, and underscores only is no longer current.

Labels beginning with p are reserved for installed or future label permission modules as defined by BRC-111. Unsupported P-label schemes MUST be rejected rather than treated as normal labels.

Example:

{
  "description": "Pay John Galt 3,301 satoshis",
  "labels": ["payment", "personal"],
  "outputs": [
    {
      "lockingScript": "76a914b10f7d6c7fda3285e9b98297428ed814374cbd4088ac",
      "satoshis": 3301,
      "outputDescription": "Payment to John Galt"
    }
  ]
}

List Actions

BRC-100 listActions retrieves wallet actions based on labels and optional inclusion flags:

Field	Description
labels	Array of labels to filter actions by
labelQueryMode	any or all; defaults to any
includeLabels	Include action labels in returned actions
includeInputs	Include inputs in returned actions
includeInputSourceLockingScripts	Include source locking scripts for inputs
includeInputUnlockingScripts	Include unlocking scripts for inputs
includeOutputs	Include outputs in returned actions
includeOutputLockingScripts	Include output locking scripts
limit	Maximum number of actions to return; current validation defaults to 10
offset	Offset into the result set; negative offsets count back from the end
seekPermission	Whether the wallet may seek user permission if needed; defaults to true

Example:

{
  "labels": ["payment"],
  "labelQueryMode": "any",
  "includeLabels": true,
  "limit": 10,
  "offset": 0
}

The response is a BRC-100 ListActionsResult:

{
  "totalActions": 42,
  "actions": [
    {
      "txid": "900b7e9ced44f8a7605bd4c1b7054b8fb958385998954d772820a8b81eabb56f",
      "satoshis": 3301,
      "status": "completed",
      "isOutgoing": true,
      "description": "Pay John Galt 3,301 satoshis",
      "labels": ["payment", "personal"]
    }
  ]
}

Current action status values are defined by BRC-100 and include completed, unprocessed, sending, unproven, unsigned, nosend, nonfinal, and failed.

Permission Behavior

Wallets may require user authorization before an originator applies or queries labels. Current wallet-toolbox behavior, including grouped label checks and P-label module delegation, is specified in BRC-116 and BRC-111.

Implementations

This functionality is implemented by current bsv-blockchain/ts-sdk BRC-100 wallet interfaces and bsv-blockchain/wallet-toolbox storage and permission layers.