CIP-6: In-PVM Actor SDK (cowboy_sdk)

​

1. Abstract

• Deterministic by construction. Non-deterministic Python primitives (wall-clock time, hardware FPU, unseeded randomness, filesystem, network, set(), pickle) are trapped or replaced by SDK equivalents.
• Two-dimensional metering. Every syscall is metered in Cycles (compute) or Cells (state IO) per CIP-3.
• Handler-mode purity. Every actor method declares whether it may issue async side effects (@pure vs @deferred); the runtime enforces this distinction.
• Deny-by-default access control. Handlers are unreachable from external callers unless explicitly decorated with @public or @callable_by(...).
• Continuations compiled at decoration time. async methods decorated with @runner.continuation or @actor.continuation are lowered to a finite-state machine at class-load time, not dynamically at runtime.
• Entitlements gate all external-effect syscalls. Entitlements are declared in a deploy-time manifest and enforced at the Host API boundary.

​

2. SDK Layers

​

2.1 cowboy_sdk — In-PVM Actor SDK (this CIP)

​

2.2 cowboy — Standalone Developer SDK

• Actor authoring helpers — @actor, @public, @callable_by, @pure, @deferred, @init_handler, OWNER, SELF, local runtime stubs for unit testing
• Source generation — actor_instance.to_source() emits deployable Python source that imports from cowboy_sdk
• Chain client — CowboyClient, AsyncCowboyClient for RPC queries and transactions
• Deployment — client.deploy_actor(code, salt, init_handler, ...), client.execute_actor(...)
• Wallets and signing — Wallet, generate_private_key, sign_payload
• Jobs — JobSpec, client.submit_job()
• CBSS — secrets management helpers

​

2.3 Handler Signature Difference

​

2.4 Compatibility Matrix

​

3. Motivation

​

4. Definitions

• Actor: A Python class whose public methods are invocable handlers. Identified by a 20-byte address.
• Handler: A public method of an Actor. Accepts the payload the host delivers; returns bytes, or a value its declared codec (raw / cbor / json, §9.5) can encode, or raises.
• Handler mode: A per-method property, either pure (default) or deferred. Pure handlers MUST NOT issue async side effects.
• Permission: A per-method access control tag (@public, @callable_by, or absent). Absent means deny-by-default from external callers.
• Syscall: A call from the PVM into the Host API (implemented in Rust) to perform a privileged operation. The SDK wraps syscalls.
• Continuation: A compiled FSM representation of an async def handler that awaits a runner job or an async actor call. State survives block boundaries.
• Manifest: A JSON document declaring the entitlements a deployed actor requests. Attached to the deploy transaction.
• PVM: The Python Virtual Machine executing actor bytecode under determinism constraints (CIP-3 §4).

​

5. SDK Module Layout

​

6. Actor Model

​

6.1 Declaration

from cowboy_sdk import actor, public, callable_by, pure, deferred, OWNER, runtime

@actor
class Counter:
    def init(self, payload):
        runtime.assume_ownership_if_unowned()
        self.storage["count"] = 0

    @pure
    @public(decode="cbor")
    def get_count(self, payload) -> int:
        return self.storage.get("count", 0)

    @deferred
    @public(decode="cbor")
    def increment(self, payload) -> int:
        self.storage["count"] = (self.storage.get("count") or 0) + 1
        return self.storage["count"]

    @callable_by(OWNER, decode="raw")
    def reset(self, payload) -> None:
        self.storage["count"] = 0

1. Injects self.address (read-only Address, the actor’s own 20-byte address). cowboy_sdk only — the standalone cowboy SDK does not inject self.address.
2. Injects self.storage (a dict-like proxy over actor private state — see §6.5).
3. Wraps every public method in permission enforcement (deny-by-default; see §7) and handler-mode enforcement (see §8).
4. Scans for @runner.continuation and @actor.continuation methods and installs the corresponding __resume callbacks. cowboy_sdk only.
5. Registers the class as the handler entry point for the deployed actor.

