diff --git a/.yamllint.yaml b/.yamllint.yaml index 6897272..48bee67 100644 --- a/.yamllint.yaml +++ b/.yamllint.yaml @@ -2,9 +2,10 @@ extends: default rules: - # Compose `command: >` folded blocks and long image refs run past 80 cols. + # Compose `command: >` folded blocks and long image refs run past 80 cols, and + # an `--experimental-rpc-endpoint` spec is one argument that cannot wrap. line-length: - max: 160 + max: 200 level: warning # Prettier owns indentation/spacing; don't double-fight it. indentation: diff --git a/README.md b/README.md index d2a72e1..b518fd6 100644 --- a/README.md +++ b/README.md @@ -68,7 +68,24 @@ be removed rather than debugged later. ## Validator -Joins the network, authors blocks. No public RPC. Needs TCP **30333** reachable. +Joins the network, authors blocks. No public RPC. Needs TCP **30333** reachable +by its peers: publicly, or only by its sentries when it runs behind them. + +**Behind sentries (recommended).** Private spends are unsigned, so every node +they reach verifies their zero-knowledge proof on arrival, and a peer sending +invalid ones loses too little reputation to be banned. A validator that takes +transactions only from its own sentries (RPC nodes, see +[docs/rpc-node.md](docs/rpc-node.md)) never pays that cost for strangers: + +```bash +# validator .env — never --reserved-only with no sentry listed +RESERVED_NODES=--reserved-only --reserved-nodes /ip4//tcp/30333/p2p/ +# each sentry's .env — no --reserved-only, it stays public +RESERVED_NODES=--reserved-nodes /ip4//tcp/30333/p2p/ +``` + +Then allow `30333` on the validator only from the sentries' IPs. Without a +sentry, leave `RESERVED_NODES` empty and keep `30333` public. ```bash cd testnet/validator # or mainnet/validator diff --git a/docs/rpc-node.md b/docs/rpc-node.md index c039755..1082185 100644 --- a/docs/rpc-node.md +++ b/docs/rpc-node.md @@ -80,12 +80,13 @@ cp .env.example .env Edit `.env` and set: -| Variable | What to set | -| --------------- | ----------------------------------------------------------------------------- | -| `RPC_NAME` | Required. Identifiable name shown in telemetry (e.g. `Orbinum-RPC-1`). | -| `RPC_NODE_KEY` | This node's libp2p key — generate with `openssl rand -hex 32`. | -| `RPC_DOMAIN` | Public domain with a DNS A record pointing to this VPS's public IP. | -| `TELEMETRY_URL` | On by default; set empty to opt out. See [Telemetry](../README.md#telemetry). | +| Variable | What to set | +| ---------------- | ------------------------------------------------------------------------------ | +| `RPC_NAME` | Required. Identifiable name shown in telemetry (e.g. `Orbinum-RPC-1`). | +| `RPC_NODE_KEY` | This node's libp2p key — generate with `openssl rand -hex 32`. | +| `RPC_DOMAIN` | Public domain with a DNS A record pointing to this VPS's public IP. | +| `TELEMETRY_URL` | On by default; set empty to opt out. See [Telemetry](../README.md#telemetry). | +| `RESERVED_NODES` | Empty, or your validator as a sentry. See [Validator](../README.md#validator). | > **Keep `RPC_NODE_KEY` stable** — this node's PeerId goes public in `bootNodes`. > If the key changes, the PeerId changes and the chain spec's bootnode entry breaks. diff --git a/mainnet/rpc/.env.example b/mainnet/rpc/.env.example index efa4abf..731329f 100644 --- a/mainnet/rpc/.env.example +++ b/mainnet/rpc/.env.example @@ -37,6 +37,12 @@ TELEMETRY_URL=--telemetry-url "wss://telemetry.orbinum.io/submit/ 0" # Empty by default: a public RPC should discover peers freely. # +# As a validator's sentry, list that validator here WITHOUT --reserved-only: +# this node stays public and keeps a slot for it, and the validator (pinned to +# its sentries, see ../validator/.env.example) only receives what this node has +# already checked. +# RESERVED_NODES=--reserved-nodes /ip4//tcp/30333/p2p/ +# # Pin it during a recovery. The chainspec's bootNodes are the RPCs themselves, # so a freshly purged RPC discovers whatever is on the network — including a # third-party node still serving a dead fork, which it will sync from because diff --git a/mainnet/rpc/docker-compose.yml b/mainnet/rpc/docker-compose.yml index 52050a7..9179e3b 100644 --- a/mainnet/rpc/docker-compose.yml +++ b/mainnet/rpc/docker-compose.yml @@ -82,6 +82,13 @@ services: - caddy-config:/config labels: com.centurylinklabs.watchtower.enable: "false" + # Caddy's error log goes to stderr, one ~2 KB line per failed request. Unbounded, + # a node outage turned it into a full disk, which corrupted the node's db_version. + logging: + driver: "json-file" + options: + max-size: "50m" + max-file: "3" watchtower: image: ghcr.io/nicholas-fedor/watchtower:latest diff --git a/mainnet/validator/.env.example b/mainnet/validator/.env.example index 99e3a35..e29df2b 100644 --- a/mainnet/validator/.env.example +++ b/mainnet/validator/.env.example @@ -68,12 +68,22 @@ PUBLIC_ADDR= # Restricts who this node talks to. Empty = discover via chainspec bootNodes. # -# Two uses: validators on a private network pin each other with --reserved-only -# so they never gossip publicly; and during recovery it stops a purged node from -# resyncing off a stranger serving a longer-but-dead fork. +# Recommended: talk only to your own sentries (one or more RPC nodes that list +# this validator in their RESERVED_NODES, see ../rpc/.env.example). Private +# spends are unsigned, so a node checks each one's zero-knowledge proof when it +# arrives, about a millisecond of CPU per spend, and a peer that sends invalid +# ones loses too little reputation to be banned. Open to every peer, the block +# author pays that cost for anyone who connects; behind sentries it never sees a +# spend they have not already checked. # -# List every OTHER node this one should reach, not itself. -# RESERVED_NODES=--reserved-only --reserved-nodes /ip4/10.0.0.21/tcp/30333/p2p/ +# Also stops a purged node from resyncing off a stranger serving a +# longer-but-dead fork. +# +# List every OTHER node this one should reach, not itself: your sentries, and +# your other validators if they peer directly. Never --reserved-only with no +# sentry listed: the node then talks to no one and never syncs. Without a +# sentry of your own, leave this empty and peer publicly. +# RESERVED_NODES=--reserved-only --reserved-nodes /ip4/10.0.0.21/tcp/30333/p2p/ RESERVED_NODES= # ─── Ports ─────────────────────────────────────────────────────────────────── @@ -81,7 +91,9 @@ RESERVED_NODES= # node uses and the one the host publishes cannot drift. RPC moves only the host # side (the container keeps 9944). -# Open it in the firewall: must stay publicly reachable or no inbound peers. +# Open it in the firewall. Behind sentries (--reserved-only), only they need to +# reach it: allow their IPs alone. Otherwise it must stay publicly reachable or +# there are no inbound peers. P2P_PORT=30333 # A local `curl` (author_rotateKeys) targets this one: diff --git a/testnet/rpc/.env.example b/testnet/rpc/.env.example index 5336e27..2aa47e5 100644 --- a/testnet/rpc/.env.example +++ b/testnet/rpc/.env.example @@ -45,6 +45,12 @@ TELEMETRY_URL=--telemetry-url "wss://telemetry.orbinum.io/submit/ 0" # Empty by default: a public RPC should discover peers freely. # +# As a validator's sentry, list that validator here WITHOUT --reserved-only: +# this node stays public and keeps a slot for it, and the validator (pinned to +# its sentries, see ../validator/.env.example) only receives what this node has +# already checked. +# RESERVED_NODES=--reserved-nodes /ip4//tcp/30333/p2p/ +# # Pin it during a recovery. The chainspec's bootNodes are the RPCs themselves, # so a freshly purged RPC discovers whatever is on the network — including a # third-party node still serving a dead fork, which it will sync from because diff --git a/testnet/rpc/docker-compose.yml b/testnet/rpc/docker-compose.yml index 80b34c4..5f61d65 100644 --- a/testnet/rpc/docker-compose.yml +++ b/testnet/rpc/docker-compose.yml @@ -107,6 +107,13 @@ services: - caddy-config:/config labels: com.centurylinklabs.watchtower.enable: "false" + # Caddy's error log goes to stderr, one ~2 KB line per failed request. Unbounded, + # a node outage turned it into a full disk, which corrupted the node's db_version. + logging: + driver: "json-file" + options: + max-size: "50m" + max-file: "3" watchtower: image: ghcr.io/nicholas-fedor/watchtower:latest diff --git a/testnet/validator/.env.example b/testnet/validator/.env.example index 49685f3..2e65909 100644 --- a/testnet/validator/.env.example +++ b/testnet/validator/.env.example @@ -68,12 +68,22 @@ PUBLIC_ADDR= # Restricts who this node talks to. Empty = discover via chainspec bootNodes. # -# Two uses: validators on a private network pin each other with --reserved-only -# so they never gossip publicly; and during recovery it stops a purged node from -# resyncing off a stranger serving a longer-but-dead fork. +# Recommended: talk only to your own sentries (one or more RPC nodes that list +# this validator in their RESERVED_NODES, see ../rpc/.env.example). Private +# spends are unsigned, so a node checks each one's zero-knowledge proof when it +# arrives, about a millisecond of CPU per spend, and a peer that sends invalid +# ones loses too little reputation to be banned. Open to every peer, the block +# author pays that cost for anyone who connects; behind sentries it never sees a +# spend they have not already checked. # -# List every OTHER node this one should reach, not itself. -# RESERVED_NODES=--reserved-only --reserved-nodes /ip4/10.0.0.21/tcp/30333/p2p/ +# Also stops a purged node from resyncing off a stranger serving a +# longer-but-dead fork. +# +# List every OTHER node this one should reach, not itself: your sentries, and +# your other validators if they peer directly. Never --reserved-only with no +# sentry listed: the node then talks to no one and never syncs. Without a +# sentry of your own, leave this empty and peer publicly. +# RESERVED_NODES=--reserved-only --reserved-nodes /ip4/10.0.0.21/tcp/30333/p2p/ RESERVED_NODES= # ─── Ports ─────────────────────────────────────────────────────────────────── @@ -82,7 +92,9 @@ RESERVED_NODES= # only the host side (the container keeps 9944 / 9615) — nothing advertises # those over the wire, so a remap there is invisible to peers. -# Open it in the firewall: must stay publicly reachable or no inbound peers. +# Open it in the firewall. Behind sentries (--reserved-only), only they need to +# reach it: allow their IPs alone. Otherwise it must stay publicly reachable or +# there are no inbound peers. P2P_PORT=30333 # A local `curl` (author_rotateKeys) targets this one: