> ## Documentation Index
> Fetch the complete documentation index at: https://docs.cowboy.inc/llms.txt
> Use this file to discover all available pages before exploring further.

# CIP-51: Catalog Listings

> One Store listing that carries a catalog of rows, each shown as its own card and hired on its own; a row's data stream starts on its first funded hire and stops after its last, within the listing's own publishing and subscription admission caps.

> [!NOTE]
>
> **Status:** Draft\\
>
> **Type:** Standards Track\\
>
> **Category:** Core (Store)\\
>
> **Created:** 2026-11-04\\
>
> **Requires:** [CIP-4](https://docs.cowboy.inc/cips/cip-4-storage.md) (dormancy and auto top-up), [CIP-7](https://docs.cowboy.inc/cips/cip-7-simple-stream-protocol.md) (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](https://docs.cowboy.inc/cips/cip-10-runner-containers.md) (the stream workload), [CIP-24](./cip-24-secrets-manager) (vendor credentials and signing keys), [CIP-33](https://docs.cowboy.inc/cips/cip-33-actor-hiring-and-distribution.md) (declarations, hires, ProviderMetered), [CIP-43](https://docs.cowboy.inc/cips/cip-43-access-meter.md) (the access meter)\\
>
> **Related:** [CIP-9](https://docs.cowboy.inc/cips/cip-9-runner-storage.md) (the catalog file)

> [!NOTE]
>
> **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`:

```text theme={"system"}
Row = {row_id: text ≤ 64,                    // [a-z0-9._:-]
       definition: RowDefinition,
       title: text ≤ 96, summary: text ≤ 256, retired: bool}
RowDefinition = {source: map ≤ 1 KiB,        // vendor identity, e.g. {network: 1399811149, address: "So111…"}
                 class: text 1–10 bytes,        // [a-z0-9_]
                 numeric_tag_scales: map,
                 static_feed: address?,      // set for a row whose feed already exists (§6.4)
                 static_deployer: address?, static_salt: bytes?, static_shard: u16?,
                 static_identity_hash: bytes32?, max_silence_ms: u64?,
                 static_max_publishes_per_hour: u32?}
```

`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:

```text theme={"system"}
select(revision, row_id, definition, title, index, count, proof) -> selection_id
```

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:

```text theme={"system"}
Selection = {selection_id, hire_id, hirer, row_id, definition_hash, class,
             status: PENDING | FUNDED | SUSPENDED | ENDED, selection_revision: u64,
             guard?, subscriber?, handler?,
             funded_blocks: {class: u64},
             funded_at?, ended_at?, activations: u64, status_since: u64, reason?}
```

`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:

```text theme={"system"}
publish_admission = Σ (1 / heartbeat(class) + MAX_EDGE_PUBLISHES_PER_HOUR / 3600)
publish_admission ≤ publish_budget
```

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.

| Field | Value |
| - | - |
| `consumer`, `guard`, `handler` | Selection's subscriber, guard and handler; no handler\_limits field |
| `feed` | Row's bound Feed |
| `reaction` | None for this listing; sponsor-only authority cannot attach any reaction |
| `payer` | Sender: the row shard's submitter account for a record-only subscription, the consumer owner for a handler subscription |
| `escrow` | u64, at least one worst-case step at the live fee, at most MAX\_SUBSCRIPTION\_ESCROW |
| `max_checks_per_hour` | Declared maximum checks per aligned 3,600-BLOCK window, based on heartbeat/edge rate; static rows use their declared maximum |
| `start_after` | Feed head when Subscribe commits |

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

| Parameter | Initial value | Set by |
| - | - | - |
| `feed_owner` | Account that deploys every row feed; fixed for the life of its feeds | creator, per listing |
| `publisher_key` / `usage_key` | Publisher key checked at bind; publisher/usage keys installed by operator rotation | creator, per listing |
| `canonical_feed_code_hash` | Canonical Feed source code hash, pinned before the first deployment | creator, per listing |
| `operator_hire_id` | Set at bootstrap | creator, per listing |
| `health_silence_ms` | Set explicitly per class before finalization; milliseconds, not block cadence | creator, in class table |
| `publish_budget` | 2 publishes per block (2 per second at the 1-second floor) | creator, per listing |
| `delivery_budget` | 0 until delivery + handler-run + SDK module gates; then admission cap of at most 60 record-equivalents/block (§6.5) | creator, per listing |
| `MAX_SUBSCRIPTIONS_PER_ROW` | 60 | this CIP |
| `MAX_PENDING_PER_HIRER` | 5 | creator, per listing |
| `MAX_UNFUNDED_SELECTIONS` | 512 | creator, per listing |
| `PENDING_UNDERFUNDED_BLOCKS` | 60 | this CIP |
| `PENDING_TIMEOUT_BLOCKS` | 3,600 | this CIP |
| `SUSPENDED_TIMEOUT_BLOCKS` | 86,400 | this CIP |
| `MAX_EDGE_PUBLISHES_PER_HOUR` | 6 per row | this CIP |
| `MAX_FUNDED_PER_HIRER` | 50 | creator, per listing |
| Vendor budget (admission limit) | per listing; 8,000,000 Codex CU a month for the first listing, on a 10,000,000 CU plan | creator, per listing |
| `MAX_TOMBSTONES` | 8,192 | this CIP |
| `BILLING_QUANTUM_BLOCKS` | 3,600 | creator, per listing |
| `MAX_SUBSCRIPTION_ESCROW` | set from the measured delivery cost | creator, per listing |
| `UNSUBSCRIBE_DRAIN_BLOCKS` | 60 | this CIP |
| `min_funding` | One BILLING\_QUANTUM\_BLOCKS of class accrual at pinned prices; delivery is uncharged and omitted from the term and settlement vector pending its meter, and edge\_publish is excluded. Required headroom is reserved minus unsettled accrual; activation is added separately only when enabled in the pinned term and due | derived |
| `FUND_QUANTA` | 2 | this CIP |
| `CLOSE_POLL_BLOCKS` | 60 | this CIP |
| `IDLE_GRACE_BLOCKS` | 600 | this CIP |
| `shard_count` | 5, at least 2 and at most 8 | creator, per listing |
| `LEASE_BLOCKS` / `LEASE_RENEW_BLOCKS` | 1,200 / 400 | this CIP |
| `FAILED_AFTER_BLOCKS` | 3,600 | this CIP |
| `FAILED_PARK_BLOCKS` / `FAILED_PROBE_BLOCKS` | 86,400 / 3,600 | this CIP |
| `RETIRED_FEED_BLOCKS` | 2,592,000 blocks (about 30 days at the 1-second floor) | this CIP |
| Rows per catalog | 16,384 | this CIP |
| Row records per wrapper (running, bound, or awaiting collection) | 2,048 | this CIP |
| Selection records per wrapper, of any status | 2,048 | this CIP |
| `MAX_EDGES_PER_SELECTION_PER_HOUR` | 2 | this CIP |

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:

| Records | Keys | Bytes |
| - | - | - |
| One per selection record, keyed by `hire_id`: fixed fields of at most 400 bytes, a guard of at most 512 and a subscriber address | at most 2,048 | at most 2.0 MiB |
| One per row record: `row_id`, definition hash, class, maximum publish rate, funded count, last funded height, feed, state | at most 2,048 | at most 0.5 MiB |
| Index pages of 128 `(selection_id, hire_id)` pairs and 128 row ids each, which `list_selections` and `list_rows` page through, and which resolve a `selection_id` to its record key | 32 | at most 192 KiB |
| Tombstone pages, 128 tombstones each | 64 | at most 0.7 MiB |
| Catalog root, parameters, class table, workload accounts (at most 16), counters | at most 64 | at most 64 KiB |
| One 5-byte `ShardConfigV1` and up to 8 lease rows of 113 bytes | at most 9 | at most 4 KiB |
| Per-hirer counters at `hirer:<address>` | at most 2,048 | included in serialized measurement |
| Per-subscriber attach counters at `subscriber:<address>` | at most 2,048 | included in serialized measurement |
| **Bound at caps (not all reachable together)** | **8,361 keys** | **at most 3.8 MiB** |

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](./cip-24-secrets-manager#workload-signing-amendment).

The three purposes below are persisted variants of `WorkloadReleasePurpose`. Tag 5 and above are refused. There is no feed-owner purpose.

| Purpose | Wire tag | `workload.sign` value | Authority and bound |
| - | - | - | - |
| `SignFeedPublish` | 2 | `feed_publish` | Allowlisted publisher key, chain/stream identity, feed-address shard fence, and within-attempt signed sequence continuity |
| `SignSubmitTransaction` | 3 | `submit_transaction` | Allowlisted targets and max fee; `feed.subscribe` is the gated target for subscription calls with no reaction and, under sponsor-only authority, an empty handler. `feed.fund_subscription` and `feed.unsubscribe` are explicit targets |
| `SignCreatorTransaction` | 4 | `creator_transaction` | Creator operations from shard 0, including catalog commit and ProviderMetered settlement; chain enforces monotone counts and the hire reservation |

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

| Wrapper method | Authorization |
| - | - |
| `commit_catalog(revision, root, row_count, class_table_hash, volume, path)` | Creator |
| `set_parameters(params)`, `set_shard_config(config)`, `set_class_table(table)` | Creator |
| `admit_workload_account(account, shard_id)` / `remove_workload_account(account)` / `admit_worker_signer(account)` / `remove_worker_signer(account)` | Creator |
| `select(...)`, `nominate(subscriber)`, `attach(guard, subscriber, handler, definition)`, `detach()`, `release()` | Hirer, under the hire |
| `accept(selection_id)` | The nominated subscriber actor |
| `expire(hire_id, selection_revision)` | Admitted workload account, for a hire it read as lapsed |
| `expire_pending(selection_id)` | Anyone; succeeds only after `PENDING_TIMEOUT_BLOCKS` |
| `expire_suspended(selection_id)` | Anyone; succeeds only after `SUSPENDED_TIMEOUT_BLOCKS` |
| `delete_record(hire_id)` | Admitted workload account, only after a hire that can no longer reopen has its final settlement and no open subscription a listing account pays for |
| `collect_row(row_id)` | Anyone; succeeds only for a row with no `FUNDED` or `SUSPENDED` selection for `RETIRED_FEED_BLOCKS` |
| `fund(selection_id, selection_revision, definition?)` | Shard 0's admitted workload account |
| `suspend(selection_id, selection_revision, reason)`, `bind_feed(row_id, feed, definition)`, `reject_pending(selection_id, selection_revision)`, `stop_row(row_id, idle_revision)` | Admitted workload account |
| `claim_lease`, `renew_lease` | Admitted worker signer |
| `get_row(row_id)`, `get_selection(id)`, `get_catalog()`, `get_parameters()` | Read-only |
| `list_selections(cursor, limit ≤ 128, filter)`, `list_rows(cursor, limit ≤ 128, filter)` | Read-only, paginated |

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.

## Copyright

CC0 1.0 Universal.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.