Skip to content

ci: private 7-node test network with state-digest comparison - #15

Merged
EnzinoBB merged 5 commits into
masterfrom
testnet/ci
Oct 9, 2026
Merged

EnzinoBB merged 5 commits into
masterfrom
testnet/ci

Conversation

@EnzinoBB

@EnzinoBB EnzinoBB commented Oct 9, 2026

Copy link
Copy Markdown
Collaborator

Depends on #14 (the state digest): this branch is built on top of it, so its two commits also show here until #14 is merged.

What it adds

A private test network that runs on a GitHub runner, so nothing runs on the shared dev server:

  • .github/workflows/testnet.yml: runs nightly, on demand (workflow_dispatch), and on PRs labelled testnet. It builds the node, reusing the Boost and ccache caches of the CI, and runs the script below.
  • ci/testnet/gen_keys.py: writes node keys in the format the node reads (Base58 ed25519 public key and 64-byte libsodium secret). Without them the node prompts for keys interactively. Checked with node --dumpkeys.
  • ci/testnet/run.sh: creates one working dir per node (config.ini on 127.0.0.1 with its own port, APIs off, no NAT traversal; hosts.txt with the other nodes; trusted.txt with all of them as initial confidants), starts the nodes and follows their block height.

What it checks

  1. Every node writes blocks up to sequence 1100.
  2. Restart: around block 300 one node is stopped and started again. It must catch up, which exercises quick start from caches and the checkpoint chain check (csnode: check quick-start checkpoints against the chain before loading them #10).
  3. State digest: all nodes print the same STATE DIGEST at every sequence they share. #1000 from all 7 nodes is required.

Node logs and configs are uploaded as an artifact (14 days).

Design notes

  • 7 nodes: when the network bootstraps, an even set of ready nodes drops one, and at least 4 confidants are needed. With 7, the network keeps going while one node restarts.
  • Stays short: the run ends well before round 10'000 (StartingDPOS). After that a private network with no stake cannot elect trusted nodes.
  • No transactions yet: the genesis funds go to an address whose key nobody holds. Adding transactions is a follow-up.

🤖 Generated with Claude Code

EnzinoBB and others added 3 commits October 9, 2026 08:22
…lisation

Phase 1 of the state-root plan agreed with BK: an order-independent digest of
the wallet state that every node can compute and compare, out of block, so
nothing changes in the protocol.

- cs::MultisetHash: elliptic-curve multiset hash over ristretto255
  (libsodium, already linked through cscrypto). An item is mapped to a group
  element via BLAKE2b-512 and crypto_core_ristretto255_from_hash. The digest
  is the group sum, starting from the identity (32 zero bytes). Adding or
  removing an item costs O(1), about 50 us, independent of state size, and
  the result does not depend on insertion order. ristretto255 is used instead
  of raw ed25519 to avoid cofactor issues.
- cs::serializeWalletState(): canonical, versioned serialisation of the
  balance-relevant state of a wallet: key, balance, delegated amount, and
  delegations in both directions. Counterparts are sorted by key (std::map);
  entries are sorted because their order depends on apply/revert history.
  Empty for a wallet without such state, so empty records never move the
  digest. Little-endian, fixed-width fields.

Tests (tests/csnode/statedigest_tests.cpp): order independence, add/remove
inverse, distinct sets, empty wallet, balance and key sensitivity, delegation
order independence.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
… blocks

Wire the ECMH digest into MultiWallets, the single place where wallet records
are inserted or replaced (onWalletCacheUpdated).

- The digest is computed in full on the first call to stateDigest(). Node
  calls it right after the blockchain is loaded (slow or quick start), before
  taking part in the network. From then on, each wallet update removes the
  wallet's previous element and adds the new one. Slow-start replay does not
  pay a per-update cost.
- The element of each wallet is stored in its record (stateElement_). The
  delegation maps are shared_ptrs that Staking updates in place before the
  record is replaced, so re-serialising the old record would remove the
  wrong element. The element is not persisted; it is rebuilt at start.
- WalletsCache_Serializer aliases the MultiWallets container through a
  mirror WalletData type, so the mirror gets the same two fields (not
  serialised: the checkpoint format is unchanged). A static_assert on the two
  sizes now catches any future mismatch at compile time.
- Node logs "STATE DIGEST #<seq> <hex> wallets <n>" at start and on every
  block whose sequence is a multiple of 1000. Healthy nodes print the same
  digest for the same sequence; a different one pinpoints a divergent node
  and, between two log points, the block range where it diverged.

No protocol, consensus or storage format change. nodetests: 132/132 pass;
the node binary builds.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Adds a nightly / on-demand / "testnet"-labelled workflow that builds the node
and runs ci/testnet/run.sh on one runner:

- ci/testnet/gen_keys.py writes NodePublic.txt / NodePrivate.txt in the
  format the node reads: Base58 of the ed25519 public key and of the 64-byte
  libsodium secret. Without them the node asks for keys interactively. The
  format was checked with `node --dumpkeys`.
- run.sh creates one working dir per node: config.ini (127.0.0.1, its own
  port, APIs off, no NAT traversal, round_elapse_time 10 s), hosts.txt (the
  other nodes with their ids) and trusted.txt (all nodes as initial
  confidants). It then starts the nodes and follows "Last written sequence".
- Around block 300 it stops one node and starts it again, exercising quick
  start from caches and the checkpoint chain check.
- It passes when every node reaches block 1100 and all nodes print the same
  "STATE DIGEST" at every sequence they share (#1000 from all nodes is
  required).

7 nodes, because the bootstrap drops one node from an even set and needs 4
confidants: with 7 the network keeps going while one node restarts. The run
stays well below round 10'000 (StartingDPOS), after which a private network
with no stake cannot elect trusted nodes. The genesis funds go to an address
nobody holds, so this first version runs without transactions.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
@EnzinoBB EnzinoBB added the testnet Run the private 7-node network workflow on this PR label Oct 9, 2026
EnzinoBB and others added 2 commits October 9, 2026 12:34
A private network cannot move any funds today: the genesis block sends the
whole supply to a hardcoded address (BlockChain::writeGenesisBlock), and the
key allowed to sign special transactions and bootstrap tables is hardcoded
too (PacketValidator's BlockChainKey). Nobody running a test network holds
either key.

With -DCREDITS_TESTNET=ON (OFF by default), and only in such builds:
- CS_TESTNET_GENESIS_KEY, if set, replaces the genesis recipient (Base58
  public key); the node logs a warning when it is used;
- CS_TESTNET_STARTER_KEY, if set, replaces the starter key.

The definition is applied only to the csnode and net targets. In a normal
build the code is not compiled at all, so mainnet binaries are byte-for-byte
unaffected and no configuration can change their genesis or starter key.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
With the CREDITS_TESTNET build the genesis funds go to a key the test network
holds, so the network can now carry real state changes:

- run.sh (FUND=1) generates a master key and passes it to the nodes as
  CS_TESTNET_GENESIS_KEY and CS_TESTNET_STARTER_KEY. It opens the Thrift
  API on node 1 only and, once the chain reaches FUND_AT, runs fund.py.
- fund.py sends 60'000 CS from the genesis key to every node (above the
  50'000 minimum stake), then LOAD_SECONDS of random 1-50 CS transfers
  between nodes, and prints the final balances. Transaction building and
  signing are adapted from BK's tools/tps_gen/tps_gen.py.
- The run fails if funding or a transfer fails, or if by block 1000 the
  state digest still covers only the two genesis wallets.
- Node logs are appended to, not truncated, so a restarted node keeps its
  earlier lines (its first STATE DIGEST was lost in the first run).

The workflow builds with -DCREDITS_TESTNET=ON and installs thriftpy2.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
@EnzinoBB
EnzinoBB merged commit 98dc76c into master Oct 9, 2026
2 checks passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

testnet Run the private 7-node network workflow on this PR

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant