Skip to main content

CIP-14: DNS-Addressable Actors

Status: Draft Type: Standards Track Category: Core Created: 2026-03-07 Updated: 2026-11-03 Requires: CIP-2 (Off-Chain Compute), CIP-3 (Gas), CIP-5 (Timers), CIP-6 (SDK)
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.
This document specifies the required protocol behavior. Implementation coverage and unresolved contracts are listed in §14; a normative requirement is not a claim that the corresponding service or instruction is implemented.
The registered-name DNS suffix below is an illustrative deployment parameter. For currently deployed address-based gateway URLs, use the Networks table; Canyon uses <0xactor>.canyon.cowboylabs.net.

1. Abstract

Background

HTTP ingress lets browsers and ordinary API clients reach actor handlers without constructing blockchain transactions.

Goal

This CIP specifies how Gateways route internet HTTP traffic to Cowboy actors by domain name. The ingress.http entitlement permits inbound HTTP requests. The on-chain Route Registry maps names to actor addresses.
  • The ingress.http entitlement grant and its parameter schema.
  • A Route Registry system actor that maps names to actor addresses.
  • A canonical HTTP request/response envelope for actor message handlers.
  • An explicit query path (read-only, no consensus) using the read-only handler RPC (§8.3), distinct from the command path (state-mutating, consensus-required).
  • A Gateway role that bridges HTTP to actor messaging.
  • Subdomain-first naming under actors.example.org.
Related specifications cover the following independently:
  • Public asset hosting from CBFS Visibility::Public volumes (CIP-15).
  • CIP-7 Watchtower stream bridging to SSE/WebSocket; replacement service authorization and key delivery remain outside this CIP.
  • Payment gating via x402 or other protocols.

2. Motivation

Cowboy actors are autonomous programs with persistent state, message handlers, timers, LLM inference, and off-chain compute. HTTP ingress allows browsers and ordinary API clients to reach actors without constructing blockchain transactions themselves. Existing blockchain naming systems (ENS, Handshake, Unstoppable Domains) resolve names to addresses or content hashes. Cowboy actors handle requests. DNS addressing supports the following services:
  1. An LLM-powered actor has its own API and identity without a hosting provider or cloud account.
  2. Anyone can audit the on-chain, deterministic code behind a DNS-addressable actor.
  3. The actor serves requests, persists without infrastructure management, scales through the protocol, and bills natively.
  4. An actor can fund its compute with API revenue and operate without human intervention.

3. Design Goals

  • Introduce HTTP ingress without changing actor execution semantics.
  • Respect the existing asynchronous actor messaging model.
  • Use the read-only handler RPC for fast, read-only requests.
  • Use standard ActorMessage transactions for state-mutating requests.
  • Define Gateways as a first-class ingress role, separate from Runners and Relay Nodes.
  • Model the entitlement using the canonical EntitlementGrant format (dotted string ID with params).
  • Limit the scope to ingress routing. Asset hosting, stream bridging, and payment are specified separately. Protocol-managed custom domains are outside scope.

4. Non-goals

  • Protocol-managed custom-domain binding and first-party TLD registration.
  • Replacing native actor-to-actor messaging. HTTP is the external ingress protocol. Internal actor composition MUST use send_message.
  • Synchronous off-chain compute within HTTP handlers. LLM inference and HTTP egress remain asynchronous (CIP-2 submit_job + callback).
  • Public static asset hosting (CIP-15).
  • Real-time stream bridging (CIP-17).
  • Payment gating (CIP-18).
  • Custom TLDs or alternative DNS roots.

5. Definitions

  • A Gateway is a network node that terminates TLS, resolves actor names, and bridges HTTP requests to the actor message protocol. Gateways are a dedicated ingress role, distinct from Runners, Validators, and Relay Nodes.
  • The Route Registry is a system actor that maintains the authoritative mapping from domain names to actor addresses.
  • The query path provides read-only request execution via the read-only handler RPC. The actor handler runs against committed state without creating a transaction or requiring consensus.
  • The command path provides state-mutating request execution via a standard ActorMessage transaction that goes through consensus.

6. The ingress.http Entitlement

6.1 Registry Entry

The entry is non-inheritable and unattested. quota: false means the max_* parameters are per-request limits, not a cumulative quota. The registry MUST remain lexicographically sorted and its entry-count assertion MUST match the entries. Current code differs on the quota flag; see §14.

6.2 Parameters

All seven parameters are optional and recognized from genesis in rules-v2. Omitted values use the defaults below; allowlist_methods = ["*"] permits all methods. CIP-15 §7.1 defines the two static-serving parameters and their upgrade exception. The Gateway MUST enforce min(actor_param, hard_ceiling). The deploy-time manifest validator MUST reject unknown methods, zero-value caps, and any param exceeding its hard ceiling.

6.3 Example Actor Manifest

6.4 Enforcement

  • The manifest validator checks parameter shapes and bounds at deployment.
  • The Gateway rejects requests to actors lacking ingress.http. It enforces request/response size and sets the actor cycle limit on read-handler calls and command dispatch. Command execution also remains subject to the transaction gas limits; the dispatch encoding for the actor limit needs definition (§14).

7. Route Registry

7.1 System Actor

ROUTE_REGISTRY=0x0E stores the authoritative name-to-actor mapping.
The registry keys records by canonical name and updates the reverse index from actor_address to its names on each write.

7.2 Naming Hierarchy

Actors register names under actors.example.org:
When an actor registers myagent, it owns the entire subtree *.myagent.actors.example.org. Subdomain resolution depends on the subdomain_policy:
  • OWNER_ONLY (0, default): Only the registration owner can add subdomain records that map to other actors.
  • ACTOR_MANAGED (1): The actor handles all subdomain routing internally via its http.request handler. The full Host header is passed to the actor.
  • OPEN (2): Any actor with ingress.http can register subdomains under this name (community namespaces).
Defaulting to OWNER_ONLY prevents arbitrary subdomain crawls from consuming the parent actor’s read-execution budget. An owner can opt into ACTOR_MANAGED when the parent is intended to serve the subtree.

7.3 Name Constraints

  • Names follow the registry-name grammar of CIP-10 §5.11: 3 to 63 bytes of a-z, 0-9, and -, beginning and ending with a letter or digit, with no two consecutive hyphens. Every such name is a valid DNS label.
  • Reserved names (www, api, dns, gateway, relay, node, cowboy, system, admin) are held by governance.

7.4 Registration

Registration has the following requirements:
  1. Caller is the actor or its deployer account, or holds a delegation authorizing Action::ActorExecuteHandler(b"register").
  2. Target actor has the ingress.http entitlement.
  3. Name is not already registered (or has expired past grace + auction).
  4. Registration fee is paid in CBY.

7.5 Registration Economics

Registration uses a fee schedule based on name length to discourage squatting: Registration fees scale by the registration period:
The registry reads the fee split for CIP-14 from system:registry_settlement_config at GOVERNANCE_SYSTEM_ACTOR=0x09 (§9.7). The required default allocation is:
The allocation values are basis points and MUST sum to 10,000. Governance updates use UpdateSettlementConfig with target_pool: REGISTRY (§9.7). The current node type and execution path do not implement this three-way allocation; see §14.

7.6 Renewal and Expiry

  • Names can be renewed at any time by paying the fee for an additional period.
  • Renewal extends expires_at from the current expiry (not from the current block), preventing gaps.
  • After expiry, a grace period of NAME_GRACE_PERIOD blocks (default: 2,592,000, ~30 days) allows the owner to renew at the standard rate.
  • After the grace period, the name enters a descending-price Dutch release auction starting at 10x the annual fee and declining linearly to 1x over NAME_AUCTION_DURATION blocks (default: 604,800, ~7 days). This prevents sniping at the exact expiry block.

7.7 Route Registry API

The Route Registry system actor exposes the following message handlers: resolve and lookup MUST support read-only invocation against the canonical registry state, without requiring a transaction.

7.8 Actor Updates

A registration owner can point a name at another actor with set_actor (§7.7). Two actor-level patterns also support application updates:
  • A router actor is a stable proxy that stores the current implementation address. Its owner updates that address through an authenticated handler. Read-only requests must be served from the proxy’s own state, because call_actor and send_message are trapped on the read path. Command forwarding requires the backend to authenticate the router explicitly (§8.4.2).
  • With upgrade_self, an actor holding sys.upgrade can replace its code_hash while retaining its address and storage. Storage-schema and ABI compatibility remain the actor author’s responsibility.
Choose one actor-level update pattern per application actor. This CIP does not specify how to combine proxy routing and in-place code replacement.

8. Request Execution

8.1 Canonical HTTP Request Envelope

When a Gateway receives an HTTP request for a registered actor, it translates it into a canonical message envelope. CIP-15 §15.2 is authoritative for these field names and types; this section restates them with the Gateway’s encoding and forwarding rules.
Encoding. The envelope is CBOR: a map keyed by the field names above, with map keys sorted length-first per RFC 8949 §4.2.3, so the encoded key order is body, host, path, query, method, headers, request_id, path_params. body is a CBOR byte string, not a text string. On the read path the Gateway base64-encodes those bytes as the payload of POST /actor/read (§8.3.1); on the command path it carries them unencoded as the ExecuteActor payload (§8.4). query. The Gateway forwards the query string as one opaque value and does not parse it. Repeated keys, bracket or comma array conventions, valueless keys and percent-encoding all reach the handler exactly as the client sent them, and the handler decodes them. A request with no query string and a request ending in a bare ? both arrive as "". headers. Header names are lowercase, normalized on receipt. A repeated header name appears as one pair per value instead of being joined or collapsed: accept-encoding: gzip followed by accept-encoding: br arrives as two pairs sharing the name, in that relative order. A handler reading a single value therefore scans the sequence; it cannot index the field as a map. The order of the sequence as a whole is unspecified, arbitrary though stable for a given Gateway build, and only the values sharing one name keep their relative order, so a handler MUST NOT depend on the order. A value reaches the handler intact only if every byte of it is printable ASCII (0x20-0x7E) or a horizontal tab. A value carrying any other byte, which includes every non-ASCII character, arrives as "" under its own name rather than being dropped, as does an unreadable Host. Otherwise the Gateway forwards the headers it received, so an x-cowboy-* header the client supplied appears in this sequence. The one exception is x-cowboy-purchase-id: when the request carries a pending settlement, the Gateway sets that header to its own purchase identifier before building the envelope, replacing any value the client sent under the name. MCP ingress does not forward caller headers at all; it synthesizes a minimal set (CIP-19 §11.2). body. Always present and never null. A GET, HEAD or DELETE with no body carries an empty byte string, which a handler cannot distinguish from an explicitly empty body. path. The path against which the route matched: the full URL path under host resolution, and the remainder after the leading /<actor_address> segment under path resolution (CIP-15 §15.1). request_id. Gateway-generated and opaque. The pinned Gateway formats it from its wall clock as gw-<hex nanoseconds> with no counter, so distinctness per request is intended rather than enforced: two requests the clock cannot separate, or a clock that steps backwards, can repeat a value. When the request carries a pending settlement the Gateway substitutes its purchase identifier, the same value it puts in x-cowboy-purchase-id. A handler MUST NOT parse the field as a UUID, read a timestamp out of it, or rely on it alone to deduplicate.

8.2 Canonical HTTP Response Envelope

Actors return responses in a canonical envelope, CBOR-encoded under the same profile as §8.1 and likewise specified by CIP-15 §15.2:
All three fields are required. body is a CBOR byte string; a null body does not decode and is an invalid envelope (§8.2.1). The pinned Gateway serves any status in 100-999 as given and answers 502 Bad Gateway for anything outside that range, so the 100-599 bound above is the contract on actors rather than an enforced clamp. Header names need not be lowercase, and the pair form can carry a repeated name. The pinned Gateway nevertheless sets each returned header rather than appending it, so when the list repeats a name only the last pair for that name reaches the client, and a response cannot yet send two set-cookie headers through this envelope. A pair whose name or value is not a valid HTTP header is dropped without failing the response. Faithful repeated-header relay remains unimplemented.

8.2.1 Command Responses and Fallbacks

On the command path the Gateway submits the handler invocation as a transaction (an ExecuteActor submit-and-wait against a validator) and acts on the validator’s result. When the validator reports a succeeded result whose handler output is absent or empty, with no result or a result that decodes to zero bytes, the Gateway MUST NOT treat the missing envelope as an invalid response. It MUST instead answer with the route’s declared fallback_response (returned unmodified) or, if the route declares none, with 202 Accepted, empty headers, and an empty body. A succeeded result whose output is non-empty but does not decode to an HttpResponseEnvelope (above) is still an invalid envelope and MUST yield 502 Bad Gateway. A succeeded result that carries a decodable envelope always takes precedence over fallback_response. An empty succeeded response is the normal shape for a route whose handler suspends to a runner in its initial segment (a @runner.continuation handler): the initial segment returns no value, so the PVM emits no output and the succeeded result carries no result. The work continues asynchronously on the runner and the client retrieves the eventual result by polling. The Gateway therefore acknowledges acceptance with 202 or the route fallback; 502 would incorrectly report a failure. This follows the receipt read API’s convention of returning 202 Accepted for PENDING (§8.8.3) and the asynchronous-handler pattern (§8.8.5). On the read path, which serves GET/HEAD through the read handler (the Gateway’s /actor/read dispatch, §8.3.1), an absent or empty result is still an invalid envelope and MUST yield 502 Bad Gateway. The empty-result rule above applies only to the command path. The X-Cowboy-Error: INVALID_RESPONSE mapping for that case is the §8.3.4 specification; the pinned gateway returns the 502 (actor invoke failed) without that header. The header remains unimplemented. Continuations belong on the command path. A Gateway route MAY declare a canned {status, headers, body} as its fallback_response for these three cases:
  • SubmitNoWait, after the node confirms admission: return 202 Accepted with x-cowboy-submit-status: admitted-pending.
  • Submit, when the validator reports timed_out after admission while waiting for a receipt: return the same 202 Accepted acknowledgement and admission header.
  • Submit, succeeded with missing/empty output: return the configured fallback unmodified, or 202 Accepted with empty headers/body when none is configured.
For the first two cases, preserve the configured fallback body and other headers, but force status 202 and replace any case-insensitive x-cowboy-submit-status header with admitted-pending. Without a fallback, the body is empty and the admission header is the only header supplied by this response. Admission is not execution success: the transaction may still execute or revert. A transport failure or an unknown admission outcome is not a timed_out receipt result and MUST NOT be described as confirmed admission. Settlement (paid routes). The former settle-after-success/D1 fire-and-forget rule is superseded. Confirm the selected payment before dispatching the initial paid operation, following CIP-18 §15.3. Associate the continuation with the same purchase and execution identity. A 202 Accepted or successful fallback response acknowledges the initial segment; it does not prove continuation completion. An interrupted or failed continuation follows the purchase recovery/refund rule without charging the client again. Unknown execution MUST NOT be automatically redispatched or refunded. Paid WebSocket/101 upgrades and resumable paid SSE are unsupported in this release and MUST be rejected before settlement and backend connection; see CIP-18 §6.2.

8.3 Read-Only Execution

Gateway flow for read mode (GET/HEAD by default), resolved under CIP-15 §6.2:
  1. Resolve fqdn to actor_address via STATE_GET against ROUTE_REGISTRY.
  2. Call POST /actor/read with actor = actor_address, handler = target.name from the matched Method route, and the base64-encoded, serialized HttpRequestEnvelope as payload. The direct-ingress default handler is "http.request". Set max_cycles to the minimum of the actor’s max_query_cycles, the ingress ceiling, and the node’s per-call ceiling.
  3. Node executes via PVM read-only mode. The trapped syscalls, state_set, state_delete, send_message, call_actor, schedule_timer*, cancel_timer, submit_job, token_transfer*, create_deferred_tx, upgrade_self, emit_event, randomness, are listed in §8.3.3.
  4. Deserialize the response as HttpResponseEnvelope. If invalid, Gateway returns 502 Bad Gateway with X-Cowboy-Error: INVALID_RESPONSE.
  5. Check the returned block_height against X-Cowboy-Min-Block, if present (§8.3.5). Only then return the handler response with X-Cowboy-Block: <block_height>.

8.3.1 RPC

The request and response are the ActorReadRequest and ActorReadResponse shapes shown above. The RPC also accepts mutually exclusive payload_text or payload_json alternatives; Gateway ingress uses payload to pass the serialized envelope bytes directly. Budgets MUST be positive and within the node’s per-call ceilings. The node bounds all three resources even when the optional limits are omitted. Gateway ingress MUST propagate the effective actor cycle cap, rather than relying on a fixed local default; operator-selected cell/access budgets cannot exceed node ceilings. block_height is omitted or null: this CIP requires latest-state execution with a minimum-height response check, not historical pinned reads. The node currently rejects a non-null block_height.

8.3.2 Host Mode

Handler execution MUST run with a read-only host context. In this mode the host:
  • Returns from state_get / state_scan_prefix from the committed snapshot.
  • Traps on every mutating syscall; see §8.3.3 for the exhaustive table.
  • Uses a synthetic zero sender and transaction hash, as in the node read RPC; there is no authenticated transaction caller. Read authorization is established by the runtime read-only context, not by an HTTP method or other envelope field.
The read-only flag MUST govern the host boundary, including every path that can mutate state or dispatch work. New syscalls default to trapped unless explicitly admitted as pure reads.

8.3.3 Syscalls

Ambient context syscalls (block_height, block_timestamp, self_address) are permitted; they read fields from HostContext rather than calling the host trait. The host traps forbidden calls with HostError::Forbidden; the node read RPC reports ActorReadStateMutation. The Gateway maps this condition to HTTP 500 with X-Cowboy-Error: READ_ONLY_VIOLATION.

8.3.4 Errors

8.3.5 Consistency

X-Cowboy-Block reflects the block_height returned by the read RPC. Clients requiring a floor send X-Cowboy-Min-Block: N. The Gateway MUST check the returned execution height and suppress the handler response if it is below N, returning 503 with X-Cowboy-Error: MIN_BLOCK_NOT_REACHED. Checking the node’s latest height separately is insufficient: the check must cover the state used for this read. Reads to different Gateways may reflect different heights; the floor does not require execution at an exact historical height.

8.3.6 Determinism

Two Gateways executing the same /actor/read request against the same committed state root and block context MUST return byte-identical bodies. This holds because:
  • Read-only PVM execution is pure (no randomness, no emit_event, no time/network/filesystem).
  • HostContext ambient values (block_height, block_timestamp, self_address) are committed-state quantities.
  • Storage reads return the committed state at the height observed.
The Gateway absorbs read-path compute cost; the actor is not charged because there is no transaction. Cycle counting follows CIP-3 PVM metering. The Gateway MUST apply the actor limit and the protocol ceiling; exceeding the budget aborts the handler.

8.4 Command Execution

Native paid Method admission is separate from Gateway authenticity. A paid CIP-15 Method request follows CIP-18 §8.5: an ordinary signed transaction carries the native payment authorization and bound HTTP envelope into the outer ExecuteActor entry. The node consumes payment and executes the selected handler atomically. This path neither synthesizes a 0x0F sender nor proves the HTTP request came from a registered Gateway. Application authentication remains separate from payment authority. Paid read handlers also enter through this consensus boundary; the business handler remains read-only. The registry-mediated direct-ingress contract below is separate Gateway-authenticity work. Its sender requirement applies to that dispatch path, not to native paid Method admission.

8.4.1 Dispatch

The required registry-mediated dispatch contract below remains implementation work (§14). The current Gateway path instead signs ExecuteActor directly to the selected route handler; direct submission does not provide registry authentication or the HTTP receipt contract. Both paths charge the Gateway signer under §8.4.3. The required IngressDispatch system instruction carries:
Under the required registry-mediated contract, the Gateway submits a signed transaction to GATEWAY_REGISTRY.dispatch. That handler verifies the operating account before emitting IngressDispatch; only GATEWAY_REGISTRY=0x0F may emit the instruction. The execution dispatcher MUST enforce this sender allowlist. Dispatch flow:
  1. Verify tx.sender is a registered active Gateway via GATEWAY_REGISTRY.is_active_gateway.
  2. Verify target declares ingress.http.
  3. Verify envelope size ≤ target’s max_request_bytes.
  4. Synthesise an internal ActorMessage to the target’s http.request selector with ctx.sender = GATEWAY_REGISTRY=0x0F.
  5. After the actor handler returns (or traps), write the result to RECEIPT_REGISTRY (§8.8).

8.4.2 Sender Authentication

For registry-mediated transactional command invocation, actors implementing the direct-ingress http.request selector MUST verify ctx.sender == GATEWAY_REGISTRY=0x0F and reject other senders. Runtime-authenticated read-only invocation (§8.3.2) does not require a registry sender. Handlers MUST determine that distinction from trusted execution context, never from the attacker-controlled envelope.method or another request field. The SDK (CIP-6) @http.handler decorator MUST include this check by default. Actors that implement the http.request selector without that decorator MUST include it manually. The protocol derives ctx.sender from the authenticated execution context; actor code cannot choose another actor’s sender address. The selector itself is not reserved by the message router. A backend receiving a forwarded request must authenticate its trusted router and distinguish that call from direct Gateway ingress. SDK handlers for direct ingress retain the registry-only default. Query-path calls have no transaction sender and are subject to the read-only contract (§8.3).

8.4.3 Gas Payment

The Gateway operating account pays gas as ordinary tx.from. Stake (held in GATEWAY_REGISTRY per §9.2) is not drawn down for fees; it remains locked collateral. A slashing policy is not yet specified (§12.2). For on-chain ingress, the current Gateway path signs ExecuteActor directly to the route handler and charges the signing wallet, subject to the separately authorized CIP-7 subscriber basefees in CIP-28 §3.4. The required registry dispatch in §8.4.1 retains the Gateway as the signed sender and gas payer. The route label pays: actor means the caller pays no service price when no enabled CIP-18 price table overrides it; it and an actor’s Action::FallbackToOwnerBalance entitlement do not authorize the chain to debit the callee for this signed top-level call. GET/HEAD default to unsigned Read mode with no transaction gas; an explicit route mode overrides the verb, and Submit/SubmitNoWait sign and pay gas. CIP-15 §6.2 defines the mode values and resolution rule. Fund, monitor and bound the Gateway wallet; see CIP-28 §3.4. The Gateway enforces a per-actor sponsorship budget (max_actor_spend) alongside its per-transaction cap (max_transaction_spend). The actor budget counts actual committed gas charged to the Gateway wallet plus pending reservations and unresolved signed maxima. Fee policy and aggregate payer-balance admission run before nonce allocation; a payer-balance refusal allocates no nonce. Pending liability is revalidated when it binds under the allocation lock. After committed account progress, valid committed receipt and finalized fee evidence for the winning signed variant replace the reservation with the actual charge, once per nonce. Up to four fee-bump variant receipts are read concurrently. Unresolved evidence keeps the maximum while retryable lookups remain queued. Transport errors, timeouts, HTTP failures such as 5xx/429 and compatibility errors during lookup stop the pass and retain the queued entry; later valid evidence settles it to the actual charge. Transient failures count at most once per second per entry. A timeout counts only for a lookup that received its full two-second budget; a later lookup cut short by the shared pass deadline is deferred without a strike or failure-timestamp update. An explicit transient error still counts under the spacing rule. A definitive miss (strict not-found for all signed variants), malformed or mismatched evidence, three failures at least one second apart, or queue overflow drops that evidence work and keeps its maximum for the process lifetime. The queue holds at most 128 nonces and discards the oldest evidence work on overflow; failed recovery or unavailable compatibility evidence before a pass does not consume retries. One settlement pass runs at a time. A bounded background tick refreshes committed account state and runs the same pass even without further writes, sharing the foreground settlement guard. [gateway].actor_settlement_interval_ms sets the interval (default 5,000 ms, minimum 100 ms); each tick has a five-second deadline and holds no nonce lock over I/O. Proven-unsent or proven-not-admitted attempts release their reservations. New nonces enforce the actor budget; same-nonce recovery may raise a reservation above it while still obeying the per-transaction and aggregate payer limits. Counters reset on restart, so operators must maintain wallet funding ceilings and monitor balances across restarts. Watchtower restores every recorded, non-refused fee variant before any recovery POST: it rebroadcasts the latest bytes, retains all variant hashes for fee matching, and shares the maximum liability across variants at one nonce. 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). The callee-scheduled, sender-billed timer path no longer exists under that rule; it is not an exclusion from the Gateway budgets.

8.4.4 Response

Response selection follows §8.2.1: a valid handler envelope, the applicable route fallback, or the specified default. The receipt-backed asynchronous path acknowledges an accepted request without waiting for its eventual result; when that acknowledgement is 202, the polling headers identify the pending receipt:
The X-Cowboy-Request-Id here is the receipt’s own identifier, the request_id the dispatching IngressDispatch carried (§8.4.1), not the envelope’s request_id (§8.1); its textual form is part of the unresolved receipt binding (§14.1). For a receipt-backed acknowledgement, the client polls /_cowboy/requests/{request_id} (Gateway-intercepted reserved path; served from RECEIPT_REGISTRY; see §8.8.3). For paid routes, §8.2.1 requires confirmed payment before dispatch. An acknowledgement is tied to that purchase; pending settlement must remain pending and cannot be acknowledged as paid or retried as a fresh purchase.

8.5 Actor Handlers

The SDK @http.handler decorator MUST enforce the command-path sender check and recognize runtime-authenticated read-only invocation (§8.4.2). Custom handlers must enforce the same boundary. The HTTP method selects application behavior only after this execution-context check; it cannot authorize a command or bypass sender authentication.
Handlers MUST NOT assume synchronous off-chain compute; LLM / HTTP egress remain async via submit_job + callback (§8.8.5).

8.6 Reserved Paths (/_cowboy/*)

CIP-37 applies its owner-only site gate before any application dispatch, including the no-routes-table fallback. Website administration uses CIP-37’s protocol-owned website owner, not application ownership KV or the DNS registration owner. Data-bearing reserved endpoints, including receipt reads, enforce the same current access policy; the reserved prefix is not a blanket authentication exemption. The path prefix /_cowboy/ is reserved for protocol-level endpoints. Gateways MUST intercept these paths before dispatching to the actor’s http.request handler. Actors MUST NOT define handlers that overlap with /_cowboy/*. Future CIPs may define additional /_cowboy/* endpoints. Actors receiving a request with a /_cowboy/ path prefix via the http.request handler indicates a Gateway implementation bug.

8.7 Subdomain Routing Limitations

When an actor uses ACTOR_MANAGED subdomain policy (§7.2), all subdomain traffic is routed to the parent actor’s http.request handler with the full Host header. The actor handles subdomain dispatch internally. On the query path, subdomain routing is purely internal to the actor handler. The Gateway resolves the top-level name and passes the full Host to the actor. This means subdomain delegation to other actors is only possible on the command path (where the actor can use send_message to forward the request). On the query path, the actor handler must serve all subdomains itself from its own storage.

8.8 Receipt Registry

RECEIPT_REGISTRY=0x10 owns command-result storage and lifetime. Registry-wide pruning avoids consuming actor KV and a timer slot for each request; actors have a bounded timer budget.

8.8.1 Record

The receipt keys on the request_id the IngressDispatch instruction carried (§8.4.1), which the dispatcher can see; it is a distinct identifier from the envelope’s opaque request_id (§8.1), which is a Gateway-local string and not bytes16. How a handler names its own receipt for the asynchronous completion in §8.8.5, which reaches complete_receipt through envelope.request_id, is part of the unresolved request-ID binding in §14.1.

8.8.2 Storage and Lifecycle

  • Written by the system instruction dispatcher, not by actor code. After IngressDispatch invokes the actor handler:
    • A successful return invokes the complete_receipt(request_id, envelope) instruction (sender = current handler context, verified to equal target_actor).
    • On a handler panic or cycle limit, the dispatcher writes status = FAILED directly with no envelope.
  • The registry reads receipt_ttl_blocks from the actor’s ingress.http entitlement (default RECEIPT_TTL_BLOCKS = 3_600, max RECEIPT_TTL_MAX = 86_400).
  • A single registry-wide pruning loop scans expires_at per block. Per-actor timer budget is not consumed.
  • The protocol includes receipt storage charges in the command-path transaction fee under CIP-3. The precise cell/access accounting must reflect the stored response size (§14.1); there is no separate billing event.

8.8.3 Reads

GET /_cowboy/requests/{request_id} is a Gateway-intercepted reserved path (CIP-14 §8.6). Gateway reads via the read-handler RPC against 0x10, selector get_receipt. Status mapping:

8.8.4 Privacy

Receipts are dispatching-Gateway-readable + target-actor-readable by default. To restrict reads (sensitive responses), the actor marks the response private. The §8.2 envelope has no such field, and how an actor signals it remains unresolved (§14.1). The registry then refuses reads whose caller is not the original gateway field of the receipt. This prevents other Gateways from polling the result. The authenticated read mechanism and response-envelope field encoding are unresolved (§14.1); this access rule alone does not establish response confidentiality.

8.8.5 Asynchronous Responses

complete_receipt is a required SDK helper that emits the complete_receipt system call against RECEIPT_REGISTRY=0x10. The registry verifies ctx.sender equals the receipt’s target_actor.

9. Gateway Specification

9.1 Gateway as a Distinct Ingress Role

A Gateway is a dedicated ingress node in the Cowboy network. It is a separate role from Runners (off-chain compute, CIP-2 and CIP-10), Validators (consensus), and Relay Nodes (storage, CIP-9). Gateway routing is a separate responsibility from runner job execution and relay storage. Persistent workloads can receive traffic through the Gateway under CIP-15; this does not make runner scheduling or storage relays responsible for public HTTP ingress.
  • Participate in DNS resolution for *.actors.example.org (authoritative DNS or integration with external DNS).
  • Terminate TLS (including certificate management via ACME).
  • Use a node’s committed state and read-only execution RPC; the node may be co-located or remote.
  • Resolve HTTP request names via the Route Registry and dispatch to the query or command path.
  • Submit command-path transactions to the mempool.
  • Enforce entitlement parameters (max_request_bytes, max_response_bytes, max_query_cycles).
  • Enforce rate limits.
Gateways do NOT:
  • Store CIP-9 shards (that is the Relay Node role).
  • Execute CIP-2 off-chain tasks (that is the Runner role).
  • Participate in consensus (that is the Validator role).
A single physical node MAY operate as multiple roles simultaneously (e.g., Gateway + Relay Node + Validator), but the protocol treats each role independently.

9.2 Gateway Registry

The Gateway Registry is a system actor at reserved address 0x0F. It manages Gateway registration, staking, and health.
A Gateway moves through the following lifecycle:
  • To register, a Gateway stakes MIN_GATEWAY_STAKE CBY and calls register_gateway(endpoint, http_port).
  • The Gateway calls heartbeat() periodically. Health resets to MAX_GATEWAY_HEALTH (default: 3,600, ~1 hour at 1 block/sec). Health decays by 1 per block.
  • The registry removes the Gateway from the active list when its health reaches 0.
  • A Gateway may unstake after GATEWAY_UNSTAKE_DELAY blocks, provided it is no longer in the active list.
The Gateway Registry exposes the following API:

9.3 Gateway Selection

When a client resolves *.actors.example.org, DNS returns the IP addresses of active Gateway nodes. Selection is handled at the DNS level:
  • With anycast, all Gateways advertise the same IP prefix via BGP. Network routing selects the nearest Gateway.
  • With Geo-DNS, the authoritative DNS server returns Gateway IPs based on the client’s resolver location.
Any Gateway can serve any actor. Gateways are stateless with respect to HTTP routing. They resolve names from the Route Registry and execute queries against their node’s committed state.

9.4 Gateway Incentives

Read from system:gateway_pool_config at 0x09:
Each epoch, the pool (funded by §7.5 gateway_percent slice of registration / renewal fees) is distributed to active Gateways pro-rata to:
Updated via UpdateSettlementConfig{target_pool=GATEWAY_POOL}. Gateway revenue is uncoupled from request volume. An active Gateway that serves no requests can still earn. Request metering and per-request remuneration are outside this pool model.

9.5 Rate Limiting

The load balancer or web application firewall in front of each gateway enforces these rate limits; the gateway process itself applies none: Actors declare their own limits in their ingress.http entitlement params. Gateways enforce the minimum of the actor’s declared limit and the protocol-wide maximum.

9.6 Gateway Authentication

The registry-mediated direct-ingress command path is system-mediated: Gateways call GatewayRegistry.dispatch() (§8.4), which verifies the caller is a registered, active Gateway before forwarding the request to the target actor. The actor receives the message with ctx.sender == GATEWAY_REGISTRY_ADDRESS (0x0F), providing a protocol-level authenticity guarantee without requiring actors to maintain their own Gateway allowlists.
Registry-mediated direct-ingress handlers MUST reject transactional http.request messages where ctx.sender != GATEWAY_REGISTRY_ADDRESS. Runtime-authenticated read-only calls follow §8.3 instead; the request’s HTTP method does not select the trust boundary. Native paid Method admission instead follows CIP-18 §8.5. Its authorization binds the paid request and execution; it is not a Gateway-registration proof, and those handlers MUST NOT replace native admission with an unconditional ctx.sender == 0x0F check. An HTTP header or envelope field cannot select either trusted entry path. On the query path, there is no on-chain transaction, so no Gateway signature. The trust model for query-path responses is equivalent to any RPC node. The client trusts the Gateway to faithfully execute the query. Clients requiring stronger guarantees can run their own node and query directly.

9.7 Settlement Configuration

CIP-3 specifies burn / treasury / runner-tip splits through SettlementConfig stored at GOVERNANCE_SYSTEM_ACTOR=0x09 under key system:settlement_config, updatable via UpdateSettlementConfig (opcode 40, sender must be 0x09). This CIP requires two fee configurations under the same governance actor (no new system actor required):
  • system:registry_settlement_config defines splits for name registration / renewal fees (§7.5)
  • system:gateway_pool_config defines splits for the Gateway serving fee pool (§9.4)
Both MUST be updated via the UpdateSettlementConfig opcode (40) with a target_pool discriminant. This avoids forking burn/treasury routing across multiple ad-hoc paths. The target_pool discriminant is a canonical enumeration that settlement configuration updates share. Implementations MUST exhaustively switch on this value and reject unknown variants with ERR_UNKNOWN_POOL: Adding a new pool variant requires a CIP that explicitly extends this table. Handlers receiving an UpdateSettlementConfig with an unrecognized target_pool MUST reject the transaction; this is a soft form of governance (the variant must exist in code before it can be set). This table defines the required pool-selection contract, not current wire support. The gateway and registration allocation must be implemented together and reviewed for conservation of fees; see §14.

10. Constants


11. Rationale

  • DNS subdomain names under actors.example.org work with ordinary browsers and resolvers. Protocol-managed custom domains and alternative DNS roots are outside this CIP.
  • Reads avoid consensus while commands retain transaction ordering and gas accounting. Read responses can reflect different committed heights; clients can require a minimum height (§8.3.5).
  • On the read path, the host traps side effects immediately instead of appearing to succeed and being discarded. Randomness is excluded so the same request and committed context produce deterministic results.
  • The Gateway is an independent role: TLS, DNS, HTTP routing, and rate limiting have different operational responsibilities from consensus, runner scheduling, and shard storage. Roles may share a physical machine.
  • The ingress.http grant uses the entitlement registry and supported parameter shapes rather than a separate permission system.
  • Registry-owned result retention and pruning do not consume each actor’s timer budget.

12. Security Considerations

12.1 Query Path Isolation

Query-path execution MUST be fully isolated. A malicious actor handler MUST NOT be able to:
  • Modify state. Side-effecting syscalls trap at the read-only host boundary (§8.3.3).
  • Affect other actors. Execution is sandboxed per CIP-3 PVM guarantees.
  • Consume unbounded resources. The max_query_cycles limit is enforced per-request.
  • Exfiltrate data via side channels. The PVM is deterministic (no network, no timing, fixed hash seed).

12.2 Gateway Misbehavior

Gateways could serve stale state, fabricate responses, or drop requests. Mitigations:
  • The X-Cowboy-Block response header and X-Cowboy-Min-Block request header allow clients to detect and reject stale responses.
  • For high-value queries, clients can re-execute the actor handler against their own node’s committed state and compare results (deterministic PVM ensures identical output for the same state root).
  • A slashing policy must define provable misconduct before stake can be treated as an economic enforcement mechanism.
Gateway slashing needs an evidence format, an adjudication authority, a slash amount, and a destination for slashed funds. None is specified by this CIP. Locked stake alone does not prove that a Gateway served requests or establish that a request was withheld. This contract must be resolved before relying on stake to secure economically meaningful ingress.

12.3 Name Squatting

The tiered pricing model (§7.5) and Dutch auction release mechanism (§7.6) make squatting economically unfavorable:
  • Short, premium names have high annual fees.
  • Ongoing fees prevent indefinite warehousing.
  • The Dutch auction on expiry prevents sniping.

12.4 DoS via Command Path

An attacker could flood an actor with command-path requests. Mitigations:
  • Gateways enforce per-actor request limits (§9.5).
  • High load increases the basefee (CIP-3 EIP-1559 mechanism), making spam progressively more expensive.
  • A follow-on CIP for x402 pricing can add per-request payment requirements for command-path endpoints.

12.5 Ingress Authenticity

For registry-mediated direct ingress, the command path is system-mediated through GatewayRegistry.dispatch() (§8.4). The GatewayRegistry system actor verifies that the caller is a registered, active Gateway before forwarding the request. Actors receive ctx.sender == GATEWAY_REGISTRY_ADDRESS (0x0F), providing a protocol-level guarantee that the request originated from a verified Gateway. Native paid Method invocation supplies the distinct payment/execution guarantee in CIP-18 §8.5; it does not claim the registry authenticity guarantee. A direct, nested, timer or hook call cannot stand in for its private outer-entry authority. Registry authenticity remains separate implementation work rather than a prerequisite sender value for the paid wrapper. On the registry-mediated path, an actor that does not check ctx.sender == GATEWAY_REGISTRY_ADDRESS would process any ActorMessage with method: "http.request", including those sent by arbitrary accounts. The SDK (CIP-6) MUST include the sender check by default in its HTTP handler decorator, so that actors using the SDK are protected without explicit validation. On the query path, the runtime supplies a synthetic zero sender with no authenticated caller. The handler runs in a read-only sandbox. The SDK must recognize that runtime context explicitly; caller-controlled envelope fields cannot opt a transaction into it.

12.6 Cross-Gateway Rate Limit Bypass

Per-actor rate limits (§9.5) are enforced per Gateway. An attacker routing requests through N different Gateways can achieve N× the intended rate limit. Mitigations:
  • The command path naturally rate-limits via fee markets (CIP-3 EIP-1559 basefee increases under load).
  • The query path is the exposure surface. Gateways are stateless with respect to each other, so coordinated rate limiting requires an off-chain protocol (not specified here).
  • For high-value actors, the max_query_cycles entitlement parameter provides a per-request computation cap that applies regardless of how many Gateways are involved.
  • Future CIPs may introduce on-chain rate limiting (e.g., per-actor query budgets that decay per-block).

12.7 TLS and Trust

Gateways terminate TLS. The client trusts the Gateway to faithfully relay the actor’s response, as with CDNs (Cloudflare, Fastly). Future CIPs may define response-signing mechanisms for end-to-end verification.
Operator-configured hostnames are covered by CIP-15 §15 and carry no on-chain domain-control attestation. These serving features do not require protocol-managed custom domains.

13.1 Static-Serving Dependencies

CIP-9 supplies StorageCommitment records, manifest commitments, deterministic volume identifiers, Visibility::Public, and the lifecycle through ACTIVE, GRACE_PERIOD, DELETED, and GARBAGE_COLLECTING in that order. Static serving also requires:
  • Direct manifest retrieval through GET_MANIFEST.
  • ManifestCommitted events for eager cache invalidation, with periodic polling as a consistency floor.
  • Canonical manifest serialization and Merkle computation from CBFS.
  • Serving decisions tied to the CIP-9 volume status.
CIP-9 and CIP-15 define these storage and serving contracts. An implementation using shard reconstruction or time-based polling must state its latency and freshness limitations; those mechanisms do not establish direct-fetch or event-invalidation coverage.

13.2 Entitlement Shapes

Ingress parameters must fit the canonical ParamValue shapes. The ingress.http fields in §6 use Uint and StrArray; nested objects and arrays of structs are not valid parameter values. Supported string/array size limits must be enforced during manifest validation. Static serving uses CIP-15’s ingress.http.static_volumes and max_static_response_bytes parameters (CIP-15 §§3, 7, and 11.2). CIP-15 owns that schema and its per-volume cache limits. The node currently represents static_volumes as a StrArray of volume names; carrying and enforcing the per-volume max_cache_bytes requirement remains a CIP-15 schema/enforcement gap, not a requirement for a separate ingress entitlement.

14. Implementation Requirements

The table below records the current state and the remaining contract per area. It does not establish that every requirement in this CIP is complete.

14.1 Receipt Contracts

The receipt requirements need the following details resolved before implementation can be considered complete:
  • Define how an initial handler response of 202 leaves the receipt pending until an authenticated asynchronous callback completes it; ordinary successful responses can complete immediately.
  • Bind request IDs to their target and dispatching Gateway, define duplicate/replay handling, and reject completion by any other actor.
  • Define an authenticated read context for private receipts. The read-only RPC has no transaction sender, so comparing a nonexistent caller with the stored Gateway address does not enforce privacy. The private field also needs a canonical response-envelope representation.
  • Define how expiry remains distinguishable from an ID that never existed after pruning, so 410 versus 404 does not depend on deleted data.
  • Specify bounded pruning work and all cell/access charges for receipt writes and reads; a receipt can contain a large response envelope and cannot be assumed to cost one storage cell regardless of its size.

14.2 Completion Evidence

Acceptance coverage must exercise the Gateway-to-node path, not only isolated helpers: deployment validation, name ownership and expiry, read-only traps and budgets, minimum-height rejection, authenticated dispatch, sender-paid fee settlement with zero additional sponsorship debit for the callee/card/owner roles, duplicate and private receipt handling, delayed completion, bounded pruning, and conservation of all fee shares. For fee-settlement acceptance, require unchanged balances only for distinct non-paying callee/card/owner accounts in a no-transfer, no-callback fixture, and exactly one sender fee debit when roles alias (for example owner == tx.from), as in CIP-3 §2.5. Gateway slashing also requires the policy in §12.2. Missing implementation remains required work; it is not waived by this document’s Draft status.