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 a CBOR-encodable value 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
    def get_count(self, payload) -> int:
        return self.storage.get("count", 0)

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

    @callable_by(OWNER)
    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 || salt || code_hash)[12:]

• deployer_address: 20 bytes, the sender of the deploy transaction.
• salt: 32 bytes, caller-supplied (zero-padded if shorter).
• 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 CBOR-encoded 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
    def balance_of(self, payload):
        return self._compute_balance()        # calls underscore helper — no perm check

    @callable_by(OWNER)
    def withdraw(self, payload):
        ...

    @callable_by(b"\xaa" * 20, b"\xbb" * 20)
    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
    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
    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: CBOR-encodable dict of keyword arguments, or list of positional arguments.
• cycles_limit: explicit cycle budget for the callee. Defaults to 100_000 if omitted; passing it explicitly is recommended for precise metering.

• 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. Exceeding this raises CallDepthExceeded.
• Return value is CBOR-decoded 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"])

​

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.

​

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

​

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

​

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: dict | bytes | str) -> None

​

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

​

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 inside 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]]

​

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/01-tokens, cowboy/examples/08-audio-transcription, cowboy/examples/09-image-generation, cowboy/examples/13-dao-copilot, cowboy/examples/14-compliance, cowboy/examples/18-ring-demo

​

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 mode deprecation. runtime.is_checkpoint_mode() exists for local development but is marked for removal once FSM mode is production-stable across all targets.
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.