CIP-26: Account-Scoped Actor Libraries

​

1. Abstract

​

2. Motivation

1. Inline-and-duplicate. Copy the shared code into every actor file. The Texas Hold’em example notes this directly: “hand evaluation inlined — PVM cannot import external modules”. Drift, duplication, no single source of truth.
2. Build-time bundling. A relayer or Makefile concatenates the shared module into each actor before deploy. Works (some examples do this), but the deployed actor’s code stops resembling its source, hash-pinning is per-deployer rather than per-library, and audit/review tooling has to reverse the bundle.

​

2.1 Why account-scoped (not global)

1. Trust. An actor that imports crypto_helpers from a global namespace is one TOCTOU window away from importing whatever a stranger published under that name first. Hash-pinning at the deploy site mitigates this for the deploy itself, but the human writing the actor source is now responsible for verifying every dependency hash, which is a security review burden with very poor ergonomics. Account scoping makes “did I write or audit this code?” trivially answerable.
2. Operational sovereignty. With account scoping, each account controls its own dependency surface. With a global registry, a third party publishing buggy or malicious code under a popular name affects every consumer simultaneously.

​

2.2 Why immutability of actors makes this simple

​

3. Specification

​

3.1 Library data structure

struct ActorLibrary {
    publisher: Address,    // account that owns this library entry
    name: String,          // import name; 1..=64 bytes; ASCII-only, `^[a-zA-Z_][a-zA-Z0-9_]{0,63}$` (stricter than Python's Unicode identifiers — see §3.3)
    code_hash: Digest,     // keccak256 of code bytes; canonical id
    code_size: u32,        // bytes of `code` (cached for gas accounting); u32 (bounded by MAX_LIBRARY_CODE_BYTES = 131_072)
    published_at: u64,     // block height of the publish
}

​

3.2 Storage layout

​

3.3 Publishing

enum LibraryInstruction {
    PublishLibrary {
        name: String,
        code: Vec<u8>,
    },
}

1. Validate name matches the Python identifier regex ^[a-zA-Z_][a-zA-Z0-9_]{0,63}$.
2. Run validate_actor_code(code) (CIP-3 §2.2.4) — same determinism gate as actor code; bans os.system, pickle, import time at module top, large integer literals, etc.
3. Compute code_hash = keccak256(code).
4. set_code(code_hash, code) — idempotent; shared blob storage.
5. Write Library { publisher: sender, name, code_hash, code_size, published_at: block_height } to (sender, name). Replaces any prior entry under the same (sender, name).

cowboy lib publish --name engine --code ./engine.py
# → "Library published: name=engine code_hash=0xabcd... size=4321"

​

3.4 Resolution and pinning at actor deploy

1. Existing flow validates the actor code, reserves the address, etc.
2. New step: scan the actor’s source AST for top-level import X and from X import ... statements where X is not in the SDK / stdlib whitelist. Call this set the candidate import set.
3. For each name X in the candidate import set:
   • Look up Library at (sender, X).
   • If absent → Err(ExecutionError::UnresolvedImport { name: X }). Deploy fails atomically (atomic-init rollback already covers the actor record per COW-870; the same rollback path applies here before any storage is committed).
   • If present → record (actor_address, X) → library.code_hash in the actor’s pin set.
4. Persist the pin set as a sequence of writes to ActorLibPin in the same atomic deploy.
5. The pin set’s total size is added to the actor’s deploy gas cost (cells_per_pin = 64 cells for the hash + key overhead — matches §3.6 and gas.rs::LIB_PIN_OVERHEAD_CELLS).

​

3.5 Resolution at handler execution

1. Before handler entry, the runtime reads the actor’s pin set from ActorLibPin and pre-resolves each code_hash → code_bytes from the shared Code table.
2. For each pinned (name, code_hash, code_bytes), the runtime executes code_bytes in a fresh module object, installs it as sys.modules[name], and adds name to the import allowlist for this PVM context.
3. The handler runs. Any import name resolves to the pre-loaded module.
4. After the handler returns (success or failure), the per-context allowlist additions are discarded; the global allowlist stays untouched.

​

3.6 Gas

• Deterministic classification: warm/cold pricing MUST depend only on committed state and in-block access order. The physical compiled-code cache is an optimization with no pricing role; validators with different process histories MUST charge identically.
• Block-local shadow cache: reset it empty at each block, with capacity 32 and LRU ordering over library and actor-code accesses. A library hash absent from this set prices cold. Admission or promotion occurs only after the charge and compile succeed; a 33rd entry evicts the least recently used entry, which prices cold on its next load.
• Synchronous charging: every compile-relevant access, including a physical cache hit, MUST call before_access(kind: ActorCode | Library, code_hash, len) → Result<Cold | Cached, OutOfGas>. The engine classifies and applies the fallible charge before compile work. OutOfGas aborts that access. The runtime then calls after_access(compile_succeeded: bool); only success admits or promotes the entry.
• Actor-code occupancy: actor-code accesses count toward shadow capacity but incur no library cold/cached charge. Actor-entry gas already pays for their compilation; charging again would double-bill them.
• Access order: each handler accesses libraries first in canonical sorted pin-name order, followed by the actor-code compile. All validators MUST derive the same shadow-cache order.
• Failure semantics: a failed charge or compile MUST leave a cold entry cold. A successfully charged and compiled entry stays warm even if the enclosing handler or transaction later faults; shadow membership is block-scoped metering state, not rollbackable application state.
• Publication accounting: every publish pays LIB_CATALOG_ROW_CELLS = 128 for the catalog/metadata row. Code-blob Cells are charged only after the cache lookup establishes that the blob is new. Reusing code bytes does not make a new catalog entry free.
• Code metadata: PublishLibrary MUST stage the CIP-27 CodeMeta marker for each new Code row, derived from the bytes by the same rule as other code producers. Publish-first and deploy-first execution MUST produce the same marker.

​

3.7 Replacing or removing a library

• gas.rs defines the gas constants, including LIB_CATALOG_ROW_CELLS.
• pvm-runtime/lib.rs calls the synchronous before_access / after_access API from §3.6 on every compile-relevant access, whether the physical cache hits or misses.
• The engine’s block-local shadow tracker owns warm/cold classification, the fallible gas charge, admission, LRU ordering, and capacity. actor_instruction.rs does not classify or charge these accesses separately.
• library_instruction.rs charges for the catalog row and stages CodeMeta for new code.
• pvm_host.rs and system_instruction.rs carry PinSetMismatch and its structured receipt codes on both upgrade paths. Protocol dependency pins must include the corresponding shared types.

​

3.7bis Error codes

​

3.8 Manifest interaction

• Explorer: for any deployed actor, scan its ActorLibPin rows and display name → code_hash (optionally resolving each code_hash to the publisher/library it came from) so users can see exactly which library versions the actor is frozen against.
• CLI: a cowboy actor pins <address> command lists the same (name, code_hash) pairs (implementation tracked separately as a CLI follow-up; this section specifies what it surfaces). Because the pin set is deploy-time-frozen and read-only, the displayed dependencies are stable for the life of the actor.

​

3.9 Determinism guarantees

• The actor’s ActorLibPin table is immutable post-deploy.
• The pinned code_hash resolves to a content-addressed blob in StatePrefix::Code that is written once and never mutated.
• Library code passes the same validate_actor_code checks as actor code, so it cannot introduce non-deterministic behavior the host would otherwise reject.

​

4. Worked example

$ cowboy lib publish --name engine --code engine.py
Library published: publisher=0xAlice name=engine code_hash=0xabcd1234... size=4321

# in world_actor.py:
from cowboy_sdk import actor, public, runtime
import engine

@actor
class World:
    def init(self, payload):
        runtime.emit_event("init", {"version": engine.VERSION})

