Skip to main content
Status: Draft Type: Standards Track Category: Core Created: 2026-08-08 Updated: 2026-10-03 Requires: CIP-3 (fee model — §2.5 multi-signer admission and metering), CIP-6 (SDK — §11.3 deterministic collections), CIP-40 (transaction verification — §7.3 duplicate-primary rule and per-slot signing modes) Relates-to: CIP-12 (Governance — Council SignerSet precedent), CIP-28 (agent banking), CIP-37 (Sign in with Cowboy)
Cowboy Cloud and Cowboy Chain. This CIP specifies the Cowboy protocol. Cowboy Cloud runs on this protocol today. Cowboy Chain, a public network on the same protocol, is under consideration for a future release. Where the two differ, this CIP says so.

1. Abstract

Cowboy transactions already carry multiple secp256k1 signatures. The mode-selected authorization digest binds Transaction.additional_signers, wire canonicalization rejects reordering and duplication, and block admission ecrecover-verifies every signer. Inside the execution engine, only two authorization checks read the verified signer set. This CIP exposes that set to actor code. HostContext gains a co_signers field, the SDK gains get_co_signers(), and client tooling gains a co-signing flow that assembles a multi-signer transaction from independently produced signatures. An actor can then enforce its own roster and threshold on a quorum operation in one atomic transaction, with no in-handler cryptography and no new signature scheme. Two companion rules live in other CIPs. CIP-40 §7.3 rejects a transaction whose primary is repeated in additional_signers, which makes a naive quorum count safe. CIP-3 §2.5 prices and bounds co-signature verification with an intrinsic non-sponsorable charge, a block budget, and ingress caps.

2. Background

In CIP-40’s fresh-genesis v3 release, Transaction.additional_signers: Vec<(Address, SignatureSlot)> holds the co-signers. Both authorization digests cover every signer address and slot descriptor but not the signature values, so nobody can add, remove or reorder a signer or descriptor after signing. verify(context) requires strict ascending address order, at most MAX_ADDITIONAL_SIGNERS (16), and no primary address in the additional roster. It recovers each caller-signed slot against that slot’s selected digest. Block admission checks every transaction. Deferred transactions are structurally unsigned, and CIP-40 §7.3 authenticates them against their origin receipt. Two consumers exist, both inside the execution engine. council_authorized counts distinct roster members across {tx.from} ∪ additional_signers against a SignerSet loaded from governance actor 0x09, and checks only membership and threshold. CreateAccount reads the same set through the existing Transaction::signers() helper and requires both tx.from and the new account to appear in it, which is a dual-signature rule. Neither re-verifies signatures; both rely on admission. Actor code cannot reach any of this. HostContext carries sender and nothing about co-signers. The fresh-genesis PVM API exposes keccak256 and CIP-6 §12.8’s verify_signature(algorithm, public_key, message, signature) with algorithm 2 (Ed25519) only, and deliberately omits secp256k1 recovery. The runtime still uses the internal ed25519_verify backend, which the same release renames in the public SDK. An actor therefore cannot verify Cowboy account signatures itself. No CLI co-signing flow exists either; test harnesses and external tooling assemble multi-signer transactions. The wasm codec already ships the client-side signing functions signing_preimage, signing_hash, sign, and encode_submission, and documents the flow this CIP standardizes: independent signing, then client-side assembly and submission. The v3 release updates these functions to bind ChainIdentity and select the digest per slot (§4.4, §4.8).

3. Goals

  • An actor can require a quorum of accounts for a privileged operation, enforced in one atomic transaction.
  • Authorization semantics are explicit: what a co-signature authorizes, in which execution frames it is visible, and how it expires.
  • The CIP adds no cryptography, no signature scheme, and no change to transaction identity.
  • Any client that can sign a 32-byte hash with secp256k1 can co-sign, including the CLI, the wasm SDK, and an EVM hardware wallet under CIP-40.

