Skip to content

Latest commit

 

History

History
256 lines (218 loc) · 24.7 KB

README.md

File metadata and controls

256 lines (218 loc) · 24.7 KB

module/tests

Run them

One command runs every test that needs no chain — 99 unit tests and the 55 invariant probes under probes/, in parallel:

tests/run-suite.sh                  # unit tests + probes
tests/run-suite.sh probes           # the probes only (unit: the unit tests only)
tests/run-suite.sh frost lez_tx     # the tests whose path contains any of these substrings
tests/run-suite.sh e2e <name>       # one chain-bound test, by name (below)

The runner materializes the Nim closure at the revs ../metadata.json pins (codegen.nim.packages) with ../tools/nim-closure.sh, into ~/.cache/muster/nimpkgs, so a local run compiles against the same sources the .lgx does. It takes libsodium from nixpkgs (and, for the host-return probe, secp256k1 and g++), and builds every test with one flag set: the union of the $SECP, $STINT, web3, SDK and libsodium flags below. An extra --path is harmless to a pure-Nim test. Each test's log lands in $OUT (a fresh temp dir unless set), and the summary names every failure. Env: JOBS (8), TEST_TIMEOUT (900 s), TEST_ARGS (appended to each selected test's command line, for an e2e test's own arguments), MUSTER_NIMPKGS (the closure dir).

On macOS (arm64) the same command runs under the stock /bin/bash 3.2, given Nix and a working git and python3 (the closure fetch needs both; /usr/bin's are the Xcode Command Line Tools'). It links nixpkgs' libsodium.dylib (no glibc to match, so no nixpkgs gcc). With no nim on PATH it takes the nim and the clang the .lgx compiles with: nixpkgs#nim and #stdenv.cc at the nixpkgs ../flake.lock pins under logos-module-builder (in a fresh clone, which has no flake.lock until a first build, the builder's own lock, read with nix flake metadata), the clang first on PATH, since nim runs clang from there. With no timeout it uses nixpkgs coreutils'.

Chain-bound tests never run by default. Bring the chain up first (on-chain tests), then run one by name:

test chain arguments (defaults)
safe_anvil_e2e, safe_real_anvil_e2e, coordinate_submit_anvil anvil + the Safe fixture, infra/anvil/devnet.sh <safeAddr> [rpcUrl] (http://127.0.0.1:8545) — the Safe address is required
btc_regtest_e2e, phase_d_exit_test a fresh Bitcoin Core regtest, infra/bitcoind/regtest.sh [rpcUrl] [user] [password] (http://127.0.0.1:18443, muster, muster)
lez_multisig_live_e2e, lez_frost_account_e2e, lez_frost_room_e2e a LEZ v0.2.4 sequencer, infra/lez/localnet.sh, or the public testnet [sequencerUrl] [blockSeconds] (http://127.0.0.1:3040, 15); lez_multisig_live_e2e also reads MUSTER_LEZ_MULTISIG_BIN
lez_frost_v030_e2e, lez_frost_room_v030_e2e, lez_multisig_live_v030_e2e a local LEZ v0.3.0 zone, infra/lez/localnet.sh, or the testnet (https://testnet.lez.logos.co 40) once its funder holds LEZ: every account the tests use is funded by the zone's funder, infra/lez/funder.sh, MUSTER_LEZ_E2E_FUND base units each (default 1 LEZ; on the testnet 50000000 for the multisig, 200000000 for FROST) [sequencerUrl] [blockSeconds] (http://127.0.0.1:3040, 15); lez_multisig_live_v030_e2e takes the deployed v0.3 multisig's program account as a third argument or MUSTER_LEZ_MULTISIG_V03_PROGRAM, or deploys the port's guest first when MUSTER_LEZ_MULTISIG_V03_BIN names it (localnet.sh deploy)
quest_room_v030_e2e a local LEZ v0.3.0 zone, infra/lez/localnet.sh, with the multisig port and programs/lez-quest deployed [sequencerUrl] [blockSeconds] [multisigProgram] [questProgram]; or MUSTER_LEZ_MULTISIG_V03_BIN and MUSTER_LEZ_QUEST_BIN name the two guests to deploy first (exo-267.8)
circle_rounds_v030_e2e a local LEZ v0.3.0 zone, infra/lez/localnet.sh, with the multisig port deployed [sequencerUrl] [blockSeconds] [multisigProgram]; or MUSTER_LEZ_MULTISIG_V03_BIN names the guest to deploy first (exo-267.3)
circle_exit_v030_e2e a local LEZ v0.3.0 zone with the multisig port and programs/lez-quest deployed [sequencerUrl] [blockSeconds] [multisigProgram] [questProgram]; or MUSTER_LEZ_MULTISIG_V03_BIN and MUSTER_LEZ_QUEST_BIN (exo-267.5)
split_anvil_e2e any fresh anvil (chain id 31337, its default funded accounts; no Safe) [rpcUrl] (http://127.0.0.1:8547)
settle_up_across_anvil_e2e any fresh anvil (chain id 31337, its default funded accounts); the Bitcoin split it covers needs no node — it goes final by its creditor's word [rpcUrl] (http://127.0.0.1:8545)
SAFE=$(infra/anvil/devnet.sh | grep -oE '0x[0-9a-fA-F]{40}' | tail -1)   # from the repo root
TEST_ARGS="$SAFE" module/tests/run-suite.sh e2e coordinate_submit_anvil
TEST_ARGS="https://testnet.lez.logos.co 40" module/tests/run-suite.sh e2e lez_multisig_live_e2e

The exophial spec oracles under probes/ are graded the same way the runner runs them (scripts/grade-specs.sh drives exophial's oracle over contracts/specs/).

What the tests cover

Most tests are named for what they check. These carry more than their name says, grouped by the phase that added them; the "needs" notes are the flags a hand run wants (below), which the runner supplies.

Signing path, log, and the room.

  • dcbor_golden_test (known-answer bytes for invariant 5, hand-computed from RFC 8949: width boundaries, the CDE-vs-length-first ordering discriminator, hash-input framing; it catches a byte-order flip the property probes pass)
  • manifest_test
  • schema_coverage_test (the card recognizes every effect a built driver canonicalizes, under the schema id the driver signs over — so no built family's card is schema-unknown with its Approve hidden; found: LEZ-FROST's lez-call)
  • manifest_precision_test (exo-ec8 — every generated manifest says exactly what its action needs, touches and discloses: unique touches, chains in CAIP-2 and accounts in CAIP-10, the environment requirement named as environment(); a Safe payee only on a transfer, an amount on a transfer (even a template), on a call only when ETH moves, never on a delegatecall; a Safe's signers, policy, nonce and gas public; a LEZ action naming every account it passes and the program it calls; lez-rpc, not lez_core, on the live LEZ paths)
  • distinct_signer_test (exo-a5a — a k-of-n decision needs k distinct signers: a contribution counts only under the name of the signer the driver identifies, checked before dedup; one signature under two names is one approval, a forgery never takes a member's slot, governance cannot be completed alone; threshold and Safe; $SECP + $SODIUM)
  • card_words_test (exo-59c — the card and the room history say what each family's intent does, over every generated (kind, variant): no proposal reads as "a payment: 0 →"; a Bitcoin spend names its payment output (change excluded) in sat, a LEZ transfer its amount in token units, a module action its call; submit/final lines follow the family's settlement; contributors are named from the address book by identity, Ed25519 key or secp address; "approved by me" is read from the log + this member's keys, and a key binding counts only when its own signer is that approver)
  • store_node_view_test (exo-661.7 — what a store node reads off a room's topic: over the app's join-by-name flow (two founders, one admits the other, a non-founding member admits a third), no member's Ed25519 key, X25519 key, secp256k1 address or binding signature appears in any retained frame, no data or grant frame carries an epoch tag at either end, and each asker still reads from its own epoch on, F-16)
  • founder_restart_test (exo-7b3 — invariant 4 across a restart, over the app's join-by-name flow with keyfile keystores reopened from disk: a founder's message and proposal from before the first admit come back after a restart, and its state digest is unchanged, because epoch 0's key is the keystore's founding key for the room (Keystore.foundingKey), not a random one; F-16 still holds for a restarted joiner and a later one; a replay shows no admitted member as asking to join; every launch announces a join key the topic never carried, so a store node cannot link one member's launches)
  • authorship_test (exo-f76 — an author-bearing event counts only when its author signed it: forged, wrong-key, cross-room, tampered and malformed author events are dropped, genuine ones count, over the wire included; $SECP + $STINT + $SODIUM)
  • parts_fold_test (exo-a90.2 — settlement in parts, over a test driver that is not the split: the threshold comes from the parties the effect names (describeFor); a part is settled by its party and confirmed by the counterparty; any settled → submitted, any confirmed → settling, all confirmed → final; a report by a disallowed author, or before agreement, never counts; a bare submit / final never moves a parts intent; 200 reorder + duplicate trials converge)
  • split_driver_test (exo-a90.3 — the split's one spelling and every refusal, only a named debtor's room key agrees, the parts, conformance, the each-locus profile and card rows, evm-split@ resolution, even shares, the room fold to final on the real driver)
  • split_live_test (exo-a90.4 — paying and confirming on the live room path over a fake ledger: no payment before agreement, the payment is the derived share, the report waits for the payer's tx, the creditor confirms only what her read shows, one tx settles one share, received outside muster, expiry refuses a payment)
  • log_proof_test
  • malformed_sig_test (exo-cf7 — a malformed signature is never fatal: the verifiers, both owner-signature drivers, the fold with a hostile approval in the log, join-request bindings, authorizations; needs $SECP + $SODIUM)
  • decline_test
  • provenance_all_test
  • flow_test
  • room_infra_test (exo-428 — the room's infrastructure is dictated by its drivers; also needs $SECP for the real Safe driver)
  • rpc_url_redaction_test (exo-14f.2 — a configured RPC URL never reaches text whole: wallet/redact.nim shows scheme, host and port, *** for userinfo and for any path, query or fragment; the split composer's "your RPC did not answer", the room's RPC connectivity row (which the MUSTER-LP debug log prints) and the readiness card's details carry neither user:pass@ nor a /v3/<key> path, against an endpoint that refuses and one that answers; web3 + $SECP + $SODIUM)
  • materialshare_test (exo-45e K5)
  • schema_unknown_test (exo-1ec.3 — the schema-driven rendering gate)
  • action_corpus_test (exo-661 A2 — the action atlas's generated half: contracts/actions/generated.json must equal what tools/action_corpus.nim reads off the running drivers — describe / environment / profile / manifest / signRefusal for each fixed (kind, variant) — byte for byte; regenerate with TEST_ARGS=--write tests/run-suite.sh action_corpus; $SECP + $STINT + web3 + $SODIUM)

Phase A — Safe and the family profile.

  • phase_a_exit_test (exo-a50.1.7 — Phase A exit: two Safes, two chains, two rooms, no globals, card rows only from the profile; needs $SECP + $STINT)
  • settlement_test (exo-a50.1.5 — the settlement seam: chosen by profile, assembled from the log, submitted through the ChainAdapter; needs $SECP + $STINT)
  • safe_fidelity_test (exo-a50.1.4 — every SafeTx field reaches the signed hash, the real ten-argument execTransaction, delegatecall disclosed + refused unless allowlisted, modules/guard decoding; needs $SECP)
  • accounts_test (exo-a50.1.3 — accounts disclosed by members into the room; two Safes on two chains in one room; the chain check; needs $SECP)
  • kinds_test (exo-a50.1.2 — the one list of driver kinds; an unknown kind refuses, never a silent Safe; needs $SECP)
  • profile_test (exo-a50.1.1 — every driver declares its multisig family profile, held to describe() and to contracts/families/registry.json both ways; needs $SECP)

Phase B — Bitcoin through PSBT.

  • btc_outside_signer_test (exo-a50.2.6 — signers outside muster, seam S8: a Bitcoin intent exports as a PSBT, an outside signer's PSBT imports as counted + unattested, another spend's refused; readiness asks the Bitcoin node which chain it serves; needs $SECP)
  • btc_settlement_test (exo-a50.2.5 — the Bitcoin settlement: a spend built from UTXOs, only driver-accepted signatures, P2WSH + tapscript witnesses finalized in script key order, the reviewed tx broadcast; needs $SECP + $STINT)
  • btc_inapp_test (exo-a50.2.4 — a member signs Bitcoin in-app through the keystore, attested; an outside signature counts, unattested; needs $SECP)
  • btc_driver_test (exo-a50.2.3 — the Bitcoin multisig driver: P2WSH sortedmulti + tapscript multi_a accounts, sighashes, contributions, conformance, signRefusal, kinds, PSBT both ways; needs $SECP)
  • psbt_test (exo-a50.2.2 — PSBT v0 + BIP-371 against the BIP-174/371 vectors; the canonical form never hashes PSBT bytes; pure Nim)
  • bitcoin_primitives_test (exo-a50.2.1 — Bitcoin primitives pinned to the official BIP-143 / BIP-340 / BIP-341 / BIP-350 vectors in tests/vectors/; needs $SECP)

Phase C — the LEZ multisig.

  • lez_multisig_rebuilt_test (exo-3c9 — the rebuilt program's account-ids layout: target accounts committed + bound at execute, checked on the S5 re-read; the card names no bypass; count-only keeps #40; §5 holds the decoder and PDA derivation to real chain bytes, from a local LEZ v0.2.4 sequencer (vectors/lez-multisig-v024/) and from the public testnet deployment (vectors/lez-multisig-testnet/); the room accepts the testnet multisig as a lez:testnet account)
  • lez_tx_test (exo-3c9: LEZ v0.2.4 public transactions byte for byte against LEZ's own crates, vectors/lez-tx-v024/ + its generator: instruction words, message borsh + hash, BIP-340 witnesses, sendTransaction payload, deployment, base58 ids; needs $SECP)
  • lez_member_keys_test (exo-3c9: fresh LEZ member keys per label, derived in the keystore, never exported; $SECP + $SODIUM)
  • lez_multisig_live_e2e (exo-3c9: the room drives the program on a REAL v0.2.4 chain: infra/lez/localnet.sh, or the public testnet with https://testnet.lez.logos.co 40; args [sequencerUrl] [blockSeconds], MUSTER_LEZ_MULTISIG_BIN deploys first; needs the web3 closure (chronos, json-rpc, bearssl) + $SECP + $SODIUM)
  • phase_c_exit_test (exo-84f — the Phase C exit: the LEZ multisig vote locus against the program model: disclose + verify, propose on chain, a member's own vote after an S5 re-read, a mismatched pointer refused before any vote, settle on the chain's count, the card; needs $SECP)
  • lez_settlement_test (exo-0c9 — count the votes on chain, re-read at settle, Execute, final when Executed)
  • lez_vote_test (exo-12a1 — voting in the room: S5 read, cast, confirm, receipt + room-key attestation; refusals cast and publish nothing; needs $SECP)
  • lez_multisig_driver_test (exo-6cbe — the vote-locus driver: disclosure with config, pointer effect, receipts, S5 checkRead, profile/conformance; needs $SECP)
  • lez_multisig_chain_test (exo-946 — the chain seam + FakeLezMultisig, the program's handlers in process; pure Nim)
  • lez_multisig_model_test (exo-a26 — lez-multisig's borsh state/proposals, SPEL seeds, versioned PDAs; pure Nim)
  • lez_readiness_test (exo-44b L1)

Phase D — FROST.

  • frost_dkg_sign_test (Phase D — a 2-of-3 ChillDKG key signs under FROST as one BIP-340 signature libsecp accepts; recovery; needs $SECP + $STINT)
  • frost_keystore_test (S7: host keys, the ceremony steps, nonces consumed before use, shares recovered from public recovery data, a restart aborts; $SECP + $STINT + $SODIUM)
  • btc_frost_driver_test (the btc.frost-bip445 driver: account from recovery data, key-path sighashes, round-tagged contributions, aggregation into one witness signature, the profile)
  • frost_ceremony_room_test (the ceremony and both rounds over a three-member room's log)
  • phase_d_exit_test (Phase D exit on a FRESH regtest bitcoind: in-room ChillDKG, then a spend Core cannot tell from single-sig)
  • lez_frost_account_e2e (a FROST key owns a LEZ public account on a real v0.2.4 sequencer; web3 closure)
  • lez_frost_room_e2e (exo-55e: a FROST group acts on LEZ from the room — in-room ceremony on lez:local, a lez-call at the chain-read nonce, both rounds, settled; a stale nonce refused; web3 closure + a local sequencer)
  • frost_chilldkg_test (exo-fae — ChillDKG against all 249 draft vectors in tests/vectors/chilldkg/)
  • frost_signing_test (exo-d7e — BIP-445 FROST signing against all 266 draft vectors in tests/vectors/bip-0445/)
  • frost_group_test (exo-b9c — points with infinity, scalars mod n; BIP-340 in those operations agrees with libsecp)

Monero (epic exo-dcc, ADR-018).

  • monero_address_test (exo-dcc.5 — src/monero/address.nim held to monero-project/monero at 24272e4: block-wise base58 against tests/unit_tests/base58.cpp; every network's standard, subaddress and integrated address from tests/functional_tests/validate_address.py, with the keys and payment ids the functional tests state; check_address's key refusals, including a point outside the prime-order subgroup; the CAIP-2 references re-derived from cryptonote_config.h's genesis constants; acceptablePayTo's refusals; make_uri / parse_uri and their amount and percent-encoding rules; $STINT)

Running one test by hand

Materialize the closure once (or let the runner do it), then build the flag groups from it. Every command below runs from module/.

D=$(tools/nim-closure.sh)     # ~/.cache/muster/nimpkgs, at metadata.json's pins
SECP="--path:$D/nim-secp256k1 --path:$D/nim-stew --path:$D/nim-results --path:$D/nimcrypto"
STINT="--path:$D/nim-stint --path:$D/nim-stew --path:$D/nim-results --path:$D/nim-intops/src"
W3="--path:$D/nim-eth --path:$D/nim-web3 --path:$D/nim-chronos --path:$D/nim-chronicles \
    --path:$D/nim-bearssl --path:$D/nim-faststreams --path:$D/nim-json-rpc \
    --path:$D/nim-serialization --path:$D/nim-json-serialization --path:$D/nim-http-utils"
SODIUM="--passL:$(nix build nixpkgs#libsodium --no-link --print-out-paths)/lib/libsodium.so"
nim r -d:release --threads:on $SECP $STINT $SODIUM tests/epoch_crypto_test.nim

Which group a test needs:

  • None — pure Nim: dcbor_golden_test, manifest_test, log_proof_test, psbt_test, lez_multisig_chain_test, lez_multisig_model_test, and most probes.
  • $SODIUM — anything whose import closure reaches crypto/curve25519 (the Ed25519/X25519 encryption identity), which is most of the room: decline_test, provenance_all_test, flow_test, materialshare_test, schema_unknown_test, lez_readiness_test, and every test that seals or encrypts (epoch_crypto_test F-16, keystore_test, coordination_test, multiparty_intent_test, coordination_surface_test, membership_handshake_test, store_node_view_test, founder_restart_test, two_instance_test — the full cross-host journey — governance_test, threshold_fold_test).
  • $SECP — anything importing src/crypto/secp256k1.nim or a secp-signing driver (secp256k1_test, safe_test, safe_collect_test, binding_test, conformance_test, readiness_test, authorization_test, and the crypto and coordination tests). nim-secp256k1 vendors and compiles its own C (the closure clones it with its submodule); no system libsecp256k1 is linked.
  • $STINT — amounts: wallet_types_test alone; with $SECP + $SODIUM for wallet_mock_test, material_test, offers_test, null_ladder_test and the holdings-catalogue probe probes/probe_catalogue_no_leak.nim (spec derived-exo-45e).
  • $W3 — nim-eth and the web3 stack: wallet_verify_test (the reused nim-eth proof primitive), wallet_sign_test (EIP-155 signing vs the canonical vector), wallet_rpc_test, rpc_budget_test, and anything importing evm_adapter (wallet_evm_test, coordinate_submit_anvil), a LEZ chain seam (lez_multisig_live_e2e, lez_frost_*_e2e), drivers/safe_rpc.nim — whose calls run on chronos under wallet/rpc_budget.nim since exo-14f — directly or through readiness / settlement (safe_owners_test, safe_fidelity_test, settlement_test, readiness_test), or wallet/btc_adapter.nim, whose node calls run on chronos's HTTP client since exo-496 (the btc_* and Bitcoin split tests, the regtest e2e tests, the btc probes). websock is deliberately not needed: the code imports web3/eth_api + json_rpc/clients/httpclient (and chronos/apps/http/httpclient), not top-level web3.

The host-return probe

probes/probe_return_marshalling_host.nim (spec derived-exo-526) builds the host harness probes/host_return_harness.nim with the module compiled in, and reads what a CLIENT observes. The harness calls the module's logos_module_* C ABI through importc, and the module's own constructor (the one the generated surface installs, as in the plugin) initializes the one Nim runtime, so the harness is built --noMain. It was C++ linked against a staticlib until exo-607 T7; a Nim harness cannot link a second Nim runtime, and the port's trace is identical to the C++ one's. Its inner nim c reads the closure from $MUSTER_NIMPKGS (default ~/.cache/muster/nimpkgs), and the harness links secp256k1 and libsodium: an explicit MUSTER_SECP256K1_LIB / MUSTER_SODIUM_LIB wins, then pkg-config, then a filesystem glob over /nix/store. The harness defines the lp_* inter-module ABI as a host with no protocol stack and reports lp_stub_calls (0: nothing the probe calls reaches another module).

tests/run-suite.sh return_marshalling

On-chain tests

anvil + the Safe fixture. infra/anvil/devnet.sh starts anvil, deploys and funds the real Safe v1.4.1 (singleton, factory, fallback handler, a 2-of-3 proxy), and prints SAFE_ADDR. Each test takes <safeAddr> [rpcUrl]. They share the Safe's nonce, so the runner runs e2e tests one at a time. safe_anvil_e2e and coordinate_submit_anvil each assume a fresh devnet (each signs its first transaction at nonce 0, and safe_anvil_e2e expects an unfunded recipient), so give each its own: restart the devnet between them (pkill -x anvil; infra/anvil/devnet.sh). safe_real_anvil_e2e reads the live nonce and runs on any devnet.

  • safe_anvil_e2e — the single-instance path: collect 2-of-3 owner signatures locally, assemble execTransaction, submit, confirm the transfer on-chain.
  • safe_real_anvil_e2e — against the contract itself: muster's safeTxHash equals the Safe's own getTransactionHash for a transaction that uses every field; the disclosure check reads getOwners + getThreshold and the bypasses (modules, guard) from the chain; a data-carrying CALL executes through the ten-argument execTransaction.
  • coordinate_submit_anvil — the ROOM-SIDE path (coordinate_submit): the owner signatures travel through the coordination log (propose + contribute events); the room folds to executable, the signatures are gathered from the log, assembled, and submitted through the adapter. A successful execTransaction proves the room's re-derived safeTxHash matches the contract's on-chain getTxHash.

Bitcoin Core regtest. infra/bitcoind/regtest.sh starts a FRESH regtest chain (RPC 127.0.0.1:18443, muster/muster, -txindex; nix shell nixpkgs#bitcoind provides the binaries). Stop any other instance first: phase_d_exit_test needs a fresh chain.

  • btc_regtest_e2e — the Phase B exit (exo-a50.2.7). For both btc.p2wsh-sortedmulti and btc.tapscript-multi-a: muster derives the address Bitcoin Core derives from the descriptor; funds it and builds a spend from the UTXOs the node reports; a member approves in-app through the keystore (attested); an outside signer — a Bitcoin Core wallet holding the third key — signs muster's exported PSBT and the imported signature counts, graded unattested; the settlement finalizes the witnesses and the adapter broadcasts; final a block later, the payee paid.
  • phase_d_exit_test — the Phase D exit: an in-room ChillDKG, then a spend Core cannot tell from single-sig.
nix shell nixpkgs#bitcoind -c bash infra/bitcoind/regtest.sh   # from the repo root; `… regtest.sh stop` stops it
module/tests/run-suite.sh e2e btc_regtest_e2e

A LEZ v0.2.4 sequencer. infra/lez/localnet.sh runs one on 127.0.0.1:3040 (the first build takes 5–15 minutes; its header lists the toolchain, including what a machine with no system g++ needs, and docs/labbook/lez-multisig-versions.md the reasons). lez_multisig_live_e2e deploys the program first when MUSTER_LEZ_MULTISIG_BIN names the guest — make build in logos-co/lez-multisig (PR #45 or later), which reproduces the testnet's ImageID 2ced3d30…d4c7. The public testnet works too: TEST_ARGS="https://testnet.lez.logos.co 40".