Skip to main content
Status: Draft Type: Standards Track Category: Core Created: 2026-07-27 Revised: 2026-08-24 — document version 2. Version 1 is superseded in full; §18 states how a deployment activates, and how genesis rejects version-1 governance keys without enumerating them. 2026-10-22: Release (method tag 22, §9.2) returns a lease without spending its attempt, deliverable again after its delay_ms. Requires: CIP-3 (fee handling), CIP-12 (governance), CIP-31 (§4, the Platform Fee Account rule §6 cites) Related: CIP-2 and CIP-10 (the runner workloads that are CBQS clients), CIP-7 (Watchtower, the actor-native stream protocol), CIP-42 (/statusz)
Cowboy Cloud and Cowboy Chain. This CIP specifies the Cowboy protocol. Cowboy Cloud runs on this protocol today. Cowboy Chain, a public network on the same protocol, is under consideration for a future release. Where the two differ, this CIP says so.

Abstract

This proposal introduces the Cowboy Queue System (CBQS), a durable off-chain messaging service for workloads running on different Cowboy Runners. CBQS provides one ordered stream from which applications construct work queues, publish/subscribe, request/reply, and replayable event logs. Broker-side lanes let many related rooms or documents share one chain-created stream. The Cowboy chain is a governance and registry plane. It records who owns a stream, which provider serves it, which key may authorize access to it, and whether its owner has paid. A new off-chain service, cbqsd, is the data plane: it stores records, manages consumer groups and delivery leases, pushes records to connected clients, and commits batches durably. The two planes operate independently. No chain transaction is required to append, deliver, acknowledge, or replay a message, and no chain round trip occurs on any message path. A broker serves from a periodically refreshed registry snapshot and keeps serving while the chain is unreachable; chain authority is applied within a bounded, stated lag rather than per request. Message payloads are opaque to the broker. CBQS does not define a key distribution mechanism; applications that need confidentiality encrypt payloads before appending them.

Background

Cowboy actors and actor-to-actor messages execute through consensus to update finality-bearing application state. High-frequency coordination between off-chain workloads needs a separate message service. Cowboy Runners execute jobs and persistent workloads away from consensus, but there is no shared messaging backplane between them. A coordinator that talks to several specialist agents must otherwise implement persistence, retry, fan-out, cursors, leases, reconnection, authorization, and crash recovery as application infrastructure. CBQS provides that service. It records tenancy, authorization, and billing on the chain and handles messages at the broker.

Goal

CBQS MUST provide:
  1. cross-runner message exchange with no consensus write and no chain read on the data path;
  2. ordered replay, and at-least-once work delivery in which consumers compete for records rather than receive them in order;
  3. push delivery with bounded, explicit backpressure;
  4. owner-controlled authorization and revocation through chain authority, applied within a bounded lag;
  5. durable commit before acknowledgement, with a signed provider commitment over each committed batch that a party holding that batch can verify;
  6. cheap logical room or document creation inside one stream;
  7. continued data-plane service for established sessions while the chain is unavailable, bounded by cbqs.max_snapshot_age_blocks for opening new sessions and by grant expiry for holding open ones (§3).
Payload confidentiality as a platform service, key distribution and rotation, exactly-once application effects, communication-graph secrecy, consensus publication, semantic routing, distributed transactions, and generic Redis-style key/value or lock operations are not goals. The following are outside this document and require follow-up CIPs: an async-durable delivery class for repairable logs, per-lane cryptographic verification, provider reassignment, provider staking or slashing, shared durable cursors, scheduled delivery, capacity-priced or tiered billing, platform-managed encryption, CBFS archival integration, and transport bindings other than the one in §11.

Specification

The key words MUST, MUST NOT, REQUIRED, SHALL, SHOULD, SHOULD NOT, and MAY in this document are to be interpreted as described in RFC 2119. Every normative requirement in this document is stated so that it can be observed from outside the implementation it constrains: from chain state, from canonical bytes on the wire, or from a broker response. §19 states the conformance tests, and enumerates the requirements that are not externally observable, which are stated as operator obligations rather than as protocol guarantees.

1. Terms

2. Trust model

The chain is authoritative for stream existence, ownership, provider assignment, admin key, authorization generation, and the owner’s prepaid balance and solvency. cbqsd is authoritative for the records, lanes, groups, and delivery state it has accepted. Payloads are opaque bytes to the broker. The broker sees, and this document does not hide: which workloads connect, stream and lane and group identifiers, message sizes, timing, traffic volume, and delivery state. The chain additionally exposes stream existence, owner, provider, billing activity, and authorization-generation changes. A provider can censor, delay, or destroy data. Checkpoints make some misbehaviour detectable after the fact; they do not provide availability, and v2 has no on-chain dispute, staking, or slashing path. An application whose data must survive its provider MUST maintain its own durable copy. §19 item J lists this application obligation among the requirements that conformance tests cannot observe. Applications that require payload confidentiality encrypt before appending. The broker never receives a key and never inspects a payload, so confidentiality is exactly as strong as the application’s own key management.

3. Architecture

The chain MUST NOT receive message payloads, lane operations, group operations, delivery leases, acknowledgements, or cursor advances. The Stream Registry system actor is allocated at 0x17. CBQS uses one top-level system-instruction opcode:
The payload is a bounded, versioned CbqsInstructionV2 (§5). A broker MUST serve appends, deliveries, acknowledgements, and replays from its registry snapshot without contacting the chain. It MUST attempt a refresh at least every cbqs.snapshot_refresh_ms, and when a refresh fails it MUST continue serving from the snapshot it has. A new session requires a snapshot no older than cbqs.max_snapshot_age_blocks. Past that age the broker MUST refuse OpenSession with ChainStateStale. The stream admin chooses grant expiry. There is no protocol cap on grant lifetime. Every grant carries expires_at_ms, and §7 requires a broker to terminate its session when that expiry passes. An authorization_generation bump revokes existing grants when the broker observes the finalized update. During a chain refresh outage, an established session can remain usable until its admin-chosen expiry; the snapshot-age limit applies to new sessions. The broker enforces its own snapshot-age bound. A client cannot observe this bound from protocol messages. Protocol messages do not let a client verify the reported snapshot_height, as §19 item B explains. §19 item 4 makes the refusal itself a conformance test. Grant expiry needs no refresh; a client can test enforcement by continuing to send past expires_at_ms. A broker obtains the snapshot by reading finalized Stream Registry state from a Cowboy node, and MUST evaluate every decision for one request from one snapshot rather than combining values read at different heights. A snapshot MUST carry, for each stream it covers: the StreamRecordV2, the CbqsAccountV2 for (stream.owner, stream.provider) when one exists, the assigned ProviderRecordV2, the §15 parameter values, and the finalized height it was taken at, which this document calls H_snapshot. A Closed stream may have no account record because §4.3 deletes an empty one. It needs none because §7 refuses a session for it on status alone. Implementations may choose the node RPC that serves the snapshot; its content and atomicity are normative. Clients connect directly to a provider endpoint. The Cowboy Gateway is not on the message data path.

4. Chain objects

Every canonical CBQS object defined with a version field carries version: u8 = 2 as its first field, and a decoder MUST reject any other value, including the version-1 bytes of the superseded document. The objects that carry it are every chain record (§4.1–§4.3), every broker record that outlives a connection (§8, §9.2, §13), the record header inside a signed digest (§9), and every signed object (§7, §10). Instruction payloads (§5) and transport frames (§11.1) are versioned by their envelope, the CbqsInstructionV2 version byte and the frame’s version: u8 = 2, and the structs carried inside them keep whatever version byte their own definition gives them. Public keys use CIP-40 §7.7’s shared registry: secp256k1 = 1, Ed25519 = 2, P-256 = 3, P-384 = 4. Inside CBQS records and preimages, SigningPublicKeyBytes has the self-delimiting form:
The length is determined by the algorithm tag: 33, 32, 33 and 49 key bytes for registry IDs 1, 2, 3 and 4 respectively. CBQS accepts only ID 2, rejecting all other IDs at decode, including assigned ones. Its Ed25519 representation therefore remains 33 bytes, with no length prefix. Its JSON is 0x followed by 66 lowercase hex digits of this CBQS form, distinct from the commonware-wire SigningPublicKey JSON in CIP-40. Decode checks algorithm and exact length structurally, with no curve arithmetic. Admission charges CBQS_KEY_VALIDATION_CYCLES per carried key, using the shared KEY_VALIDATION_CYCLES[Ed25519] calibration, before calling the shared key validator and before storing or trusting the key. Invalid/small-order keys are refused after the charge. The signature verifier still checks the point strictly as defense in depth. A byte-decode charge cannot pay for unmetered cryptography. Every Ed25519 verification defined by this document, StreamGrantV2 (§7), SessionProofV2 (§7), CheckpointReceiptV2 (§10), uses pure Ed25519 (RFC 8032) with a 32-byte public key and a 64-byte signature, verified with strict semantics: canonical point and scalar encodings, and rejection of weak or small-order public keys and R values. A verifier MUST verify each signature individually and MUST NOT accept a batch-verification result. No v2 chain instruction carries a signature. These verification rules apply to the broker and off-chain verifiers, not consensus. All CBQS canonical bytes follow these rules. Integers are unsigned big-endian of their declared width. Fixed byte strings and addresses are their raw fixed-width bytes. A variable byte string is u32 length || bytes. A bool is one byte, 0 for false and 1 for true; any other value is invalid. An option is 0 for absent or 1 || value for present; any other value is invalid. A vector is u32 count || elements. These are CBQS-specific fixed-width framing rules; they do not describe commonware Vec<T> storage framing, whose count is an unsigned varint (see CIP-4 §4.3). An enum tag is one byte, the numeric tag listed at that definition, followed by the variant’s fields; unknown tags are invalid. SigningPublicKey has algorithm-determined length in the CBQS form above; Signature remains a fixed 64-byte string. Neither is length-prefixed. Every CBQS record and preimage carrying a key, including StreamGrantV2.holder_signing_key, room-session delegation, policy fence/ack, policy boot info and holder-key ID, uses alg_tag_u8 ‖ key_bytes. Every accepted Ed25519 record retains its size; only the registry tag changes to 2. Struct fields appear in the order listed here. Field names and map keys never enter canonical bytes. A decoder MUST consume each self-delimiting input, each §11.1 frame, and each stored record exactly: a well-formed body followed by any unconsumed byte violates this encoding. A struct decoded inline from a larger reader is bounded by its own fields, not by the end of the input. Every option is encoded with its explicit presence tag. An implementation MUST NOT encode an absent option as a fixed-width sentinel: two distinct values MUST NOT share canonical bytes. Several rules below reject an instruction whose owner, provider, payer, or account is a reserved system address. For this document that means the zero address 0x00…00 and every address in 0x00…01 through 0x00…FF, the low range from which Cowboy allocates system actors, and which contains the two this document names (0x17, 0x18) and the zero address that §4.1 and §6.3 both burn to. The set is enumerated rather than cited so that a validator can be built from this document alone, and the zero address is inside it because two handlers read and write it separately from a caller’s own native account: CreateStream from the owner’s and RegisterProvider from the caller’s (§15.1). A caller at 0x00…00 would alias the two slots and net a burn against its own credit, so nothing would be burned. Several handlers move value between accounts named separately in §15.1. Those accounts MUST be distinct addresses, and three rejections enforce it: CreateStream when provider == owner or when owner is a reserved system address; TopUpAccount when the payer is the account’s provider, or when the payer or owner is a reserved system address; and RegisterProvider when the caller is a reserved system address (§4.1), which is what keeps its own two native-account slots distinct. The rejection names the payer and the owner but not the provider, because a reserved provider is already unreachable: §4.3 rejects a TopUpAccount naming a provider with no record, and §4.1 forbids registering at a reserved address, so no fixture can isolate a reserved-provider rejection. The reserved-address half is not redundant with §4.1’s rule that a provider cannot register at one. An owner or payer of 0x17 would alias the custody account, so the creation charge would be debited from pooled custody or a credit would net to zero against it, breaking the invariant that custody equals the sum of balances; 0x18 aliases the Platform Fee Account the same way. Both require a reserved address to originate an instruction, which this document does not otherwise exclude, so the enumeration covers it rather than resting on who can sign. The rejection makes aliased writes unreachable, so this document does not define them. A definition would need a write ordering §15.1 does not define, under which the later write clobbers the earlier and either mints or destroys the creation charge. An operator that wants to serve its own streams uses a second address to own them, which costs one address and removes a consensus divergence. For every signed object the named codec function returns domain_separator || canonical(all fields except signature), and the signer signs the Keccak-256 digest of those bytes. This table is the complete v2 registry; an implementation MUST NOT reconstruct a preimage from JSON, from transport framing, or from locally repeated field concatenation. The three domains are distinct and none is a prefix of another, so a signature valid over one object type is invalid over every other.

4.1 ProviderRecordV2

A provider record has no status field. accepts_new = false refuses new streams without disturbing existing ones, which is the whole of what a Draining state expressed. A Deregistered state would add one thing an implementation could get wrong and nothing it could act on: gating it on assigned_streams == 0 would let any single owner hold it open indefinitely by keeping one stream funded, so deregistration would never be a right a provider actually held. A provider leaves by clearing accepts_new and letting its streams close. A provider cannot terminate service to an owner who keeps paying. assigned_streams stays above zero for as long as one funded stream names the provider, so max_streams cannot be lowered past it and the record is permanent in practice. A provider that must stop serving a specific paying owner has one protocol move: stop accepting new streams, and negotiate the rest off chain. RegisterProvider MUST be rejected when a record already exists for the caller. Re-registration would otherwise reset assigned_streams to zero while live streams still name the provider, and reset signing_key_since, voiding every checkpoint the provider had signed. Everything mutable is changed through UpdateProvider. An endpoint is a URI. The v2 protocol defines one transport, so a transport tag would have one legal value. Consensus admission validates each endpoint as follows, rejecting the instruction on the first failure:
  1. the endpoint list is nonempty and at most cbqs.max_provider_endpoints long;
  2. each URI is at most cbqs.max_provider_endpoint_uri_bytes bytes and begins with the byte string wss://, compared byte-exactly; and
  3. every byte is in the closed range 0x21–0x7E inclusive, printable ASCII, excluding space and every control byte.
Rule 2’s length bound repeats the decode bound. cbqs.max_provider_endpoint_uri_bytes has Default equal to Maximum and §15 caps the same length at decode at that value, so no URI that survives decode can fail it. The handler still reads the parameter within its reservation (§15.1). No fixture can isolate this rejection, as with §5’s two unreachable rejections.
The vectors above are normative in full: a conforming implementation MUST admit every ACCEPT and reject every REJECT. HT denotes a single 0x09 byte and SP a single 0x20 byte, written as names because the byte itself is invisible in this document’s rendering; a conformance harness MUST substitute the byte rather than the four literal characters, which rule 3 would otherwise admit. The two non-ASCII vectors are homoglyphs, and are named by codepoint because a renderer may normalise them away: the first substitutes U+3002 IDEOGRAPHIC FULL STOP for each ., the second U+FF0F FULLWIDTH SOLIDUS for the / that would end the authority. Rule 3 rejects both on their bytes without having to know what they resemble, which is why it is a byte-range rule rather than a list of confusables. Consensus does not parse the host. A fourth rule could impose a grammar for the authority: canonical dotted-quad, RFC 5952 lowercase IPv6 inside brackets, DNS labels whose last label begins with a letter, and a port with no leading zero and not 443. Its purpose would be to stop one registered byte string from meaning two things to two readers, one parsing the URI and one scanning its bytes. This document defines no such rule, for two reasons. It would buy nothing. Consensus stores this field and never interprets it: no rule compares two endpoints, and no handler resolves one. The only reader that acts on it is a client deciding where to dial, and §11.4 governs that decision at the destination it dials, whether that came from a resolution or straight out of the URI. Walk the vectors such a grammar targets and both readings land in the same place. The URI wss://0251.0376.0251.0376/ws is 169.254.169.254 to a parser and an ordinary name to a scanner, and §11.4 rejects the first outright and rejects whatever the second resolves to; wss://good.example@169.254.169.254/ws sends a parser to a link-local address §11.4 refuses and a scanner to good.example, which is safe. Two clients can disagree about which host a provider meant, and neither can be walked into a private network. It would also cost something real. “The canonical lowercase form of RFC 5952” is not a single form: RFC 5952 §5 leaves the mixed hex/dot-decimal notation for IPv4-mapped addresses a recommendation, so the two mainstream standard-library canonicalisers disagree. Rust renders ::ffff:c000:201 as ::ffff:192.0.2.1 and Python renders ::ffff:192.0.2.1 as ::ffff:c000:201. Either validator can follow that sentence yet admit an instruction the other rejects. That is an admission fork on RegisterProvider and UpdateProvider, reachable by anyone who can pay the registration charge, and no vector in the block above would catch it. A hand-written IPv6 grammar would close that instance while leaving every validator obliged to implement one; omitting the rule closes the class. Consensus does not guarantee that a registered endpoint is syntactically dialable. A provider that registers an unusable URI pays the registration charge and remains unreachable. A URI admitted here is not a statement that the endpoint is safe to dial. A client MUST apply the dialing policy in §11.4 to every destination it connects to, whether it resolved a name or read a literal out of the URI; §19 item 7 makes that testable. The registry maintains assigned_streams: it increments on each CreateStream that names the provider and decrements on that stream’s transition to Closed, the only terminal status v2 defines. RegisterProvider MUST set it to zero, and no instruction may set it directly. A CreateStream MUST be rejected when accepts_new is false or when assigned_streams already equals max_streams. An UpdateProvider MUST NOT lower max_streams below the current assigned_streams; §5’s provider-side CloseStream is what lets a provider reduce that floor without the cooperation of an owner who has stopped paying. A provider MUST NOT be registered at a reserved system address, and RegisterProvider MUST be rejected when the caller is one: §6 moves value between the custody account, the provider account, and the Platform Fee Account in one transition, and an alias between any two would make one credit overwrite another. Changing a provider signing key is prospective, and the registry keeps one previous key. UpdateProvider that carries a signing_key MUST move the current key into previous_signing_key, move signing_key_since into previous_signing_key_since, and set signing_key_since to the height at which it commits. An UpdateProvider carrying a signing_key MUST be rejected when signing_key_since already equals the height at which it would commit. Two rotations at one height would leave previous_signing_key_since == signing_key_since, an empty interval that §10’s second row can never select. The stored previous key would resolve for nothing and the provider’s whole history would go unverifiable in one block. The previous key exists to prevent this self-repudiation. RegisterProvider MUST set signing_key_since to the height at which it commits, previous_signing_key to absent, and previous_signing_key_since to zero. Stating all three matters: they are consensus-visible record bytes that no instruction body carries, so two implementations seeding them differently produce different state roots while metering identically, and seeding previous_signing_key to the current key rather than to absent would change which row of §10’s resolution table a never-rotated provider reaches. One key of history is what makes rotation survivable in both directions. With none, a provider could not sign between rotation and its next finalized read. §10 closes a batch every cbqs.commit_batch_max_ms, and §3 forbids stopping service through a chain outage. Every receipt it had signed would also become uncheckable at rotation, which is self-repudiation for the price of one instruction. With unbounded history the registry grows without bound. One key covers the rotation window and the preceding epoch, provided rotations are at least one height apart, which the rule above enforces; §10 states what a verifier does beyond that. Provider registration is permissionless and creates no slashable stake, but it is not free. RegisterProvider MUST debit CBQS_PROVIDER_REGISTRATION_CHARGE from the caller’s native account and credit it to the zero address, in the same transition that writes the record, failing without registering when the debit cannot be completed.
A provider record is permanent because v2 has no deregistration. It is the largest record this document defines: at the §15 defaults a maximum-size one encodes to 8,364 bytes, or 8,397 once it carries a previous signing key, roughly fifty times a stream record, which pays the same charge. §6.3 states the rule that permanent registry state costs unrecoverable capital no governance write can zero, and an unpriced, unremovable, permissionless record was the one case that rule did not cover. The record carries no registered_block and the stream record carries no created_at_block, because no rule reads either. A consumer reads either height from the cbqs.provider.registered or cbqs.stream.created event (§16).

