CIP-41: Multi-Signer Transaction Authorization

​

1. Abstract

​

2. Background

​

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 does and does not authorize, in which execution frames it is visible, and how it expires.
• No new cryptography, no new signature scheme, no change to transaction identity.
• Any client that can produce a secp256k1 signature over a 32-byte hash — CLI, wasm SDK, or an EVM hardware wallet under CIP-40 — can be a co-signer.

​

3.1 Non-Goals

• Actors as co-signers. Actors hold no keys and cannot produce a signature; an actor address can never appear in additional_signers. Actor quorums are expressed by approval accumulation across calls, where the callee observes the calling actor through sender, and are specified separately.
• Threshold or aggregate signatures. The set is k independent ECDSA signatures, not one aggregated signature. Cost and transaction size scale linearly.
• Protocol-level multisig accounts. Authorization policy lives in the actor, not in a system-level account type. The protocol supplies an authenticated signer set; it does not interpret it.
• Changing tx.digest(). Transaction identity is signature-independent and stays that way.

​

4. Specification

​

4.1 Signer Set Semantics

• tx.nonce is checked against tx.from’s account nonce alone (node/execution/src/execution/transaction.rs:143), and the nonce increment writes only that account (transaction.rs:886). Co-signers consume no nonce.
• A co-signer need not hold a balance, and need not exist as a funded account at all. An address that has never transacted is a valid co-signer. The co-signer role never causes a debit — F_sig is paid by tx.from alone — though a co-signing account may separately pay in an ordinary sponsorship role (as the target actor’s UseOwnerBalance owner, say), which is that role’s debit, not the co-signature’s.
• The primary signer controls submission: it chooses whether, when, and at which nonce to assemble. Once assembled, the transaction is a bearer artifact — it carries every signature it needs, so any party holding the bytes can broadcast it. Exclusive control ends at assembly, not at inclusion.

​

4.2 Host Context

pub struct HostContext {
    // ... existing fields ...
    /// Authenticated co-signers of the directly signed transaction that entered
    /// this frame: `Some(canonical ascending set, excluding sender)`.
    /// `None` in any frame not entered by a directly signed transaction.
    pub co_signers: Option<Vec<Bytes>>,
    /// Code hash of the executing actor. See §5.2.
    pub code_hash: [u8; 32],
}

1. Excludes the sender. The set contains additional_signers only. sender is already available and is tx.from when the set is Some. The full authorizing set is {sender} ∪ co_signers.
2. Canonical order preserved. Strictly ascending under byte-lexicographic comparison of the 20-byte big-endian address — the same total order Address: Ord provides and that the wire canonicalization is verified against. Actors may rely on the ordering and on the absence of duplicates.
3. Derived from the verified transaction. Populated 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. Populated by provenance, not by depth alone. The set is Some in exactly one case: the frame was entered by an actor-invoking instruction of a directly signed, non-deferred transaction — ExecuteActor, or the atomic init invocation of a deploy. init qualifies because the signed instruction contains the code, the handler, and the payload; the deployer authorized exactly that invocation. Every other frame is None. “Outermost frame” is not the predicate — several execution paths create a fresh, outermost PVM context without a signed instruction behind them, 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 — while a synchronous event fire is a nested entry (it runs through the same switch/restore machinery as call_actor) and is None by the nested-frame rule, not by fresh construction (run_simulation accepts a caller-injected HostContext, node/pvm/crates/pvm-runtime/src/simulate.rs:501; the default is None, and injected values are test fixtures carrying no authorization claim). A gateway submit is not on that list: the gateway builds and signs an ordinary non-deferred ExecuteActor transaction with its own key (gateway/crates/gateway-actor/src/lib.rs:383), so the actor observes Some([]) with the gateway as sender — signed provenance, no co-signers.
5. Cleared on every nested entry. A nested handler invocation sets None and restores the caller’s value on return. This covers the cross-actor path through switch_to_callee / restore_call_snapshot (node/execution/src/pvm_host.rs:2183) and the self-call path, which bypasses both and dispatches straight to execute_current_handler (pvm_host.rs:3154). A sender-based test does not work here: a self-call leaves sender untouched, so sender == tx.from still holds in the nested frame. See §5.1.

​

4.3 SDK Surface

def get_co_signers() -> list[bytes] | None:
    """Co-signers of the directly signed transaction that entered this frame,
    ascending, excluding get_sender(). None when this frame was not entered by a
    signed transaction — nested calls, deferred txs, timers, messages, event
    fires, transfer hooks, runner callbacks, gateway READS, default simulation contexts.
    Gateway SUBMITS are gateway-signed transactions and yield [] (see §4.2.4)."""

def get_code_hash() -> bytes:
    """32-byte code hash of the executing actor. Present in every frame;
    the oracle for the §5.2 policy commitment."""

def authorized(roster: ordered_set, threshold: int) -> bool:
    if threshold < 1 or threshold > len(roster):
        return False                      # degenerate policy: fail closed
    signers = get_co_signers()
    if signers is None:
        return False                      # not a signed-transaction frame
    count = 1 if get_sender() in roster else 0
    for addr in signers:                  # canonical: ascending, no dups, excludes sender
        if addr in roster:
            count += 1
    return count >= threshold

