Balance Baskets: Backwards-Compatible Basket Balance Queries
An application that only wants to know how much is in a group has to fetch every item and add them up. This lets it ask for the total directly, using a form older wallets still handle correctly.
Summary
- Why
- Getting the total value of a basket normally requires fetching and summing every output in it, which is wasteful when only the total is needed.
- What
- BRC-112 is a backwards-compatible extension to BRC-100's listOutputs call that lets an app request a basket's total satoshi balance by prefixing the basket name with "balance ".
- How
- A developer calls listOutputs with a basket name like "balance savings" instead of "savings", and the wallet returns an empty outputs array while putting the summed satoshi total in totalOutputs.
What this lets you do
- Query a basket's total satoshi balance in one call
- Skip fetching and summing individual outputs
- Combine balance queries with existing tag filters
- Rely on normal basket permission checks still being enforced
- Detect module baskets that reject balance queries outright
Written by claude-sonnet-5 from the specification text. Where the two differ, the original is correct.
Reference for an AI
Everything an assistant needs to answer questions about BRC-112 accurately, including what it depends on.
The specification
Abstract
This specification defines a backwards-compatible extension to BRC-100 that allows applications to query a basket's balance using a balance prefix in listOutputs. The wallet returns no outputs and re-purposes totalOutputs to report the sum of satoshis contained in all outputs in the specified basket.
Motivation
Applications often need a quick way to retrieve the total value of a basket without enumerating all outputs. Extending listOutputs with a special basket prefix preserves API compatibility while enabling efficient balance queries.
Specification
Balance Basket Prefix
A balance query is requested by using a basket name that begins with balance (a lowercase "balance" followed by a space). The remainder of the basket string is treated as the target basket name.
Example:
listOutputs({ basket: "balance savings" })
Required Behavior
When listOutputs is called with a basket name beginning with balance :
- The wallet must return no outputs in the results array.
- The wallet must re-purpose
totalOutputsto contain the sum (in satoshis) of all outputs currently in the target basket that match any provided tag filters. - The wallet must still enforce all normal permission checks for access to the target basket.
- The wallet must apply any basket resolution, ownership, internalization, and tag-filtering rules as if the caller had requested outputs from the target basket directly.
- No regard is given to the
limitoroffsetparameters, since this is a sum of total value.
This behavior is backwards compatible because existing callers will ignore the empty outputs array and read totalOutputs as the count of outputs; with this extension, totalOutputs is intentionally redefined only when the balance prefix is used.
BRC-99 Module Baskets
For module-defined baskets in BRC-99:
balance p <module> <basket>is never allowed and must be rejected.p <module> balance <basket>may be implemented at the module's discretion.
If a module chooses to implement balance semantics, it may interpret balance <basket> according to its own rules, including permissioning and aggregation behavior. If a module does not implement this, the wallet must reject the request as unsupported.
Validation Rules
- The
balanceprefix must be lowercase and followed by a single space. - The target basket name that follows must conform to the basket naming rules in BRC-100 and BRC-99 where applicable.
- If the target basket does not exist or is not accessible, the wallet must return the appropriate error according to BRC-100.
Conclusion
By reserving a balance prefix within basket queries, this specification enables efficient balance retrieval while remaining compatible with existing listOutputs behavior and the broader wallet permission model.