Skip to content

chore(peering): recommend validators behind sentries (--reserved-only), document the sentry role of RPC nodes and never --reserved-only without a sentry - #12

Merged
nol4lej merged 1 commit into
mainfrom
chore/validator-sentry-peering
Oct 22, 2026
Merged

nol4lej merged 1 commit into
mainfrom
chore/validator-sentry-peering

Conversation

@nol4lej

@nol4lej nol4lej commented Oct 22, 2026

Copy link
Copy Markdown
Member

Summary

Recommend running validators behind sentries with --reserved-only, and document how an RPC node acts as a validator's sentry.

Private spends (private_transfer, unshield) are unsigned, so a node verifies each one's Groth16 proof when it reaches the pool, about 1 ms of CPU per spend. A peer that sends spends with invalid proofs loses too little reputation per transaction to ever be banned. A validator open to any peer pays that verification cost for anyone who connects. Behind sentries, it only receives spends a sentry has already checked: invalid ones are refused at the sentry and never propagated.

Changes

  • testnet/validator/.env.example, mainnet/validator/.env.example
    • RESERVED_NODES recommends --reserved-only --reserved-nodes <sentry> and says why.
    • It warns never to use --reserved-only with no sentry listed, which isolates the node. Without a sentry, leave it empty and peer publicly.
    • P2P_PORT: behind sentries, only their IPs need to reach it.
  • testnet/rpc/.env.example, mainnet/rpc/.env.example: the sentry role. List the validator in RESERVED_NODES without --reserved-only, so the RPC node stays public.
  • README.md (Validator): when to run behind sentries, both .env lines, and the firewall rule.
  • docs/rpc-node.md: RESERVED_NODES in the .env table.

The compose files are unchanged; they already pass ${RESERVED_NODES} through.

Rollout (per host, after merge)

  1. Validator .env: RESERVED_NODES=--reserved-only --reserved-nodes <sentry multiaddr> ..., listing every sentry plus any validator it peers with directly.
  2. Each sentry's .env: RESERVED_NODES=--reserved-nodes <validator multiaddr>.
  3. docker compose up -d on each host (not docker restart, which keeps the old arguments).
  4. Allow the validator's P2P port only from its sentries.

External validators need their own sentry for the same protection; without one they keep peering publicly.

Testing

  • python3 -m unittest tests/test_rpc_config.py: 4 tests pass.
  • Same topology on a local network (validator --reserved-only with one sentry; a public node; an outside node that only knows the validator):
    • The validator peers with the sentry alone and refuses the outside node.
    • Spends with invalid proofs sent to the public nodes are refused there, and the validator's pool runs no validation for them.
    • Legitimate spends still reach blocks.

@nol4lej
nol4lej force-pushed the chore/validator-sentry-peering branch from bc7f364 to 20211be Compare October 22, 2026 01:33
…), document the sentry role of RPC nodes and never --reserved-only without a sentry
@nol4lej
nol4lej force-pushed the chore/validator-sentry-peering branch from 20211be to f8da12a Compare October 22, 2026 01:35
@nol4lej
nol4lej merged commit a2230c2 into main Oct 22, 2026
1 check passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant