Skip to main content
Status: Draft
Type: Standards Track
Category: Core (Store)
Created: 2026-11-04
Requires: CIP-4 (dormancy and auto top-up), CIP-7 (the two-tier feed amendment on companion branch feeds/cip7-amend; its §6.6–§6.9 land with that amendment, not in the page linked here), CIP-10 (the stream workload), CIP-24 (vendor credentials and signing keys), CIP-33 (declarations, hires, ProviderMetered), CIP-43 (the access meter)
Related: CIP-9 (the catalog file)
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.

1. Abstract

Background

Data vendors cover far more series than anyone uses at once.

Goal

A catalog listing is one CIP-33 declaration whose wrapper actor commits a catalog of rows, for example ten thousand market data series. The Store shows every row as its own card. A buyer hires the listing and selects one row under that hire, proving the row against the committed catalog. The wrapper counts funded selections per row on chain. A store-operated stream workload starts a row when it gains its first funded selection, publishes it to a CIP-7 feed bound to that row, and stops it after its last. The workload caps its own publishing and sponsored subscription admission; outside subscriptions to these public feeds are paid by their own payers and remain subject to the chain-wide phase limits.

2. Motivation

Listing each series separately means one declaration, one review and one always-on publisher per series. At ten thousand series that is unworkable for review and for the chain: every publish is an actor call, and every application shares the User lane’s 2,051 charged access units per block; frame throughput must be measured in rollout. The buyer wants to find “SOL price on Solana”, hire it, and have an actor act on it, without caring whether the series was already running.

3. Design Goals

  • One declaration and one review cover the catalog and its generator.
  • Each row is discoverable and hireable as if it were its own listing, and its definition cannot change under a buyer.
  • Work follows funded hires: a row with no funded selection has no vendor traffic and no publishing.
  • The listing’s own publishing and sponsored attaches have stated admission caps; outside subscriptions remain subject to chain-wide limits and reserve no share for the listing.
  • The selection, the row it names and the feed bound to it are authenticated on chain.
  • The store operator bills what it can attribute to a hire, and funds it before it starts: a selection needs a deposit for its worst-case next billing periods, and stops before those run out. Costs it cannot attribute, such as the idle grace, unmatched guard checks and idle feed rent, are covered by margin in the class rate and activation.
  • The workload is an actor plus a CIP-10 workload. Its only private key is a worker signer for shard leases (§6.11.1), which can spend only its own float.

4. Non-goals

  • Exclusive data. A row’s feed is a public CIP-7 feed.
  • Data authenticity beyond the publisher. The store operator signs what its workload observed; buyers trust the store operator for correctness (§8).
  • Every vendor tick on chain. Rows are sampled and coalesced (§6.7).
  • Changes to the CIP-33 hire record or the CIP-7 Feed source.

5. Definitions

  • Wrapper: the actor a catalog listing’s declaration names.
  • Creator account: the account that created the declaration. It commits catalogs and settles usage.
  • Catalog revision: an ordered set of rows identified by a revision number and a Merkle root.
  • Row: one hireable item. Its definition (source identity, class and numeric tag scales) is immutable for its row_id.
  • Selection: the binding of one hire to one row, with an optional guard and subscriber.
  • Consumer owner: the account that owns the subscriber actor. It alone signs ApproveSponsor, SetHandlerAllowance and ResumeSubscription, and it sends and pays for a handler Subscribe (§6.6). It need not be the hirer.
  • Funded: a selection whose hire has spendable headroom reserved − unsettled accrual covering its minimum (§6.3/§6.9).
  • Running row: a row with at least one funded selection, or within its grace period after the last.
  • Access unit: the CIP-43 meter. Lane-charged work has a 4,096-unit block aggregate, separate from the 730-unit OutsideShared pool used by delivery (§6.5).

6. Specification

The key words MUST, MUST NOT, SHOULD and MAY are to be interpreted as described in RFC 2119. Draft amendment status. This text adopts the fixed 190-byte CIP-7 delivery record and the current three-purpose signing model. Delivery scheduling, SDK import admission, signing-target support and catalog rollout remain implementation dependencies. Draft placeholders: final delivery costs/capacity and benchmark evidence; the signing owner’s exact persisted variant names and supported feed-owner/funding targets; feed-address-sharded vendor batch arithmetic; final acceptance evidence. These are not deployment or capacity claims.

6.1 Catalog

A catalog revision is a canonical CBOR file on a public CBFS volume owned by the creator, in pages of at most 1,024 rows sorted by row_id:
definition_hash = SHA256(ASCII("cowboy/catalog/row-definition/v1") || canonical_cbor(definition)). The leaf of a row is SHA256(0x00 || ASCII("cowboy/catalog/row/v1") || canonical_cbor([row_id, definition_hash, title, retired])) and node = SHA256(0x01 || L || R). A single row’s root is its leaf; n > 1 rows split at the largest power of two strictly below n, with no padding. A proof carries the zero-based leaf index, the leaf count and at most 14 bottom-up siblings, with directions derived from the index and count. The creator records a revision with commit_catalog(revision, root, row_count, class_table_hash, volume, path). revision is one more than the last. The wrapper keeps only the latest revision’s root, and a selection proves against it. Because retired is part of each leaf, a row retired in the latest revision cannot be selected with a proof from an older one. A row_id names one definition forever. The wrapper pins a row’s definition_hash when the row’s first selection is funded (§6.3). After that, a proof of that row_id with a different definition rejects with DEFINITION_CHANGED. Title is authenticated by the Merkle leaf: changing it requires a new leaf and catalog revision. Summary may change without changing that leaf; neither changes the pinned row definition. A change to source, class or scales needs a new row_id. Setting retired stops new selections; existing selections run until they end. The Store reads the latest revision, verifies every page against its root, and renders one card per non-retired row. The Store reviews a catalog listing once: its wrapper, its stream workload and its catalog generator. A revision needs no new review unless it adds a class. A class identifier is 1 to 10 bytes of [a-z0-9_], so <class>_block is a valid ProviderMetered unit label of at most 16 bytes (UnitPrice::label_valid in protocol/crates/cowboy-protocol-codec/src/trading_post.rs). A card’s display name is separate from its class identifier. The wrapper stores the class table, which the creator sets with set_class_table on its direct path. commit_catalog carries class_table_hash and rejects a mismatch, and the Store checks that the catalog’s copy matches. So the broker-signed path cannot change a cap or a class. A class’s sample_interval, heartbeat and ring_size cannot change once the class exists, and set_class_table rejects a change with CLASS_CHANGED, because a buyer’s row depends on them. A running-row cap and vendor units can change. A new cadence needs a new class and a new row_id. A new lowercase class id also needs a new billing unit, and so a new version (DeclareVersion). A selection under a hire whose pinned term lacks that unit stays PENDING with reason TERM_LACKS_CLASS.

6.2 Selection

A hirer hires the declaration under CIP-33, then calls the wrapper under that hire:
The wrapper takes the hire from runtime.hire_id(), which the chain sets only when the hirer’s own signed ExecuteActor names an active, in-term hire of this declaration. select and every other hirer method are therefore top-level calls signed by the hirer. The wrapper computes the row’s leaf with the supplied title and retired = false and verifies the proof against the latest revision, which revision MUST name (STALE_REVISION otherwise); it then checks count equals that revision’s row_count, checks definition_hash against the row’s pin if it has one, and records:
selection_id is allocated by the wrapper and never reused. A hire holds at most one live selection. status starts PENDING. selection_revision increments on every change to the selection; revision in commit_catalog and select always names the catalog revision. select creates no row record: an unfunded selection holds only its own definition_hash, so it uses no row capacity. funded_blocks is the wrapper’s own tally of blocks each class spent FUNDED, accumulated on leaving FUNDED as the exit height minus funded_at, with funded_at reset on each new funding. It is an upper bound on billable accrual, not a settled count: §6.9 subtracts STALE and FAILED blocks off chain. The authoritative cumulative counts are the Trading Post channel’s settled_counts for the hire; no wrapper method accepts settlement counts. Skipped intervals are workload-journal and Store disclosures (§6.6), not a wrapper billing field. attach(guard, subscriber, handler, definition) and detach(), under the hire, set or clear the guard, the subscriber and its handler. The wrapper stores only definition_hash, so attach carries the definition and checks it against the pin, and guard MUST validate against its scales. subscriber MUST be one the hirer named with nominate(subscriber) and that has then called accept(selection_id) itself. accept works only for the nominated sender, so no one else can overwrite the consent. A subscriber named in the attach request is not consent, whether it is the hirer, an actor the hirer owns or an allowed caller: the wrapper asks the chain about no address but the sender’s. guard and subscriber are optional: a selection with neither gets no delivery, and its hirer reads the feed. Each change increments selection_revision, separate from both the catalog revision and CIP-7 Resume revision. attach MUST refuse CAPACITY_REACHED when the subscriber would exceed 32 live subscriptions of this listing, counted from the wrapper’s own state. A nonempty handler additionally requires the consumer owner to send and pay for the Subscribe transaction (§6.6); ApproveSponsor, SetHandlerAllowance and wrapper attach/accept consent do not supply that signature. Without it, a sponsor can create only a record-only subscription with handler = "" and reaction = None. The Store preflights the consumer’s sponsor approval and total subscription count before submitting attach; the workload repeats those RPC checks before fund and Subscribe (§6.6). The wrapper cannot read the consumer’s native rows or count subscriptions outside this listing. Native Subscribe remains the authoritative cap. The node already excludes messages at or below the committed start_after; the SDK fix makes the handler’s own paging start there too (§6.6). A selection ends by release() under the hire, or by expire(hire_id, selection_revision) from an admitted workload account. The wrapper cannot read another account’s hire, so the workload reads it from the hire’s Trading Post row and sends expire only for a hire that is no longer Active or is past paid_through. It reads the hire again before it signs, and drops the expire if the hire is active again. selection_revision names the selection the workload read, so an expire queued before the hire reopened and selected again is refused with STALE_REVISION. Anyone else, the hirer included, is refused with UNAUTHORIZED; the hirer ends its own hire with release().

6.3 Funding and admission

The workload moves a selection between PENDING, FUNDED and SUSPENDED with fund(selection_id, selection_revision, definition?) and suspend(selection_id, selection_revision, reason). It funds a selection only when all of these hold, read from one committed state view. Current ingestion reads the latest committed height; a multi-validator rollout requires height-pinned/finalized reads or an agreed lag before claiming finality. Only the holder of shard 0 (§6.11) calls fund. The wrapper enforces the class cap, publish admission cap, listing-local attaches and vendor units from its own counters and class table. Consumer-native approval/count checks below are off-chain workload preflights, not wrapper foreign-storage reads:
  • the selection’s class is enabled in the hire’s pinned term (TERM_LACKS_CLASS otherwise);
  • the hire is valid (renewal_on && reserved ≥ cheapest priced unit), is not closing, and its headroom reserved − unsettled accrual covers FUND_QUANTA times min_funding (§6.10), plus the activation charge (§6.9) for a row with no row record when included in the pinned term;
  • the hirer has fewer than MAX_FUNDED_PER_HIRER funded selections;
  • the selection’s subscriber, if attached, keeps the row within MAX_SUBSCRIPTIONS_PER_ROW and the listing within its delivery budget (§6.5), and passes the workload’s RPC preflight of native sponsor approval and total consumer subscription count (§6.6);
  • the listing’s running rows would stay within the row’s class cap, the listing’s publish admission cap (§6.5) and its vendor budget (§6.7).
If the hire’s headroom does not cover FUND_QUANTA × min_funding plus any due activation charge, an initial selection stays PENDING with reason UNDERFUNDED; an already SUSPENDED selection stays suspended with that reason. The Store shows the reason. Any other failed check also leaves an initial selection PENDING, with that check’s reason; a failed re-funding attempt leaves an already SUSPENDED selection suspended with the reason. The workload settles every quantum (§6.9) and suspends a selection before its headroom falls below min_funding. Funding needs more than suspension does, so a selection is not funded and then suspended at once. A suspended selection is funded again when the deposit is topped up. A PENDING or SUSPENDED selection is not billed and does not keep its row running. A hirer holds at most MAX_PENDING_PER_HIRER PENDING selections. MAX_UNFUNDED_SELECTIONS is an admission threshold for the combined PENDING and SUSPENDED count: select rejects with CAPACITY_REACHED when that count meets or exceeds it. suspend can exceed the threshold, and the live-selection cap still bounds storage. Reaching the threshold blocks new selections, not existing funded ones. A workload account can end a selection that has been PENDING for PENDING_UNDERFUNDED_BLOCKS and whose hire’s headroom is below FUND_QUANTA × min_funding, with reject_pending(selection_id, selection_revision). A selection left PENDING for PENDING_TIMEOUT_BLOCKS can be ended by anyone with expire_pending(selection_id). A selection left SUSPENDED for SUSPENDED_TIMEOUT_BLOCKS, for any reason, can be ended by anyone with expire_suspended(selection_id). A selection record, keyed by hire_id and resolved from selection_id by the paired index pages in §6.10, also holds the hire’s cumulative funded_blocks and activations, so a new select under the same hire reuses an ENDED record, keeps them and still checks MAX_UNFUNDED_SELECTIONS. Settlement monotonicity is enforced by the chain’s channel state, not by these counters. An ENDED record with all counters zero is deleted once every subscription a listing account pays for is unsubscribed and settlement is complete. Any other ENDED record stays until a workload account deletes it with delete_record(hire_id), only after the hire can no longer reopen and the subscriptions a listing account pays for and its final settlement are complete; the wrapper’s state is therefore bounded by its live caps, its row records, its tombstones and the latest catalog root. fund is the only call that creates a row record. For a row with no record, fund creates the record, pins the selection’s definition_hash and records one activation on the selection. The wrapper cannot read the term, so it records this on every such fund, and the workload bills it only when the pinned term includes the unit. The workload settles that optional activation charge with the selection’s next routine quantum settlement (§6.9), or as part of the final statement if the hire starts closing first. It is not settled in the same transaction as fund: counts only rise, so settling first could charge for a fund that failed, and a hire that is not closing keeps its reserved deposit, so the charge stays payable afterwards. If row records are full, fund rejects with CAPACITY_REACHED, nothing is charged, and the selection stays PENDING with that reason. If the row’s pin or tombstone differs from the selection’s definition_hash, fund does not revert: it sets the selection ENDED with reason DEFINITION_CHANGED, with no charge. When a row’s funded count goes from 0 to 1 the wrapper emits RowStarted(row_id). When it goes to 0 the wrapper emits RowIdle(row_id, height), and the row stops after IDLE_GRACE_BLOCKS unless a selection is funded again. The workload then calls stop_row(row_id, idle_revision), which releases the row’s counters once, only if the row’s idle revision matches, it has no funded selection and the grace has elapsed, and emits RowStopped(row_id). Until that call the row counts as running, so the counters can only overstate what runs.

6.4 Row feeds

Each running row publishes to its own CIP-7 CONSENSUS feed. RowStarted(row_id) is the operator’s deployment trigger; until the operator has deployed the feed and an admitted workload account has called bind_feed, the row publishes nothing, is STALE under §6.8 and accrues nothing. A non-static selection whose row has a record but no bound feed shows reason AWAITING_FEED, and the workload MUST NOT report SOURCE_FAILED for it. On a row’s first start the operator deploys the canonical Feed source from the feed owner account (§6.11) with the row’s numeric_tag_scales, the class’s ring_size, the listing’s publisher key, and service_url = "https://<listing host>/rows/<row_id>/<definition_hash hex>". The workload then calls bind_feed(row_id, feed, definition), which checks the definition against the row’s pin. The wrapper accepts the binding only from an admitted workload account and only if the row has a pinned definition and no feed, the feed is bound to no other row, and the address equals derive_actor_address(feed owner, SHA256(row_id), canonical_feed_code_hash, shard = None), and the feed’s get_config shows CONSENSUS, the row’s scales, the listing’s publisher key, owner equal to the wrapper’s feed owner parameter, the class’s ring size and exactly that service_url. Successful bind_feed emits FeedBound(row_id, feed). get_config returns no code hash; the derived address commits the canonical source for these newly deployed row feeds. The fixed salt also makes deployment idempotent after a crash. The binding is permanent, so a row’s identity is committed in its feed’s immutable configuration as well as in the wrapper. Every message on a row feed carries the text tag row equal to row_id. A subscriber MUST check the feed against the wrapper’s binding for its selection, not against the feed’s tags alone. A row’s feed is kept when the row stops; publishing resumes on the same feed when it starts again. A static row points at a feed that already exists and is published by someone else, for example an outside publisher’s feed. Its definition carries static_feed (the address), static_deployer, static_salt and optional static_shard (which reproduce its address with the canonical source’s Keccak-256 hash), static_identity_hash, max_silence_ms and static_max_publishes_per_hour, a limit on how many of its messages a subscription checks in an aligned 3,600-block window. static_identity_hash is SHA-256 of the canonical CBOR of the feed’s immutable configuration fields only: chain_id, chain_instance_id, stream_id, owner, feed_class, numeric_tag_scales, ring_buffer_capacity and service_url. It excludes publisher_key, usage_key and generation, which key rotation changes, and the mutable usage fields. The catalog generator MUST check the static Feed’s actual code hash over RPC at catalog build and refuse non-canonical code. Until an actor code-hash host call exists, the wrapper cannot repeat that code-hash check. Uniqueness of static_feed across the catalog is a catalog-generator invariant that the Store checks at review; the wrapper has no feed-to-row index enforcing it. It binds the row inside first fund, checks its address/stream identity, CONSENSUS and that the immutable fields from get_config hash to static_identity_hash; the service_url, scale and publisher-key checks above do not apply. A static row is always on: it counts toward billing and delivery, not toward the publish admission cap or the vendor budget, and its messages need not carry row, observed_ms or sampled_ms (§6.8). A key rotation on the feed changes neither the hash nor the row’s definition, so selections continue and new ones are admitted across rotations. Consensus subscribers consume the bound feed’s canonical retained ring. Feed publish verifies new envelopes against the current publisher key; a key rotation does not invalidate retained messages admitted under an earlier generation. The feed owner pays each row feed’s rent through auto top-up (§6.11), and the class rate plus any activation charge included in the pinned term cover it. Auto top-up is off for a collected row, so its feed can go dormant after CIP-4’s unpaid epochs. Restoring it needs the complete pre-eviction storage and pays its rent debt, so the operator does it on its direct path, from an archive it keeps, before the row restarts. Without one, the creator retires the row, and a new row_id takes its place. A row with no FUNDED or SUSPENDED selection for RETIRED_FEED_BLOCKS can be collected by anyone with collect_row(row_id), which replaces its row record with a tombstone {SHA256(row_id), definition_hash, feed} of 84 bytes, packed 128 to a page. The operator also freezes the feed of a collected row that the latest catalog marks retired, with freeze_publishing. A later select of that row_id checks the tombstone exactly as it would the record, so the definition stays pinned after the record is gone. Funding a selection of a collected row removes its tombstone, restores the record with the same pin and feed, and charges activation again when included in the pinned term; bind_feed never creates a record. If the feed is frozen, the operator first calls rotate_keys with the named keys, because only a rotation unfreezes a feed. The wrapper holds at most MAX_TOMBSTONES; when they are full, retired rows keep their records and stop being collected, and once row records are also full, new rows cannot be bound. The guarantee that a row_id names one definition forever therefore holds for the wrapper’s life, enforced by records and tombstones together.

6.5 Chain budget

All lane-charged chain work shares a block aggregate of 4,096 access units (BLOCK_AGGREGATE_ACCESS_CEILING). Delivery draws from the separate 730-unit OutsideShared pool, which the aggregate is already net of. The phase holds no transaction-lane reservation; subscription escrow pays its metered checks. The User lane holds 2,051 charged units. A publish includes at least one Python frame (structural tariff 99 before scalar, envelope and publish work); throughput is measured in rollout, not eleven calls per second. Block-start hold reclamation does not raise the User lane constant. An uncached native checked subscription costs 1 subscription read + 3 for a record touch = 4 structural units, match or miss; this is the per-subscription preflight bound and cached rows within one pass can cost less, before shared queue/cursor/index/settlement overhead. Reactions add 7; an untracked handler’s run-row touch adds 3. Python runs separately, at most 3 runs minted chain-wide per block, at fixed limits of 200 accesses / 5M cycles / 256 KiB of cells, with 16 matches and a page budget enforced by the SDK. Final phase capacity depends on the handler reserve, FeedIndex rewrites and benchmark results. Draft placeholder — final costs/capacity: insert those measurements after the delivery and settlement changes and production-zygote acceptance benchmark. The creator declares:
  • publish_budget: the listing’s sustained publish admission/pacing cap, initially 2 publishes per block (2 per second at the 1-second floor); this reserves no chain lane;
  • delivery_budget: the admission cap on the listing’s own attached delivery work, initially 0 until delivery, handler-run and SDK module gates are active, then at most 60 record-equivalents per block under the configured rate model. At the base 4-unit step, 60 is about 240 structural units before additional overhead, not a guaranteed chain allocation. The step cost is not a throughput figure: one measured publish to a full Feed of 1,024 record-only subscriptions, on one validator with no other traffic, reached about 5 records a block. Admission numbers MUST come from measured throughput, not from dividing the phase by the step cost.
For every running non-static row, publish admission holds its heartbeat rate plus its full edge allowance:
These cadences are in blocks; the 1-second minimum block interval is a floor, not a fixed clock. Wall-clock projections MUST be measured before pricing or rollout. Attach and fund MUST both check the sum of attached subscriptions times maximum publish rate, including a declared conservative rate for static rows. The wrapper applies this check at attach in every selection status, so at a delivery_budget of 0 it refuses every attach that names a subscriber. This cap bounds admitted load, not live load: an owner-paid subscription can outlive its attachment and an outside subscription never had one, so only the chain’s limits bound those. Such static rows do not consume the listing’s publishing/vendor budget, but they do consume its delivery cap. Admission assumes every check matches. The delivery phase gets the OutsideShared remainder up to 600 units, which can be 0 in a saturated block. delivery_budget reserves none of it. If the phase had no usable budget, delivery resumes at the Feed’s next publish. There is no bounded-block eventual-execution guarantee. One listing’s matching subscriptions can occupy every handler run for a stretch; FIFO scheduling and a three-run cap do not promise other applications a share. A full-scale rollout measures delivery throughput and competing traffic before raising either admission cap.

6.6 Delivery

