talk.nervos.org: RFC draft: Lock Proof, proving control of a CKB lock<br />
We would like feedback on an RFC draft before opening it in nervosnetwork/rfcs. It came up in the review of ckb-devrel/ccc#641.
What it does.
A site asks a wallet to prove it controls a lock. The wallet signs a transaction that can never be committed: one input at an out point no transaction can create, one output under the lock holding the site’s message. The site rebuilds that transaction, resolves the input itself and runs the lock in CKB-VM. If the lock accepts, the key controls the lock. It is BIP-322 adapted to CKB.
Why.
A verifier for one signature scheme cannot check a passkey lock, a multisig, an Omnilock in a foreign chain’s mode or a smart account. Running the lock checks all of them with one verifier, and every wallet can sign it with the code it already has.
What is tested.
17 signed proofs, replayed by the reference test suite: secp256k1, JoyID main key and sub key (signed in the JoyID app), multisig, anyone-can-pay, Omnilock (Dogecoin, Ethereum, Bitcoin modes), PW-lock, Nostr, the quantum-resistant lock, a smart-account lock. Four of them on mainnet.
Questions for you.
Standards Track or Informational?
Is there a lock you use that this would not cover? The draft lists what it does not cover (relative time locks, locks that need two inputs, locks that do not sign the transaction hash).
Wallet authors: would you show a proof as a sign-in request, as the draft suggests?
Reference implementation:
GitHub - LusoCryptoLabs/ckb-ward: Ward: lock proof for CKB. Prove control of any CKB lock with a proof transaction that can never land on chain. · GitHub
(npm
ckb-ward
)
Draft: Lock Proof, Proving Control of a CKB Lock
Category: Standards Track. Status: Proposal.
Abstract
This RFC defines a way to prove, off chain, that the holder of a key controls a CKB lock script, for any lock that signs the transaction hash. The prover signs a transaction that can never be committed: its only input points at an out point no transaction can create, and its only output, under the claimed lock, holds a message written by the party that asks. The verifier rebuilds that transaction from the lock and the message, resolves the input itself, and runs the lock in CKB-VM. If the lock accepts, the key controls the lock. Nothing moves on chain.
It follows BIP-322 (generic signed message format for Bitcoin) and serves the purpose EIP-1271 serves for Ethereum contract accounts.
Motivation
A service sometimes needs to know that the person behind one of its accounts controls a CKB lock. A governance site, for example, counts the Nervos DAO deposits under a lock as that account’s voting weight.
On CKB a lock is a program. A verifier that checks one signature scheme (secp256k1 with a known message prefix) cannot check a passkey lock, a multisig, an Omnilock in a foreign chain’s mode or a smart-account lock. Each new lock would need new verifier code and new wallet code, and locks that have no message signing at all could never be counted.
Every wallet can already sign a transaction that spends a cell under its lock. If the proof is such a transaction, every wallet can produce one with the code it has, and one verifier, which runs the lock as the node would, handles every lock.
Specification
The key words “MUST”, “MUST NOT”, “SHOULD”, “SHOULD NOT” and “MAY” are to be interpreted as described in RFC 2119.
Terms
ckbhash
: BLAKE2b-256 with personalization
ckb-default-hash
.
lock hash
: ckbhash of the molecule-serialized
Script
.
prover
: the holder of the key, and their wallet.
platform
: the service that asks for the proof, issues the message and runs the verifier.
binding
: a platform’s record that links a lock to one of its accounts.
Message
The platform writes the message. It is UTF-8, lines separated by a single LF (0x0a), no trailing LF, at most 1024 bytes, exactly six lines:
{domain} wants you to prove control of a CKB lock.
Account: {account}
Lock hash: {lock hash}
Chain: {chain}
Issued at: {issued at}
Nonce: {nonce}
Field
Format
domain
host name of the platform, optional
:port
; letters, digits,
.
and
-
account
1 to 256 printable ASCII characters (0x20 to 0x7e), no space at either end
lock hash
0x
and 64 lowercase hex digits: the lock hash of the claimed lock
chain
0x
and 64 lowercase hex digits: the genesis block hash of the chain
issued at
RFC 3339 in UTC with
Z
, optional fraction of a second
nonce
1 to 128 characters from
A-Z a-z 0-9 . _ ~ -
, at least 64 random bits
Mainnet genesis:
0x92b197aa1fba0f63633922c61c92375c9c074a93e85963554f5499fe1450d0e5
. Testnet genesis:
0x10639e0895502b5688a6be8cf69460d76541bfa4821629d86d62ba0aae3f9606
.
Proof transaction
TAG = "CKB lock proof v1\n" (18 bytes, ASCII, ends with LF)
P = ckbhash(TAG || lock hash || message) (lock hash as 32 raw bytes, message as UTF-8)
n = byte length of the message
s = occupied size of the claimed lock (32 of code hash, 1 of hash type, its args)
Field
Value
version
0
cell_deps
what the lock needs, chosen by the wallet
header_deps
what a header-reading lock needs, chosen by the wallet, usually none
inputs
exactly one:
previous_output = { tx_hash: P, index: 0xffffffff }
,
since
= 0 or a value the wallet sets to satisfy a matured absolute time lock
outputs
exactly one:
lock
= the claimed lock,
capacity
= (8 + s + n) * 10^8 shannons, no type
outputs_data
exactly one: the message bytes
witnesses
exactly one: what the lock needs, as the wallet writes it
The verifier resolves the input to the cell
{ capacity: 0xffffffffffffffff, lock: the claimed lock, type: none, data: empty }
. The prover never supplies it.
A wallet signs the proof as it would any transaction spending a cell under the lock. A wallet that receives the transaction without the input cell MUST rebuild it from the transaction: capacity u64::MAX, the lock of the only output, no type, empty data. It MUST NOT look the input up on chain, since it does not exist.
Verification
Input: the claimed lock L, the message M, the signed transaction T, and the platform’s expectation E: the exact message it issued for this nonce, its domain, the account, the nonce, the chain’s genesis hash from its own configuration, and an age window. A node error means “could not verify”, not “refused”. Steps 1 to 7 read nothing from the chain.
Refuse when any field of E is missing.
Parse M. Refuse when it is not the six lines above.
Refuse unless M equals E’s message byte for byte.
Refuse unless the lock hash line equals the lock hash of L. Refuse when L is a lock an administrator can open (see Security considerations).
Refuse unless the domain, account, nonce and chain lines equal E’s,
now - issued at
is within E’s window, and
issued at
is at most 60 seconds ahead of
now
.
Refuse unless T has exactly one witness and is within the limits below.
Build the transaction of the previous section from (L, M), copy T’s cell deps, header deps and the input’s
since
into it, and refuse unless its transaction hash equals T’s.
Mark the nonce used. Refuse when it was already used.
Refuse unless the node’s genesis hash equals E’s chain.
Read every cell dep of T from the node as a live cell. Count the cells each dep group lists, from its data, and refuse when all groups together list more than 32, before reading any member; then read each member as a live cell. Refuse when any cell is not live. Read each header dep from the node; refuse when one is unknown.
Run the lock script group of input 0 in CKB-VM with T, the resolved input, deps and headers, under a cycle limit. Refuse unless it exits 0.
Probe for exclusive control. Run the lock again on (a) T with its witness replaced by an empty one, and (b) the transaction built from M with a fresh random nonce, with T’s cell deps and T’s witness. Refuse when either exits 0.
Accept. Return the out points read in step 10.
The VM SHOULD be the node’s own script verifier under the chain’s consensus at the current epoch, so that the VM version, syscalls and
hash_type
resolution match what the node does for a real spend. Node RPCs such as
test_tx_pool_accept
cannot do this check: they refuse the transaction before any script runs, because the input does not exist.
Limits
Limit
Value
cell deps listed
16, no out point twice
cells listed by all dep groups together
32, counted from the groups’ data before any member is read
header deps
8
transaction size in a block
597,000 bytes (the consensus block limit)
witness
65,536 bytes; a verifier MAY raise it for a lock with larger signatures
message
1,024 bytes
each chain read
a timeout
each lock run
a cycle limit
Platform requirements
A verifier only says that a lock accepted one transaction. A platform that counts anything from a binding MUST also:
Write the message itself, store the exact text per nonce, and compare byte for byte. It MUST NOT rebuild the message from the proof.
Issue each nonce for one account and one lock hash, and mark it used with a compare-and-set no later than the first chain read.
Take the genesis hash from its configuration, never from the message or the node.
Keep at most one active binding per lock hash. Moving a binding to another account notifies the previous one, and the moved binding counts only after a cooldown.
When counting weight, read it at one snapshot block for every account, and count a binding only if it was made before that block and every cell dep its proof used was still live at that block. For the Nervos DAO, count deposits only (data of 8 zero bytes), found by the exact lock script.
Wallet behaviour
A wallet SHOULD recognise a proof: a transaction equal to the proof transaction for one of its locks and the message in its only output, cell deps, header deps,
since
and witness aside. It SHOULD then show a sign-in request rather than a transfer: the domain next to the origin of the site that asks, with a warning when they differ, the account and the chain. It SHOULD NOT show the input’s capacity as an amount: nothing leaves the account.
Rationale
Index 0xffffffff.
No transaction can have 2^32 - 1 outputs within the block size limit, so the out point cannot exist and the signed proof can never be committed.
P commits to the tag, the lock and the message.
Another lock or another message gives another transaction, so a signature cannot be moved between them. The tag keeps P apart from any real transaction hash, and names the bytes being signed: a change to those bytes gets a new tag.
Input capacity u64::MAX.
Some locks let a key move only a limited amount per transaction. At u64::MAX such a key sees the whole account leave and cannot prove the lock; a key with no limit can. The transaction hash covers out points, not the cells they resolve to, so this value is not part of the signed bytes for locks that sign the transaction hash.
Output under the claimed lock.
Output locks never run. The output names the lock, so a wallet with several locks reads from the transaction which one is asked to sign, and a signer that gets the transaction without the input cell can rebuild it. The lock is part of the signed bytes, so a transaction whose output lock differs from the lock P commits to is a proof for no lock.
Output capacity (8 + s + n) CKB.
The occupied capacity of that output. CCC 1.19 and later raises an output to its occupied capacity while building, so fixing this value makes every implementation build the same bytes.
The verifier builds the transaction.
If it accepted any transaction with input 0 under L, a prover could add inputs or outputs that open L without the key: an owner-lock style lock accepts when another input carries a given lock hash, and anyone-can-pay accepts without a signature when an output under the same lock receives more than the input. With one input at u64::MAX and one output holding less, anyone-can-pay still asks for the signature.
Message shape.
The first line follows EIP-4361 (Sign-In with Ethereum), so it reads the same way to users who have seen that. The account is ASCII only, so it cannot carry line breaks, direction overrides or look-alike letters into the text a wallet shows.
Rejected: a real input that cannot be spent yet
An earlier draft let wallets that only sign real inputs use a live cell of the lock with
since
set to a block far in the future. It was dropped: such a since satisfies time locks that have not matured, the outflow is only a fee so a key with a per-transaction limit can prove the whole account, the real input may carry a type script that opens the lock another way, and the message is only visible as a hash.
Security considerations
Cell deps come from the chain as live cells, never from the prover.
A lock’s code and settings can live in deps. A forged settings cell that lists the attacker’s key would make some locks accept.
The input is a constant of the verifier
, never a cell the prover names.
No exclusive control, no proof.
A lock that accepts an empty witness opens for anyone. A lock that accepts the same witness on another message (a password or hash-preimage lock) lets anyone who has seen one proof make another. The two probes of step 12 refuse both kinds. A lock written to tell a probe from a real proof could still pass them.
No lock an administrator can open.
An Omnilock with the administrator flag (args byte 21, bit 0) is also opened by any identity on an admin list the administrator controls. The verifier refuses such locks, for the owner’s proofs too.
Read the VM’s result, not text the script printed.
A debugger that prints script logs on the same stream as its result can be fooled by a script that prints a result line.
Replay:
Replay
Stopped by
the same proof, same platform
nonce used once
a proof made for another platform
domain
another account on the same platform
account, and the stored message
another lock
the stored message, and P
testnet on mainnet, or the reverse
chain line, against the platform’s configuration and the node
an old proof
issued at window
the proof sent to the chain
its input does not exist
A proof shows control at verification time. A key can be shared later, and for locks whose code is upgradable or whose settings live in cells, the keys that control a lock can change. Requirement 5 ties a binding to the cells its proof used.
Not covered:
relative time locks, and time-dependent conditions in general: the input is fabricated, and the lock sees the
since
the wallet sets, not the chain’s time;
locks whose signature does not cover the transaction hash;
locks that need more than one input or one witness;
locks that read the input’s capacity and could overflow on u64::MAX;
type scripts, which are never run.
Backwards compatibility
An earlier form of this proof put the output under the lock
{ code_hash: 0x00 * 32, hash_type: "data", args: 0x }
with capacity (41 + n) CKB and the tag
CKB lock proof v0\n
. It is a different transaction, a signature for one form does not open the other, and verifiers following this RFC refuse it at step 7.
Reference implementation and test vectors
ckb-ward
(
GitHub - LusoCryptoLabs/ckb-ward: Ward: lock proof for CKB. Prove control of any CKB lock with a proof transaction that can never land on chain. · GitHub
, npm
ckb-ward
) implements the message, the transaction, the verifier, and three runners: one built from the node’s own script crates, one on ckb-debugger, and one on ckb-vm-js in a browser. It carries 17 signed proofs, each replayed by its tests with the expected exit codes for the proof and for controls: secp256k1 (testnet and mainnet), JoyID main key (testnet and mainnet, signed in the JoyID app), JoyID sub key, a 2-of-3 multisig, anyone-can-pay, Omnilock in Dogecoin, Ethereum and Bitcoin modes, PW-lock (testnet and mainnet), the Nostr lock, the quantum-resistant lock with an SLH-DSA key (testnet and mainnet), and a smart-account lock in two configurations. The full byte-exact vectors are in its
docs/SPEC.md
.
CCC’s signer JSON-RPC rebuilds the input cell as described above, so a wallet connected through it can sign a proof for any of its locks. The change (ckb-devrel/ccc#641) is merged into CCC’s development branch and not yet in a release.
Link