> For the complete documentation index, see [llms.txt](https://bsv.brc.dev/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://bsv.brc.dev/wallet/0153.md). # Action Reference Labels for BRC-100 Wallets David Case ## Abstract This specification defines a backwards-compatible extension to [BRC-100](/wallet/0100.md) that exposes each action’s wallet `reference` as a synthetic label on `listActions` results. No new request or response fields are introduced, and the label is not persisted as ordinary action metadata. ## Motivation Under [BRC-100](/wallet/0100.md), `createAction` may return `signableTransaction.reference`. That value is required for subsequent `signAction` and `abortAction` calls. The interface does not include `reference` on action records returned from `listActions`. If an application loses the reference after a successful `createAction`—for example because of process failure, lost in-memory scope, or a delayed multi-step signing flow—there is no interoperable way to resume or abort the in-flight action through the public wallet interface. Adding a new field to action records would change the `listActions` response shape, break WalletWire consumers, and require version or capability negotiation. Following the special-operation label pattern used by [BRC-114](/wallet/0114.md), this specification surfaces `reference` inside the existing `labels` array as response-derived metadata. The BRC-100 reference implementation (`bsv-blockchain` ts-sdk / wallet-toolbox) normalizes labels by trimming and lowercasing before persistence and query matching, as documented in [BRC-100](/wallet/0100.md) and [BRC-65](/wallet/0065.md). Action `reference` values are `Base64String` and therefore case-sensitive, so the synthetic label encodes reference bytes as lowercase hex. ## Specification ### Reserved label form This specification reserves labels of the form: * `reference ` Where `` is the lowercase hexadecimal encoding of the raw bytes of the action’s wallet `reference` (`Base64String` decoded to bytes). That `reference` is the value defined by BRC-100 (`signableTransaction.reference`, and the `reference` argument to `signAction` / `abortAction`). The prefix is exactly `reference` (lowercase, single trailing space before the value). The hex value must use only characters `0-9` and `a-f`, with even length and no `0x` prefix. ### Reserved prefix Labels beginning with `reference` are reserved for this specification’s response annotation. The synthetic label must not be persisted as ordinary action metadata. ### Response reference label When `listActions` is called with `includeLabels` set to `true`, each returned action must include exactly one synthetic label: * `reference ` derived from that action’s stable wallet reference: 1. Take the action `reference` as a BRC-100 `Base64String`. 2. Decode it to raw bytes. 3. Encode those bytes as lowercase hex. Rules: * Include the label only when `includeLabels` is `true`. * If the returned labels already contain any entry beginning with `reference` , replace those entries with the single wallet-authored synthetic label (do not leave forged or stale values alongside it). * The value must round-trip to the same `reference` accepted by `signAction` and `abortAction` for that action. * The underlying reference remains stable for the life of the action record across all statuses exposed by the wallet (including `unsigned`, `nosend`, `sending`, `unproven`, `completed`, and `failed`). * The label must satisfy general label constraints in [BRC-100](/wallet/0100.md). ### listActions No other list behavior is required beyond BRC-100. Callers recover references by listing with ordinary application labels and reading the synthetic `reference ` entry when `includeLabels` is `true`. How a wallet obtains `reference` internally (for example from local or remote storage) is an implementation concern outside this specification. ### Recovery 1. Create the action with an ordinary correlator label (e.g. `my-app-flow-xyz`). 2. If the in-memory reference is lost, call `listActions({ labels: ["my-app-flow-xyz"], includeLabels: true })`. 3. Read `reference ` from the matching action’s `labels`. 4. Decode `` to bytes, encode those bytes as standard base64, and use the result as `reference` for `signAction` or `abortAction`. ## Conclusion By exposing each action’s wallet `reference` as a synthetic `listActions` label, this specification closes the recovery gap for in-flight BRC-100 actions without changing the API surface, WalletWire encodings, or ordinary label storage. ## References * [BRC-100](/wallet/0100.md) — Unified wallet-to-application interface * [BRC-65](/wallet/0065.md) — Transaction labels and list actions * [BRC-114](/wallet/0114.md) — Time labels for list actions --- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## 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, and the optional `goal` query parameter: ``` GET https://bsv.brc.dev/wallet/0153.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal. 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.