This CIP depends on the record model on companion CIP-7 branch feeds/cip7-amend; the numbered §6.6–§6.9 references resolve when that amendment lands. The linked main CIP-7 page does not yet contain those sections. Each subscription has ONE fixed 190-byte delivery record with last_sequence, matches, missed, rate_limited, revision, start cursor and escrow. The node overwrites that summary, rather than appending inbox entries. A later handler pages the Feed ring from its own cursor, rechecks its guard and commits effects with cip7/processed/<id> (8-byte big-endian sequence). This is guest progress, not a processed-match billing counter. Draft placeholder — core enforcement. The consumer-owner signature on a nonempty-handler Subscribe and the owner-or-payer FundSubscription check are required core changes; the final pass confirms them against the landed code. Until both checks land, this listing’s delivery_budget MUST remain 0. Subscribing. A subscription has one of two paths, by the selection’s handler. With an empty handler, the row’s shard submits a record-only Subscribe after attach on a funded selection. With a nonempty handler, the consumer owner sends and pays for Subscribe directly, through the Store. The workload never signs a handler Subscribe. The check window starts at height − height % 3600; it is not a wall-clock hour. The consumer owner sets the per-consumer allowance across all subscriptions. A nonempty handler or any reaction requires that owner’s signature on Subscribe. Sponsor approval and the allowance alone are insufficient. A sponsor acting alone can create only an explicitly selected record-only subscription with an empty handler and no reaction. The consumer owner approves that payer with ApproveSponsor { consumer, sponsor, max_subscriptions, expires_at }, naming the row shard’s admitted submitter account, which get_parameters() exposes per shard from admit_workload_account. The sponsor row (sponsor_key) and total subscription count (consumer_meta_key) live in the consumer’s own KV, which the wrapper cannot read through the actor storage API. Both are read with GET /actors/{consumer}/storage/value; expires_at is a block height, and a revoked row reads as present with zero values. For a record-only subscription, before submitting attach, the Store MUST read both over RPC and refuse delivery setup with NOT_CONSENTED unless the approval names the row shard’s admitted submitter, active < max_subscriptions, expiry extends beyond the proposed funding horizon, and the consumer holds fewer than 32 native subscriptions. A direct wrapper attach only records the request and enforces its listing-local cap; it does not authenticate those external facts, and the Store shows delivery as unconsented until preflight succeeds. The workload MUST repeat both RPC checks before fund and before a record-only Subscribe. A handler selection needs no sponsor approval: fund requires only that the consumer holds fewer than 32 subscriptions or already holds its own. A failed preflight MUST prevent submission of the corresponding operation and show delivery as unconsented with reason NOT_CONSENTED. Before fund, the selection remains in its existing PENDING or SUSPENDED state. Before Subscribe, an already FUNDED selection remains subject to the billing and suspension rules in §§6.3 and 6.9; withholding Subscribe does not itself undo funding. A funded handler selection with no owner subscription yet shows as awaiting its owner on the workload’s status, and it bills while it waits, as the card MUST disclose. The workload finds the owner’s subscription from the consumer’s meta, sub/<id> and record/<id> rows. Native Subscribe remains authoritative if state changes afterward: once the required core changes above land, it checks the required signatures, sponsor approval/count/expiry where applicable, and total consumer count at its execution height, not the listing’s funding horizon. The consumer, then its owner, pays Python runs; the allowance is a cap, not a payer. No allowance means no handler execution, but the fixed delivery record can still advance and the ring can overwrite unread messages. The SDK’s start_after handling, subscription-row guard and 16-match/page cap are required before enabling delivery. Attach records its requested start and the workload journals the confirmed subscription and any skipped interval. Messages between attach and Subscribe are not backfilled. Replacing or detaching has the old subscription’s recorded payer send Unsubscribe before creating another, and the listing does this only for subscriptions it pays for. An owner-paid subscription stays open until its owner ends it, so it can outlive the hire, and the listing cannot top it up. The card MUST disclose that the owner pays for its checks, and the Store shows the escrow remaining. Unsubscribe returns the remaining escrow to its payer; the guest progress cursor is not a durable node billing counter. The wrapper MUST NOT rely on record_subscription, clear_subscriptions or archived_processed as existing authenticated billing APIs. Hirer contract. Runs are per (consumer, subscription), FIFO by due time, with no block latency bound. Ring overwrite yields an exact lost range. An increase in missed or rate_limited yields one conservative gap (processed_through, first delivered match) with delta counts before messages; the range can include sequences that were not lost. There is no 256-entry inbox or inbox-full gap. Exhaustion needs Resume signed by the consumer owner; a rate-limited subscription returns automatically at the next aligned window. A failed consensus handler run is re-minted while its consecutive failure count is below HANDLER_FAILURE_LIMIT; 3 consecutive failed attempts park scheduling until the consumer owner sends Resume. Draft placeholder — core enforcement: a live-chain run of the amended CIP-7 code found failed runs re-minted without counting failures, and the per-run hold not refunded; the owner-paid handler path depends on this rule landing. A successful call with no progress counts toward that same limit. The required target for an attempt whose child never executes is to clear its fence at expiry, refund its hold on an allowance-epoch match and re-queue without increasing failures; the earlier core snapshot increments failures at expiry and must not define this rule. This is separate from the runner tier’s completed-request/no-retry rule in CIP-7. Row billing can continue while subscriber delivery is unavailable, as the card MUST disclose. Recovery and suspension. Only the consumer owner or the recorded subscription payer may top up (required core change above) with FundSubscription { consumer, subscription_id, amount }. Top-up never changes the payer, and all remaining escrow is refunded to that recorded payer, including owner-funded amounts; funding alone does not clear PAYER_EXHAUSTED. The workload keeps listing-paid escrow at or above two windows of worst-case steps at the live fee. The workload’s status lists subscriptions that need the consumer owner’s Resume, read from chain state, and the Store presents them to that account, even when it is a third party. A record-only subscription can instead be replaced by its recorded payer, with the gap journaled; on a nearly full Feed the listing keeps the slot and asks for Resume. Resume preserves any in-flight run hold/fence, and the node acknowledges only committed guest progress. A Resume with no explicit start_after sets the record’s start to the Feed head, so the consumer owner SHOULD pass the subscriber’s own cip7/processed/<id> sequence to keep the backlog due. An explicit cursor advance skips that backlog in addition to ring loss and missed/rate-limited gaps; the card MUST disclose that effect. On suspension the workload may allow at most UNSUBSCRIBE_DRAIN_BLOCKS of best-effort drain, then has the recorded payer send Unsubscribe for a subscription the listing pays for; it must not claim to read another actor’s guest storage through a nonexistent host call. Delivery is uncharged and its unit is omitted from the declared term and settlement count vector under §6.9. Not adopted (N14). This CIP uses no node-attested processed count, no RecoverSubscription and no SetFeedPayerPolicy. Delivery is uncharged, so nothing needs the count. A handler’s payer is its owner, so Resume is its recovery. The normative progress model above remains the guest-written CIP-7 cursor. A payer restriction can be reconsidered if griefing appears or guaranteed slots become a requirement; it would be mutable and owner-controlled, because a shard’s submitter can change and handler payers are not known in advance. Open — atomicity (question 2). Whether any reactions require atomicity with a publish remains undecided. End-of-block delivery is not atomic with publication; a proposer may place another transaction after a publish and before the phase. The card MUST disclose that public row feeds accept outside subscriptions up to 1,024 slots: 32 consumers with 32 subscriptions can fill the limit and block hirers while class billing continues. The base implementation accepts zero escrow; the delivery amendment requires minimum escrow on Subscribe/Resume, which raises cost but does not remove this limit attack. The workload reads the Feed’s index before fund and leaves the selection PENDING with CAPACITY_REACHED when the Feed is full. Reading feeds remains public.

6.7 Sampling and publishing

The workload samples each running row from the vendor at its class’s sample_interval. A sample carries the vendor’s observation time. Publishing is coalesced:
  • Heartbeat: a row publishes its latest sample every heartbeat of its class.
  • Guard edge: when a sample satisfies an attached guard that the previous sample did not, the row publishes that sample if the row has edge allowance left (at most MAX_EDGE_PUBLISHES_PER_HOUR in any 3,600 blocks, reserved in §6.5), and otherwise at its next heartbeat. One selection’s guard can use at most MAX_EDGES_PER_SELECTION_PER_HOUR of that allowance, so one selection cannot use it all; one hirer can hold several selections and consume the row’s full allowance. An edge publish is not separately billed in this amendment (§6.9); its cost belongs in the class rate. Any later edge billing is a separate decision and cannot define today’s funding or signing caps.
