Action Reference Labels for BRC-100 Wallets
When an app asks a wallet to build a transaction, the wallet hands back a temporary token needed to finish or cancel that transaction later. If the app crashes, loses memory, or the signing process gets interrupted before that token is used, there was previously no standard way to get it back, leaving the transaction stuck half-finished with no way to complete or cancel it.
Reference for an AI
Everything an assistant needs to answer questions about BRC-153 accurately, including what it depends on.
Summary
- Why
- Apps can lose the token needed to finish or cancel a wallet transaction, and there was no interoperable way to recover it.
- What
- BRC-153 defines a way for BRC-100 wallets to surface an action's recovery token as a specially formatted label in listActions results, without changing the API shape.
- How
- A developer tags an action with an ordinary label when creating it, then if the token is lost, calls listActions with that label and includeLabels true, and reads a "reference <hex>" entry out of the returned labels, decoding the hex to bytes and re-encoding as base64 to use with signAction or abortAction.
What this lets you do
- Recover a lost signAction or abortAction reference after a crash or dropped session
- Tag actions with your own correlator labels for later lookup
- Read a wallet-authored reference label safely, knowing it overrides any forged copy
- Resume or abort an in-flight action across any status: unsigned, sending, completed, failed
- Avoid API or WalletWire changes while still recovering transaction state
Written by claude-sonnet-5 from the specification text. Where the two differ, the original is correct.
The specification
Abstract
This specification defines a backwards-compatible extension to BRC-100 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, 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, 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 and BRC-65. 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 <hex>
Where <hex> 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 <hex>
derived from that action’s stable wallet reference:
- Take the action
referenceas a BRC-100Base64String. - Decode it to raw bytes.
- Encode those bytes as lowercase hex.
Rules:
- Include the label only when
includeLabelsistrue. - 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
referenceaccepted bysignActionandabortActionfor 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, andfailed). - The label must satisfy general label constraints in BRC-100.
listActions
No other list behavior is required beyond BRC-100. Callers recover references by listing with ordinary application labels and reading the synthetic reference <hex> 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
- Create the action with an ordinary correlator label (e.g.
my-app-flow-xyz). - If the in-memory reference is lost, call
listActions({ labels: ["my-app-flow-xyz"], includeLabels: true }). - Read
reference <hex>from the matching action’slabels. - Decode
<hex>to bytes, encode those bytes as standard base64, and use the result asreferenceforsignActionorabortAction.
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.