Basket Identifier Namespace Framework

Simon Bettison ([email protected])

Abstract

We define a hierarchical namespace framework for BRC-46 output basket identifiers. Existing standards reserve basket prefixes in an ad-hoc manner (BRC-44 reserves admin, BRC-99 reserves p , BRC-112 claims balance as a virtual prefix). This specification unifies these reservations under a single grammar, establishes a mechanism for claiming new namespaces, and provides conventions that prevent collisions between protocols, applications, and wallet-internal operations.

We propose a backwards-compatible extension to BRC-100's basket naming rules that introduces a structured zone alongside the existing flat zone, using the colon (:) character — which is not valid in any existing BRC-100 basket name — as the delimiter for hierarchical namespace prefixes. This creates an opportunity for wallets to validate structured names against registered prefixes, without affecting any existing basket name or wallet behaviour.

The design draws on the hierarchical decomposition principles of RFC 3986¹ (URI Generic Syntax), adapted for the simpler requirements of basket identification within the BRC-100 wallet interface. BRC-87² (Standardised Naming Conventions for Topic Managers and Lookup Services) provides prior art for naming conventions within the BSV ecosystem.

Motivation

As the BSV wallet ecosystem grows, basket names are being used for increasingly diverse purposes: token tracking, payment receipts, UTXO pool management, permission tokens, and module-defined digital asset schemes. Each new protocol that uses baskets must choose a naming convention, and without a framework, the risk of collision increases with every new standard.

The current state is fragmented:

Prefix/Pattern	Reserved by	Zone	Mechanism
admin	BRC-44	Flat	Wallet rejects at validation
p <module>	BRC-99	Flat	Wallet rejects unless module installed
default	BRC-100 (implicit)	Flat	Wallet uses internally for balance
balance <basket>	BRC-112	Flat	Virtual prefix, reinterprets listOutputs

Each BRC independently grabs a prefix with no coordination, no registry, and no grammar that composes them. There is no way to answer "is this prefix taken?" or "what prefixes exist?" without reading every wallet-related BRC.

Furthermore, all reservations operate within BRC-100's flat character set ([a-z0-9 ]), which provides no syntactic distinction between a reserved prefix and an ordinary name. The string admin tokens is rejected because the validator knows to check for admin — but there is no general mechanism for recognising that a name belongs to a managed namespace.

RFC 3986 demonstrates that a hierarchical namespace with a simple grammar (scheme, authority, path) can scale to billions of identifiers while remaining human-readable and machine-parseable. Basket identifiers need a similar — though much simpler — structure.

Specification

1. Two Zones: Flat and Structured

This specification introduces the concept of two complementary zones within the basket identifier space:

Flat zone — the existing BRC-100 character set ([a-z0-9 ]). All existing basket names, reservations, and validation rules operate here unchanged. Names in the flat zone are validated against the existing rules defined in BRC-100 Section "Rules for Basket Names"³.

Structured zone — identifiers containing a colon (:) character. Since BRC-100 restricts basket names to [a-z0-9 ], no valid BRC-100 basket name has ever contained a colon. The structured zone is therefore entirely new territory — its introduction cannot conflict with any existing basket, application, or wallet behaviour.

Wallets that do not implement this specification will reject structured-zone names at the BRC-100 validation step (the colon fails the character check). This is the correct and safe behaviour — it means structured names are only accepted by wallets that understand them.

2. Proposed Extension to BRC-100

We propose that BRC-100's "Rules for Basket Names" be extended as follows:

Basket names conforming to the existing character set ([a-z0-9 ]) continue to be validated under the existing rules (minimum 5 characters, maximum 400 characters, no consecutive spaces, reserved prefix exclusions).

Additionally, basket names containing a colon (:) character are valid if they conform to the structured namespace grammar defined in BRC-123. The colon acts as a namespace delimiter, separating a registered or application-scoped prefix from a basket-specific identifier. Structured names are validated against their namespace's rules rather than the flat-zone character restriction.

This extension is purely additive:

• No existing valid basket name is affected

• No existing validation rule is weakened

• The existing reserved prefixes (admin, p , default, balance ) remain in the flat zone and continue to function unchanged

• Wallets that do not implement this extension safely reject structured names

3. Basket Name Grammar

A basket identifier is a UTF-8 string that, after trimming and lowercasing, conforms to one of the following forms:

basket-name     = structured-name / flat-name

; --- Structured zone (new — contains ":") ---
structured-name = protocol-name / app-name
protocol-name   = registered-prefix ":" identifier
app-name        = domain-prefix ":" identifier

; --- Flat zone (existing BRC-100 — no ":") ---
flat-name       = system-name / module-name / simple-name
system-name     = "default" / "admin" flat-identifier
module-name     = "p" SP module-id SP flat-identifier
simple-name     = flat-identifier

; --- Components ---
registered-prefix = 1*ALPHA                          ; claimed via BRC registration
domain-prefix     = 1*(ALPHA / DIGIT / "." / "-")   ; FQDN or reverse-domain
module-id         = 1*(ALPHA / DIGIT / "-")          ; BRC-99 module identifier

identifier        = 1*(ALPHA / DIGIT / SP / "-" / "_" / ":" / ".")
                    ; no consecutive spaces, no leading/trailing spaces (trimmed)

flat-identifier   = 1*(ALPHA / DIGIT / SP)
                    ; BRC-100 compatible: lowercase letters, numbers, spaces only

SP                = %x20                              ; single space character

Components are listed in order of decreasing precedence, following the RFC 3986 principle that "the URI syntax is organised hierarchically, with components listed in order of decreasing significance from left to right"¹.

4. Namespace Tiers

4.1 System-Reserved (Tier 0) — Flat Zone

Names matching default or the admin prefix are reserved for wallet-internal use. These MUST NOT be used by applications or protocols. Wallets MUST reject operations on system-reserved baskets from non-admin originators.

Existing reservations (grandfathered):

• default — wallet balance basket (BRC-100)

• admin * — wallet administrative baskets (BRC-44, BRC-116)

• balance <basket> — virtual query prefix, not a real basket (BRC-112)

These reservations predate this specification and remain in the flat zone. No changes are required to their validation or behaviour.

4.2 Module-Reserved (Tier 1) — Flat Zone

Names matching p <module-id> are reserved for BRC-99 wallet modules. Access requires the corresponding module to be installed in the wallet. Modules define their own permission semantics for baskets in their namespace.

Existing reservations (grandfathered):

• All p prefixed names (BRC-99)

4.3 Protocol-Reserved (Tier 2) — Structured Zone

Names matching <registered-prefix>:<identifier> are reserved for protocols defined by BRC specifications. A protocol claims a prefix by declaring it in a "Basket Namespace" section of its BRC. The colon (:) delimiter is chosen because:

• It is not valid in any existing BRC-100 basket name, ensuring zero collision

• It is visually distinct from the space delimiter used by Tiers 0 and 1

• It mirrors the scheme: pattern from RFC 3986¹

• It follows the precedent set by BRC-87² for structured identifiers in the BSV ecosystem

Registration mechanism: A BRC specification MAY claim a protocol prefix by including a "Basket Namespace" section that declares the prefix and its intended use. The prefix MUST be a single lowercase alphabetic word (matching 1*ALPHA). Wallets SHOULD maintain an internal registry of known protocol prefixes and MAY reject unrecognised protocol prefixes, or MAY accept them permissively — the choice is an implementation decision that balances security against extensibility.

Claimed prefixes:

• pool: — UTXO Pool Management (future BRC)

Validation: When a wallet encounters a structured name with a recognised protocol prefix, it MAY apply protocol-specific validation rules (e.g. the UTXO Pool BRC may require pool: names to be at least 6 characters total). When the prefix is not recognised, the wallet MAY accept or reject at its discretion.

4.4 Application-Scoped (Tier 3) — Structured Zone

Names where the portion before the first colon contains a dot (.) are treated as application-scoped, using the originator's domain as a namespace:

example.com:my tokens
game.x420.io:session inventory

This convention follows the reverse-domain pattern common in Java packages and Android namespaces. Applications MAY use this pattern to prevent cross-application collisions without requiring a BRC registration. The dot distinguishes application prefixes from protocol prefixes (which are single alphabetic words without dots).

Wallets MAY enforce that application-scoped baskets are only accessible to the matching originator, connecting to BRC-116⁴ DBAP basket permissions. This enforcement is OPTIONAL — wallets that do not implement originator-scoping treat these as ordinary structured names.

4.5 Simple Names (Tier 4) — Flat Zone

Any name in the flat zone that does not match the patterns in Tiers 0-1 is a simple name in the unreserved space. These names are first-come-first-served and carry no implicit ownership or access control beyond standard BRC-116 basket permissions.