​

6.2 Address Derivation

address = keccak256(0xff || deployer_address || keccak256(salt) || code_hash)[12:]

• deployer_address: 20 bytes, the sender of the deploy transaction.
• salt: caller-supplied bytes, keccak256-reduced to 32 bytes for CREATE2 — derive_actor_address hashes the salt unconditionally; it is not zero-padded (keccak256(salt) ≠ zero_pad(salt) for any non-trivial salt).
• code_hash: 32-byte hash of the actor source. The CLI’s cowboy actor address is authoritative for the exact hash algorithm used.
• Output: 20-byte Address.

​

6.3 Deployment

• By default the CLI calls "init" atomically in the same transaction as the deploy, with sender set to the deployer’s address.
• Pass --no-init to deploy without an init call (only safe for actors that do not rely on init for ownership bootstrapping).
• Pass --init-handler <name> to name a different handler.
• Pass --init-payload <json-string | @file> to supply a custom payload.

​

6.4 Message Handler Dispatch

1. The PVM loads the actor class and state.
2. method_name is looked up; unknown methods raise AttributeError — converted to ActorCallError.
3. The handler runs under its declared permission (§7) and handler mode (§8).
4. Return value is encoded with the handler’s declared codec — passed through unchanged under raw, the default (§9.5) — and returned to the caller (for call()) or discarded (for send()).

​

6.5 Storage

self.storage[key] = value        # CBOR-encode value, write
value = self.storage[key]        # read, CBOR-decode; None if absent
del self.storage[key]            # delete
key in self.storage              # membership test
value = self.storage.get(key, default)

self.storage.set_raw(key, data)  # data: bytes, stored verbatim
data = self.storage.get_raw(key) # returns bytes | None

balance = self.storage.guard("balance")  # returns GuardedValue; see §10.3

​

7. Handler Permissions

​

7.1 Decorators

from cowboy_sdk import actor, public, callable_by, OWNER, SELF, runtime

@actor
class Vault:
    def init(self, payload):
        runtime.assume_ownership_if_unowned()

    @public(decode="cbor")
    def balance_of(self, payload):
        return self._compute_balance()        # calls underscore helper — no perm check

    @callable_by(OWNER, decode="raw")
    def withdraw(self, payload):
        ...

    @callable_by(b"\xaa" * 20, b"\xbb" * 20, decode="raw")
    def admin_pause(self, payload):
        ...

    def _compute_balance(self):
        ...    # underscore prefix — not wrapped, no permission check at all

​

7.2 Internal Helpers

​

7.3 @callable_by(SELF) Semantics

​

7.4 init Bootstrap Window

​

8. Handler Modes

from cowboy_sdk import actor, public, deferred, send

@actor
class Example:
    @public(decode="cbor")
    def balance_of(self, payload) -> int:          # @pure by default
        addr = payload.get("addr") if isinstance(payload, dict) else payload
        return self.storage.get(f"bal:{addr}", 0)

    @deferred
    @public(decode="cbor")
    def transfer(self, payload) -> None:
        to = payload["to"]
        amount = payload["amount"]
        self.storage[f"bal:sender"] -= amount
        self.storage[f"bal:{to}"] = self.storage.get(f"bal:{to}", 0) + amount
        send(to, {"kind": "received", "amount": amount})   # async side effect

​

8.1 Read-Only Execution Flag

• Every state-mutating host syscall MUST return HostError::Forbidden instead of recording the mutation. The mutating syscalls — exhaustive list — are: state_set, state_delete, emit_event, send_message, schedule_timer and cancel_timer (all variants), submit_job, create_deferred_tx, upgrade_self, every token_* mutation, fork (CIP-27), and any future host call that writes durable state.
• The flag MUST persist across call() sub-calls: a read-only top-level call cannot launder a mutation through a callee. The callee inherits read_only = true for the duration of the cross-call.
• Read syscalls (state_get, state_scan_prefix, etc.) and pure computation are unaffected.
• send_message is on the deny list because, although fire-and-forget, it is a durable effect (CIP-1).

• @pure + read_only=false: ordinary external view-style call. Async effects would already be rejected by @pure enforcement.
• @pure + read_only=true: typical RPC query path. Belt-and-braces.
• @deferred + read_only=false: ordinary mutating call.
• @deferred + read_only=true: the handler could issue async effects, but the runtime is rejecting them at the host boundary. This is the case other CIPs (e.g. CIP-27 §3.1) need to name when they require their syscalls to be inert under read-only.

​

9. Call Primitives

​

9.1 call() — Synchronous Cross-Actor Call

from cowboy_sdk import call

result = call(
    target="0x1111...",
    method="get_balance",
    args={"user": "0xABCD..."},
    cycles_limit=5000,
)

• target: 20-byte address, as Address, hex string, or raw bytes.
• method: UTF-8 handler name on the target.
• args: the arguments, encoded with the call’s codec — a dict of keyword arguments or a list of positional arguments under an encoded codec (cbor / json), or bytes sent verbatim under raw.
• cycles_limit: explicit cycle budget for the callee. Defaults to 100_000 if omitted; passing it explicitly is recommended for precise metering.
• codec: the payload codec for both the arguments and the return — raw, cbor, or json, defaulting to cbor. It must match the decode= the target handler declares — see §9.5.

• Executes in the same transaction. Shared read-write set with the caller.
• Callee exceptions propagate — uncaught, they roll back the entire transaction.
• Call depth is capped at 32. On-chain, the host rejects an overflow as Forbidden (E1205) and call() surfaces it as ActorCallError, indistinguishable from a permission or re-entrancy reject. CallDepthExceeded is raised only when an in-process (local/checkpoint-mode) chain overflows Python’s recursion limit. Below the call-error shape activation height the legacy classification applies, under which an on-chain overflow does raise CallDepthExceeded.
• Return value is decoded with the call’s codec and returned to the caller.

from cowboy_sdk import ActorRef

oracle = ActorRef("0x4444...", cycles_limit=5000)
price = oracle.get_price("ETH")     # lowers to call("0x4444...", "get_price", ["ETH"])

blob = ActorRef("0x5555...", codec="raw")   # every call through this ref is raw

​

9.2 send() — Fire-and-Forget Message

from cowboy_sdk import send

send(
    target="0x3333...",
    payload={"event": "order_created", "order_id": "abc"},
)

• Enqueues a message for delivery at the start of the next block.
• No return value; send() returns immediately.
• Irrevocable: once a transaction commits, its sent messages are delivered even if later logic would want to cancel them.
• Allowed only from @deferred handlers.
• payload is encoded with the send’s codec — raw, cbor, or json, defaulting to cbor (§9.5). send(raw=True) is the original spelling of codec="raw" and stays equivalent to it; naming any other codec alongside raw=True raises ValueError rather than letting one silently win.

​

9.3 await runner.<op> — Runner Continuation

from cowboy_sdk import runner, capture

@runner.continuation
async def analyze(self, msg):
    ctx = capture()
    ctx.summary = await runner.llm(
        prompt=f"Summarize: {msg['text']}",
        max_tokens=200,
    )
    self.storage["last_summary"] = ctx.summary

​

9.3.1 runner.http response status and headers

{"status": 402, "headers": {"www-authenticate": ["Payment id=\"...\", method=\"tempo\", ..."]}, "data": {"challengeId": "..."}}

• The inner data is exactly what data is without the control header.
• headers holds only the requested headers that the response carried, keyed in lowercase. Each is an array of its values in the order the server sent them. A value is a string when its bytes are valid UTF-8, and {"base64": "..."} otherwise.
• The serialized headers object counts toward output_tokens and is capped at 16 KiB; a response over the cap fails the job.
• The control header is accepted only for jobs whose result is not compared across runners: at most one runner, or verification mode None or EconomicBond. Actor runner.http jobs use EconomicBond with one runner. Any other job fails before the request is sent, because headers such as Date differ between requests.
• A control header that names no header (empty, blanks or commas only) is ignored.
• RunnerResult.text does not change: extract_text follows the data key to the body.

