Skip to content

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.

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.

At every step of the round, before your node signs anything, kadia-verify checks three things and stops if any fails:

  1. 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.
  2. None of the transaction’s inputs belongs to your own wallet. A governance action spends lending’s boxes, never yours.
  3. 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 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, --keys and --reviewed are your own pinned files. Don’t take them from the proposal or the lead.
  • --deploy is lending’s checker, kadia-deploy, at the version you pinned. kadia-verify checks its fingerprint before running it.
  • --node is your own node. Its wallet holds your key, and it gives the height and the boxes.
  • --key is your public key. --signers lists the public keys of everyone signing this round.
  • --hints passes 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.

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.

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.

  • 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 step and its usage. Exit 0 means done, 2 refused, 1 anything else.
  • src/lending.rs: pins_from_files, build_request and check_supplied. They build the govVerify request from the pinned manifest’s governance, the keys file’s directory, the reviewed list and the node’s tip. A supplied --request is 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, and final’s check of the signed transaction’s id.
  • src/govverify.rs: govVerify run through the pinned kadia-deploy, built from kadia-lending at a7bea30 and 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.