4.2 StreamRecordV2

The owner’s account (§4.3) stores the rate, balance, settlement height, and suspension state. Retention, message size, and the two rate ceilings are broker-side settings (§13) bounded by governance parameters (§15). The stream record stores only ownership, provider assignment, and access authority. It holds no economic state and no configuration. The stream id is:
chain_instance_id is the genesis-configuration fingerprint. Genesis MUST seed it into a Stream Registry singleton before any CBQS instruction can execute. Handlers MUST read that singleton rather than node-local configuration and MUST reject an absent or malformed singleton. The domain separator is "cbqs/stream-id/v2", and version 1’s was "cbqs/stream-id/v1", so no version-1 id can collide with a version-2 id and every version-1 id is unreachable. Any out-of-tree re-derivation, a test harness that reconstructs ids from an owner and a nonce, must use the version-2 separator, or it will address the wrong stream silently rather than fail. The preimage carries no separate chain id. chain_id_u64_be would have no stated source or reserved read, leaving two readings: the chain’s configured identifier or the transaction’s chain_id. The second would put a caller-supplied value inside a consensus-derived id. chain_instance_id already distinguishes genesis configurations, so a separate chain id would add one source of admission forks without distinguishing more chains. CreateStream MUST set authorization_generation to zero and status to Active. Neither is carried in the instruction body, so both are stated here for the reason §4.1 and §4.3 state their own seeds: they are consensus-visible record bytes no payload supplies, and two implementations seeding them differently produce different state roots while metering identically. The generation also determines which grants are live: §7 check 2 tests a grant’s generation for equality against it. UpdateStream is the only instruction that raises the generation, and CloseStream the only one that changes the status. The Stream Registry MUST reject a CreateStream whose (owner, owner_nonce) has already been used, including after that stream closes. An owner nonce is never reusable, and a Closed record is retained to enforce that: a resurrected id would let a grant issued against the old stream authorize the new one. owner, owner_nonce, and provider are immutable for the stream’s lifetime. Moving an application to another provider is described in §4.4, which states its ordering obligation.

4.3 CbqsAccountV2

The account keyed by (owner, provider) holds the entire economic relationship between those two parties. An owner with streams at three providers funds three accounts, to pay those three vendors. Everything follows from that key:
  • the rent clock, the balance, and the solvency flag are shared by exactly the streams one provider serves for one owner, so two of them can never disagree about any of it;
  • settle has exactly one provider to pay, so the rent split is a single credit rather than a distribution over an unbounded set, and every instruction’s state-I/O is a fixed pair (§15.1); and
  • a provider’s collectible is isolated from the same owner’s streams at other providers. A sibling elsewhere cannot drain the pool this provider is owed from, so the exposure §6.3 discloses is bounded by this provider’s own settlement cadence.
The broker is the same party as provider, so it evaluates §6.2 against the one account it is actually owed by, from fields its snapshot already carries. active_streams counts that account’s streams in Active status. CreateStream increments it and CloseStream decrements it, and every instruction that touches an account settles it first (§6.1), so active_streams is constant across any settled interval. CreateStream MUST be rejected when it would exceed cbqs.max_streams_per_account. Exactly one instruction creates an account: a TopUpAccount whose caller is the owner and whose amount is at least
Two rules, one purpose. Only the owner may create, so a third party can fund an existing account but cannot mint permanent registry state at an address it does not control. A creating top-up has a floor, so the record costs its creator something: without it an owner could pre-mint an account against every registered provider for one nano-CBY each, which is unbounded permanent state. The floor is a refundable deposit, not a burn. A handler deletes the record at balance == 0 && active_streams == 0. The deposit prices entry: one CBY must be locked to bring a pair’s record into existence. It does not price standing balance, and §5 says why it cannot: settle may leave any residue, so a record can legitimately persist holding less than the floor. The only route to one is to spend CBQS_STREAM_CREATION_CHARGE and let rent draw the balance down, which costs five times the floor. §5’s resulting-balance rule is what stops an owner shortcutting that by withdrawing to a dust balance instead. The floor does not stop an owner locking today’s rate for business it has not yet done, because a created account seeds rate_per_block = 0 and only CreateStream writes the parameter in. CreateStream does not create the account. Funding precedes owning: an owner tops up, then creates streams. A CreateStream that created the record would face a solvency test the fresh record could never pass, a dead path that two implementers could resolve differently, which is an admission divergence on a consensus instruction. A created record is exactly:
rate_per_block is seeded to zero rather than to the parameter. Four of its five readers, settle’s due, finalize’s revival test, §6.2’s serviceability, and §5.1’s provider-close predicate, multiply by active_streams, so a zero rate cannot affect them while the account has no streams. The fifth reader does not vanish, and it is why §5 fixes an order rather than leaving one to be inferred: CreateStream’s admission guard multiplies by active_streams + 1, which is 1 at the transition. CreateStream MUST write the rate before evaluating that guard, on the transition that writes it at all. An implementation that wrote it afterwards, alongside the active_streams increment, would still satisfy every other reader and would still meter identically, and would test a stale rate against a fresh balance, which is an admission fork on a consensus instruction whenever an idle account carries a rent residue and governance has since moved the parameter. Reading the parameter at account creation would charge every top-up for a value that CreateStream overwrites before any reader can use it. Every field is stated because leaving last_settled_block unstated is a consensus divergence a gas vector cannot catch: an implementation seeding 0 would charge H × rate at the first settlement that finds a stream. It would charge tens of CBY against an account that owes nothing and meter identically to one that seeds the height correctly. The balance is held in custody by the Stream Registry system actor at 0x17. TopUpAccount transfers native CBY from the payer into 0x17 and credits balance by the same amount in the same transition; every debit of balance moves the same amount out of 0x17 in the same transition. No handler in §15.1 may change the quantity native(0x17) − Σ balance, and §18 rule 1 makes it zero at genesis. Two reasons require preserving this quantity per transition rather than asserting a global equality. A handler MUST NOT read or test the quantity: §15.1 reserves no read that could sum the accounts, there is no account index or running total, and §16’s events carry no amounts, so not even an indexer can reconstruct the sum. Asserting an equality the handler cannot evaluate would halt consensus rather than enforce a safety property. And the equality is falsifiable from outside this document. A native transfer into 0x17 is not a CBQS instruction, so §4’s reserved-address rejections do not reach it. Those constrain the owner, payer, provider and caller of a CBQS instruction. Such a credit raises the quantity and can never leave, because every custody debit is bounded by some account’s balance. This document does not attempt to prevent it: TopUpAccount is itself a transfer into 0x17, so a carve-out would cost more than the disclosure. A debit from outside would lower it, and every custody debit would then fail closed; nothing here recovers from that either. An account whose balance has no custody behind it can never be withdrawn from and can never be deleted, because deletion requires balance == 0. A handler MUST fail closed rather than credit a share it cannot debit from custody, and a credit or debit that does not fit the native account’s width MUST fail closed rather than truncate. The account record is not permanent. A handler that leaves balance == 0 and active_streams == 0 MUST delete it. suspended is not part of that condition, because §6.1 clears it whenever active_streams reaches zero. An account with no streams owes nothing and cannot be insolvent. Requiring suspended == false as a separate conjunct would have made the rule unreachable on the path it exists for: the abandoned account whose last stream a provider closes under §5.1. Deleting state incurs a state-write charge (§15.1). TopUpAccount MUST be rejected when no provider record exists for provider, and under the reserved-address and payer rules of §4. Every check is inside the reservation §15.1 gives it.

4.4 Moving an application

Provider assignment is immutable, so moving an application to another provider, and the only remedy v2 offers when a provider stops serving, is a move the application performs:
  1. create a new stream naming the new provider;
  2. copy or replay the data from a durable source the application controls;
  3. issue new grants and redirect clients; and
  4. close the old stream only after verifying that the target’s latest checkpoint covers everything the source held.
Step 4 requires this ordering: closing first turns a move into data loss, and v2 has no dispute path that could recover it.

5. Chain instructions

CbqsInstructionV2 is version: u8 = 2 || tag: u8 || body:
An UpdateStream that carries admin_key MUST increment authorization_generation by exactly one, whatever bump_authorization_generation says. The step is stated because the field is consensus-visible record state that §7 check 2 tests for equality, and a reading under which the key change and the flag each contribute one puts two validators on different state roots for the same permissionless instruction; one that carries neither a new admin key nor bump_authorization_generation = true MUST be rejected as a no-op. A key rotation that did not invalidate outstanding grants would leave the old key’s grants live, which is the opposite of what a rotation is for. UpdateStream and CloseStream MUST be rejected when the stream is Closed. TopUpAccount names the account it credits, so a third party MAY fund an owner, but only the owner may bring a record into existence (§4.3). It MUST be rejected when amount is zero. WithdrawAccount acts on the caller’s (caller, provider) account: it MUST debit amount from balance and the same amount from custody at 0x17, and credit it to the owner’s native account, in the same transition. An absent amount withdraws the whole balance; a present one MUST be nonzero and at most balance. It MUST be rejected unless active_streams == 0 and the resulting balance is either zero or at least CBQS_MIN_ACCOUNT_TOPUP. suspended is not tested, because §6.1 clears it whenever active_streams reaches zero. amount is an option so that “withdraw everything” does not have to name a number. TopUpAccount against an existing account is permissionless, so if the only way to empty an account were to name amount == balance exactly, any third party could add one nano-CBY ordered ahead of the withdrawal and reject it, indefinitely, for a nano a block. The exit has to be expressible without naming the balance. The resulting-balance rule enforces §4.3’s creation floor. Without it an owner pays the floor, withdraws all but one nano-CBY in the next block, and keeps a permanent record for a nano. It bounds withdrawals. Rent follows a separate rule: settle can leave any residue below the floor, so a record may legitimately persist under it. The floor limits what an owner may withdraw. The balance can fall below it. CreateStream MUST be rejected when no account record exists for (owner, provider), whose creation belongs to TopUpAccount alone (§4.3), and, after settling and, when this CreateStream takes active_streams from 0 to 1, writing cbqs.stream_rate_per_block into account.rate_per_block (§6.1), unless balance >= rate_per_block * (active_streams + 1). The + 1 is the whole guard: it tests whether the account can fund the new stream as well as its existing streams. Testing the suspended flag instead admitted the first stream of every account, because finalize clears the flag at zero streams and the increment has not happened yet, so a zero-balance owner could mint Active chain state the broker refuses every session for, earn the provider nothing, burn the creation charge for nothing, and pin a provider slot until the provider spent a §5.1 close on it, up to cbqs.max_streams_per_account times. CreateStream MUST also be rejected when provider == owner, and when owner is a reserved system address (§4). Neither rejection is reachable as the sole cause of a rejection: CreateStream already requires an existing (owner, provider) account, and §4’s TopUpAccount rejections mean no account with a reserved owner or with owner == provider can exist. These redundant checks protect the instruction that creates permanent registry state. A conformance test cannot isolate them. SettleAccount and WithdrawAccount MUST be rejected when no record exists for the named pair. Neither creates one: §4.3 gives creation to TopUpAccount alone, and letting a permissionless SettleAccount create records would reopen the third-party minting §4.3 closes.

5.1 The provider’s close

The assigned provider may close a stream under this ordering:
CloseStream submitted by the assigned provider MUST first settle the account (§6.1) and is authorized only if, after that settlement, balance < rate_per_block * active_streams. The account cannot fund even one more block of the streams it has. Otherwise it MUST be rejected without effect.
Settling first accounts for all elapsed rent before authorizing the close. The projected inequality is preferred over the stored suspended flag because the flag is a materialized record of a past default, and nobody is obliged to submit the settlement that materializes it, whereas this rule has to authorize on whether the account can fund the next block, the same quantity §6.2 refuses service on. Using the flag would let the provider’s close and the broker’s refusal fire on two conditions that disagree while no one settles. Settling first means the provider’s own instruction gives the owner credit for every block the owner paid for, and the close proceeds only if the owner still cannot pay. The predicate is written out rather than deferred to §6.2 because §6.2 is defined over H_snapshot, a broker-side quantity a consensus handler does not have. Substituting the handler’s own height would make the elapsed factor zero and the test degenerate to suspended == false. Leaving the substitution unstated would let two implementations differ on whether a provider’s close is admitted. The inequality above is the negation of §6.2 evaluated one block on, the first block the account would have to pay for, stated directly so there is nothing to substitute. The provider’s close releases capacity that assigned_streams would otherwise reserve indefinitely for an owner who has stopped paying and participating. It moves only the balance the owner already owed. What it does not do is protect the owner’s data, which §12 leaves to the provider in any case, and it is not a grace mechanism: an owner who wants a stream kept keeps the account funded, and §6’s suspension is reversible for as long as the stream exists.

6. Billing

CBQS charges a flat per-stream rate for the existence of a stream, drawn from the owner’s account balance. It does not meter messages, bytes, or capacity: the provider’s exposure is bounded instead by the per-stream ceilings of §15, which the broker enforces, and by its own max_streams. A stream’s durable footprint has three parts, and only the first is measured in bytes:
  • retained_bytes_limit measures the records and their checkpoint receipts (§12), each receipt discarded once the floor passes the last record it attests.
  • A separate product bounds delivery cycles. One cycle exists per (retained record, applicable group), and §9.2 reclaims each with the record it names, so the floor bounds them, but their bytes are not inside retained_bytes_limit. The bound is retained records × cbqs.max_groups_per_stream, and it is stated rather than folded into the byte limit because folding it in would make creating a group evict data: a group starting at At(first_retained_sequence) mints a cycle for every retained record at once, and a byte limit that saw them would advance the floor in response.
  • Everything else is bounded by count: lanes by cbqs.max_lanes_per_stream, groups by cbqs.max_groups_per_stream, leases by cbqs.max_groups_per_stream × max_in_flight, and one settings record per stream. The lease figure is a ceiling on the configuration rather than a reachable count: a lease exists only while a delivery is outstanding, so at the §15 defaults the number a broker actually holds is bounded an order of magnitude lower by the delivered rate. A rate of 4,194,304 B/s sustained over a 30-second max_visibility_ms, divided by a 152-byte delivery frame, is about 828,000 against a configured ceiling of 16,777,216. The two do not stay in that order: at the §15 maximums the rate-derived figure is the larger of the two, so a provider takes whichever is smaller for the settings in front of it.
Naming all three matters because no one of them is the whole footprint. One reading takes the byte limit as covering the footprint; another takes cycles as inside it. The difference between those two readings is a gigabyte against a few terabytes at the §15 defaults, and a terabyte against tens of petabytes at the §15 maximums, so a provider sizing from either one alone sizes wrong. The product is the number a provider budgets against, and cbqs.max_groups_per_stream is the parameter that changes it. Rent is measured in finalized block height. There is no pause-adjusted clock. Rent accrues through an emergency pause of the registry, during which no owner can top up because no CBQS instruction executes. The cost is bounded and stated: if the registry is ever pausable, a pause consumes at most the balance each account held when it began. The conditional is deliberate. CIP-12 §7’s allowlist does not currently name 0x17, though the implementation it cites does, and it is the reason this document no longer depends on the answer. Rent accrues through the pause, the balance covers what it covers, and the rest is written off by the first settlement afterwards, the same write-off §6.3 describes, reached by a different path. Recovery is one TopUpAccount per account, which settles, writes off, credits, and revives in a single instruction (§6.1). What a pause cannot do is compound: a suspended account accrues nothing, so the damage does not grow with the pause’s length once the balance is gone. That bound makes the coverage clock unnecessary. A pause can still consume the balance. Omitting the clock removes a state record, a coverage expression, a per-instruction read, and a cross-document dependency on CIP-12’s pausable-actor list.

6.1 Settlement

Settlement is defined once, here, and every instruction that touches an account calls it first, CreateStream, CloseStream, TopUpAccount, SettleAccount, and WithdrawAccount, with no exceptions. All account-touching handlers follow this rule: exempting TopUpAccount would leave the amount owed unchanged but increase what is collectible, so topping up before settling handed the next settlement a larger balance to take for an interval the owner had already been refused service through, and made a provider’s optimal strategy never to settle a lapsed account.
Every account-touching handler runs settle first, then its own effects, then finalize. Revival and deletion tests must observe the updated active_streams and balance. Running them before those changes would leave a funded top-up suspended or leave a streamless account flagged as insolvent, allowing an incorrect provider close under §5.1. Settlement has five properties. active_streams is constant across every settled interval, because every mutator settles before it changes the counter and finalizes after. due is exact rather than an approximation, and the broker computing the same product from the same record gets the same answer. The rate is snapshotted when a billing run starts and stays fixed for its duration. CreateStream copies cbqs.stream_rate_per_block into the account on the transition from active_streams == 0 to 1, the moment the account begins to be billed, and nothing else reads the parameter. A newly created account stores a rate of zero. Four of its five readers multiply by active_streams and so cannot observe it while the account has no streams; the fifth is CreateStream’s own guard, which is why §5 orders the rate write before it. Both halves matter. Fixing the rate within a run makes settle a pure function of the account and the height, which is what §6.3 claims. If the account re-copied the rate at every settlement, any caller could pick the moment a rate rise took effect, because settlement is permissionless, and hand the provider 90% of the difference. Re-reading the rate at the start of a run lets a governance rate change reach every account. If the account copied the rate only at creation, an owner could keep a zero-stream account, which accrues nothing and can be held indefinitely, and so hold an old rate forever. The transition from 0 to 1 is the right place because only the owner can trigger it, so no third party can choose when a repricing lands. An owner therefore pays, for each continuous run of streams at one provider, the rate in force when that run began. The underfunded branch takes the whole balance rather than a whole number of blocks, so nothing is left that is neither paid nor owed, and §6.3 states what the write-off costs. A suspended account accrues nothing, so an abandoned account’s arrears cannot grow without bound and revival never costs more for having been left. The broker refuses its mutations (§6.2), which is what makes charging nothing correct rather than generous. An account with no streams is never suspended, because finalize clears the flag after the handler has decremented the counter. That is what makes §4.3’s deletion rule reachable on the abandoned-account path, the one the rule exists for. distribute splits every paid amount out of custody:
The split is a protocol constant, not a governance parameter. A live parameter here has the same retroactivity as a live rate. The settle function pays for an interval that has already elapsed, and at provider_bps = 0 one governance write would pay providers nothing for service already rendered. The rate is fixed by snapshotting; the split is fixed the cheaper way, by not being writable. There is no separate platform parameter: the platform share is the complement, and a stored copy of 10000 - CBQS_PROVIDER_BPS could only disagree with it. provider_share is credited to account.provider, one recipient, because §4.3 keys the account by it, and platform_share to the Platform Fee Account, system actor 0x18, the same account and rule as CIP-31 §4. Both addresses are known without a lookup, so settlement’s state-I/O is a fixed pair. Integer division truncates toward zero and the platform share is the exact complement, so provider_share + platform_share == paid for every input, and custody is debited by exactly paid. The truncation is one-directional: provider_share is zero exactly when paid <= 1 nano-CBY, which is why §15 gives cbqs.stream_rate_per_block a floor rather than only requiring it to be nonzero. TopUpAccount credits between settle and finalize, so the sequence is: settle the elapsed interval against the old balance, write off whatever it could not cover, credit the new money, then finalize, which sees the new balance and clears suspended. A funded owner is revived by one instruction, whoever else submitted what in the same block: an adversary who orders SettleAccount ahead of the top-up changes nothing, because the second settlement finds due == 0 and finalize runs on the credited balance.

6.2 Solvency, and what the broker refuses

An account is serviceable at H_snapshot when
This is the same expression settle evaluates, over the same fields, at the same scope, which makes the broker and chain agree. A per-stream test could not state it, because one stream’s dues say nothing about its siblings’ claims on a shared pool. The broker MUST evaluate serviceability on every request that appends or creates broker state, not only when a session opens, and MUST refuse those requests with AccountSuspended when it fails. The test is whether the action creates or extends durable broker state. That covers every append, CreateLane, CreateGroup, SetStreamSettings, and any UpdateGroup that raises record_deadline_ms. DeleteGroup is exempt: it removes state rather than creating any. Among the five lease actions the test covers Extend alone: Ack, Reject, Nack, and Release all release a lease, and the no-new-lease rule below forbids re-acquiring one, so all four are exempt; Extend keeps a record leased past the expiry that would otherwise return it, so it is not. That discriminator is exact because Nack moves no deadline: §9.2 releases a Nacked record at issued_at + visibility_timeout_ms, the moment silence would have released it, so no exempt action extends a record’s unavailability beyond what the lease already bought. If a Nack could park a record for an hour while Extend bought at most thirty seconds, the exempt action would buy a hundred and twenty times the lifetime of the gated one. Without the exemption a suspended account’s consumers cannot terminate the cycles they already hold: each lease expires, each expiry counts toward max_attempts exactly as a Nack would (§9.2), and at the §15 defaults a suspension of any length costs each in-flight cycle exactly one attempt, since the no-new-lease rule below forbids the redelivery a second attempt would need, and refusing Nack would have burned an attempt on the very cycle its holder was asking to release. Evaluating it only at session open would let a session established while solvent keep appending for the whole life of its grant against an account that had since been suspended. Admin-chosen grant expiry never exempts a request from the serviceability check. Reads and replays are the provider’s call: it MAY continue serving them, because they cost bandwidth rather than durable state and cutting a consumer off from data already paid for serves nobody, and it MAY refuse them with the same code once an account is suspended, because §6.1 guarantees it is paid nothing for them and max_delivered_bytes_per_sec is not a small number. This is the one serviceability decision left to the provider. A Group delivery is not a request, so the rule above does not reach it and this one does. While an account is unserviceable the broker MUST NOT issue a new lease. A lease is durable state created at the broker’s own initiative, and it is the one growth path a suspended owner would otherwise still get for free. Existing leases run to their expiry unchanged. Together with the Ack/Reject/Nack exemption this makes the in-flight set monotonically shrink through a suspension rather than churn: a consumer drains what it holds, no attempt is burned on a cycle its holder was forbidden to terminate, and the group is quiescent by the time the owner tops up. The test needs no chain round trip; every field is in the snapshot the broker already holds.

6.3 Creation charge, and the write-off

CreateStream MUST debit CBQS_STREAM_CREATION_CHARGE from the owner’s native account, never from its CBQS balance, and credit it to the zero address in the same transition that writes the stream record, failing without creating the stream when the debit cannot be completed.
The charge has three properties. It is a protocol constant, so no governance write can price permanent registry state at zero. It is credited to the zero address, so a self-providing owner cannot recover it through the rent split the way it recovers CBQS_PROVIDER_BPS. And it is debited from the native account rather than from custody, so it cannot consume balance that providers have already earned but not yet settled. Settlement writes off the shortfall. When settlement finds the balance short, the balance goes to zero and the unpaid remainder ceases to exist; no later instruction can collect it, and because §6.1 makes TopUpAccount settle before it credits, new money cannot be reached backwards through the interval it was written off from. A provider’s collectible is bounded by what the account holds, and settlement cadence does not change it. balance has exactly three debit sites, settle’s two branches, both paying this provider, and WithdrawAccount, which requires active_streams == 0 and so requires a CloseStream that §6.1 makes settle first. The balance is therefore unreachable except through a settlement that pays this provider, so settling every block and settling once after a year collect the same amount. No governance parameter controls settlement cadence. What bounds unpaid service is §6.2’s per-request serviceability test, evaluated against a snapshot no older than cbqs.max_snapshot_age_blocks, a bound three orders of magnitude tighter than any settlement interval. Settlement is permissionless: nobody is obliged to submit it, so a provider that wants to be paid submits SettleAccount itself. A permissionless caller can therefore materialize another owner’s suspension or revival, but not change what that owner owes: settle is a pure function of the account and the height, so the only thing the caller chooses is when the same arithmetic runs and how often, and how often costs the provider nothing, because §15 requires cbqs.stream_rate_per_block to be a multiple of 10. provider_share is therefore exact on the full branch, so settling every block for a year pays the provider exactly what settling once would. The multiple-of-10 rule removes the per-call truncation a permissionless caller could otherwise force, at the cost of one clause on a parameter whose Default, floor, and Maximum already satisfy it. The same key is why the exposure is bounded: because the account belongs to one provider, no other provider’s settlement can reach the balance this one is owed from. A provider that settles on its stated cadence is exposed to at most that cadence of service, and to nothing that happens elsewhere on the network.

7. Authorization

The stream’s current admin key signs a StreamGrantV2. The owner controls that key through UpdateStream. An owner account signature is not itself a valid grant signature.
Bits above 7 MUST be rejected, as check 6 of the ordered list below. Bit 5 is unassigned: version 1 used it for REDRIVE, and version 2 has no dead-letter queue to redrive. It is left as a hole rather than closed up so that the remaining bits keep the meanings they carried in version 1 and a v1 verb table ports unchanged; STREAM_ADMIN is new at bit 7 and authorizes §13 settings changes. A grant setting bit 5 is not rejected. It simply authorizes nothing, which is the same disposition as a grant setting no bits at all. The grant carries no per-holder in-flight limit. On the grant it would need a durable per-holder counter, a rule about when to check it relative to lease release, and an answer for a holder presenting several valid grants. The bound lives on the group as max_in_flight_per_holder (§9.2), where it is one number beside the group total, needs no per-grant counter, and has one answer per holder. holder_signing_key_id is keccak256("cbqs/signing-key-id/v2" || canonical(holder_signing_key)). It is stated here because it identifies the holder for three later rules: lease ownership and max_in_flight_per_holder (§9.2), and the append rate across the holder’s sessions (§13). All three lose their shared scope if it is read as a per-session or per-grant handle instead. grant_nonce exists so an owner can mint distinct grants over identical terms, so a per-grant reading gives one holder as many budgets as it holds grants, which is the multiplication those scopes prevent. The broker MUST verify the following in the order listed, rejecting on the first failure. Two things fix the order. Check 5 subtracts two values the grant supplies, and orders its own two comparisons so that the subtraction cannot underflow. And the signature is verified third, after two comparisons that cost nothing: a strict Ed25519 verification is roughly three orders of magnitude more work than a memcmp, an unauthenticated peer can send OpenSession frames as fast as a socket drains, and cbqs.max_sessions_per_connection caps open sessions rather than handshake attempts. Ordering the free checks first means a peer that guesses neither the chain instance nor a stream the broker serves pays for nothing. Two of the three codes this exposes before authentication, ChainInstanceMismatch and StreamUnknownToBroker, tell such a peer nothing it did not already supply. The third, AuthorizationGenerationStale, does: it reports whether this broker’s snapshot has caught up to a generation bump, which is broker state and is the signal an attacker timing the use of a revoked grant wants. It is exposed deliberately, because the alternative is to verify a signature before deciding whether the stream is one this broker serves, and a peer that learns a broker is behind still needs a valid admin signature to use anything.
  1. the exact chain_instance_id and stream_id;
  2. authorization_generation equal to the snapshot’s value;
  3. the admin-key signature over stream_grant_signing_bytes_v2;
  4. the time window, allowing at most cbqs.max_clock_skew_ms, evaluated as not_before_ms <= now + cbqs.max_clock_skew_ms and now <= expires_at_ms. The skew is applied to not_before_ms only: a grant already past its raw expires_at_ms MUST be rejected with GrantExpired, because admitting it inside the skew would open a session §7 requires to terminate at once, a session with no usable lifetime, and no single ordering of SessionOpened and GrantExpired for a client to expect. Both comparisons arrange the skew against the broker’s own clock rather than against a grant field: the grant’s two timestamps are u64s an unauthenticated peer chose, so not_before_ms - skew underflows at not_before_ms = 0 and expires_at_ms + skew overflows at u64::MAX, while now + skew is bounded by a clock and a governance parameter;
  5. not_before_ms < expires_at_ms. The stream admin chooses the expiry; there is no maximum lifetime, including for expires_at_ms = u64::MAX. A Set lane scope has at least two and at most cbqs.max_lane_ids_per_grant sorted, unique ids. A one-element Set MUST be rejected, because Exact already expresses it, and a broker admitting both would verify two grant preimages and issue two grant_ids for one authority. That is not forbidden in general. The grant_nonce field exists so an owner can mint distinct grants over identical terms, and so give each holder a distinct grant_id to name in its session proof, but it should be deliberate rather than a side effect of two spellings of one scope. Distinct grants are not separately revocable: version 2 has no per-grant revocation, and UpdateStream’s two operations, admin-key rotation and a generation bump, both act on the whole stream, so revoking one holder invalidates every outstanding grant at the next snapshot refresh. An owner that needs a smaller blast radius uses shorter expiries, which check 5 bounds;
  6. verbs has no bit above 7 set, then the requested verb, and both scope dimensions by intersection. A group scope never widens a lane scope; and
  7. the grant’s max_message_bytes and max_append_bytes_per_sec against the stream’s §13 settings, the effective bound being the lower of the two.
A lane scope may name a lane that does not exist yet, because §8 assigns lane ids from a counter: Exact(7) authorizes whatever lane becomes the seventh. That is a standing authorization over part of the stream’s future namespace, and owners issuing narrow scopes SHOULD name only lanes that already exist. CreateLane therefore requires lane_scope = Any, returning LaneScopeTooNarrow otherwise: a holder scoped to specific lanes cannot mint the very ids its scope names, which is the one place the counter would otherwise let a narrow grant widen itself. CreateGroup requires group_scope = Any for exactly the same reason, returning GroupScopeTooNarrow otherwise. §9.2 assigns group_id from a per-stream counter, so Exact(3) is the same standing claim on the future that Exact(7) is for lanes, and a holder that can advance the counter to 3 reaches a group the owner meant to create itself, setting start and max_in_flight_per_holder, which §9.2 makes immutable, so UpdateGroup cannot repair it. A counter removes the reuse half of that hazard and leaves the advance half, which is the half this rule closes. A holder that must both create groups and be confined to one afterwards needs two grants: an Any-scoped one to create with, and a narrow one to operate with. That is the same shape §8 already forces for lanes. Scope is checked on every operation, including lease actions. An operation that resolves to a (lane, group) pair, every Ack, Nack, Release, Extend, and Reject, whose bodies name a lease rather than a lane, MUST have both components inside the acting session’s scopes, returning LaneScopeDenied or GroupScopeDenied. Naming a lease does not exempt an operation from the scopes the grant states. A session begins with the client’s OpenSession carrying the grant. The broker answers with SessionChallenge, echoing that frame’s request_id and carrying an unpredictable 32-byte challenge, an unpredictable session_id, and an expires_at_ms no more than cbqs.session_handshake_timeout_ms in the future. The client initiates this exchange. A challenge issued unprompted on connection could not echo a request_id, and would cap the connection at one session, contradicting cbqs.max_sessions_per_connection. The client returns:
signed by the grant’s holder key over keccak256(session_proof_signing_bytes_v2(proof)). The broker MUST reject the proof, and MUST close the session being established while preserving the connection, whose other sessions are unaffected by one bad proof, unless all of:
  • proof.session_id and proof.challenge are the exact pair issued for this OpenSession on this connection, and that pair has not already completed a session, so a captured CompleteSession frame opens nothing, and the broker retains at most cbqs.max_sessions_per_connection pairs, which die with the socket;
  • the proof arrives before the challenge’s expires_at_ms;
  • proof.grant_id == grant_id(grant) for the grant carried in OpenSession, and proof.stream_id and proof.chain_instance_id equal that grant’s; and
  • the signature verifies under grant.holder_signing_key.
Requests inside a session are not individually signed. Every Request frame carries the session_id it executes under (§11.1), and the broker MUST execute it with exactly that session’s grant and MUST reject a session_id that is not open on the connection that sent it. No request body carries a stream_id: the session determines it, so there is nothing to disagree with. The exposure this accepts is stated in Security Considerations: an attacker who can inject into an established TLS session acts with that session’s authority. Per-request signatures would not have prevented the same attacker from reordering or dropping frames. A broker MUST terminate a session, and every subscription opened under it, when any of the following becomes true:
  • the grant’s expires_at_ms passes, this is the bound §3 relies on, and it needs no snapshot refresh to observe;
  • the snapshot shows the grant no longer matches (a bumped authorization_generation, a rotated admin key, or a Closed stream), no later than the first request the broker serves after the refresh that observed the change; or
  • the connection carrying it closes.
A broker MUST NOT open a new session for a stream that is Closed, absent from its snapshot, or whose owner account is not serviceable (§6.2). The codes are StreamNotActive, StreamUnknownToBroker, and AccountSuspended (§14).

8. Lanes

Lane 0 is the default lane. It exists for every stream, has no LaneRecordV2, and is always Active. The CloseLane method rejects it, so there is no status to report. ListLanes therefore does not include it, and cbqs.max_lanes_per_stream counts created lanes, so a stream may hold that many lanes with ids 1 upward in addition to lane 0. These three rules keep two brokers from returning different pages for an empty stream or differing by one at the creation ceiling. Lanes above 0 are broker-side state:
The broker assigns lane_id; the client cannot choose it. CreateLane returns the next unused integer for that stream, starting at 1, and the broker never reissues one: it keeps a per-stream high-water mark, committed in the same atomic write as the LaneRecordV2 it assigns (§10), so a recovery cannot hand the same id out twice. cbqs.max_lanes_per_stream bounds how many may be Active at once, and cbqs.max_lane_creates_per_min bounds the rate at which a stream may mint them. Ids cannot be squatted, but creation still costs durable state under flat billing. CloseLane MUST be rejected for lane 0 with LaneNotClosable. Lane 0 is where a client appends when it has no reason to route. The AppendRequestV2.lane_id field is a plain u64, so there is no wire form for “no lane” and 0 is the value a client sends, and closing it would make the stream unusable for every holder that never created a lane, irreversibly and from one request. A closed lane rejects new appends and remains replayable through the retention floor, after which the broker MAY drop its LaneRecordV2. The counter, not the record, is what prevents reuse, so the record has no reason to outlive the data it describes. Lane creation is rate-limited per stream at cbqs.max_lane_creates_per_min. A creation over that rate returns RateLimited. Broker-assigned ids prevent squatting. Creation still writes records and high-water marks at no marginal cost under flat billing, so the limit applies per stream rather than per grant. ListLanes requires at least one of CONSUME, REPLAY, or LANE_ADMIN; APPEND alone does not authorize topology discovery. It is paginated by cbqs.max_lane_list_page, filtered by the caller’s lane scope before the page limit, with an exclusive after_lane_id cursor. A lane is a routing filter over one total order. Lanes have no independent provider, billing, retention, or ordering authority, and no per-lane quota carve-out: a hot lane consumes the stream’s shared throughput and may backpressure its siblings. An honest broker enforces a lane-scoped grant. The grant provides no cryptographic isolation.

9. Records and delivery

A record is identified by its sequence: u64. The first record of a stream has sequence = 1; sequences increase by exactly one per committed record and are never reused. 0 is not a record. It is the value every exclusive lower bound in this document takes before anything has been committed, a cursor that has consumed nothing (§11.3), a consumer group’s progress watermark (§9.2), a retention floor over an empty stream (§12), and reserving it is what lets each of those be a plain u64 instead of an Option<u64> that every reader has to unwrap the same way. An origin of 0 would make the sentinel and the first record the same number, which is the one collision a sequence space cannot tolerate. The broker fills stream_id from the session. The header carries no client-chosen field. Every field in it is one the broker assigns and reads. A message identifier and an application timestamp belong in the payload for the same reason the next paragraph gives, and putting them in the header would be worse than redundant: a broker-visible field the broker never interprets invites a later rule to interpret it, which is the history §9.1 and §12 both record. RecordHeaderV2 carries the version byte because it is the canonical preimage inside record_digest (§10), which a provider signs. Application semantics, reply routing, storage references, encryption framing, and application deduplication identifiers belong inside the payload. The broker-visible header contains only delivery mechanics; the broker MUST NOT interpret payload bytes. Payloads above the effective max_message_bytes, the lower of the §13 setting and the grant’s limit, MUST be rejected with MessageTooLarge. An append is acknowledged only after the record has crossed the durable-commit boundary of §10. The broker MUST NOT acknowledge from memory or an operating-system page cache. A verifier recomputes records_digest from every record in the batch. A party that holds the whole batch can prove the provider committed to exactly that range. A party that holds only some of it cannot, and no arrangement of this receipt changes that: a producer whose records shared a batch with another producer’s is such a party. Goal 5 requires a batch commitment that a full-batch observer can verify. A producer cannot verify it from its own append alone. Returning the receipt inside Appended would give every producer 245 bytes it could not verify and, at the §15 defaults, require 6.00× the acknowledgement egress the delivered ceiling allows. At 87,381 minimal appends per second, a 288-byte reply requires 25,165,728 B/s against a 4,194,304 B/s ceiling. Per-record binding, a Merkle path over the batch, would make a producer’s own proof checkable, and is deliberately not here: nothing in v2 consumes such a proof, and §11 already declines lane-scoped verification on the same ground.

9.1 Producer retries and duplicates

The broker does not deduplicate appends. A retried Append that the broker already committed produces a second record with a second sequence. Nor does the record carry a client-chosen identifier for a consumer to deduplicate on. A deduplication key has to be a pair such as (producer, client_message_id), because client_message_id is client-chosen and two honest producers on one stream may pick the same one. A single header field would therefore be unusable for exactly the purpose it appears to serve: a consumer deduplicating on it alone drops messages it has never seen. The identity a deduplicating party needs is the producer’s to define, and §9’s first paragraph puts it where a producer can define it, the payload. §9.2 already places the obligation on the party that acts on a record: at-least-once delivery repeats application effects, and a consumer MUST make those effects idempotent or deduplicate in its own state. A consumer deduplicating on an identifier its producers agreed on gets exactly the property the broker was approximating, at the layer that must implement it anyway, over the records it actually holds. A producer whose Append times out cannot learn whether it landed because this document defines no query for it. Retrying may duplicate the record; declining to retry may lose it. Under an at-least-once service the consistent choice is to retry, and it is the choice the delivery model already assumes on the consuming side. A broker-side deduplication store is a durable object per append that outlives the record it describes, so it is bounded by the append rate rather than by any byte budget: at the §15 defaults such a store would carry roughly 195 GB per stream, 182× retained_bytes_limit’s own default, non-evictable, against a flat rent. The bounds considered for that store each failed. Its count parameter was 363× tighter than the permitted rate. Its shared byte budget had an eviction rule that could not reach the entries, so it stalled the stream. Its derived figure was enforced by no rule. Its monotone floor compared a client clock against a broker clock and so admitted a duplicate under compliant inputs: an entry received before the floor could still carry a client timestamp up to cbqs.max_clock_skew_ms beyond it, so its retry passed the test its own eviction was supposed to fail. That store needed a rule relating two clocks that the protocol does not relate anywhere else. Without the store the record carries no client clock, since that field existed only to be compared against the floor, and no other rule in this document reads a client timestamp.

9.2 Consumer groups

Groups are broker-side objects and are not chain state.
The client supplies every field; nothing is inherited. Making six of them options that fall back to per-stream defaults would save a client six values and cost an inheritance rule, a “stores the resolved value” rule, six Options in a signed-adjacent encoding, and a question about what a later settings change means for an existing group. There are no per-stream defaults to fall back to: §13 carries five settings and none of them is a group default. A client supplies all six values on every CreateGroup, and GetStreamSettings returns the three governance ceilings those values are validated against (GroupCeilingsV2, §11.1) so a client can choose values that will be accepted rather than discover the bound by being refused. GroupConfigInvalid is returned, with details naming the field, when any of the rows below is violated, except the start row, which returns CursorTooOld carrying the floor, because a client whose start is merely too old needs the floor to retry with and not the name of a field it set correctly: UpdateGroup may change only visibility_timeout_ms, max_visibility_ms, max_in_flight, max_attempts, and record_deadline_ms, and re-validates only those five. The per-holder bound needs no cross-field re-check because §9.2 applies it as min(max_in_flight_per_holder, max_in_flight) at lease time: lowering the group bound lowers the effective per-holder bound with it, and raising max_in_flight_per_holder is impossible because the field is immutable. Re-validating the cross-field row would freeze max_in_flight for any group created with the two limits equal, forcing deletion to change it. The start row is checked at creation and never again: it is measured against first_retained_sequence, which advances, so re-checking it would make every UpdateGroup on a group created at an older position fail forever. The group would have to carry the one value the check now refuses, and the five mutable fields would become unreachable. group_id, lane_id, start, and max_in_flight_per_holder are immutable, and an UpdateGroup differing in any of them MUST be rejected with GroupConfigInvalid. Each is immutable for its own reason: group_id and lane_id are the record’s key; a mutable start would let one holder rewind a shared group and redeliver the whole retained log to every co-tenant, breaking the monotonicity a group’s order depends on: a cycle is created once, when its record enters the group’s range, and is never recreated; and max_in_flight_per_holder is immutable so that the bound is not trivially edited away by the holder it constrains. Head resolves once, at creation. A group created with start = Head takes the stream’s next sequence, the first record committed after the atomic write that created the group (§10). It stores that sequence as though it had been given At(n). It does not re-resolve when a subscription opens. A Cursor subscription’s Head is a different thing and stays that way: a cursor is ephemeral, so binding it to subscription-open is the only reading available; a group is durable and outlives every subscription that attaches to it, so binding it to any subscription would give one holder’s connection timing control over what every co-tenant receives. DeleteGroup is atomic against everything the group holds. In the write that removes the record it drops every delivery cycle of the group, invalidates every outstanding lease on it, and closes every subscription attached to it (§10 commits the set as a unit). The cycles are named because they are the large part: a group created at At(first_retained_sequence) holds one cycle per retained record, and §12’s floor, the only other thing that drops a cycle, cannot reach them once the group they belong to is gone. Afterwards a lease action naming any of those leases returns LeaseStale, not GroupNotFound and not DeliveryTerminal: the handle no longer resolves, which is what LeaseStale means, and a client that refetches discovers the group is gone from its subscription being closed. Without this rule four codes would be reachable for one condition, with no rule for a lease whose group vanished mid-flight. Immutability is not a defence against GROUP_ADMIN itself: GROUP_ADMIN is full control of the group, and a holder that has it can lower max_in_flight, set record_deadline_ms to expire the whole backlog, or delete the group outright. The immutable set prevents accidents and rules out the one change whose effect on other holders is invisible, a rewound start silently redelivering the retained log. An owner that does not trust a consumer does not give it GROUP_ADMIN. Broker state keys a group by (stream_id, lane_id, group_id). Creating, updating, or deleting a group requires GROUP_ADMIN scoped to both the group and its lane. cbqs.max_groups_per_stream bounds active groups per stream, and exceeding it returns GroupLimitExceeded. The broker assigns group_id, as it assigns lane_id (§8); the client cannot choose it. A CreateGroup body is a GroupConfigV2 whose group_id MUST be 0. The request carries the field because it carries the whole config, and a value the broker is going to overwrite has to be pinned rather than ignored: “ignored” admits three conforming answers to the same bytes (assign anyway, reject, require a sentinel), and 0 is outside the assigned range so it can never collide with a real id. A body naming any other group_id MUST be rejected with GroupConfigInvalid naming the field. CreateGroup assigns the next unused integer for that stream, starting at 1, and returns it as GroupCreated (§11.1); the broker never reissues one and keeps a per-stream high-water mark committed in the same atomic write as the group it assigns (§10). That single change removes two mechanisms and leaves a third. A client-chosen group_id could be deleted and recreated, so the id would need a deletion tombstone against a grant scoped to Exact(group_id) authorizing a group it was never issued for, and the tombstone would need an expiry, which would need a governance parameter. A monotone counter makes reuse impossible by construction, so neither has anything left to do. It is the same reasoning §8 already applied to lanes. The rate limit is the one that stays. Group creation is rate-limited per stream at cbqs.max_group_creates_per_min, and a creation over that rate returns RateLimited. The limit bounds the group creation rate. The cost of each one depends on its starting position: a group created at At(first_retained_sequence) mints a cycle for every record the stream currently retains, so the expensive create is the one that starts at the oldest retained record rather than at Head. A provider budgets for the rate times the retained-record count, which is the same product §6 states for the footprint as a whole. cbqs.max_groups_per_stream bounds only groups that are active, so on its own it is defeated by churn: a GROUP_ADMIN holder that creates and deletes in a loop never raises the active count, never reaches the cap, and mints a GroupConfigV2 and a high-water-mark bump per cycle, durable writes at no marginal cost under flat per-stream rent. A counter prevents id reuse. Creating records still costs durable writes. §8 states the same thing for lanes in the same words. The counter makes the other two mechanisms redundant; the rate limit still does its own work. Each record is delivered at least once to each applicable group until one terminal state occurs:
There are two terminal states, and no dead-letter queue. A record that a group cannot process, because its attempts ran out, because a consumer rejected it, or because its deadline passed, reaches EXPIRED and stays in the log, where a Cursor subscription replays it by sequence until §12’s floor passes it. A third, dead-letter state with a Redrive verb could only be drained blindly, never inspected, so it would be a second index over bytes the log already holds, carrying its own TTL, its own governance parameter, its own page limit, and its own reclamation rule. Leaving it out costs a client one thing: a Cursor replay names records by sequence rather than handing back only the failed ones. At-least-once delivery repeats application effects. A consumer MUST make those effects idempotent, or deduplicate in its own state. This is the consuming side of §9.1’s decision not to deduplicate on the producing side, and it is stated here, inside the section that defines delivery, and inside §19 clause 8’s conformance surface, rather than only in Security Considerations, because it is the obligation §9.1’s argument rests on. Delivery creates a lease naming the group, sequence, delivery-cycle id, attempt number, consumer holder_signing_key_id, and expiry. The lease handle is a 32-byte value the broker MUST choose unpredictably, so that a co-tenant cannot name another holder’s lease and read the denial codes as an oracle over its delivery state. Ack, Nack, Release, Extend, and Reject MUST name that lease, and the broker MUST reject a lease action whose session’s holder_signing_key_id differs from the one the lease was issued to, with LeaseNotYours. Without that check any holder carrying ACKNOWLEDGE could terminate another holder’s in-flight records. Reject is terminal in one request, and under session-level authority the acting identity is no longer on the wire per request. A lease expires. Its expiry is visibility_timeout_ms after issue, and when it passes without a terminal action the record returns to the group for redelivery, the attempt counter increments, and the attempt counts toward max_attempts exactly as a Nack would. Without that rule a silent consumer would hold a record’s delivery cycle open until §12 evicted the record underneath it, so every retry a producer was owed would be spent on a consumer that had stopped answering; with it, max_attempts bounds how long silence costs before the cycle reaches EXPIRED and stops consuming the group’s in-flight budget. Expiry and Nack share one transition, including the last one. An expiry that completes the attempt exhausting max_attempts transitions the cycle to EXPIRED directly; it does not return the record for a further delivery it has no attempt left for. At max_attempts = 1 the first lease’s expiry therefore terminates the cycle, and a second delivery never happens. Stating it removes the only reading under which the two paths differ.
  • Ack transitions the cycle to ACKED.
  • Nack ends the attempt and frees the in-flight slot at once, and the record becomes deliverable again at issued_at + visibility_timeout_ms, the moment a silent expiry would have released it, or reaches EXPIRED when the completed attempt exhausts max_attempts. A record waiting out that interval holds no lease and occupies no max_in_flight slot, which is stated because the interval is the one point where a cycle is neither leased nor terminal: a broker that held the slot would let one holder freeze a group for the whole interval with a single round trip, and Backpressure would then clear on a timer rather than “as other holders drain” (§14).
  • Release gives the lease back unprocessed. It frees the in-flight slot, and the attempt the lease spent is refunded: the cycle’s attempt counter decrements, so the next lease has the same attempt number. With delay_ms = 0 the record becomes deliverable again at once. With a nonzero delay_ms the cycle cools until now + delay_ms, holding no lease and no slot, and the group delivers its other records meanwhile; delay_ms MUST NOT exceed the group’s visibility_timeout_ms, the cooling a Nack already imposes, else the request is rejected with DelayTooLarge. A cycle refunds at most RELEASE_REFUNDS = 8 releases, whatever its max_attempts; past that budget a Release is exactly a Nack (its delay_ms ignored), and the record can reach EXPIRED like any other. The budget is deliberate poison-message protection: a record that every holder gives back, or a holder that leases and releases in a loop, spends the refunds and then the attempts, so no record circulates forever.
  • Extend sets expiry to min(now + extend_ms, issued_at + max_visibility_ms).
  • Reject transitions directly to EXPIRED.
  • passage of record_deadline_ms, measured from the moment the record’s batch crossed the durable-commit boundary (§10), transitions the cycle to EXPIRED.
Release is for work the holder could not serve, not work that failed. A consumer uses it when it took a lease it cannot process. One example is a native room session’s consumer that could not keep a subscription open (CIP-11 §15.9). Another is a consumer whose session is busy with other in-flight work: it releases with a delay so that, on a single-flight group, the record it gives back does not come straight back ahead of the in-flight work that would free the session. Returning that work with Nack, or letting it expire, would spend an attempt on a record nobody tried, and at max_attempts = 1 would end the record unexecuted. Work that was attempted and failed uses Nack or Reject. Release requires ACKNOWLEDGE, resolves its (lane, group) scope and holder exactly as Nack does (§7), and is exempt from the §6.2 solvency gate on the same ground. Nack carries no delay of its own, and it moves no deadline. It ends the attempt and frees the in-flight slot at once; the record becomes deliverable again at issued_at + visibility_timeout_ms, which is exactly when it would have become deliverable had the holder said nothing. So Nack and a silent expiry are one transition with one timing, and answering is never worse for the group than staying quiet. That is the protocol’s entire backoff policy: a consumer that wants longer raises visibility_timeout_ms, where the value is validated against a ceiling and applies to every holder alike. Each clause above closes a specific failure. A Nack carrying its own delay_ms of up to an hour, beside an Extend that buys at most thirty seconds, would let the action §6.2 exempts from the solvency test buy a hundred and twenty times the lifetime of the action §6.2 gates. A Nack that released immediately is worse in a way that is easy to miss: a group orders its cycles by sequence, so a just-released cycle is the lowest non-terminal sequence and is redelivered ahead of everything appended after it. The Nack-redeliver loop then runs at round-trip speed, spends all of max_attempts in milliseconds, and since a record whose attempts run out reaches EXPIRED with no dead-letter path, a consumer retrying the way client libraries retry destroys the record it was trying to process. A delay measured from the moment of the Nack rather than from the lease’s issue reinstates the first failure at a smaller magnitude. A Nack at issued_at + visibility_timeout_ms - 1 would hold the record for almost twice the window, and make a prompt Nack cost the group more than silence. Extend adds extend_ms to now, not to the current expiry or to issued_at. It caps the sum at issued_at + max_visibility_ms, anchored to the lease’s original issue, so a sequence of extends is bounded in total rather than rolling forward. An Extend whose now + extend_ms exceeds that cap is rejected with DelayTooLarge rather than silently clamped. Both operands are stated because both were ambiguous, and either ambiguity alone lets the same request sequence succeed on one broker and be refused on another. A terminal cycle is reclaimed with its record. A terminal cycle MUST be dropped once §12’s floor has passed the record it names, and MUST NOT be dropped before. With two terminal states and no dead-letter TTL, the floor is the only reclamation deadline a cycle has. record_deadline_ms ends delivery but does not drop the cycle. A stream’s delivery state therefore cannot outlive the records it describes: cycles are bounded by retained records × applicable groups and §6 states that product as part of a provider’s exposure. MUST requires reclamation. MAY would leave the state unbounded and the response dependent on the broker’s collection policy. A lease naming a dropped cycle returns LeaseStale, and one naming a retained cycle returns DeliveryTerminal, so two conforming brokers would answer the same request differently according to whether either had collected. LeaseStale identifies the dropped case because the handle no longer resolves. Refetch is its remedy and the correct one. A group orders its cycles by sequence, and may lease up to max_in_flight of them at once. There is no per-group queue counter or second ordering: with Redrive gone, a cycle is created once, when its record enters the group’s range, and never recreated, so a record’s position in the group is its position in the log. Redrive would need more: a redriven record has to sort behind records appended after it while its sequence is still the lowest, which takes a queue_position counter, and ordering by (redrive_epoch, sequence) instead puts a later redrive of a lower sequence ahead of a cycle that already exists. Without redrive, neither is needed. A lease requires room under both max_in_flight for the group and min(max_in_flight_per_holder, max_in_flight) for the requesting holder_signing_key_id; the first returns Backpressure, which clears as other holders drain, and the second returns HolderInFlightLimitExceeded, which does not.

10. Durability and checkpoints

The broker commits appends in batches, one batch per stream. A stream’s batch closes when cbqs.commit_batch_max_ms elapses with at least one record buffered, or when cbqs.commit_batch_max_records records are buffered, and one synchronous durable write commits it. An append is acknowledged only after the batch containing it commits, so a batch is the unit of both durability and signing. A broker MAY commit several streams’ batches in one physical write; the batch a checkpoint attests is always one stream’s. A batch with no records produces no checkpoint.
A broker MUST retain a receipt for as long as any record it attests is retained (§12). Those bytes count against retained_bytes_limit like the records themselves, so the obligation is bounded by the limit the owner sets. There is no server-pushed checkpoint frame. A per-batch push is an unbounded write obligation against a peer that grants no credit, and bounding it to one pending frame per session discards evidence a client cannot recover. GetCheckpoint serves every reader a push would serve: §4.4 step 4 wants the latest checkpoint, a replay wants a sequence to resume from, and a client retaining a checkpoint_id outside the provider wants the latest; all three are one GetCheckpoint away, and a Request is not governed by subscription credit, so a consumer out of credit reaches its evidence by asking. Omitting the push also removes a credit-exempt-but-not-rate-exempt carve-out from §13 and the only unsolicited channel by which a lane-scoped holder would learn the whole stream’s commit cadence. Sequences in a batch are contiguous, so record_count is last_sequence - first_sequence + 1 and is derived rather than carried: a carried copy could disagree with the range it accompanies. The digest commits that count alongside the concatenation, so two batches cannot share a digest by regrouping. The chain of checkpoints covers the stream without gaps. For a checkpoint whose previous_checkpoint names another checkpoint of the same stream, first_sequence MUST equal that predecessor’s last_sequence + 1; for the first checkpoint of a stream, previous_checkpoint MUST be checkpoint_genesis = keccak256("cbqs/checkpoint-genesis/v2" || chain_instance_id || stream_id) and first_sequence MUST be 1, the first record of the stream (§9.1), since 0 is the empty-stream sentinel and never names a record. committed_at_ms MUST NOT decrease along the chain. Without the contiguity rule a provider could link A(1..100) to B(201..300) and destroy every record between them while a verifier walking the chain saw unbroken linkage. Linkage integrity and coverage integrity have to be the same check. A verifier MUST check both halves, and the linkage half is the digest. For each receipt after the first, previous_checkpoint MUST equal the predecessor’s checkpoint_id (§10). Contiguity on its own is the mirror of the gap above and fails the same way: a provider that swapped one receipt for another covering the same range with a different records_digest would be equivocating about what it had committed, and a verifier comparing only sequences would accept either. Both are genuinely signed by the provider. Verification can cross the retention boundary (§12). A broker keeps a receipt only as long as the records it attests, so a stream older than its own retention_ms has no genesis checkpoint left to serve and a verifier cannot walk to one. Such a verifier MAY anchor instead on a checkpoint_id it has previously verified, together with that checkpoint’s last_sequence: linkage and coverage are both decidable from those two values, and the receipt they name need not still exist. The committed_at_ms and snapshot_height orderings compare fields the discarded receipt carried and are therefore NOT decidable at such a seam; a verifier that needs them MUST retain the predecessor receipt rather than its id. A verifier MUST NOT report an empty set of receipts as verified: there is no proposition in it to be true. The provider signs keccak256(checkpoint_signing_bytes_v2(receipt)) with the key whose validity interval contains snapshot_height, and snapshot_height MUST be a finalized height the provider actually read and MUST NOT decrease along the chain. A verifier resolves the key from the provider record by the same interval:
The previous key’s lower bound is what makes the third row reachable. Without it the second row would swallow every earlier epoch: a receipt honestly signed two rotations ago would resolve to the previous key, fail the signature check, and be adjudicated invalid, which §10 calls “signed evidence of provider misbehaviour”. That outcome accuses an honest provider. That gives three verdicts, and they are decidable rather than merely named:
  • a key resolves and the signature verifies, valid;
  • a key resolves and the signature does not verify, invalid, and the verifier MUST reject it; and
  • no key resolves, because the receipt predates the rotation before last, unverifiable, which the verifier MUST report as such rather than as invalid.
The third verdict still applies within a bounded history: two rotations still put a receipt beyond the registry’s reach, and a client that wants one to stay checkable retains the key alongside it. That is the disclosed limit of on-chain key history, and Security Considerations states what it costs. A verifier MUST also reject a receipt whose provider is not the provider the stream record names. The atomic durable commit set for one batch is: the record bytes, the assigned sequences, the checkpoint receipt, and the checkpoint-chain tail. For delivery mutations it is the delivery state and the lease state. For a lane creation it is the LaneRecordV2 and the stream’s lane high-water mark (§8); for a group creation it is the GroupConfigV2 and the stream’s group high-water mark (§9.2). Both counters are named beside the record they assign, and for the same reason: a crash between the record and its counter lets the next create reissue an id, and a grant scoped Exact(n) would then authorize an object it was never issued for, the failure broker assignment exists to make impossible. Recovery MUST replay or roll back an incomplete transaction as a unit. A broker MUST NOT acknowledge an append, expose a sequence, or serve a record whose batch has not committed. A subscriber holding every record of a range recomputes records_digest and compares it with the signed value; a mismatch, a break in linkage, a gap in coverage, or two different checkpoints naming one range is signed evidence of provider misbehaviour. Three limits are stated rather than implied: a subscriber holding only some lanes cannot verify a checkpoint at all, because the digest is flat over the batch; no consensus state anchors any checkpoint chain, so a provider serving two divergent chains is detectable only by a party holding both branches, and clients that need this SHOULD retain their latest checkpoint_id outside the provider; and no availability guarantee follows, because v2 has no dispute or slashing path.

11. Transport and flow control

11.1 Frames

The transport is a bidirectional TLS WebSocket carrying binary frames. One WebSocket message contains exactly one canonical frame: version: u8 = 2, a one-byte frame tag, then the canonical body. A frame larger than cbqs.max_wire_frame_bytes MUST be rejected before allocation, and every variable-length field inside a frame MUST be capped at decode by its §15 bound, in particular a grant’s Set lane scope at cbqs.max_lane_ids_per_grant, rather than only at verification, so an unauthenticated peer cannot make the broker allocate or verify beyond those bounds.
Client tags 5 and 6 and server tags 7 and 8 are reserved for Package R’s policy-fence and boot-info extension; they MUST NOT be reassigned. Client tag 7 closes only a session owned by the connection. Native room bootstrap (client tag 4) and content-free room accounting (client tags 8/9, server tag 9) are defined in Native room sessions and accounting, which is part of this contract. These additions retain wire version 2 and the existing 5 MiB frame ceiling. All other unassigned frame tags remain invalid. Delivery.lease is present for a Group subscription and absent for a Cursor one, which takes no leases (§11.2); it is an Option rather than a zero sentinel because §4 forbids the sentinel. DeliveryStateBodyV2 has one variant. There is no Terminal variant reporting a cycle’s terminal state: the consumer that acts on a cycle already gets a Response, and no other consumer needs to be told. CreditShort is how §11.2’s broker reports the head frame’s size, and it names no group because a Cursor subscription has none. message is a human-readable summary of the code’s own condition. It MUST NOT carry implementation internals, store errors, file paths, query text, stack frames, and MUST NOT vary with the existence or state of an object the acting session is not authorized to observe; without that, Internal (§14) is an oracle over exactly the state the denial-precedence rule works to hide. message and details MUST each be at most cbqs.max_error_message_bytes; details is empty unless §14 defines a payload for the code. A connection MUST hold at most cbqs.max_sessions_per_connection open sessions and cbqs.max_subscriptions_per_connection open subscriptions; exceeding the first returns SessionLimitExceeded. Two deadlines bound an unauthenticated peer. Every outstanding challenge MUST be closed after cbqs.session_handshake_timeout_ms. This deadline applies per challenge, so a second session cannot hold one open indefinitely. A connection that has completed no session within that same interval of its first byte MUST be closed. Without the second, a peer that sends OpenSession frames and never completes one holds zero sessions and zero subscriptions, so every other per-connection bound is satisfied at zero while each frame still costs the broker a grant verification before any proof of possession. The deadline runs from the first byte. It can expire before the first frame completes. Separately, and for the life of the connection rather than only before its first session, a broker MUST close any connection whose partially-received message has not completed within cbqs.session_handshake_timeout_ms of that message’s first byte. The second rule is scoped to the whole connection because the hold it closes is not a handshake hold: a peer that completes one session satisfies every pre-authentication bound permanently and can then hold a partial message on every connection it opens. Both halves are stated because a WebSocket message can be fragmented indefinitely: a peer that opens a connection, begins a message and sends one byte completes no frame, so a frame-anchored deadline never starts while the broker accumulates reassembly buffer up to cbqs.max_wire_frame_bytes. The “reject before allocation” rule of this section can only fire once a frame is known to exceed the cap, and a length that is never declared never exceeds it. CbqsRequestBodyV2 is a tagged union whose tag is the method tag below: GetCursorProgress reads an open cursor subscription owned by the acting session and returns CursorProgress { subscription_id: Bytes32, lane_id: u64, scanned_through: u64 } (response tag 9). A missing, closed, foreign-session, or group subscription returns SubscriptionNotYours. The current grant MUST allow the cursor’s lane. scanned_through is an inclusive stream position: all records for that lane through it have already been sent on the same connection before the response. Records of other lanes can advance this position without being disclosed. The operation MUST NOT scan, append, grant credit, or move the cursor; its response reports transport progress. It provides no signed checkpoint. CreateLaneForKey binds a nonzero allocation key and nonzero metadata hash to one sequential lane within the session’s stream. Zero inputs return MalformedFrame. Current session, verb and scope checks MUST precede the binding lookup. An identical retry returns the existing active lane even when new allocation would exceed capacity or rate limits. Different metadata for the same key returns LaneAllocationConflict (3957); a closed lane returns LaneClosed and MUST NOT reopen. A new key follows CreateLane admission limits. The broker MUST durably commit the binding, lane and advanced lane counter together before responding. Bindings survive closure and restart; they do not provide idempotency after loss of that broker’s durable store. MaterializeRoomLane creates a deterministic room lane in the session’s stream. room_id MUST be nonzero. A zero seat_id selects the shared Messages lane; a nonzero seat_id selects that seat’s inbox. The full lane commitment and broker lane id are:
A derived zero lane id MUST be rejected with InvalidGrant. The session MUST carry APPEND and lane_scope = Exact(lane_id); Any and Set MUST be rejected with LaneScopeDenied even when they contain the derived lane. This request refusal MUST leave the otherwise valid session open. LaneScopeTooNarrow applies to operations such as CreateLane that require Any; widening a room materialization grant does not satisfy its exact-scope requirement. The broker MUST durably store the full commitment with the lane before returning LaneCreated { lane_id }. Repeating the operation for an active lane with the identical commitment is idempotent. An existing lane with a different or absent commitment MUST return InvalidGrant; a closed lane MUST return LaneClosed. New lanes count against cbqs.max_lanes_per_stream and return LaneLimitExceeded at the ceiling. Materialization does not allocate from or advance the sequential lane id allocator. The stream administrator’s exact signed grant delegates this topology operation. It does not establish room membership or authorize actor execution. The room projector and runner MUST separately validate finalized room and seat authority before routing or executing a message. Brokers MUST support method 21 before projectors use these lanes; an unsupported broker returns UnknownMethod and the client MUST NOT substitute CreateLane. GetGroup returns the stored GroupConfigV2, or GroupNotFound. It exists because UpdateGroup carries a whole config and MUST be rejected when any of the four immutable fields differs from the record: without a read path, a holder newly granted GROUP_ADMIN cannot construct an acceptable UpdateGroup at all, and would have to be handed the full configuration out of band, which contradicts GROUP_ADMIN being full control of the group. GetCheckpoint returns the named checkpoint’s CheckpointReceiptV2, or the stream’s latest when checkpoint_id is absent; an id that is not a checkpoint of this stream, or one whose records are no longer retained, returns CheckpointNotFound. A broker MUST resolve the id by a bounded index lookup, never by scanning history. A replay does not take a checkpoint id. A checkpoint start would leave open whether it means the checkpoint’s first_sequence or its last_sequence + 1, so two brokers could replay disjoint ranges from the same cursor, and it would draw two codes for one condition, CursorTooOld from §11.3 and CheckpointNotFound from here, which §14’s precedence leaves unordered. A client that wants to replay from a checkpoint reads its last_sequence here and passes At(last_sequence + 1). At(n) delivers from sequence n inclusive, and Head delivers only records committed after the subscription opens. Both are stated because an explicit number is explicit only once its own resolution is fixed. Unknown method tags are invalid and return UnknownMethod. ListLanes.limit MUST be at least one and at most cbqs.max_lane_list_page; a value outside that range returns PageLimitInvalid rather than being clamped, so a client never has to guess whether its page size was honoured. ListLanes is the only paged method version 2 has. A subscription belongs to the session that opened it. CloseSubscription, Credit, and every Delivery for it MUST name a subscription_id opened under the acting session; a request naming another session’s subscription MUST be rejected with SubscriptionNotYours, even on the same connection. Without that rule a holder with an APPEND-only grant could open a second session on one connection and close, or exhaust the credit of, a consumer’s subscription.

11.2 Subscriptions and credit

A Cursor subscription replays a lane scope from a position and takes no leases; it needs REPLAY (or CONSUME for Head). A Group subscription attaches the session to a consumer group and receives leased deliveries under §9.2; it needs CONSUME. Without this second form the entire lease model would be unreachable from the wire: Ack and its siblings would name a lease that nothing could produce. A subscription’s lane scope MUST be inside the grant’s lane scope, and a Group subscription’s (lane_id, group_id) MUST be inside both the grant’s lane and group scopes. A subscription carries a credit balance in encoded frame bytes. The broker MUST NOT send a Delivery frame whose encoded length exceeds the remaining credit, and MUST decrement the balance by exactly that length. DeliveryState and Response are outside the credit balance, neither gated by it nor decremented from it, and are bounded by §13’s max_delivered_bytes_per_sec alone. Binding the rule to the frame class rather than to the word “delivery” is what makes CreditShort sendable: it is a DeliveryState frame of 71 bytes, and a credit-gated reading would forbid it in exactly the condition it exists to report. Credit adds bytes to the balance, saturating at cbqs.max_subscription_credit_bytes; a Credit that would exceed it saturates rather than wrapping, and the balance is a u64 so no sequence of u32 additions can overflow it. An uncapped credit would disable the mechanism Goal 3 rests on. A subscription is a slow consumer, and MUST be closed with SlowConsumer, when its credit has been at least the encoded size of the next pending delivery for cbqs.slow_consumer_timeout_ms and it has accepted nothing in that window. The broker compares credit with the size of the head frame: a client whose credit is merely smaller than the next frame is complying, and closing it would punish the party doing the right thing. When credit is below the head frame’s size the broker MUST report that size in a DeliveryState frame carrying CreditShort { needed_bytes } (§11.1). Scheduling across subscriptions on one connection MUST be starvation-bounded: a subscription with sufficient credit and pending records MUST be served within cbqs.max_subscriptions_per_connection scheduling rounds.

11.3 Replay

A Cursor start behind the retention floor returns CursorTooOld (§12). A replay MUST deliver in ascending sequence within each lane, and each Delivery frame it sends is bounded by cbqs.max_wire_frame_bytes like every other frame (§11.1) and by the subscription’s remaining credit (§11.2). A bound on “the bytes it materializes per response” would fail on both halves: bytes materialised inside a broker are not chain state, a wire byte, or a response, so the rule would be outside the observability the Specification preamble claims and outside §19’s lettered exceptions; and Response is a frame class that carries no records, so the bound would name the wrong frame. Delivery already has those bounds, so this section needs no separate bound.

11.4 Dialing policy

A client MUST determine the destination address of every connection it makes, by resolving a name, or by reading an address literal straight out of the URI, and MUST NOT connect unless that address passes the check below. Stating it over the destination rather than over “addresses it resolves” matters because §4.1 admits wss://127.0.0.1/ws and wss://[::1]/ws: both are byte-legal, and neither involves a resolution step at all. The destination MUST NOT be loopback, unspecified, link-local, unique-local, multicast, or in a private or special-use range. Concretely, a client MUST reject any IPv4 destination in 0.0.0.0/8, 10.0.0.0/8, 100.64.0.0/10, 127.0.0.0/8, 169.254.0.0/16, 172.16.0.0/12, 192.0.0.0/24, 192.0.2.0/24, 192.88.99.0/24, 192.168.0.0/16, 198.18.0.0/15, 198.51.100.0/24, 203.0.113.0/24, or 224.0.0.0/3, and any IPv6 address outside 2000::/3 or inside 2001::/23, 2001:db8::/32, 2002::/16, 3ffe::/16, or 3fff::/20. It MUST connect only to a destination it checked, resolving once if it resolves at all and never re-resolving between check and connect. A name that resolves to more than one address is checked in full: every address in the result MUST pass, and a client MUST NOT fall back to a member of the result it did not check. The singular reading was a real hole, because every mainstream resolver returns a list and every mainstream connector races or falls back across it. A name answering with one public address and ::1 reaches loopback on a client that checked only the first. A client MUST NOT follow a redirect. Re-applying the check after each redirect would be weaker than it appears: the check constrains the address range and nothing else, so an open redirect anywhere on a provider’s edge sends the client to any publicly routable host the attacker names, and the client has no provider identity to compare the new peer against, since §7’s handshake authenticates only the client. Refusing redirects is one rule instead of the three (same-host, same-scheme, bounded count) that constraining them would need, and a provider that wants to move an endpoint updates its registry record, which is the mechanism §4.1 already provides. The check is a client obligation because only the client knows what it is about to connect to; consensus admission (§4.1) cannot, and does not try to.