from cowboy_sdk import runner, capture

@runner.continuation
async def price(self, msg):
    ctx = capture()
    ctx.url = msg["url"]
    reply = await runner.http(
        url=ctx.url,
        method="GET",
        headers={"X-Cowboy-Return-Headers": "www-authenticate"},
    )
    result = reply.data
    if result["status"] == 402:
        self.storage["challenge"] = result["headers"].get("www-authenticate", [])

​

9.4 await ActorRef.async_* — Actor Continuation

from cowboy_sdk import actor, ActorRef, capture

@actor
class Aggregator:
    @actor.continuation(timeout_blocks=100)
    async def collect(self, assets: list[str]) -> dict:
        ctx = capture()
        ctx.results = {}
        for asset in assets[:5]:
            ctx.results[asset] = await ActorRef("0x4444...").async_get_price(asset)
        return ctx.results

• Each await ActorRef.async_<method>(...) is lowered to send(target, {...}) plus a state save.
• The target’s handler is invoked in a future block; when it completes, it delivers a callback message that resumes the caller’s continuation.
• Requires both caller and callee to be @deferred.

​

9.5 Payload Codecs — decode= and codec=

@public(decode="cbor")
def quote(self, payload):                            # payload is a dict, not bytes
    return {"price": 42}                             # returned as Canonical CBOR

result = call(target, "quote", {"symbol": "ETH"})     # codec="cbor" by default

​

The strict JSON profile

• Sorted keys, no separator padding, ASCII-escaped. {"b": 1, "a": 2} serializes to {"a":2,"b":1}, and {"k": "café"} to {"k":"caf\u00e9"} — the bytes never depend on dict insertion order, and are always 7-bit.
• No non-finite numbers. NaN / Infinity / -Infinity are refused on encode, and on decode in both spellings: the bare tokens json.loads accepts by default, and a number literal that is valid RFC 8259 syntax but overflows to infinity (1e400).
• No surrogate code points, on encode or decode, paired or not. A supplementary character is a single code point, so it survives as a well-formed pair escape — "😀" encodes to "\ud83d\ude00" — and nothing legitimate is lost.
• UTF-8 only on decode, so a UTF-16/32 BOM cannot reinterpret the payload under an encoding this profile never emits.
• No byte-string type, and object keys are strings. A bytes payload is refused, and integer keys stringify — {1: "a"} round-trips as {"1": "a"}, where cbor returns {1: "a"}. Choose cbor when key fidelity or binary data matters.

​

10. Continuations

​

10.1 FSM Compilation

• <name>: the initial handler; starts the FSM, persists state 0, issues the first async effect, returns.
• <name>__resume: the resume handler; called by the runtime on callback delivery, loads state, advances the FSM, issues the next async effect (or returns final value).

​

10.2 capture() — Explicit Local State

ctx = capture()
ctx.first = await runner.llm("...")       # first-await state
ctx.second = await runner.http("...")     # second-await state
return ctx.first + ctx.second

​

10.3 Guards

@runner.continuation(guard_unchanged=["price", "config"])
async def act_on_price(self, msg):
    decision = await runner.llm(f"Given price {self.storage['price']}, ...")
    # On resume: if storage["price"] or storage["config"] was modified by any
    # intervening transaction, raise StateConflictError BEFORE running the body.
    ...

balance = self.storage.guard("balance")          # GuardedValue
result = await runner.llm("...")
new_balance = balance.value - 100                # raises StateConflictError if changed
self.storage["balance"] = new_balance

​

10.4 Bounded Loops

from cowboy_sdk import bounded_loop, capture

@runner.continuation
async def fan_out(self, items: list):
    ctx = capture()
    ctx.results = []

    @bounded_loop(max_iterations=10)
    async def run():
        for item in items[:10]:
            ctx.results.append(await runner.process(item))

    await run()

​

10.5 Sequential Await Limit

​

10.6 Continuation Persistence Format

• Authoring layer (compile-time, §10.1–10.5). The decorator rewrites an async def with await points into straight-line code (the FSM transform), and capture() / guards / bounded loops constrain what may cross a suspension. This is developer ergonomics — it shapes the source, not the persisted bytes.
• Persistence layer (runtime, this section). When a continuation suspends at an await, the runtime serializes the suspended interpreter state and commits it to actor storage; the resuming dispatch restores it. This is the format that is part of the consensus boundary.

Note. The SDK also ships continuation.save_cont record helpers (a small typed map of state / ctx / handler / timeout / guards). Those belong to the FSM execution mode, which production does not currently enable, and they exist in two not-yet-reconciled variants. The normative on-chain format is the checkpoint snapshot defined below. Reconciling the record helpers and the fsm-vs-checkpoint terminology is tracked in COW-2340.

​

11. Type System

​

11.1 Address

from cowboy_sdk import Address

a = Address.from_hex("0x7a3B6E...F92E")
b = Address(raw_bytes_20)
a.to_hex()       # checksummed (EIP-55)
a.to_bytes()     # 20-byte payload
Address.ZERO     # sentinel
Address.JOB_DISPATCHER   # 0x0000…0002

​

11.2 BlockHeight

​

11.3 SoftFloat, ordered_set

• SoftFloat is a software-floating-point type. Native Python float depends on the hardware FPU and is non-deterministic across platforms; authors MUST use SoftFloat instead. The SDK may alias SoftFloat = float when running under a PVM that enforces softfloat at the instruction layer; authors SHOULD still annotate with SoftFloat for clarity.
• ordered_set is a dict-backed set with deterministic insertion-order iteration. Python’s built-in set() is prohibited in actor code.

​

11.4 CowboyModel

• Deterministic serialization via to_cbor() and from_cbor(bytes).
• JSON Schema export via schema() (for use with Verify).
• Field validation on construction.
• Forbids set / frozenset fields (non-deterministic iteration).
• Forbids float fields (requires SoftFloat).

from cowboy_sdk import CowboyModel, SoftFloat

class Trade(CowboyModel):
    asset: str
    size: int
    price: SoftFloat

​

11.5 CBOR Codec

• Map keys sorted by length-first ordering (RFC 8949 §4.2.3): compare the encoded key bytes by length first, then bytewise (lexicographically) within equal lengths.
• No duplicate keys.
• Floats encoded as IEEE 754 double (when unavoidable).
• Integers encoded in the shortest form.

Ordering note. This is RFC 8949 §4.2.3 (“length-first”) map-key ordering, not the §4.2.1 (“Core Deterministic Encoding”) pure byte-lexicographic ordering. Length-first is what the encoders in this section’s scope actually produce — the pure-Python codec (cowboy_sdk.codec, the encoder used on-chain since there is no host-side cbor_encode) and the VM’s continuation/snapshot encoder (cbor_key_cmp) both sort (len(key), key). The two implementations are byte-for-byte consistent; the choice is fixed by the deployed encoders. (Note: the transaction / PayloadSign envelope is a separate determinism boundary — it is keccak256-signed and serialized with ciborium in struct-field-declaration order, not length-first, so a tx signer must mirror that field order rather than length-first-sort its keys. That envelope is outside §11.5’s scope.) Migrating the boundary to §4.2.1 would change the canonical bytes of all on-chain CBOR (state values, payloads, continuation state) and is therefore a coordinated consensus change, tracked separately — not implied by this section.

​

12. Runtime Module

​

12.1 Context

​

12.2 State

runtime.get_state(key: bytes) -> bytes | None
runtime.set_state(key: bytes, value: bytes) -> None
runtime.delete_state(key: bytes) -> None

​

12.3 Events

runtime.emit_event(name: str, payload: Any, *, schema: bytes | None = None) -> dict

​

12.4 Tokens (CIP-20)

runtime.token_create(name, symbol, decimals, initial_supply, max_supply, transfer_hook, metadata_uri) -> token_id
runtime.token_transfer(token_id, to, amount)
runtime.token_approve(token_id, spender, amount)
runtime.token_transfer_from(token_id, from_addr, to, amount)
runtime.token_mint(token_id, to, amount)
runtime.token_burn(token_id, amount)
runtime.token_balance_of(token_id, account) -> int | None
runtime.token_allowance(token_id, owner, spender) -> int | None
runtime.token_total_supply(token_id) -> int | None

​

12.5 Timers (CIP-5)

runtime.schedule_timer(fire_at_block: int, payload: bytes) -> timer_id: bytes
runtime.schedule_timer_ex(height, payload, fee_payer, gas_limit, expires_at) -> timer_id: bytes
runtime.extend_timer(timer_id: bytes, new_expires_at: int) -> None
runtime.cancel_timer(timer_id: bytes) -> None

​

12.6 Jobs (CIP-2)

runtime.submit_job(payload: bytes) -> None

​

12.7 Upgrades

runtime.upgrade_self(new_code: bytes, new_manifest: bytes | None = None) -> None

​

12.8 Crypto

runtime.keccak256(data: bytes) -> bytes                 # 32-byte hash
runtime.randomness(domain: bytes) -> bytes              # deterministic VRF output

​

12.9 Metering

runtime.charge_gas(amount: int) -> None

Superseded for application actors (2026-07-28). The paragraph above records the original CIP-6 position and is retained as historical specification text. Current guidance: application actors MUST NOT call runtime.charge_gas(). The function remains implemented and still consumes Cycles, so a manual call charges gas in addition to the automatic syscall-boundary metering described above — it inflates cost rather than front-loading it. Manual calls were removed from the bundled node examples and developer guides in node#921, and from the remaining actors, examples, and guides. This note changes recommended practice only; it does not alter the metering semantics specified in this section.

​

12.10 Ownership

runtime.get_owner() -> bytes              # current owner (20 bytes), or b'' if unset
runtime.transfer_ownership(new_owner: bytes) -> None
runtime.renounce_ownership() -> None      # sets owner to zero address; irrevocable
runtime.assume_ownership_if_unowned() -> bytes   # first-caller-wins bootstrap
runtime.is_initialized() -> bool          # True after init returns successfully

def init(self, payload):
    runtime.assume_ownership_if_unowned()   # deployer becomes owner atomically

• If no owner is set, any caller may set it (bootstrap window). Safe only when ownership is claimed inside init, because the CLI runs init atomically in the deploy transaction with sender = deployer, closing the window. Deploying with --no-init (or deferring the owner claim to a later transaction) leaves an unguarded front-run window — the protocol enforces no deployer-binding on the first assume_ownership_if_unowned() call, so a third party can claim ownership between deploy and the owner-claim tx. Actors that rely on init for ownership MUST NOT be deployed with --no-init.
• Once set, only the current owner or an intra-actor call may transfer.
• Passing the zero address to transfer_ownership raises ValueError; use renounce_ownership() explicitly.

​

12.11 State Prefix Scan

runtime.scan_state_prefix(prefix: bytes, limit: int = 100) -> list[tuple[bytes, bytes]]

​

12.12 Native CBY Balance

runtime.transfer_balance(to: bytes, amount: int) -> None

• to: 20-byte recipient address. The system-reserved address band (per CIP-1 §5) is rejected with HostError::InvalidInput. The zero address is rejected.
• amount: non-negative integer in wei.

• Atomic with the calling transaction. The debit and credit are staged in the transaction’s write-set; if the enclosing transaction reverts, both reverse together. Implementations MUST route the balance writes through the same staged-writeset machinery used by call() and set_state — direct ledger mutations bypassing the writeset are non-conformant and leak balance on revert.
• Insufficient balance raises HostError::InsufficientFunds and does not mutate either account.
• amount == 0 is a no-op (no event, no metering beyond the syscall base cost).
• Self-transfer (to == get_actor_address()) is permitted and is a no-op on net balance, but still consumes the syscall base cost.
• Allowed from any @deferred handler. @pure and read-only contexts MUST reject transfer_balance with HostError::Forbidden.
• Requires the econ.transfer entitlement on the calling actor’s manifest. Legacy actors with no manifest MAY transfer freely, consistent with the rest of the runtime.

1. Atomic seed via fork(endowment=N) — birth the child already funded, with a single atomic debit/credit folded into the fork itself. Use when the parent must guarantee the child has CBY before any post-fork code runs (e.g. a child whose on_fork schedules a self-timer at default fee_payer = self).
2. Post-fork transfer — fork the child, then transfer_balance(child, N) from the parent. Both calls are in the same transaction and share rollback, but the child is briefly zero-balance between the two syscalls. Use when the funding amount depends on state the parent doesn’t know pre-fork.

​

13. Verification Builder

from cowboy_sdk import Verify, runner

await runner.llm(
    prompt="Analyze market...",
    response_model=MarketAnalysis,
    verification=Verify.builder()
        .mode("consensus")
        .runners(5)
        .threshold(3)
        .check(Verify.json_schema_valid(MarketAnalysis.schema()))
        .check(Verify.numeric_tolerance("score", 0.05))
        .check(Verify.no_prompt_leak())
        .build(),
)

​

14. Entitlements

​

14.1 Manifest Format

{
  "entitlements": [
    {"id": "econ.hold_balance"},
    {"id": "econ.transfer", "params": {"max_amount": "1000000000", "max_per_block": "10000"}},
    {"id": "http.fetch", "params": {"allowlist_domains": ["api.example.com"], "max_requests": 100}},
    {"id": "oracle.llm", "params": {"max_tokens": 4096, "max_requests": 50}}
  ]
}

• id values MUST appear in the Entitlement Registry (types/src/registry.rs).
• The entitlements array MUST be lexicographically sorted by id; a chain MUST reject deploy transactions with an unsorted manifest.
• params contents are entitlement-specific and validated at deploy time against the registry’s ParamSchema.
• An upgrade’s manifest MUST be a subset (in both ids and param-bound strength) of the prior manifest.

​

14.2 Runtime Enforcement

1. Actor invokes an SDK function.
2. SDK issues the corresponding syscall.
3. Host checks the actor’s manifest for the required entitlement.
4. If absent: Host returns HostError::MissingEntitlement → SDK raises the corresponding error.
5. If present but quota-exceeded or param-restricted: Host returns the appropriate error.

​

14.3 Entitlement Registry (Informative Summary)

Note — token entitlements are not discrete string IDs (COW-1507). Unlike the other rows, the token.* capabilities are not registered as string IDs in the entitlement registry. The implementation models them with a typed Scope::Token([u8; 32]) (the token id) plus the matching Action variant (TokenTransfer / TokenMint / TokenBurn / TokenFreeze / …) in node/types/src/entitlement.rs — so a grant is naturally scoped to a specific token rather than a global token.transfer string. token.create is the exception: it has no Action variant and is not entitlement-gated — creating a token is gas-metered only, and the creator (tx.from) becomes the token’s owner and mint authority. This row is an informative summary of those capabilities; the typed Scope::Token + Action model is authoritative.

​

15. Error Hierarchy

• HOST_ERROR_CODE: int — Host API error code (1–8)
• ERROR_SLUG: str — short identifier, format E1xxx
• .why: str — human explanation
• .fix: str — suggested remediation

​

16. CLI

​

16.1 Project bootstrap

cowboy init <network>                     # network: local | dev | summit
cowboy wallet create [--output FILE]
cowboy wallet create-mnemonic

​

16.2 Actor lifecycle