Simple names are validated against BRC-100's existing rules: minimum 5 characters, maximum 400 characters, lowercase letters/numbers/spaces only, no consecutive spaces, no reserved prefixes.

Examples: my tokens, game inventory, receipts

5. Validation Rules

Wallets implementing this specification MUST apply the following validation in order:

1. Reject if the value is not a string

2. Trim leading and trailing whitespace

3. Lowercase the entire string

4. Branch on zone:

   • If the normalised name contains : → structured zone (proceed to step 5)

   • Otherwise → flat zone (proceed to step 8)

5. Reject if byte length is less than 1 or greater than 300

6. If the prefix before the first : matches a known registered protocol prefix → apply protocol-specific validation (Tier 2)

7. If the prefix contains . → treat as application-scoped (Tier 3); otherwise treat as an unrecognised protocol prefix (wallet MAY accept or reject)

8. Apply existing BRC-100 flat-zone validation:

   • Reject if character length is less than 5 or greater than 400

   • Reject if characters outside [a-z0-9 ] are present

   • Reject if consecutive spaces are present

   • Reject if the name matches a system-reserved pattern (Tier 0)

   • If the name matches a module pattern (p <id> ...), defer to BRC-99 module resolution (Tier 1)

   • Otherwise, accept as a simple name (Tier 4)

6. Backwards Compatibility

This specification is designed for full backwards compatibility:

1. No existing basket name is affected. The structured zone uses : which is not valid under BRC-100's [a-z0-9 ] character set. No existing basket has ever contained a colon.

2. No existing validation rule is weakened. Flat-zone names continue to be validated under BRC-100's original rules with the original character set, minimum length, and reserved prefix checks.

3. Non-implementing wallets are safe. A wallet that does not implement this specification will reject any structured-zone name at BRC-100's character validation step. This is correct behaviour — the structured zone is opt-in.

4. Existing reservations are grandfathered. admin, p , default, and balance continue to operate in the flat zone under their original BRC specifications. This framework does not alter or supersede those reservations — it provides a unified model that encompasses them.

5. The extension is purely additive. The only change to BRC-100 is the acceptance of colon-containing names by wallets that implement this specification. No existing behaviour is modified.

7. Relationship to RFC 3986

The basket namespace grammar draws structural inspiration from RFC 3986 but is deliberately simpler:

RFC 3986 Concept	Basket Analogue	Notes
Scheme (http:)	Protocol prefix (pool:)	Single-word, no // authority separator
Authority (example.com)	Domain prefix (example.com:)	Application-scoped isolation
Path (/resource)	Identifier (doom)	The basket-specific name after the prefix
Registration (BCP 35)	BRC declaration	Federated, no central registry
Query / Fragment	Not applicable	Baskets are flat identifiers, not hierarchical resources

The key simplification: baskets do not need authority, path hierarchy, query parameters, or fragment references. A single level of namespacing (prefix + name) is sufficient for the foreseeable use cases.

Should the BSV ecosystem require interoperability with external systems (e.g. cross-chain wallet communication), a formal URI scheme (bsv-basket:pool:doom) could be proposed via RFC 3986's BCP 35 registration process. This specification does not preclude such a future extension.

8. Relationship to BRC-87

BRC-87² establishes standardised naming conventions for BRC-22 Topic Managers and BRC-24 Lookup Services within the overlay network. While the domain differs (overlay services vs wallet baskets), the underlying problem — preventing name collisions in a growing ecosystem — is identical. This specification follows BRC-87's precedent of proposing structured naming conventions via a BRC, and adopts a similar philosophy of human-readable identifiers with clear hierarchical separation.

Implementations

This specification is implemented in the bsv-wallet Ruby gem's Validators.validate_basket! method, which applies trim, lowercase, byte-length, zone detection (colon presence), and reserved-prefix validation aligned with this grammar.

References

• 1: RFC 3986: Uniform Resource Identifier (URI) Generic Syntax, Section 1.2.3

• 2: BRC-87: Standardised Naming Conventions for Topic Managers and Lookup Services

• 3: BRC-100: Wallet Interface — Rules for Basket Names

• 4: BRC-116: Wallet Permissions and Counterparty Trust

• 5: BRC-44: Admin-reserved and Prohibited Key Derivation Protocols

• 6: BRC-46: Wallet Transaction Output Tracking (Output Baskets)

• 7: BRC-99: P Baskets

• 8: BRC-112: Balance Baskets