parameters for chain exercises

[n13]

Summary

Adds two parameters to quantus exercise so the suite can run against any funded account — e.g. a public testnet — instead of requiring the genesis-funded crystal_alice dev account and ~4000 tokens.

What's new

• --root-account <NAME> (+ --root-password / --root-password-file) — the wallet that funds the run. Defaults to the built-in crystal_alice dev account, so existing --dev usage is unchanged. Threaded through the funding step and the wormhole scenario.
• --total-amount <TOKENS> (default 40) — total budget drawn from the root account, split evenly across the ephemeral test accounts.

How it works

• Discretionary test amounts (transfers, multisig funding, reversible, fuzz, …) are scaled down by a fixed DISCRETIONARY_SCALE = 100 via a new ctx.test_unit = unit / 100, so the suite needs ~tens of tokens instead of ~4000.
• Fixed, chain-imposed amounts are never scaled — existential deposit and the multisig / preimage / governance deposits are read from the chain, so they stay covered. That's why the practical floor is ~40 tokens, not ~1.
• Preflight + guards replace the old cryptic mid-run failure (Inability to pay some fees) with fast, actionable errors:
  • root-account balance check before any funding,
  • "budget too low to cover deposits" guard,
  • existential-deposit floor guard on the scale (a fresh account funded with test_unit/2 must stay above ED).
• The wormhole amount is intentionally left unscaled (50.0): it round-trips back to the wallet and draws from the separately-funded root account, so shrinking it saves nothing — and small per-proof amounts round below the on-chain minimum in later rounds (No transfer event found).

Caveat

The governance phase still relies on the dev genesis accounts (tech-collective membership), so pass --skip governance when using a custom root account on a public testnet. This is documented in --help.

Testing

• Local --dev node (spec 135 / tx 3): full suite 62/62 passing with --root-account crystal_alice --total-amount 40 — funds 4 ephemeral accounts at 10 DEV each; multisig, governance, preimage (all deposit-bearing) and wormhole all green.
• Live Planck testnet: preflight balance check, budget-too-low guard, and custom-root wallet loading all verified.

quantus exercise --skip governance \
  --root-account <wallet> --root-password <pw> \
  --total-amount 40 --node-url <ws-url>

Docs

quantus exercise was previously undocumented — added a Chain Exercise Suite section to the README (phases, dev-node vs. testnet usage, and a flag table). All new flags are also self-documented in --help.

[n13]

Verdict: REQUEST_CHANGES (opinion; GitHub does not permit a formal request-changes review on my own PR).

Two blocking correctness issues remain:

1. The documented custom-root testnet command still runs a dev-only vesting phase. src/cli/exercise/mod.rs:59-62 says only governance must be skipped, but setup replaces ctx.alice with the custom root. src/cli/exercise/scenarios/vesting.rs:294-310 then derives the well-known dev treasury from [ctx.alice, bob, charlie]; with any custom root, that prediction cannot match the configured dev treasury and the default vesting phase fails. Keep the scenario's dev Alice identity separate from the funding account, make vesting support a custom signer set, or fail/skip vesting up front and update the documented command and caveat.

2. --total-amount is not actually a hard cap on root-account spend. src/cli/exercise/runner.rs:52-90 reserves only transfer values before submission, excluding the root signer's transaction fees, and several root-signed calls bypass these helpers entirely. In particular, src/cli/exercise/mod.rs:355-360 budgets only two referendum submission deposits, while governance::referendum_flow also places and leaves locked the track's decision deposit (currently 1,000 tokens), plus root-paid preimage deposits and fees. A well-funded root can therefore spend far beyond the requested cap; a root funded only to the preflight amount can pass setup and fail mid-run. Route every root-paid fee/deposit/transfer through cap enforcement, include the runtime track's decision deposit, and verify that final spend cannot exceed the cap.

Validation on head 6ebb415c490ab250f3a497a7f2d35b87bbf3e652:

