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.
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. Theingress.http entitlement permits inbound HTTP requests. The on-chain Route Registry maps names to actor addresses.
- The
ingress.httpentitlement 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.
- Public asset hosting from CBFS
Visibility::Publicvolumes (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:- An LLM-powered actor has its own API and identity without a hosting provider or cloud account.
- Anyone can audit the on-chain, deterministic code behind a DNS-addressable actor.
- The actor serves requests, persists without infrastructure management, scales through the protocol, and bills natively.
- 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
ActorMessagetransactions for state-mutating requests. - Define Gateways as a first-class ingress role, separate from Runners and Relay Nodes.
- Model the entitlement using the canonical
EntitlementGrantformat (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
ActorMessagetransaction that goes through consensus.
6. The ingress.http Entitlement
6.1 Registry Entry
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.
name and updates the reverse index from actor_address to its names on each write.
7.2 Naming Hierarchy
Actors register names underactors.example.org:
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 itshttp.requesthandler. The fullHostheader is passed to the actor.OPEN(2): Any actor withingress.httpcan register subdomains under this name (community namespaces).
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
- Caller is the actor or its deployer account, or holds a delegation authorizing
Action::ActorExecuteHandler(b"register"). - Target actor has the
ingress.httpentitlement. - Name is not already registered (or has expired past grace + auction).
- 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:
system:registry_settlement_config at GOVERNANCE_SYSTEM_ACTOR=0x09 (§9.7). The required default allocation is:
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_atfrom the current expiry (not from the current block), preventing gaps. - After expiry, a grace period of
NAME_GRACE_PERIODblocks (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
10xthe annual fee and declining linearly to1xoverNAME_AUCTION_DURATIONblocks (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 withset_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_actorandsend_messageare trapped on the read path. Command forwarding requires the backend to authenticate the router explicitly (§8.4.2). - With
upgrade_self, an actor holdingsys.upgradecan replace itscode_hashwhile retaining its address and storage. Storage-schema and ABI compatibility remain the actor author’s responsibility.
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.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: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 (anExecuteActor 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: return202 Acceptedwithx-cowboy-submit-status: admitted-pending.Submit, when the validator reportstimed_outafter admission while waiting for a receipt: return the same202 Acceptedacknowledgement and admission header.Submit, succeeded with missing/empty output: return the configured fallback unmodified, or202 Acceptedwith empty headers/body when none is configured.
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:
- Resolve
fqdntoactor_addressviaSTATE_GETagainstROUTE_REGISTRY. - Call
POST /actor/readwithactor = actor_address,handler = target.namefrom the matchedMethodroute, and the base64-encoded, serializedHttpRequestEnvelopeaspayload. The direct-ingress default handler is"http.request". Setmax_cyclesto the minimum of the actor’smax_query_cycles, the ingress ceiling, and the node’s per-call ceiling. - 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. - Deserialize the response as
HttpResponseEnvelope. If invalid, Gateway returns502 Bad GatewaywithX-Cowboy-Error: INVALID_RESPONSE. - Check the returned
block_heightagainstX-Cowboy-Min-Block, if present (§8.3.5). Only then return the handler response withX-Cowboy-Block: <block_height>.
8.3.1 RPC
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_prefixfrom 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.
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, noemit_event, no time/network/filesystem). HostContextambient values (block_height,block_timestamp,self_address) are committed-state quantities.- Storage reads return the committed state at the height observed.
8.4 Command Execution
Native paid Method admission is separate from Gateway authenticity. A paid CIP-15Method 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 signsExecuteActor 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:
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:
- Verify
tx.senderis a registered active Gateway viaGATEWAY_REGISTRY.is_active_gateway. - Verify
targetdeclaresingress.http. - Verify envelope size ≤
target’smax_request_bytes. - Synthesise an internal
ActorMessageto the target’shttp.requestselector withctx.sender = GATEWAY_REGISTRY=0x0F. - 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-ingresshttp.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 ordinarytx.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 is202, the polling headers identify the pending receipt:
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.
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 usesACTOR_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
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
IngressDispatchinvokes the actor handler:- A successful return invokes the
complete_receipt(request_id, envelope)instruction (sender = current handler context, verified to equaltarget_actor). - On a handler panic or cycle limit, the dispatcher writes
status = FAILEDdirectly with no envelope.
- A successful return invokes the
- The registry reads
receipt_ttl_blocksfrom the actor’singress.httpentitlement (defaultRECEIPT_TTL_BLOCKS = 3_600, maxRECEIPT_TTL_MAX = 86_400). - A single registry-wide pruning loop scans
expires_atper 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 originalgateway 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.
- 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).
9.2 Gateway Registry
The Gateway Registry is a system actor at reserved address0x0F. It manages Gateway registration, staking, and health.
- To register, a Gateway stakes
MIN_GATEWAY_STAKECBY and callsregister_gateway(endpoint, http_port). - The Gateway calls
heartbeat()periodically. Health resets toMAX_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_DELAYblocks, provided it is no longer in the active list.
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.
9.4 Gateway Incentives
Read fromsystem:gateway_pool_config at 0x09:
gateway_percent slice of registration / renewal fees) is distributed to active Gateways pro-rata to:
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 callGatewayRegistry.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.
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 throughSettlementConfig 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_configdefines splits for name registration / renewal fees (§7.5)system:gateway_pool_configdefines splits for the Gateway serving fee pool (§9.4)
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.orgwork 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.httpgrant 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_cycleslimit 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-Blockresponse header andX-Cowboy-Min-Blockrequest 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.
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 throughGatewayRegistry.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_cyclesentitlement 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.13. Related Serving Specifications
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 suppliesStorageCommitment 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. ManifestCommittedevents 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.
13.2 Entitlement Shapes
Ingress parameters must fit the canonicalParamValue 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
202leaves 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
privatefield also needs a canonical response-envelope representation. - Define how expiry remains distinguishable from an ID that never existed after pruning, so
410versus404does 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.