CIP-14: DNS-Addressable Actors

​

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, // 0x0012
  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 (0x0012).
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 = "0x0012"

@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  # 0x0012

​

10. Protocol Constants

// Route Registry
ROUTE_REGISTRY_ADDRESS          = 0x0011
GATEWAY_REGISTRY_ADDRESS        = 0x0012
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 (0x0011).
• The Gateway Registry is a new system actor at a previously unused reserved address (0x0012). 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.