BRC-65

Transaction Labels and List Actions

A wallet holding hundreds of transactions with no way to tell them apart is hard to make sense of. This lets an application attach its own labels when a transaction is made, and later list transactions by those labels.

Ty Everett17 Aug 2023changed 1 May 20263 min read

Why: Applications need a consistent way to categorize transactions and later retrieve just the ones relevant to a given purpose, without each wallet inventing its own scheme.
What: BRC-65 is the standard for attaching organizational labels to Bitcoin wallet transactions and querying transactions back out by those labels.
How: An app passes a `labels` array when calling BRC-100's `createAction` or `internalizeAction`, then later calls `listActions` with a `labels` filter, a match mode, and inclusion flags to get back a `ListActionsResult` containing matching actions and a total count.

What this lets you do

Tag a transaction with one or more labels when creating it
Filter and retrieve transactions by matching any or all labels
Choose which extra details come back (inputs, outputs, scripts, labels) when listing
Paginate through large sets of labeled transactions with limit and offset
Reject unsupported reserved label schemes instead of silently accepting them

Written by claude-sonnet-5 from the specification text. Where the two differ, the original is correct.

Reference for an AI

Everything an assistant needs to answer questions about BRC-65 accurately, including what it depends on.

The specification

Read the original

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.

Was this helpful?

Summary