CIP-40: EIP-712 Signing & WalletConnect

​

1. Abstract

​

2. Motivation

1. Wallet reach without custody. Today the only way to sign a Cowboy transaction is to hold the raw private key in the signing context — the browser extension, the wasm SDK, or a server key. The wasm SDK explicitly documents this as a weakened threat model. EIP-712 mode moves signing into hardware wallets and audited wallet software that never reveal the key.
2. One testable core. Transaction v2, explicit chain identity, the connector, and the facade form one implementation slice that can be exercised end to end without activating route-authentication, payment-admission, governance, or storage redesigns.
3. Ecosystem leverage. Signing via the eip155 namespace lets dapps reuse wagmi/viem/AppKit and compatible wallets use an existing typed-data surface. A custom WalletConnect namespace would initially reach only Cowboy-specific wallets.
4. Standard wallet surface. EIP-712 gives the transaction a domain-separated typed-data digest that provider and WalletConnect APIs can request without exporting the user’s key.

​

3. Design Goals

• The signature determines the transaction. In both modes, every field of the executed object is bound under the signature, either directly in the digest or by a structural invariant enforced at verification. No field is a free variable.
• One digest identity. tx.digest(chain_identity) — the BMT leaf, receipt key, and dedup identity — is the tagged, chain-bound construction over canonical transaction bytes with signatures zeroed. Signature bytes never affect identity; signature_mode does, so otherwise-identical native and EIP-712 authorizations are distinct transactions.
• One construction. The transaction domain shape, encoding rules, field names, and verification context are defined once and consumed everywhere a transaction is signed or verified.
• Single implementation. Transaction EIP-712 machinery lives in cowboy-protocol-codec and is consumed by node and the wasm/FFI/SDK bindings. No hand-copied digest code.
• Fail closed. Unknown signature modes, unknown typed-data versions, and malformed signatures are rejected at decode or verification, at every admission point.
• Wallet-agnostic dapp surface. Dapps integrate via standard eip155 WalletConnect sessions and eth_signTypedData_v4. Cowboy-specific logic (building the typed data, encoding the submission) lives in a connector library, not in wallets.
• No display spoofing. Every field in a typed struct is verified against the object it authorizes. No derived, display-only fields.

​

4. Non-goals

• EVM execution or general eth_* compatibility. The Ethereum facade (§10) serves wallet onboarding only. eth_call, eth_sendTransaction, eth_sendRawTransaction, eth_getLogs, eth_estimateGas, and EVM semantics are permanently out of scope for it.
• A custom cowboy: WalletConnect namespace. CAIP-2 registration of a cowboy namespace adds no capability over eip155 + typed data and would fragment wallet support. Not pursued.
• Per-instruction expanded typed structs. The typed representation carries the instruction as canonical bytes (§7.2). Expanded, human-readable per-instruction structs (e.g. a dedicated Transfer type) are a candidate follow-up once the generic mode is proven; see §15.
• Mixed-mode multisig. signature_mode applies to a transaction as a whole; the primary signer and all additional signers use the same mode.
• Route-authentication and payment signing. Those designs remain separate drafts owned by their respective CIPs. This release adds no route/payment version gate, connector method, server readiness claim, or activation dependency.

​

5. Definitions

• Native mode. The non-EIP signature scheme: 65-byte recoverable secp256k1 over the tagged, chain-identity-bound §7.1 signing preimage with all signatures zeroed.
• EIP-712 mode. The scheme defined here: the same 65-byte recoverable secp256k1, but over an EIP-712 typed-data digest (keccak256(0x19 ‖ 0x01 ‖ domainSeparator ‖ structHash)).
• Signature mode. A u8 discriminant selecting the verification scheme: 0 = native, 1 = eip712. All other values are invalid.
• Chain identity. ChainIdentity { chain_id: u64, chain_instance_id: [u8; 32] }. chain_id names the network. chain_instance_id names one exact release-pinned genesis and is derived in §16 independently of block-header digest versions.
• Cowboy transaction domain. EIP712Domain(string name,string version,uint256 chainId,bytes32 salt), with salt = chain_instance_id. No verifyingContract is used because no contract is the transaction verification authority.
• Connector. The dapp-side library (@cowboyinc/connect) that builds typed data, requests signatures over WalletConnect or an injected provider, assembles signed transactions, and submits them to the REST RPC.
• Ethereum facade. The minimal JSON-RPC endpoint of §10.

