Balance Baskets: Backwards-Compatible Basket Balance Queries

Ty Everett ([e-mail])

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 use the separate exact representation below.

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.

Exact 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 an exact nonnegative aggregate in totalOutputs, represented as a string matching 0|[1-9][0-9]* at both the API and JSON boundaries, including zero and small balances. No sign, whitespace, leading zeroes, decimal point or exponent is allowed. There is no uint64 bound on the aggregate; limits on individual outputs remain the module's concern.

In the BRC-100 binary response, this field is a VarInt byte length followed by UTF-8 decimal text, using BRC-100's string encoding. It is not a numeric VarInt. The remaining response fields are unchanged. Codecs MUST select this format from the supported query contract, never by guessing from response bytes. 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 rounded, 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. Adoption requires compatible codecs and validators along the selected connection; this specification does not assert compatibility with earlier P-basket codecs or require an enumeration fallback.

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.