BRC-153

Action References for BRC-100 Wallets

Once a wallet starts building a payment, it hands back a token needed to finish signing or to cancel it. If an app crashes, loses that token, or is in the middle of a multi-step approval when something goes wrong, there was previously no standard way to find that in-progress payment again or look it up by ID. This makes it possible to recover, resume, or safely abort a payment the app can no longer locate.

David Case5 Aug 20264 min read

Reference for an AI

Everything an assistant needs to answer questions about BRC-153 accurately, including what it depends on.

Why: Apps using BSV wallets could lose track of an in-progress payment's identifying token and have no standard way to recover or cancel it.
What: BRC-153 is an extension to the BRC-100 wallet interface that makes the action reference (the ID used to sign or abort a transaction) optionally settable by the caller, always present on listed actions, and fetchable directly by a new getAction call.
How: A developer can pass their own reference string when calling createAction or internalizeAction, then later call getAction with that same reference to retrieve the full action record if it was lost, using the same permission checks as listActions.

What this lets you do

Supply a custom reference when creating or internalizing an action
Look up a single action later using its reference via getAction
Rely on reference always appearing on listActions records
Detect duplicate references as an error instead of silent overwrite
Track an action's reference across all its status changes

Written by claude-sonnet-5 from the specification text. Where the two differ, the original is correct.

The specification

Read the original

Abstract

This specification defines a backwards-compatible extension to BRC-100 that allows the caller to optionally supply the action reference on createAction and internalizeAction, requires reference on action records from listActions, and adds a getAction method for single-item lookup by reference.

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, and it does not define a way to fetch one action by reference.

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.

Application-level correlators (labels or output tags) can aid discovery of completed or basket-tracked outputs, but they do not substitute for the wallet’s action reference: tags are not the key used by signAction and abortAction, and they do not make the wallet reference itself recoverable through the standard interface.

internalizeAction also creates wallet-tracked action state. The same optional caller-supplied reference rules apply.

Specification

This BRC extends the BRC-100 wallet interface. Unless stated otherwise, types, permission behavior, and error structure are those of BRC-100.

Action reference

The canonical field name is reference, consistent with signableTransaction.reference, signAction, and abortAction in BRC-100.
Values use the BRC-100 Base64String type.
createAction accepts an optional reference on the request. If omitted, the wallet generates a unique reference.
internalizeAction accepts an optional reference on the request under the same rules.
For a given wallet user, reference values must be unique across action records. If the caller supplies a reference that already exists, the wallet must return an error.
The reference remains stable for the life of the action record across all action statuses exposed by the wallet (including unsigned, nosend, sending, unproven, completed, and failed).

createAction

Field	Required	Description
`reference`	no	Caller-supplied action reference (`Base64String`). If omitted, the wallet generates one.

When the result includes signableTransaction, signableTransaction.reference is the assigned action reference (caller-supplied or wallet-generated).

internalizeAction

Field	Required	Description
`reference`	no	Caller-supplied action reference (`Base64String`). If omitted, the wallet generates one.

listActions

Each action record must include reference.

getAction

getAction fetches a single action by reference.

Field	Required	Description
`reference`	yes	Action reference (`Base64String`)
`includeLabels`	no	Same meaning as `listActions`
`includeInputs`	no	Same meaning as `listActions`
`includeInputSourceLockingScripts`	no	Same meaning as `listActions`
`includeInputUnlockingScripts`	no	Same meaning as `listActions`
`includeOutputs`	no	Same meaning as `listActions`
`includeOutputLockingScripts`	no	Same meaning as `listActions`
`seekPermission`	no	Same meaning as `listActions`

The successful result is a single action object with the same shape as an element of listActions.actions.

If no action exists for reference, or the action is not visible under ordinary permission rules, the wallet must return an error.

Required behavior

getAction must enforce the same originator and permission checks that apply when inspecting the corresponding record via listActions.
Supplying reference on createAction or internalizeAction must not bypass basket, protocol, or other authorization checks.
A second createAction or internalizeAction that supplies a reference already used by an existing action for the user must fail. Wallets must not overwrite the existing action.

Errors

Errors use the uniform structure defined in BRC-100:

status — always "error"
code — a short machine-readable string
description — a human-readable explanation
context — optional additional data

As in BRC-100, wallets may choose their own code naming conventions provided description clearly identifies the failure. Illustrative examples:

{
  "status": "error",
  "code": "ERR_DUPLICATE_REFERENCE",
  "description": "An action with the supplied reference already exists."
}

{
  "status": "error",
  "code": "ERR_ACTION_NOT_FOUND",
  "description": "No action was found for the supplied reference."
}

Validation rules

Optional request reference values must be valid Base64String values under BRC-100.
Wallet-generated reference values must be valid Base64String values and must not collide with existing action references for the user.

Conclusion

By making action reference optionally caller-supplied, unique, present on action records, and fetchable via getAction, this specification closes the recovery gap for in-flight BRC-100 actions.

References

BRC-100 — Unified wallet-to-application interface
BRC-65 — Transaction labels and list actions
BRC-116 — Wallet permissions and counterparty trust

Was this helpful?