Skip to main content
Status: Draft Type: Standards Track Category: Core Created: 2026-03-07 Updated: 2026-11-03 Requires: CIP-9 (Runner Attached Storage), CIP-11 (native runner routes), CIP-14 (DNS-Addressable Actors), CIP-18 (price tables); workload registry records for Workload-target routes only
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

An actor can serve static files, handle dynamic requests, and run off-chain services under the same domain. Each request needs a destination and a payment policy.

Goal

This CIP specifies a routes table in actor KV state for the CIP-14 Gateway network. Each (verb, path) entry selects a CBFS Visibility::Public volume, a named actor handler, an off-chain runner, or a registered workload. It also selects whether the actor or caller pays. An actor publishes its Workload URL routes in __cowboy/routes (§8.15), without a per-actor Gateway configuration change.
  • A unified route schema (verb, path, target, payment policy, priority, enabled) stored in actor KV at the reserved key __cowboy/routes.
  • A verb-aware route resolution algorithm that determines per-request dispatch (volume mount, actor handler, or off-chain runner) and payment policy.
  • A Runner target that proxies a route off-chain for endpoints that cannot run in consensus, such as LLM inference, outbound API calls, and streaming. Current dispatch requires an explicit runner pin and its advertised endpoint. Selection through runner_bindings and binding-scoped CBFS mount authorization are unimplemented target design (§7.5, §8.14).
  • A Workload target that relays an actor-declared route, including WebSocket upgrades and unbuffered SSE, to a single long-lived registered workload backend (§8.15), for streaming app endpoints: inference SSE, agent chat UIs, application websockets.
  • A per-route payment policy (pays = actor | caller) with actor as the default. caller opts the route into payment gating per CIP-18.
  • An extension to the ingress.http entitlement with static_volumes and max_static_response_bytes parameters.
  • A Gateway-to-Relay-Node fetch protocol for retrieving, reconstructing, caching, and serving public-volume objects.
  • A Gateway-to-Runner fetch protocol for reading the routes table from actor state with Merkle-proof verification.
  • A CORS configuration schema (_meta/cors.json) with defaults for static assets.
  • Cache invalidation driven by on-chain state-root and manifest_root changes.
  • The build lowers an actor’s route declarations to the canonical table. The deploy and upgrade instructions carry it. The chain validates and installs it into a protected slot that actor code cannot write.
This CIP defers the following:
  • Pre-compressed asset variants (.gz, .br files in the volume).
  • Small object inlining (bypassing erasure coding for tiny files).
  • Image optimization or resizing at the Gateway edge.
  • Range requests and chunked transfer for streaming large assets.
  • Caller-pays static-asset downloads (paid public-volume content).

2. Motivation

CIP-14 makes actors reachable over HTTP through a single http.request handler. An actor can serve static assets, dynamic API endpoints, and off-chain work such as LLM inference, outbound API calls, and streaming. Each needs a different execution path. A static file should come straight from storage. A state-changing call needs the actor’s deterministic handler under consensus. A model call cannot run in the PVM at all. The routes table assigns each (verb, path) a destination and payer. It supports the following behavior:
  1. The Gateway serves static assets from its cache or reconstructs them from Relay Node shards without invoking an actor handler.
  2. Static and runner routes consume no actor-handler execution or max_query_cycles budget.
  3. Gateways cache reconstructed objects, serve conditional requests using ETags, and set Cache-Control headers without invoking the actor.
  4. Routes target named actor handlers, not a single http.request catchall. GET /post and POST /post go to different methods. Path parameters (/users/{id}) bind to handler arguments. Actors no longer reimplement routing.
  5. Each route declares pays = actor | caller. actor is the default and needs no caller wallet when no enabled CIP-18 price_table overrides it; caller selects 402/x402 gating under the same fallback. An enabled table’s rule or default_mode is authoritative.
  6. The build produces the routes table from actor source. The chain installs it with the code it routes to. What the Gateway serves is always what the deployed code declares; no admin handler or later write can make the two drift. Prices that change at runtime live in the CIP-18 price_table, and assets change by republishing their volume.
  7. Authors declare routes with decorators on handler functions (FastAPI / axum / Hono style). The build lowers them to the canonical schema.
  8. Authors declare endpoints for LLM inference, outbound API calls, and streaming responses as Runner targets. The Gateway proxies these requests off-chain to a runner. The same routing table decides, per (verb, path), what runs in consensus, what serves static, and what runs off-chain.
  9. WebSocket and SSE connections terminate at a registered persistent workload under the same URL space (Workload target, §8.15). One domain serves static from a volume, consensus methods from the actor, and live streams from a workload the actor owns.

3. Design Goals

  • Serve static assets without invoking any actor handler or consuming PVM cycles.
  • Let actors declare routes per (verb, path), targeting a CBFS volume mount, a named actor handler, or an off-chain runner, with explicit priority ordering.
  • Let a route execute off-chain on a runner (Runner target) for work that cannot or should not run in consensus, with optional caller authentication and actor- or caller-owned CBFS mounts.
  • Relay long-lived streaming connections (WebSocket, SSE) unbuffered to a registered persistent workload (Workload target), with explicit idle-timeout and connection-lifetime policy.
  • Make pays = actor the fallback default so that browser GETs do not require a wallet absent an enabled CIP-18 price_table; let actors opt specific routes into pays = caller as the client-paid fallback for payment-gated endpoints.
  • Support SPA (single-page application) fallback patterns (index.html for all non-file paths).
  • Reuse CIP-9’s existing _meta/content_types.json and _meta/cache_config.json for HTTP header generation.
  • Provide CORS headers for static assets by default (browsers need them).
  • Define the Gateway-to-Relay-Node fetch protocol for static assets and the Gateway-to-Runner fetch protocol for routes: retrieval, integrity verification, and caching.
  • Extend the existing ingress.http entitlement. No new entitlement type is introduced.
  • Install the routes table only with the code it routes to. The build produces it; the chain writes it at deploy and upgrade. Actor code can never write it.

4. Non-Goals

  • Replacing actor handlers for dynamic requests. Volume and method targets coexist; the routes table controls which (verb, path) pair goes where.
  • Server-side rendering. Actors that need SSR use a method target.
  • Pre-compressed asset variants (.gz, .br). Compression is on-the-fly only.
  • Image optimization, resizing, or transformation at the Gateway edge.
  • Range requests (Range header) for partial content delivery.
  • Verifiable or multi-operator runner serving. A Runner-target route is trusted to the selected runner in this CIP; attested / trustless serving and on-chain settlement of off-chain work are deferred (§13). The same applies to Workload-target routes: a workload-served route is exactly as trustworthy as its host (§8.15).
  • Metered billing of streamed content. A Workload route can payment-gate connection establishment (pays = caller, CIP-18); usage-metered streaming settlement (per-token, per-message) is the streaming-payments protocol’s scope, not this CIP’s.

5. Definitions

  • A route is an entry in the actor’s routes table that maps a (verb, path) pattern to a Target, with a payment policy, priority, and enabled flag.
  • A verb is an HTTP method (GET, HEAD, POST, PUT, PATCH, DELETE) or ANY (matches any verb at lowest specificity).
  • A target is the destination of a route, a Method (named actor handler, executed via actor RPC under consensus), a Volume (CBFS public volume mount), a Runner (the request proxied off-chain to a selected runner endpoint for non-consensus execution), or a Workload (a registered persistent service).
  • A Runner target is a route whose handler runs off-chain on a selected runner (the CIP-9 / RAS execution tier), not in consensus. Distinct from the state read of §8.12 (GET_STATE against a full node), which only serves verified reads of the actor’s KV state; a Runner target serves the route’s request and response itself.
  • A Workload target relays to a single long-lived registered service with a control-plane registry record (identity, owning actor, serving endpoint). It uses no per-request runner selection, handler dispatch, or route mounts. The Gateway relays bytes to one durable backend, including upgraded WebSocket connections and streamed SSE responses (§8.15).
  • A workload registry record is the control-plane record describing a persistent workload. This CIP consumes five of its fields, workload_id, owning_actor, serving_endpoint, reporter, and host_pool, and the reporter’s CIP-2 Runner pool entitlement for that pool. Workload-target routes are unavailable where that registry does not exist.
  • The pays field selects the fallback route payment gate when no enabled CIP-18 price_table applies, actor (default; the caller pays nothing at establishment) or caller (Gateway requires payment proof; on missing/invalid proof returns 402 Payment Required). An enabled table’s matching rule or default_mode takes precedence. Workload hosting costs and any actor-funded serving-budget charge follow their own policies.
  • The routes table is the CBOR-encoded Routes value stored in actor KV at the reserved key __cowboy/routes.
  • A mount is a Volume-target route with a wildcard path, declared at the SDK module level (e.g., actor.mount("/assets", volume="web-assets")).
  • An object is a single file stored in a CBFS volume (e.g., assets/logo.png). Objects are erasure-coded into shards and distributed across Relay Nodes.
  • A shard is one piece of an erasure-coded object, stored on a single Relay Node. Any K of K+M shards are sufficient to reconstruct the original object.

6. Routes

6.1 Storage Location

The routes table is stored in the actor’s KV state at the reserved key __cowboy/routes. The CIP-11 sponsorship ceiling for native runner routes is stored beside it at __cowboy/route_sponsorship. Both are protected slots: they are written only by the chain’s install path (§6.9), during deployment, upgrade, or a fork that copies its parent’s code. The host refuses every actor write or delete of either key. KV storage, rather than a volume file or an actor method, gives the Gateway a table it can verify without executing the actor: the unified state root is committed in every block header, and the Gateway fetches __cowboy/routes with a CIP-17 proof against it (§8.12). An actor that serves only dynamic methods needs no CBFS volume to publish routes. Protection makes the table part of the code’s identity. It is validated once, by the node, at installation, including the static_volumes membership of every Volume target (§7.3). It can change only together with the code it routes to.

6.2 Schema

Installed price values are canonical positive integer native base-unit strings, without a denomination suffix, sign, fraction or leading zero. They are the net actor fee. One CBY is 1,000,000,000 base units; SDK/compiler declarations MAY accept an exact decimal such as price="0.05 CBY", but MUST lower it to "50000000" before installation, as in CIP-18 §8.5. The caller’s total adds the 5% protocol fee, rounded down in base units; transaction gas is separate. A route price of 50,000,000 therefore quotes 52,500,000 base units before gas. Price-table entries follow their asset and model rules in CIP-18. For Method targets, an explicit mode overrides the HTTP verb. If absent, GET/HEAD resolve to "read" and other verbs to "submit" (after ANY matches, use the request’s actual method). For unpaid invocation, "read" uses the unsigned query path; "submit" signs and waits for a transaction result; "submit_no_wait" signs and submits without waiting for that result. Both submit modes charge gas to the Gateway signing wallet under CIP-14 §8.4.3. For this Gateway-signed command path, timeout_ms sets the submit receipt wait (default 3,000 ms), not a transaction expiry or a guarantee that the handler has stopped. After confirmed admission, a submit receipt wait that reports timed_out, or a submit_no_wait acknowledgement, returns 202 Accepted with x-cowboy-submit-status: admitted-pending. The Gateway preserves the configured fallback_response body and other headers, but overrides its status and replaces any case-insensitive admission-status header. Without a fallback, this acknowledgement has an empty body. A succeeded submit result with missing/empty output instead returns the configured fallback unmodified, or empty 202 when absent; a valid non-empty response envelope takes precedence. Read responses and malformed non-empty command responses do not use this fallback. See CIP-14 §8.2.1. The native paid Method path below returns its atomic committed response under CIP-18 §8.5. Native paid Method requests are an exception. A Method request selected for payment follows CIP-18 §8.5, with the current route and policy resolved by the node. Payment and handler execution share a consensus savepoint. Even Read / GET / HEAD enters through the signed atomic wrapper while its business handler stays read-only; unsigned /actor/read or an opaque direct message cannot bypass paid-handler admission. SubmitNoWait also returns the committed atomic response, rather than authorizing a second dispatch or a fire-and-forget fallback. External Runner and Workload routes retain their distinct confirmation-before-dispatch lifecycle in CIP-18 §6. pays = "actor" (the default) means the caller pays no service price and needs no payment proof when no enabled CIP-18 price_table applies. For actor handlers, GET/HEAD default to unsigned Read mode with no transaction gas; an explicit route mode overrides the verb. In Submit or SubmitNoWait mode, the Gateway signs the call and pays its gas from its own wallet under CIP-14 §8.4.3. The actor’s hot balance is not debited for the Gateway-signed top-level transaction; deferred work the handler emits is billed to the emitting actor, then its FallbackToOwnerBalance owner for any shortfall, at basefee with zero tip (CIP-28 §3.4). The Gateway enforces a per-actor budget alongside the Gateway’s per-transaction cap under CIP-14 §8.4.3, including its same-nonce recovery rules. The actor budget counts actual committed gas plus unresolved signed maxima. Unresolved evidence keeps the maximum while retryable lookups remain queued; later valid evidence settles the actual charge. A definitive miss (strict not-found for all signed variants), malformed or mismatched evidence, or queue overflow keeps its maximum for the process lifetime. Evidence retry and exhaustion rules follow CIP-14 §8.4.3. A callee cannot bill the Gateway for timers: CIP-5 §4.2 requires an actor to pay for its own timers (the canonical Watchtower Feed’s owner-paid start/restart applies only to the Feed owner’s own signed call). There is no callee-scheduled, sender-billed timer path to exclude from the Gateway budgets under this rule (CIP-14 §8.4.3). A Workload route does not execute the actor per request: without an enabled table, the Gateway treats pays = "actor" as free. An enabled table’s matching rule or default_mode can instead require caller payment or charge the actor’s serving budget. Workload hosting and bandwidth costs are governed separately; the route declaration alone does not fund serving. pays = "caller" selects the client-paid fallback when no enabled CIP-18 price_table applies. Under that model the Gateway returns 402 Payment Required with x402-compatible headers until the caller submits a valid payment proof. price is required and is the per-request fallback charge interpreted by CIP-18. An enabled table’s matching rule or default_mode can instead make the route free or actor-funded. For Volume targets, pays MUST be "actor". Caller-pays static downloads are deferred to a follow-on CIP. A Runner target proxies the request off-chain, outside consensus; the body and any stream never enter a transaction. In the current implementation, the route must set an explicit runner pin that resolves to an advertised route_serving_endpoint. Missing pins, unavailable records, and missing or unusable endpoints return 503 Service Unavailable. Current selection does not apply requires or affinity, and an explicit pin does not establish a runner_bindings authorization check. Under the unimplemented selection and binding-authorization design, an omitted requires selector would admit runners in the actor’s runner_bindings (§7.5); a selector would narrow that set, and the Gateway would choose a healthy runner with the requested affinity. A runner pin would then have to belong to that eligible set (§8.14). Actor- and caller-owned mount issuance under those bindings is also target design, not a guarantee of the current proxy. This is the path for endpoints that cannot or should not run in the deterministic PVM: LLM inference, outbound API calls, long-running or streaming work. On-chain state changes still belong behind a Method target; a Runner handler’s execution is never consensus. Payment and caller authentication follow §8.14; they do not implement the missing binding authorization. A Workload target relays the request to one registered persistent workload, such as a model server, agent chat backend, or app relay, using its control-plane registry record. This is the streaming path: the Gateway upgrades and pipes WebSocket connections, relays SSE unbuffered, and applies stream-lifetime policy (idle_timeout_ms, max_connection_ms) instead of the request-scoped timeout_ms (§8.15). The resolved client-paid model gates connection establishment; pays = "caller" selects that model only when no enabled price_table overrides it. auth = "account" authenticates the establishing caller. There is no runner selection, no handler name, and no route mounts. The workload’s registry record carries its volume mounts and any future capabilities. The actor publishes the route in __cowboy/routes; the Gateway resolves the serving endpoint from the workload registry (§8.15).

6.3 Path Patterns

Route paths use the following syntax:
  • /api/users/{user_id} binds a named path parameter to a single segment.
  • /static/*rest matches zero or more segments and binds the remainder to rest.
  • /about matches exactly.
  • /assets/* matches anything under the prefix without binding.
The Gateway extracts named path parameters from the matched route and passes them to the actor handler in the HttpRequestEnvelope.path_params field (§15.2). Static (Volume-target) routes do not bind path parameters; the matched suffix is handled per §6.7.

6.4 Example: Full-Stack Application

This CIP defines the canonical wire format (the Routes value at __cowboy/routes) and the Gateway’s resolution algorithm. SDK authors choose the authoring API. This example uses Python and the Actor subclass style from CIP-6. The Runner branch below illustrates the target selector and mount design. It does not configure a currently serving runner: current dispatch needs an explicit runner pin (§6.2), and selector-based choice and binding-scoped mount issuance remain unimplemented (§7.5, §8.14).
The build lowers the decorators and mount(...) declarations to the canonical Routes value, and the deploy installs it at __cowboy/routes (§6.9):
In this configuration:
  • GET /api/users/abc matches /api/users/{user_id} (priority 100). The Gateway dispatches an unsigned read to users_get with path_params = {"user_id": "abc"}. The caller pays no service price (pays = "actor"); no transaction gas is charged.
  • POST /api/inference matches /api/inference. The Gateway returns 402 with x402 headers until the caller pays the quoted total (a net actor price of 0.05 CBY plus the 5% protocol fee, 0.0525 CBY before gas), then, in the target design, proxies the request off-chain to a runner selected from the eligible set (§8.14); current dispatch instead requires an explicit pin (§6.2); inference_run runs on the runner, not the actor PVM.
  • GET /assets/logo.png matches /assets/* (priority 10). The Gateway serves assets/logo.png from the web-assets volume without invoking the actor.
  • GET /about matches /* (priority 0). The Gateway looks up about in web-assets. If absent, it serves index.html with status 200 as the SPA fallback.
  • The Gateway always intercepts the reserved path GET /_cowboy/health (CIP-14 §8.6). It never consults the routes table.
@get/@post/etc. are single-verb sugar for the underlying multi-verb @route(verbs, path) decorator; both can coexist:
This compiles to two entries in the canonical table, one per verb, both targeting foo. The runner selector ergonomics in this paragraph are informative target design and are unimplemented. requires is optional, so runner() with no selector inherits the actor’s runner_bindings. This needs no configuration when the bound pool is already capable. An SDK SHOULD also offer helpers that lower to capability tags. For example, runner(model="claude-sonnet") lowers to requires.capabilities = ["llm", "model:claude-sonnet"]. Typed helpers like runner.llm(...) / runner.mcp(...) let common routes omit tag strings, while requires={…} stays the explicit form. Routes may serve LLMs, image generation, webhooks, or plain compute. The default therefore inherits the entitlement’s capabilities.

6.5 Canonical Encoding

The Routes value is encoded as CBOR (RFC 8949) with deterministic key ordering (CBOR §4.2.1 Core Deterministic Encoding). The routes list is sorted before encoding by:
  1. priority descending,
  2. then path descending (UTF-8 byte order),
  3. then verb ascending in declaration order:
This canonical form ensures that two semantically identical routes tables produce the same CBOR bytes and the same Merkle leaf in the actor’s state tree.

6.6 Route Resolution Algorithm

When a Gateway receives an HTTP request for a registered actor:
  1. If the path starts with /_cowboy/, handle per CIP-14 §8.6. Highest priority, not overridable by the routes table.
  2. Read cached routes for this actor. Refresh every poll interval (§8.12). Filter to routes with enabled = true.
  3. A route is a candidate if:
    • Its path pattern matches the request path (literal segments + named params + wildcards).
    • Its verb matches the request method, or verb = "ANY".
  4. The Gateway selects one winner among the matching routes:
    • Highest priority wins.
    • On a tie, the longest concrete prefix wins. Count the UTF-8 bytes of the matched path before a terminal wildcard, including matched parameter segments. A named wildcard and an anonymous wildcard have the same prefix length; neither includes the wildcard remainder. A matching path without a terminal wildcard consumes the whole path. Do not add an exact/prefix/template category rank ahead of this comparison.
    • On a further tie, a more specific verb (any non-ANY) wins over ANY.
    • On a further tie, prefer Method, then Runner, then Workload, then Volume (safety: prefer the consensus handler, then per-request off-chain compute, then the long-lived proxy, over static).
    • If these comparisons still tie, take the first route in the canonical table order from §6.5. Installed tables are already canonical; configuration-built routers MUST canonicalize before resolution so reordering equivalent declarations does not change the winner.
    • RunnerRoute entries are not Gateway dispatch targets; they are admitted and invoked per CIP-11 and never match an HTTP request here.
4a. The Gateway checks access. OPTIONS preflights are answered per §9.5 before this step. For any other request, apply the current site gate and the winning route’s access per CIP-37 §7 and §9, before the body is read and before payment is evaluated. Site Owner dominates route Public; missing route tables inherit the site gate through Site fallback. Current policy must be established before cached content can answer. A caller that is not admitted receives 302, 401 or 403 and the target is not reached.
  1. If a Volume target wins:
    • The verb MUST be GET or HEAD. Other verbs on a route whose only match is a Volume target return 405 Method Not Allowed.
    • The Gateway resolves the volume object path per §6.7.
    • If the object exists, serve it from the named volume (§8).
    • If the object does not exist and fallback is set, serve the fallback object from the same volume with fallback_status.
    • If no fallback, return 404 Not Found.
  2. If a Method target wins:
    • Resolve the payment model using the enabled CIP-18 price_table first, falling back to route.pays only when no enabled table applies. If the policy read or decode fails, return 503 Service Unavailable.
    • For a resolved free model, dispatch without a payment check. For a resolved actor-funded model, check the actor budget before dispatch; a depleted budget MUST NOT authorize free service. CIP-18 §7.2 defines the fallback and deduction rules. The Gateway invokes the named handler, passing the HttpRequestEnvelope with path_params populated. Unless the route sets mode, GET/HEAD use the CIP-14 query path and POST/PUT/PATCH/DELETE use the command path; an explicit mode selects the path instead.
    • For a client-paid model selected by an enabled price_table or fallback pays = "caller", verify the caller’s payment proof per CIP-18. On missing or invalid proof, return 402 Payment Required with x402-compatible headers (X-PAYMENT-Required, X-PAYMENT-Receipt, etc., per CIP-18). On valid proof, dispatch to the named handler.
  3. If a Runner target wins:
    • If auth = "account", the request MUST carry the caller’s Cowboy-account signature; the runner verifies it (§8.14) and the Gateway returns 401 Unauthorized if the runner rejects it. Identity is 401, payment is 402. Both checks apply.
    • If the resolved payment model is client-paid, apply CIP-18 payment gating exactly as for Method (return 402 Payment Required until a valid proof is presented).
    • Current dispatch resolves the explicit runner pin and its advertised endpoint (§6.2), then proxies the request off-chain; the actor’s PVM is not invoked. Selection from a binding-authorized eligible set and per-request scoped mount issuance are target design (§7.5, §8.14), not checks performed by the current proxy.
  4. If a Workload target wins:
    • If auth = "account", the establishment request MUST carry the caller’s Cowboy-account signature; the workload verifies it (§8.15) and the Gateway returns 401 Unauthorized when it is rejected.
    • If the resolved payment model is client-paid, apply CIP-18 payment gating to connection establishment (return 402 Payment Required before any upgrade or first streamed byte).
    • The Gateway resolves the workload’s serving endpoint from its registry record and relays the connection per §8.15, using a WebSocket upgrade and byte relay, or an unbuffered streamed HTTP response. The actor’s PVM is not invoked.
  5. If no route matches, return 404 Not Found. Explicit routes are required; there is no fallback default_behavior.

6.7 Volume Object Path Resolution

Given a Volume-target route match and a request path:
If strip_prefix is false, the full request path (minus leading /) is used:

6.8 Validation

The node validates a table when it installs it (§6.9) and rejects the deployment or upgrade that carries an invalid one. It decodes the table with the strict admission decoder, which bounds size and rejects unknown fields and duplicate map keys. It requires the canonical encoding (§6.5). Every rule below is checked at install except those marked dispatch, which depend on state outside the table and are checked when a request is served or a connection established. Gateways apply the same structural rules when they load a table.
  • version MUST be 2, the final launch schema, with the encoded access field. Other versions return 503 without application dispatch (CIP-37 §7.2).
  • routes MUST NOT exceed MAX_ROUTES entries.
  • Total CBOR-encoded size MUST NOT exceed MAX_ROUTES_SIZE.
  • Each path MUST start with /.
  • path MUST NOT equal /_cowboy/ or start with /_cowboy/ (reserved by CIP-14).
  • verb MUST be one of the seven valid values.
  • mode, when present, MUST be exactly "read", "submit", or "submit_no_wait"; unknown values reject the table. When absent, a Method route uses read for GET/HEAD and submit for other verbs.
  • target.kind MUST be "method", "volume", "runner", "workload", or "runner_route".
  • For Method targets: name MUST be a non-empty string. (The build checks that the named handler exists and declares a permission; a missing method at dispatch returns 502 Bad Gateway.)
  • For Volume targets: volume_name MUST be one of the actor’s ingress.http static_volumes; pays MUST be "actor"; fallback_status MUST be a valid HTTP status code (100–599).
  • For Runner targets, handler MUST be a non-empty string; affinity MUST be none / caller / session, and affinity = "caller" REQUIRES auth = "account"; auth MUST be "public" or "account"; a mount with owner = "caller" REQUIRES auth = "account"; timeout_ms MUST be ≤ MAX_RUNNER_TIMEOUT_MS (§10). Current dispatch additionally needs an explicit runner pin and a usable advertised endpoint (§6.2); this is not a runner_bindings check. Target design, unimplemented: requires must be covered by a binding, an omitted selector inherits the bindings, the eligible set must be non-empty, and any pin must belong to that set. Binding-scoped actor-owned mount authorization and caller-grant checks/issuance at dispatch are also target design (§7.5, §8.14). Do not pass runner_bindings at deployment: the manifest validator rejects this unknown parameter, including [].
  • For Workload targets, route-table/config validation is structural: workload MUST be exactly 32 bytes (a text form MUST be canonical 64-char lowercase hex; wrong length or noncanonical encodings reject); auth MUST be "public" or "account"; idle_timeout_ms MUST be in 1..=MAX_WORKLOAD_IDLE_TIMEOUT_MS; max_connection_ms, if present, MUST be at least 1; and max_concurrent_streams, if present, MUST be in 1..=MAX_CONCURRENT_STREAMS_CEILING (§10). Registry existence, ownership, route eligibility, and endpoint validity are establishment-time checks (§8.15), not route-load checks: a transiently unavailable registry MUST NOT make the Gateway discard an otherwise valid actor route table.
  • pays MUST be "actor" or "caller".
  • When pays = "caller": price MUST be present and non-empty; it is interpreted per CIP-18 at dispatch. When pays = "actor": price MUST be absent.
  • timeout_ms, when present, MUST be ≤ MAX_RUNNER_TIMEOUT_MS.
  • access MUST be present and one of the five Access forms; an Allowlist MUST satisfy CIP-37 §7.2. Missing access rejects the table.
  • For RunnerRoute targets: the declaration MUST decode and validate per CIP-11, its verb, path and enabled flag MUST equal the outer route’s, pays MUST be "actor", and the route MUST carry no price, mode, timeout_ms or fallback_response.
  • No two routes may share a (verb, path).
  • The sponsorship value MUST be present exactly when the table contains a RunnerRoute target, and MUST validate per CIP-11.
Because the node admits only valid tables, a table that fails Gateway validation means the Gateway is older than the node’s schema. The Gateway logs a warning and keeps serving the previously cached table for that actor; an actor with no previously cached table falls back to all-CIP-14 dispatch. Whichever table applies, the CIP-37 site gate admits each request before any dispatch.

6.9 Installation

The routes table is fixed when code is installed: produced by the build, carried by the instruction that installs the code, validated by the node, and written by the chain. The installing instructions carry an optional
as the final field of DeployActor, the final field of UpgradeActor, and the third argument of the actor-initiated upgrade_self(code, manifest?, routes?). Its bytes pay the per-byte deploy or upgrade rate (CIP-3’s governed gas.deploy.* rates; initially 12 Cycles + 40 Cells) but not the 10-Cycle AST parse. The parse applies to code bytes only, because routes are never parsed. The node validates routes (§6.8) against the manifest being deployed, resolves every Volume target’s volume_id (below), and writes both slots in the same write set as the actor’s code, before the init handler runs. An invalid table rejects the deployment; a failing init handler reverts the slots with everything else. An upgrade validates routes against the new manifest when it carries one and the current manifest otherwise, then replaces both slots in the same write set as the new code. An upgrade without routes removes both slots: the installed routes always describe the code that is running. UpgradeActor is issued by a genesis system deployer, and upgrade_self requires sys.upgrade, which only system deployers may grant; any other actor changes its routes by deploying a new actor. Native runner-route sessions already open keep the declaration they were admitted under (CIP-11). fork_actor copies the parent’s code and storage; the child carries the parent’s installed routes and sponsorship unchanged. For each Volume target the node writes volume_id into the stored table: the declared volume_id when the declaration names one, otherwise keccak256(installer || volume_name) (CIP-9 §11.1), where installer is the deploying account for a deployment and the actor’s owner for an upgrade. The Gateway serves only the stored volume_id; later changes to the actor’s owner do not move a mount. The host refuses state_set, state_set_checkpoint and state_delete on __cowboy/routes and __cowboy/route_sponsorship from every frame, including the deploy init handler and reserved-state writes. The install path is the only writer. The build reads an actor’s declared routes and lowers them to a RouteInstall:
  • method routes from @get, @head, @post, @put, @patch, @delete and @route decorators on the Actor subclass’s handlers;
  • Volume, Runner and Workload routes from mount(...), runner(...) and workload(...) entries in the class-level routes tuple or list.
Declarations are read statically: each argument is a literal or an SDK constructor call whose arguments are literals. The build rejects a route whose handler does not exist or declares no permission (@public / @callable_by), a mount(...) whose volume the manifest does not grant in static_volumes, and any table that fails §6.8. It records the table’s digest with the artifact so a reviewer sees exactly what the deploy installs. A deploying tool may supply RouteInstall bytes that are not lowered from source. For example, a room provisioner bakes one instance’s owner, secret references, metering key and bundle hashes into its CIP-11 native route declarations. The node applies identical validation. Because an actor’s address does not depend on its routes, a provisioner can derive the address and bake actor-scoped references before deploying; changing them later is an upgrade. A project declares the directory that holds its static assets and the public volume that serves them. cowboy deploy publishes the directory to that volume before submitting the deployment and refuses to deploy when the manifest does not grant the volume in static_volumes. Republishing the volume later updates the served assets without changing routes or code. Method and Runner route prices that change at runtime live in the CIP-18 price_table. A native runner route’s price is fixed by its declaration (CIP-11). Installing a deployment or an upgrade advances the actor’s state root. Gateways pick up the new table within MANIFEST_POLL_INTERVAL blocks.

7. Entitlement Extension

7.1 New Parameters

This CIP extends the ingress.http entitlement (CIP-14 §6.2) with two new parameters: static_volumes is an array of volume-name strings. Per-volume max_cache_bytes bindings are a proposed extension (§7.4). The existing CIP-14 parameters (allowlist_methods, max_request_bytes, max_response_bytes, max_query_cycles) are unchanged and continue to govern Method-target route behavior. max_static_response_bytes is separate from max_response_bytes because static assets (images, video thumbnails, font files) are typically much larger than dynamic API responses. static_volumes names must be valid CBFS volume names; *, empty names, . and .. are invalid. The response cap must be in 1..=104_857_600 (100 MiB). Both parameters are actor-controlled configuration and are exempt from the upgrade-subset monotone-narrowing rule: an upgrade retaining ingress.http may add, grow, shrink, or remove them. The replacement manifest still passes name, type, and cap validation. Other ingress.http parameters retain their existing upgrade restrictions; this is a narrow exception to CIP-6 §12.7. When max_static_response_bytes is absent, the Gateway applies the 10 MiB default, so removing it on upgrade resets the cap to that default rather than making it unbounded.

7.2 Example Manifest

7.3 Enforcement

  • When the node installs a routes table (§6.9), every Volume target MUST name a volume in the manifest’s static_volumes; otherwise the deployment or upgrade is rejected. The node writes the resolved volume_id into the stored table. Because the table changes only through that path, the Gateway serves the stored volume_id without re-checking membership per request.
  • The Gateway applies max_static_response_bytes, using the 10 MiB default when absent. Objects larger than that limit return HTTP 413 Content Too Large.
  • The Gateway’s serving authority follows the volume’s CIP-9 status (§8.13). If a mounted volume is DELETED or GARBAGE_COLLECTING, the Gateway returns the corresponding HTTP status without invoking the actor. Restoring or replacing the volume resumes serving.

7.4 Proposed Per-Volume Cache Bindings

Per-volume max_cache_bytes is not present in the on-chain string-array representation and is not enforced through entitlement reads by the Gateway. The earlier object-binding proposal placed cache limits in the entitlement to declare a Gateway resource quota. Such a quota would require its own schema, validation, upgrade policy, and Gateway enforcement; rules-v2 does not provide those guarantees.

7.5 Runner Bindings

The route-binding design below is unimplemented. runner_bindings is absent from the current ingress.http registry schema. Manifest validation rejects it as an unknown parameter, even when the value is []; omitting it does not materialize a binding or disable a separately pinned route. The current Gateway requires an explicit runner pin and advertised endpoint (§6.2). It does not implement the binding/selector intersection, health-based selection, affinity, or binding-scoped mount issuance described below. The parameter, RunnerBinding model, and deployment/request-time enforcement rules in the remainder of this section specify the target design. Existing job mount machinery does not mean these route-specific authorization checks have shipped. Runner-target routes require the actor to authorize, at deploy time, which runners may serve them and which actor-owned volumes those runners may be issued CapTokens for, through the ingress.http parameter runner_bindings:
CIP-9’s mount-allowlist grants access to a MountPrincipal (Actor or Account). It never grants access to a runner directly. The runner holds no standing grant; at dispatch it receives a scoped CapToken (and, for a private volume, a CBSS-sealed DEK) issued by the same dispatcher path that attaches volumes to a job. runner_bindings does not create a CIP-9 grant. It authorizes the Gateway to dispatch this actor’s Runner routes to runners in the bound pool / capability set and bounds which actor-owned volumes a route may reference. Runner pools are CIP-2 Runner pools, whose membership is granted by the pool’s owner (CIP-2 §7.3). The pool-based authorization and selection below use that membership. The following target enforcement is unimplemented for these route bindings:
  • Deployment-time (actor-owned mounts). Each binding’s pool / capabilities MUST be ones the actor is entitled to (CIP-2). Each owner = "actor" mount volume MUST be owned by the deploying account (or carry an Actor-principal grant to it). A route’s requires MUST be covered by some RunnerBinding (its pool / capabilities a subset of the binding’s), and its owner = "actor" mounts MUST appear in that binding with the route’s mode and canonicalized path_prefix within the grant. Runners chosen at dispatch (§8.14) must be RAS-registered, healthy, and advertise a route-serving endpoint.
  • Request-time (caller-owned mounts). owner = "caller" mounts are authorized by the caller, not the actor: the caller must own the volume and have granted the agent actor (MountPrincipal::Actor) mount access via the CIP-9 allowlist. After the runner authenticates the caller (§8.14), the dispatcher issues the runner a CapToken (+ sealed DEK) for that caller’s volume under the actor principal; the authenticated caller’s identity is what selects which caller-owned volume. This lets one endpoint give every caller scoped access to their own owned storage without the actor hosting it.
Actor jobs already use CIP-9 allowlist grants to a principal, dispatcher-issued per-runner CapTokens, and CBSS threshold-seal of the DEK for private volumes. What this CIP adds is routing a request through that issuance path and selecting a caller-owned volume from the authenticated HTTP caller per request.

8. Gateway-to-Relay-Node Fetch Protocol

8.1 Request Flow

When a Gateway receives an HTTP request that resolves to a Volume-target route:

8.2 Gateway-Side Caching

The Gateway maintains a layered cache: Layer 1a is the per-volume metadata cache. The Gateway keeps it warm for every active volume.
Keyed by volume_id. Refreshed when the on-chain manifest_root changes. Layer 1b is the per-actor routes cache. The Gateway keeps it warm for every active actor.
Keyed by actor_address. Refreshed when the verified __cowboy/routes value changes (§8.12). Layer 2 is the object cache, a bounded LRU cache of reconstructed objects.
Keyed by (volume_id, object_path). MAX_GATEWAY_CACHE_BYTES bounds the total across all volumes. Per-volume max_cache_bytes from an entitlement is proposed but unimplemented (§7.4). Eviction follows LRU with frequency weighting. The Gateway retains frequently accessed objects longer.

8.3 Cache Invalidation

Cache invalidation is driven by changes to the on-chain StorageCommitment.manifest_root. When volume contents change (new deploy via commit_manifest), the manifest root changes.
  1. The Gateway polls the on-chain StorageCommitment.manifest_root for each actively-cached volume every MANIFEST_POLL_INTERVAL blocks (default: 6, ~6 seconds at 1 block/sec).
  2. If manifest_root has changed: a. Fetch the new volume manifest from any Relay Node. b. Diff old and new manifests to identify changed, added, and removed objects. c. Evict all changed and removed objects from the object cache. d. Update the per-volume metadata cache (content-type map, cache config, CORS config).
  3. If manifest_root is unchanged, all cached objects remain valid.
Per-actor routes (Layer 1b) re-read and re-verify __cowboy/routes each poll; see §8.12. Relay Nodes provide no push notifications for storage changes. Subscribing to on-chain events for every cached volume creates scaling concerns. Polling the manifest_root (a single 32-byte on-chain read) suffices because static assets tolerate invalidation delays of a few seconds.

8.4 Relay Node RPC

Gateways interact with Relay Nodes using the existing CIP-9 GET_SHARD RPC (CIP-9 §16.3) plus GET_MANIFEST for direct manifest retrieval.

GET_MANIFEST

Retrieves the canonical serialized volume manifest for a given volume.
CIP-9 §5.3.2 defines this RPC’s shape, authorization and verification alike. This section describes only what is specific to a Gateway. Duplicating the schema here is what let the two documents drift; the block above is a convenience copy and CIP-9 wins on any disagreement.
  • A Gateway reads only public volumes with GET_MANIFEST. It is an unauthenticated public reader (§8.13 and CIP-9 §7.6.3) and holds no CapToken or DEK. A private manifest is read node-by-node via GET_SHARD by a DEK holder. CIP-9 §5.3.2 distinguishes this assembly restriction from the reference implementation’s admission of the volume owner’s READ_WRITE token; grant-scoped tokens do not admit GET_MANIFEST.
  • The Gateway, as caller, supplies the root. It reads manifest_root, erasure_k and erasure_m from the volume’s on-chain StorageCommitment and passes them in the request. The response carries no root: the Gateway MUST rebuild the manifest from the returned entries, recompute its DAG root, and reject unless it equals the root it supplied. On mismatch, try another Relay Node and mark the offending one suspect.
If GET_MANIFEST is not available on a given Relay Node, the Gateway MAY fall back to node-by-node traversal via GET_SHARD from the on-chain root, fetching each manifest node at manifest_node_shard_id(volume_id, locator) as defined in CIP-9 §5.3.2 and the storage whitepaper’s Manifest section. There is no well-known single manifest blob fallback. A Relay Node does not hold the whole manifest, and no push propagates one to it: each DAG node is itself an erasure-coded object spread across a placement set, and a relay stores only its assigned shard indices. It answers GET_MANIFEST by assembling the DAG from peers, or from a cache it built for itself; see CIP-9 §5.3.2, “Server-side model”. A relay that cannot assemble it does not implement the RPC, and the Gateway falls back to node-by-node traversal as above.

GET_SHARD (existing CIP-9 §16.3)

volume_id is required, not decorative: CIP-9 §7.6.2/§7.6.3 make an anonymous read conditional on the shard’s recorded volume matching the volume the request names, and a request that names none is refused. The response is the shard bytes alone. The relay returns no hash, because a relay-chosen hash would verify nothing. The Gateway verifies each shard against the shard_hash carried in the object’s own descriptor from the manifest it has already verified against the chain (§8.5). Shards that fail verification are discarded and replacements are fetched from alternative Relay Nodes. For public volumes, no CapToken is required (CIP-9 §7.6.3), subject to the status gate there: a volume that is not ACTIVE or GRACE_PERIOD is not served anonymously.

8.5 Canonical Manifest Serialization and Verification

GET_MANIFEST returns bincode(BTreeMap<String, ManifestEntry>), an entry map ordered by path. The map is not the stored DAG encoding and its serialized bytes MUST NOT be hashed directly as the manifest root. Verification MUST rebuild the canonical public manifest DAG specified in CIP-9 §3.1: group entries into leaf nodes, build interior nodes, and compute each locator from its canonical stored bytes. The top node’s locator is the computed root. A flat ShardMap list or an RFC-6962 tree is not this format.
  1. Read manifest_root, erasure_k and erasure_m from the volume’s authoritative on-chain StorageCommitment. Require public visibility and a serveable status as specified in CIP-9 §5.3.2.
  2. Fetch GET_MANIFEST { volume_id, manifest_root, erasure_k, erasure_m }, using the values read in step 1.
  3. Decode the entry map with a bincode byte budget bounded by the received payload length and construct its canonical path index using CIP-9 §5.3.2, Entry-map decoding and lookup. Every lookup key must come from the corresponding value’s entry.path(). Reject inconsistent keys or duplicate entry paths, or normalize them exactly as specified there before verification.
  4. Rebuild the canonical public DAG from that canonical path index and compute its root.
  5. Require the computed root to equal the authoritative root from step 1. On mismatch, reject the manifest without caching or serving its content and try another Relay Node.
The response carries no root. A root supplied or echoed by the same relay is not a substitute for the independent chain commitment. After verification, the Gateway MUST use that same canonical path index for lookups and caching, never the original wire keys. It resolves file content and shard hashes from the file’s ObjectDescriptor; a PlacementRecord supplies shard locations, not the content trust anchor.

8.6 Integrity Verification

The Gateway MUST verify every layer of the integrity chain:
  1. Verify the fetched manifest against the on-chain manifest_root using the Merkle verification protocol (§8.5). A manifest that does not match the on-chain root MUST be rejected.
  2. For each fetched shard, verify BLAKE3(shard_bytes) == shard_hash from the verified ObjectDescriptor. Shards that fail verification are discarded; the Gateway fetches a replacement from an alternative Relay Node.
  3. After Reed-Solomon reconstruction, verify BLAKE3(reconstructed_bytes) == content_hash from the verified ObjectDescriptor. If verification fails, the Gateway MUST NOT serve the object and MUST return HTTP 502 Bad Gateway.

8.7 Parallel Fetch and Hedging

For latency-sensitive serving, the Gateway employs adaptive parallel fetch:
  1. Request K shards from the K lowest-latency Relay Nodes (based on historical RTT for that volume’s shard assignments).
  2. If any shard request takes longer than HEDGE_THRESHOLD_MS (default: 100ms), issue a speculative request to an alternative Relay Node for a parity shard. Use whichever response arrives first.
  3. The Gateway prefers data shards (indices 0..K-1) but accepts parity shards. Any K of the K+M shards suffice for reconstruction.
  4. Allow no more than MAX_CONCURRENT_SHARD_FETCHES (default: 8) outstanding shard requests per object reconstruction.

8.8 HTTP Response Headers

When serving a static asset, the Gateway sets the following headers:
Clients requiring strict consistency MAY send X-Cowboy-Manifest-Root: <hex> as a request header; the Gateway returns 409 Conflict if its cached manifest does not match.

8.9 Conditional Requests

  • For If-None-Match, the Gateway compares the client’s ETag against the cached object’s content_hash ("b3_" + hex(content_hash), §8.8) under RFC 7232 §3.2 weak comparison. If it matches, return 304 Not Modified with no body. The decision uses only the content-hash ETag. The manifest is deliberately not consulted here: byte-identical content under a changed manifest_root still returns 304, which is HTTP-correct because the representation the client holds is unchanged. Manifest-root coherence is enforced separately by the X-Cowboy-Manifest-Root request pin, which yields 409 on mismatch (§8.8), not as a condition on the ETag match; the 304 still echoes x-cowboy-manifest-root so a pinning client still observes a manifest change.
  • The Gateway does not directly support If-Modified-Since. Volume objects do not have per-file modification timestamps. Clients SHOULD use If-None-Match (ETag-based) for conditional requests.

8.10 Compression

Gateways SHOULD support Accept-Encoding: gzip, br and compress responses on-the-fly for compressible content types: text/html, text/css, application/javascript, application/json, image/svg+xml, text/plain, application/xml. Binary content types (image/png, image/jpeg, font/woff2, application/octet-stream) MUST NOT be compressed. They are already optimally encoded and compression wastes CPU. Gateways MAY cache compressed variants alongside the uncompressed object to avoid re-compressing on subsequent requests.

8.11 Relay Node Bandwidth Economics

CIP-9 specifies that Relay Nodes earn storage fees proportional to the shards they store (CIP-9 §10). This CIP introduces Gateways as readers that may fetch many shards for popular static sites. The bandwidth cost model:
  • The volume owner (actor’s account) pays for Relay Node storage via per-epoch storage fees (CIP-9 §10). These fees cover the cost of storing and serving shards.
  • Gateways do NOT pay per-shard-fetch fees directly. The bandwidth cost is absorbed into the Relay Node’s storage fee revenue, analogous to how a CDN origin server absorbs bandwidth from CDN edge pulls.
Introducing per-read micropayments between Gateways and Relay Nodes would add significant protocol complexity (payment channels, per-request accounting) for marginal benefit. The storage fee model already compensates Relay Nodes for both storage and bandwidth. Nodes that serve more popular volumes earn proportionally more storage fees because those volumes persist (the owner keeps paying). If a volume is not worth paying storage fees for, it gets garbage-collected. Relay Nodes MAY enforce local rate limits on GET_SHARD and GET_MANIFEST requests to prevent bandwidth abuse:
  • Per-source-IP rate limiting (suggested: MAX_SHARD_READS_PER_SECOND = 1000 per IP).
  • Per-volume rate limiting (suggested: MAX_SHARD_READS_PER_VOLUME_PER_SECOND = 500 per volume per IP).
  • Total bandwidth throttling per connection.
These limits are locally enforced by each Relay Node and are not protocol-mandated constants. Relay Node operators MAY adjust them based on their infrastructure capacity. A follow-on CIP may introduce actor-funded bandwidth budgets. Actors would deposit CBY into a bandwidth pool that compensates Relay Nodes for read traffic proportional to actual serving volume. This would align incentives more precisely but requires a per-read accounting mechanism that is not justified in this initial CIP.

8.12 Routes Fetching (Gateway ↔ Full Node)

The routes table is fetched from the actor’s KV state, not from a Relay Node. The Gateway reads it with GET_STATE (CIP-17) against a full node; Runners do not serve GET_STATE yet (CIP-17 §1).
  1. The Gateway fetches via GET_STATE(actor_address, "__cowboy/routes").
  2. The Gateway verifies the response per CIP-17 §5.3: state_root equals the unified state root of a block header it trusts at block_height, and the QMDB/MMR operation proof (CIP-17 §5.2) authenticates the (actor_address, key) operation against that root. Cowboy has no per-actor storage trie or per-actor state root.
  3. If both checks pass, the Gateway deserializes value as Routes and validates per §6.8.
  4. The verified routes table is cached, keyed by actor_address.
If the response cannot be verified, the Gateway MUST reject it and try another full node. The Gateway re-reads __cowboy/routes every MANIFEST_POLL_INTERVAL blocks and replaces the cached routes table when the verified value changes. If value is empty (the actor declares no routes), the Gateway falls back to all-CIP-14 dispatch: every request the CIP-37 site gate admits reaches the http.request handler. State reads against a full node are part of normal protocol operation (block production, RPC) and do not incur additional fees. Per-read rate limits MAY be enforced locally by full nodes (suggested: same MAX_SHARD_READS_PER_SECOND as Relay Nodes).

8.13 Serving Authority by Volume Status

Gateway HTTP serving authority follows the CBFS volume lifecycle (CIP-9 §13) through ACTIVE, GRACE_PERIOD, DELETED, and GARBAGE_COLLECTING in that order. Continuing to serve in GRACE_PERIOD lets the owner top up storage fees while the Gateway serves responses with an advisory header instead of abrupt 503s. The hard halt happens at DELETED (intentional removal) and GARBAGE_COLLECTING (irreversible). This bounds the “free CDN” externality (Gateway caches continuing to serve after the owner stops paying) within STORAGE_GRACE_EPOCHS per CIP-9.

8.14 Runner-Target Dispatch (Gateway → Runner)

For a Runner-target route (resolution §6.6 step 7), the Gateway does not invoke the actor’s PVM. It proxies the request off-chain to a runner and relays the response. The current Gateway resolves only the explicit runner pin to its advertised endpoint; absent pins or unavailable endpoints return 503 (§6.2). The eligible-set algorithm below is target design in its entirety: job filters, runner_bindings/requires intersection, pin-in-set validation, HRW affinity, and load balancing are not current selection guarantees. The binding-scoped mount issuance below is likewise unimplemented. A forwarded mount declaration is not evidence of a scoped CapToken or DEK grant. In the unimplemented target design, the Gateway would resolve the route to a runner per request. It reads runner registry state (as it already does to fetch routes) and applies the same eligibility filters the dispatcher applies to jobs (the registry’s filter_job_candidates): capability / job-type, the CIP-2 required_runner_pool entitlement (CIP-2 §7.3), TEE, rate card, active-job capacity, and health / heartbeat (derived from last_heartbeat). It then makes the pick itself:
  1. Build the eligible set E = runners passing those filters, intersected with the route’s requires, the actor’s runner_bindings entitlement (§7.5), and current RAS health. (requires.region is checked route-side against the runner’s advertised capabilities.regions; the job filter doesn’t apply region today.) If E is empty, return 503 Service Unavailable.
  2. If the optional runner pin is set: use it if it is in E, else 503.
  3. Else if affinity ≠ none: pick argmax(r in E) of H(affinity_key, r.id) using rendezvous (HRW) hashing. The same key maps to the same runner while it stays in E; when a runner leaves E, only the keys that were on it move to their next-best, leaving every other key undisturbed. The affinity_key is the caller account (caller), a client-supplied session id (session), or unused (none).
  4. Otherwise, spread across E by selecting the least-loaded runner by advertised active-job count, or by round-robin selection.
The selected runner advertises a route_serving_endpoint in its RAS registration. This CIP requires that new registration field. The Gateway reuses existing registry data and mirrors the job-dispatch eligibility filters where they exist; the route-only additions are region filtering, HRW affinity, optional route-pin validation, and the route_serving_endpoint proxy. The Gateway dispatches to the selected runner’s route_serving_endpoint:
The runner maps (actor_address, handler) to deployed code; it MUST already have a handler registered for (actor_address, handler) before the Gateway may dispatch. Deployment and registration are out of scope. The runner returns 502 if the handler is absent. The runner returns a normal HTTP response (status, headers, body or chunked stream); the Gateway relays it verbatim, applying only the CORS rule (§9.4), timeout_ms, and the 502/504 mapping. For auth = "account" the Gateway is untrusted transport and asserts no caller identity; the identity it attests for access (CIP-37 §9) does not replace the runner’s check. For auth = "account", the caller uses a new signed-request scheme. The payment-specific EIP-712 SessionVoucher does not authenticate the caller. The caller signs, with their Cowboy-account secp256k1 key, a canonical preimage over:
The preimage MUST be domain-separated (a fixed tag distinct from every other Cowboy signing context) and MUST length-prefix each variable-length field, so that no two distinct field assignments can serialize to the same bytes (otherwise e.g. handler="a",verb="bc" and handler="ab",verb="c" would share a signature). The signature is over keccak256(preimage), recoverable to the caller’s account. The recovered signer is the caller, which may be any Cowboy account, authenticating as itself and not as the actor. A single endpoint serves every authenticated user under their own identity (the multi-user model). The runner recovers the signer (reusing the runner’s existing secp256k1 recovery utilities), verifies chain_id and network against its own deployment (rejecting a signature minted for another chain, preventing cross-deployment replay that per-runner nonce stores cannot prevent), checks expiry (a bounded validity window) and the single-use nonce for replay, forwards the recovered caller to the handler, and binds the request to that account; on any failure it returns 401, which the Gateway relays. For auth = "account" the Gateway never asserts caller identity. (host is gateway-forwarded and not independently verifiable by the runner under the untrusted-gateway model, so it is not bound.) The recovered account is what authorizes a caller-owned mount (§7.5). The runner self-enforces auth from RouteContext.auth: a route with auth = "account" and no account_sig is rejected 401 even when a request reaches the runner directly. The Gateway’s account_sig presence check supplements this runner check. In the unimplemented target design for route-binding mount issuance, the runner would hold no standing grant; the dispatcher issues it a CapToken (and, for a private volume, a CBSS-sealed DEK) per mount, scoped to the mount’s volume, mode, and path_prefix and never broader than the relevant grant. The same issuance path attaches volumes to a job:
  • For owner = "actor", the dispatcher issues the token under the actor principal, bounded by the actor’s runner_bindings (§7.5).
  • For owner = "caller", the dispatcher issues the token under the actor principal for the authenticated caller’s volume. This is valid only because the caller granted the agent actor mount access (§7.5) and the runner verified the caller’s signature. Writes commit back to CBFS (advancing the volume manifest_root) as normal, leaving the data owned by the caller.
Consistent with current Gateway behavior, v0 buffers the request body (subject to the ingress.http max_request_bytes cap) before forwarding. This lets body_sha256 bind the signed request. The runner executes the handler off-chain (no consensus, no deterministic-PVM constraint: LLM inference, outbound HTTP, streaming) within timeout_ms, and the Gateway streams the response back as it arrives. Streaming request bodies (with a stream_session_id-bound signature) are deferred. On timeout_ms expiry the Gateway returns 504 Gateway Timeout; on a runner transport/handler error, 502 Bad Gateway. A resolved client-paid model is gated exactly as for Method (§6.6): the Gateway enforces CIP-18 (402) before forwarding. Metering of the off-chain work itself (tokens, wall-time) is a runner/RAS concern, out of scope here. Runner-target CORS follows the Method rule (§9.4): the runner’s response headers are authoritative; the Gateway fills CORS only when the runner sets none. In v0, the runner is trusted to execute the route faithfully, as for any runner to which an actor dispatches a job. Verifiable / multi-operator runner serving (attested execution, on-chain settlement) is deferred (§13). CIP-9 mount-allowlist grants to a principal, dispatcher-issued per-runner CapTokens, and CBSS DEK seal for private volumes already ship. This CIP adds the Runner route target; the proxy from the Gateway to the runner; a route-serving endpoint advertised in RAS registration; a route caller-auth signing scheme (distinct from the payment voucher); and selecting a caller-owned volume from the authenticated HTTP caller per request.

8.15 Workload-Target Dispatch (Gateway → Workload)

For a Workload-target route (resolution §6.6 step 8), the Gateway relays the connection to one long-lived registered workload. There is no per-request selection: the route names a workload registry record, and the record names the backend. A persistent workload carries a control-plane workload registry record. This CIP consumes five of its fields, workload_id (what Workload.workload names), owning_actor (what the §6.8 validation binds routes to), serving_endpoint (where the Gateway relays), reporter (the claiming Runner), and host_pool (the CIP-2 Runner pool its claim came through); the Gateway reads the reporter’s pool entitlement, its slot binding and its accountable registration (the host Runner’s RunnerRegistration for a bound slot, its own otherwise, CIP-10 §17.3.5) at the same proof point to decide whether the workload is still eligible and whether the endpoint must be public (CIP-10 §17.4.1 and §17.3.4). It also checks route eligibility: the Gateway relays only to a workload whose desired_state is Running and whose current attempt is either Running or a finalized Prepared attempt within its preparation lease, with a fresh liveness lease (CIP-10 §17.4.1); an ineligible workload returns 503. The initial record carries volume mounts only. Secrets and egress capabilities are deferred. There is no route-binding field; route binding lives in the actor’s __cowboy/routes table. A Workload target has no mounts of its own. Workload-target routes are a hard dependency on that registry: no record, no route. The actor declares a Workload target, installed in its proof-backed __cowboy/routes table (§6.9). The Gateway resolves that table through its normal actor-route cache and requires the registry record’s owning_actor to equal the URL actor at every connection establishment. An upgrade can replace a Volume target with a Workload target under the same actor URL, without a Gateway configuration edit or restart. The operator may still configure fallback routes for infrastructure-owned cases; their schema is:
The embedded Workload target shape is the same for actor-owned and operator fallback routes. expected_workload_owner exists only in operator configuration; an actor-declared route cannot override the registry owner check. Operator-configured workload routes remain owner-only under CIP-37, even on a published site. Public workload routing requires the owner-approved canonical manifest and its exact target binding; a local configuration entry cannot inherit an absent-table publication approval. The operator configuration key is (actor, verb, path). A static entry belongs to a specific actor’s URL space, never a hostless global. Duplicate keys are invalid. Ownership is validated at every establishment: an actor-declared route MUST resolve only a record whose owning_actor equals that actor. For an operator route, absent expected_workload_owner, the named record’s owning_actor MUST equal the entry’s actor; present, owning_actor MUST equal expected_workload_owner, which MUST differ from actor. This is the explicit cross-owner form (one actor’s URL space fronting another principal’s workload), with a typed principal. A record later repointed to a different owner fails closed (§8.15 tests require the record-swap negative). Collision depends on semantic overlap, not key equality. An operator static entry collides when its verb set intersects an actor-declared route’s verb set (ANY intersects every verb) and the two path patterns can match any common path (wildcard, parameter, and literal segments considered; /api/* overlaps /api/admin; ANY /chat overlaps GET /chat). The Gateway MUST reject such entries when loading configuration against the current actor-route snapshot. Because actor routes can change after startup, it MUST recheck overlap against the current actor-route snapshot before serving any operator fallback candidate. If a newly observed actor route overlaps an already loaded static workload route, the actor-declared route wins and the Gateway MUST reject the conflicting fallback while that actor-route snapshot applies, emitting a high-severity diagnostic identifying both patterns when the fallback is attempted. A stale cache or lookup order MUST NOT let operator configuration override a consensus Method route or its payment policy. Both binding modes share the dispatch semantics below, so promoting a static route to an actor-declared one changes where the route lives, not how it serves. The registry serving_endpoint is a base URL. The Gateway appends the matched request path (after applying strip_prefix; preserving a leading /) to the endpoint’s base-path prefix and forwards the original query string verbatim. It MUST NOT follow backend redirects. It forwards end-to-end request headers, replaces Host with the backend authority, removes the standard hop-by-hop headers and every header named by Connection, and adds X-Cowboy-Route-Context; response headers receive the same hop-by-hop filtering before relay. The original Origin is end-to-end and MUST NOT be rewritten. The Gateway forwards Authorization byte-for-byte. It MAY parse and validate the Payment scheme for CIP-18 gating; other application schemes remain opaque. It MUST NOT log the header value. For a plain or streamed HTTP exchange the Gateway buffers the request body per §8.14’s max_request_bytes rule, establishes the backend response within WORKLOAD_CONNECT_TIMEOUT_MS, then relays the response body unbuffered: each non-empty backend body chunk is yielded downstream as it arrives, without applying the Runner response-byte cap. SSE (Content-Type: text/event-stream) is the motivating case: events MUST NOT be accumulated into a complete body, deliberately coalesced, or compressed by the Gateway. idle_timeout_ms bounds response-body silence after headers arrive. Each non-empty body chunk resets it; on expiry the Gateway drops the body stream. max_connection_ms, when set, starts when the route is admitted and hard-caps establishment plus the response body’s lifetime. Client disconnect MUST immediately drop the backend response/body, which cancels upstream reads, and release the route’s concurrency permit. For a valid WebSocket upgrade request the Gateway applies auth / pays gating, resolves and checks the workload record, and completes the backend handshake before sending 101 Switching Protocols to the client. A backend HTTP rejection (including 401) is relayed as an HTTP response; timeout and transport failures use the mappings below. The Gateway forwards the client’s Sec-WebSocket-Protocol offers and returns only the protocol selected by the backend. The Gateway does not negotiate WebSocket extensions: it removes Sec-WebSocket-Extensions on both handshakes rather than claiming an extension independently on either leg. After both upgrades, the Gateway terminates the two WebSocket legs and relays data messages and close semantics in both directions without inspecting application payloads. Message bytes and text/binary opcode MUST be preserved, but fragmentation and masking are hop-local and MAY be re-encoded. Ping and pong are handled hop-locally by each terminated leg (not forwarded, which would create duplicate automatic pong responses) and count as traffic for idle_timeout_ms; silence means no frame in either direction. max_connection_ms starts at route admission and includes both handshakes. On backend transport death without a close frame the Gateway sends the client close code 1011 and closes; a normal backend close is forwarded, and client disconnect or close closes the backend side. Streaming request bodies outside an upgraded connection remain deferred (§13). auth = "account" follows the §8.14 signing scheme’s construction, with length-prefixed fields, keccak256, secp256k1 recovery, chain_id/network binding, expiry, and a single-use nonce. It uses a distinct fixed domain tag for workload route authentication, the literal ASCII bytes "cowboy/cip15/workload-route-auth/v1", pinned here so independent client and workload implementations can produce matching golden vectors (§8.15 tests require them, alongside the cross-target negatives). The workload record id (32 bytes) occupies the slot handler occupies in §8.14; for a body-less upgrade request body_sha256 is the hash of the empty body. The distinct tag means a signature minted for a Runner route can never validate on a Workload route or vice versa, even if a handler string collides with a workload id. The two targets have separate verifiers and nonce stores, so shared-domain reuse would replay once in each (§8.15 tests require the cross-target negative vector). The Gateway forwards X-Cowboy-Route-Context: base64url(CBOR(WorkloadRouteContext)), where WorkloadRouteContext contains actor_address: bytes20, workload: bytes32, verb: string, the forwarded path: string, path_params: list<(string,string)>, authenticated_sender: bytes20? (CIP-37 §9), auth, optional payment_proof, optional account_sig, optional account_expiry, optional account_nonce, chain_id: u64, and network: string. It has no handler or mounts fields. payment_proof is only raw client X-Payment header material when supplied; it is not an authenticated payment result and may be absent even when another payment credential was accepted. The workload verifies the signature and self-enforces auth from this context. The Gateway’s complete-field presence check supplements that verification; the Gateway asserts no caller identity. Per-message authentication inside an established stream is the workload’s own concern (it holds the authenticated identity from establishment). A resolved client-paid model gates establishment exactly as for Method (§6.6): 402 before the upgrade or first streamed byte. A successful payment gate authorizes establishment of that connection; a pass or subscription may clear it without a new per-connection charge. The streaming-payments protocol handles usage-metered settlement above this transport. Metering tokens, messages, or wall-time is out of scope here. SSE and plain HTTP responses follow the Method rule (§9.4): the workload’s response headers are authoritative; the Gateway fills CORS only when the workload sets none. Browsers do not enforce CORS on WebSocket connections. An auth = "public" WS route is reachable from any origin’s JavaScript. Therefore the workload MUST validate the Origin header itself for browser-facing endpoints (§12.12), and user-bound streams SHOULD use auth = "account". A Gateway deployed behind a load balancer or reverse proxy (ALB, nginx) MUST have that layer configured for long-lived streams, or the layer silently breaks what this section specifies: idle timeout above the workload’s heartbeat interval (or the LB kills healthy connections), response buffering disabled on streaming routes (or SSE events arrive in bursts after the fact), and request-body size caps reviewed (an intermediary defaulting to small body caps rejects requests far below the application’s own limits, as observed on public RPC endpoints). Operators configure these settings in their deployment; the settings are outside the protocol parameter set. For actor-declared routes, the concurrency key includes actor, verb, path, workload ID, and route limit so concurrent establishments of the same route share a cap; an updated workload binding receives its own cap. Operator fallback entries use their static (actor, verb, path) identity. The Gateway acquires a permit before registry resolution or backend dialing and holds it through the complete HTTP body or WebSocket lifetime; handshake attempts therefore count against the cap and cannot form an unbounded slow-establishment queue. At max_concurrent_streams (default DEFAULT_MAX_CONCURRENT_STREAMS) it returns 503 Service Unavailable immediately. For every admitted establishment, the Gateway reads the current registry record and checks: the id exists; owning_actor satisfies the rule above; route eligibility is true at the record snapshot’s current block; and serving_endpoint passes workload-registry validation plus the Gateway’s transport policy. Missing, ineligible, owner-mismatched, or invalid records return 503 Service Unavailable without dialing. Backend DNS/connect/TLS failure or connection refusal returns 502 Bad Gateway. A backend HTTP or WebSocket handshake not completed within WORKLOAD_CONNECT_TIMEOUT_MS returns 504 Gateway Timeout. After response headers or 101 have been sent, later timeout or transport failure terminates the stream because its HTTP status can no longer be changed. The host determines the trustworthiness of a workload-served route. Gateway relaying adds no verification. Authors choose verification per route: the same actor’s URL space can mix Volume routes (content-addressed, verifiable), Method routes (consensus), and Workload routes (host-trusted). The actor’s route authority does not attest to the host’s execution; verifiable workload serving is deferred (§13).

9. CORS

9.1 Why CORS Is Specified Here

This CIP is the first specification where browsers will directly consume Gateway responses. Static HTML pages served from one actor’s domain will fetch JavaScript, CSS, and API endpoints from the same or other actors. Without CORS headers, browsers block cross-origin requests. Deferring CORS any further would make this CIP unusable for real web applications.

9.2 Configuration

CORS is configured via _meta/cors.json in the CBFS public volume:

9.3 Example

9.4 Default CORS Policy and Precedence

When no _meta/cors.json exists, the Gateway applies a permissive default for routes whose target is a Volume:
Static assets in a Visibility::Public volume are public by definition. Restricting their CORS policy by default would break most web applications. The permissive default matches CDN behavior (Cloudflare, Fastly, S3).
  • For Method-target routes, the actor’s HttpResponseEnvelope is authoritative. If the response includes any Access-Control-* headers, the Gateway passes them through unmodified and adds nothing. Otherwise, the Gateway applies matching cors_config rules. Otherwise, no CORS headers are added. The actor retains control of CORS for its dynamic responses.
  • For Volume-target routes, the Gateway applies cors_config rules. If no rule matches, the default policy above applies. The actor is not invoked.
  • For Runner-target routes, the runner’s response is authoritative, exactly as for Method. If it sets any Access-Control-* headers, the Gateway passes them through unmodified; otherwise the Gateway applies matching cors_config rules, else no CORS headers are added. The permissive Volume static-asset default is never applied to a Runner route.
  • For Workload-target routes, the workload’s response is authoritative, exactly as for Method and Runner. The Gateway passes through any Access-Control-* headers the workload sets. Otherwise it applies matching cors_config rules, or adds no CORS headers if none match; the Volume default is never applied. WebSocket upgrades are outside CORS entirely (browsers do not enforce it on WS): Origin validation is the workload’s responsibility (§12.12).

9.5 Preflight Handling

The Gateway handles OPTIONS requests for all routes directly, without dispatching to the actor or runner:
  1. Match the request path against _meta/cors.json rules. The permissive default policy applies only when the matched route’s target is a Volume; for Method, Runner, and Workload targets, preflight uses cors_config rules or, failing a match, no Access-Control-* headers. It never uses the Volume default or the backend’s response headers.
  2. If the Origin header matches allowed_origins and the Access-Control-Request-Method matches allowed_methods, return 204 No Content with the appropriate Access-Control-* headers.
  3. If no match, return 204 No Content with no Access-Control-* headers (the browser will block the actual request).
This prevents actors from needing to implement preflight handling in any of their handlers, which would require listing OPTIONS in the allowlist_methods entitlement parameter and waste query-path cycles on a pure CORS check.

10. Protocol Constants


11. Rationale

11.1 Why Routes Are Installed With Code

Routes decide which code answers which request and who pays for it. Writing them through the actor’s own KV path would let them drift from the code. An admin handler could install a stale table, or an upgrade could rename a handler without updating the table. Each write would require validation. Tying the table to deployment and upgrade gives one validated install per code version, lets the node enforce static_volumes membership once instead of the Gateway on every request, and leaves actor code with no path to the table at all. Prices live in the CIP-18 price_table, assets in their volume, and everything else in a code upgrade. KV storage remains the location because the Gateway verifies a single Merkle-proven value without executing the actor (§8.12), and an API-only actor needs no volume. An actor routes() method was rejected because every dispatch would require PVM execution to read the table.

11.2 Why Extend ingress.http Instead of a New Entitlement

Routes select how the Gateway handles HTTP requests. The Gateway dispatches some to named handlers and serves others from a volume. A separate ingress.static entitlement would require checking two entitlements on every request and complicate the Gateway’s dispatch logic. Extending ingress.http keeps the parameter space unified.

11.3 Why Polling-Based Cache Invalidation

Relay Nodes and Runners do not support push notifications for cached state. Subscribing to on-chain events for every cached volume and actor creates scaling concerns as the number of active actors grows. Polling StorageCommitment.manifest_root for volumes and the proven __cowboy/routes value for routes is cheap (one small read per anchor per MANIFEST_POLL_INTERVAL blocks) and sufficient. The resulting invalidation latency (up to ~6 seconds) is acceptable for both asset deploys and route updates.

11.4 Why Include CORS

This CIP is the first specification where browsers will directly consume Gateway responses at scale. Without CORS headers, a static HTML page served from app.example.org cannot load JavaScript from api.example.org or fetch data from its own /api/ endpoints if they are on a different subdomain. Deferring CORS to yet another CIP would make this one impractical for real web applications.

11.5 Why Permissive CORS Default for Static Assets

Public volume assets are, by definition, publicly readable. Any party can fetch them from Relay Nodes directly without authentication. Restricting CORS origins by default would create a mismatch: the data is public, but browsers cannot access it. This matches the behavior of every major CDN and static hosting provider.

11.6 Why Actor-Wins CORS Precedence on Method-Target Routes

For Method-target routes, the actor’s response envelope is authoritative for CORS. The Gateway only fills in CORS headers when the actor sets none. Allowing cors_config to override actor-set headers could remove a security restriction, such as an Access-Control-Allow-Origin limited to a single trusted origin.

11.7 Why b3_ ETag Prefix

ETags are opaque strings in HTTP, but clients and intermediary caches may compare them. The b3_ prefix:
  • Distinguishes BLAKE3 hashes from MD5, SHA-256, or other ETag formats used by other servers.
  • Enables clients that understand BLAKE3 to verify content integrity end-to-end by stripping the prefix and comparing against BLAKE3(response_body).
  • Avoids collision with weak ETags (which use the W/ prefix per RFC 7232).

11.8 Why a Runner Target (Off-Chain Compute Belongs Off Consensus)

The deterministic PVM cannot run LLM inference, call external APIs, or stream long responses. Consensus execution also imposes cycle, block-time, and RPC body limits. For a Runner target, the Gateway proxies the request to the runner without a transaction and streams the response back. This uses existing runner execution, mounts, and secp256k1 recovery utilities. The caller-authentication scheme is new (§8.14). Method targets execute actor handlers through the query or command path selected by their mode; Runner targets execute off-chain.

12. Security Considerations

12.1 Cache Poisoning

A compromised Relay Node serves corrupted shards, causing the Gateway to cache and serve incorrect content. The Gateway verifies every layer of the integrity chain (§8.5–§8.6):
  • Manifest against on-chain manifest_root (Merkle root).
  • Each shard against its shard_hash (BLAKE3) from the verified ObjectDescriptor.
  • Reconstructed object against its content_hash (BLAKE3).
To poison the cache, an attacker would need to produce a BLAKE3 collision (computationally infeasible with 256-bit output) or forge the on-chain manifest_root (requires consensus compromise).

12.2 Volume Impersonation

An actor declares static_volumes pointing to a volume it does not own, serving another account’s data under its own domain. Every Volume target’s name must be in static_volumes (§7.3). Without an explicit volume_id, the node resolves it at install from the installing account (§6.9), so the mount serves that account’s own volume and cannot be moved afterwards by changing the actor’s owner. An explicit volume_id serves another account’s Visibility::Public volume, and only when the owner grants that name in static_volumes; the content is already public, and the route claims no ownership over it.

12.3 Large Asset DoS

An actor stores very large objects in a public volume and drives traffic to them, exhausting Gateway resources. The following measures limit this attack:
  • The Gateway caps individual object sizes at max_static_response_bytes (default 10 MiB, ceiling 100 MiB) and returns 413 Content Too Large above the cap.
  • Per-volume max_cache_bytes is a proposed mitigation and is not an on-chain field or an enforced entitlement quota (§7.4).
  • MAX_GATEWAY_CACHE_BYTES caps total cache across all volumes.
  • CIP-14 rate limits apply: MAX_REQUESTS_PER_SECOND = 100 per actor per Gateway.
  • CIP-9 storage billing makes hosting large volumes expensive for the account owner.

12.4 Stale Manifest

A Gateway serves content from an old manifest after the volume owner has deployed an update (e.g., serving a version with a known security vulnerability). MANIFEST_POLL_INTERVAL (6 blocks) bounds the maximum staleness to ~6 seconds. The X-Cowboy-Block and X-Cowboy-Manifest-Root response headers tell the client which block and manifest were used. Clients requiring strict freshness can include X-Cowboy-Min-Block (CIP-14 §8.3) or X-Cowboy-Manifest-Root (§8.8) request headers; mismatch yields 409 Conflict.

12.5 Routes Table Manipulation

A malicious or compromised actor routes handler-served paths to a Volume target (bypassing authentication logic), changes the fallback payment gate from pays = caller to pays = actor when no enabled price_table applies, or points a route at a different handler than expected. The routes table is authored by the actor owner and installed with the owner’s code. A malicious table means a malicious owner, which is outside the protocol’s threat model. The following invariants hold regardless:
  • /_cowboy/* paths are always Gateway-intercepted (CIP-14 §8.6).
  • Actor code cannot write the table. Routing changes only with new code: a system deployer’s UpgradeActor, or upgrade_self from code holding sys.upgrade (§6.9). Any other actor keeps its deployed routes for life.
  • Volume targets are restricted to the actor’s static_volumes at install (§7.3).
  • The node rejects invalid tables at install (§6.8), so a table never reaches the Gateway unvalidated.

12.6 Routes Cache Poisoning

A compromised Runner serves a tampered routes value via GET_STATE, causing the Gateway to dispatch requests according to attacker-controlled routes. The Gateway verifies every GET_STATE response against the unified state root of a trusted block header using the supplied QMDB/MMR proof (§8.12, CIP-17 §5.3). A response that does not verify is rejected; the Gateway tries another full node. To poison the cache, an attacker would need to forge the on-chain state root (consensus compromise) or produce a Merkle proof collision (computationally infeasible).

12.7 Free-CDN Externality on Delinquent Storage

A Gateway continues to serve cached objects for a volume whose owner has stopped paying storage fees, externalizing bandwidth onto Relay Nodes that are no longer compensated. §8.13 ties Gateway serving authority to the volume’s CIP-9 status. Serving terminates at DELETED and GARBAGE_COLLECTING. The GRACE_PERIOD window is bounded by STORAGE_GRACE_EPOCHS, beyond which the volume transitions to DELETED regardless of cache state.

12.8 CORS Misconfiguration

An overly permissive CORS configuration (allowed_origins: ["*"] with allow_credentials: true) could enable credential-leaking cross-origin attacks. Gateways MUST reject CORS configurations where allowed_origins includes "*" and allow_credentials is true. The CORS specification forbids this combination; browsers also reject it. If detected, the Gateway falls back to the default CORS policy.

12.9 Runner-Target Trust

A selected runner may return a wrong result, leak a request, or misuse a mounted volume on a Runner-target route. An explicit pin selects a trusted operator, and current Gateway selection provides no runner_bindings authorization or binding-scoped mount-issuance guarantee. Do not rely on the following target rules as a current blast-radius bound. Under the unimplemented route-binding design, the actor trusts the runner to execute the route faithfully, as with runner jobs. The blast radius is bounded by what the route authorizes: a runner may only mount volumes named in the actor’s runner_bindings (owner = "actor") or a volume the caller granted it (owner = "caller"), each under a scoped CIP-9 mount-allowlist grant and, for private volumes, a per-job CBSS-sealed DEK. The Gateway is untrusted transport and asserts no result authority. Verifiable runner execution (attestation, fraud proofs) and on-chain settlement of off-chain work are deferred to a follow-on CIP (§13).

12.10 Caller Authentication and the Untrusted Gateway

For an auth = "account" route, a malicious Gateway forges or strips the caller’s identity to reach a handler as the wrong account (e.g., to mount another user’s caller-owned volume). Caller authentication is performed by the runner, not the Gateway. The runner verifies the caller’s secp256k1 signature (ecrecover) over the request. Binding a caller-owned mount to that account and issuing its scoped grant are unimplemented target design (§7.5, §8.14). A Gateway cannot forge a signature it does not hold, and a stripped signature simply yields 401. The Gateway’s own attestation under CIP-37 (authenticated_sender) is separate and is not accepted as a substitute for this check. Confidential request bodies SHOULD be encrypted to the runner so the Gateway sees only ciphertext (mechanism out of scope).

12.11 Streaming Connection Exhaustion

Long-lived Workload connections are held open en masse (slow-loris on upgrade requests, idle websockets, abandoned SSE streams), exhausting Gateway or workload connection capacity that request-scoped timeouts never reclaim. Every established stream is bounded by idle_timeout_ms (silence in both directions tears it down) and optionally max_connection_ms; establishment is bounded by WORKLOAD_CONNECT_TIMEOUT_MS; per-route concurrency is capped at max_concurrent_streams with 503 beyond it. The Gateway does not queue excess streams, preventing an unbounded backlog. A resolved client-paid policy gates establishment.

12.12 Cross-Origin WebSocket Hijacking

Browsers do not apply CORS to WebSocket connections, so any origin’s JavaScript can open a WS to an auth = "public" Workload route and act with the visiting user’s ambient context. The workload MUST validate the Origin header on browser-facing WS endpoints and reject unexpected origins. User-bound streams SHOULD require auth = "account", which binds establishment to a caller signature no foreign origin can produce. The Gateway relays Origin verbatim and never rewrites it.

12.13 Workload Endpoint Hijack

An attacker redirects a Workload route’s traffic by tampering with the serving endpoint or substituting another workload ID, turning a trusted route into an attacker-controlled backend. The registry record is the single binding authority for the endpoint. Registration and updates are authorized by the owning actor’s controller, and the endpoint is written only by a claim from a Runner holding the record’s host-pool entitlement whose accountable registration, its own or its host Runner’s, is staked (CIP-10 §17.3.2, §17.3.3, §17.3.5). The Gateway resolves the endpoint from the record at connection time and never accepts an endpoint from request data. An actor-owned route can name only a workload whose registry owner is that actor; a wrong-owner ID fails closed. Operator static configuration for first-party workloads is operator-trusted by definition. A claimant admitted through a reserved cby- pool MAY use a private-network endpoint, and platform deployments MAY use mutually authenticated transport. Any other claimant’s endpoint MUST be public, and the Gateway MUST resolve it and refuse a non-public address before every dial, so a repointed DNS name cannot reach an internal service (CIP-10 §17.3.4).

13. Future Work


14. Relationship to CIP-14

  • An actor that declares no routes has no __cowboy/routes value. Gateways dispatch every request for it that the CIP-37 site gate admits to the http.request handler per CIP-14.
  • static_volumes and max_static_response_bytes are optional. An absent static_volumes admits no Volume routes; an absent cap means the 10 MiB default.
  • runner_bindings is an unimplemented target-design parameter (§7.5). Current manifest validation rejects it, even as []; current Runner dispatch instead requires an explicit pin and advertised endpoint (§6.2). The target default [] is not a currently accepted deployment value.
  • A Visibility::Public volume is served only when an actor grants it in static_volumes and declares a route that mounts it.
  • The _meta/cors.json file is optional. Volumes without it use the default CORS policy (§9.4).
  • A Gateway without routes support dispatches every request to the http.request handler.
  • Every gateway serving a host must enforce CIP-37 before exposing that host. Provisioning, policy refresh, or enforcement failure serves no application traffic.
CIP-37 §8 defines how private pages load: directly, after site admission, with frame-ancestors 'none'. API and asset responses are not rewritten. CIP-37 §10 governs private receipts, direct backends, and indexing, and §11 distinguishes access control from confidentiality of public storage.

15. Host Resolution and HTTP Envelopes

15.1 Actor resolution

The operated Gateway resolves an actor using its configured resolution.mode: For host resolution, the Gateway strips the optional port from the Host header before looking up the static map. A configured mapping takes precedence over actor-address subdomain parsing. The operator supplies mappings such as:
DNS records and TLS certificates are operator responsibilities. Host resolution does not query an on-chain naming registry, register first-party TLD labels, or perform a protocol-managed domain-attachment or reverification flow. These features are outside this CIP’s scope.

15.2 HTTP envelopes

The Gateway’s Method-target dispatch uses the following request and response shapes (gateway-types::HttpRequestEnvelope and HttpResponseEnvelope). This section is authoritative for these envelope fields.
path_params contains named parameters extracted from the matched route (§6). Headers are pairs so repeated header names can be represented. The envelope is CBOR-encoded for actor dispatch; body is a byte string. host is request metadata, not proof of domain ownership or tenant authorization. The envelope contains no protocol-attested verified_fqdn or namespace_kind. Actor authorization MUST use the application’s authenticated identity and policy rather than treating a hostname as a domain-control attestation.