​

6. Architecture

​

6.1 Signature schemes touched by this CIP

​

6.2 Signing-flow comparison

NATIVE (today, unchanged)                EIP-712 (this CIP)

dapp/SDK holds raw key                   dapp holds no key
  build canyon JSON                        build canyon JSON
  signing_hash(tx)                         eip712_typed_data(tx) ──► wallet
  sign(hash, privkey)                        (WalletConnect / injected)
  attach sig, mode=0                       wallet renders & signs typed data
  encode_submission ──► POST /submit       attach sig, mode=1
                                           encode_submission ──► POST /submit

​

6.3 EIP-712 encoding conventions

• Field names are snake_case, matching the canonical Rust field names. Type strings in this document are normative byte-for-byte; a wallet or SDK that re-derives a typehash from differently-cased names produces a different digest and fails verification.
• The transaction domain is the four-field form EIP712Domain(string name,string version,uint256 chainId,bytes32 salt). chainId and salt = chain_instance_id come from one closed GET /chain-info response and are treated as one identity. The domain version is the decimal transaction version (§7.2).
• bytes fields hash as keccak256(contents) per EIP-712; arrays hash as keccak256 of the concatenated encoded elements.
• Signatures are 65-byte r ‖ s ‖ v with v ∈ {0, 1} on the wire. EVM wallets emit v ∈ {27, 28} from eth_signTypedData_v4; normalizing to {0, 1} is the connector’s job (§11.2), and verifiers MUST reject any wire v ∉ {0, 1}. Verifiers MUST reject high-S signatures. Together these give each authorization exactly one valid wire encoding.

​

7. Transaction EIP-712 Mode

​

7.1 Wire change

chain_id, nonce, instruction,
cycles_limit, cells_limit,
max_fee_per_cycle, max_fee_per_cell,
max_priority_fee_per_cycle, max_priority_fee_per_cell,
from, access_list, metadata,
origin_tx_hash, origin_remaining_cycles, origin_remaining_cells,
signature_mode, fee_payer_override, signature, additional_signers

keccak256( b"cowboy.tx.v2" ‖ u64_be(chain_id) ‖ chain_instance_id(32) ‖ full v2 encoding with every signature field zeroed )

ChainIdentity { chain_id: u64, chain_instance_id: [u8; 32] }
Transaction::signing_hash(&self, identity: &ChainIdentity) -> Result<[u8; 32], TxIdentityError>
Transaction::digest(&self, identity: &ChainIdentity) -> Result<Digest, TxIdentityError>
TransactionVerificationContext { chain_identity: ChainIdentity }
Transaction::verify(&self, context: &TransactionVerificationContext) -> Result<(), TxVerifyError>

​

7.2 Typed representation

EIP712Domain(string name,string version,uint256 chainId,bytes32 salt)
  name    = "Cowboy Transaction"
  version = "2"                    (decimal CURRENT_TX_VERSION)
  chainId = <tx.chain_id>
  salt    = <chain_identity.chain_instance_id>

Transaction(uint8 kind,uint64 nonce,bytes instruction,uint64 cycles_limit,uint64 cells_limit,uint64 max_fee_per_cycle,uint64 max_fee_per_cell,uint64 max_priority_fee_per_cycle,uint64 max_priority_fee_per_cell,address from,bytes metadata,address[] additional_signers,bool has_fee_payer_override,address fee_payer_override)