3.1 Non-Goals

  • Actors cannot be co-signers. They hold no keys, so an actor address can never appear in additional_signers. Actor quorums accumulate approvals across calls, where the callee sees the calling actor as sender, and a separate specification covers them.
  • Threshold and aggregate signatures are out of scope. The set is k independent ECDSA signatures, so cost and transaction size scale linearly.
  • The protocol adds no multisig account type. Authorization policy lives in the actor; the protocol supplies an authenticated signer set and does not interpret it.
  • tx.digest() does not change. Transaction identity stays signature-independent.

4. Specification

4.1 Signer Set Semantics

A co-signature is authorization only and has no economic or sequencing role:
  • The runtime checks tx.nonce against tx.from’s account nonce alone, and the nonce increment writes only that account. Co-signers consume no nonce.
  • A co-signer needs no balance and need not exist as a funded account; an address that has never transacted is a valid co-signer. The co-signer role never causes a debit. tx.from alone pays the co-signer intrinsic charge, and any separately authorized debit is independent of the co-signature.
  • The primary signer controls submission: it chooses whether, when, and at which nonce to assemble. The assembled transaction is a bearer artifact that carries every signature it needs, so anyone holding the bytes can broadcast it. Exclusive control ends at assembly.
Fees do not follow the signer set. For every signed (non-deferred) transaction, including top-level ExecuteActor, tx.from pays execution fees and the co-signer intrinsic charge from its escrow. The one exception is CIP-7 callback Cycles/Cells basefees, which their authorized subscribers pay. The sender pays every priority tip and Access fee. The callee, its CIP-28 default card and its owner entitlement neither sponsor nor gate that call. Separately authorized callback and deferred-work charging is unchanged; see CIP-28 §3.4 and §4.7 below. The authorization digest binds chain_id, nonce, and the full instruction in both signature modes, so a collected signature set authorizes exactly one transaction, on one network, at one nonce of one account. Once tx.from’s nonce advances past it, the signatures authorize nothing. Collected approvals therefore expire without an expiry field.

4.2 Host Context

HostContext gains two fields:
co_signers holds only the additional signers. The existing Transaction::signers() returns both the primary and the additional signers. The distinction between None and Some([]) MUST be preserved end to end. Some([]) means a signed transaction carrying one signer entered this frame. None means the frame’s authority did not come from a transaction signature. If both collapsed to an empty list, an actor deciding whether it was authorized could not tell a timer fire from a single-signer transaction. code_hash describes the executing actor. The field is present in every frame, including nested and non-signed ones, and always reflects the code actually executing. Simulation derives it from the executed code and overrides any injected value (§7). Without it, actor code could not check §5.2’s policy commitment: the execution context already carries actor.code_hash internally and reads it on every cross-actor call, but no host field or SDK accessor exposes it. code_hash is a frame-entry snapshot, immutable for the life of the handler frame. The snapshot matters because upgrade_self mutates the live context mid-handler: it stages the new bytes and overwrites ctx.actor.code_hash while the old code keeps executing. If the field tracked the live value, old code could call upgrade_self, observe the new hash, and pass a §5.2 commitment check under code that no longer matches it. The runtime captures the value at frame entry. upgrade_self changes what subsequent invocations observe and never the current frame. A self-call into the new code observes the new hash in its own nested frame, and nested frames restore the outer snapshot on both success and error return. Normative rules:
  1. The set contains additional_signers only. When the set is Some, sender is tx.from and is already available, so the full authorizing set is {sender} ∪ co_signers.
  2. The set is strictly ascending under byte-lexicographic comparison of the 20-byte big-endian address, which is the total order Address: Ord provides and wire canonicalization verifies. Actors may rely on the ordering and on the absence of duplicates.
  3. The runtime populates the set from the Transaction that passed verify() at admission. Nothing in the execution path may reconstruct it from handler input, instruction payload, or any other caller-supplied source.
  4. Provenance, not depth, determines the set. The set is Some in exactly one case: a directly signed, non-deferred transaction entered the frame through ExecuteActor or through the atomic init invocation of a deploy. init qualifies because the signed instruction contains the code, the handler, and the payload, so the deployer authorized exactly that invocation. Every other frame is None. Being the outermost frame does not make the set Some. Several execution paths create a fresh, outermost PVM context with no signed instruction behind it, and each of them MUST be None: deferred transactions, timer fires, mailbox deliveries, asynchronous event fires, token transfer hooks, runner result callbacks, gateway read paths, and default simulation contexts. A synchronous event fire is a nested entry. It runs through the same switch/restore machinery as call_actor, so the nested-frame rule makes it None. Simulation accepts a caller-injected HostContext. The default is None, and injected values are test fixtures with no authorization claim. A gateway submit differs: the gateway builds and signs an ordinary non-deferred ExecuteActor transaction with its own key, so the actor observes Some([]) with the gateway as sender.
  5. Every nested handler invocation sets the field to None and restores the caller’s value on return. The rule covers the cross-actor path through switch_to_callee / restore_call_snapshot and the self-call path, which bypasses both and dispatches straight to execute_current_handler. A sender-based test cannot replace this rule, because a self-call leaves sender untouched and sender == tx.from still holds in the nested frame. See §5.1.