$ cowboy actor deploy --code world_actor.py --salt $SALT \
    --init-handler init --init-payload '{}'
✓ Library imports resolved:
    engine → 0xabcd1234...
✓ Actor deployed: 0xWorld...

$ cowboy lib publish --name engine --code engine_v2.py
Library published: code_hash=0xfeed5678... size=4520

$ cowboy actor deploy --code world_actor.py --salt $SALT --init-handler init
Error: deploy failed: UnresolvedImport { name: "engine" }
   no library named "engine" published under deployer account 0xBob

​

5. Reference implementation

• node/storage/src/state_key.rs — add StatePrefix::Library and StatePrefix::ActorLibPin.
• node/storage/src/traits.rs — add get_library, set_library, delete_library, get_actor_lib_pins, set_actor_lib_pin.
• node/storage/src/accounts.rs — concrete impls of the above.
• node/cowboy-types/src/instruction.rs — Instruction::Library(LibraryInstruction::{PublishLibrary, RemoveLibrary}).
• node/execution/src/execution/library_instruction.rs — new file; instruction handler.
• node/execution/src/execution/actor_instruction.rs::DeployActor — add the AST scan + pin resolution step before atomic init.
• node/pvm/crates/pvm-runtime/src/guard.rs — extend _is_allowed and the _pvm_import hook to consult the per-context pin set.
• node/pvm/crates/pvm-runtime/src/lib.rs — pre-load pinned libraries into sys.modules before handler entry.
• node/cli/src/commands.rs — cowboy lib publish | remove | list subcommands.

• Publish + import + handler call round-trip.
• Cross-account import is rejected.
• Pin survives library re-publish.
• Pin survives library removal (existing actors keep working; new deploys can’t pick up the removed name).
• Atomic deploy rolls back on UnresolvedImport (extends the COW-870 regression test).
• Determinism: re-running the same handler at the same height with the same input returns identical state across nodes after a library re-publish.

​

6. Backwards compatibility

​

7. Security considerations

​

7.1 Trust model

​

7.2 Determinism attacks

​

7.3 Storage exhaustion

​

7.4 Pin-set tampering

​

8. Out of scope

• Cross-account imports. Forbidden by design (§2.1). Not a future addition.
• Bytecode caching across handler invocations. Performance optimization; doesn’t change semantics. Worth doing eventually since the per-call lib re-execution is real cost.
• Lazy / conditional imports. Disallowed by §3.4 because they break the AST-driven pin discovery. Could be revisited if a compelling use case emerges.
• Library transitive dependencies. Transitive imports are not resolved by the §3.4 mechanism: the deploy-time AST scan and pin set are computed from the actor’s source only, and only the actor’s own ActorLibPin modules are installed into sys.modules at handler entry (§3.5). A library that does import other_lib therefore only resolves if other_lib is also a direct import of the actor (so it is independently pinned under the actor); a library’s private dependency that the actor does not itself import is unresolved at runtime. Library authors must flatten their dependency closure into the actor’s direct import set (or vendor it into the library source). Automatic transitive resolution is spec’d separately if pain emerges.
• Versioning / semver. Not built in. Account holders can publish multiple distinct names (engine_v1, engine_v2) if they want explicit version pinning visible in actor source. The hash-pinning at deploy makes “what version did this actor pin?” trivially answerable from ActorLibPin.

​

9. Open questions

• Should cowboy lib publish accept a directory and bundle multiple files into a single library, or strictly single-file? Single-file is simpler and matches how almost all examples are structured today; multi-file can be added if anyone hits the friction.
• Should a library be allowed to import cowboy_sdk? Most utility libraries won’t need it (pure rules), but some will (lib that emits events). Default: yes, allow cowboy_sdk imports from libraries on the same terms as actors. The handler-execution import map already covers it.
• MAX_LIBS_PER_ACTOR = 8 is a guess. Empire’s example would use 1; Texas Hold’em would use 1. If real usage demands more, raising the cap is a numeric change with no spec impact.