• kind — the shell’s kind byte (§7.1), leading the struct as it leads the wire body. Always 0 for a signable transaction; binding it makes the §7.1 cross-kind replay rejection derivable from the typehash itself.
• instruction — the canonical codec encoding of the transaction’s Instruction, byte-identical to what Transaction::write emits for that field. This binds the full instruction payload (including nested actor calls, deploy code, amounts) without replicating the enum in EIP-712’s type system.
• has_fee_payer_override / fee_payer_override — the exact typed projection of CIP-28’s wire Option<Address>. None maps to false and the zero address. Some(address) maps to true and that address, including zero. The boolean binds the Option tag, so None and Some(ZERO) cannot share a digest.
• additional_signers — the transaction’s additional-signer addresses, in the transaction’s canonical (strictly ascending) order. Binding the signer set into the digest preserves the native mode’s property that no signer can be added or removed after signing.
• chain_id and chain_instance_id appear in the domain, not the struct.
• All other fields map one-to-one to the transaction fields of the same name.

​

7.3 Digest and verification

struct_hash = keccak256(typehash ‖ enc(kind) ‖ enc(nonce) ‖ keccak256(instruction_bytes) ‖ … ‖ keccak256(enc(additional_signers)) ‖ enc(has_fee_payer_override) ‖ enc(fee_payer_override))
digest      = keccak256(0x19 ‖ 0x01 ‖ domain_separator(chain_id, chain_instance_id) ‖ struct_hash)

• Deferred transactions (origin_tx_hash present) are structurally unsigned. They require signature_mode == 0, fee_payer_override == None, a zero primary signature, and an empty additional_signers list. These checks run before fee-payer resolution or state access.
• mode 0: verify against signing_hash(&context.chain_identity), the §7.1 tagged construction.
• mode 1: the following structural invariants are checked before any recovery, and violation is rejection:
  • access_list is None;
  • origin_tx_hash, origin_remaining_cycles, and origin_remaining_cells are all None.
  These invariants close the fields the typed struct does not carry: with them, every byte of the canonical encoding is either bound in the EIP-712 digest, fixed by invariant, or a signature slot — so a mode-1 signature determines the full transaction and its digest(), exactly as a native signature does. Verification then computes the EIP-712 digest above from the transaction’s own fields and runs the identical recovery path: primary signature must recover to from; each additional signer’s signature must recover to its stored address, all against the same digest (matching the native mode’s shared-digest multisig semantics).

• from MUST NOT appear in additional_signers. Previously unchecked: one key could fill both slots with valid signatures and pass verification, letting a single signer satisfy any consumer that counts 1 + additional_signers.len() as a quorum of two (the Council’s HashSet accumulation is immune only by accident of implementation). The check runs with the other structural invariants, before any recovery in either mode — after the CIP-3 §2.5 common preflight, before the mode digest is computed. Every transaction producer ships the matching contract and rejects a duplicate primary with an error rather than silently de-duplicating — a caller who listed the primary has a confused roster, and silent repair would mask it. The producer contract, per surface, with its concrete error API:

  Surface	Location	Contract
  Verifier	cowboy-protocol-codec/src/transaction.rs verify()	structural rejection before zero recovery calls
  Rust signer	cowboy-protocol-codec — sign_multi becomes sign_multi(…) -> Result<Self, TransactionSigningError> with variant DuplicatePrimary (it currently returns Self and silently sorts/de-duplicates); all call sites and golden fixtures migrate in the same change	Err(TransactionSigningError::DuplicatePrimary)
  Python SDK signer	python-sdk/cowboy/signing.py (today sorts and de-duplicates but never checks the primary)	raises DuplicatePrimarySignerError (a ValueError)
  CLI build/assemble (the CIP-41 §4.4 flow — the commands are defined there, not here)	node/cli/src/commands.rs	exits non-zero, emits no artifact
  wasm	cowboy-protocol-wasm/src/lib.rs — every export that accepts transaction JSON with a roster; note sign_transaction derives and overwrites from after parsing, so roster validation MUST run after the final from is known, not at parse time	throws JsError
  wasm-FFI	cowboy-protocol-wasm-ffi, same exports and the same post-derived-from ordering	error sentinel + last-error message

  Every table row carries one executable rejection test asserting its exact error: Rust Err(TransactionSigningError::DuplicatePrimary); Python DuplicatePrimarySignerError; CLI build-unsigned and assemble tested separately, each exiting non-zero with no artifact written; every roster-taking wasm export throwing JsError; every mirrored FFI export returning its packed-ABI sentinel (out_ptr == 0) and setting cpw_last_error(). The sign_transaction post-derived-from collision — parsed JSON clean, derived from colliding with a listed co-signer — is tested on both the wasm and FFI routes. Fixtures: a dedicated invalid corpus at cowboy-protocol/crates/cowboy-protocol-codec/fixtures/commonware-codec-invalid/, layout <case>/input.json + <case>/expected_error.txt — deliberately not the four-file shape of the success corpus at …/fixtures/commonware-codec/, whose harness (…/tests/golden_vectors.rs) assumes successful encodings; the invalid corpus is driven by a dedicated harness alongside it (…/tests/invalid_vectors.rs). Each duplicate-primary vector is otherwise valid — canonical ordering, valid mode structure, and cycles_limit ≥ TX_BASE_CYCLES + k × COSIGNER_VERIFY_CYCLES so the CIP-3 §2.5 minimum is not what rejects it; duplicate-primary is the sole violation, in mode 0 and mode 1, with an instrumented assertion that zero recovery calls occur. The valid deferred case (mode 0, empty additional_signers) remains accepted.