For deferred transactions, an existing structural invariant reinforces rule 4: verify() returns true for a deferred transaction only if additional_signers is empty. That invariant is what lets Council authorization trust the field at all. The Python bridge change is additive. host_context_to_dict gains a co_signers key, holding a list of 20-byte values or None, and a code_hash key holding 32 bytes. Actors that read context through the named accessors see no change. Because context is a dictionary, an actor that enumerates or serializes its keys does see the new ones, and that is the only compatibility change.

4.3 SDK Surface

cowboy_sdk.runtime exposes both functions, and pvm_sys re-exports them, mirroring get_sender(). get_co_signers reads context().get("co_signers"), so a missing key in an older runtime returns None without raising. It never returns [] for an absent key, because an older runtime is a frame of unknown provenance, which is the None case. A roster check is then ordinary actor code. The helper below fails closed on a degenerate threshold: threshold < 1 would authorize everyone, and threshold > len(roster) can never be met and indicates a configuration error. It rejects None outright instead of counting it as a quorum of one. The count needs no de-duplication, because canonical form (§4.5, CIP-40 §7.3) guarantees the set is ascending, duplicate-free, and disjoint from the sender:
The roster uses an ordered_set because CIP-6 §11.3 prohibits the built-in set and set() in actor code for determinism. This CIP requires CIP-6.

4.4 Client Co-Signing Flow

Co-signing is a three-phase flow over each slot’s mode-selected authorization digest. In mode 0 that digest is signing_hash(chain_identity); in mode 1 it is the EIP-712 digest of the typed representation (§4.8). Both digests bind the complete roster and every slot descriptor, so all of them must be fixed before anyone signs.
  1. The initiator builds the complete transaction: instruction, chain_id, from, from’s next nonce, all nine gas limit/fee fields, reserved defaults, and a frozen algorithm/mode/public-key descriptor for the primary and every additional signer. Additional signers are in ascending address order, and each slot holds a correctly sized zero signature placeholder. This object is the co-signing request.
  2. Each signer independently computes the digest its own slot’s mode selects over that object and signs it. Signers in the same mode share a digest; native and EIP-712 signers use distinct digests that bind the same complete transaction. No signer needs the others’ signatures, and signers can sign in any order, on any device, at any time.
  3. The initiator fills each signature into its slot, places the primary in signature, and submits. Changing any field other than the signature values between phases 1 and 3 invalidates every signature.
The reserved CLI commands use the existing cowboy transaction subcommand: assemble emits the bare transaction encoding, and submit decodes it with Transaction::read to EOF and constructs Submission::Transactions itself. The wasm encode_submission path emits the envelope for direct POST. Tooling and tests must keep these two artifacts apart. cosign MUST render the decoded instruction before signing. The digest is opaque in both modes, so a co-signer shown only the digest is signing blind. Clients holding a decoder, such as the CLI or the wasm codec in a browser, MUST show the decoded transaction; those that cannot MUST say so rather than present the digest alone. In native signature mode the wasm path uses signing_hash for phase 2, sign for the signature, and encode_submission for phase 3, and its existing exports gain the shared roster validation of CIP-40 §7.3. In CIP-40’s eip712 mode, phase 2 uses a different digest (§4.8). The indexer JSON already exposes the roster of landed and pending transactions, so a UI can show which slots are filled without new endpoints.

