Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
5 changes: 3 additions & 2 deletions .yamllint.yaml
Original file line number Diff line number Diff line change
Expand Up @@ -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:
Expand Down
19 changes: 18 additions & 1 deletion README.md
Original file line number Diff line number Diff line change
Expand Up @@ -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/<sentry-ip>/tcp/30333/p2p/<sentry-peer-id>
# each sentry's .env — no --reserved-only, it stays public
RESERVED_NODES=--reserved-nodes /ip4/<validator-ip>/tcp/30333/p2p/<validator-peer-id>
```

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
Expand Down
13 changes: 7 additions & 6 deletions docs/rpc-node.md
Original file line number Diff line number Diff line change
Expand Up @@ -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.
Expand Down
6 changes: 6 additions & 0 deletions mainnet/rpc/.env.example
Original file line number Diff line number Diff line change
Expand Up @@ -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/<validator-ip>/tcp/30333/p2p/<peer-id>
#
# 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
Expand Down
7 changes: 7 additions & 0 deletions mainnet/rpc/docker-compose.yml
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down
24 changes: 18 additions & 6 deletions mainnet/validator/.env.example
Original file line number Diff line number Diff line change
Expand Up @@ -68,20 +68,32 @@ 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/<peer-id>
# 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/<sentry-peer-id>
RESERVED_NODES=

# ─── Ports ───────────────────────────────────────────────────────────────────
# P2P and metrics use ONE value on both sides of their mapping, so the port the
# 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:
Expand Down
6 changes: 6 additions & 0 deletions testnet/rpc/.env.example
Original file line number Diff line number Diff line change
Expand Up @@ -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/<validator-ip>/tcp/30333/p2p/<peer-id>
#
# 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
Expand Down
7 changes: 7 additions & 0 deletions testnet/rpc/docker-compose.yml
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down
24 changes: 18 additions & 6 deletions testnet/validator/.env.example
Original file line number Diff line number Diff line change
Expand Up @@ -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/<peer-id>
# 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/<sentry-peer-id>
RESERVED_NODES=

# ─── Ports ───────────────────────────────────────────────────────────────────
Expand All @@ -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:
Expand Down
Loading