12. Retention

The retention floor advances past a record when either bound is reached:
  • retention_ms has elapsed since the broker committed it, or
  • keeping it would put the stream above retained_bytes_limit, in which case the floor advances over the oldest records until it would not.
retained_bytes_limit is measured over the stream’s evictable footprint: its records and the checkpoint receipts attesting them (§10). A receipt is discarded when the floor has passed the last record it attests, which is §10’s rule read from this side; a floor landing inside a batch is ordinary at these defaults, and the two sections would otherwise disagree about whether the receipt’s bytes are still counted, which moves the floor itself, so two brokers would refuse different Cursor replays from the same append stream. Receipts belong inside it because they are per-batch and outlive nothing. At one record per batch, the worst case, reached at any append rate at or below 1000 / cbqs.commit_batch_max_ms, 50 records/s at the §15 defaults, a 245-byte receipt runs about six times a 41-byte record, so a limit that did not see them would bound a seventh of what the stream stores. The ratio falls as the rate rises, because batches close on a fixed clock while records do not. Time or size determines eviction, whichever bound is reached first. retention_ms is therefore a guaranteed window only while the stream stays inside its byte budget, and §13’s two settings together are what a client can rely on for replay. The broker measures retention from its own commit time. A record’s retention is measured from the moment its batch crossed the durable-commit boundary (§10), which the broker records for itself. RecordHeaderV2 carries no client timestamp for it to be measured from instead (§9), and that is the durable form of this rule: under a client-supplied clock a producer backdates its own records and evicts them early, which is the window this section exists to guarantee. Two alternative rules fail in opposite directions. Making the floor’s advance conditional on every consumer group being terminal or past its deadline is vacuous for a stream with no groups, so a broker could evict the instant a record was appended and Cursor replay (§11.2) would have nothing to work with. Making time the only trigger turns retained_bytes_limit into a hard ingest ceiling. At the §15 defaults a producer at its own permitted rate fills 1 GiB in seventeen minutes and then stalls for the remaining seven days, a sustained rate 591 times below what its own settings allow. A window bounded by time alone cannot also be bounded by bytes. Groups cannot change the retention floor. §9.2 caps record_deadline_ms at the stream’s retention_ms, so a group can neither shorten the window nor outlast it. Eviction is a terminal transition. When the floor passes a record, every non-terminal delivery cycle for it transitions to EXPIRED. That is what lets the byte bound evict without contradicting §9.2’s “delivered at least once to each applicable group until one terminal state occurs”: the cycle reaches a terminal state, and the state is EXPIRED. retention_ms and retained_bytes_limit are read at eviction, so a STREAM_ADMIN holder that lowers either (§13) shortens the window for records already retained, which §13 states plainly as the most destructive thing that verb can do. Behind the floor the broker returns CursorTooOld, whose details carry the current first_retained_sequence as a big-endian u64. The floor is monotone per stream and never regresses. A Closed stream, or one whose owner account is suspended, retains data at the provider’s discretion; a provider SHOULD state its policy in its registered metadata. This is not consensus state.

13. Broker-side stream settings

Five settings, one per resource the provider actually spends. There are no default_* fields, because §9.2 has no group-config inheritance. A holder with STREAM_ADMIN sets these through SetStreamSettings, which replaces the whole record. Each field is validated against the ceiling below on every change, enumerated rather than stated as a rule, because the ceilings do not share one naming convention, and a stream with no explicit settings uses those parameters’ defaults. Every field MUST be nonzero. A violation returns SettingsInvalid with details naming the field; SettingsRejected is reserved for a provider declining settings it will not serve, so a client can tell an invalid value from a policy refusal. Ceilings are admission-time only. A stream stores its resolved settings and a group stores its config, and no request path re-reads a §15 ceiling to bound an already-accepted value. A governance write constrains the next SetStreamSettings or CreateGroup and never retroactively narrows a stream that is already running. GetStreamSettings returns the settings and the §15 ceilings a client needs to build a valid GroupConfigV2, cbqs.visibility_ms, cbqs.max_attempts, and cbqs.max_in_flight_per_group, in the Settings response body (§11.1). §9.2 made every group field mandatory, so the client has to know its bounds, and a client holding only a grant has no other way to learn them. The ceiling on record_deadline_ms is the stream’s own retention_ms, which the same frame already carries in settings; repeating it among the ceilings would be a second copy of one value in one frame, with no rule for a client that finds the two different, the pattern §10 and §6.1 both refuse elsewhere. Settings are broker state: they need no chain transaction and do not change what the owner is charged. A provider MUST enforce the accepted settings. max_append_bytes_per_sec and max_delivered_bytes_per_sec are enforced as rate limits returning RateLimited. The broker cannot silently drop requests to enforce these limits. Both are per stream, in aggregate over every session and every connection acting on it. A grant’s own max_append_bytes_per_sec is a second bound at a different scope, per holder_signing_key_id, across that holder’s sessions, and a request must pass both. §7 check 7’s “lower of the two” bounds the holder. The stream limit still applies. Without the aggregate scope one holder key opening sessions on many connections multiplies the rate. max_append_bytes_per_sec is measured over the encoded AppendRequestV2 of every append the broker decodes, accepted or refused, charged before the admission checks. Charging refusals is what stops the limit defeating itself: a producer over its rate would otherwise pay nothing to stay over it, since everything it sends is refused and a refusal that costs nothing is free. It is measured over the request alone, because the request is the only part of the exchange whose size is fixed by the encoding, an Error’s message is implementation-chosen prose bounded only above, so metering the reply would make the admitted append rate depend on how verbose a broker’s diagnostics are. The two ceilings are related, and §13 does not enforce the relation. Each setting is validated against its own §15 row and never against the other, so an owner may configure a stream whose permitted ingest cannot be delivered. Two couplings matter, and they behave differently. The first is fan-out, and it is inherent. One accepted append produces one Appended, then per applicable group one Delivery and one Ok answering the Ack that terminates it. Writing A and D for the two settings, n for the payload and G for the number of groups, one delivery attempt per record needs
which at the §15 defaults (D / A = 4) admits no groups at all below a 61-byte payload, one from 61 bytes, two from 185, three from 556, and never four. The bound approaches 4 asymptotically without reaching it, against a cbqs.max_groups_per_stream of 4,096. It is a lower bound in a second sense too: max_attempts permits up to that many delivery attempts per record per group, so a stream whose consumers retry needs a multiple of it. No accounting rule removes this coupling, because the bytes are the service the stream exists to provide. The excess does not accumulate. §12’s floor evicts, and eviction transitions every non-terminal cycle for an evicted record to EXPIRED, but a client sees records expire that it never saw delivered. The second is refusals, and it is not inherent. A refused append is answered with an Error of up to 45 + cbqs.max_error_message_bytes bytes, 2,093 at the defaults, against a 12-byte request, inside D, at whatever rate A permits, so a holder with APPEND alone and a bad lane_id can exhaust a stream’s delivered budget without exceeding its own, starving every consumer on the stream. An earlier draft moved an append’s reply into A to close this, which closed it and broke three other things: it metered Error.message, whose width no rule fixes, so two brokers admitted different append rates from one setting; it charged the refusal announcing exhaustion to the budget already exhausted, while the stop rule that ends the delivered budget’s exhaustion was not carried across; and the reply cannot exist until its batch commits, so two brokers charged it to different one-second windows. What closes it without those is a bound on the reply rather than a change of budget, and this document does not have one: a provider that needs it caps message far below the Codec ceiling, which costs diagnostics rather than correctness. Providers size delivery capacity using the inequality. cbqs.max_groups_per_stream caps group count; it promises no delivery rate. max_delivered_bytes_per_sec is measured over Delivery, DeliveryState, Response and Error, four of §11.1’s six server frames, an append’s reply included. SessionChallenge and SessionOpened are outside it because they are answered at most once per OpenSession, and §11.1’s two handshake deadlines close the connection of a peer that opens sessions it never completes. Error is inside, with one exception: the single RateLimited frame reporting that the budget is exhausted is sent outside the budget, one per session per exhaustion and at most one per connection per exhaustion, after which the broker serves that session no further bytes from this budget until the budget refills. It does not close the session. Both caps are stated because only the second bounds the exemption: sessions are capped per connection, connections are not capped at all (§11.1), so a per-session cap alone scales with a quantity this protocol does not bound. Stopping service to the session outright would punish whichever session was next to be served rather than whichever had consumed the budget. The ceiling is per stream, so under contention these are routinely different holders. Exempting the whole class instead would have handed any holder an unmetered egress channel at roughly sixty times amplification, and handed it first to a suspended account, which §6.1 guarantees pays the provider nothing, inverting the incentive §6.2 rests on. Scoping the limit to Delivery alone would leave Response outside every rate bound. It is bounded per frame, by cbqs.max_wire_frame_bytes and by the page caps, but not per second, and Response is the amplifying class: a ListLanes at cbqs.max_lane_list_page answers an 80-byte request frame with a page two orders of magnitude larger, on a verb a read-only holder has. Lowering a retention setting can discard existing records. A reduction of retention_ms advances the eviction horizon, and §12’s floor then moves past everything older. One request can discard nearly the whole retained log, because the only constraint on the new value is that it be nonzero and within the ceiling. A reduction of retained_bytes_limit below current usage does the same through §12’s other bound: the floor advances until the stream fits, so the excess is discarded at once rather than aging out. A clause such as “MUST NOT prune below the floor already published to clients” would forbid nothing: pruning only ever advances the floor, and §12 already makes the floor monotone, so it would restate an existing property without protecting retained data. Instead, STREAM_ADMIN is a separate verb bit an owner need not issue, as Security Considerations explains.

14. Typed errors

§14 is the broker’s wire-error table. Every code below is something a broker returns to a client over §11’s transport. Chain-instruction rejections are not in it: a rejected SYS_CBQS instruction fails its transaction and surfaces through the platform’s ordinary execution-error path, so enumerating a CBQS wire code for each of the roughly fifteen refusals §4–§6 state would invent a second, parallel error channel that nothing reads. All bindings expose stable typed errors. Version 2 assigns its own error codes. Activation resets the network (§18), so it need not preserve version-1 client compatibility. Several codes below describe conditions assigned to different codes in version 1. Within version 2 the numbers are fixed. When a request fails checks in more than one of the classes below the broker MUST return a code from the earliest class: unknown method (UnknownMethod), then malformed frame (MalformedFrame), then session binding (SessionNotOpen), then verb (VerbDenied), then scope (LaneScopeDenied, GroupScopeDenied), then object state (LeaseNotYours, then LeaseStale, then DeliveryTerminal, then AccountSuspended, then the not-found codes). Each class names the code it returns, because an ordering over classes with no code in one of them orders nothing, and the object-state class is ordered internally for the same reason lease handles are unpredictable (§9.2): a broker that answered DeliveryTerminal before LeaseNotYours would tell a holder naming someone else’s handle what state that delivery is in. Codes outside those classes, capacity, rate, size, and version refusals, are unordered relative to them and to each other. An Extend that would advance expiry past issued_at + max_visibility_ms is rejected with DelayTooLarge rather than silently clamped, so a client never has to guess whether its request was honoured. The remedy is to send a smaller number. StreamNotFound (3900) has no version-2 condition: the broker decides from a snapshot, so “the registry does not have this stream” and “this stream is absent from my snapshot” are one observation, which StreamUnknownToBroker states without implying the broker read the chain at request time. The numbers absent from the table above, 3900, 3911, 3915, 3916, 3942 through 3947, 3953, and 3955, are unassigned in version 2 and MUST NOT be emitted, and so is every number outside the assigned codes above : an implementation that reports a wire failure as 3998 because this document gave it no code is emitting an unassigned number. Unknown future errors MUST be preserved by clients as (code, message, details) rather than mapped to success or retry.

15. Parameters and bounds

All decode-time collection and byte lengths MUST be capped before allocation, and the cap applied at decode is the row’s Maximum, never its deployed value. An instruction body carries two: the endpoint vector’s u32 count, capped at cbqs.max_provider_endpoints’ Maximum of 8, and each endpoint URI’s u32 length, capped at cbqs.max_provider_endpoint_uri_bytes’ Maximum of 2,048. Capping at the deployed value instead would make the same payload decode on one deployment and fail on another. The deployed value of either is then an admission check (§4.1 rules 1 and 2), which is a different disposition and a different charge: a 9-endpoint payload fails decode and is charged nothing, while a 5-endpoint payload on a Default-4 deployment decodes, reaches its row, and is rejected with its row’s reservation charged. cbqs.max_provider_endpoint_uri_bytes has Default equal to Maximum, so for that row the two coincide and only the decode cap can fire. These decode bounds apply to incoming wire data. Existing state follows a separate rule: a stored ProviderRecordV2 decodes at whatever length it was admitted with, so lowering cbqs.max_provider_endpoints stops new registrations without making live providers unreadable. The Read by column says who reads the parameter: C a consensus handler, B the broker. The Class column says when a change reaches an object:
  • An Admission parameter is read when an instruction or a request is admitted; the accepted object never consults it again.
  • A Ceiling parameter bounds a value at the moment it is set (§13 settings, §9.2 group config). The accepted record stores its resolved value, so a later write never redefines an existing stream or group. §13 states this as a rule, not only as a class.
  • A Runtime parameter is read continuously by the broker; a change takes effect with the snapshot that carries it. Only operational limits live here.
  • A Codec parameter is a decode bound whose Maximum equals its Default, so a conforming decoder accepts the same byte strings on every deployment. Maximum equals Default does not by itself make a row immovable; the rule below does that.
A Codec row is not governance-writable at all. A governance write naming one MUST be rejected. That is the whole of the protection, and it is the half that does work: §18 rule 1 seeds every row at its Default, so genesis cannot produce a divergent Codec value in the first place and a genesis check for one would never fire. A genesis check alone, with the Codec rows outside Tier 0, would leave the four rows whose whole purpose is that every deployment reads them alike as the only rows with no post-genesis protection. Lowering cbqs.max_wire_frame_bytes or cbqs.max_lane_ids_per_grant on a running network splits decoders and invalidates outstanding grants. Every CIP-12 change to any other cbqs.* row is Tier 0. A governance write below a row’s Minimum MUST be rejected, on the same path and with the same disposition as one above its Maximum. A Codec row is not governance-writable at all, so its Minimum is written —. Below a row’s Minimum, another rule becomes unsatisfiable or the broker spins or destroys data:
  • cbqs.retention_ms at 0 is the sharpest. §13 gives a stream that never set its own settings the parameter’s value, and §12 then treats every record as past its retention, so one write deletes the entire retained window on every such stream, chain-wide and irreversibly.
  • cbqs.visibility_ms, cbqs.max_attempts and cbqs.max_in_flight_per_group at 0 make §9.2’s group config unsatisfiable in both directions at once. The field must be greater than zero AND no greater than the parameter, so no group can be created or updated again.
  • cbqs.max_message_bytes, cbqs.max_retained_bytes_per_stream, cbqs.max_append_bytes_per_sec and cbqs.max_delivered_bytes_per_sec at 0 do the same to §13’s settings.
  • cbqs.session_handshake_timeout_ms at 0 expires every challenge before it can be answered. cbqs.max_lane_list_page at 0 admits no valid page size, since §11.1 rejects a limit of 0 and a limit above the parameter alike.
  • cbqs.snapshot_refresh_ms, cbqs.slow_consumer_timeout_ms, cbqs.commit_batch_max_ms and cbqs.commit_batch_max_records at 0 make a loop spin or fire on every pass.
Where 0 merely disables an operation it stays admissible, and those rows carry a Minimum of 0. Freezing new streams, sessions, lanes, groups or subscriptions is a governance choice this table leaves open, and so is tolerating no staleness (cbqs.max_snapshot_age_blocks) or no clock skew (cbqs.max_clock_skew_ms) at all. cbqs.stream_rate_per_block’s floor of 10,000 is its Minimum in the table. It MUST also be a multiple of 10 after any governance write. That rule is separate, and stays in prose because the table has no column for it. Neither needs a genesis clause: §18 rule 1 seeds every parameter at its default, and the default is 80,000. Every row’s Default is inside its own [Minimum, Maximum], so §18’s genesis state is admissible under the rule above. The multiple-of-10 requirement is what makes provider_share exact on settle’s full branch, where paid = elapsed * rate_per_block * active_streams and so paid * 9000 / 10000 divides evenly. Without it, the truncation is per call, and SettleAccount is permissionless: anyone could settle every block and move up to one nano-CBY per call from the provider to the Platform Fee Account. With it, N settlements across an interval pay the provider exactly what one would, and the only residue left anywhere is the partial branch’s single truncation below. A floor rather than merely nonzero, because §6.1’s provider_share = paid * 9000 / 10000 truncates toward zero, and is zero exactly when paid <= 1 nano-CBY, with the Platform Fee Account taking all of it. The full branch has no loss to bound. The multiple-of-10 rule above makes provider_share exact there. The floor is for the partial branch, where paid is whatever the balance holds, so a final paid of 1 nano-CBY pays the provider nothing. That residue is one nano-CBY per insolvency event and does not compound, because reviving the account costs the owner at least rate_per_block * active_streams. Four protocol constants are deliberately not parameters, because a governance write that set any of them to zero would price permanent state at nothing or pay a provider nothing for service already rendered:

15.1 State-I/O reservations and metered cost