4.5 Canonicalization

CIP-40 §7.3 specifies the canonical form (strictly ascending, duplicate-free, bounded, disjoint from from) and the matching producer contract. This CIP relies on those guarantees: they make the §4.3 helper’s naive membership count correct and keep each authorization mapped to exactly one transaction identity.

4.6 Genesis

These rules apply from genesis, with no activation height or version gate; Transaction::verify() has no height parameter. CIP-40 §7.3 canonicalization and CIP-3 §2.5 metering ship with v3 at genesis. Actor-visible co_signers, code_hash, get_co_signers and the proposed CLI flow are reserved follow-up work, and their host and SDK semantics ship together.

4.7 Metering

CIP-3 §2.5 prices and bounds co-signature verification with four mechanisms. The first is a checked, non-sponsorable intrinsic charge for every signature slot, including the primary, which the sender pays along with execution fees for signed top-level calls; selecting co-signers authorizes no other account debit. The others are a pre-recovery structural minimum on cycles_limit, a per-block co-signer budget checked before any recovery, and ingress caps with a cross-connection peer key and a global work budget. CIP-3 is normative for all of them, and this CIP adds no metering rules.

4.8 Signature Modes

Under CIP-40 every signature slot carries its own algorithm and signing mode, so a hardware wallet using EIP-712 and a CLI using native signing MAY co-sign one transaction. build-unsigned freezes the entire roster and every descriptor, and every signer binds that exact object, including the other signers’ modes. cosign selects the signer by its declared address, rejects if absent, and uses that slot’s mode: native signing_hash(chain_identity) or the canonical EIP-712 digest. assemble fills signature values only and verifies the complete roster. It MUST NOT sort a signed roster, repair duplicates, infer a mode from a signature, or change public keys, modes or algorithms while attaching signatures. Changing any descriptor after signing invalidates the collected authorization. The transaction ID is CIP-40’s native, chain-bound, signature-independent digest for any mix of modes. At genesis every transaction slot uses secp256k1, and mode choice does not enable another signature algorithm.

5. Security Considerations

5.1 Cross-Frame Confused Deputy

co_signers is frame-scoped because of the confused-deputy case. If a callee could observe the transaction’s signer set, any actor that a quorum-authorized transaction called, at any depth, would appear authorized by that quorum directly. Suppose actor A holds a legitimate 3-of-5 roster and calls actor B for an unrelated reason, and B checks the same roster and concludes it was authorized. The quorum authorized the instruction against A and nothing downstream of it. Clearing co_signers on cross-actor entry makes the guarantee precise: a co-signature authorizes exactly the instruction it signed, in the frame that instruction entered. An actor that wants to propagate quorum authorization must pass it as call data, so B decides whether to trust A. The same reasoning applies within an actor, where a sender-based rule fails. call_actor dispatches a self-call (target equal to caller) straight to execute_current_handler without entering switch_to_callee. sender stays untouched, so in that nested frame sender still equals tx.from and a sender comparison would treat the quorum as visible. An actor whose public handler self-calls a privileged one would carry the quorum into it, although the co-signers authorized only the handler named in the instruction. The provenance rule (§4.2.4) and the clearing rule (§4.2.5) follow from this. The implementation must clear and restore the field around both nested entries: the cross-actor path (switch_to_callee / restore_call_snapshot) and the self-call dispatch.

5.2 Roster Changes Between Signing and Inclusion

The transaction binds no actor state, so a signature collected under one authorization policy can still be presented after that policy changes. A removed signer’s signature can keep counting. Lowering a threshold, widening a role, or raising a spend tier makes an already collected set sufficient for an operation nobody authorized at that strength. An actor whose authorization policy is mutable MUST therefore bind a policy commitment into the signed instruction, covering every mutable input to the decision, including roster, threshold, roles, and limits. Roster membership alone is insufficient. The actor rejects on mismatch, so any policy change invalidates every in-flight authorization instead of reinterpreting it. An actor whose policy is immutable after construction has no such obligation. The commitment MUST cover the actor’s code hash as well as its policy state. upgrade_self lets an actor replace its own code, so the same actor, handler, payload, and policy version can execute under changed authorization semantics. A hash commitment binds the code structurally. A monotonic version counter binds it only if every upgrade bumps the counter. The code_hash field (§4.2) and get_code_hash() (§4.3) let the actor check that requirement, since the existing context exposes actor_addr but nothing about the code running at it. The actor compares the committed hash against get_code_hash() and rejects on mismatch, without relying on any upgrade path. The protocol cannot enforce this by exposing co_signers. The commitment is the actor’s obligation, and a reference multisig actor MUST carry an acceptance test in which an in-flight transaction is rejected after a policy change that would otherwise have made it succeed.

5.3 Blind Co-Signing

A co-signer’s exposure is bounded by the instruction they signed, but only if they can see it. The authorization digest is opaque in both modes and tells a signer nothing. §4.4 therefore makes decode-before-sign a requirement of the signing surface, and CIP-40’s typed-data mode extends the same property to hardware wallets.

5.4 Submission Withholding

The primary signer can collect a quorum and never submit, or submit at a moment of its choosing. Someone must pay and sequence, so this control is inherent. The nonce binding in §4.1 invalidates the signatures when the primary’s nonce advances, and the actor’s policy-commitment check (§5.2) also bounds this control. Actors whose operations are timing-sensitive should bind a deadline height into the signed payload and reject late execution.

6. Rationale

CIP-41 exposes the signer set instead of building multisig into the protocol. A protocol-level multisig account type would fix one policy, k-of-n over a static roster, into consensus. Actors already own policy, and the policies people want (spend limits, per-operation thresholds, time locks, role-scoped signers, agent budgets under CIP-28) are actor logic. The protocol states which keys authorized a transaction, and the actor interprets that. Actors do not verify signatures themselves. Exposing secp256k1 recovery to the PVM would let an actor verify collected signatures, but every actor author would then reimplement replay protection, domain separation, and canonicalization. Consensus already does all three for transactions. CIP-37 draws the same line for gateway authentication. The Council path is unaffected. council_authorized operates on the transaction inside the execution engine, where the field is already available, and its roster is system state. The CIP-40 §7.3 duplicate-primary rule applies to both paths. The Council never depended on it, because its HashSet accumulation de-duplicates, but actor code counting {sender} ∪ co_signers does.

7. Acceptance Criteria

Client flow (the duplicate-primary and metering criteria live with their rules, in CIP-40 §7.3 and CIP-3 §2.5)
  • The authorized helper fails closed on degenerate thresholds: 0, negative, and greater than the roster size each return False regardless of the signer set.
  • A table test mutates each field of the canonical signing preimage except signature bytes in turn, between build-unsigned and assemble, once per signature mode. Every row fails assembly’s local verification, and in mode 1 the CIP-40 §7.3 forbidden fields (run_root, access_list, the origin_* fields) reject structurally in both modes. The rows are the preimage schema itself: chain_id, nonce, every instruction field, each of the nine gas parameters, from, access_list, every slot descriptor, nonce_lane, the sponsor address/terms/slot descriptor, delivery, the signer roster, origin_tx_hash / origin_remaining_cycles / origin_remaining_cells / origin_remaining_access, run_root, and metadata. Signature slots are excluded because assembly is supposed to fill them. The sponsor mutation rows become meaningful only once a sponsorship CIP admits sponsor = Some. Until then, CIP-40 §14’s typehash/struct-hash/digest vectors prove terms binding.
  • The initiator runs build-unsigned, each of the k signers runs cosign independently and offline, and the initiator runs assemble. The resulting transaction verifies locally and executes on a devnet.
  • assemble output decodes as a bare Transaction byte-equal to encode_transaction of the same object and feeds transaction submit unchanged. encode_submission output decodes as Submission::Transactions. One test per artifact proves the two are not interchangeable.
  • When the phase-1 object cannot be decoded and rendered, cosign fails closed and emits no signature.
  • A signature produced for a mode-0 slot fails when that slot changes to mode 1, and vice versa. A valid mixed-mode transaction succeeds, and changing either slot descriptor invalidates the other signer’s signature. Tests cover both the primary slot and an additional slot.
The following cases have Some provenance:
  • An actor called directly by a k-signer ExecuteActor observes Some of exactly the k−1 additional signers, ascending, excluding the sender.
  • A single-signer transaction yields Some([]), distinguishable at the SDK boundary from every None case below.
  • A deploy’s atomic init invocation observes Some of the deploying transaction’s co-signers.
  • A gateway submit, which is the gateway-signed ExecuteActor, yields Some([]) with the gateway account as sender.
The following cases have None provenance or restore earlier provenance: Every causally seedable derived-path test in this group starts from a transaction carrying a non-empty co-signer set (k ≥ 2), so an implementation that never populates the field cannot pass by accident. The tests must observe Some at the origin and None on the derived path. Gateway reads and default simulation have no originating transaction and are tested independently.
  • On a cross-call, the callee observes None, and the caller’s Some([...]) is restored on the success path and on the error path (callee raises, caller resumes).
  • On a self-call, the nested frame observes None, and the outer Some([...]) is restored on both success and error paths. A handler reachable only by self-call cannot see the quorum.
  • For TokenTransferFrom where from ≠ tx.from, both transfer hooks observe sender = from and co_signers = None.
  • On a synchronous event fire, the subscriber observes None, and the emitting frame’s Some([...]) is restored after the fire, on the success path and when the subscriber raises.
  • On an asynchronous event fire, the subscriber observes None even though the deferred transaction carries an origin_tx_hash naming the co-signed origin.
  • Deferred transactions, timer fires, mailbox deliveries, runner result callbacks, and gateway reads each yield None. Each entry path has its own test, seeded from a co-signed origin where the path admits one.
  • run_simulation with no injected context observes co_signers = None. Simulation accepts a caller-supplied HostContext, so this is a property of the default context; injected co_signers values are untrusted test fixtures with no authorization claim.
  • Simulation code_hash is the executed code’s on every simulation API. run_simulation, Simulator::new(code, options), and simulate::Network each override a default or injected code_hash with keccak256 of the code actually executed, so an injected context cannot make get_code_hash() misreport the running code. Simulator::new and simulate::Network currently copy options.context unchanged. Runnable tests cover both APIs.
  • The bridge maps None to Python None, Some([]) to [], and Some([a, b]) to [a, b] in that order. A missing key in an older runtime maps to None.
  • get_code_hash() returns the executing actor’s code hash in every frame: signed, nested, and non-signed.
  • get_code_hash() is a frame-entry snapshot. Within the handler that calls upgrade_self, it keeps returning the old hash after the call; a self-call made after the upgrade observes the new hash in its nested frame; and the first subsequent invocation observes the new hash.
  • Nested frames restore the outer frame’s code_hash snapshot on return, on both the success and the error path.
Existing consumers and release
  • Council authorization (council_authorized) and CreateAccount dual-signature behavior are unchanged, with continuity tests for both.
  • A zero-co-signer transaction is byte-identical on the wire to one produced without this CIP and behaves the same, because this CIP adds no field and changes no encoding.
  • CIP-40 §7.3 and CIP-3 §2.5 ship at the Friday v3 genesis. The actor-visible co-signer host and SDK APIs and the proposed CLI flow follow after genesis as additive APIs, not another wire version.
  • A reference multisig actor accompanying this CIP, using get_co_signers() and a policy commitment covering roster, threshold, limits, and get_code_hash(), rejects an in-flight authorization after each of two policy changes: a threshold reduction that would otherwise have made the collected set sufficient, and an upgrade_self that changes authorization semantics with policy state unchanged.