​

CIP-33: Actor Hiring & Distribution

​

Abstract

​

1. Motivation

​

1.1 Store mechanics belong in the protocol; stores do not

1. Hireability — a machine-readable statement that an actor can be hired, under what terms, by humans and by other actors.
2. Distribution rights — creator-controlled authorization for a store to sell access to the actor.
3. Fee splits — hire revenue divided among creator, store, and referrers exactly as declared, atomically with payment.
4. Attestation — verifiable review verdicts bound to exact code snapshots, so trust survives redistribution.
5. Enforcement — for private-code actors, access that can be granted, metered, and revoked without trusting the storefront.

​

1.2 Why enforcement needs no consensus changes

​

1.3 Design principles

• Neutrality. No privileged store. Store registration is open. The Trading Post grants every store identical powers, scoped to its own grants.
• Creator sovereignty. Creators decide which stores may distribute their actors. Grants are non-exclusive by default and revocable.
• Direct hire is first-class. A hire with no store involved MUST work; a store is a discovery and trust layer, never a tollbooth.
• Enforce by cryptography and settlement, not consensus. Leases gate key delivery; the Trading Post gates payment flows. Validators are unmodified.
• Policy is replaceable. Review standards, curation, pricing of trust — all app-layer. The protocol records outcomes (attestations), not opinions.

​

2. Specification

​

2.1 The Trading Post system actor

HireableDeclaration {
  declaration_id:  Hash,             // caller-supplied: H(creator ‖ actor ‖ salt); §2.1.1
  actor:           Address,          // the hireable actor
  creator:         Address,          // payout + grant authority
  badges:          { human_hireable: bool, agent_hireable: bool },
  latest_version:  u32,
  status:          Active | Retired,
}

DeclarationVersion {                 // append-only under a declaration; never edited in place
  version:           u32,            // 1.. , assigned sequentially
  manifest_root:     Hash,           // CBFS manifest root of the code at this version (CIP-9)
  code_visibility:   Public | Private,
  capability_schema: VolumePath,     // CBFS path to capability document (§2.6)
  terms:             [PricingTerm],  // §2.4
  default_split:     SplitVector,    // §2.3, used for direct hire
}

ServingArtifact {                    // a concrete volume carrying a version's code
  artifact_id:    u32,               // 0 = the creator's own volume, created with the version
  declaration_id: Hash,
  version:        u32,
  store_id:       Option<u64>,       // None for artifact 0; the registering store otherwise
  volume_id:      VolumeId,
  claimed_root:   Hash,              // MUST equal the version's manifest_root (a claim — §2.5.1, §4)
  registered_by:  Address,           // creator (artifact 0) or the store's operator
  ibe_ciphertext: Bytes,             // volume DEK under the artifact's IBE label (§2.5.1); Private only
  status:         Active | Retired,  // Retired = no new hires may pin it; pinned hires unaffected
}

StoreRecord {
  store_id:    u64,
  operator:    Address,              // store's signing/treasury address
  metadata:    VolumePath,           // name, policy URI, branding
  status:      Active | Retired,
}

DistributionGrant {
  grant_id:          u64,
  declaration_id:    Hash,           // grants are declaration-scoped; hires pin versions
  store_id:          u64,
  split:             SplitVector,    // agreed split incl. store commission
  max_referral_bps:  u16,            // ≤ the store's own share; referral entries draw from it (§2.3)
  lease_epoch_blocks:u64,            // §2.5; creator-set, per grant
  status:            Active | Revoked,
}

Hire {
  hire_id:        u64,
  declaration_id: Hash,
  version:        u32,               // pinned at hire time; root swaps never affect live hires
  artifact_id:    u32,               // pinned serving artifact this hire runs (§2.2)
  grant_id:       Option<u64>,       // None = direct hire
  hirer:          Address,           // payer; human account or hiring actor
  hire_block:     BlockHeight,       // anchors lease-epoch numbering (§2.5.1)
  term:           PricingTerm,       // selected at hire time
  split:          SplitVector,       // pinned copy (grant/default split + referral entry, §2.3)
  prepaid:        u128,              // balance held by the Trading Post (§2.4); funds renewals
  reserved:       u128,              // portion of prepaid committed to open PerCall sessions (§2.6.3)
  renewal_on:     bool,              // hirer-controlled via set_renewal; renew() no-ops when false
  paid_through:   BlockHeight,       // subscription horizon; ∞ for one-shot; unused for PerCall
  status:         Active | Paused | Revoked | Lapsed,
}

Attestation {
  attester:      Address,
  manifest_root: Hash,
  verdict:       Approved | Rejected | Flagged,
  policy_uri:    VolumePath,         // the policy the verdict was issued under
  issued_at:     BlockHeight,
}

​

2.1.1 Declaration identity

​

2.1.2 Methods

​

2.2 Direct hire and artifact pinning

​

2.3 Split vectors

SplitVector = [ (beneficiary: Address, share_bps: u16) ]   // Σ share_bps = 10_000

• Validated at declare/declare_version/grant time: shares sum to exactly 10,000 bps; max 8 entries; no zero-share entries.
• Pinned at hire. The effective vector (grant or default split, plus any referral entry) is copied into the Hire and every subsequent renew and settle_per_call settles against the pinned copy. Editing a grant’s split affects only future hires.
• Executed atomically inside hire/renew/settle_per_call: the Trading Post receives or draws the payment (CBY or a CIP-20 token named in the term) and transfers each beneficiary’s share in the same method execution. Rounding dust (the remainder after integer division) accrues to the first entry (by convention, the creator).
• Settlement is direct ledger movement. Trading Post transfers mutate balances directly and do NOT invoke CIP-20 transfer hooks — a multi-leg split must not be abortable or reenterable by a beneficiary’s hook. Hook semantics consequently do not fire on hire settlement; tokens whose economics depend on transfer hooks should not be offered as pricing denominations. Standard CIP-20 transfer events ARE emitted per leg, so indexers observe every movement. A settlement fails closed as a whole if any participant’s token account is frozen.
• Referral and creator codes are not a mechanism. At hire time the client MAY append at most one referral entry of up to the grant’s max_referral_bps, deducted exclusively from the store’s share; the pinned vector still sums to 10,000. The protocol has no opinion about what codes mean.
• The protocol itself takes no cut. Chain revenue from hiring is gas and compute, as for any other actor activity.

​

2.4 Pricing terms

PricingTerm =
  | OneShot      { price, token }                   // perpetual access; survives retirement (below)
  | Subscription { price, period_blocks, token }    // paid_through advances per renewal
  | PerCall      { price_per_call, token }          // metered via MPP session (§2.6.3)
  | Free

• OneShot sets paid_through = ∞ and survives retirement: the creator’s escrow and serving obligation for already-sold one-shot hires is perpetual. Creators who want a sunset path MUST price as Subscription.
• Subscription advances paid_through by period_blocks per successful renew.
• PerCall ignores paid_through; validity is an open, funded MPP session (§2.6.3), where “funded” means the session’s reservation is covered by reserved. Reservations move balance from available to reserved at session open and release at settlement or session close, so withdraw_unused can never strand an open session.
• Free carries no money; validity is simply declaration ∧ grant (if any) ∧ hire all Active. Private + Free is legitimate (e.g., a free private beta).

​

2.5 Key leases (private-code actors)

​

2.5.1 Mechanism

tradingpost/{declaration_id}/{version}/{artifact_id}

job(job_id) is assigned to runner_id
  ∧ job(job_id) is bound to (hire_id, pinned artifact)   // job metadata, set at dispatch
  ∧ Hire(hire_id).status == Active
  ∧ term validity:  Subscription | OneShot → current_block ≤ paid_through
                    PerCall              → bound MPP session open ∧ funded (§2.4, §2.6.3)
                    Free                 → declaration ∧ grant (if any) Active (§2.4)

​

2.5.2 Revocation latency

• Fast path (seconds): runners MUST subscribe to Trading Post lifecycle events (CIP-29 via indexer feed) and stop accepting/continuing jobs for a hire upon observing pause/revoke_hire. This is a runner-policy requirement tied to reputation/slashing (CIP-2), not consensus.
• Cryptographic backstop (≤ one lease epoch): share issuance stops at the next lease-epoch boundary regardless of runner behavior.

​

2.5.3 Residual risk — cached DEKs

​

2.6 Agent hire

​

2.6.1 Capability schema

​

2.6.2 Discovery and hire

​

2.6.3 Metered usage

​

2.6.4 Instances

​

2.7 Attestations

• Open: any address may attest; there is no attester registry to gatekeep. Trust is a client decision — wallets, dashboards, and stores choose which attesters to honor and how to render unattested code (e.g., Android-style friction). The protocol ranks nothing. Spam is bounded, not policed: implementations MUST bound per-root index growth by one of two means — (a) storage-proportional gas per record written plus paginated reads (list_attestations serves pages), or (b) a hard cap on distinct attesters per root, under which whole-list reads are acceptable and supersession by an already-listed attester MUST still succeed at the cap, so a full index can never block an attester from downgrading a prior verdict.
• Bound to exact roots: an attestation never carries to a new manifest_root. Re-review is a new attestation.
• Append-only with supersession: records are never deleted; the effective verdict for (attester, manifest_root) is the latest record, so an attester can downgrade a prior Approved to Flagged or Rejected. Flagged is advisory — clients SHOULD surface it prominently; it gates nothing protocol-side.
• Cowboy Labs’ review organization is simply one attester, whose verdicts the flagship store and first-party clients choose to require.

​

2.8 Events

​

3. Economics and neutrality

​

4. Security considerations

• Trading Post as high-value target. It custodies split execution and lease state. Mitigations: CIP-12 upgrade governance, no operational superpowers to abuse (§2.1 neutrality invariant), splits executed by simple arithmetic over validated vectors, and the actor-model’s single-threaded method execution (no reentrancy across a split’s transfers; token transfers are CIP-20 syscalls inside one method execution).
• Grant/declaration forgery. All mutating methods authenticate the caller against the object’s authority field (creator, store operator, or hirer); standard actor-call sender authentication, no new signature schemes. declaration_id preimage verification (§2.1.1) prevents id squatting.
• Prepaid custody. The Trading Post holds per-hire balances; only the hirer can withdraw, only renew/settle_per_call can draw, and revoke_hire refunds automatically. Balance accounting is per-hire — no pooled-fund invariants to break.
• Artifact equivalence is a claim. claimed_root is signed state from the registrant, not a proof. A store serving content that diverges from the attested root is detectable by anyone with read access (decrypt + compare) and publicly attributable to the registering address; attesters can downgrade (§2.7). A cryptographic equivalence proof is an open question.
• Lease policy correctness in cbssd. Issuance policy reads chain state; cbssd hand-rolls chain interaction today and has drifted from node before — the policy check MUST be covered by e2e tests against a live devnet node, not unit fixtures.
• Split griefing. Vector caps (8 entries, no zero shares) bound transfer fan-out; beneficiary addresses are not validated as live — a transfer to a dead address burns that share, which is the beneficiary’s risk, as with any CIP-20 transfer.
• Attestation index growth. attest is open to any address (§2.7), so a hostile attester can grow a root’s attestation index without bound. §2.7 mandates a bound: proportional metering plus pagination, or a per-root attester cap. The cap variant has a residual: Sybil attesters can fill a root’s index and block new attesters from recording verdicts on it — accepted, since filling costs gas per record and verdicts from unrecognized attesters carry no client trust weight; attesters clients rely on SHOULD attest at review time, before an adversary targets the root. Spam records themselves carry no trust weight because clients filter by attester.
• Store-side censorship. Bounded by design: scope-limited pause powers, open store registration, direct hire, and public events.
• Cached-DEK residual (§2.5.3): accepted, bounded by settlement refusal and runner stake; revisit if runner trust assumptions weaken.

​

5. Out of scope

​

6. Open questions

1. Per-epoch IBE label rotation as cached-DEK hardening — cost: ciphertext re-production path; candidate for a CIP-33.r2 once runner-trust data exists.
2. PerCall rate-limit defaults and MPP session caps for hostile hiring actors.
3. Capability-schema registry: whether a curated schema-type catalog (beyond free-form JSON Schema) earns its complexity once agent-hire volume exists.
4. Whether instance_mode: Forked should become the default once CIP-27 stabilizes.
5. Per-period escrow of executed splits, enabling protocol-level pro-rata clawback on trust-and-safety revocation (v1 refunds only unspent prepaid, §2.4).
6. Cryptographic plaintext-equivalence proof binding a ServingArtifact to its version’s manifest_root (v1: signed claim + social detectability, §4).