Pacing. Each shard’s holder paces every publish at its running rows’ share of publish_budget, with no burst and with heartbeats first, so the listing stays within publish_budget over every 60-block window. An edge that finds no capacity waits in the journal, coalesced per row to its latest sample. So edges are prompt when capacity is free and queue when it is not: if all 525 standard rows fire together, the queue takes at most about 420 blocks to drain (seven minutes at the 1-second floor: the initial 20 fast/525 standard rows’ heartbeats take 45 of each 60-block window’s 120 publishes, leaving 75 for edges). It drains sooner when a heartbeat carries a crossing, because that row then needs no edge slot. A shard with no running rows has an even split of the budget, for work it left in flight only, so the shares can pass the budget by that much. The semantics are sampled and level-checked on published messages: a subscriber is delivered every published message on which its guard holds. A condition that starts and ends between two samples is not seen. A crossing can also be missed after it is sampled: a heartbeat or queued edge carries only the latest sample, so if a deferred condition has ended by then, no message shows it. The row sets the text tag coalesced on such a message, and the card states this. The workload persists each pending edge publish in its journal before it signs, so a crash does not lose the latest one. Messages carry the row’s values as numeric tags at the declared scales, the numeric tag observed_ms, the vendor’s observation time, and the numeric tag sampled_ms, the time the workload last got a valid response from the vendor for this row. A heartbeat whose sample has not changed carries the same observed_ms. A value the vendor did not return is omitted. A leaf predicate naming that missing tag evaluates false; compound guards retain CIP-7’s normal not/all/any semantics. The card shows the value as unavailable. Conversion from vendor floats or strings to fixed point uses the shortest decimal representation of the vendor value, rounds toward zero, and sets the tag precision_loss when it rounds. Each listing also declares a vendor budget: the vendor’s metered units it may spend per month, with a class table giving each class’s units per running row per month at its sample_interval. The workload funds a selection only if Σ over classes (running rows × units per row per month) plus fixed costs (catalog generation, metric refresh) stays at or below the vendor budget, and it projects month-to-date spend each hour and stops funding new selections when the projection reaches it. The vendor budget is the admission limit itself, set below the vendor plan’s allowance to leave headroom. Selections refused by the class running-row cap use CLASS_CAP; projected vendor-budget exhaustion uses VENDOR_QUOTA. Both remain PENDING, with the actual reason shown.

6.8 Health

A non-static row with a record but no bound feed is STALE, shows AWAITING_FEED, accrues nothing and does not enter the source-failure/parking path until bound. A non-static running row with a bound feed is LIVE while 0 <= block.timestamp_ms - last_sampled_ms <= health_silence_ms for its class; a static row uses its declared max_silence_ms against its last message timestamp. A row is STALE otherwise, and FAILED after FAILED_AFTER_BLOCKS of STALE. Each class’s health_silence_ms MUST be set explicitly before finalization; a block-count heartbeat is not a millisecond threshold. The Store derives the state from the feed and shows it on the card. Billing accrues only while LIVE. A vendor response that omits the row is not valid. So a quiet market stays LIVE, and the card shows the age of observed_ms separately. A row publishes only fresh valid samples, and its first recovered sample returns it to LIVE. The workload retries a failing source with backoff capped at one heartbeat and alerts its operator on STALE. A FAILED row keeps its selections FUNDED and its subscriptions in place, accrues nothing, and returns to LIVE by itself when the source recovers, so a short outage needs no per-selection transactions. After FAILED_PARK_BLOCKS the workload suspends its selections with reason SOURCE_FAILED, which frees its caps and vendor spend. It then probes the source every FAILED_PROBE_BLOCKS and funds them again when the source recovers, unless they expired. Its hirers can release at any time, and the creator can retire the row. The workload chooses what it reports here, as with all row data (§8). Draft placeholder — class health thresholds. Supply explicit per-class health_silence_ms values before finalization; none are inferred from heartbeat blocks.

6.9 Billing

The term is ProviderMetered with one <class>_block unit per enabled class (one per block a funded selection’s row is LIVE). The delivery unit is omitted until an authenticated delivery meter is approved and implemented. activation, when the pinned term includes it, pays for creating a row record and any feed deployment; it is not refundable. A workload guard match is not proof of delivery and MUST NOT be charged as any per-delivery or per-match unit. The guest cip7/processed/<id> sequence cannot measure processed matches, survives on the consumer rather than as a node counter, and cannot be read by the wrapper through an existing cross-actor storage host call. Therefore delivery MUST NOT be charged, and the delivery unit MUST be omitted from the declared term and settlement count vector until a concrete authenticated billing meter is approved and implemented; core rejects zero-priced units. The proposed meter in Open (N14) is not adopted by this text. No archived_processed or processed-count-clear path is normative. edge_publish is open and excluded from funding arithmetic and signing caps. Publishing its edge is still paced and admission-bounded. A term has at most 8 units with labels at most 16 bytes; the allowable class count follows the units actually enabled, not a five-class assumption derived from unresolved edge billing. Prices are pinned at hire. Activation and class pricing require measured operator cost. A selection accrues from its funded_at height to the first of release, expiry, suspension, the hire starting to close, or end of term, minus STALE and FAILED blocks. Counts are cumulative per hire and integer. The workload settles each hire at least every BILLING_QUANTUM_BLOCKS; the quantum is also the unit of min_funding. This is the only debit path: chain costs (publishes, delivery records, wrapper calls) are paid by the store operator’s accounts and recovered through these units. A subscriber’s handler runs are paid by the consumer, then its owner, within the consumer’s handler allowance, and are not billed by the listing. Closing a hire. Turning off renewal or revoking the hire starts a 600-block close window (core per_call.rs). An accepted ProviderMetered settlement during that window is final: it releases the rest of reserved, even at zero increase, and the hirer can withdraw it at once. A further charge then needs the hirer to deposit again or reopen the hire. After the window the hirer can withdraw the rest. So the workload’s shard 0 holder:
  1. reads each funded hire’s close state at least every CLOSE_POLL_BLOCKS, and before it signs any settlement;
  2. on a closing hire, calls expire, has the recorded payer account of each subscription the listing pays for send Unsubscribe (core accepts it only from that account or the consumer owner), and then settles those counts once, as the final statement. An owner-paid subscription does not hold this up;
  3. never sends a routine settlement for a closing hire.
A routine settlement that was already signed can still land just after a close begins, and that forfeits usage since its counts. Usage is also lost if billing is down for the whole window. The operator bears both, and each is bounded by what accrues between settlements or during the window. Settlement limit. A settlement above reserved is rejected whole, and counts can only rise. So when usage exceeds reserved, the workload clamps the count increments above the last settled counts, in the term’s order, so that their total price fits. It then suspends the selection and has it unsubscribed. It journals the clamped counts as its own, so recovery and a later top-up cannot bill the waived usage. If renewal is off or reserved falls below the cheapest priced unit, the hire is invalid, expire can end the selection, and a top-up then needs a new select. Revenue and floats. Settlement pays the hire’s split, which includes any store’s share. It does not refill the accounts that pay gas. The operator moves funds to the submitter and feed owner floats on its direct path, and the workload has no path to do this (§6.11). A listing’s prices are pinned at hire, so a rise in basefee reduces its margin on existing hires. The listing can stop funding new selections, but it bears that risk on existing ones.

6.10 Parameters

Class parameters (sample_interval, heartbeat, health_silence_ms, ring_size, running-row cap, vendor units per row per month) are set per listing in the class table, committed with the revision. Prices live in the version’s ProviderMetered term and are pinned at hire. The wrapper is an ordinary actor, so its state must fit the actor limits: at most 10,000 keys, 8 MiB in total and 64 KiB per value (core types/src/constants.rs, protocol/crates/cowboy-protocol-types/src/params.rs). Its layout is: The per-row byte figures are layout estimates, not a measured total. The bound counts every row above; maxima in this table are not all reached together. It stays within the 10,000-key / 8-MiB limits. Tests at caps MUST include key bytes, CBOR framing, maximum guards and index entries. select rejects with CAPACITY_REACHED at the selection-record cap or MAX_UNFUNDED_SELECTIONS, a row with no record waits for capacity as §6.3 states, and an ENDED selection’s record is deleted after its final settlement. Both caps are above what the first listing can run under its publish admission cap and vendor budget.

6.11 Authority and signing

The creator account is dedicated to the listing. The publisher, feed owner, creator and shard submitter keys remain CIP-24 secrets. The broker signs typed operations and never releases these private keys to the workload. The persisted grant adds three signing purposes under WORKLOAD_SIGNING_PURPOSES_ACTIVATION_HEIGHT, together with the manifest’s workload.sign entitlement. The entitlement allowlists purposes, publisher keys, signing targets and transaction fee caps. The gate is new and NOT_SCHEDULED everywhere. Existing EgressInject/WebhookVerify purposes retain their encoding and behavior below it. See the CIP-24 signing amendment. The three purposes below are persisted variants of WorkloadReleasePurpose. Tag 5 and above are refused. There is no feed-owner purpose. A submit target is one of 0x<40 lowercase hex>.<identifier>, feed.publish, feed.subscribe, feed.fund_subscription or feed.unsubscribe. A creator target is 0x<40 lowercase hex>.<identifier> or trading_post.settle_metered. <identifier> starts with an ASCII letter or _, continues with ASCII letters, digits or _, and is at most 64 bytes. The broker narrows the generic form: on a submit target, to publish on the Feed and to the listed workload methods of the service actor; on a creator target, to commit_catalog on the service actor. Any other target string is refused, including feed.deploy, feed.set_auto_top_up, feed.freeze_publishing, feed.rotate_keys and feed.resume. Feed-owner operations, including deployment, auto-top-up, freeze and key rotation, MUST remain on the operator’s direct path until listing-specific checks are implemented and verified. Generic support for a SubmitTransaction target proves only its actor/handler allowlist membership, not its payload restrictions or wrapper state. Adding a category here does not create a core purpose. Subscription signing is two dependencies: consensus feed.subscribe grammar under the signing gate, then the broker codec/call path after feed subscription support is available. A sponsor-only Subscribe MUST carry an empty handler and no reaction, and payer MUST equal sender. The broker refuses a Subscribe with a nonempty handler: its owner sends that transaction directly (§6.6). FundSubscription MUST accept only the consumer owner or the recorded payer (required core change, §6.6); refunds already go to that payer. Only the consumer owner can sign Resume, which remains on that account’s path; payer top-up cannot replace it. Generic feed.publish and listed 0x<feed>.publish targets MUST both run the broker’s publish-envelope validation, with the same identity/key/signature checks. The broker maintains per-attempt signed-head history; a fresh attempt starts without an on-chain head read. The canonical Feed’s on-chain follows check is the backstop for a gap/fork. The broker cannot read the wrapper’s row-to-feed binding: it checks chain, stream id, shard fence and within-attempt continuity; the on-chain bind_feed relation is the binding backstop. A valid signature does not prove row membership or data correctness. Settlement limit. The broker checks allowed targets and count-vector length; it does not enforce an elapsed-block or per-unit accrual bound. Core enforces monotone cumulative counts and refuses settlement above the hire’s reserved amount. The hire reservation is the enforceable financial bound. A compromised workload can over-report up to it. It cannot claim a stronger bound from the wrapper’s guest progress cursor. The signing policy also refuses settlement of the operator hire, of another declaration’s hire and of a term with a delivery unit. These checks read listing state proven from the finalized state that also proves the shard leases, at one height per decision: the wrapper’s parameter record (w/params, for the declaration, the operator hire and the escrow limit) and the hire’s Trading Post row. An unproven or mixed-height read refuses. The broker does not read the hire’s standing (status, renewal or reservation); core enforces it at settlement. The operator refills submitter/feed-owner floats directly. The workload’s worker signer can only claim/renew leases, and holds no publishing or creator key.

6.11.1 Shards and leases

The wrapper is the service actor, so it holds the rows core proves, written with storage.set_raw in their exact encodings: the 5-byte ShardConfigV1 at cowboy/shard-config/v1 and a 113-byte ShardLeaseV1 at cowboy/shard-lease/v1/<shard_id>, by compare-and-set on fence_epoch. The creator sets the configuration once, with set_shard_config. Derive each row’s Feed address first. Its publish-signing shard is u32_be(SHA256(feed_address)[0..4]) % shard_count, across the configured shards, including shard 0. This is not a hash of row_id into a class range. Creator signing and listing-wide work use shard 0; submitter signing requires a current lease. A row’s publish shard holder samples and publishes it. Draft placeholder — shard arithmetic: recompute partially filled vendor batches and monthly units from the derived feed-address distribution; one full batch per class is not assumed. An instance claims a free or expired shard with claim_lease(shard_id, expected_fence_epoch, workload_id, workload_generation, attempt, routing_revision), which increments fence_epoch and records the sender as worker_signer. Only that signer renews, every LEASE_RENEW_BLOCKS, with renew_lease(shard_id, fence_epoch), or reclaims its unexpired lease with a new attempt, so a rollout does not wait for expiry. An expired lease needs a new claim. Each write sets expires_at_height to LEASE_BLOCKS past the current height. Core refuses a release without a fence once a shard configuration exists, so the broker cannot sign a claim. Each instance therefore holds a worker signer, a key the host profile provides as a private input, with a small float. The creator admits it with admit_worker_signer. A worker signer can only claim and renew leases. Operational methods need a submitter account, and fund needs shard 0’s. A stolen worker signer can disturb leases, but it cannot publish or move other funds, because a release also needs the live attempt of the registered workload and an approved image. A lease stops admitting new operations 360 blocks before expiry (core SHARD_LEASE_STOP_MARGIN_BLOCKS). A crashed holder’s shard is therefore idle for at most LEASE_BLOCKS, its rows can go STALE and stop accruing, and this is shorter than FAILED_AFTER_BLOCKS.

6.11.2 Chain path and nonces

Every broker operation needs a fence once shards exist, so an instance with no lease cannot use the broker to read a lease or submit a claim. The workload therefore reaches one operator-chosen RPC endpoint through a named egress destination in the host profile, not through the broker, for chain reads and submission. It holds no credential for it. The host profile also supplies workload_id; the instance reads its attempt from the registry. Vendor traffic still goes through the broker. The broker today offers only fetch, verify_secret and ws_connect, so the signing purposes also need a broker signing operation, which returns signed bytes for the workload to submit. Each shard has exactly one submitter account, enforced by admit_workload_account, so its nonce has one owner. The creator account belongs to shard 0; feed-owner operations remain on the operator direct path until listing-specific checks are implemented and verified (§6.11). A new lease holder reads the account’s nonce from finalized state before it signs. A transaction signed by the old holder can still land; §6.12 says what bounds each one. Operator hire. Workload release needs a live hire and a grant that names it (core authorize_workload_release). The listing’s keys and vendor credentials belong to no customer, so the creator holds one direct hire of its own listing, the operator hire, and every grant for these secrets names that hire, the wrapper as service actor and one tenant slot named in the parameters. The wrapper’s operator_hire_id parameter records it. A ProviderMetered hire is valid while renewal_on is true and reserved covers the cheapest unit, so the operator hire needs no renewal while it stays unsettled. The rules are:
  • select rejects under the operator hire, so it holds no selection and uses no capacity.
  • The listing-specific creator signing policy MUST refuse settlement of the operator hire before rollout. The generic broker target/count checks do not establish this refusal today; it remains an acceptance dependency.
  • The hire has no grant_id, so no store can pause or revoke it. Only the creator can; core allows this for direct ProviderMetered hires, although CIP-33 lists only Free and PerCall.
  • The operator profile sizes the per-tenant limits for the listing’s whole signing and vendor rate, because all of it runs in one tenant slot. These secrets set tee_required = false.
  • The operator alerts when the hire stops being valid. An invalid hire blocks further secret releases. The broker MUST recheck hire validity during open vendor sessions and close them when invalid; acceptance must verify this behavior before rollout. Transactions signed earlier can still execute.
  • During an outage, non-static rows stop accruing when they go STALE, and static rows can stay LIVE. Usage unsettled on hires whose close window ends during the outage is lost. No chain state is lost.
  • To recover, the operator resumes a paused hire, or calls set_renewal(true) within the close window. Otherwise it creates a new operator hire, writes new grants and updates operator_hire_id, on the path that creator administration uses.
  • A new declaration version does not invalidate the hire. A replacement wrapper needs a matching hire, workload and grants. A new workload image needs approval in each grant.
