Status: Draft
Type: Standards Track
Category: Core
Created: 2026-08-05
Relates-to: CIP-3 (fee preflight runs before either mode’s digest or recovery), CIP-33 (co-owner of the Transaction-v3 decoder; kind 1 remains decode-only and consensus-disabled here), CIP-41 (multi-signer authorization — relies on the §7.3 duplicate-primary rule)
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
Genesis uses Transaction v3, algorithm-tagged signature slots and stored signing keys, and signed objects bound to one chain instance. Nodes accept only version 3 and reject other versions with the §7.2 stable token. Actor-visible co-signers, passkey accounts and sponsorship semantics are reserved for later specifications.Background
Cowboy uses Ethereum’s cryptography: secp256k1 ECDSA, keccak256, and Ethereum-identical address derivation. Any Ethereum keypair is a valid Cowboy account. Stock Ethereum wallets still cannot produce Cowboy signatures, because Cowboy signs a raw keccak256 of the canonical codec encoding and stock wallets expose only prefixed signing methods (personal_sign, eth_signTypedData_v4).
Goal
This CIP specifies an EIP-712 typed-data signature mode alongside the native mode for caller-signed transactions.Transaction signing
Transaction carries algorithm-tagged signature slots. Each inner slot selects native or EIP-712 mode before signing, and every signer binds the entire roster and every slot descriptor. Transaction identity in both modes binds an immutable ChainIdentity and excludes signature bytes from digest(chain_identity).
With mode eip712, a compatible EVM wallet can sign Cowboy transactions through an injected provider or the standard WalletConnect eip155 namespace and eth_signTypedData_v4. Cowboy’s wallets use the same methods, recognize the Cowboy transaction domain, and render an instruction-aware approval screen in place of raw typed-data fields.
This CIP also specifies the Ethereum facade, a JSON-RPC endpoint (POST /eth) that implements the eth_* methods wallets need for wallet_addEthereumChain, balance display and nonce lookup. The facade provides no EVM compatibility and accepts no Ethereum transactions.
2. Motivation
- A Cowboy signer currently holds the raw private key in the signing context: the browser extension, the wasm SDK or a server. EIP-712 mode lets hardware wallets and audited wallet software sign without revealing the key.
- Transaction v3, explicit chain identity, the connector and the facade can be tested end to end without the route-authentication, payment-admission, governance or storage redesigns.
- The
eip155namespace lets dapps reuse wagmi, viem and AppKit, and lets wallets use their existing typed-data methods. A custom WalletConnect namespace would reach only Cowboy-specific wallets. - Provider and WalletConnect APIs can request a domain-separated EIP-712 digest without exporting the user’s key.
3. Design Goals
- In both modes, the signature binds every field of the executed object, either in the digest or through a structural invariant that verification enforces.
tx.digest(chain_identity)identifies the BMT leaf, receipt key and deduplication record. It is the tagged, chain-bound hash of the canonical transaction bytes with signatures zeroed. Signature bytes never affect identity. Each slot’s algorithm, mode and public key do, so otherwise-identical native and EIP-712 authorizations are distinct transactions.- The transaction domain shape, encoding rules, field names and verification context are defined once and used wherever a transaction is signed or verified.
cowboy-protocol-codecholds the transaction EIP-712 code, and the node and the wasm, FFI and SDK bindings call it rather than copying digest code.- Decode or verification rejects unknown signature modes, unknown typed-data versions and malformed signatures at every admission point.
- Dapps use standard
eip155WalletConnect sessions andeth_signTypedData_v4. A connector library builds the typed data and encodes the submission, so wallets need no Cowboy-specific logic. - Verification checks every typed-struct field against the object it authorizes. Typed structs carry no derived or display-only fields.
4. Non-goals
- This CIP provides no EVM execution or general
eth_*compatibility. The Ethereum facade (§10) serves wallet onboarding only, andeth_call,eth_sendTransaction,eth_sendRawTransaction,eth_getLogs,eth_estimateGasand EVM semantics are permanently out of its scope. - This CIP defines no custom
cowboy:WalletConnect namespace. A CAIP-2cowboynamespace would add no capability overeip155with typed data and would fragment wallet support. - The typed representation carries the instruction as canonical bytes (§7.2) and defines no per-instruction structs. Human-readable per-instruction structs, such as a dedicated
Transfertype, are a candidate follow-up (§15). - Transaction slots accept only secp256k1 at genesis. Algorithm
5(P-256 WebAuthn assertion, §7.5) has a registered slot layout and digest rule, so a later upgrade can accept passkey signers without changing the wire, the digest rule or the typed data. No surface accepts it at genesis. This CIP does not address post-quantum signatures. - Route-authentication and payment signing belong to their own CIPs. This release adds no route or payment version gate, connector method, server readiness claim or activation dependency for them.
5. Definitions
- Native mode. A 65-byte recoverable secp256k1 signature over the tagged, chain-identity-bound §7.1 signing preimage with all signatures zeroed.
- EIP-712 mode. A 65-byte recoverable secp256k1 signature over an EIP-712 typed-data digest (
keccak256(0x19 ‖ 0x01 ‖ domainSeparator ‖ structHash)). - Signature mode. A per-slot
u8discriminant selecting the signing digest:0= native,1= eip712. All other values are invalid. - Chain identity.
ChainIdentity { chain_id: u64, chain_instance_id: [u8; 32] }.chain_idnames the network.chain_instance_idnames 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), withsalt = chain_instance_id. The domain omitsverifyingContractbecause no contract verifies transactions. - 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
The
0x19 0x01 prefix separates EIP-712 digests from the native transaction digest. The EIP-712 domain name, version, chain ID and salt separate them further, so one logical transaction on two chain instances has different signing digests.
This CIP does not change other authorization schemes or declare them release-ready. It sets one rule for all of them: no native signing preimage may begin with the byte 0x19. ASCII domain tags satisfy the rule, and schemes that start with a version byte avoid the value 0x19.
6.2 Signing-flow comparison
6.3 EIP-712 encoding conventions
Cowboy typed structs use standard EIP-712 encoding with these conventions:- Field names are snake_case and match the canonical Rust field names. Type strings in this document are normative byte for byte. A wallet or SDK that derives a typehash from differently cased names gets a different digest and fails verification.
- The transaction domain has four fields:
EIP712Domain(string name,string version,uint256 chainId,bytes32 salt).chainIdandsalt = chain_instance_idcome from one closedGET /chain-inforesponse and form one identity. The domainversionis the decimal transaction version (§7.2). - A
bytesfield hashes askeccak256(contents)per EIP-712. An array hashes askeccak256of its concatenated encoded elements. - Signatures are 65-byte
r ‖ s ‖ vwithv ∈ {0, 1}on the wire. EVM wallets returnv ∈ {27, 28}frometh_signTypedData_v4, and the connector normalizes it to{0, 1}(§11.2). Verifiers MUST reject any wirev ∉ {0, 1}. Verifiers MUST reject high-S signatures. Each authorization therefore has exactly one valid wire encoding.
7. Transaction EIP-712 Mode
7.1 Wire change
At genesis,CURRENT_TX_VERSION = 3. Nodes accept only version 3 and have no
decoder, activation height or fallback for any other version.
The closed framing is u8 version=3 ‖ u8 kind ‖ body. kind=0 carries the
transaction body below (including engine-produced deferred transactions):
UInt. The two Access fee fields are u128, and the
other fee and limit fields and nonce_lane are u64. Inside their Option,
origin_remaining_cycles, origin_remaining_cells and origin_remaining_access
use fixed eight-byte big-endian u64, not UInt. run_root is an unconditional
Option<Digest> (32 digest bytes when Some), immediately after
origin_remaining_access; it is bound by the native digest and MUST be None on
external transactions. delivery is one byte with this closed producer table:
Tags 7–255 reject at decode. Execution asserts that the tag matches the authenticated
producer path, so the guest cannot select it. Token transfer hooks run synchronously
and need no tag of their own, and their staged children use the ordinary producer
paths. Every deferred transaction carries the real chain ID.
signature is the primary account’s AccountSignature. additional_signers is
a bounded vector of (Address, AccountSignature), strictly ascending by address,
that excludes the primary address. The CIP-49 AccountSignature encoding is:
AccountAuth row uses policy_revision=0, entries=[(0, slot)]. A stored
policy requires its current revision and exactly its threshold of authorized
indexed keys. A transaction holds at most 32 slots in total, separately from the
bound of 16 additional accounts.
The following inner slot encoding is normative:
Option encodes as exactly 0x00 for None, or 0x01 followed by its value. Vectors use
the canonical commonware length prefix and raw bytes. Public-key bytes are bounded
by MAX_SIGNATURE_PUBLIC_KEY_BYTES = 4096 and signature bytes by
MAX_SIGNATURE_BYTES = 65536. The decoder checks each length prefix before
allocating or reading its payload. These ceilings bound the envelope only. The
closed support matrix below sets the lengths each algorithm permits.
The implemented P-256 and P-384 object prices are 25,400 and 102,300 Cycles
respectively. They are not a ratified calibration: their measurements included
trusted-key validation, and replacement prices await an accepted quiet-window
measurement. This CIP sets no price.
CIP-6 §12.8 shares this signature algorithm registry. The registry defines IDs,
surface support and byte lengths, and CIP-3 §2.5 owns the verification-cycle
schedule. IDs 0 and 6–255 are unassigned. Each surface rejects registered but
unsupported algorithms and unknown algorithms, with no fallback to another
algorithm. Signature algorithm IDs are a separate namespace from CIP-9
wrapping-suite IDs. Modes are
0 native and 1 EIP-712, and unknown modes
reject at decode. The slot codec checks shape only. A 65-byte zero placeholder
has valid shape for unsigned construction but cannot authorize a caller-signed
transaction. Verification enforces recovery-ID and low-S rules before recovery.
v3 has no fee_payer_override field.
nonce_lane MUST equal zero at genesis. sponsor is Option<Sponsor>, with:
delivery. Some encodes
address[20] ‖ UInt(max_fee) ‖ UInt(expires_at_height) ‖ SignatureSlot in that
order. Both terms use minimal UInt. max_fee uses the same u128 encoding as
max_fee_per_access, and the expiry is u64.
At genesis, sponsor MUST be None. Every admission and consensus path rejects
Some before hashing, recovery, fee resolution or state writes. This CIP fixes
only the shape. A later sponsorship CIP defines authorization, escrow, refund and
what is sponsorable. Every non-default reserved field rejects at the same point.
Transaction JSON is a closed v3 object with one member per field, and unknown
members reject. The sponsor member is "sponsor": null or the following closed
object, with the terms flattened:
{"algorithm":1,"mode":0|1,"public_key":null,"signature":"0x<130 lowercase hex>"}.
An address-derived primary signature is
{"policy_revision":0,"entries":[[0,<SignatureSlot JSON>]]}. Each additional signer
pairs an address with the same account-signature object. This codec DTO uses JSON
numbers for the revision and index, and §7.4’s decimal strings apply only to typed
data. A bare slot is not an account signature.
kind=1 is the CIP-33 TradingPostSpawn body and carries no signature fields. The standalone shared decoder accepts it only to reproduce the codec corpus exactly. Every external RPC/mempool submission and every consensus block-validation, import, replay, and execution entry point MUST reject a decoded kind=1 before lane selection, digest use, recovery, state access, event, or execution. A block that contains it is invalid, including one a Byzantine validator proposes directly. This release has no kind-1 producer or capability advertisement and does not activate the CIP-33 spawn path. The outer discriminant rejects every unknown kind and every outer version other than 3.
CIP-40 owns the outer shell, the kind-0 body, ChainIdentity, the transaction digest
and the disabled-kind policy. CIP-33 owns the exact kind-1 body and any future activation that changes
the disabled policy. CIP-33 §2.6.4 mirrors this contract and pins the fixed-width kind-1 body, which
does not use kind 0’s minimal-UInt scalar encoding.
For kind 0, the digest and native signing preimage are exactly:
chain_id names the network and chain_instance_id names the exact genesis. Zeroing covers signature bytes only. The preimage keeps account policy revisions, entry counts and key indices, slot algorithms, modes, public-key Option tags and bytes, signature lengths (except for algorithm 5, below), reserved fields, delivery, the sponsor Option tag, the sponsor address and both terms, and signer addresses. Identity therefore depends on the authorization mode but not on signature bytes. The sponsor slot’s descriptor (algorithm, mode, public-key presence and bytes) is bound, and its signature bytes are zeroed like those of additional_signers.
Zeroing in place keeps a signature’s length, which works only where the algorithm
fixes that length (algorithm 1: 65 bytes). A WebAuthn authenticator decides the
assertion’s length when it answers, and it answers a challenge taken from this
hash. A slot whose algorithm is 5 therefore enters the preimage with its
signature as the empty vector (length prefix 0, no bytes), and keeps its
algorithm, mode and public key. This rule follows the algorithm wherever the slot
appears: primary, additional signers and the reserved sponsor. Slots of every
other algorithm are zeroed in place.
The codec exposes no v3 digest API that omits the chain identity:
self.chain_id == identity.chain_id. Block construction, block verification and replay, mempool admission, execution, RPC, CLI, wasm, FFI and every transaction producer pass the same immutable ChainIdentity. The CIP-3 preflight runs before either mode’s digest computation. All native and EIP-712 vectors use the v3 encoding.
7.2 Typed representation
The typed representation of the §7.1 transaction uses this domain:version string MUST equal the decimal rendering of CURRENT_TX_VERSION, so a new transaction version changes the mode-1 domain separator and invalidates every mode-1 signature across the boundary. The mode-1 digest also binds the shell’s kind as a struct field. Only kind 0 can be signed, because kind 1 has no signature fields.
The primary type and its dependencies have these exact EIP-712 encodeType
strings:
Transaction; its custom-type dependencies are Signer,
SignerSlot and Sponsor, appended in that alphabetical order under EIP-712
encodeType. Each nested struct encodes as its hashStruct. Each account’s
slots array hashes its ordered SignerSlot hashStruct values, and
additional_signers hashes the concatenation of its element hashStruct values
in canonical address order. An empty array hashes the empty byte string.
primarycontainsfrom, itspolicy_revisionand its orderedslotsarray. EachSignerSlotbindskey_indexand the inner slot descriptor, and each additional signer has the same account descriptor. Signature bytes are omitted because the admitted algorithm fixes their length. Algorithm5has no mode-1 form. Every signer binds all policy revisions, entry indices and slot descriptors, including slots that use the other mode. Modes MUST be frozen before any signing.kindis always zero.instructionis its complete canonical codec encoding, including DeployActor’s optional shard field.metadatais the exact byte vector. Each dynamicbytesmember uses the ordinary EIP-712 content hash.- A None public key maps to
has_public_key=false, public_key=0x. Some(empty) would map to the distincttrue, 0x, and secp256k1 rejects both Some forms. sponsor=Nonemaps tohas_sponsor=falseand the exact absent descriptorSponsor(ZERO_ADDRESS,0,0,0,0,false,0x). This descriptor exists only in the typed projection and does not decode as an algorithm-zero slot. Some would map tohas_sponsor=truewith its address,max_fee,expires_at_heightand slot descriptor, excluding signature bytes. Genesis rejects Some before producing or verifying typed data.chain_idandchain_instance_idare in the domain. Limits and fee fields map one to one as lossless integers, so Access fees stayuint128.nonce_lane=0anddelivery=0are bound although external transactions fix them.run_root,access_listand all fourorigin_*fields MUST be None in any external signed transaction, independently of its slots’ modes.
Stable verification and decode errors
The following table is the single normative token registry.TxVerifyError::Display
returns exactly the listed token, with no prefix or suffix. Parameters in
parentheses use canonical unsigned decimal without spaces, and field is the exact
snake_case field name. Slot indices count entries in wire order: the primary
account’s entries first, then each additional_signers account’s, each in
key-index order. Signer indices count accounts, with the primary at zero. A
decode error has the same token wherever it occurs. Diagnostic context travels
separately and never enters a fixture token. A fixture file adds exactly one LF.
Reserved field names are
nonce_lane, sponsor, access_list and, for external
transactions, run_root. Origin-field and delivery-class violations use
TxDeliveryOriginMismatch. The decoder checks each length prefix against its
bound before reading or allocating the payload. An excessive additional-signer
count uses TxRosterTooLarge, and other ceiling violations use TxOversize.
Decode proceeds in wire order and reports the first failure, and version and kind
reject before the body decodes. Verification rejects a registered slot that
passes shape decode but is unsupported for transactions with TxSlotPolicy(slot).
Verification finishes each whole-roster pass before starting the next, in this
order: roster, v, low-S, CIP-3 signature preflight, identity-access preflight,
hashes, recoveries. The roster pass checks its bound, then duplicate primary,
then duplicate co-signers, then strict ascending order. A bad recovery ID in the
last slot therefore beats high-S in the first, and a duplicate primary beats
either. Noncanonical scalars, including an all-zero caller signature, fail in the
low-S pass. Deferred placeholders skip this pass because the deferred invariants
cover them. Every failure before recovery performs zero recoveries. A signature
for a different instance with the same chain ID fails only after hashing and
recovery, with TxSignerMismatch(slot), and changes no state.
CIP-3 charges every inner slot, not one recovery per account. Before hashing or recovery, the identity-access
preflight requires access_limit >= ceil((3 + 4k) × 1,350,358 / 1,000,000) for
k additional accounts: 5 for a primary alone, 10 with one additional signer,
and 91 with sixteen. Each signer’s extra read is its AccountAuth policy. An
estimate probe with one address-derived signer therefore declares 5 accesses,
and its separately signed final transaction must cover the complete estimated
work.
Client-signing inspection uses schema 14. Approval consumers must understand
the account, revision and index descriptors before signing. The companion CIP-43
tail-floor amendment specifies the per-transaction lane-tail floor and owns its
dispatch-row rules.
These tokens add no StructuredError codes. A structural failure at ingress
refuses admission, and one in consensus invalidates the block. The execution
!verify path keeps code 1001 and its constant what/why strings.
7.3 Digest and verification
RPC, mempool, block verification, import, replay and execution all callTransaction::verify(context). It performs these steps in order. Steps 2–4 apply
only to caller-signed transactions, and the complete roster preflight finishes
before any slot is recovered:
- Validate version/kind, trusted chain identity, all size bounds, reserved defaults, delivery/origin invariants and every slot’s algorithm/mode/shape.
- In separate whole-roster passes, validate the signer roster (bounded, no
duplicate primary or co-signers, strictly ascending), then every recovery ID
in
{0,1}, then every signature’s low-S/scalar canonicality, then CIP-3 §2.5 preflight, then the identity-access floor. §7.2 defines the exact order and tokens. - Compute the §7.1 native hash and, if needed, EIP-712
keccak256(0x19 ‖ 0x01 ‖ domain_separator ‖ hashStruct(Transaction)). - Recover each signer from its slot’s selected digest. At revision zero the
recovered address must equal the declared address. Otherwise verification
returns the recovered indexed keys and the signed policy revision in
VerifiedSigners, and admission and execution separately require those keys to satisfy the account’s currentAccountAuthpolicy, so a signature under a stale policy grants nothing. High-S signatures reject.
verify(context) result alone does not admit them to a block. The
enclosing block/execution path MUST also prove the origin receipt binding
below. Deferred transactions require all four origin_* fields, nonce=0,
nonce_lane=0, sponsor=None, a native secp256k1
primary account signature at revision zero with one index-zero slot, no public
key and 65 zero signature bytes, and no
additional signers. access_list is None. All fee and tip fields are zero, and each of the three limits is at
most its origin allowance. delivery must be the authenticated producer’s
nonzero kind. External ingress rejects deferred transactions outright, and
block/execution validation authenticates their exact digest against the origin
receipt.
A pre-verified flag or cache may reuse only a successful cryptographic validation
of the exact transaction and chain identity. Stateful wallet, actor, nonce and
balance checks still run against the current execution view.
For caller-signed transactions, Transaction::verify checks every primary and
additional signature for a wire recovery id in {0,1} and for low-S before any
recovery call, so recovery ids 2 and 3 never reach recovery. It then
recovers the signer address, and recovery also rejects high-S. Both modes keep
the shared structural checks (MAX_ADDITIONAL_SIGNERS, strict signer ordering)
and add one:
-
fromMUST NOT appear inadditional_signers. Without this check, one key could fill both slots and let a single signer satisfy any consumer that counts1 + additional_signers.len()as a quorum of two. The check runs with the other structural invariants, before recovery, the low-S pass and the CIP-3 §2.5 preflight in either mode. Every transaction producer rejects a duplicate primary with an error and does not de-duplicate it, because a caller who listed the primary twice has a confused roster that silent repair would hide. Every producer also rejects duplicate co-signers with an error. Rust returnsTransactionSigningError::DuplicateCosigner; Python raisesDuplicateCosignerError; wasm/FFI use their normal error channels. Each producer reports rejection through its error API:Each implemented table row has an executable rejection test that asserts its exact error: RustErr(TransactionSigningError::DuplicatePrimary); PythonDuplicatePrimarySignerError; the reserved CLIbuild-unsignedandassembleflow will require separate no-artifact tests when implemented; every roster-taking wasm export throwingJsError; every mirrored FFI export returning its packed-ABI sentinel (out_ptr == 0) and settingcpw_last_error(). Thesign_transactionkey/frommismatch and duplicate-roster rejection are tested on both the wasm and FFI routes. A dedicated harness runs the invalid corpus, whose layout is<case>/input.json+<case>/expected_error.txt, separate from the success corpus’s four-file shape. Each duplicate-primary vector is otherwise valid, with canonical ordering, valid mode structure, andcycles_limit ≥ TX_BASE_CYCLES + (k + 1) × COSIGNER_VERIFY_CYCLESfor the genesis secp256k1-only slots (primary pluskadditional slots), so the CIP-3 §2.5 minimum cannot reject it. Duplicate-primary is the sole violation, in mode 0 and mode 1. Instrumentation asserts zero recovery calls. The valid deferred case (mode 0, emptyadditional_signers) remains accepted.
digest(chain_identity), is the §7.1 tagged hash of the domain tag, chain identity and signature-zeroed v3 encoding. Two transactions that differ only in a slot descriptor have different hashes and are distinct authorizations.
7.4 What a wallet displays
The codec emitstyped_data.json as RFC-8785 JCS UTF-8 plus one file-framing LF.
All integer values, including kind, policy revision, key index, algorithm, mode,
nonce and domain chainId,
are canonical unsigned decimal strings. Bytes and addresses are lowercase 0x
hex, with exact widths for fixed fields, and booleans stay JSON booleans. types
includes EIP712Domain, Signer, SignerSlot, Sponsor and Transaction, with each field
array in the exact §7.2 type-string order. No integer passes through a floating
point number. Callers pass exactly this object to eth_signTypedData_v4.
A stock EVM wallet shows the domain name (“Cowboy Transaction”), the chain id and the struct fields. nonce, the fee fields and from are readable, but instruction and metadata appear as hex. The instruction carries the recipient, amount or deploy payload, so mode 1 in a wallet without Cowboy support is blind signing with a domain tag. The user knows which bytes they signed but cannot read what they do. Every displayed field is bound to the signature, and only a Cowboy-aware signer can show the instruction.
Cowboy’s own wallets recognize the domain, decode instruction with the canonical codec, and show a native approval screen with the transfer amount and recipient, actor and handler, or deploy summary. Connectors SHOULD render the decoded instruction alongside the wallet prompt, and documentation SHOULD steer high-value signing toward Cowboy-aware wallets until expanded per-instruction typed structs land (§15).
7.5 Registered passkey slot (algorithm 5)
This section fixes the passkey slot so a later release can accept passkey signers without a wire, digest or typed-data change. At genesis every surface rejects algorithm5 as registered but unsupported, after shape validation and
before any digest use or verification, with zero recovery calls.
An algorithm-5 slot’s mode MUST be 0; mode 1 with algorithm 5 rejects at decode.
public_key MUST be Some with exactly 33 bytes, the compressed SEC1 P-256 point
(the §7.7 form). signature is the canonical encoding of:
authenticator_data is exactly rpIdHash[32] ‖ flags[1] ‖ signCount[4]. In
flags, user present (bit 0) and user verified (bit 2) MUST be set; attested
credential data (bit 6) and extension data (bit 7) MUST be clear, because an
assertion carries no attested credential and this registration accepts no
extensions; the reserved bits 1 and 5 MUST be clear. Backup state (bit 4) MUST
NOT be set unless backup eligibility (bit 3) is set. Both backup states are
otherwise accepted, so synced passkeys work. A later CIP that accepts extensions
must first define their exact parsing and bounds.
When a later release accepts algorithm 5, verification follows the §7.3 order:
- The structural pass (§7.3 step 1) checks the slot layout, every length bound and the flag rules above.
- In the whole-roster passes (§7.3 step 2), algorithm
5has no recovery ID and is exempt from the recovery-ID pass. In the scalar pass,randsare nonzero and below the P-256 group order, andsis at most half of it (low-S). Authenticators return DER signatures that may be high-S, so the signer converts them to fixed-widthr ‖ sand normalizessbefore submitting. The resource preflights still run before any hashing. - After preflight and digest computation, and before any slot is recovered or
verified, the client-data pass checks every algorithm-
5slot in the roster. A failing slot costs zero recovery calls:client_data_jsonparses as one strict UTF-8 JSON object with no duplicate keys. Itstypeis exactly"webauthn.get"; itschallengeis exactly the unpadded base64url encoding of this transaction’s §7.1 signing hash (43 characters);crossOriginis absent orfalse; andoriginis exactly one member of the network’s pinned allowed-origin set (§17). The origin check is needed because, with only the relying-party hash, any page under the relying-party domain, such as a user-content subdomain, could ask a person’s passkey to sign a transaction presented as a login. A native application origin is allowed only if listed.rpIdHashequalsSHA-256(rp_id)for the network’s registered relying-party ID (§17). The signature counter is ignored, because synced passkeys report zero.
- In place of recovery, the verifier checks the ECDSA signature over
SHA-256(authenticator_data ‖ SHA-256(client_data_json))withpublic_key.
5 slot can satisfy only a
CIP-49 policy. It authorizes its account when the account’s current policy holds
the slot’s public key, as a §7.7 algorithm-5 SigningPublicKey, at the entry’s
key index. An address-derived account cannot use it. Accepting algorithm 5
therefore also replaces §7.3’s recovery step with per-algorithm verification for
these slots and adds algorithm 5 to TX_SLOT_POLICY. It also needs a CIP-49
key-proof form for keys that cannot sign under SECP256K1_OBJECT_POLICY, likely
an algorithm-5 assertion whose challenge is the key-proof object’s signing
hash, carried in the existing SignatureSlot proof fields. This CIP does not
specify that form. CIP-3 assigns the verification-cycle price when algorithm 5
is accepted.
7.6 Signed objects
Every consensus-verified Cowboy signed object uses the sharedSignatureSlot,
wrapped in an AccountSignature when an account gives the authorization. Rows 18
and 19 are the two exceptions to native preimage framing, described below. For
native objects, the codec owns the single construction:
\0, \x01, \x02 and \x03 denote
single bytes. Existing domain labels keep their version even when the layout
changes, and new domains use cowboy/<surface>/<object>/v1. Every listed native
row binds the verifier’s trusted ChainIdentity through this framing. No API
hashes without an identity, and no request supplies its own trusted identity. Any
chain ID inside a body must equal that identity. Every domain is shorter than
0x1900 bytes, so native signing bytes never begin with 0x19.
For account-signed objects (CIP-49), rows 1 (RAS owner delegation), 7 (workload
owner certificate), 9 (both read-transfer signatures), 19 (session/per-call
vouchers), 22 (PaymentIntent), 24 (account Intent), and 26 (TokenPermit’s
instruction-carried authorization) use AccountSignature, applying the row’s
slot policy to every entry. account_object_body appends
account[20] ‖ u64be(policy_revision) to each of these rows’ table body before
object_signing_preimage is built. The 20 bytes are the raw account address,
even when the body already contains an address string, and the revision is
fixed-width BE here rather than its wire UInt. All entries sign the same object
digest and must satisfy the trusted account policy at its current revision.
Unsigned storage signing DTOs carry policy_revision as a decimal string, and
signed DTOs carry it inside signature: AccountSignature.
Other rows keep their dedicated key or address slot authorization. These include
read-channel vouchers (row 8), read-channel requests, CBSS committee signatures
and relay or TEE signatures. A secp256k1 slot alone grants no account-policy
authority.
The body is the object’s canonical signing-field projection, not its signed
wire record. It excludes the signature being produced and keeps every other
signed field in its established order and encoding. The framing above replaces
any leading domain and standalone chain or network prefix, with no nested inner
preimage or hash. Identity fields inside an encoded record stay in its body and
must match the trusted identity. Tagged keys in a signing projection use §7.7’s
canonical form. Existing version fields do not change, and a newly versioned
record starts at 1. Nested signed records keep their signatures where the
enclosing format already binds them. The table gives each projection and its
owning layout, and encode(X) means that layout’s canonical binary encoder,
never JSON or bincode.
If an object’s identity or storage key hashes its full encoding, its inline-key
policy MUST be Required or Forbidden, never Optional, so each authorized key has
one accepted encoding. Rows 3–6 forbid inline keys and verify against the trusted
key the verifier selects.
The policy names are normative:
RAS_RELAY_SLOT_POLICY applies to rows 3–5, VOLUME_ESCROW_SLOT_POLICY to row 6,
and CAE_SERVICE_SIGNATURE_POLICY to row 17.
Below, S, E, T and 712 abbreviate respectively
SECP256K1_OBJECT_POLICY, ED25519_OBJECT_POLICY, TEE_QUOTE_POLICY and
SECP256K1_EIP712_OBJECT_POLICY. Secp256k1 signs the keccak256 of the framed
bytes. Ed25519 signs the bytes directly and verifies with verify_strict. TEE
P-256 and P-384 use standard ECDSA with SHA-256 and SHA-384 respectively over
those bytes, with raw low-S signatures and never DER or a keccak prehash.
Verification checks policy, recovery ID and scalar canonicality before
cryptography. An inline key never replaces the authorized signer the verifier
supplies.
Where a row’s inline-key requirement differs from its policy constant’s public-key rule, the row’s column governs and the owning CIP’s decoder MUST enforce it: row 29 forbids an inline key (public_key is null).
Row 30’s domain includes the terminal NUL byte. Verification uses the trusted chain
identity and channel terms; the payer signs in Native mode without an inline key.
For the anchor exception (row 18), the digest is exactly the packed CIP-25 layout:
src is u64be(src_chain_id) followed by src_chain_instance_id[32] for a
Cowboy source and no instance for an Ethereum source. dest_binding is
u64be(chain_id) ‖ chain_instance_id[32] for Cowboy or uint256be(block.chainid)
for EVM. The kind bytes are 0 = Cowboy, 1 = Ethereum/EVM, matching
CHAIN_KIND_COWBOY and CHAIN_KIND_ETHEREUM in the core runner dispatcher, so
each layout is unambiguous. Values 2–255 are unassigned and reject. An Ethereum
source always appends state_root, and a Cowboy source never does. The layout
has no parent_hash. Registry or constructor configuration pins the source
instance, and the verifier never trusts the instance in the submitted anchor. On
Cowboy the signature is a native secp256k1 slot with v in {0,1}. Only at the
EVM submission boundary does the relayer validate the slot and emit
r ‖ s ‖ (v+27) for OpenZeppelin ECDSA.recoverCalldata. Nothing wraps or
rehashes the packed digest.
For the session exception (row 19), use
EIP712Domain(string name,string version,uint256 chainId,address verifyingContract,bytes32 salt).
chainId is the real Cowboy chain ID, salt is its instance ID and
verifyingContract is the Session actor for session vouchers or the Trading Post
for per-call receipts. SignedMessage::Eip712Digest carries the final 32-byte
keccak256(0x1901 ‖ domainSeparator ‖ structHash) unchanged, with no extra hash or
native object frame. The voucher carries account and an AccountSignature;
the exact type is Voucher(bytes32 session_id,uint128 cumulative_amount,uint64 nonce,uint64 expires_at,bytes32 usage_digest,address account,uint64 policy_revision).
Route reports carry the zero account at revision zero with one slot authorized
by the binding’s metering key.
Consensus BLS12-381 MinSig certificates and VRF seeds keep their scheme-tagged
consensus format. Ethereum sync-committee BLS, vendor Nitro COSE/X.509 and TDX
evidence keep their foreign formats. CBSS BLS partials and tlock use the
release-key suite tag and the instance-bound tlock identity, and blinding Schnorr
already has a suite tag. P2P Ed25519 peer authentication belongs to the transport
and is not a Cowboy object signature. Stored keys used with these formats are
still tagged where §7.7 applies. The request-authentication specification owns
off-chain request authentication, including Watchtower access proofs.
7.7 Tagged signing keys
SigningPublicKey uses the shared algorithm registry with exact key lengths:
secp256k1 (1): 33-byte compressed SEC1; Ed25519 (2): 32 bytes; P-256 (3): 33-byte
compressed SEC1; P-384 (4): 49-byte compressed SEC1; P-256 WebAuthn (5): 33-byte
compressed SEC1, which no field accepts at genesis (§7.5). Unassigned IDs, wrong lengths,
uncompressed points and DER keys reject. The encodings are distinct and normative:
Commonware and JSON decoding checks the algorithm, the exact length and each
field’s permitted algorithm set without curve arithmetic. The producers’
validating constructor and the shared
validate() reject small-order Ed25519
keys and off-curve secp256k1, P-256 and P-384 keys. Every consensus handler
charges KEY_VALIDATION_CYCLES[algorithm] before validation and validates
before storing or trusting a key. Per-slot signature verification already pays
for the validation it performs. A per-byte decode charge does not count as a
key-validation charge, and a rejected key still consumes the charged work. The
access-weight table version does not change.
Every retyped field declares its support set: RAS delegated keys, CBFS owner and
mount-grant keys, runner grant-signing keys, room signing keys and validator peer
keys accept Ed25519; route metering and CBSS proxy signing keys accept secp256k1;
TEE trusted/bound quote keys accept only the TEE-specific algorithm: SGX/TDX
require P-256, SEV-SNP/AMD-SEV-SNP require P-384, and Nitro requires Ed25519.
The vendor Nitro COSE certificate signature is a separate, exempt format.
Registering an algorithm for one surface does not enable it on another. P-256
and P-384 stay disabled for transactions and contract verify_signature.
Key-addressed storage and lookup paths, including ras:delegation:,
ras:revocation:, ras:svrn: and tee_measurement_binding:, use the
algorithm-bearing fragment. Every surface rejects untagged keys and never
converts them.
8. Deferred Route-Authentication Signing
The route-authentication CIP owns route-authentication EIP-712 forms. CIP-40 neither specifies nor activates them, adds no route-auth version to its activation payload, exposes nosignRouteAuth, and makes no Gateway, Runner or Workload readiness claim.
9. Deferred Payment Signing
The payments CIP owns payment-intent EIP-712 forms. CIP-40 neither specifies nor activates them, adds no payment-auth version to its activation payload, exposes nosignPayment, and makes no payment-admission or settlement readiness claim.
10. Ethereum Facade
A wallet that adds Cowboy as a network needs a JSON-RPC URL whoseeth_chainId matches the requested chain. The facade serves network setup and balance display and runs no EVM code.
GET /chain-info returns exactly this closed JSON object with Cache-Control: no-store:
chain_id is a canonical unsigned decimal u64 string and never passes through a JavaScript number. The example pair ("mesa", 26909) is not a registry row. At startup the node recomputes and stores the complete §16 release identity, including the external manifest digest. This handler reads that trusted local result and MUST NOT echo request data or an unchecked configured digest. /chain-info reports configuration and proves nothing about state by itself. The connector trusts release-pinned metadata shipped with the application, plus HTTPS, and compares every configured mirror to that identity and to every other mirror. The connector refuses to sign if any identity or version field is missing, extra, duplicated, of the wrong type or case, or unequal, or if the modes are reordered.
GET /chain-info and POST /eth are public, read-only browser endpoints. Successful and error responses on those exact paths include Access-Control-Allow-Origin: * and never include Access-Control-Allow-Credentials. Connector requests use credentials: "omit". An OPTIONS request to /chain-info returns 204 with Access-Control-Allow-Origin: *, Access-Control-Allow-Methods: GET, OPTIONS, and Access-Control-Allow-Headers: content-type; /eth returns the same headers with POST, OPTIONS. No neighboring authenticated RPC endpoint inherits this CORS policy.
Chain parameters
GET /chain-parameters is unauthenticated and uses Cache-Control: no-store.
Success and error responses include Access-Control-Allow-Origin: *, never
Access-Control-Allow-Credentials; OPTIONS returns 204 with methods GET, OPTIONS
and allowed header content-type. No adjacent authenticated route inherits this policy.
The body contains "chain_identity":{"chain_id":"<decimal>","chain_instance_id":"0x<64 lowercase hex>"},
the closed §14 identity object, and the following parameters moved from /chain-info:
Unlike
/chain-info, /chain-parameters is extensible. Readers take the members
they need, but MUST refuse a nested chain_identity different from their trusted
identity before using any parameter. session_chain_id is removed, and runner and
session clients read the real identity from /chain-info. Every Rust /chain-info
consumer, including the runner, CBFS, CLI, harness and SDK readers, decodes through
the codec’s closed ChainInfo. Dashboard, outpost and explorer readers obey the
same six-member contract.
10.1 Endpoint
POST /eth on the existing REST RPC server accepts a UTF-8 application/json JSON-RPC 2.0
body. The root is one request object or a nonempty array of at most 16 request objects. Each request
has exactly jsonrpc:"2.0", a method string, optional params and optional id. An id is a JSON
string or I-JSON integer, and the response echoes it unchanged. A request without an id is a
notification and gets no response entry. No-parameter methods accept absent params or exactly []; every other method
requires the exact positional array below. Duplicate keys, extra request members, non-I-JSON
numbers, or trailing JSON reject as an invalid request.
Every response object has exactly jsonrpc:"2.0", the request id, and one of result or
error. An error is exactly {"code":<integer>,"message":<string>} with no data: parse error
(-32700,"Parse error"), invalid request (-32600,"Invalid Request"), method not found
(-32601,"Method not found"), invalid params (-32602,"Invalid params"), or internal error
(-32603,"Internal error"). JSON-RPC success and error bodies use HTTP 200. A malformed root,
empty batch, or batch larger than 16 returns one invalid-request object with id:null and executes
nothing. Batch responses preserve request order while omitting notifications; an all-notification
batch returns HTTP 204 with an empty body.
QUANTITY is lowercase 0x hexadecimal with no leading zero (0x0 is zero). DATA<n> is 0x
plus exactly 2n lowercase hex digits. Input addresses are 0x plus 40 case-insensitive hex
digits. FINALIZED_TAG is exactly one of "latest", "safe", or "finalized"; all three resolve
to the same locally finalized Cowboy head. Every other tag, including "pending", "earliest"
and numeric block tags, is invalid params.
The compatibility block result has exactly these members.
block_hash, parent, tx_root,
state_root, receipt_root, height, and timestamp come from the same finalized Cowboy block.
ZERO8, ZERO20, ZERO32, and ZERO256 are zero-filled DATA<n> values. Wallets use this
object to check liveness. It is neither an Ethereum block nor an EVM commitment.
baseFeePerGas: null tells wallets the network predates EIP-1559, so they use legacy fee display and make no fee-market calls. The facade is read-only and stateless. It MUST NOT implement eth_sendTransaction, eth_sendRawTransaction, eth_call, or eth_estimateGas, so a wallet or tool that submits an Ethereum-format transaction gets method-not-found.
10.2 Balance scaling
CBY has 9 protocol decimals (1 CBY = 10⁹ Cowboy wei). The supported-wallet metadata usesnativeCurrency.decimals = 18, so eth_getBalance returns checked(balance_wei9 × 10⁹) as a JSON-RPC quantity. The multiplication uses u128 or wider arithmetic and never narrows through u64. The scaling applies only to the facade’s display.
10.3 Chain id uniqueness
In theeip155 namespace, chain ID 1 is Ethereum mainnet. A Cowboy network exposing the facade MUST use one noncolliding ID allocated in the release-pinned docs/cips/registries/cip-40-chain-ids-v1.json. The registry is the closed object {"allocations":[...],"format_version":1}. Each allocation is the closed object {"allocation_pr":N,"chain_id":"D","network":"S","public":B}. N is a JSON integer in 1..=2^32-1 naming the allocating cowboyinc/cowboy pull request. D is a nonzero canonical unsigned decimal u64 string. S matches [a-z][a-z0-9-]{0,31}. B is a JSON boolean, true when accounts outside Cowboy’s operators may use the network. Rows are strictly ascending by the numeric u64 value of D. Both D and S are globally unique, and existing rows never change. The file bytes are the RFC-8785 JCS of that object followed by exactly one LF, which is excluded from any JCS digest or equality check. The registry allocates bigsky 26926903 (public), cloud 26926904 (public), canyon 26926905 (operator dev/staging) and mesa 26926906 (operator dev/staging). Each allocation is checked for collisions against a pinned ethereum-lists/chains checkout whose commit the allocating PR records. The example fixture ID 26909 is unallocated.
Wallet display metadata is a separate release-pinned object containing the allocated chain ID, chain name, 18-decimal CBY metadata, HTTPS /eth RPC URLs, and optional explorer URLs. Before asking a provider to add or switch networks, the connector checks every listed RPC’s eth_chainId and /chain-info response against that metadata, the expected activation-manifest digest and each other. One failed or divergent mirror rejects the operation.
11. WalletConnect Integration
11.1 Provider state machines
Injected and WalletConnect providers onboard differently. For an injected EIP-1193 provider, the connector first validates the release-pinned network metadata and every direct facade mirror. It then reads the provider’s activeeth_chainId and calls the EIP-3326 method wallet_switchEthereumChain if the chain differs. Only the unknown-chain error ProviderRpcError.code = 4902 lets the connector follow with EIP-3085 wallet_addEthereumChain. Code 4001 and every unmapped error fail without an add request. After adding, the connector requests the switch again and re-reads eth_chainId before signing.
For WalletConnect, dapps request a standard eip155 session:
- The session requests
eip155:<cowboy_chain_id>for each network the dapp supports. - The session requires
eth_signTypedData_v4. No transaction-sending methods are requested. - The session subscribes to
accountsChangedandchainChanged.
domain.chainId, /chain-info.chain_id, domain salt, and connector chain_instance_id MUST agree. An account, chain or session change invalidates pending typed data.
11.2 Connector
@cowboyinc/connect is the dapp-side connector. It exposes connect, getAccount and signTransaction over injected and WalletConnect transports, and no arbitrary-message, route-authentication or payment-signing method. For each signature operation it:
- Validates every configured facade mirror and the release-pinned activation-manifest digest, then freezes the resulting
ChainIdentityfor the operation. - Builds canonical canyon JSON without routing any
u64oru128through JavaScriptnumber, and freezes the complete roster and every slot descriptor before requesting signatures. - Calls the canonical wasm export with that exact
ChainIdentityto produce the full typed object, then checks the returned domain identity and bound account. - Requests exactly
eth_signTypedData_v4for the approved account. - Accepts exactly 65 bytes, leaves
v=0/1unchanged, maps27/28to0/1, rejects every other value, fills only the selected, already-frozen mode-1 slot, re-verifies locally throughTransactionVerificationContext, encodes, and submits.
11.3 Cowboy wallets
The iOS wallet integrates Reown WalletKit. It treats a request as Cowboy only when the domain name, version, chain and salt, theprimaryType, the exact type and member sets, and the bound account all match the pinned schema. It rejects any malformed request that uses a reserved Cowboy domain. For a recognized transaction, the wallet decodes and re-encodes the exact signed instruction bytes before showing them. Stock wallets still sign blind with a domain tag (§7.4).
11.4 SDK surface
cowboy-protocol-wasm provides the canonical v3 exports, and the C-ABI FFI crate mirrors them. The wasm exports take and return JSON or bytes and throw JsError on failure:
slot_index=0 is the primary, and later indices follow canonical additional-signer order. Out-of-range indices and wrong signature lengths reject. Attachment never adds signers or changes a mode. Once every slot is filled, assembly verifies the complete transaction.
Rust, wasm, C ABI, Swift FFI, Python, CLI and JS transaction bindings take the same explicit ChainIdentity, and every verification binding takes TransactionVerificationContext. Only the canonical implementation generates typed-data JSON. Connectors and wallets MUST NOT hand-assemble it.
12. Security Considerations
- Native v3 and EIP-712 preimages use distinct prefixes, and both bind the same immutable
ChainIdentity. A signature replayed on another instance with the same chain ID, or in the other mode, therefore fails. - The typed struct and the §7.3 invariants together cover every canonical field.
verify(context)runs the structural checks before recovery at every admission point. - The native preimage contains the version and kind bytes. Mode 1 binds the version through its domain and the kind through its message. Kind 1 can decode in the standalone codec but is invalid in every external and consensus path in this release.
has_sponsorbinds the wire Option tag, soNonecannot share a digest with aSomewhose fields are zero.- Verifiers reject high-S signatures and every wire recovery id outside
{0,1}. Connectors normalize only provider values27/28. - The signed bytes are the authorization, and a stock wallet cannot interpret the opaque instruction. This release gives stock wallets cryptographic interoperability but makes no claim that their users can read what they approve. Cowboy wallets trust their rendering only after decoding and re-encoding the exact bytes.
- The facade refuses transaction-sending and EVM-execution methods and never interprets an Ethereum-format transaction as a Cowboy submission.
- Connectors compare every configured
/chain-infomirror to one pinned activation-manifest digest before building typed data. A chain, provider or session change invalidates the operation.
12.1 Wallet and actor identity
An address becomes a wallet when the chain accepts its first authenticated transaction signature. The permanent wallet marker is stored apart from the account balance and nonce. Receiving funds, appearing as an instruction argument or signing an off-chain message does not make an address a wallet. The consensus carrier is fixed by CIP-4 §§4.2–4.3:WalletMark=0x25, key 0x25 ‖ address[20] ‖ zeros[65], and the existing
SystemBytes([0x01]) variant at value tag 0x0A (encoded 0A 01 01). No
alternative key or encoding is permitted.
For each ordinary signed transaction, execution MUST check the primary sender
and every co-signer against the current state. An actor address or an address
below the reserved system-address limit (0x100) cannot sign a transaction.
This check runs even when cryptographic verification finished before
execution, because an earlier transaction in the same block may have deployed an actor.
Engine-authored deferred transactions are not wallet signatures and do not
create wallet markers.
Once signature, nonce, fee and address-role admission succeed, execution marks
every signer when it accepts the nonce. A CreateAccount target must co-sign, so
it is marked too. The markers survive an instruction failure, as the nonce and
fees do. An admission rejection leaves no marker. A storage failure that prevents
committing the transaction rolls it back, including markers already written.
The wallet role is permanent for primary and additional signers alike.
Co-signing is an authenticated wallet action that claims wallet identity. The
protocol has no co-signer exemption, opt-out, unclaim or role-conversion
operation. Once the chain accepts an address’s signature, that address stays a
wallet and can never become an actor. The same wallet/actor exclusion applies to
every signer, including CreateAccount targets.
Deploy and fork() MUST reject a wallet-marked destination using the current
staged state. A funded address with no marker remains eligible for deployment.
Identity I/O is reserved per account, whatever its inner slot count. The
primary reserves 2R + 1W = 3 structural accesses, and each additional account
reserves 3R + 1W = 4. Each row includes one AccountAuth read of the current
policy, besides its actor and marker work and, for an additional account, its
Account read. Admission charges the complete identity row before identity I/O,
and insufficient capacity rejects admission without accepting the nonce.
Deploy and fork() additionally pay for their wallet-marker probe. A nonce
value alone MUST NOT substitute for the identity check.
Deploy reads the actor address’s wallet marker before any Actor creation;
fork() reads the child address’s wallet marker before its Actor collision check
and returns WalletAddressConflict without changing either creation counter.
A wallet-marker read sees the claims of the selected speculative parent, not
those of a sibling branch. The marker persists and rolls back atomically with its
savepoint.
12.2 Keys used only off chain
A valid off-chain signature proves control of a key but does not reserve its address as a wallet. Before granting lasting authority based on such a key, a service MUST require it to sign an accepted on-chain transaction and verify the wallet claim in finalized state on the intended chain instance. The key may be the sender or a co-signer. Funding the address, submitting a transaction without finalization, or observing only an off-chain challenge response is insufficient. A reserved future passkey account may receive funds before signup, and its first transaction both claims the wallet and registers its backup key. Genesis does not enable passkey transaction authorization, and §7.5 fixes its slot.
This requirement applies to wallet-address authority. An actor gets authority
from its on-chain actor identity and permissions, and registering a raw transport
public key does not make it a wallet address. Services must keep these identities
apart and verify ordinary authorization independently of the wallet marker. A
chain reset or instance change invalidates cached wallet claims, which services
must verify again against the new finalized state.
13. Protocol Constants
These constants define the genesis v3 release (§7.1).14. Release Corpus
This section fixes the corpus schema and minimum matrix and publishes no placeholder v3 bytes or hashes. Before release, every consumer recomputes the implementation-generated vectors independently and pins them. A successful kind-0 vector contains:input.jsonandchain_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, andsubmission.bin; - for mode 1, exact
typed_data.json,domain_separator.hex,typehash.hex,struct_hash.hex,digest.hex, andsignature.hex.
.bin file is raw bytes. Every .hex file is lowercase hexadecimal without 0x and with
exactly one trailing LF; hashes contain 64 digits and signatures 130. JSON files are UTF-8, closed
schema and free of duplicate keys, and end in one LF. typed_data.json is the exact object passed to
eth_signTypedData_v4.
A decode-only kind-1 fixture contains exactly input.json, submission.bin and
expected_rejection.txt, with no signing preimage, signing hash, typed-data object or
signature. The shared codec must decode and re-encode it byte for byte. The RPC, mempool, directly
proposed block, block import, replay and execution fixtures must all reject it before lane or state
use. Unknown kinds reject at the outer discriminant before body decode.
The kind-1 expected_rejection.txt contains exactly TxKindDisabled(1)\n, and every boundary harness
asserts that rejection after a successful decode. A raw decode-failure fixture contains
exactly submission.bin and expected_decode_error.txt, whose text is one stable codec
error token plus LF, never a disabled-kind token.
The kind-0 matrix covers native and EIP-712 transfer, actor execution, multisig,
maximum-width lossless integer JSON, provider v normalization, duplicate-primary rejection, wrong chain/instance/domain,
version/kind/algorithm/mode/public-key mutation, mixed-mode rosters, non-default reservations, malformed Option tags, high-S, invalid recovery id, deferred-mode
invariants, and signature-byte-independent identity. Algorithm 5 vectors cover a
well-formed §7.5 slot that decodes and then rejects as unsupported with zero
recovery calls, its empty-vector digest placeholder, a payload mutation that leaves
the digest unchanged, an algorithm-5 additional signer and an algorithm-5
sponsor slot each taking the empty-vector preimage, mode 1 with algorithm 5
rejected at decode, and each §7.5 length bound. The release that accepts algorithm 5 adds verification vectors: each flag rule,
authenticator data one byte long or short, an unlisted origin, a sibling-subdomain
origin under the same rp_id, the wrong type, the wrong challenge,
crossOrigin: true, backup state set without backup eligibility, high-S, and
mixed-algorithm rosters whose failures surface in the §7.3 pass order. Any invalid slot, including the last slot, must fail with zero recovery calls. Each slot-descriptor mutation is tested against every other signer as well as the mutated slot. An independent EIP-712 implementation consumes
the canonical wasm-emitted object. Typehash, domain-separator, struct-hash and digest
vectors use the §7.2 Sponsor type and exact dependency ordering. The invalid corpus
includes a sponsor=Some rejection using the §7.1 address/terms/slot shape; success
vectors use the exact absent sponsor projection.
The release matrix exercises protocol codec, node RPC/mempool/block verification/replay/execution,
CLI, wasm, FFI, Python/JS SDKs, connector, wallet, indexer, and explorer. It also pins the §16
JCS/identity fixture; the closed /chain-info schema; one-divergent-mirror rejection; injected
provider switch/add behavior including 4902 and 4001; WalletConnect session invalidation; and
the facade’s exact request/result/error schemas, batch and notification behavior, quantities,
finalized-tag aliases, complete compatibility-block object, balance scaling, method refusal,
endpoint-scoped CORS, credential omission, and preflights. Tests also show that an adjacent
authenticated RPC route gets none of these permissive CORS headers and that the node never serves
a configured but unrecomputed manifest digest as its chain identity. Registry vectors cover
empty, one-row, numeric sorting ("9" before "10"), duplicate ID/network, extra member, and
missing/excess final-LF cases.
15. Rationale
- The typed data carries
bytes instructionrather than per-instruction structs. Per-instruction structs would make stock-wallet prompts readable, but each adds another reconstruction path for a large instruction enum. The generic form has one verifier and full cryptographic binding. Stock-wallet blind signing stays an explicit product and security acceptance gate, and a connector-rendered summary is not part of the signed authorization. - Mode 1 forbids
access_listand theorigin_*fields instead of binding them through an extrabytes32 tx_extrafield. These fields mean nothing in a caller-signed, non-deferred transaction, and forbidding them keeps the typed struct readable. If they are activated later, the typehash changes. - This CIP uses
eip155rather than acowboyCAIP namespace, which would need wallet-specific support.eip155with typed data reuses provider machinery in wallets that support the Cowboy chain. §11 does not claim every wallet works. The facade answers only the pinned read-only subset and refuses transactional methods. - Modes are per slot so that a hardware wallet and a native CLI can authorize the same transaction. Both digests fix every descriptor before any signer starts, so changing one invalidates every collected signature.
16. Clean-Genesis Release Contract
This release starts from one clean genesis and defines no state-conversion procedure. The immutableCip40ActivationV1 payload is a closed
JSON object with exactly these six members:
genesis_config_sha256 hashes the exact, separately pinned genesis-input bytes. Those bytes
fully determine the validator and consensus configuration and the height-zero application state,
except for the genesis parent derived from the payload. make_genesis_v2 rejects a mismatch before
construction. Genesis also refuses an absent nonce, chain ID zero, or a defaulted network name.
The genesis input MUST contain a required feature_authority section with exactly
this closed JSON shape:
members contains 1–16 distinct 20-byte addresses, strictly ascending by address;
each string uses exactly 0x plus 40 lowercase hex digits. threshold is a JSON
integer with 1 ≤ threshold ≤ members.len(). Genesis load rejects a missing
section, missing or unknown object members, duplicate JSON keys, wrong types or
address encodings, duplicate or out-of-order addresses, member counts outside
1–16, threshold zero, or a threshold greater than the member count. The section
is part of the genesis-input bytes that genesis_config_sha256 hashes, so the
activation payload below binds it into chain_instance_id without adding a
member to the six-member payload.
Stage 0 initializes FEATURE_REGISTRY = 0x1A (allocated in the Technical
Whitepaper §9) with exactly one key: feature:auth, whose value is the canonical
encoding of FeatureAuthority { members, threshold }. No instruction can write
this actor. Directives and their opcode, feature records and GET /features are
reserved for a later CIP, and this release adds no feature state beyond the
authority key. Every environment’s Stage-0 genesis producer MUST emit
{"members":[<genesis deployer address>],"threshold":1} for feature_authority.
Duplicate keys, non-I-JSON input, missing/extra members, or values outside the grammars reject before
RFC 8785 canonicalization. Derivations consume raw digest bytes:
activation_payload_hash and chain_instance_id.
activation_manifest_digest = SHA-256(RFC 8785 JCS(final_manifest)) is an external release pin,
not a manifest member. Keccak-256 is the Ethereum function, not FIPS SHA3-256.
The following fixture is normative for JCS and hash construction. The genesis fixture
holds the same bytes and hashes, and docs CI checks that the two match and recomputes the full hash
chain. Its example genesis deployer is 0x1111111111111111111111111111111111111111. Its genesis-input bytes are the
124 ASCII bytes {"accounts":[],"feature_authority":{"members":["0x1111111111111111111111111111111111111111"],"threshold":1},"validators":[]} with no newline. The example
(network, chain_id) pair ("mesa", 26909) is not a registry row, so the fixture
reproduces the bytes but fails the production allocation check.
/chain-info object from genesis, with every value taken from the recomputed identity
and no null member.
The release consists of these steps:
- land CIP-40, CIP-33’s reciprocal decoder policy, the Technical Whitepaper §2/Appendix A mirror, the changelog, and the chain-ID registry artifact;
- use a reviewed
(network, chain_id)allocation, derive one clean genesis, and start validators only after every node agrees on chain identity, manifest digest, and v3 codec; - 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;
- update all consumers in the same codec release: the Solidity transaction decoder, the runner chain client’s digest preimage, the transaction and consensus wire test vectors, the indexer, the explorer, and the example probes and decoders. Their verification, recovery, digest and unsigned-slot checks must use v3 slots and explicit trusted chain identity. The example probes and decoders are built and run against the release codec before the examples are published.
17. Passkey slot: status and open decisions
No genesis transaction can contain an algorithm-5 slot, so §7.5 and the
empty-vector digest rule change no genesis transaction’s identity. Because they
are registered at genesis, v3 decoders, indexers, wallets and SDKs that implement
this CIP already hash such slots correctly. The release that accepts passkeys
should then change only verification rules, once the CIP-49 key-proof design
(§7.5) and the configuration in decision 2 exist.
Core implements v3 with algorithm IDs 1–4 and zeroes every slot in place. To
conform, core needs algorithm 5 in the slot and SigningPublicKey decoders
(shape only, then rejected as unsupported), the empty-vector preimage rule and
the §14 vectors.
These decisions are open:
- Which release accepts passkeys. No surface accepts them at genesis. Accepting them at genesis would require amending §4, §7.1, §7.5, §7.7 and the §16 release contract, and finishing the CIP-49 key-proof design first.
- Where
rp_idand the allowed origins live.Cip40ActivationV1is closed, immutable and an input tochain_instance_id(§16), so it can hold them only if they are pinned before genesis. Otherwise the accepting release specifies a separate consensus configuration for them, such as per-network protocol constants.rp_idmust be the registrable domain the wallet serves passkeys from, and passkeys created under it cannot move. The origin set lists exact origins, never a wildcard. - Whether a passkey can create an account by itself. Under this CIP, an
algorithm-
5slot satisfies only a CIP-49 policy. Once accepted, a passkey could become the sole key of an existing account through a 1-of-1SetAuthPolicy, but a secp256k1 key must create the account first. For a passkey alone to create an account, as §12.2’s reserved passkey accounts suggest, the accepting release would define an address for an algorithm-5key, for example the last 20 bytes ofkeccak256("cowboy.address.webauthn-p256.v1" ‖ X ‖ Y), where the domain tag separates it from secp256k1 derivation. That release would also lift §7.5’s exclusion of address-derived accounts and extend CIP-49’s revision-zero check from recovered keys to a supplied, verified algorithm-5key that derives the declared address. A lost passkey would lose the account, so that account’s first transaction should install a policy with a backup key, as §12.2 describes. No genesis transaction can authorize such an address, so this decision can also wait.