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.

Specification

BRC-65 extends the functionality of BRC-56 by introducing the concept of transaction labels and the ability to list labeled transactions. This extension adds two new features to the wallet-to-application messaging layer: labeling transactions at the point of creation and retrieving labeled transactions.

Transaction Labels

The labels field is introduced as an optional parameter next to the outputs array and description of the BRC-1 Transaction Creation Request in BRC-56. This field allows applications to label transactions. Each label must be no longer than 300 characters and can only contain letters, numbers, and underscores.

The updated Transaction Creation Request with the labels field is as follows:

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

In this example, the application is creating a transaction with the labels "payment" and "personal". These labels can be used to categorize and organize the transaction in a way that is meaningful to the application.

List Actions

BRC-65 introduces the listActions message (the Actions List Request) to retrieve a list of Bitcoin transactions based on their labels. The Actions List Request message takes the following parameters:

Field	Description
label	The label to filter the transactions by.
skip	The number of transactions to skip before returning results (optional).
limit	The maximum number of transactions to return (optional).

The Actions List Request message retrieves Bitcoin transactions that have been labeled with the specified label. The skip parameter allows applications to retrieve a subset of transactions by skipping a certain number of transactions from the beginning of the list. The limit parameter defines the maximum number of transactions to return. If skip and limit are not provided, the request will return all transactions with the specified label.

The Actions List Response comprises an array of BRC-8 Transaction Envelopes as defined in BRC-56, representing the labeled transactions, along with a totalActions field denoting the total number of transactions with the specified label.

An example Actions List Request message with the label "payment" and a limit of 10 transactions is as follows:

{
  "label": "payment",
  "limit": 10
}

The corresponding Actions List Response would contain an array of BRC-8 Transaction Envelopes as well as the totalActions field:

{
  "transactions": [
    {
      "rawTx": "...",
      "inputs": { ... },
      "mapiResponses": { ... },
      "txid": "..."
    },
    ...
  ],
  "totalActions": 42
}

In this example, the actions list response includes an array of BRC-8 Transaction Envelopes representing the labeled transactions with the label "payment". The totalActions field indicates that there are a total of 42 transactions with the "payment" label.

Implementations

Implementations of this specification will need to extend the existing wallet software in order to support the labeling of transactions and the listing of labeled transactions. Wallets will need to ensure that they can create transactions with labeled outputs and store the labels for future retrieval. Applications will need to handle the labeling of transactions and make use of the Actions List Request to retrieve labeled transactions.

Some existing implementations of BRC-56 may already support the labeling and listing of transactions, while others may need to update their software to include this additional functionality. The Babbage MetaNet Client, for example, has already implemented the Transaction Labels and List Actions functionality.