Feed owner. A Feed’s owner is the account that deployed it, and it cannot change (feed.py init). So a listing deploys every row feed from one dedicated feed owner account, separate from the submitter accounts, and keeps that key for the life of its feeds. To rotate keys, the creator names the new publisher and usage keys in the wrapper’s parameters, and the operator calls rotate_keys on each bound feed. Automated rotation requires verified checks that bind the replacement keys to the creator’s parameters; until then the operator rotates keys directly. Creator administration. The broker never signs set_parameters, set_class_table, set_shard_config, admit_workload_account, remove_workload_account, admit_worker_signer, remove_worker_signer, DeclareVersion or SetWorkloadSecretGrant. The operator signs these directly, on a path outside any workload. Bootstrap therefore runs in this order, before any workload starts: deploy the wrapper, declare the version, store the keys as CIP-24 secrets, register the workload, create the operator hire, write the grants that name it, fund the floats, set parameters and the class table, set the shard configuration, and admit the workload accounts and worker signers.

6.12 Crash safety

Each instance keeps a durable outbox in its CBQS journal. Before signing, it records the intent: the row, the next sequence and the payload, or the wrapper call with its applicable identity and revision, or the settlement counts, or the CIP-7 subscription action. After signing it records the signed bytes and hash, then submits, then records the receipt. A new lease owner replays the outbox from the journal: it reads the feed head and resubmits an identical envelope when the head is below it (a duplicate publish is an idempotent success), resubmits an unresolved wrapper call with the appropriate guard (selection_revision for selection mutations, catalog revision for catalog commits, and row identity/idle revision for row operations), and resumes settlement from the larger of its counts and the chain’s. Feed deployment and every other feed-owner operation are outside the workload outbox: the operator signs them on its direct path (§6.11), so moving a workload lease cannot replay a deployment. A transaction signed before a lease moved can still land; publishes, settlement and wrapper calls are idempotent or reject as stale, so they cannot double-publish a sequence, double-bill or move a selection backwards. A record-only Subscribe signed again at a later nonce is neither: it creates another subscription. The journal removes honest duplicates. For a compromised workload, sponsor approval, the 32 and 1,024 slot limits, the per-operation escrow limit and the operator’s float bound the loss, and refunds go only to the recorded payer.

6.13 Interfaces

Events: CatalogCommitted(revision, root, row_count), Selected(selection_id, hire_id, row_id), SelectionChanged(selection_id, selection_revision, status), RowStarted(row_id), RowIdle(row_id, height), RowStopped(row_id), FeedBound(row_id, feed). Selection state reasons, independent of status: TERM_LACKS_CLASS, CLASS_CAP, VENDOR_QUOTA, SOURCE_FAILED, AWAITING_FEED, NOT_CONSENTED, UNDERFUNDED, DEFINITION_CHANGED, CAPACITY_REACHED. These are state reasons, separate from call errors. Errors: NOT_HIRED, ALREADY_SELECTED, INVALID_PROOF, DEFINITION_CHANGED, GUARD_INVALID, CLASS_CHANGED, NOT_CONSENTED, NOT_LAPSED, STALE_REVISION, UNAUTHORIZED, CAPACITY_REACHED.

6.14 Upgrades and rollback

  • Wrapper. A declaration’s actor is fixed. A wrapper whose manifest declares sys.upgrade can upgrade in place with upgrade_self, which keeps its hires. Otherwise a new wrapper is a new declaration and a new listing, and hirers of the old one stay on it until they release. A new wrapper can bind an old row feed only if the owner, row identity, code hash, service_url, scales, ring size and publisher key all match, and only after the old listing’s row has stopped, because two listings cannot publish one feed. It needs its own operator hire, workload registration and grants (§6.11).
  • Version. A new version can add classes and prices. Existing hires keep their pinned term (§6.1).
  • Workload image. Any image change, rollback included, needs UpdateWorkload, a restart and new lease claims. A new image also needs approval in each grant.
  • Feed source. A change to the canonical Feed source changes its code hash and retires live feeds (CIP-7). Bindings are permanent, so each affected row needs a new row_id and a new feed, and hirers select again.
  • Keys. The creator names new publisher and usage keys, and the operator rotates each bound feed directly until listing-specific signing checks are verified (§6.11). A submitter key changes by removing the shard’s account and admitting a new one, because each shard has exactly one. Each affected consumer owner must approve the new account as sponsor before new attaches on that shard; existing subscriptions keep their recorded payer. The replaced submitter account MUST stay available for signing until its existing subscriptions are unsubscribed: core accepts Unsubscribe only from the recorded payer or the consumer owner. Otherwise the replacement cannot unsubscribe those rows; they may become PAYER_EXHAUSTED and remain until the recorded payer or consumer owner unsubscribes. The feed owner key cannot change for an existing feed, so losing it stops rotation and freezing on all feeds.
  • Activation gates. The signing and delivery gates cannot be rolled back once active. Without the signing gate rows cannot publish. Without delivery, handler-run and SDK module gates together, rows can publish and serve readers but delivery_budget stays 0; FEED_DELIVERY alone writes records, not subscriber Python.
  • Stuck listing. The creator can stop new selections by retiring rows or by setting caps to zero. Existing hirers can release at any time, and they recover unused deposit after a close: at the final settlement or after 600 blocks.

7. Rationale

Ten thousand declarations would need ten thousand reviews for one generator’s output. The catalog needs one review and proves rows against an on-chain root. The wrapper cannot read the CBFS catalog. Carrying the row and its proof in select authenticates exactly what the hirer bought, and pinning the definition stops a later revision from changing it. runtime.hire_id() authenticates the hirer. A parameter on the hire record would need a Trading Post consensus change, and funding is checked separately anyway, because ProviderMetered validity only requires the cheapest unit. Lane-charged work shares the 4,096-unit aggregate and the User lane holds 2,051 charged units per block. Delivery uses the separate OutsideShared pool. A per-row cadence increases work with the number of running rows. A per-listing budget bounds that work. Admission depends on the per-listing budget, so excess rows wait in a queue the buyer can see. A forked Python callback adds a 75-unit frame per subscriber, which makes publishing fan-out scale with the subscriber count. The base CIP-7 check and record touch costs 4 structural units before shared overhead, reaction and run tracking. Subscriber Python still costs its own frame. It runs in the subscriber’s own transaction, which the subscriber pays for. Publishing every vendor tick on chain would require a publish per tick. The workload publishes guard edges promptly when capacity is free, which keeps a matching value timely, and other values at heartbeat to stay within budget.

