Output Identity Tags for BRC-100 Wallets
Wallet apps often need to find one specific coin they are holding again later, for example after a restart, or to spend exactly that one and not another, but the usual way to look through a wallet's holdings means scanning everything and hoping the details still match. There was no agreed, simple way to give a single held item a durable nickname that a lookup could search for directly.
About Labels and actions, tagging transactions so an app can find them again.
Reference for an AI
Everything an assistant needs to answer questions about BRC-164 accurately, including what it depends on.
Summary
- Why
- Wallet apps need a stable, queryable handle for one specific held output so they can find or target it again without scanning every row.
- What
- BRC-164 defines an id:<key> tag convention that gives a BRC-100 wallet output a stable, queryable list key usable with ordinary listOutputs tag filters.
- How
- A wallet or tool stamps an id:<key> tag on an output when it takes custody of it, then later filters listOutputs by that exact tag (or resolves it inside a spend label as defined by other specs like BRC-165) to find or target that row without extra BRC-100 fields.
What this lets you do
- Stamp a stable id: tag on a wallet output when it is created
- Look up a specific output later with a plain listOutputs tag filter
- Target a spend against a known output without scanning every row
- Correlate UI state or app state to a specific held output
- Reuse the same key convention across tools that share a basket profile
Written by claude-sonnet-5 from the specification text. Where the two differ, the original is correct.
The specification
Abstract
This specification defines a tag convention for BRC-100: an output tag prefix id: that carries a stable list key for a held output. Callers use it with ordinary listOutputs tag filters. It does not change the BRC-100 request or response shape, and it does not require special wallet storage behavior beyond normal tags.
Motivation
Basket profiles and applications often need a stable handle for one wallet output — reload after restart, target a spend, correlate UI to storage — without scanning every row.
Stamping that handle as a normal, queryable tag under a short prefix makes listOutputs the lookup API, without new BRC-100 fields or pseudo-tag peel paths.
Specification
Tag form
This specification uses tags of the form:
id:<key>
- The prefix is exactly
id:(lowercase, ASCII). <key>is a non-empty string chosen by the writer that stamps the tag (wallet or tool).- Because reference BRC-100 clients commonly trim and lowercase tags before store and match, writers SHOULD use a case-insensitive alphabet for
<key>(e.g. lowercase hex or decimal digits), and readers MUST treat tag equality as case-insensitive.
Tags beginning with id: are used for this output list-key role.
Meaning
id:<key>identifies a held output row for list and spend targeting inside that wallet storage.- It is not a global asset id, token id, origin, outpoint, remittance field, or proof of ownership.
- Encoding of
<key>is defined by the writer (e.g. decimal storage primary key, UUID). Only that writer must round-trip it. - Uniqueness:
<key>SHOULD be unique among that wallet’s held outputs (or a documented narrower scope such as per basket). - Stability: for a given held row,
id:SHOULD remain stable for the life of that row (including unproven / unmined outputs if they are listable).
Behavior
id: is an ordinary BRC-100 output tag. No special listOutputs semantics, peel, inject, or foreign-tag overwrite is required of generic wallet storage.
Conforming tools and wallets that adopt this profile SHOULD:
- Stamp
id:<key>on the output when the row is created or first taken into custody (same path as any other tag). - Query with a full
id:<key>tag via ordinarytags/tagQueryMode. - Treat
id:as their own list key vocabulary — not as token id, origin, or on-chain identity. Basket profiles that need those notions use their own tags (e.g.bsv21:<tokenId>,origin:…).
Applications MAY read id:<key> from listOutputs (with includeTags) and reuse it in later filters or app state.
Related: spend labels (BRC-165)
BRC-165 (P1Sat collectables) uses the bare <key> — not the full id:<key> tag string — in createAction labels of the form p 1sat input id <key>. The holding wallet resolves that key by querying tag id:<key> under basket 1sat. Other asset schemes MAY use the same pattern under their own scheme ids. This BRC does not define those labels; it only supplies the list-key vocabulary they reference.
Out of scope
- Changing BRC-100 method schemas or WalletWire encodings
- Basket names, token economics, or provenance proofs
- Requiring a particular key generation algorithm (UUID, counter, storage PK encoding, …)
- Mandating peel/inject or other non-tag storage paths in reference wallets
Security considerations
- Not authentication — Knowing
id:<key>only helps address a row inside a wallet that already authorizedlistOutputs/ spend for that basket. - Authority — The tag is only as trustworthy as the storage that stamped it. Counterparty remittance is not a substitute for the holding wallet’s (or tool’s) own stamp.
- Case folding — Assume tags are lowercased in storage; do not put case-sensitive secrets in
<key>. - Ambiguity —
id:is short and may appear in other informal tag sets. Writers that need a stricter namespace MAY document a longer key form; this BRC does not reserve exclusivity of the two-letter prefix beyond the list-key meaning above for adopters.
References
- BRC-100 — Unified Open BSV Wallet-to-Application Interface
- BRC-37 — Basket and Custom Instructions Extension for Bitcoin Outpoints
- BRC-46 — Wallet Transaction Output Tracking (Output Baskets)
- BRC-153 — Action Reference Labels for BRC-100 Wallets
- BRC-147 — 1Sat Ordinals Basket Profile
- BRC-165 — P1Sat Permission Scheme (spend labels:
p 1sat input id <key>)