Balance Baskets: Backwards-Compatible Basket Balance Queries

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. P-basket module balances retain the numeric representation described below, with exact internal aggregation before conversion to a numeric summary.

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 totalOutputs to 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 limit or offset parameters, 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.

Module Balance Representation

Every supported p <module> balance <basket> query MUST use this profile. The module defines its units, eligible records, permissions and tag filters. The result has outputs: [], no BEEF, and the nonnegative aggregate in totalOutputs as a number at both the API and JSON boundaries. The number MUST be a finite nonnegative integer. On a JavaScript system it is exact through 2^53 and may be rounded above; enumerating the actual outputs is required for exact accounting or value movement. JSON summary values have no uint64 ceiling. Limits on individual outputs remain the module's concern.

In the BRC-100 binary response, this field is the numeric VarInt of any listOutputs result. A numeric value of 2^64 or more does not fit the VarInt and MUST be answered with an error, including a smaller exact aggregate that rounds to 2^64 before serialization. Canonical CompactSize decoding is required; a valid uint64 frame may round when converted to a JavaScript Number. The remaining response fields are unchanged. Ordinary output counts, including P-basket inventories, and all non-P basket responses retain their existing API types and wire formats.

Compute sums exactly. Unsupported module profiles, incapable adapters or exceeded implementation resource limits MUST produce explicit errors, never wrapped, saturated or partial balances. Receivers MUST reject noncanonical or wrong-type results and validate lengths before allocation. Implementations MUST document any resource limits; these do not make larger holdings invalid. Established numeric clients retain their existing representation. Older codecs may explicitly reject magnitudes beyond their implemented bounds; never truncate or claim compatibility outside tested bounds. Exact-balance extensions must be additive; a numeric result must not become a string or a number/string union.

Validation Rules

• The balance prefix 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.