cowboy actor new <name>                   # scaffold actors/<name>/main.py
cowboy actor deploy
    --code <file.py>
    --salt <hex>
    [--manifest-json <file.json>]
    [--no-init]                           # skip atomic init entirely
    [--init-handler <name>]               # default: "init"
    [--init-payload <json-string | @file>]  # default: "{}"
    [--cycles-limit N] [--cells-limit N]
cowboy actor address
    --code <file.py>
    --creator <addr>
    --salt <hex>                          # compute CREATE2 address locally
cowboy actor execute
    --actor <addr>
    --handler <name>
    --payload <hex | @file>
cowboy actor get --address <addr>
cowboy actor logs --address <addr>

cowboy fund-actor --actor <addr> --amount <cby>
cowboy upgrade-actor
    --actor <addr>
    --code <new.py>
    [--manifest-json <new.json>]          # requires sys.upgrade entitlement

​

16.3 Ecosystem

cowboy account balance [--address <addr>]
cowboy token create --name N --symbol S --decimals D --initial-supply X [--max-supply Y]
cowboy token transfer --token-id T --to <addr> --amount A
cowboy runner list
cowboy runner register --stake <amount>
cowboy job submit --job-spec <file.json>
cowboy watchtower init
cowboy watchtower new feed --name N [--description D]
cowboy watchtower feed <id> publish --data <json>

​

16.4 Conformance

​

17. PVM Determinism Rules

​

18. Reference Implementation

• In-PVM SDK (cowboy_sdk): node/pvm/Lib/cowboy_sdk/ (version 0.1.1)
• Host API: node/execution/src/pvm_host.rs
• CLI: node/cli/ (binary cowboy)
• Standalone developer SDK (cowboy): python-sdk/ (PyPI: cowboy-sdk, version 0.1.0)
• Examples: cowboy/examples/core/05-tokens-and-balances, cowboy/examples/core/09-runner-llm, cowboy/examples/gallery/audio-transcription, cowboy/examples/gallery/image-generation, cowboy/examples/gallery/dao-copilot, cowboy/examples/gallery/compliance, cowboy/examples/gallery/advanced-messaging-ring

​

19. Open Questions / Gaps

1. CIP-9 volume mounts from the SDK. Today, CBFS volumes are a runner-side concern. An actor-side API for mount(volume_id, access_mode) is not yet defined. Needed for first-class storage-attached actor workflows.
2. CIP-7 / CIP-17 stream helpers. cowboy watchtower exists at the CLI level and as a system-actor pattern, but there is no actor-side @on_stream(stream_id) decorator or stream_publish() helper. Authors currently manage this via raw call() / send().
3. Checkpoint vs FSM mode. runtime.is_checkpoint_mode() reports the persistence layer. Checkpoint mode (ContinuationMode::Checkpoint) is the current production on-chain format (§9.5); the FSM execution mode is not yet enabled in production. Terminology reconciliation is tracked in COW-2340.
4. Reentrancy semantics on call() cycles. @reentrancy_guard is defined, but its key derivation (keccak256(method_name ‖ caller_addr)) may over-collide in contract-factory patterns. A CIP-6.1 revision may add an explicit key argument.
5. Address scheme forward compatibility. Address is fixed at 20 bytes (Ethereum-compatible). A future migration to a larger scheme would break the type; no migration path is specified here.
6. Static loop-bound detection. The compiler rejects unbounded await-in-loop at class-load, but edge cases (awaits inside comprehensions, awaits in helper functions called from loops) are under-specified. A future revision should enumerate accepted and rejected shapes.
7. Entitlement manifest upgrade semantics. “Subset” is defined informally; the registry needs an is_tighter_than operator per entitlement, currently implemented ad-hoc.
8. Standalone cowboy SDK coverage gaps. The standalone package does not yet mirror runner, capture, ActorRef, Verify, CowboyModel, SoftFloat, ordered_set, BlockHeight, or Storage.get_raw() / set_raw() / guard(). Actors that use those features must be tested against a live PVM sandbox.