Each instruction reserves exactly this many state reads and writes before its first admission check, and therefore before its first state operation. The pairs are protocol constants: they do not vary with stream shape, balance, branch, or any other observed state, and changing one is a consensus change requiring a new document version. Every handler reads the Stream Registry singleton. Each row is then exactly: Five of the eight carry settlement’s reads and writes, because §6.1 makes every account-touching instruction settle: CreateStream, CloseStream, TopUpAccount, SettleAccount, and WithdrawAccount. TopUpAccount reads the provider record as well, to reject a top-up naming a provider that does not exist (§4.3). Only RegisterProvider, UpdateProvider, and UpdateStream touch no CBQS account and carry none of it; RegisterProvider still reads and writes two native accounts for its §4.1 charge. Only CreateStream reads cbqs.stream_rate_per_block, because §6.1 lets only the transition from 0 to 1 write the account’s rate. settle multiplies by the rate the account already stores, so no other instruction consults the parameter. That correspondence is the metered form of §6.1’s rule: an instruction reads the parameter if and only if it can start a billing run. Every branch of every instruction is charged exactly its reserved reads and writes. A successful branch also performs them; a rejected branch persists none of them and is still charged for all of them, and what it actually performed before failing is informational (below). Handlers perform their credit writes unconditionally, including for a zero amount and on settle’s suspended branch; a handler that deletes the account record under §4.3 performs a state write in place of the update it would otherwise have made. A handler that skipped a zero-value write, or took a cheaper path on one branch, would meter differently from one that did not, and the two would disagree on gas in the same block. This is why the artifact below pins several branches of one instruction at identical read, write, and cell counts. Cycles differ with payload bytes and the number of carried keys. The charge includes cycles_per_instruction_byte × decoded_instruction_bytes plus CBQS_KEY_VALIDATION_CYCLES × carried_key_count, reserved before validation. Optional keys can change both terms; endpoints and other variable payloads change the byte term. State-I/O reservations do not vary with a cheaper handler branch. The shared cost classifier and admission charge include the same per-key term. The artifact below includes key_validations for every row and key_validation_cycles = 600 in its constants block, matching the Ed25519 KEY_VALIDATION_CYCLES row in CIP-3 §2.5. The exact metered cost is pinned as a normative artifact beside this document as cip-39-gas-vectors-v2.json (schema cowboy.cbqs.gas-vectors.v2), covering every branch §19 item 2 names. A conforming implementation MUST reproduce every pinned field of every vector, measured against that artifact, whose SHA-256 is 8f0bf5e0ae4b94ab2c6683b8fd796dbdd9518f5e4ac2afeb53628d5587f51457 after CIP-43 removes the state-read/write cycle terms and adds the Access total. The artifact’s constants include key_validation_cycles=600; every row carries key_validations, and RegisterProvider’s one-key success path is 725 Cycles. Each carried key adds exactly 600 Cycles before validation. The revised artifact retains the same branch set, state-I/O reservations, Cells and Accesses; only key-carrying rows gain that Cycle charge. Every vector is reachable under the genesis parameter set §18 rule 1 mandates; none requires a prior governance write. The artifact’s constants block uses the platform’s implemented metering schedule, including a flat per-state-write Cell charge. CIP-3 §2.2.2 describes PVM host metering with a per-byte state_set model. CIP-39 leaves both models unchanged; CIP-3 must reconcile them. The vectors are CBQS-dispatch scoped: each covers this document’s decode surcharge plus its handler’s key validation, hash, signature, and state-I/O work, and excludes the transaction base, intrinsic calldata cells, the outer system-instruction dispatch, and event emission (§16), all of which the platform levies uniformly outside this family. Hash charging is max(1, ceil(len / 32)) words. A rejected instruction is charged its reservation. charged_reads and charged_writes equal the table above on every path, successful or rejected: the reservation is taken before the first admission check and is never refunded, and a handler computes every hash its row names before that first check, excepting only the §4.2 singleton read that the stream-id derivation’s own inputs depend on, which §18 rule 1 makes unreachable at genesis. So a rejected instruction is charged the handler base, its decoded instruction bytes, its per-key validation charge, its reservation, and its hash words, and differs from the successful path only in what it persists, nothing, and no event (§16). A payload that does not decode is not a CBQS charge at all. A SYS_CBQS payload whose version byte is not 2, whose tag is outside 1–8, or whose body violates §4’s canonical encoding fails transaction decode: the instruction is a field of the transaction, not a length-prefixed blob a handler unwraps, so the enclosing transaction never reaches CBQS dispatch and this document charges it nothing. That is the platform’s uniform decode path, which §15.1 already excludes. §18 rule 2 assigns this case to the decoder. §15 draws the decode/admission boundary these charges rest on: a payload over a row’s Maximum fails decode and is charged nothing, and one within the Maximum but over the deployed value decodes, reaches its row, and is charged that row’s reservation. Without a single statement of that boundary the same instruction has two charges depending on which side an implementation puts a parameter, which is the free variable this section exists to remove. On a rejected path, state_reads and state_writes are informational. Only reserved_*, charged_*, cycles, and cells are normative there. This document fixes only the orderings whose outcome depends on them, §5’s rate write before CreateStream’s balance guard, §5.1’s settlement before a provider’s close, and §6.1’s call to settle, followed by the handler’s effects and then finalize. It fixes no order among the remaining admission checks, so how far a particular rejection got before failing is an implementation’s choice; pinning it would impose a check order indirectly. What is pinned is that the charge does not depend on which check fired. The rule is stated because fees on a failed transaction are consensus-visible on this platform, so an unpinned rejection path is a free variable in the state root. That a rejected instruction persists nothing settles its state effects and leaves its gas open. On a rejected CreateStream the two readings, charge the reservation, or charge only I/O actually performed, differ by up to 2,700 cycles and 8,000 cells on a transaction anyone can submit deliberately. The artifact carries one rejection vector per instruction, so the rule is tested rather than asserted.

16. Chain events

Events are consensus data: emitter, topic, payload bytes, and order commit through logs_root into receipt_root. The topic is the exact UTF-8 byte string shown; the payload is exactly the one fixed-length identifier listed. Each successful instruction emits exactly one event, the one on its row, and a rejected instruction emits none. The emitter is the Stream Registry system actor 0x17 for every row. Neither the transaction sender nor the account named in the payload emits the event, regardless of which account authorized the instruction. The address is stated rather than derived from a rule like “the actor that owns the state”, because six of the eight handlers also write native accounts at 0x00…00, 0x18, and the provider’s own address, and a derivable rule reopens the question for each of them. Leaving the emitter unstated is a consensus divergence of the same kind §4.1 and §4.3 close for their seeded record fields: it is committed data no instruction body carries, so two implementations choosing differently produce different logs_root and therefore different receipt_root while metering identically. The v2 events publish record levels and carry no state-transition edges. A consumer that needs to know whether a particular settlement suspended or revived an account diffs CbqsAccountV2.suspended across the blocks around the event; two settlements for one account in one block leave the intermediate state unobservable. Events carry no amounts, so provider revenue, platform accrual, and the two burns, the stream creation charge and the provider registration charge, are reconstructed from balance deltas rather than from the log. An edge-and-amount event set is a follow-up CIP if indexers need one. The event payload carries the owner rather than the (owner, provider) pair because a 20-byte payload is the established shape; a consumer that needs the provider reads the account record at that block.

17. Operational surface

cbqsd exposes /statusz (CIP-42 self-report, where answering at all is the liveness signal), /readyz, and /metrics in Prometheus text form. /readyz reports only data-plane readiness: 503 when the store is unwritable, or when the commit loop has stopped making progress while records wait. A failed registry snapshot refresh MUST NOT make the broker unready. Nor MUST the age of a refresh loop’s last success make it unready. Only one with an overdue refresh attempt is unready: §3 requires continuing refresh attempts while serving from the existing snapshot. A readiness probe that failed on chain reachability would have a load balancer remove exactly the brokers still able to serve. That argument holds while the snapshot is inside cbqs.max_snapshot_age_blocks; past it the broker refuses every OpenSession with ChainStateStale (§3) and serves only its established sessions, which is still service and still worth routing to, but an operator draining such a broker for new connections is acting on the /metrics snapshot age rather than on /readyz. The condition is reported as a /statusz degraded flag and a /metrics gauge carrying the age of the current snapshot.

18. Activation and removed surface

Document version 2 supersedes version 1 in full. CBQS has never activated on a network whose state must be preserved, and version 1 already specified itself as reset-only and pre-launch. Activation is at genesis:
  1. genesis MUST seed the Stream Registry singleton and every §15 parameter at its default, MUST reject a parameter set carrying any cbqs.* key §15’s table does not name, MUST NOT seed any other record under 0x17, and MUST leave 0x17 holding no native balance. Stating the rule exhaustively rather than naming version-1 artifacts is what keeps it checkable from this document alone. A validator does not need to know what version 1 stored in order to reject it. Seeding defaults also satisfies §15’s cbqs.stream_rate_per_block floor and its Codec-class equality, so neither needs a genesis check of its own; both bind governance writes, which is where §15 states them;
  2. a decoder MUST reject a SYS_CBQS payload whose version byte is not 2;
  3. a decoder MUST reject any stored CBQS record whose version byte is not 2; and
  4. a broker store MUST carry a store-format marker cbqs/store-format = 2 written at creation, and a version-2 cbqsd MUST refuse to open a store whose marker is absent or not 2 rather than attempt a partial decode. The marker’s key is cbqs/store-format and its value is the single character 2; a store carrying a version marker under any other key has not satisfied this rule, whatever that marker says. The key is pinned because a deployed version-1 store writes its marker under a different key entirely, so a version-2 broker opening one finds the pinned key absent and refuses, the disposition this rule wants, and the one a rule stated only over “a version marker” would have left to the implementation. The marker, not a per-record byte, is what covers the durable broker state this document describes without giving it a canonical struct, leases, delivery cycles, both high-water marks, and the checkpoint-chain tail.
An operator MUST NOT carry version-1 chain state, broker stores, or archived snapshot bundles across this boundary. Genesis rejects unlisted keys. A list of version-1 governance keys to reject would have to be derived from the deployed key set and the version-1 document’s table, and a genesis carrying a key neither source recorded would pass it. Rule 1 accepts only the named parameter keys. A parameter set carrying any cbqs.* key §15 does not name is rejected, which is checkable from §15 alone, strictly stronger than any enumeration, and cannot go stale. It rejects cbqs.rent.burn_bps, which version 1’s text never named but its implementation carried, paired with cbqs.rent.provider_bps by a sum-to-10,000 invariant, without anyone having had to know that. Activation resets all prior objects, so this document carries no per-object mapping from version 1. Rule 1 already answers the only question an upgrading implementation has, and rules 2 through 4 reject every version-1 byte mechanically.

19. Conformance

An implementation conforms when:
  1. it admits and rejects exactly the chain instructions §4–§6 define, with the state effects §6 defines and the events §16 defines. That clause is total, and deliberately not expanded into a checklist, because a harness can derive the cases. Two classes are worth naming because no gas vector can catch them: the initial field values §4.1, §4.2 and §4.3 state for a created provider record, stream record, and account, since two implementations seeding them differently meter identically; and the order in §6.1, which calls settle, applies the handler’s effects, and calls finalize, which a test distinguishes by closing the last stream of a suspended account whose balance is exactly zero and observing that the record is deleted;
  2. it reproduces every pinned field of every vector in cip-39-gas-vectors-v2.json under the genesis parameter set of §18 rule 1 with no prior governance write, a null on a rejection path is not a value to reproduce (§15.1), and meters every branch of every instruction with identical charged reads, charged writes, and cells, including settle’s full, partial, and suspended branches and the §4.3 account deletion, cycles differing only by payload bytes and the number of charged key validations; each row pins key_validations and includes 600 × key_validations Cycles before any carried-key validation.
  3. its canonical encodings round-trip as §4 defines them, reject every version byte other than 2 on every object §4 gives one, and produce byte-identical signing preimages for the three §4 registry entries;
  4. its broker accepts and rejects sessions and requests as §7 and §11 define: continued service for established sessions across a simulated chain outage (§3); refusal of OpenSession past cbqs.max_snapshot_age_blocks; single-use session_id/challenge; rejection of a session_id not open on the sending connection; termination on grant expiry with no snapshot refresh; and termination under a revoked grant on the first request served after the observing refresh;
  5. it refuses a lease action from any holder other than the one the lease was issued to; refuses a subscription request naming another session’s subscription; evaluates lane and group scope by intersection on every operation including lease actions; refuses CreateLane from a grant whose lane scope is not Any with LaneScopeTooNarrow, and CreateGroup from one whose group scope is not Any with GroupScopeTooNarrow; redelivers a lease that expires without a terminal action while an attempt remains and counts that attempt toward max_attempts, terminating instead on the expiry that exhausts them (§9.2); rejects an UpdateGroup that differs in any immutable field; and returns codes consistent with §14’s denial precedence;
  6. its broker acknowledges no append before the batch containing it is durable; every acknowledged record still retained appears in a checkpoint a client holding CONSUME or REPLAY can retrieve with GetCheckpoint (§11.1) and whose records_digest recomputes; first_sequence equals the predecessor’s last_sequence + 1 along the whole chain and 1 at checkpoint_genesis (§9.1), and previous_checkpoint names the predecessor’s checkpoint_id at every step; snapshot_height and committed_at_ms do not decrease; a receipt whose provider is not the stream’s is rejected; and §10’s three verdicts are each reachable and correctly assigned: a receipt in the current key’s window verifies as valid, one in the previous key’s window verifies against previous_signing_key and is equally valid, one whose resolved key rejects the signature is invalid, and one below previous_signing_key_since is reported unverifiable rather than rejected;
  7. its client rejects every destination in §11.4’s list, for an address literal read straight out of the URI as well as for a resolved name, and for every address a name resolves to and not only the first. It refuses to follow a redirect at all, and connects only to a destination it checked;
  8. its broker’s externally observable behaviour is the behaviour §6.2 and §§7–17 define. That clause is total, and clauses 4 through 7 name classes under it rather than exhausting it, for the reason clause 1 gives: an enumeration here adds nothing a harness cannot derive from the body, and the one this clause replaces had already fallen behind the body it was enumerating. The range names §6.2 explicitly and runs to §17 because both ends were once outside it: §6.2 is broker behaviour sitting in a chapter of chain instructions, and §17’s readiness rules were reachable by no clause at all. Three classes under it are worth naming because a passing implementation can differ without a client observing it on a healthy path: §6.2 evaluated on every append and every state-creating request rather than only at session open, which a test distinguishes by suspending an account mid-session; §6.2’s converse, that Ack, Reject, and Nack stay available while an account is suspended and that no new lease is issued while it is, which an over-refusing broker would otherwise satisfy vacuously; and §9.2’s reclamation of an ACKED or EXPIRED cycle, which is a MUST precisely because a broker that never reclaims answers a late Ack with DeliveryTerminal where a conforming one answers LeaseStale; and
  9. a crash injected on either side of a durable write boundary leaves, after restart, either no record and no acknowledgement, or the record, its sequence, and its checkpoint together (§10); and
  10. its activation satisfies §18: a genesis that seeds the singleton and every §15 parameter at its default and nothing else under 0x17, holds no native balance there, and carries no cbqs.* key §15 does not name; a handler that rejects a SYS_CBQS payload whose version byte is not 2; a decoder that rejects a stored record whose version byte is not 2; and a broker that refuses to open a store without cbqs/store-format = 2 under that key. Each is a boundary an implementation can be run against, and none of them is proved by the gas vectors, the structural checks, or the system-address invariant. Those pass equally against a version-1 deployment.
The requirements below are not externally observable, and are stated as operator obligations rather than as protocol guarantees. The Specification preamble claims observability for everything else; these are the exceptions, lettered so they are not confused with the numbered conformance items above:
  • A. the broker’s snapshot-refresh attempt interval (§3);
  • B. the truthfulness of the snapshot_height it reports in SessionOpened (§3). A broker on a year-old snapshot can report the current height, because the frame carries no proof and none is defined;
  • C. that it evaluates one request from one snapshot rather than mixing heights (§3);
  • D. that session_id, challenge, and lease handles are chosen unpredictably (§7, §9.2). A counter is indistinguishable from entropy on the wire, and the anti-replay and anti-oracle arguments rest on it;
  • E. that lane ids and group ids are never reissued (§8, §9.2), which depends on durable state a client cannot inspect. It is lettered rather than dropped because a grant scoped to Exact(lane_id) or Exact(group_id) rests on it, and a broker that reissues an id hands an old grant authority over a new object without emitting a byte that differs;
  • F. the starvation bound in §11.2, whose “scheduling round” has no wire representation; and
  • G. that a checkpoint’s snapshot_height is a height the provider actually read (§10). It selects the verification key, so misstating it downward moves a batch into an earlier key’s window, where the receipt still verifies, since the provider holds that key too. What bounds the move is previous_signing_key_since, below which a receipt stops resolving to any key at all. Monotonicity bounds it only from the other side: a provider can never stamp a batch below where its own chain already stands. Monotonicity does not constrain later batches, which remain free to return to the current height; and
  • H. that an oversized frame is rejected before allocation and that every variable-length field is capped at decode rather than at verification (§11.1). The refusal is observable through its code and response, but its position relative to allocation and signature verification produces the same response bytes either way, so a client cannot tell a conforming broker from one that allocates first and refuses second; and
  • I. that the broker does not interpret payload bytes (§9). One that parses, indexes, or routes on them emits identical frames, identical chain state, and identical codes, so §2’s confidentiality framing rests on an obligation no probe can distinguish; and
  • J. that an application whose data must survive its provider keeps its own durable copy (§2), an obligation on a party outside this protocol, which no chain state, wire byte, or broker response can evidence.
A client needing assurance about any of them reads the chain itself or measures the broker’s behaviour over time. Grant expiry, which elapses without the broker’s cooperation, is the one bound that holds regardless, which is why §3 and Security Considerations rest the revocation argument on it.

Security Considerations

