# Transaction Labels and List Actions * Ty Everett () ## 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](/wallet/0100.md). The singular `label` request field, `skip` pagination field, and [BRC-8](/transactions/0008.md) 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](/wallet/0111.md). Unsupported P-label schemes MUST be rejected rather than treated as normal labels. Example: ```json { "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: ```json { "labels": ["payment"], "labelQueryMode": "any", "includeLabels": true, "limit": 10, "offset": 0 } ``` The response is a BRC-100 `ListActionsResult`: ```json { "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](/wallet/0116.md) and [BRC-111](/wallet/0111.md). ## Implementations This functionality is implemented by current `bsv-blockchain/ts-sdk` BRC-100 wallet interfaces and `bsv-blockchain/wallet-toolbox` storage and permission layers. --- # Agent Instructions: Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter: ``` GET https://bsv.brc.dev/wallet/0065.md?ask= ``` The question should be specific, self-contained, and written in natural language. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.