Keyholder guide: verify and sign a proposal
A DEX governance action is one Ergo transaction that several keyholders sign together: 2 of 6 for a guardian action, 4 of 6 for an upgrader action (on testnet today, 2 of 5 and 3 of 5). Ergo’s node wallets sign it in a round of steps, each keyholder on their own node. A public mailbox (kadia-gov-store) carries the public parts between you, and the console’s inbox shows where the round is.
Who does what
Section titled “Who does what”- The lead proposes. That’s the first key in the proposal’s list of signers (its quorum).
- The co-signers are the other keys in the quorum.
- Anyone else may read the proposal, but can’t post to it.
1. The lead posts the proposal
Section titled “1. The lead posts the proposal”The lead creates the proposal in the governance console and posts it to the mailbox. The mailbox answers with:
- a link to the proposal;
- a token for each signer. It shows them once, and stores only their hashes.
The lead sends each co-signer the link and their own token, by a private channel. Both are capabilities: whoever has the link can read the proposal, and a token lets its holder post as that signer. Keep them private.
The mailbox has rules of its own. It refuses a proposal for the wrong network, and a second open proposal on the same governance box. It refuses any document with a field named like a secret (secret, private, seed, mnemonic, nonce), and never stores it. A proposal expires after 3 days, together with its tokens and everything posted to it.
2. Each signer checks it, twice
Section titled “2. Each signer checks it, twice”In the console: open the link. The inbox reads the proposal and checks it again against the site’s node: every input must be on chain, and the transaction must rebuild exactly. If it says “This proposal didn’t pass this site’s check. Don’t sign it.”, stop.
On your own node, which is the check that counts: save the proposal document from the mailbox. It’s the data.proposal part of the mailbox’s answer. <id> is the last part of the link, and <site> is the site you opened it on:
curl -s https://<site>/api/gov/testnet/v1/proposals/<id> | jq .data.proposal > proposal.jsonThen check it:
kadia-verify show proposal.json --pins pins.json --node http://127.0.0.1:9053 --api-key-file keykadia-verify checks:
- the network and genesis block, against your pins and your node;
- that every input exists on your node and matches its id;
- that the transaction rebuilds from your node’s boxes to the proposal’s exact id, with nothing backdated;
- that the governance box is your pinned script and NFT, and that the action is the one the proposal names, and one-way exactly when it says so;
- that the new state is sound: thresholds within the number of keys, no repeated keys, and announced contracts among your reviewed hashes if you pinned them;
- that the named signers can actually sign it.
It prints the change in words, who must sign, and the clocks, then OK TO SIGN or REFUSED: <reason>. Sign only after OK TO SIGN, and only once you’ve read the change it describes. kadia-verify stops a different transaction, an extra wallet input, a wrong network, an unknown hash or key, and a reused nonce. It can’t stop you signing something you didn’t read.
3. Run your steps, in order
Section titled “3. Run your steps, in order”Each signer runs kadia-verify step for their part. It runs show again first and refuses unless it says OK TO SIGN.
kadia-verify step <commit|lead|cosign|final> proposal.json --pins pins.json --node http://127.0.0.1:9053 \ --api-key-file key --nonce-dir <dir> [--hints <file>]... [--out <file>] [--signed-out <file>]The order, with A the lead and B, C the co-signers:
| Round | Steps |
|---|---|
| Two signers (a guardian action) | commit (B), then lead (A), then final (B) |
| Three signers (an upgrader action on testnet today) | commit (B and C), then lead (A), then cosign (B), then final (C) |
kadia-verify documents these two rounds. The order for four signers, an upgrader action with six keyholders, is pending confirmation.
commitasks your node for a commitment. The secret half is written to<dir>/<txid>.nonce(only you can read it, and it’s never printed); the public half is the output you share.leadandcosignsign with the others’ public parts (--hints), and output the next public parts.finalcompletes the transaction and checks it with your node (--signed-out).
Share only the public output of each step: the --out file of public hints, through the mailbox. Never share the nonce file, your node’s API key or anything from your wallet.
Passing hints through the mailbox
Section titled “Passing hints through the mailbox”Your --out file and the mailbox use different shapes, so a small tool moves hints between them: kadia_gov_store.keyholder, from kadia-dex’s packages/kadia-gov-store. It needs only Python 3.11 or later. Run it from a kadia-dex checkout at the commit you reviewed. <store> is the mailbox through the site you opened the proposal on, https://<site>/api/gov/testnet/v1.
After each of your steps, post your public hints with your own token:
PYTHONPATH=packages/kadia-gov-store/src python3 -m kadia_gov_store.keyholder post \ --store <store> --proposal <id> --token-file <your token file> --public-key <your public key, hex> --hints <your --out file>It posts only the hints for your key. It refuses a file with any secret field, and it never sends the node’s secret commitment. A hint already posted is reported as already posted.
Before lead, cosign or final, fetch the others’ hints into a file for --hints:
PYTHONPATH=packages/kadia-gov-store/src python3 -m kadia_gov_store.keyholder hints \ --store <store> --proposal <id> --out hints.jsonA nonce is used once. kadia-verify moves it aside before signing and deletes it after, whatever happens. If a round fails or is disputed, start again with fresh commitments: run with --discard-nonce, and the others commit again.
4. Send it
Section titled “4. Send it”Once enough keyholders have signed, the complete transaction is sent from a keyholder’s own node; the console assumes the lead sends it. The inbox then shows it as sent, and as executed once it’s in a block, with a link to the transaction.
The console’s safety rules
Section titled “The console’s safety rules”- A one-way action waits 24 hours after it’s posted before anyone may sign: applying new upgraders, giving up upgrades, and moving the treasury to new keys. The inbox shows the hold as a deadline and doesn’t mark it “your turn” until it ends. The exception is wind-down, the emergency stop. If someone signed during the hold, don’t send it: the lead voids the proposal and posts it again. The console doesn’t reliably flag this, so the lead checks the round’s contribution times against the hold before sending.
- Before posting a one-way action, the lead types its name back: “wind down”, “renounce”, “apply upgraders”, “move custody”.
- One action per proposal. The console never bundles two.
- A treasury payout shows its address and amount first, with “Treasury payouts can’t be recalled”. It’s checked against this site’s treasury, and a proposal for another treasury is refused.
When to stop
Section titled “When to stop”Don’t sign, and tell the other keyholders, if:
- kadia-verify says REFUSED, for any reason;
- the console’s check fails;
- the change in words isn’t what you were told the proposal does;
- you’re asked for a seed phrase, a key, your node’s API key or a nonce file. No real round ever needs them.
The lead can void a proposal with their token; then nobody can post to it:
PYTHONPATH=packages/kadia-gov-store/src python3 -m kadia_gov_store.keyholder void \ --store <store> --proposal <id> --token-file <lead token file> --reason "<why, at most 140 characters>"Technical details
Sources: kadia-dex packages/kadia-verify/README.md and packages/kadia-gov-store/README.md at commit f77779f (f77779f41090743865751e59cc3434b6756ed935, which adds the keyholder tool, kadia-dex #297); kadia-web apps/governance (the inbox); docs/ui-safety-checklist.md.