8. Security Considerations

  • The store operator is trusted for data. The workload chooses what the publisher key signs. A dishonest or compromised workload can publish false values that verify. The broker limits it to the feeds of its own shards, in sequence, under a current fence; it does not make the data true. Buyers that move funds on a value SHOULD bound what one message can make them do.
  • Funding. A selection starts only with a deposit for two quanta at its full rate and any activation charge, is settled every quantum, and is suspended before it can run unpaid. Per-hirer and per-listing caps bound how much of the listing one hirer can hold.
  • Capacity griefing. Only a funded selection creates a row record; a non-refundable activation barrier exists only when its pinned term includes an activation charge. Idle records can be collected, up to MAX_TOMBSTONES. Filling MAX_UNFUNDED_SELECTIONS blocks new selections but not funded ones. Underfunded PENDING selections become rejectable after PENDING_UNDERFUNDED_BLOCKS. Underfunded SUSPENDED selections can occupy slots until SUSPENDED_TIMEOUT_BLOCKS. A deposit is refundable, so these rules raise the cost of the attack and do not remove it.
  • Budget exhaustion. The wrapper bounds admission for the listing’s own sponsored attaches, and the workload paces its publishes. Outside subscriptions can add delivery work and compete for phase capacity; the listing reserves no chain share.
  • Replay. The fixed delivery record binds subscription and latest match; subscribers commit their own monotone sequence with effects. This prevents repeated effects but proves no processed-match billing count.
  • Row identity. A deployed row feed is bound to one row by construction: its address is derived from SHA256(row_id), so no other row can claim it. For a static row, uniqueness of static_feed across the catalog is a catalog-generator invariant that the Store checks at review, not a wrapper check. A deployed row feed’s configuration names the row’s definition hash, and a definition never changes.
  • Creator key. The broker signs with it under its allowlist from the instance holding shard 0. Core enforces monotone counts and the hire reservation, not elapsed-block accrual. A compromised workload can over-report up to that reservation; declaration binding and operator-hire refusal must be verified before rollout.
  • Operator hire. Whoever holds the creator’s direct signing path can stop the listing by closing the operator hire. This stops service, and usage unsettled on hires whose close window ends during the outage is lost. No chain state is lost, and recovery is stated in §6.11.
  • Worker signer. It is the one key an instance holds. A theft can disturb lease rows and spend its float, so outages are possible, but it cannot sign publishes or settlements.
  • Workload spending. A compromised workload can invoke allowlisted targets with any payload those targets accept, subject to transaction fee caps and available floats. The generic broker does not prove that subscription funding belongs to a funded selection, that a frozen feed belongs to a collected retired row, or that replacement keys were selected by the creator. Feed-owner operations MUST remain on the operator’s direct path until these listing-specific checks are implemented and verified. A compromised workload still controls what the publisher key signs (above).
  • Public data. A running row’s feed is public on chain.

9. Reference Implementation

The complete catalog rollout is not implemented or validated. First enable about 7,430 catalog rows with 545 runnable non-static rows (20 fast + 525 standard); prediction and launchpad adapters stay disabled until their schema checks. Static rows remain public readers/delivery inputs and are not part of the 545 publisher cap. Prerequisites:
  • the three signing purposes, workload.sign entitlement and required broker targets under the CIP-24 gate. The Linux runner starts a broker per workload attempt when the operator profile enables it (runnerd/crates/runner-workload/src/linux_runtime.rs, re-anchor by broker construction on the landed version); codex-ingest needs that profile setting on the runners that serve it;
  • native subscriber delivery in CIP-7, with the requirements in §6.6;
  • final signing-policy checks and targets in §6.11, distinguishing enforced rules from wrapper backstops and pending work.
A first listing package and wrapper are in cowboyinc/cowboy-store-content on branch cbd/codex-feeds (packages/codex-feeds/), with catalog paging and hashing, connection groups, leases and journals. It authenticates hires through an off-chain registrar; this CIP replaces that with runtime.hire_id() and runtime.is_allowed_caller (core pvm/Lib/cowboy_sdk/runtime.py, functions hire_id and is_allowed_caller; re-anchor on the landed SDK). Store support (cards per row, verified catalog indexing, queued and health states, hire then select) is in the dashboard and Store admin. Acceptance on a local chain with representative gate heights; no live-network transaction is authorized by this draft:
  • one listing with a committed catalog; a hire, select with proof, funding, feed deployment by the operator and binding, publishing;
  • a second hire of the same row sharing the feed;
  • after the core-enforcement changes in §6.6: attach after FeedBound, an owner-sent and owner-paid nonempty-handler Subscribe, a guard edge publish and one delivery, and a replayed record that is a no-op; sponsor-only handler Subscribe refused while record-only Subscribe succeeds;
  • a suspended selection drained best effort, unsubscribed and funded again with a disclosed skipped interval and no delivery charge or delivery unit in the term/settlement vector before an approved meter;
  • attach refused at listing-local delivery/32-attach bounds; external sponsor/count failure refused by Store/workload RPC preflight, with a direct attach only recording its request and fund withheld at delivery_budget, the total-consumer 32-subscription cap or missing sponsor approval; delivery uncharged and its unit omitted from the term/settlement vector before an approved meter; reservation-limited monotone settlement and listing-specific operator-hire refusal verified;
  • a static row selected, its feed’s publisher key rotated without invalidating retained backlog, the catalog recommitted, and the same row selected again; duplicate static feeds rejected by catalog review;
  • a retired row collected to a tombstone, then a catalog that reuses its row_id with a different definition, which select rejects;
  • unfunded selections of many rows that create no row record, and a full MAX_UNFUNDED_SELECTIONS that does not affect funded selections;
  • an underfunded selection stays PENDING with reason UNDERFUNDED, then is ended by reject_pending;
  • an optional activation charged once at the next routine settlement, or the final statement if closing starts first, when enabled and two hires select one new row, never on a refused fund; a class-only term funds without an activation unit;
  • an idle row collected to a tombstone, then funded again on the same feed with its pin intact;
  • after the core-enforcement changes in §6.6: top-up refused for a third party, owner top-up refunded to the recorded payer, and old subscriptions unsubscribed by their recorded payer after submitter replacement; failed consensus runs re-minted below the three-attempt failure limit and parked at it;
  • keys released through the operator hire; select under it rejected; its settlement refused by the broker; the hire closed, signing stopped, and recovery through a new hire and new grants;
  • a selection under a hire below FUND_QUANTA × min_funding that stays PENDING; suspension before the deposit runs out; refunding on top-up;
  • a hire closed mid-quantum, detected, expired and settled once inside the window; a settlement clamped to reserved;
  • a collected row whose feed went dormant, restored and restarted by the operator on the same address;
  • a row awaiting operator deployment that stays STALE with AWAITING_FEED, accrues nothing and never reports SOURCE_FAILED before binding;
  • a row that goes STALE and stops accruing, reaches FAILED, and recovers by itself; a quiet market that stays LIVE;
  • an edge deferred past the allowance, with coalesced set when its condition ended; a guard limited to its selection’s share of edges; commit_catalog rejected for a changed cadence;
  • a never-funded selection whose record is deleted at once; a reselect under one hire that keeps its counters;
  • release, grace and stop; restart on the same feed; expire of a lapsed hire;
  • a selection refused by fund at a class cap, and two instances that cannot both fund past it;
  • a shard claimed after its holder is killed, within LEASE_BLOCKS, with no new broker signature under the old attempt/fence; transactions signed before takeover may still land and must be duplicate-safe or stale as specified in §6.12; a rollout that reclaims with a new attempt without waiting for expiry; a worker signer refused by fund;
  • broker signing/release throughput measured at publish_budget, including publish signatures, submission and wrapper/settlement traffic; no unmeasured rate assumed;
  • an instance killed at each outbox boundary (before sign, after sign, after submit) with no doubled publish, delivery or charge;
  • the listing at its budgets, alongside representative competing User-lane traffic, measuring publish rate, inclusion latency and contention; no reserved delivery share or bounded-block execution promise;
  • verified indexing of a 16,384-row catalog, eight revisions of churn, cold recovery of 2,048 selections through the paginated lists, bulk expiry, and the wrapper at both state caps with maximum-size guards.
CC0 1.0 Universal.