​

7.4 What a wallet displays

​

8. Deferred Route-Authentication Signing

​

9. Deferred Payment Signing

​

10. Ethereum Facade

{
  "chain_id": "26909",
  "network": "mesa",
  "chain_instance_id": "0x<64 lowercase hex digits>",
  "activation_manifest_digest": "0x<64 lowercase hex digits>",
  "transaction_version": 2,
  "transaction_signature_modes": ["native", "eip712"]
}

​

10.1 Endpoint

​

10.2 Balance scaling

​

10.3 Chain id uniqueness

​

11. WalletConnect Integration

​

11.1 Provider state machines

• Chains: eip155:<cowboy_chain_id> per network the dapp supports.
• Methods: eth_signTypedData_v4 (required). No transaction-sending methods are requested.
• Events: accountsChanged, chainChanged.

​

11.2 Connector

1. Validates every configured facade mirror and the release-pinned activation-manifest digest, then freezes the resulting ChainIdentity for the operation.
2. Builds canonical canyon JSON without routing any u64 through JavaScript number.
3. Calls the canonical wasm export with that exact ChainIdentity to produce the full typed object, then checks the returned domain identity and bound account.
4. Requests exactly eth_signTypedData_v4 for the approved account.
5. Accepts exactly 65 bytes, leaves v=0/1 unchanged, maps 27/28 to 0/1, rejects every other value, attaches mode 1, re-verifies locally through TransactionVerificationContext, encodes, and submits.

​

11.3 Cowboy wallets

​

11.4 SDK surface

​

12. Security Considerations

• Domain and instance separation. Native v2 and EIP-712 use structurally distinct prefixes, and both bind the same immutable ChainIdentity. Same-chain-ID/different-instance and cross-mode mutations therefore fail.
• Complete transaction binding. The typed struct plus §7.3 invariants cover every canonical field. Structural checks run in verify(context) before recovery at every admission point.
• Version and kind policy. The version/kind bytes are inside the native preimage; mode 1 binds version through its domain and kind through its message. Kind 1 may decode in the standalone codec but is invalid in every external and consensus path in this release.
• Option-tag binding. has_fee_payer_override binds the wire Option tag, preventing None from sharing a digest with Some(ZERO).
• Signature canonicality. Verifiers reject high-S signatures and every wire recovery id outside {0,1}; connectors normalize only provider 27/28.
• Signed bytes are the authorization. A stock wallet cannot interpret the opaque instruction. This release provides cryptographic interoperability, not a human-readable stock-wallet consent claim. Cowboy-native rendering is trusted only after exact decode→re-encode.
• Facade misuse. The facade refuses transaction-sending and EVM-execution methods. An Ethereum-format transaction is never interpreted as a Cowboy submission.
• Release identity. Connectors compare every configured /chain-info mirror to one pinned activation-manifest digest before building typed data. Chain/provider/session changes invalidate the operation.

​

13. Protocol Constants

​

14. Release Corpus

