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.

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.

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.