Action Reference Labels for BRC-100 Wallets

David Case

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:

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.

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

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 <hex> from the matching action’s labels.

4. Decode <hex> 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 — Unified wallet-to-application interface

• BRC-65 — Transaction labels and list actions

• BRC-114 — Time labels for list actions