Requests inside a session are not individually signed; each carries the session_id it executes under and the broker binds it to that session’s grant (§7). An attacker who can inject into an established TLS session acts with that session’s authority until it closes. Version 1’s per-request signatures did not defend against that attacker either. They were bound to a session id, so the same injection position permitted reordering and dropping. The signatures cost a signature and a verification per message. What version 1’s counter did provide, and what §7 replaces explicitly, is the binding of a request to its session: a single-use session_id/challenge pair scoped to one connection, a handshake deadline per challenge, and a per-request session_id the broker checks. Holder keys SHOULD be workload-scoped and grants SHOULD carry the shortest practical expiry. Chain authority reaches an established session at the next successful refresh; during a chain outage it does not reach it at all. cbqs.max_snapshot_age_blocks stops a broker from admitting new sessions against stale state, but a broker that lies about its snapshot age cannot be caught from the wire (§19). The bound that does not depend on the broker’s cooperation is grant expiry: it elapses on its own, and §7 requires termination on it. The stream admin chooses that bound without a protocol lifetime cap. Owners issuing long-lived grants accept the corresponding refresh-outage exposure. A generation bump revokes all existing grants once observed; rotating an admin key also invalidates grants under the old key. Neither takes effect at a broker before it observes the finalized update. STREAM_ADMIN outlives its grant. Bit 7 changes broker state, not session state: a holder that lowers retention_ms discards nearly the whole retained log in one request, and one that lowers retained_bytes_limit below current usage discards the excess just as immediately, through §12’s other bound. Either reduction is a deletion that takes one request. Revoking the grant restores neither. The verb provides no protection against these deletions (§13). An owner can withhold this separate bit from consumer grants. LANE_ADMIN is the same shape one verb over, and is disclosed here for the same reason: it closes any lane inside its scope, v2 defines no reopen, and at lane_scope = Any that is every lane but 0. It is a permanent-denial power over the lanes it names, mitigated only by not issuing the bit. A narrow lane scope is a claim on the future. Lane ids come from a counter (§8), so Exact(7) authorizes whatever lane becomes the seventh, not a lane a particular party created. §7 keeps that from compounding by requiring lane_scope = Any to create a lane at all, so a narrowly scoped holder cannot mint the ids its own scope names; but an owner issuing Exact or Set over ids that do not exist yet is pre-authorizing part of the namespace and SHOULD name only lanes that already exist. Rent accrues on chain and is collected by permissionless settlement, so a provider that never settles carries the unpaid remainder as credit risk, and §6.3 writes off whatever the balance could not cover. Because §4.3 keys the account by (owner, provider), that exposure is isolated: no other provider’s settlement can reach the balance this one is owed from, and the bound is the service rendered since the broker’s snapshot was last refreshed, which cbqs.max_snapshot_age_blocks caps. That is why §6.3 states a cadence and why §6.2’s solvency test is evaluated per request rather than per session. A session established while solvent would otherwise keep appending for the whole life of its grant against an account that had since been suspended. Every stream pays the same rate regardless of traffic, so a heavy stream is cross-subsidised by a light one. The provider’s exposure is bounded by §15’s per-stream ceilings and its own max_streams. Price does not bound that exposure. A provider unwilling to serve at the governance rate sets accepts_new = false, which refuses every new counterparty rather than a chosen one: v2 has no per-counterparty refusal, so a provider facing a repeat defaulter closes the abandoned streams under §5.1 and, if it must, stops accepting new ones. CBQS_STREAM_CREATION_CHARGE is a protocol constant credited to the zero address, so permanent stream state costs unrecoverable capital no governance write can zero, and it is debited from the owner’s native account so it cannot consume rent a provider has already earned. cbqs.max_streams_per_account and each provider’s max_streams bound the count from the other two directions, and §4.3 deletes an account that holds no balance and no streams. A provider record is permanent and unremovable, so §4.1 prices it with a charge of its own. It is the largest record here and the only one that never goes away. Rotation is prospective, not revocation. One rotation does not cost a provider its history: §4.1 keeps the previous key and its lower bound, so every receipt signed under it still verifies (§10). The same property is the exposure: a compromised key keeps resolving, and keeps producing valid verdicts, for every snapshot_height in its own interval, and §19 item G concedes that height is unverifiable, which lets a holder of a stolen key place a forged receipt inside that window. Rotating away from it does not stop that. A provider responding to a compromise rotates twice, which removes the key from the registry, and in the same moment makes every honest receipt of that epoch unverifiable rather than valid, because the epoch before last has no key there. So the remedy and the loss arrive together, and a client that needs those receipts must have retained the key alongside them before the second rotation. A client that wants a receipt checkable across an arbitrary number of rotations retains the key with it as a matter of course. There is no dispute, staking, or slashing path in v2; the remedy for a provider that stops serving is the application’s own durable copy plus the §4.4 move. Broker identity is not established at handshake time. §7 authenticates the client to the broker and nothing in the other direction: a client dials an endpoint the registry names and relies on TLS to establish that it reached the host that endpoint names. Three things follow. Checkpoint verification can detect a network-position attacker afterwards. A mis-issued certificate, a DNS or BGP hijack, or a compromised edge host puts an attacker in the session with the client’s grant and payloads, and TLS is the whole of the defence against that happening. It is not the whole of the defence against it going unnoticed: a provider signs every CheckpointReceiptV2 under the signing_key the registry carries (§10), and an impostor does not hold that key. The observer described in §9 can use this: it must hold every record in the batch because records_digest is flat. A REPLAY holder whose lane scope is Any qualifies: a batch spans the stream’s total order rather than one lane (§8), so a holder scoped to specific lanes holds a strict subset of it and is the party §10 says cannot verify at all. A consumer competing in a group does not qualify either, because it sees only the records the group hands it. The window is also finite: §12 discards a receipt when the floor passes the last record it attests, so a checkpoint whose earliest records have already been evicted still resolves while no longer being recomputable. §4.4 step 4 is the case the document already builds on this. Detection leaves the payloads disclosed to the attacker. A chain-account compromise is worse, and is only partly detectable. UpdateProvider changes signing_key and endpoints together, so an attacker holding the provider’s chain account key repoints the endpoint and installs a key it holds, in one instruction, and its checkpoints verify. What it cannot overwrite is previous_signing_key: §4.1 makes the handler move the outgoing key there, so the honest key survives the attacker’s first rotation and §10 resolves it at any height inside its interval. A client that pinned a height before the takeover can therefore still detect one, until a second rotation flushes it, which §4.1 permits at the very next block, and a client meeting this provider for the first time has nothing to pin. This document defines no pinning rule and no first-contact remedy. Neither attack is closed. Handshake relaying is a third, unaddressed one. SessionProofV2 binds the grant, the session and the challenge, and no channel: an attacker who relays a whole handshake to the genuine broker holds a session there under its own connection, authenticated, which outlives the client’s and expires only with the grant. Closing that needs channel binding this document does not define. A provider signature on SessionChallenge would close none of the three. A signature resolved from the record the attacker just rewrote proves nothing. A relayed signature remains valid. The signature would also require the client to read a chain snapshot before opening a session, preventing clients without chain access from reaching the data plane §3 keeps available. The handshake therefore carries no provider signature. Consensus admission does not establish that a registered endpoint is safe to dial; a hostname admitted at registration may resolve into private address space later, and DNS may change between one resolution and the next. §11.4 places the check on the client, names the ranges, and requires the client to connect to the address it checked rather than re-resolving, the rebinding gap a check-then-dial client would otherwise leave open. §4.1 admits the URI without parsing it, so two readers of one admitted URI may disagree about which host it names. The URI wss://a.example@b.example/ws names b.example to a WHATWG parser and a.example to a byte scanner. §11.4 makes that disagreement non-SSRF, since neither reading can reach an address in its ranges. It does not make it harmless: pick both halves public and one reading lands on a host the registrant chose and the other did not. That is the whole guarantee. It is a client-side one about address ranges rather than the identity of the host reached. Nothing in this document lets a client verify that the peer it reached is the provider the registry names. See Broker identity above. Every variable-length field in a frame is capped at decode by a §15 bound, before allocation and before any signature verification. Two deadlines bound an unauthenticated peer: each outstanding challenge, and the connection itself, which is closed if it completes no session within cbqs.session_handshake_timeout_ms (§11.1). A peer that never completes a handshake satisfies the per-connection session and subscription bounds at zero, so the connection deadline is the one that binds it. Paging is bounded by cbqs.max_lane_list_page, lane creation by cbqs.max_lane_creates_per_min, and group creation by cbqs.max_group_creates_per_min. The session and subscription bounds are per connection, and the protocol bounds no one’s connection count; that is an operator concern, and a provider SHOULD bound concurrent connections per source at its terminator. The other two do not scale that way and must not be enforced as though they did: cbqs.max_lane_list_page is per request, and the two creation limits are per stream (§8, §9.2). Enforcing those per connection would restore exactly the N-connections-N-times multiplication per-stream scoping removes. Lane ids are broker-assigned, so the namespace cannot be squatted, and cbqs.max_lanes_per_stream bounds what is open at once. record_deadline_ms is capped by the stream’s own retention, so a group’s delivery cycles always terminate within the window the stream is paid for. Under §12 no group can affect the floor at all, on any timescale. Credit saturates at cbqs.max_subscription_credit_bytes, so the backpressure mechanism cannot be disabled by a client. At-least-once delivery repeats application effects, and §9.2 requires a consumer to make them idempotent or deduplicate in its own state. A lease may be mutated only by the holder it was issued to, and its handle is unpredictable so the denial codes cannot be read as an oracle over another holder’s in-flight set (§9.2). max_in_flight_per_holder is what bounds one consumer’s share of a shared group, and it is a real bound now that there is one delivery mode. A CONSUME-only holder, the weakest consumer verb, and one that can take no terminal action, since Ack, Nack, Reject and Extend all need ACKNOWLEDGE, can absorb at most that many leases and hold them silently. Three of the four routes to EXPIRED need no action at all: attempt exhaustion, the group’s record_deadline_ms, and eviction by the retention floor. So a silent holder burns one attempt per lease per visibility_timeout_ms, and at the §15 defaults it walks each record it holds into EXPIRED in ten timeouts, five minutes, after which no path returns that record to the group. What max_in_flight_per_holder bounds is how many records at a time it can do that to; its co-tenants keep max_in_flight - max_in_flight_per_holder leases, and the records under them, throughout. The two in-flight limits constrain a hostile holder only when they differ. max_in_flight_per_holder is validated at nonzero, <= max_in_flight, so a group with max_in_flight = 1 forces it to 1 and one silent holder reaches every record in the group, one at a time. A client wanting serialized processing will choose max_in_flight = 1, and so accepts this exposure. A group with max_in_flight = 1 is a single-consumer configuration, whatever else is set on it. Setting the two equal at a larger value is different and is not a defect: honest consumers still compete, and §9.2 keeps that setting reachable because it is the escape from a frozen max_in_flight. What it gives up is the bound against one hostile holder, and an owner choosing it should know it is choosing that, the more so because max_in_flight_per_holder is immutable, so the choice cannot be narrowed later without deleting the group. None of this bounds a GROUP_ADMIN holder, which can lower max_in_flight, expire the backlog through record_deadline_ms, or delete the group; §9.2 says so plainly. A hostile co-tenant with ACKNOWLEDGE can still Reject records it was legitimately leased. Sharing a group with a party you would not trust with those verbs means not issuing them: a group shared with an untrusted consumer is a trust decision the owner makes when it issues the grant. Egress has no per-holder scope, and the fairness rule is per connection. max_append_bytes_per_sec is bounded twice, per stream in aggregate, and per holder_signing_key_id across that holder’s sessions (§13). Egress is bounded only the first way: the grant carries no delivered-bytes field, and §11.2’s starvation bound is over the subscriptions on one connection. So a holder with the weakest read verb can open subscriptions across many connections, each inside every stated per-connection bound, and take a share of the stream’s max_delivered_bytes_per_sec proportional to how many it opened. Its co-tenants are slowed, and at §12’s floor a sufficiently slowed consumer’s backlog ages out. The asymmetry is disclosed rather than closed because closing it means a second per-holder rate on the grant and a fairness rule with a scope wider than a connection, and version 2’s answer to a co-tenant that behaves this way is the one §6.2 and §7 give throughout: it is a party the owner issued a grant to, and the remedy is the grant. A producer can evict a consumer’s backlog. §12’s byte bound is reached by appending, and any holder with APPEND can reach it: at the §15 defaults a producer running at its own permitted max_append_bytes_per_sec fills retained_bytes_limit in the seventeen minutes §12 computes, advancing the floor past everything older and transitioning every co-tenant’s non-terminal cycle for that range to EXPIRED. The bound on this is retained_bytes_limit and the grant’s own rate limit, and nothing else. A producer needs no admin verb to do it. A stream shared with an untrusted producer is therefore the same kind of trust decision as a group shared with an untrusted consumer, made at the same moment, and an application that cannot make it gives the producer its own stream. Lane scope does not hide traffic volume. sequence is assigned over the whole stream (§9), so every Appended, every Delivery, the first_retained_sequence in CursorTooOld, and every GetCheckpoint response tells any holder with any lane scope how many records the stream has taken. Three of the four require the holder to act. Delivery does not: it arrives within credit the holder granted once, so a lane-scoped consumer measures the stream’s growth passively for as long as its subscription is open. What the deleted checkpoint push additionally leaked was commit cadence, timing for batches containing no record the holder can see, which no surviving channel carries. §2’s disclosure of what identifiers and volumes are visible is written against the provider; this one is visible to co-tenants as well. Lanes filter delivery and authorization. Tenants who must not measure each other use separate streams.

Rationale

The chain is a governance plane, not a data plane

Version 1 made the broker read finalized chain state on every request and fail closed when that state aged past a bound. The result was a message queue that stopped when the chain stopped, and whose latency and availability were coupled to consensus for decisions, ownership, an admin key, a balance, that change on the order of days. Version 2 keeps those decisions on chain and applies them from a periodically refreshed snapshot, so the data plane’s failure domain is its own store.

The economic unit is the (owner, provider) relationship

This is the change that removed the most machinery. Version 1 put the balance on the stream: every stream carried its own escrow, rate, settlement height, suspension state, and grace deadline, priced across three capacity dimensions admitted through either a signed quote or a genesis-frozen schedule and reserved against four per-provider counters. Moving the balance to the owner removes the per-stream economics but creates three problems: a broker cannot soundly test solvency, because one stream’s dues say nothing about its siblings’ claims on a shared pool; a provider’s collectible is no longer isolated, because a sibling at another provider can drain the pool first; and the rent split has to be distributed over an unbounded set of providers, which makes settlement’s gas unbounded. Keying the account by (owner, provider) fixes all three at once, because it is the scope the economics actually live in. The broker testing solvency is the provider being paid, so it evaluates the same expression over the same fields the chain does. The settlement has one recipient, so its state-I/O is a fixed pair. And a provider’s exposure is bounded by its own cadence rather than by what other providers do. A stream record ends up with no economic state at all, and nine fields, none of them money.

Flat rent, snapshotted per billing run

The rate is a governance parameter, but each account copies it when a run of streams begins and charges every interval of that run at the copy. A change never reprices an elapsed interval and never reprices a run in progress; it reaches an account when the owner next starts one. The two alternative copy points fail in opposite directions. Re-copying at every settlement makes settlement timing worth money, and settlement is permissionless, so a provider could pick the block a rate rise took effect. Copying only at account creation makes the parameter unreachable, because a zero-stream account accrues nothing and can be held forever, so nobody ever takes the repricing path. The transition from 0 to 1 is the only point that is both inside the owner’s control and outside anyone else’s. The same reasoning applied to the provider/platform split gives a different answer: a split is read at settlement too, so a live parameter would be equally retroactive, but unlike the rate it has no natural per-account snapshot point that isn’t just a second copy of the same idea. It became a protocol constant instead, the cheaper fix for the same hazard.

One delivery class, batch checkpoints, no lane proofs

Version 1 specified an at-least-once class and an async-durable class together, signed a receipt per append and per acknowledgement, maintained a global and a per-lane receipt chain, and committed synchronously per record. Version 2 keeps the at-least-once class, commits in batches, and signs one checkpoint per batch, with a contiguity rule so linkage and coverage are the same check. The evidence is coarser and the cost falls by the batch size in signatures and fsyncs. The sparse-Merkle lane commitment addressed the fact that a lane-scoped subscriber cannot check a flat digest. It protected a claim no one can enforce, since v2 has no dispute path, so §10 states the limitation instead of implementing it.

Broker-assigned lane and group ids

A client-chosen nonce hashed into a lane id forced a permanent tombstone set so a closed id could not be recreated with a different history, a bound on that set, a rate limit so one holder could not squat the namespace, and a stall when both bounds filled at once. A monotonic counter the broker assigns makes reuse impossible by construction and retires three of them. The fourth survives re-scoped: §8 and §9.2 both keep a per-stream creation rate limit, because assignment prevents squatting. Creation still requires a durable write under flat rent, so the broker limits its rate. Most of what version 2 removed decomposes the same way. A compensating mechanism has a part that compensated for another choice and a part that does its own work, and only the compensating part goes away. Here the counter replaces the mechanisms that prevented id reuse, and the creation rate limit stays because it bounds writes. §9.2 applies the same counter to group ids and retires the same three, keeps the rate limit, and gains §7’s group_scope = Any requirement, which is the one thing a counter adds, since a holder with a narrow grant could advance the counter until it reached the authorized id.

Rejected alternatives

  • Incrementally fixing version 1 leaves dependencies between the removed mechanisms: quotes exist because rates are per-stream, reservations because quotes do, lane tombstones because lane ids are client-chosen. Removing them one at a time leaves the document inconsistent at every intermediate step.
  • Dropping billing would leave providers to bill off chain. The platform arbitrates ownership, authorization, and payment; a broker with a private customer table is not a Cowboy service.
  • Unmodified Kafka, NATS, or RabbitMQ cannot verify a StreamGrant or enforce a chain-controlled generation.
An existing broker can be adapted instead of writing one from scratch. This third option verifies grants, generations and tenancy, and maps most of §§9–13 onto an existing broker. The mapping must preserve lease semantics, lane ordering, and checkpoint boundaries. No candidate has been evaluated against those three requirements, and no evaluation has ruled this option out. The v2 cbqsd storage engine remains pluggable.
  • Per-request signatures cost a signature and a verification per message and defend against an attacker who, having reached the required position, can already reorder and drop frames.
  • Billing per byte requires trusting a provider-reported counter or putting usage on chain. A flat rate bounded by per-stream ceilings the broker already enforces keeps both off the table.
  • Carrying arrears would let an abandoned account accumulate debt nobody will pay or act on. Revival would cost more the longer the account is left.