• git diff --check bdc9c4d...6ebb415 — passed
• SKIP_CIRCUIT_BUILD=1 cargo test --locked --lib cli::exercise:: — 2 passed (only existing fuzz-classification tests; the new budget/custom-root paths have no focused unit coverage)
• SKIP_CIRCUIT_BUILD=1 cargo clippy --locked --all-targets -- -D warnings — passed
• All six GitHub CI checks are green

[n13]

Verdict: REQUEST_CHANGES remains (opinion; GitHub does not permit a formal request-changes review on my own PR).

The live PR head is still 6ebb415c490ab250f3a497a7f2d35b87bbf3e652; no commits have been pushed since the previous review, so both blockers remain in the remote diff:

1. The documented custom-root testnet command still runs a dev-only vesting phase. src/cli/exercise/mod.rs:59-62 says only governance must be skipped, but setup replaces ctx.alice with the custom root. src/cli/exercise/scenarios/vesting.rs:294-310 then derives the well-known dev treasury from [ctx.alice, bob, charlie]; with a custom root this cannot match the configured dev treasury, so the default vesting phase fails. Separate the dev scenario signer from the funding account, support a custom vesting signer set, or reject/skip vesting up front and update the docs.

2. --total-amount still is not a hard cap on root-account spend. src/cli/exercise/runner.rs:52-90 guards transfer values only, excluding the root signer's fees, while direct root-signed calls bypass these helpers. src/cli/exercise/mod.rs:355-360 budgets only two submission deposits even though governance::referendum_flow also leaves the track's 1,000-token decision deposit locked, plus root-paid preimage deposits and fees. A sufficiently funded root can exceed the requested cap; a root funded only to the preflight amount can pass setup and fail mid-run. Account for every root-paid fee/deposit/transfer, include the runtime track decision deposit, and enforce the cap after each root-signed operation and at completion.

Fresh validation on the unchanged head:

• git diff --check bdc9c4d...6ebb415 — passed
• SKIP_CIRCUIT_BUILD=1 cargo test --locked --lib cli::exercise:: — 2 passed (only fuzz-classification tests; no focused coverage for these new paths)
• SKIP_CIRCUIT_BUILD=1 cargo clippy --locked --all-targets -- -D warnings — passed
• All six GitHub CI checks remain green

[n13]

Verdict: REQUEST_CHANGES remains (opinion; GitHub does not permit a formal request-changes review on my own PR).

The custom-root/vesting blocker from the earlier review is fixed: funding and dev identities are separated, and non-dev treasuries skip only the admin steps. Two blockers remain on head 67b20137ddd08f049a0c68fd435494c2070e56ba:

1. Root-paid multisig costs still bypass the hard cap. src/cli/exercise/scenarios/vesting.rs:350 submits create_multisig with reserved = 0, and line 427 does the same for each treasury proposal. submit_budgeted therefore checks only the extrinsic partial fee, but these calls also draw pallet-level funds from Alice: create_multisig burns MultisigFee (currently 0.6 token), while propose burns the dynamic ProposalFee (about 1.03 tokens for three signers) and reserves ProposalDeposit (1 token until execution). When the default root is dev Alice, a tightly capped vesting run can cross --total-amount; the final check reports the violation only after those funds have already been drawn. Pass the chain constants/dynamic proposal charge through reserved (including the temporary deposit headroom), and include them in setup's phase-needs calculation as appropriate.

2. The required format check is red. cargo +nightly fmt --all -- --check fails in src/cli/exercise/mod.rs, runner.rs, and scenarios/vesting.rs. GitHub's Fast Checks job fails for the same reason and skips the build/test, Clippy/doc, audit, and examples jobs. Run the pinned formatter and commit its output.

Validation:

• git diff --check bdc9c4d...67b2013 — passed
• SKIP_CIRCUIT_BUILD=1 cargo test --locked --lib cli::exercise:: — 2 passed
• SKIP_CIRCUIT_BUILD=1 cargo test --locked --lib cli::send::tests:: — 10 passed
• SKIP_CIRCUIT_BUILD=1 cargo clippy --locked --all-targets -- -D warnings — passed locally
• cargo +nightly fmt --all -- --check — failed as described above; CI Fast Checks failed and downstream jobs were skipped