​

CIP-14 v2

Versioning. This is v2 of CIP-14. v1 is the canonical document cip-14-dns-addressable-actors.md (preserved verbatim as Part I). v2 = v1 + the alignment revision (Part II) + the cross-cutting conventions (Part III). Conflict rule: Part II is canonical wherever it contradicts Part I. Part III defines shared conventions referenced by Part II. Summary of v2 changes

• queryActor → read_handler RPC + PVM read-only mode. v1 referenced a hypothetical “Milestone 2 §5.2 queryActor” that does not exist in node/rpc/src/rpc.rs. v2 specifies a concrete RPC and PVM mode flag with an exhaustive trapped-syscall table.
• System actor renumbering v1 two-byte 0x0011 / 0x0012 → single-byte 0x0E / 0x0F / 0x10 (continues the existing 0x01..0x0D sequence; 0x0C is SESSION_ACTOR and 0x0D is STREAM_KEY_MANAGER per system_actors.rs).
• Sender authenticity for "http.request". Actors check ctx.sender == GATEWAY_REGISTRY=0x0F (SDK-default in @http.handler). An earlier CIP-14 v2 draft proposed PVM-router selector reservation; that proposal is withdrawn because it broke router-actor forwarding patterns — see §6.2 Note.
• Receipt registry replaces _http/results/{request_id} actor-KV pattern. Avoids exhausting MAX_TIMERS_PER_ACTOR=1024 per actor.
• Stake vs. operating balance separation. Gateway stake stays locked collateral; gas comes from the operating account. Actor-funded ingress uses existing Action::UseOwnerBalance.
• Real syscall names. Trap table uses state_set / schedule_timer / token_transfer / submit_job (not set_storage / set_timeout / transfer / submit_task). Adds randomness to the trap list — v1 missed it.
• Default subdomain_policy = OWNER_ONLY (was ACTOR_MANAGED) to prevent accidental subdomain DoS.
• Settlement reuse. Name registration and Gateway pool fees route through system:registry_settlement_config and system:gateway_pool_config under GOVERNANCE_SYSTEM_ACTOR=0x09 via the existing UpdateSettlementConfig opcode.

​

Part I — v1 Specification (verbatim from cip-14-dns-addressable-actors.md)

​

1. Abstract

• 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 queryActor RPC primitive, distinct from the command path (state-mutating, consensus-required).
• A Gateway role — a dedicated ingress node type that bridges HTTP to actor messaging.
• Subdomain-first naming under cowboy.network.

• Public asset hosting via CIP-9 (PUBLIC_READ volumes).
• CIP-7 stream bridging to SSE/WebSocket (see CIP-17).
• Payment gating via x402 or other protocols.
• Custom domain binding and first-party TLD support (see CIP-16).

​

2. Motivation

1. AI agents with web presence: An LLM-powered actor with its own API and identity — no hosting provider, no cloud account.
2. Verifiable APIs: Anyone can audit the code behind a DNS-addressable actor because the actor code is on-chain and deterministic.
3. Self-sovereign web services: The actor is the server. It persists without infrastructure management, scales through the protocol, and bills natively.
4. Autonomous economic agents: An actor can earn revenue from its API, use that to fund its own compute, and operate indefinitely without human intervention.

​

3. Design Goals

• Introduce HTTP ingress without changing actor execution semantics.
• Respect the existing async actor messaging model — no synchronous assumptions.
• Use the existing queryActor RPC primitive 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).
• Keep the scope tight: ingress routing only. Defer asset hosting, stream bridging, payment, and custom domains to follow-on CIPs.

​

4. Non-goals

• 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-task + deferred callback).
• Public static asset hosting (future CIP extending CIP-9).
• Real-time stream bridging (future CIP bridging CIP-7 to SSE/WebSocket).
• Payment gating (future CIP integrating x402 or similar).
• Custom TLDs or alternative DNS roots.

​

5. Definitions

• Gateway: 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.
• Route Registry: A system actor that maintains the authoritative mapping from domain names to actor addresses.
• Query path: Read-only request execution via queryActor — the actor handler runs against committed state without creating a transaction or requiring consensus.
• Command path: State-mutating request execution via a standard ActorMessage transaction that goes through consensus.

​

6. The ingress.http Entitlement

​

6.1 Entitlement Grant

Amendment required: The Entitlements Specification §9 states “Any entitlement not listed here is invalid” (§10). Adoption of this CIP MUST add a new §9.x Ingress section to the Entitlements Specification containing the ingress.http row below. Until that amendment lands, ingress.http is not a valid entitlement and actors declaring it will be rejected at deployment.

​

6.2 Parameter Schema

​

6.3 Example Actor Manifest

{
  "entitlements": [
    {"id": "ingress.http", "params": {
      "allowlist_methods": ["GET", "HEAD", "POST"],
      "max_request_bytes": 1048576,
      "max_response_bytes": 1048576,
      "max_query_cycles": 10000000
    }},
    {"id": "storage.kv", "params": {"max_bytes": 10485760}},
    {"id": "econ.hold_balance"},
    {"id": "econ.transfer"}
  ]
}

​

6.4 Enforcement

• Deployment-time: The deployment transaction is rejected if ingress.http params are invalid (unknown methods, zero-value quotas).
• VM syscall gate: Not applicable — ingress.http is enforced at the Gateway and Route Registry, not within the PVM.
• Gateway enforcement: Gateways MUST reject requests to actors without ingress.http. Gateways MUST enforce max_request_bytes and max_response_bytes. On the query path, Gateways MUST enforce max_query_cycles.

​

7. Route Registry

​

7.1 System Actor

name → RouteRegistration

RouteRegistration {
  actor_address:     Address,       // the actor this name resolves to
  owner:             Address,       // the account that owns this registration
  registered_at:     BlockHeight,
  expires_at:        BlockHeight,
  subdomain_policy:  u8,            // 0 = OWNER_ONLY, 1 = ACTOR_MANAGED (default), 2 = OPEN
}

​

7.2 Naming Hierarchy

<name>.cowboy.network                     → top-level actor name
<sub>.<name>.cowboy.network               → subdomain of the actor
<deep>.<sub>.<name>.cowboy.network        → nested subdomain

• OWNER_ONLY (0): Only the registration owner can add subdomain records that map to other actors.
• ACTOR_MANAGED (1, default): 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).

​

7.3 Name Constraints

• Names are lowercase alphanumeric with hyphens: [a-z0-9][a-z0-9\-]{1,62}[a-z0-9].
• Minimum 3 characters, maximum 64 characters.
• Names MUST NOT start or end with a hyphen.
• Reserved names (www, api, dns, gateway, relay, node, cowboy, system, admin) are held by governance.

​

7.4 Registration

# Actor or owner calls the Route Registry system actor
send_message(ROUTE_REGISTRY, "register", {
    "name": "myagent",
    "actor_address": self_address(),
    "duration_blocks": 31_536_000,  # ~1 year at 1 block/sec
})

1. Caller is the actor or the actor’s deployer account.
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_fee = annual_fee * (duration_blocks / BLOCKS_PER_YEAR)
protocol_share   = registration_fee * REGISTRY_PROTOCOL_FEE_BPS / 10_000
burn_share       = registration_fee - protocol_share

​

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 release auction — a descending-price Dutch 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

​

7.8 Router Actor Pattern (Recommended)

@actor.handler("http.request")
def handle_http(ctx, envelope):
    # Read the current implementation actor from storage
    impl = storage.get("current_impl")
    if envelope["method"] in ("GET", "HEAD"):
        # Query path: read from the implementation actor's storage directly
        # (requires the router to share storage or proxy via convention)
        return storage.get("cached_response/" + envelope["path"])
    else:
        # Command path: forward to the implementation actor
        ctx.send_message(impl, "http.request", envelope)
        return {"status": 202, "body": "forwarded"}

@actor.handler("set_implementation")
def set_impl(ctx, args):
    assert ctx.sender == storage.get("owner")
    storage.set("current_impl", args["address"])

Not mandated: This pattern is a recommendation, not a protocol requirement. Simple actors that do not expect to change can bind names directly. The Route Registry’s set_actor method (§7.7) remains the protocol-level migration mechanism for all actors.

​

8. Request Execution

​

8.1 Canonical HTTP Request Envelope

HttpRequestEnvelope {
  method:       string,           // HTTP method (uppercase): GET, POST, etc.
  path:         string,           // URL path (no query string, no fragment)
  query:        map<string, array<string>>, // parsed query parameters (repeated keys → array)
  headers:      map<string, array<string>>, // HTTP headers (lowercase keys; repeated headers → array)
  body:         bytes | null,     // request body (POST/PUT/PATCH only)
  host:         string,           // full Host header (for subdomain routing)
  request_id:   string,           // unique request ID (UUID v4, gateway-generated)
}

​

8.2 Canonical HTTP Response Envelope

HttpResponseEnvelope {
  status:       u16,              // HTTP status code (100-599)
  headers:      map<string, array<string>>, // response headers (repeated headers → array)
  body:         bytes | null,     // response body
}

​

8.3 Query Path (Read-Only, No Consensus)

1. Gateway calls queryActor(actor_address, [], "http.request", envelope) against its local node. (See Milestone 2 §5.2 for the canonical queryActor signature. This CIP passes "http.request" as the selector argument and the serialized HttpRequestEnvelope as the payload. If the Milestone 2 signature evolves, Gateways MUST track that evolution.)
2. The PVM executes the actor’s http.request selector with the request envelope as input.
3. Execution is pure: the handler may read from storage (get_storage) but any side-effecting syscall traps immediately with ERR_QUERY_NO_SIDE_EFFECTS (see §8.3.1 for the exhaustive permitted/trapped syscall tables). Side effects are not silently discarded — the handler cannot attempt them.
4. The handler returns an HttpResponseEnvelope.
5. Gateway translates the envelope to an HTTP response and returns it to the client.

​

8.3.1 Query-Path Execution Contract (Normative)

Exhaustiveness: Any syscall not listed in the “Permitted” table above MUST be trapped. New syscalls added to the PVM in future protocol versions default to trapped on the query path unless a future CIP explicitly adds them to the permitted list.

• The Gateway MUST enforce the actor’s max_query_cycles parameter (from the ingress.http entitlement).
• Cycle counting uses the same PVM metering as CIP-3 transactional execution.
• If the handler exceeds max_query_cycles, the PVM MUST abort execution with ERR_QUERY_CYCLE_LIMIT.
• The Gateway MUST NOT charge the actor — query-path execution has no fee. The Gateway absorbs the compute cost.

• On success: the handler MUST return a serialized HttpResponseEnvelope (§8.2). If the return value does not deserialize to a valid HttpResponseEnvelope, the Gateway MUST return HTTP 502 Bad Gateway.
• On trap (ERR_QUERY_NO_SIDE_EFFECTS): the Gateway MUST return HTTP 500 Internal Server Error with X-Cowboy-Error: QUERY_SIDE_EFFECT_TRAP.
• On cycle limit exceeded (ERR_QUERY_CYCLE_LIMIT): the Gateway MUST return HTTP 422 Unprocessable Content with X-Cowboy-Error: QUERY_CYCLE_LIMIT.
• On handler panic / unhandled exception: the Gateway MUST return HTTP 500 Internal Server Error with X-Cowboy-Error: HANDLER_PANIC.

X-Cowboy-Block: 1234567

​

8.4 Command Path (Consensus Required)

Transaction::ActorMessage {
  from:       GATEWAY_ADDRESS,          // Gateway's registered on-chain address
  to:         GATEWAY_REGISTRY_ADDRESS, // 0x0F
  message:    Message {
    method:   "dispatch",
    args:     DispatchArgs {
      target:   actor_address,
      envelope: HttpRequestEnvelope { ... }
    }
  },
  fee:        computed_fee,
  nonce:      gateway_nonce,
  signature:  gateway_signature,
}

1. Verifies that msg.sender is a registered, active Gateway (health > 0, stake ≥ MIN_GATEWAY_STAKE).
2. Verifies that the target actor has the ingress.http entitlement.
3. Forwards the HttpRequestEnvelope to the target actor as a Message { method: "http.request", args: envelope } with ctx.sender set to GATEWAY_REGISTRY_ADDRESS (0x0F).
4. If the sender is not a registered Gateway, the dispatch reverts with ERR_UNAUTHORIZED_GATEWAY.

Non-spoofable ingress: Unlike a plain ActorMessage, the system-mediated path prevents arbitrary on-chain accounts from sending http.request messages directly to actors. The GatewayRegistry acts as a trusted intermediary, analogous to how the Route Registry mediates name resolution. Direct ActorMessage with method: "http.request" from non-system senders will have ctx.sender != GATEWAY_REGISTRY_ADDRESS and actors MUST reject them.

HTTP/1.1 202 Accepted
X-Cowboy-Request-Id: abc-123
X-Cowboy-Block: 1234567

GET myagent.cowboy.network/_cowboy/requests/abc-123

• 200 OK with the stored HttpResponseEnvelope → the command has been executed.
• 202 Accepted → the transaction is still pending.
• 404 Not Found → no such request ID.
• 410 Gone → result expired and was cleaned up.

from cowboy_sdk import http

@http.command("/api/submit")
def handle_submit(ctx, req):
    # Process the command
    data = json.loads(req.body)
    storage.set("submissions/" + data["id"], data)

    # Return response — SDK stores it at _http/results/{request_id}
    return http.Response(201, body=json.dumps({"id": data["id"]}))

​

8.5 Actor Handler Convention

from cowboy_sdk import actor, storage
import json

GATEWAY_REGISTRY = "0x0F"

@actor.handler("http.request")
def handle_http(ctx, envelope):
    # On the command path, verify the message came through GatewayRegistry
    if ctx.sender is not None and ctx.sender != GATEWAY_REGISTRY:
        return {"status": 403, "body": "unauthorized: not dispatched via GatewayRegistry"}

    method = envelope["method"]
    path   = envelope["path"]
    host   = envelope["host"]

    # Query-path handler (GET)
    if path == "/api/profile" and method == "GET":
        profile = storage.get("profile")
        return {
            "status": 200,
            "headers": {"content-type": ["application/json"]},
            "body": json.dumps(profile)
        }

    # Command-path handler (POST) — may mutate state
    if path == "/api/profile" and method == "POST":
        data = json.loads(envelope["body"])
        storage.set("profile", data)
        return {
            "status": 200,
            "headers": {"content-type": ["application/json"]},
            "body": json.dumps({"updated": True})
        }

    return {"status": 404, "body": "not found"}

SDK default: The SDK (CIP-6) @http.handler decorator MUST include the ctx.sender verification by default. Actors using the raw @actor.handler("http.request") form (as shown above) MUST include the check manually.

1. On the command path: submit a CIP-2 task, return 202 Accepted, and store the result when the deferred callback fires.
2. On the query path: read pre-computed results from storage. The query handler cannot trigger off-chain compute.

@actor.handler("http.request")
def handle_http(ctx, envelope):
    if envelope["path"] == "/api/ask" and envelope["method"] == "POST":
        question = json.loads(envelope["body"])["question"]
        request_id = envelope["request_id"]

        # Submit async LLM task — result arrives via deferred callback
        ctx.submit_task(
            task_type="llm_inference",
            request={"prompt": question},
            callback="on_llm_result",
            callback_context={"request_id": request_id}
        )

        # Return 202 — client polls _cowboy/requests/{request_id}
        return {"status": 202, "body": json.dumps({"request_id": request_id})}

@actor.handler("on_llm_result")
def handle_llm_result(ctx, result):
    request_id = ctx.callback_context["request_id"]
    storage.set("_http/results/" + request_id, json.dumps({
        "status": 200,
        "headers": {"content-type": ["application/json"]},
        "body": json.dumps({"answer": result["output"]})
    }))

​

8.6 Reserved Paths (/_cowboy/*)

​

8.7 Subdomain Routing Limitations

​

9. Gateway Specification

​

9.1 Gateway as a Distinct Ingress Role

• Participate in DNS resolution for *.cowboy.network (authoritative DNS or integration with external DNS).
• Terminate TLS (including certificate management via ACME).
• Maintain a full or pruned copy of committed state (to execute query-path requests locally).
• Route HTTP requests: resolve names via the Route Registry, dispatch to 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

GatewayProfile {
  address:          Address,
  stake_amount:     u256,           // CBY staked
  endpoint:         string,         // public endpoint (IP or hostname)
  http_port:        u16,            // port for HTTPS traffic
  last_heartbeat:   BlockHeight,
  health:           u16,            // decays per block, reset on heartbeat
  registered_at:    BlockHeight,
}

• Register: Gateway stakes MIN_GATEWAY_STAKE CBY and calls register_gateway(endpoint, http_port).
• Heartbeat: 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.
• Removal: If health reaches 0, the Gateway is removed from the active list.
• Unstake: A Gateway may unstake after GATEWAY_UNSTAKE_DELAY blocks, provided it is no longer in the active list.

​

9.3 Gateway Selection

• Anycast: All Gateways advertise the same IP prefix via BGP. Network routing selects the nearest Gateway.
• Geo-DNS (alternative): The authoritative DNS server returns Gateway IPs based on the client’s resolver location.

​

9.4 Gateway Incentives

gateway_pool_share = registration_fee * GATEWAY_POOL_BPS / 10_000

​

9.5 Rate Limiting

​

9.6 Gateway Authentication

# On the command path, ctx.sender is always the GatewayRegistry system actor
assert ctx.sender == GATEWAY_REGISTRY_ADDRESS  # 0x0F

​

10. Protocol Constants

// Route Registry
ROUTE_REGISTRY_ADDRESS          = 0x0E
GATEWAY_REGISTRY_ADDRESS        = 0x0F
MIN_NAME_LENGTH                 = 3
MAX_NAME_LENGTH                 = 64
NAME_GRACE_PERIOD               = 2_592_000        // ~30 days at 1 block/sec
NAME_AUCTION_DURATION           = 604_800           // ~7 days
BLOCKS_PER_YEAR                 = 31_536_000        // ~365.25 days at 1 block/sec
REGISTRY_PROTOCOL_FEE_BPS       = 1_000             // 10%
GATEWAY_POOL_BPS                = 2_000             // 20% of registration fees to gateway pool

// Gateway
MIN_GATEWAY_STAKE               = <governance-set>
MAX_GATEWAY_HEALTH              = 3_600             // blocks (~1 hour at 1 block/sec)
GATEWAY_UNSTAKE_DELAY           = 604_800           // ~7 days
MAX_REQUESTS_PER_SECOND         = 100               // per actor per gateway
MAX_CONCURRENT_CONNECTIONS      = 1_000             // per actor per gateway

// Command path
RESULT_TTL_BLOCKS               = 3_600             // ~1 hour; actors may override

// Protocol-wide ingress limits (ceilings — actors may set lower)
PROTOCOL_MAX_REQUEST_BYTES      = 10_485_760        // 10 MiB
PROTOCOL_MAX_RESPONSE_BYTES     = 10_485_760        // 10 MiB
PROTOCOL_MAX_QUERY_CYCLES       = 100_000_000       // 100M cycles

​

11. Rationale

​

11.1 Why Subdomains of cowboy.network

• Work today with existing DNS infrastructure and all browsers/resolvers.
• Require no client-side changes.
• Can coexist with a future TLD if one is acquired.
• Follow D3’s lesson: DNS compliance first, sovereignty later.

​

11.2 Why Query/Command Split

​

11.3 Why queryActor (Not “Run the Normal Handler”)

• The RPC shape is already defined and supported by existing node infrastructure.
• The PVM can enforce side-effect restrictions at the syscall gate per the CIP-14 execution contract (§8.3.1).
• No new execution mode is needed — we reuse existing infrastructure with CIP-14-defined semantics.
• Actors using the same handler for query and command paths get automatic enforcement: side-effecting calls trap immediately on the query path, not silently succeed-then-discard.

​

11.4 Why Gateways Are a Separate Role

​

11.5 Why ingress.http (Not a Rust Enum)

• It fits the existing EntitlementGrant schema and CDDL serialization.
• Parameters (allowlist_methods, max_query_cycles, etc.) use established parameter types.
• It can be extended with additional params in future protocol versions without changing the data model.
• Scheduler matching and enforcement follow the same rules as all other entitlements.

​

11.6 Why Defer CIP-9 Public Assets, CIP-7 Streams, x402, Custom Domains

• CIP-9 public assets require Gateway-side route manifests and static serving logic on top of the PUBLIC_READ volume mode already specified in CIP-9 §7.6.
• CIP-7 stream bridging is specified by CIP-17 and defines SSE/WebSocket delivery, Gateway-local paid-stream sessions, and wrapped epoch-key retrieval for local client decryption.
• x402 payment requires payment verification, serving budget accounting, and integration with an external protocol.
• Custom domains require TXT record challenges, ACME certificate management, and periodic reverification.

​

12. Security Considerations

​

12.1 Query Path Isolation

• Modify state: Side-effecting syscalls trap with ERR_QUERY_NO_SIDE_EFFECTS.
• Affect other actors: Execution is sandboxed per CIP-3 PVM guarantees.
• Consume unbounded resources: max_query_cycles is enforced per-request.
• Exfiltrate data via side channels: The PVM is deterministic (no network, no timing, fixed hash seed).

​

12.2 Gateway Misbehavior

• Stale state detection: X-Cowboy-Block response header and X-Cowboy-Min-Block request header allow clients to detect and reject stale responses.
• Response verification: 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).
• Stake slashing: Gateways that are provably misbehaving (e.g., signed a command-path transaction but did not submit it) are slashable.

​

12.3 Name Squatting

• 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

• Rate limiting: Gateways enforce per-actor request limits (§9.5).
• Fee markets: High load increases the basefee (CIP-3 EIP-1559 mechanism), making spam progressively more expensive.
• Future: x402 pricing: A follow-on CIP can add per-request payment requirements for command-path endpoints.

​

12.5 Ingress Authenticity

​

12.6 Cross-Gateway Rate Limit Bypass

• 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

​

13. Future Work

​

14. Backwards Compatibility

• ingress.http is a new entry in the normative entitlement registry. Existing actors and entitlements are unaffected.
• The Route Registry is a new system actor at a previously unused reserved address (0x0E).
• The Gateway Registry is a new system actor at a previously unused reserved address (0x0F). Its dispatch() method provides system-mediated ingress — a new capability that does not affect existing actor messaging.
• The queryActor RPC is an existing primitive (Milestone 2 §5.2). This CIP standardizes its use for HTTP query-path execution and provides a full normative execution contract (§8.3.1) but does not change its underlying semantics.
• Actors without ingress.http are unaffected — they cannot register names and will not receive HTTP traffic.
• The Gateway role is additive. Existing Runners, Validators, and Relay Nodes are unaffected.

​

Part II — v2 Revision (canonical; verbatim from former cip-14-aligned.md)

​

0. What this document is

​

1. Preconditions

​

2. Scope

• The “query path” is implemented via the new read_handler RPC + PVM read-only mode defined in Part III of this document §5, not via a hypothetical queryActor.
• Command-path results are stored in RECEIPT_REGISTRY=0x10, not in actor KV with per-request cleanup timers.
• Static-asset hosting is deferred to CIP-15-aligned (separate ingress.static entitlement).

​

3. The ingress.http entitlement

​

3.1 Registry entry

• quota: false (the manifest has no on-chain quota accumulation; max_* params are per-request limits).
• All four params are optional; absence implies the protocol defaults below.
• An additional optional param receipt_ttl_blocks lets the actor override the default receipt TTL (§8).

​

3.2 Defaults and ceilings

​

3.3 Enforcement points

• Deploy-time (manifest_validate.rs): param shape and bounds check.
• Gateway: rejects requests to actors lacking ingress.http; enforces request/response size; sets max_cycles on read-handler RPC calls and on command-path system instructions.

​

4. Route Registry (0x0E)

​

4.1 Record

RouteRegistration {
  name:             string,                 // canonical lowercase, ≤ 64 bytes
  fqdn:             string,                 // computed: name || ".cowboy.network"
  actor_address:    Address,
  owner:            Address,
  registered_at:    BlockHeight,
  expires_at:       BlockHeight,
  subdomain_policy: u8,                     // 0 = OWNER_ONLY (default), 1 = ACTOR_MANAGED, 2 = OPEN
}

​

4.2 Naming hierarchy

​

4.3 Naming constraints

​

4.4 Registration

​

4.5 Economics (uses existing settlement plumbing)

RegistrySettlementConfig {
  burn_percent:     7000,   // 70%
  treasury_percent: 1500,   // 15%
  gateway_percent:  1500,   // 15%  → flows into the gateway pool (§7.4)
}

​

4.6 Renewal, expiry, auction

​

4.7 Route Registry API

​

4.8 Two upgrade paths (clarification)

1. Router proxy (original §7.8) — never call set_actor; route through a stable proxy whose code never changes.
2. upgrade_self syscall — node/execution/src/pvm_host.rs:1765, gated by sys.upgrade entitlement. Replaces the actor’s code_hash in place; storage and address persist.

​

5. Read-only handler execution (replaces “query path”)

1. Resolve fqdn → actor_address via STATE_GET against ROUTE_REGISTRY.
2. Call POST /actor/{address}/read_handler with selector "http.request" and the serialized HttpRequestEnvelope as payload. Pass the actor’s max_query_cycles as max_cycles.
3. Node executes via PVM read-only mode. 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 Part III of this document §5.3.
4. Response: deserialize as HttpResponseEnvelope. If invalid, Gateway returns 502 Bad Gateway with X-Cowboy-Error: INVALID_RESPONSE.
5. Set X-Cowboy-Block: <block_height> on the outgoing response.

​

5.1 Error mapping

​

5.2 Consistency

​

5.3 Determinism (corrected)

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

​

6. Command path (system-mediated)

​

6.1 IngressDispatch system instruction (opcode 65)

IngressDispatch {
  target:        Address,
  envelope:      HttpRequestEnvelope,
  request_id:    bytes16,
}

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 target.http_request with ctx.sender = GATEWAY_REGISTRY=0x0F.
5. After the actor handler returns (or traps), write the result to RECEIPT_REGISTRY (§8).

​

6.2 Sender authenticity (revises original §8.5)

Note (withdrawal of an earlier proposal). An earlier CIP-14 v2 draft proposed making "http.request" a PVM-router-reserved selector — i.e., the message router would reject any non-system send_message / call_actor with that selector at routing time, returning ERR_RESERVED_SELECTOR. That proposal is withdrawn because it broke a legitimate pattern: an intermediary router actor that receives http.request from the Gateway and wants to forward to a backend implementation would be unable to use the same selector for the forwarded call. The SDK-enforced sender check at the receiving actor is sufficient for authenticity: ctx.sender is set by the protocol message router from the calling tx’s signer (it cannot be forged by the caller’s own code), so a check inside the receiving handler IS the protocol guarantee. This matches the established pattern used by other system-mediated handlers (e.g., result-verifier callbacks). Custom-PVM-bytecode actors that omit the check are accepting the risk on their own behalf, the same as any other handler-side validation.

​

6.3 Gas payment (separates stake from fees)

​

6.4 Async response

HTTP/1.1 202 Accepted
X-Cowboy-Request-Id: <uuid>
X-Cowboy-Block: <height>

​

7. Gateway role

​

7.1 Distinct ingress role

​

7.2 GatewayRegistry (0x0F)

GatewayProfile {
  address:           Address,                     // operating account (also pays gas)
  stake_amount:      u128,
  endpoint:          string,
  http_port:         u16,
  last_heartbeat:    BlockHeight,
  health:            u16,                          // decays per block, reset on heartbeat
  registered_at:     BlockHeight,
}

​

7.3 Selection

​

7.4 Incentives (uses existing settlement plumbing)

GatewayPoolConfig {
  weight_stake:   u32,     // basis points; default 5000
  weight_uptime:  u32,     // basis points; default 5000
}

gateway_share = pool * (weight_stake * stake + weight_uptime * uptime_blocks) / Σ(...)

​

7.5 Rate limits, response envelope, reserved paths

​

8. Receipt Registry (0x10)

​

8.1 Record

Receipt {
  request_id:    bytes16,                   // UUID v4 from envelope
  target_actor:  Address,
  gateway:       Address,                   // the dispatching Gateway operating account
  status:        u8,                         // 0 = PENDING, 1 = COMPLETED, 2 = FAILED
  envelope:      HttpResponseEnvelope?,     // populated on completion
  created_at:    BlockHeight,
  expires_at:    BlockHeight,                // = created_at + receipt_ttl_blocks
  private:       bool,                       // see §8.4
}

​

8.2 Storage and lifecycle

• Written by the system instruction dispatcher, not by actor code. After IngressDispatch invokes the actor handler:
  • Successful return → complete_receipt(request_id, envelope) opcode (allocated 66 per CIP-13 v2 §1; sender = current handler context, verified to equal target_actor).
  • Handler panic / cycle limit → dispatcher writes status = FAILED directly with no envelope.
• TTL: receipt_ttl_blocks is read from the actor’s ingress.http entitlement (default RECEIPT_TTL_BLOCKS = 3_600, max RECEIPT_TTL_MAX = 86_400).
• Pruning: a single registry-wide pruning loop scans expires_at per block. Per-actor timer budget is not consumed.
• Fee: receipt write is one extra cell (charged via the dual-cell meter from CIP-3) folded into the command-path tx fee. No separate billing event.

​

8.3 Read API

​

8.4 Privacy

​

8.5 Async LLM example (corrected for new receipt model)

from cowboy_sdk import actor, http, jobs

@http.handler("POST", "/api/ask")
def handle_ask(ctx, envelope):
    question = json.loads(envelope.body)["question"]

    ctx.submit_job(
        job_type    = "llm",
        params      = {"prompt": question, "max_tokens": 256},
        callback    = "_on_llm",
        context     = envelope.request_id,        # opaque to scheduler
    )

    # 202 Accepted + Receipt PENDING; client polls /_cowboy/requests/<id>
    return http.Response(202, body='{"status": "pending"}')

@actor.handler("_on_llm")
def on_llm(ctx, result):
    request_id = ctx.callback_context
    ctx.complete_receipt(request_id, http.Response(
        200,
        headers={"content-type": ["application/json"]},
        body=json.dumps({"answer": result["output"]}),
    ))

​

9. Actor handler convention

from cowboy_sdk import http
import json

@http.handler(methods=["GET", "POST"])
def handle(ctx, envelope):
    if envelope.method == "GET" and envelope.path == "/api/profile":
        return http.Response(200,
            headers={"content-type": ["application/json"]},
            body=json.dumps(ctx.storage.get("profile") or {}))

    if envelope.method == "POST" and envelope.path == "/api/profile":
        ctx.storage.set("profile", json.loads(envelope.body))
        return http.Response(200, body='{"updated": true}')

    return http.Response(404, body='not found')

​

10. Constants

ROUTE_REGISTRY_ADDRESS              = 0x0E
GATEWAY_REGISTRY_ADDRESS            = 0x0F
RECEIPT_REGISTRY_ADDRESS            = 0x10

MIN_NAME_LENGTH                     = 3
MAX_NAME_LENGTH                     = 64
NAME_GRACE_PERIOD                   = 2_592_000           // ~30 days
NAME_AUCTION_DURATION               = 604_800             // ~7 days
BLOCKS_PER_YEAR                     = 31_536_000          // ~1 year

MIN_GATEWAY_STAKE                   = <governance-set>
MAX_GATEWAY_HEALTH                  = 3_600               // ~1 hour
GATEWAY_UNSTAKE_DELAY               = 604_800             // ~7 days
MAX_REQUESTS_PER_SECOND             = 100                 // per actor per Gateway
MAX_CONCURRENT_CONNECTIONS          = 1_000               // per actor per Gateway

RECEIPT_TTL_BLOCKS                  = 3_600               // ~1 hour default
RECEIPT_TTL_MAX                     = 86_400              // ~1 day ceiling

PROTOCOL_MAX_REQUEST_BYTES          = 10_485_760          // 10 MiB
PROTOCOL_MAX_RESPONSE_BYTES         = 10_485_760          // 10 MiB
PROTOCOL_MAX_QUERY_CYCLES           = 100_000_000         // 100M cycles

​

11. Security delta vs. original

​

12. Backwards compatibility

• New entries in REGISTRY (Part III of this document §2.1).
• New system actors at unused addresses 0x0E / 0x0F / 0x10.
• New SystemInstruction::IngressDispatch and complete_receipt opcodes.
• New read_handler RPC + PVM read_only: bool mode flag.
• New target_pool discriminant on UpdateSettlementConfig.

​

13. Future work (unchanged from original §13 except)

​

Part III — Cross-Cutting Conventions (verbatim from former alignment-conventions.md)

​

Alignment Conventions for CIP-14 / CIP-15 / CIP-16

​

1. System actor address allocation

​

2. Entitlement registry amendments (entitlement spec §9)

​

2.1 ingress.http (CIP-14)

RegistryEntry {
    id: "ingress.http",
    inheritable: false,
    attested: false,
    quota: false,
    params: &[
        ParamSchema { name: "allowlist_methods",     param_type: ParamType::StrArray, required: false },
        ParamSchema { name: "max_request_bytes",     param_type: ParamType::Uint,     required: false },
        ParamSchema { name: "max_response_bytes",    param_type: ParamType::Uint,     required: false },
        ParamSchema { name: "max_query_cycles",      param_type: ParamType::Uint,     required: false },
        ParamSchema { name: "receipt_ttl_blocks",    param_type: ParamType::Uint,     required: false },
    ],
},

​

2.2 ingress.static (CIP-15)

RegistryEntry {
    id: "ingress.static",
    inheritable: false,
    attested: false,
    quota: false,
    params: &[
        ParamSchema { name: "static_volume_names",       param_type: ParamType::StrArray, required: true  },
        ParamSchema { name: "max_static_response_bytes", param_type: ParamType::Uint,     required: false },
        ParamSchema { name: "max_cache_bytes_total",     param_type: ParamType::Uint,     required: false },
    ],
},

​

2.3 dns.attach_external (CIP-16)

RegistryEntry {
    id: "dns.attach_external",
    inheritable: false,
    attested: false,
    quota: false,
    params: &[
        ParamSchema { name: "max_bindings", param_type: ParamType::Uint, required: false },
    ],
},

​

2.4 Test update

​

3. ParamValue limits (binding for spec authors)

• a scalar Uint (≤ u64)
• a single Str (≤ 256 bytes)
• a StrArray (≤ 64 entries × 256 bytes)
• an AddressArray (≤ 64 addresses)

• nested objects → flatten to multiple entitlements, or two parallel StrArrays pairing by index
• booleans → use Uint with 0/1
• arrays of structs → use parallel arrays
• maps → store JSON in a Str (deploy-time validation cannot recurse into the JSON)

​

4. System-mediated handler invocation pattern

1. Define a new SystemInstruction opcode (e.g. IngressDispatch, ExternalDomainCallback) carrying (target_actor, selector, payload).
2. The dispatch handler enforces a sender allowlist: only the named system actor address may emit the opcode.
3. The dispatcher synthesises an internal ActorMessage whose ctx.sender is set to the system actor address. Ordinary send_message / call_actor from arbitrary accounts cannot reproduce this ctx.sender value because the message router populates ctx.sender from the calling tx’s signer (it cannot be forged by the caller’s own code).
4. Receiving actors MUST verify ctx.sender against the canonical sender for that selector (e.g. ctx.sender == GATEWAY_REGISTRY=0x0F for "http.request"; ctx.sender == RESULT_VERIFIER=0x03 for "_dns.callback"). The SDK (CIP-6) decorator-based handlers MUST include this check by default; raw handlers MUST include it manually.

Note (revision). An earlier draft of this section described a 4th step in which the PVM message router would additionally reserve the corresponding selectors (rejecting any non-system sender with ERR_RESERVED_SELECTOR at routing time). That proposal was withdrawn (see CIP-14 v2 Part II §6.2 Note) because it broke legitimate router-actor patterns where an intermediary needs to forward http.request to a backend implementation. The handler-side ctx.sender check above is sufficient — ctx.sender is protocol-set, not caller-set.

​

5. Read-only handler execution (replaces “queryActor”)

​

5.1 RPC

POST /actor/{address}/read_handler
{
  "selector":   string,        // method name, e.g. "http.request"
  "payload":    base64,        // serialized arguments
  "max_cycles": u64?,          // overrides actor entitlement up to PROTOCOL_MAX_QUERY_CYCLES
  "min_block":  u64?           // optional consistency floor
}
→ {
  "block_height": u64,
  "result":       base64,      // handler return bytes
  "cycles_used":  u64
}

​

5.2 PVM mode

• Returns from state_get / state_scan_prefix as today.
• Traps on every mutating syscall — see §5.3 for the exhaustive table.
• Returns Address::ZERO for caller and None for ctx.sender (no transaction context).

​

5.3 Permitted vs. trapped syscalls (definitive table)

​

6. Settlement / fee distribution reuse

• system:registry_settlement_config — splits for name registration / renewal fees (CIP-14-aligned §4.5, CIP-16-aligned §4)
• system:gateway_pool_config — splits for the Gateway serving fee pool (CIP-14-aligned §7.4)

​

7. CIP-9 amendments (precondition for CIP-15-aligned)

Errata note. An earlier revision of this section (v1) listed AMEND 9-A through 9-E claiming that StorageCommitment, commit_manifest, the volume_id = keccak256(...) formula, and Visibility::Public were missing. They are NOT missing — they are all in CIP-9 today. The corrected, smaller delta list is below; details are in cip-9-runner-storage-v2.md (Part II).

• StorageCommitment with volume_id, owner, visibility, manifest_root, status (CIP-9 §11.1).
• commit_manifest(cap_token, manifest_root) system instruction (CIP-9 §12.2).
• volume_id = keccak256(account_address || volume_name) (CIP-9 §11.1).
• Visibility::Public model for unauthenticated reads via shard metadata (CIP-9 §7.6.3) — note: original CIP-15 used PUBLIC_READ; the canonical CIP-9 / CBFS name is Visibility::Public.
• Volume status state machine ACTIVE → GRACE_PERIOD → DELETED → GARBAGE_COLLECTING (CIP-9 §13).

• AMEND 9-G — GET_MANIFEST Relay Node RPC (cip-9-runner-storage-v2.md (Part II) §2). Direct manifest fetch in one round trip without per-shard reconstruction; required for low-latency Gateway operation against Visibility::Public volumes.
• AMEND 9-H — ManifestCommitted chain event (cip-9-runner-storage-v2.md (Part II) §4). Powers Gateway eager cache invalidation; polling remains as a floor.
• Pin canonical manifest serialization to cbfs/manifest/src/merkle.rs (cip-9-runner-storage-v2.md (Part II) §3). Reuses existing CBFS bincode + RFC-6962-style Merkle (avoids the Bitcoin-style duplicate-last-leaf shape).
• Gateway serving authority mapped from existing CIP-9 statuses (cip-9-runner-storage-v2.md (Part II) §5). Uses existing ACTIVE / GRACE_PERIOD / DELETED / GARBAGE_COLLECTING rather than introducing a new DELINQUENT status.

​

8. CIP-2 amendments (precondition for CIP-16-aligned)

• AMEND 2-A — Add VerifierCheck::DnsTxtRecordMatch { fqdn: String, expected_value: String, min_resolvers: u32 }. Verifier runners resolve fqdn via min_resolvers independent recursive resolvers (operator-configured public list) and report match / mismatch.
• AMEND 2-B — Add VerifierCheck::DnsCnameMatch { fqdn: String, expected_target: String, min_resolvers: u32 }. Used to check the canonical-edge CNAME.
• AMEND 2-C — JobType::Custom { executor_hash, params } already exists (runner/src/types.rs:146-149). CIP-16-aligned uses it for the verification job; executor_hash references a built-in DNS-verification executor whose hash is governance-pinned (DNS_VERIFIER_EXECUTOR_HASH).

​

9. CIP-5 amendments

​

10. Receipt model (replaces SDK-conventional _http/results/{request_id})

• Receipts are written by the IngressDispatch system instruction post-handler-return, not by actor code. Actors do not consume their own KV or timer budget for receipt management.
• A single registry-wide pruning loop expires receipts via TTL, replacing per-request timers. One timer slot total, not one per pending request.

​

11. Whitepaper alignment