• input.json and chain_identity.json; the latter is exactly the closed object {"chain_id":"<canonical u64 decimal>","chain_instance_id":"0x<64 lowercase hex>"};
• exact preimage.bin, signing_hash.hex, and submission.bin;
• for mode 1, exact typed_data.json, domain_separator.hex, typehash.hex, struct_hash.hex, digest.hex, and signature.hex.

​

15. Rationale

• Generic bytes instruction over per-instruction typed structs. Expanded structs would make stock-wallet prompts legible, but each adds another reconstruction path for a large instruction enum. The generic form gives one verifier and full cryptographic binding. Stock-wallet blind signing remains an explicit product/security acceptance gate; a connector-rendered summary is not part of the signed authorization.
• Structural invariants over a catch-all hash field. The alternative to forbidding access_list/origin_* in mode 1 was binding them via an extra bytes32 tx_extra field. The invariant approach was chosen because the fields are semantically meaningless in a caller-signed, non-deferred transaction today — forbidding them costs nothing, keeps the typed struct legible, and the typehash-change mechanism handles their future activation.
• eip155 over a cowboy CAIP namespace. A native namespace would require wallet-specific support. eip155 + typed data reuses provider machinery in wallets that support the Cowboy chain; §11 does not claim universal compatibility. The facade answers only the pinned read-only subset and refuses transactional methods.
• Mode as a per-transaction field, not per-signer. Per-signer modes would let a MetaMask co-signer join a natively-signed multisig, at the cost of a mode vector in the encoding and a per-signer digest branch in verification. Deferred until a concrete need exists; the typed struct already binds the signer set, so adding per-signer modes later is a version bump, not a redesign.

​

16. Clean-Genesis Release Contract

activation_payload_hash = SHA-256(RFC 8785 JCS(activation_payload))
chain_instance_id       = Keccak-256(
                            ASCII("cowboy/chain-instance/v1")
                            ‖ raw_32_bytes(activation_payload_hash)
                          )
genesis_v2.parent       = raw_32_bytes(chain_instance_id)

genesis_config_sha256 = 0xb46e81a9bc58b918716cf5eb58c1a54c6de65668e63b2704a5b0ea24bae95075

JCS payload (258 UTF-8 bytes, no newline):
{"chain_id":"26909","format_version":1,"genesis_config_sha256":"0xb46e81a9bc58b918716cf5eb58c1a54c6de65668e63b2704a5b0ea24bae95075","genesis_nonce":"0x0101010101010101010101010101010101010101010101010101010101010101","network":"mesa","transaction_version":2}

activation_payload_hash = 0x2b6a1de5e097e9608fe5675646e4b586ac6a64d25e1e4e86f1fd1cf8240aa60a
chain_instance_id       = 0x9d5585bb2f3bc88cb10fb37e0bed53e7f482dacc29a194fba0873c8bf2871812

JCS final manifest (442 UTF-8 bytes, no newline):
{"activation_payload_hash":"0x2b6a1de5e097e9608fe5675646e4b586ac6a64d25e1e4e86f1fd1cf8240aa60a","chain_id":"26909","chain_instance_id":"0x9d5585bb2f3bc88cb10fb37e0bed53e7f482dacc29a194fba0873c8bf2871812","format_version":1,"genesis_config_sha256":"0xb46e81a9bc58b918716cf5eb58c1a54c6de65668e63b2704a5b0ea24bae95075","genesis_nonce":"0x0101010101010101010101010101010101010101010101010101010101010101","network":"mesa","transaction_version":2}

activation_manifest_digest = 0x14f29f8611696652b46c49660f0c6ed69e5708c4c1fdd3844d5c1f36dc4b0d99

1. land CIP-40, CIP-28’s reciprocal field/type mapping, CIP-33’s reciprocal decoder policy, the Technical Whitepaper §2/Appendix A mirror, the changelog, and the chain-ID registry artifact;
2. allocate a production (network, chain_id) row separately, derive one clean genesis, and start validators only after every node agrees on chain identity, manifest digest, and v2 codec;
3. deploy protocol codec, node, CLI, wasm/FFI, SDKs, connector, wallet, indexer, and explorer only after the §14 corpus passes at each real sign/verify/import boundary.