​

4.4 Client Co-Signing Flow

1. Build. The initiator constructs the complete transaction — instruction, chain_id, from, from’s next nonce, gas parameters, signature_mode, and additional_signers populated with every co-signer address in ascending order and EthSignature::ZERO in each slot. This object is the co-signing request.
2. Sign. Each signer independently computes the mode-selected digest over that object and signs it. The digest is identical for every signer including the primary. No signer needs the others’ signatures, and signatures may be produced in any order, on any device, at any time.
3. Assemble and submit. The initiator fills each signature into its slot, places the primary in signature, and submits. Any single field altered between phases 1 and 3 invalidates every signature.

​

4.5 Canonicalization

​

4.6 No Migration

​

4.7 Metering

​

4.8 Signature Modes

​

5. Security Considerations

​

5.1 Cross-Frame Confused Deputy

​

5.2 Roster Changes Between Signing and Inclusion

​

5.3 Blind Co-Signing

​

5.4 Submission Withholding

​

6. Rationale

​

7. Acceptance Criteria

• 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, run once per signature mode; every row fails assembly’s local verification, and in mode 1 the CIP-40 §7.3 forbidden fields (access_list, the origin_* fields) reject structurally. The row set is the preimage schema itself: chain_id, nonce, every instruction field, each of the six gas parameters, from, access_list, signature_mode, the signer roster, origin_tx_hash / origin_remaining_cycles / origin_remaining_cells, and metadata. (Signature slots are exactly the fields assembly is supposed to fill.)
• A transaction assembled by build-unsigned → cosign (×k, independently, offline) → assemble 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, proving the two are not interchangeable.
• cosign fails closed: when the phase-1 object cannot be decoded and rendered, no signature is emitted.
• A signature produced under signature_mode 0 fails verification when placed in a mode-1 transaction and vice versa — tested in the primary slot and in an additional slot.

• 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 — the gateway-signed ExecuteActor — yields Some([]) with the gateway account as sender.

• 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).
• Self-call: the nested frame observes None and the outer Some([...]) is restored, success and error paths both. A handler reachable only by self-call cannot see the quorum.
• TokenTransferFrom where from ≠ tx.from: both transfer hooks observe sender = from and co_signers = None.
• Synchronous event fire: the subscriber observes None; the emitting frame’s Some([...]) is restored after the fire, on the success path and when the subscriber raises.
• 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 — one test per entry path, each seeded from a co-signed origin where the path admits one.
• Default simulation yields None: run_simulation with no injected context observes co_signers = None (node/pvm/crates/pvm-runtime/src/simulate.rs:501 accepts a caller-supplied HostContext, so this is a property of the default context — injected co_signers values are untrusted test fixtures and carry no authorization claim).
• Simulation code_hash is the executed code’s, on every simulation API: run_simulation, and Simulator::new(code, options) / simulate::Network (which copy options.context unchanged today, node/pvm/crates/pvm-runtime/src/simulate.rs:612) each override default or injected code_hash with keccak256 of the code actually executed — an injected context cannot make get_code_hash() lie about the running code. Runnable tests for both APIs.
• Bridge mapping is exact: None → Python None; Some([]) → []; Some([a, b]) → [a, b] in that order; a missing key (older runtime) → 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 continues to return 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.

• Council authorization (council_authorized) and CreateAccount dual-signature behavior are unchanged — continuity tests for both.
• A zero-co-signer transaction is byte-identical on the wire to one produced without this CIP, and unchanged in behavior — this CIP adds no field and changes no encoding.
• One release carries every CIP-41 rule together with its CIP-40 §7.3 and CIP-3 §2.5 prerequisites; none is separately togglable.
• The reference multisig actor — cowboy/examples fixture 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 a policy change: a threshold reduction that would otherwise have made the collected set sufficient, and an upgrade_self that changes authorization semantics with policy state unchanged.

​

8. Implementation Notes

• HostContext and host_context_to_dict: canonical in node/pvm; the standalone pvm/ repo mirrors the PVM crates, and bronco syncs its shared crates from node/pvm (per its README). The synced crates pick the change up automatically — but sync is not the whole story: both repos also contain local HostContext literals outside the synced crates (bronco/crates/cli/src/host.rs, bronco/crates/wasm-sim/src/host.rs, pvm/examples/* constructing HostContext directly). The release includes a sweep of every HostContext construction site across consumers — enforced as a build gate, since a missed literal is a compile error once the fields are non-optional in the struct — hand-updating non-synced consumers to co_signers = None and an honest executed-code hash.
• cowboy_sdk (runtime.py, pvm_sys.py): canonical in node/pvm/Lib/cowboy_sdk; the PyPI package republishes a duplicated snapshot under node/pvm/Lib/pypi_build, refreshed by pypi_build/sync_sdk.py and guarded by cowboy_sdk/tests/test_pypi_build_sync.py — the release runs the sync script before rebuilding, since rebuilding alone ships the stale snapshot.
• The published python-sdk package is a separate codebase, not a synced mirror — but it is touched twice: its signer is a CIP-40 §7.3 producer, and its cowboy/runtime.py promises a local-dev interface identical to cowboy_sdk.runtime, so it implements both accessors with mock state (listed above).