Keyholder guide: sign a lending action
Lending has its own governance boxes: a status box (which pools are open, paused or wound down) and a release box (upgrades and the upgrader keys). A lending action, such as a pause or an upgrade, is one Ergo transaction that several keyholders sign together, as a DEX action is. The lead proposes, each signer checks the proposal on their own node, and the signers sign in a round of steps, each on their own node.
What’s different is the check: for a lending action, kadia-verify asks lending’s own checker whether the transaction is safe to sign.
What the check trusts
Section titled “What the check trusts”Lending’s checker judges the transaction against a request: lending’s governance settings, which key belongs to which keyholder, the upgrades that have been reviewed, and the current block height. kadia-verify builds that request itself, only from what you control:
- lending’s governance settings, from the lending launch manifest you pinned;
- which key belongs to which keyholder, from the keys file you pinned;
- the upgrades you’ve reviewed, from your reviewed list, if you keep one;
- the current block height, from your own node.
The proposal supplies only the transaction and the boxes it spends, which kadia-verify reads from your own node. If someone hands you a request of their own, kadia-verify compares it with your files and your node’s height before anything else, and refuses it on any difference.
Three checks before anything is signed
Section titled “Three checks before anything is signed”At every step of the round, before your node signs anything, kadia-verify checks three things and stops if any fails:
- Lending’s checker says OK TO SIGN on the request built from your files. kadia-verify runs the checker as the exact program you pinned, and refuses any other.
- None of the transaction’s inputs belongs to your own wallet. A governance action spends lending’s boxes, never yours.
- Your node commits only for keys the checker expects. For each input, the checker reports which keys may sign it. Your node commits only for the keys your own wallet holds, so its keys must be among those. A key outside them is refused.
At the last step, kadia-verify also checks that the signed transaction is exactly the one that was checked. A node that signs a different transaction is refused.
If a check refuses, the command says REFUSED with the reason, and exits with status 2.
Each step
Section titled “Each step”Each signer runs one command per step, on their own machine:
kadia-verify lending step <commit|lead|cosign|final> <envelope.json> \ --manifest <lending manifest> --keys <keys file> [--reviewed <reviewed list>] \ --deploy <kadia-deploy> --node http://127.0.0.1:9053 --api-key-file key \ --key <your public key> --signers <key>,<key>,... \ --nonce-dir <dir> [--hints <file>]... [--out <file>] [--signed-out <file>]<envelope.json>is the proposal: its transaction and the boxes it spends.--manifest,--keysand--reviewedare your own pinned files. Don’t take them from the proposal or the lead.--deployis lending’s checker, kadia-deploy, at the version you pinned. kadia-verify checks its fingerprint before running it.--nodeis your own node. Its wallet holds your key, and it gives the height and the boxes.--keyis your public key.--signerslists the public keys of everyone signing this round.--hintspasses the others’ public output from earlier steps.
kadia-verify lending --help prints the full usage. Leave out --secrets: it sends a test key to the node with each request, and is only for test networks. Never put a real key in a file.
Your nonce is used once
Section titled “Your nonce is used once”As in a DEX round, your commit step asks your node for a commitment. Its secret half is written to a private file in your --nonce-dir. Only you can read it, and it’s never printed. It’s deleted as soon as you sign. A second commitment for the same transaction is refused, so if a round fails, start again with fresh commitments.
Share only the public output of each step (the --out file). Never share the nonce file, your node’s API key or anything from your wallet.
The order of the round
Section titled “The order of the round”A is the lead. B, C and D are the co-signers:
| Round | Steps |
|---|---|
| Three signers | commit (B and C), then lead (A), then cosign (B), then final (C) |
| Four signers | commit (B, C and D), then lead (A), then cosign (B), then cosign (C), then final (D) |
Lending’s upgraders on testnet are 3 of 5. With six keyholders, an upgrader action needs four signers. The four-signer order has been tested only against simulated nodes so far.
Still to come
Section titled “Still to come”- Passing a lending round’s public output through the mailbox, as for a DEX round, isn’t tested for lending yet. Until it is, pass it by a private channel.
- A four-signer round on a real node, then a round on testnet.
Back to what a keyholder does.
Technical details
Source: kadia-dex develop at commit d85102a (d85102a5d0ff4e43f5a6657c5b47fa3d6da239aa, PR #348, on #342’s 486dd7e):
packages/kadia-verify/src/lending_cli.rs:kadia-verify lending stepand its usage. Exit 0 means done, 2 refused, 1 anything else.src/lending.rs:pins_from_files,build_requestandcheck_supplied. They build the govVerify request from the pinned manifest’sgovernance, the keys file’sdirectory, the reviewed list and the node’s tip. A supplied--requestis refused on any difference from the pins or the tip, before any node call.src/lending_round.rs: the EIP-11 round. It holds the three pre-sign checks (check_verdict,check_no_wallet_input,check_node_reduction), the single-use nonce, andfinal’s check of the signed transaction’s id.src/govverify.rs: govVerify run through the pinned kadia-deploy, built from kadia-lending ata7bea30and checked by sha256 before it runs.tests/lending_round.rs:a_four_signer_round_completes_and_each_nonce_is_used_once, for the four-signer order, on scripted nodes.- The devnet run: the L-7 rotation proposal, three signers of five keys as on testnet today, transaction
93a67fb4…, confirmed at height 7,962 (examples/lending_l7_devnet.rs). - The mailbox: kadia-gov-store accepts a lending proposal (
keyholder propose, tested). Posting a round’s contributions for lending isn’t tested separately.