CIP-15: Public Asset Hosting and HTTP Routing

​

1. Abstract

• 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 to a selected runner (authorized by a runner_bindings entitlement), with optional caller authentication and actor- or caller-owned CBFS mounts, for endpoints that cannot run in consensus — LLM inference, outbound API calls, streaming.
• 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 sensible defaults for static assets.
• Cache invalidation driven by on-chain state-root and manifest_root changes.
• Runtime mutability of routes via the actor’s normal KV write path, with narrow typed SDK helpers (toggle, re-price, re-prioritize, re-target).

• 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

1. Static served straight from storage: Static assets come directly from the Gateway’s cache or are reconstructed from Relay Node shards — CDN-fast, with no actor handler involved.
2. Consensus spent only where it’s needed: The actor’s deterministic handler and max_query_cycles budget are reserved for requests that actually compute or change state; static and runner routes don’t draw on them.
3. CDN-like performance: Gateways cache reconstructed objects locally, serve conditional requests via ETags, and set proper Cache-Control headers — all without actor involvement.
4. Verb-aware dispatch to named handlers: 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. Per-route payment fallback: 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. Runtime mutability without redeploys: Toggling a route, raising a price, or activating a maintenance redirect does not require shipping new assets. The routes table is small structured state, mutated via the actor’s normal KV write path.
7. Familiar developer ergonomics: Routes are declared via decorators on handler functions in the actor’s source code (FastAPI / axum / Hono style). The SDK lowers them to the canonical schema at deploy time. A developer who has shipped a Flask or Express app can ship a Cowboy actor in minutes.
8. Off-chain compute as a route: Endpoints that cannot run in the deterministic PVM — LLM inference, outbound API calls, streaming responses — are declared as Runner targets and proxied off-chain to a runner, rather than being forced through consensus or bolted on as out-of-band jobs. The same routing table decides, per (verb, path), what runs in consensus, what serves static, and what runs off-chain.
9. Streaming app backends as a route: Long-lived connections — websockets for live apps, SSE for streamed inference and agent chat — terminate at a registered persistent workload behind the same URL space (Workload target, §8.15), instead of a sidecar server outside the platform. 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.
• Allow runtime mutation of route metadata (priority, pays/price, enabled, target handler) via narrow typed SDK helpers, without redeploying assets or actor code.

​

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

• Route: 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.
• Verb: An HTTP method (GET, HEAD, POST, PUT, PATCH, DELETE) or ANY (matches any verb at lowest specificity).
• Target: 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).
• Runner target: 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 runner role of §8.12 (GET_STATE), which only serves verified reads of the actor’s KV state; a Runner target serves the route’s request and response itself.
• Workload target: A route relayed to a single long-lived registered service — a persistent workload with a control-plane registry record (identity, owning actor, serving endpoint). Distinct from a Runner target: no per-request runner selection, no handler dispatch, no route mounts — the Gateway relays bytes to one durable backend, including upgraded WebSocket connections and streamed SSE responses (§8.15).
• Workload registry record: The control-plane record describing a persistent workload. This CIP consumes exactly three of its fields — workload_id, owning_actor, and serving_endpoint. Workload-target routes are unavailable where that registry does not exist.
• Pays: 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.
• Routes table: The CBOR-encoded Routes value stored in actor KV at the reserved key __cowboy/routes.
• Mount: A Volume-target route with a wildcard path, declared at the SDK module level (e.g., actor.mount("/assets", volume="web-assets")).
• Object: A single file stored in a CBFS volume (e.g., assets/logo.png). Objects are erasure-coded into shards and distributed across Relay Nodes.
• Shard: 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 and Rationale

• Volume _meta/routes.json: atomic with assets but couples cadences that should be independent. Routes change far more often than assets — toggles, prices, A/B paths, abuse-mitigation flips — and forcing a commit_manifest for every metadata change is friction. It also requires API-only actors (no static files) to provision a CBFS volume just to publish routing rules.
• Actor routes() method called by the Gateway: defeats the static-serving performance goal because every dispatch would need a read_handler PVM execution to read the table.
• Entitlement parameters (CIP-2): immutable after deployment, so changing any route would require redeploying the actor. Website route structures change too frequently.
• Convention-based (e.g., /static/* always from volume): too rigid. A path like /app.js might be static in one actor and dynamic in another.

• Routes are state, not assets. KV is the natural home for small, structured, mutable actor state.
• Verifiable by the Gateway with no actor execution. The actor’s state root is committed on-chain. The Gateway fetches the value at __cowboy/routes along with a Merkle proof against the state root and verifies it without invoking the actor (§8.12).
• Update cadence decoupled from asset deploys. Most route changes (toggle, pays, price) don’t touch assets and don’t require commit_manifest.
• Atomicity recoverable when needed. A single block-level transaction can write to __cowboy/routes and call commit_manifest, restoring atomic asset+route deploys for the cases that need them.

​

6.2 Schema

Routes {
  version:  u8,             // schema version (1 for this CIP)
  routes:   list<Route>     // resolution sorts by priority — order in storage is canonical (§6.5)
}

Route {
  verb:      Verb,          // HTTP method this route matches
  path:      string,        // URL path pattern (see §6.3)
  target:    Target,        // where matching requests go
  pays:      Pays,          // who pays — default "actor"
  price:     string?,       // required when pays = "caller", e.g., "0.05 CBY"
  priority:  u16,           // higher value wins; default 0
  enabled:   bool           // default true; allows toggling without removing
}

Verb     = "GET" | "HEAD" | "POST" | "PUT" | "PATCH" | "DELETE" | "ANY"

Target   = Method | Volume | Runner | Workload

Method {
  kind:    "method",
  name:    string           // CIP-14 actor handler name (e.g., "users.get", "http.request")
}

Volume {
  kind:                "volume",
  volume_name:         string,    // must match a static_volumes entitlement binding (§7)
  strip_prefix:        bool,      // strip matched path prefix before volume lookup
  volume_path_prefix:  string,    // prepended to remaining path
  fallback:            string?,   // object path to serve when not found
  fallback_status:     u16        // HTTP status for fallback (200 for SPA, 404 otherwise)
}

Runner {
  kind:        "runner",
  handler:     string,             // runner-side entrypoint this route invokes (deployed runner code / registered executor); how that code is deployed is out of scope
  requires:    RunnerRequirements?, // OPTIONAL selector — omitted (or empty fields) ⇒ any runner in the actor's runner_bindings (§7.5); set to narrow. Intersected with runner_bindings + RAS health (§8.14)
  affinity:    Affinity,           // soft stickiness: prefer the same runner per key. Default "caller" when auth = "account", else "none"
  runner:      string?,            // OPTIONAL hard pin (escape hatch); when set it overrides selection and MUST be in the eligible set
  auth:        Auth,               // caller identity required to reach the handler — default "public"
  mounts:      list<RouteMount>,   // CBFS volumes the runner is issued CapTokens for, on this route (§7.5)
  timeout_ms:  u32                 // gateway wait before 504 Gateway Timeout; default per §10
}

RunnerRequirements {
  pool:          string?,          // CIP-2 required_runner_pool (entitlement-scoped runner cohort)
  capabilities:  list<string>,     // capability tags the runner must advertise (job-class, model, feature); empty = unconstrained
  region:        string?,          // optional locality constraint
  tee:           bool              // require a TEE-attested runner; default false
}

Workload {
  kind:                    "workload",
  workload:                bytes32,    // workload registry record id (§8.15);
                                       // text encodings MUST be the canonical 64-char lowercase hex
  strip_prefix:            bool,       // strip matched path prefix before forwarding
  auth:                    Auth,       // caller identity required to ESTABLISH the connection — default "public"
  idle_timeout_ms:         u32,        // tear down an established stream after this much silence; default per §10; 0 is invalid
  max_connection_ms:       u32?,       // optional hard ceiling on one connection's lifetime; unset = no ceiling; 0 is invalid
  max_concurrent_streams:  u32?        // per-route open-connection cap; unset = DEFAULT_MAX_CONCURRENT_STREAMS; 0 is invalid (§6.8)
}

Affinity = "none" | "caller" | "session"   // HRW key: stable per caller account, per client session, or unkeyed (pure load-balance)
Auth     = "public" | "account"             // "account" = runner or workload verifies the caller's Cowboy-account (secp256k1) signature

RouteMount {
  volume:       string,           // volume name
  mode:         "ro" | "rw",
  owner:        "actor" | "caller", // "actor": granted in the entitlement (§7.5); "caller": the authenticated caller's own volume (requires auth = "account")
  path_prefix:  string            // least-privilege scope within the volume; default "" (root). Maps to the CIP-9 attachment canonical_path_prefix
}

Pays     = "actor" | "caller"

​

6.3 Path Patterns

• /api/users/{user_id} — named path parameter; binds to a single segment.
• /static/*rest — wildcard; matches zero or more segments and binds the remainder to rest.
• /about — exact match.
• /assets/* — anonymous wildcard; matches anything under the prefix without binding.

​

6.4 Example: Full-Stack Application

import json
from cowboy_sdk import actor, runtime, Pays
from cowboy_sdk.routes import get, post, mount, runner, mount_ro

@actor
class MyApp:
    # Static asset mounts: served directly from the "web-assets" CBFS volume,
    # which must be in this actor's static_volumes entitlement binding.
    routes = [
        mount("/assets", volume="web-assets"),
        mount("/", volume="web-assets", fallback="index.html"),  # SPA fallback
    ]

    @get("/api/users/{user_id}")
    def users_get(self, request):
        user_id = request["path_params"]["user_id"]
        row = self.storage.get(f"user:{user_id}")
        if row is None:
            return {"status": 404, "headers": {}, "body": b""}
        return {
            "status": 200,
            "headers": {"content-type": "application/json"},
            "body": json.dumps(row).encode(),
        }

    @post("/api/users")
    def users_create(self, request):
        body = json.loads(request["body"]) if request.get("body") else {}
        seq = self.storage.get("user_seq", 0) + 1
        self.storage["user_seq"] = seq
        record = {"id": str(seq), "email": body.get("email"), "name": body.get("name")}
        self.storage[f"user:{seq}"] = record
        return {
            "status": 201,
            "headers": {"content-type": "application/json"},
            "body": json.dumps(record).encode(),
        }

    # Runner target: runs OFF-CHAIN on a runner selected at call time
    # (capability: llm) — not the actor PVM — so it may call an LLM, hit
    # external APIs, or stream.
    @post(
        "/api/inference",
        target=runner(requires={"capabilities": ["llm"]}, mounts=[mount_ro("models")]),  # handler = this method
        pays=Pays.CALLER, price="0.05 CBY",
    )
    def inference_run(self, request):
        body = json.loads(request["body"]) if request.get("body") else {}
        result = run_model(body["prompt"])
        return {
            "status": 200,
            "headers": {"content-type": "application/json"},
            "body": json.dumps({"output": result}).encode(),
        }

{
  "version": 1,
  "routes": [
    {
      "verb": "GET", "path": "/api/users/{user_id}",
      "target": {"kind": "method", "name": "users_get"},
      "pays": "actor", "priority": 100, "enabled": true
    },
    {
      "verb": "POST", "path": "/api/users",
      "target": {"kind": "method", "name": "users_create"},
      "pays": "actor", "priority": 100, "enabled": true
    },
    {
      "verb": "POST", "path": "/api/inference",
      "target": {"kind": "runner", "handler": "inference_run", "requires": {"capabilities": ["llm"]}, "affinity": "none", "auth": "public",
                 "mounts": [{"volume": "models", "mode": "ro", "owner": "actor"}], "timeout_ms": 60000},
      "pays": "caller", "price": "0.05 CBY",
      "priority": 100, "enabled": true
    },
    {
      "verb": "GET", "path": "/assets/*",
      "target": {
        "kind": "volume", "volume_name": "web-assets",
        "strip_prefix": false, "volume_path_prefix": "assets/",
        "fallback": null, "fallback_status": 404
      },
      "pays": "actor", "priority": 10, "enabled": true
    },
    {
      "verb": "GET", "path": "/*",
      "target": {
        "kind": "volume", "volume_name": "web-assets",
        "strip_prefix": false, "volume_path_prefix": "",
        "fallback": "index.html", "fallback_status": 200
      },
      "pays": "actor", "priority": 0, "enabled": true
    }
  ]
}

• GET /api/users/abc → matches /api/users/{user_id} (priority 100) → dispatched to users_get handler with path_params = {"user_id": "abc"}. Actor pays.
• POST /api/inference → matches /api/inference → Gateway returns 402 with x402 headers until caller pays 0.05 CBY, then proxies the request off-chain to a runner selected from the eligible set (§8.14); inference_run runs on the runner, not the actor PVM.
• GET /assets/logo.png → matches /assets/* (priority 10) → served from web-assets volume at assets/logo.png. No actor invocation.
• GET /about → matches /* (priority 0) → looks up about in web-assets. Not found → serves index.html with status 200 (SPA fallback).
• GET /_cowboy/health → reserved path, always Gateway-intercepted (CIP-14 §8.6), never consults the routes table.

@route(["GET", "POST"], "/foo")
def foo(self, request):
    if request["method"] == "GET":
        ...
    else:
        ...

​

6.5 Canonical Encoding

1. priority descending,
2. then path descending (UTF-8 byte order),
3. then verb ascending in declaration order:
   GET < HEAD < POST < PUT < PATCH < DELETE < ANY
   

Errata (COW-3005). This clause previously read “verb ascending (alphabetical)”. No encoder in the Rust stack has done that: both encoders — cowboy-protocol-codec’s and the gateway’s — sort tied verbs by the order the Verb enum declares them, which is the request-lifecycle order above, not the lexical order (ANY < DELETE < GET < HEAD < PATCH < POST < PUT). One encoder outside that stack did implement the old clause faithfully: gateway/examples/site-actor/tools/lower_routes.py, which sorts the verb strings and therefore lexicographically. It writes routes.cbor for operators to install, so its output is embedded in signed history and this amendment makes it non-conforming; correction pending in cowboyinc/gateway#85. The divergence had not surfaced because that tool’s static-route branch emits only GET/HEAD, one of the eight verb pairs (of twenty-one) the two orders happen to agree on — luck, not design. It is reachable from the method branch: a single @route(["POST", "PATCH"], …) ties two verbs the orders disagree on, and the tool then emits PATCH, POST where both Rust encoders emit POST, PATCH. Tables it already installed keep working: Routes::decode does not re-check the ordering, so a table stored in the old order is still read back and served correctly — it is only re-encoding it that would move the digest. The spec text is what changed here, and deliberately. Canonicalization decides the encoded bytes, the bytes decide the signing digest, and that digest is what account holders have already signed and what deployed actors already carry in their state. Amending the implementation to match the old text would silently re-encode every existing route table: signatures over historical set_routes transactions would stop reproducing, and every actor whose table has two verbs at one (priority, path) would change its Merkle leaf without anyone touching it. The asymmetry is the whole argument — the implementation’s behaviour is embedded in signed history and cannot be recalled; this sentence was not. Clients are unaffected either way: they decode the exact wire bytes for the signing preview, so a signer always saw the truth. This is a spec-conformance correction, not a change to what any user was shown.

​

6.6 Route Resolution Algorithm

1. Reserved paths: 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 on state-root change (§8.12). Filter to routes with enabled = true.
3. Match candidates. A route matches if:
   • Its path pattern matches the request path (literal segments + named params + wildcards).
   • Its verb matches the request method, or verb = "ANY".
4. Select winner. Among matching routes:
   • Highest priority wins.
   • Tie: longest concrete prefix (path with wildcards/params replaced by their match length) wins.
   • Tie: more specific verb (any non-ANY) wins over ANY.
   • Tie: Method > Runner > Workload > Volume (safety: prefer the consensus handler, then per-request off-chain compute, then the long-lived proxy, over static).
5. 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.
6. 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.
   • Resolved free model: Dispatch without a payment check. 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.
   • Client-paid model (selected by an enabled price_table or fallback pays = "caller"): Per CIP-18, verify the caller’s payment proof. 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.
7. 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 — they compose.
   • 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).
   • The Gateway selects an eligible runner (§8.14) and proxies the request off-chain to it; the runner mounts the route’s authorized volumes (via dispatcher-issued CapTokens), executes the handler outside consensus, and streams the response back. The actor’s PVM is not invoked.
8. 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 — WebSocket upgrade + transparent byte-pipe, or unbuffered streamed HTTP response. The actor’s PVM is not invoked.
9. No match. Return 404 Not Found. Explicit routes are required; there is no fallback default_behavior.

​

6.7 Volume Object Path Resolution

request_path = "/docs/getting-started"
matched_route.target = {
  volume_name: "docs-site",
  strip_prefix: true,
  volume_path_prefix: "documentation/"
}
matched_route.path = "/docs/*"

1. Extract remainder:
   prefix = path-prefix-of(matched_route.path)   // "/docs/"
   remainder = request_path.removePrefix(prefix) // "getting-started"

2. Build volume path:
   volume_path = matched_route.target.volume_path_prefix + remainder
   // volume_path = "documentation/getting-started"

3. Look up volume_path in the canonical, root-verified manifest path index (§8.5) and read the file's ObjectDescriptor.
   - If found: serve the object.
   - If not found and target.fallback is set: serve the fallback object with target.fallback_status.
   - If not found and no fallback: return 404.

request_path = "/assets/logo.png"
matched_route.target = {
  volume_name: "web-assets",
  strip_prefix: false,
  volume_path_prefix: "assets/"
}

// strip_prefix=false → use request path directly (minus leading "/")
volume_path = "assets/logo.png"

​

6.8 Validation

• version MUST be 1. Unknown versions cause the Gateway to fall back to all-CIP-14 dispatch (no routes-driven dispatch; HTTP ingress still works for actors with an http.request handler).
• 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.
• target.kind MUST be "method", "volume", "runner", or "workload".
• For Method targets: name MUST be a non-empty string. (Method existence is validated at deploy time by the SDK lowering pipeline; runtime missing-method errors return 502 Bad Gateway.)
• For Volume targets: volume_name MUST match one of the actor’s static_volumes entitlement bindings; 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; requires, if present, MUST be covered by some runner_bindings entry (§7.5); if omitted, the route inherits the actor’s runner_bindings — which MUST be non-empty for any Runner route; either way the eligible set MUST be non-empty; if the optional runner pin is set it MUST fall within that eligible set; affinity MUST be none / caller / session, and affinity = "caller" REQUIRES auth = "account"; auth MUST be "public" or "account"; every mounts[] with owner = "actor" MUST be authorized in that binding, with its mode and path_prefix within the bound grant; any mount with owner = "caller" REQUIRES auth = "account" (its mode / path_prefix are checked against the caller’s CIP-9 grant at dispatch, §8.14); timeout_ms MUST be ≤ MAX_RUNNER_TIMEOUT_MS (§10).
• 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 parseable per CIP-18.

​

6.9 Runtime Mutability

• routes.disable(verb, path) — sets enabled = false for the matching route.
• routes.enable(verb, path) — sets enabled = true.
• routes.set_pays(verb, path, pays, price?) — updates payment policy.
• routes.set_priority(verb, path, priority) — re-prioritizes.
• routes.replace_handler(verb, path, name) — points a route at a different method.

​

7. Entitlement Extension

​

7.1 New Parameters

StaticVolumeBinding {
  volume_name:      string,    // must be a Visibility::Public volume owned by the same account
  max_cache_bytes:  u64        // maximum Gateway cache space this volume may consume (per Gateway)
}

​

7.2 Example Manifest

{
  "entitlements": [
    {"id": "ingress.http", "params": {
      "allowlist_methods": ["GET", "HEAD", "POST"],
      "max_request_bytes": 1048576,
      "max_response_bytes": 1048576,
      "max_query_cycles": 10000000,
      "static_volumes": [
        {"volume_name": "web-assets", "max_cache_bytes": 104857600}
      ],
      "max_static_response_bytes": 10485760
    }},
    {"id": "storage.kv", "params": {"max_bytes": 10485760}},
    {"id": "econ.hold_balance"},
    {"id": "econ.transfer"}
  ]
}

​

7.3 Enforcement

• Deployment-time: The deployment transaction verifies that each volume_name in static_volumes references a Visibility::Public volume owned by the deploying account. If any volume does not exist or has Visibility::Private, deployment is rejected. The volume_id is deterministic per CIP-9 §11.1 (keccak256(account_address || volume_name)), so cross-account references are impossible.
• Gateway enforcement: Gateways MUST only serve static assets from volumes listed in static_volumes. Objects larger than max_static_response_bytes return HTTP 413 Content Too Large. Gateways MUST respect max_cache_bytes per volume when allocating cache space.
• Volume lifecycle: The Gateway’s serving authority follows the volume’s CIP-9 status (§8.13). If a volume listed in static_volumes is DELETED or GARBAGE_COLLECTING, the Gateway returns the corresponding HTTP status without invoking the actor. The entitlement remains valid — the volume reference is stale. The actor owner must redeploy with updated static_volumes (or restore the volume) to resume static serving.

​

7.4 Why max_cache_bytes Is in the Entitlement

​

7.5 Runner Bindings

RunnerBinding {
  pool:          string?,         // CIP-2 required_runner_pool the actor may dispatch routes to
  capabilities:  list<string>,    // capability tags the actor may require (job-class, model, feature)
  mounts:        list<RouteMount>  // actor-owned volumes runners under this binding may mount (owner = "actor")
}

• 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.

​

8. Gateway-to-Relay-Node Fetch Protocol

​

8.1 Request Flow

Client                    Gateway                         Relay Nodes
  |                         |                                 |
  |--- GET /app.js -------->|                                 |
  |                         |--- 1. Check object cache        |
  |                         |   key: (volume_id, "app.js")    |
  |                         |                                 |
  |                         |   [CACHE HIT + fresh]           |
  |<-- 200 + body ----------|                                 |
  |                         |                                 |
  |                         |   [CACHE HIT + If-None-Match]   |
  |<-- 304 Not Modified ----|                                 |
  |                         |                                 |
  |                         |   [CACHE MISS]                  |
  |                         |--- 2. Fetch volume manifest --->|
  |                         |   (public, no CapToken)         |
  |                         |<--- manifest bytes -------------|
  |                         |                                 |
  |                         |--- 3. Look up file entry for    |
  |                         |   "app.js" in manifest          |
  |                         |                                 |
  |                         |--- 4. Fetch K shards in ------->|
  |                         |   parallel from K Relay Nodes   |
  |                         |<--- shard 0 --------------------|
  |                         |<--- shard 1 --------------------|
  |                         |<--- shard 2 --------------------|
  |                         |<--- shard 3 --------------------|
  |                         |                                 |
  |                         |--- 5. Reed-Solomon reconstruct  |
  |                         |--- 6. Verify content_hash       |
  |                         |--- 7. Read content-type + cache |
  |                         |--- 8. Store in object cache     |
  |                         |                                 |
  |<-- 200 + headers + body-|                                 |

​

8.2 Gateway-Side Caching

VolumeMetadataCache {
  content_type_map:     ContentTypeMap,       // _meta/content_types.json (CIP-9 §7.6.5)
  cache_config:         CacheConfig,          // _meta/cache_config.json (CIP-9 §7.6.6)
  cors_config:          CorsConfig?,          // _meta/cors.json (this CIP §9)
  volume_manifest:      VolumeManifest,       // verified path-ordered ManifestEntry map
  manifest_root:        bytes32,              // on-chain StorageCommitment.manifest_root
  last_verified_block:  BlockHeight           // block at which manifest_root was checked
}

ActorRoutesCache {
  routes:               Routes,               // CBOR Routes from __cowboy/routes
  state_root:           bytes32,              // on-chain Account.state_root
  last_verified_block:  BlockHeight           // block at which state_root was checked
}

ObjectCacheEntry {
  body:             bytes,          // reconstructed plaintext
  content_hash:     bytes32,        // BLAKE3, used as ETag
  content_type:     string,         // resolved MIME type
  content_length:   u64,
  cached_at:        BlockHeight,
  max_age:          u32             // from cache_config
}

​

8.3 Cache Invalidation

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.

​

8.4 Relay Node RPC

​

GET_MANIFEST

GET_MANIFEST { volume_id: bytes32, manifest_root: bytes32, erasure_k: u8, erasure_m: u8 }
  → { manifest: bincode(map<path → ManifestEntry>) }

• Public volumes only. A Gateway 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 caller supplies the root. The Gateway 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.

​

GET_SHARD (existing CIP-9 §16.3)

GET_SHARD { shard_id: bytes32, shard_index: u8, volume_id: bytes32 }
  → shard_bytes

​

8.5 Canonical Manifest Serialization and Verification

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.

​

8.6 Integrity Verification

1. Manifest integrity: 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. Shard integrity: 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. Object integrity: 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

1. Initial fetch: Request K shards from the K lowest-latency Relay Nodes (based on historical RTT for that volume’s shard assignments).
2. Hedged requests: 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. Shard selection: The Gateway prefers data shards (indices 0..K-1) but accepts parity shards. Any K of the K+M shards suffice for reconstruction.
4. Concurrency cap: No more than MAX_CONCURRENT_SHARD_FETCHES (default: 8) outstanding shard requests per object reconstruction.

​

8.8 HTTP Response Headers

HTTP/1.1 200 OK
Content-Type: text/javascript; charset=utf-8
Content-Length: 45231
ETag: "b3_a1b2c3d4e5f6..."
Cache-Control: public, max-age=86400, immutable
X-Cowboy-Block: 1234567
X-Cowboy-Manifest-Root: a1b2c3d4...
X-Cowboy-Volume: web-assets
X-Cowboy-Source: static
Vary: Accept-Encoding

​

8.9 Conditional Requests

• 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 is gated on the content-hash ETag alone. 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 → 409 mechanism (§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.
• If-Modified-Since: Not directly supported. Volume objects do not have per-file modification timestamps. Clients SHOULD use If-None-Match (ETag-based) for conditional requests.

​

8.10 Compression

​

8.11 Relay Node Bandwidth Economics

• 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.

• 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.

​

8.12 Routes Fetching (Gateway ↔ Runner)

​

GET_STATE (state read with Merkle proof)

GET_STATE {
  actor_address:  bytes20,
  key:            bytes,            // "__cowboy/routes" for the routes table
  block_height:   u64?              // optional pin; default = latest finalized block
}
→ {
  value:          bytes,            // CBOR-encoded Routes (or empty if unset)
  proof:          MerkleProof,      // proof from leaf to state_root
  state_root:     bytes32,          // actor.state_root at the resolved block
  block_height:   u64               // block at which state_root was read
}

1. The Gateway fetches via GET_STATE(actor_address, "__cowboy/routes").
2. The Gateway verifies state_root matches the on-chain Account.state_root for actor_address at block_height.
3. The Gateway verifies the Merkle proof from value to state_root.
4. If both checks pass, the Gateway deserializes value as Routes and validates per §6.8.
5. The verified routes table is cached, keyed by (actor_address, state_root).

​

8.13 Serving Authority by Volume Status

​

8.14 Runner-Target Dispatch (Gateway → Runner)

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) — 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. Else: spread across E — least-loaded by advertised active-job count, or round-robin.

POST {route_serving_endpoint}/_cowboy/route
  <forwarded request headers>
  X-Cowboy-Route-Context: base64url(CBOR(RouteContext))
  <buffered request body, raw bytes>

RouteContext {
  actor_address, handler, verb, path, path_params,
  mounts:         list<RouteMount>,
  auth:           Auth,       // the route's caller-auth requirement, so the runner self-enforces
  payment_proof:  bytes?,     // untrusted raw client X-Payment header, if supplied; not a settlement result
  account_sig:    bytes?,     // §8.14 caller-auth, when auth = "account"
  account_expiry: uint?,      // unix-seconds expiry bound into account_sig
  account_nonce:  bytes?,     // single-use nonce bound into account_sig
  chain_id:       uint,       // target deployment; the runner rejects a mismatch
  network:        string      // target deployment (see chain_id)
}

domain_tag                                   // fixed, unique to CIP-15 route auth
  ‖ chain_id ‖ len‖network ‖ actor_address
  ‖ len‖handler ‖ len‖verb ‖ len‖path
  ‖ body_sha256 ‖ expiry ‖ len‖nonce

• owner = "actor": issued under the actor principal, bounded by the actor’s runner_bindings (§7.5).
• owner = "caller": issued under the actor principal for the authenticated caller’s volume — 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.

​

8.15 Workload-Target Dispatch (Gateway → Workload)

StaticWorkloadRoute {
  actor:     Address,        // the actor whose URL space this route lives in — resolved from the request
                             // host exactly as actor routes are, BEFORE lookup; bound as the actor for
                             // auth context and actor-funded payment policy lookup
  verb:      Verb,
  path:      string,         // §6.3 pattern
  target:    Workload,       // the §6.2 Workload shape — normative here (see below)
  expected_workload_owner: Address?,  // cross-owner override: when set, MUST exactly equal the resolved
                                      // record's owning_actor (and differ from `actor`); a repointed record
                                      // whose owner no longer matches fails closed
  pays:      Pays,
  price:     string?,        // required when pays = "caller"
  priority:  u16,
  enabled:   bool
}

​

9. CORS

​

9.1 Why CORS Is Specified Here

​

9.2 Configuration

CorsConfig {
  rules:  list<CorsRule>    // evaluated in order; first matching path_prefix wins
}

CorsRule {
  path_prefix:       string,           // URL path prefix to match
  allowed_origins:   list<string>,     // "*" permits all origins
  allowed_methods:   list<string>,     // HTTP methods permitted
  allowed_headers:   list<string>,     // request headers permitted
  expose_headers:    list<string>,     // response headers exposed to browser
  max_age:           u32,              // seconds for Access-Control-Max-Age
  allow_credentials: bool              // Access-Control-Allow-Credentials
}

​

9.3 Example

{
  "rules": [
    {
      "path_prefix": "/api/",
      "allowed_origins": ["https://myagent.cowboy.network"],
      "allowed_methods": ["GET", "POST", "OPTIONS"],
      "allowed_headers": ["Content-Type", "Authorization", "X-Cowboy-Min-Block"],
      "expose_headers": ["X-Cowboy-Block", "X-Cowboy-Request-Id"],
      "max_age": 86400,
      "allow_credentials": false
    },
    {
      "path_prefix": "/",
      "allowed_origins": ["*"],
      "allowed_methods": ["GET", "HEAD", "OPTIONS"],
      "allowed_headers": [],
      "expose_headers": ["X-Cowboy-Block"],
      "max_age": 86400,
      "allow_credentials": false
    }
  ]
}

​

9.4 Default CORS Policy and Precedence

Access-Control-Allow-Origin: *
Access-Control-Allow-Methods: GET, HEAD, OPTIONS
Access-Control-Max-Age: 86400

• 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. This preserves the actor’s authority over its own dynamic-response CORS — a load-bearing security posture for many applications.
• Volume-target routes: the Gateway applies cors_config rules. If no rule matches, the default policy above applies. The actor is not invoked.
• 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.
• Workload-target routes: the workload’s response is authoritative, exactly as for Method and Runner — pass-through if it sets any Access-Control-* headers, else matching cors_config rules, else none; 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

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 — never the Volume default and never 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).

​

10. Protocol Constants

// Routes table
MAX_ROUTES                          = 200             // maximum entries in routes
MAX_ROUTES_SIZE                     = 65_536          // bytes; maximum CBOR-encoded Routes value
MIN_ROUTES_UPDATE_INTERVAL_BLOCKS   = 6               // minimum blocks between routes-affecting commits
MAX_RUNNER_TIMEOUT_MS               = 300_000         // ms; max gateway wait for a Runner-target response
DEFAULT_RUNNER_TIMEOUT_MS           = 60_000          // ms; default Runner-target timeout_ms

// Workload streaming (per-Gateway operator-tunable; the bounds are normative)
WORKLOAD_CONNECT_TIMEOUT_MS         = 10_000          // ms; establishment deadline before 504
DEFAULT_WORKLOAD_IDLE_TIMEOUT_MS    = 120_000         // ms; default Workload-target idle_timeout_ms
MAX_WORKLOAD_IDLE_TIMEOUT_MS        = 3_600_000       // ms; ceiling on route-declared idle_timeout_ms
DEFAULT_MAX_CONCURRENT_STREAMS      = 1_000           // per Workload route when max_concurrent_streams unset; 503 beyond, no queueing
MAX_CONCURRENT_STREAMS_CEILING      = 10_000          // ceiling on route-declared max_concurrent_streams

// Manifest and state caching
MANIFEST_POLL_INTERVAL              = 6               // blocks between manifest_root / state_root checks (~6s)
METADATA_CACHE_TTL                  = 60              // seconds; _meta/* cached between root changes

// Object caching
MAX_GATEWAY_CACHE_BYTES             = 10_737_418_240  // 10 GiB total per Gateway
DEFAULT_MAX_CACHE_PER_VOLUME        = 104_857_600     // 100 MiB default if not set in entitlement

// Static serving limits
DEFAULT_MAX_STATIC_RESPONSE_BYTES   = 10_485_760      // 10 MiB default max single asset
PROTOCOL_MAX_STATIC_RESPONSE_BYTES  = 104_857_600     // 100 MiB hard ceiling

// Fetch optimization
HEDGE_THRESHOLD_MS                  = 100             // ms before issuing hedged shard requests
MAX_CONCURRENT_SHARD_FETCHES        = 8               // max parallel shard requests per object

// CORS
DEFAULT_CORS_MAX_AGE                = 86_400          // seconds for preflight cache (24 hours)
MAX_CORS_RULES                      = 50              // maximum entries in _meta/cors.json

​

11. Rationale

​

11.1 Why KV Storage for Routes (Not Volume _meta/)

• Lets API-only actors function without a CBFS volume. An actor that exposes only dynamic methods should not need to provision a public volume just to publish routing rules.
• Decouples route updates from asset deploys. Toggling a path, adjusting a price, or activating a maintenance redirect does not require a commit_manifest cycle or republishing assets.
• Reuses the actor’s existing state-root commitment for verifiability. The Gateway reads __cowboy/routes via GET_STATE (§8.12) and verifies a Merkle proof against the on-chain Account.state_root. No new on-chain primitive is required, and no actor execution is invoked on the dispatch path.
• Permits runtime mutation via narrow typed SDK helpers (§6.9), matching how operational web apps are actually run — feature flags, gradual rollouts, abuse mitigation, dynamic pricing.

​

11.2 Why Extend ingress.http Instead of a New Entitlement

​

11.3 Why Polling-Based Cache Invalidation

​

11.4 Why Include CORS

​

11.5 Why Permissive CORS Default for Static Assets

​

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

​

11.7 Why b3_ ETag 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)

​

12. Security Considerations

​

12.1 Cache Poisoning

• 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).

​

12.2 Volume Impersonation

​

12.3 Large Asset DoS

• max_static_response_bytes caps individual object sizes (default 10 MiB, ceiling 100 MiB). Objects exceeding this limit return 413 Content Too Large.
• max_cache_bytes per volume caps Gateway cache consumption.
• 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

​

12.5 Routes Table Manipulation

• /_cowboy/* paths are always Gateway-intercepted (CIP-14 §8.6) regardless of the routes table.
• Volume targets can only reference volumes in the actor’s static_volumes entitlement bindings (§6.8, §7.3). Cross-account volume references remain impossible.
• MIN_ROUTES_UPDATE_INTERVAL_BLOCKS rate-limits routes-affecting commits, preventing an actor from churning gateway caches faster than ~1 update per 6 seconds.
• Validation (§6.8) rejects routes tables that are empty, oversized, reference unknown volumes, or set pays = caller without a price. On rejection, the Gateway falls back to all-CIP-14 dispatch with the previously-cached table.

​

12.6 Routes Cache Poisoning

​

12.7 Free-CDN Externality on Delinquent Storage

​

12.8 CORS Misconfiguration

​

12.9 Runner-Target Trust

​

12.10 Caller Authentication and the Untrusted Gateway

​

12.11 Streaming Connection Exhaustion

​

12.12 Cross-Origin WebSocket Hijacking

​

12.13 Workload Endpoint Hijack

​

13. Future Work

​

14. Backwards Compatibility

• Actors without a __cowboy/routes value in their KV state are unaffected. Gateways fall back to all-CIP-14 dispatch — every request reaches the http.request handler. This is the migration path for existing actors: they continue to work, and they opt into routes-driven dispatch by writing to __cowboy/routes (typically via the SDK’s deploy step).
• The new entitlement parameters (static_volumes, max_static_response_bytes) are optional. When absent, defaults preserve baseline behavior: static_volumes = [] (no Volume-target routes can be served) and max_static_response_bytes = 10_485_760.
• The new runner_bindings entitlement parameter is optional and defaults to [] (no Runner-target routes can be served). Actors opt in by declaring bindings and writing Runner-target routes; existing actors are unaffected.
• Workload targets are additive. Actors opt in by writing a Workload target to __cowboy/routes; existing actors and routes are unaffected. Operator static routes remain available as a fallback, but actor deployments require no per-actor Gateway configuration or restart.
• Existing Visibility::Public volumes gain no new behavior unless an actor explicitly references them in static_volumes and writes a routes table that mounts them.
• The _meta/cors.json file is optional. Volumes without it use the default CORS policy (§9.4).
• Gateway nodes must be upgraded to support routes-driven dispatch. Gateways that have not been upgraded will ignore __cowboy/routes and dispatch all requests to the http.request handler — safe degradation with no data loss or protocol violations.

​

15. Host Resolution and HTTP Envelopes

​

15.1 Actor resolution

[resolution]
mode = "host"

[resolution.host_to_actor]
"shop.example.com" = "0x9b80c2fbc7b277e2cc12a2b4c50386218fa0ed1c"

​

15.2 HTTP envelopes

HttpRequestEnvelope {
  method:       string,
  path:         string,
  path_params:  map<string, string>,
  query:        string,
  headers:      list<(string, string)>,
  body:         bytes,
  host:         string,
  request_id:   string
}

HttpResponseEnvelope {
  status:       u16,
  headers:      list<(string, string)>,
  body:         bytes
}