Registered humans can run an Aequitas validator node — no stake, no application required, but NODE_OPERATOR_WALLET must be a registered Aequitas human (this is a protocol security requirement). Nodes participate in block production, validate the human registry, and synchronize the BlockDAG. Node operators earn a share of protocol fees via the Validators Pool (40% of all protocol fees, distributed daily). The more nodes that run, the more decentralized and resilient the network becomes.
Or Become a Bio Verifier — the Role That Makes Uniqueness Decentralized
A block-producing node secures the ledger. A bio verifier secures something else: the promise that each human registers only once. These are separate roles — you can run either, or both on the same machine.
Status: closed beta — read this before you start
The verifier source is not public yet, so the steps below cannot be completed by everyone today. They are published now because the design should be checkable before it is deployed, not after. If you want to run one, ask in the Telegram group linked on the front page. Opening this repository is what turns the guide below from a plan into an invitation, and it is the next thing we owe you.
What you would hold — and what you would never see
A face is never sent to you. Your machine stores one additive share of a 64-byte sketch: on its own it is indistinguishable from random noise, and no computation you can run recovers a face from it. Comparisons happen jointly with the other members of your committee, and none of you learns anything but the answer — duplicate: yes or no. That is not a promise about our good intentions; it is a property of the arithmetic.
Why every additional verifier makes the network harder to corrupt
A registration is accepted only once several different verifiers have attested it. One stolen key is not enough — an attacker needs a whole committee. And because one human may hold exactly one validator key, buying a committee means being that many people. With 100 verifiers, an attacker controlling 10 of them has under a 1-in-1,000 chance of owning a full committee of three. Every person who joins makes that number smaller. This is the one place where the count of participants is the security.
AEQUITAS BIO VERIFIER GUIDE
v1.0 · August 2026
Step by step · No cryptography knowledge required · About 30 minutes, most of it downloading
Before You Start — What You Need
1.A registered Aequitas human account. Same rule as for block production, and for the same reason: one human, one key. Without it, a single person could quietly become a whole committee.
2.A small Linux server with Docker. 2 GB RAM is enough. No GPU — the comparison is arithmetic on 64-byte values. The machine already running your node is fine.
3.A domain name with HTTPS. Other committee members must reach you. A subdomain of something you already own is enough.
4.To stay online. Every member of a committee must answer for a registration to finish. A verifier that is often away slows people down instead of protecting them.
Step 1 — Generate Your Own Keys
Generate them yourself. Never accept keys from anyone. Two verifiers holding the same secret count as one, and the committee would be smaller than it looks. Nobody — including us — should ever send you a key.
# Encrypts what little is stored on disk
openssl rand -base64 32
# Defines your own projection — see the note below
openssl rand -hex 32
# Your Ed25519 attestation key pair
docker run --rm python:3.12-slim sh -c "pip -q install cryptography && python -c '
from cryptography.hazmat.primitives.asymmetric.ed25519 import Ed25519PrivateKey
from cryptography.hazmat.primitives import serialization as s
k = Ed25519PrivateKey.generate()
print(\"PRIVATE\", k.private_bytes(s.Encoding.Raw, s.PrivateFormat.Raw, s.NoEncryption()).hex())
print(\"PUBLIC \", k.public_key().public_bytes(s.Encoding.Raw, s.PublicFormat.Raw).hex())'"
Keep the private half on your server and nowhere else. The public half is meant to be shared — it is how others verify that you attested something. Your own projection seed matters: because every verifier uses a different one, a stolen database from one verifier cannot be compared against another's. Lose the seed and your stored shares become meaningless, so back it up somewhere you control.
Step 2 — Write the Configuration File
Put the values from Step 1 into a file readable only by you. One value per line, no quotes.
nano /root/.aequitas-verifier.env
# --- paste, with your own values ---
TEMPLATE_ENCRYPTION_KEY=<openssl rand -base64 32>
FACE_SKETCH_SEED=<openssl rand -hex 32>
VALIDATOR_SIGNING_KEY=<the PRIVATE hex from step 1>
ALLOW_REAL_BIOMETRIC_DATA=false
POH_DB_PATH=/data/poh.db
PORT=8098
chmod 600 /root/.aequitas-verifier.env
Leave ALLOW_REAL_BIOMETRIC_DATA on false until you have read the data-protection notes. With it off, your verifier joins the network and takes part in test enrollments without ever storing data from a real person. That is the right way to start, and there is no hurry to change it.
Step 3 — Start the Verifier
docker network create aequitas-net 2>/dev/null || true
mkdir -p /root/aequitas-verifier-data
docker run -d --name aequitas-verifier \
--network aequitas-net --restart unless-stopped \
--env-file /root/.aequitas-verifier.env \
-v /root/aequitas-verifier-data:/data \
<image>
# Did it come up?
curl -s localhost:8098/health
A healthy answer reports plaintext_templates: 0 and sketch_seed_configured: true. The first is the claim that no whole template is stored, in a form you can check yourself rather than take on faith. Check it now and again later — it is your own guarantee as much as anyone else's.
Step 4 — Put HTTPS in Front
Other committee members reach you over the public internet, so the port must not be exposed unencrypted. Caddy obtains a certificate on its own.
# /root/Caddyfile
verifier.example.org {
reverse_proxy aequitas-verifier:8098
}
Step 5 — Link Your Key to Your Human Wallet
This is the step that makes one human one verifier. You sign twice: once with your registered human wallet, and once with your node key. The chain accepts the pair only if both signatures check out, so nobody can register a key in your name and you cannot register two. Use the button below.
Step 6 — Publish Your Public Key
Send the public half from Step 1, together with your HTTPS address, to the group. It is added to the list every proof server checks against, and from then on your attestations count toward the quorum. Nothing secret leaves your machine in this step — that is the point of the split: the private half stays with you forever, and the public half is useless without it.
Checking That It Works
# Reachable from outside, with a valid certificate?
curl -s https://verifier.example.org/health
# Does the network see you and agree with the others?
curl -s https://aequitas.digital/inventory
The second call lists every verifier and compares them: whether all hold the same number of enrollments, whether anyone is missing a seed, and whether the keys agree. If your entry shows a divergence, it is better to find out here than during someone's registration.
Where this stands today — plainly
This part is in beta and the limits are real. The joint comparison consumes one-time cryptographic material, and one delivery currently covers a few dozen registrations before more is needed — so the confidential path proves itself at small scale first, not at millions. The work also grows with the number of people enrolled. We publish these numbers rather than round them off: a system that asks for your face has no business being vague about what it can and cannot do yet.
This inline guide is in English. A translated PDF is available in your language using the button above.
AEQUITAS NODE OPERATOR GUIDE
v1.0 · June 2026
Complete step-by-step guide · No prior blockchain experience required · Estimated time: 20–30 min
What is an Aequitas Node?
An Aequitas node is a program that runs in the cloud and participates in the Aequitas network. It keeps a copy of the entire blockchain, validates who is a registered human, and produces new blocks (like new pages in the global ledger). The more nodes exist, the more decentralized and resilient the network becomes. As a reward for running a node, you receive a daily share of all protocol fees — automatically, with no further action required on your part.
Before You Start — What You Need
1.An Aequitas account: You must first be registered as a human on Aequitas. Install the Android app, complete biometric registration, and note your wallet address. Without this, you cannot receive validator rewards.
2.A GitHub account (free): Go to github.com and create a free account. Optional — only needed if you want to build from your own fork rather than the published image.
3.A Linux server (VPS): Any provider works — Contabo, Hetzner, DigitalOcean. You need SSH access and about 2 GB RAM. A small instance is enough to validate.
4.Node signing key (RELAYER_PRIVATE_KEY): Your node needs a dedicated Ethereum wallet to sign on-chain registrations. This can be any MetaMask wallet. Export its private key: MetaMask → Account Details → Show Private Key → enter password → copy. Keep strictly private. IMPORTANT: To receive validator rewards you also need NODE_OPERATOR_WALLET set to your registered Aequitas human wallet (the one verified with the Aequitas app). Only verified humans can earn validator rewards.
5.20–40 minutes of your time. Most of it is waiting for the initial chain sync.
Step 1 — Fork the Aequitas Repository on GitHub
What is a fork? A fork is your own personal copy of the Aequitas code on GitHub. You only need one if you intend to modify the node or build the image yourself.
a) Open github.com/hanoi96international-gif/Aequitas in your browser
b) Click the Fork button in the top-right corner of the page
c) Click Create fork — GitHub creates a copy under your own account (e.g. github.com/YOUR-NAME/Aequitas)
d) Done — you now have your own copy of the Aequitas node code
Step 2 — Create a PostgreSQL Database
What is a database? Your node needs permanent storage for all block data and human registrations. Without it, your node loses all data on every restart. PostgreSQL is the storage system Aequitas uses. Each node must have its own dedicated database — never share one database between two nodes.
On your VPS (Contabo, Hetzner, DigitalOcean, or any Linux server)
One database per node. Install PostgreSQL on the same machine as your node and keep it there. Two nodes sharing one database will overwrite each other's state — this is the single most damaging mistake you can make when setting up.
# 1. Install PostgreSQL (Ubuntu / Debian)
sudo apt update && sudo apt install -y postgresql postgresql-contrib
sudo systemctl enable --now postgresql
# 2. Create database and user (run as root or with sudo)
sudo -u postgres psql -c "CREATE USER aequitas WITH PASSWORD 'CHOOSE_A_STRONG_PASSWORD';"
sudo -u postgres psql -c "CREATE DATABASE aequitas OWNER aequitas;"
# 3. Allow connections from Docker containers (Docker bridge: 172.17.0.0/16)
PG_CONF=$(sudo -u postgres psql -t -c "SHOW hba_file;" | tr -d ' ')
echo "host aequitas aequitas 172.17.0.0/16 md5" | sudo tee -a $PG_CONF
sudo -u postgres psql -c "ALTER SYSTEM SET listen_addresses = '*';"
sudo systemctl restart postgresql
# 4. Test (should print one row)
psql "postgres://aequitas:CHOOSE_A_STRONG_PASSWORD@localhost:5432/aequitas" -c "SELECT 1;"
# Your DATABASE_URL for the docker run command below:
# postgres://aequitas:CHOOSE_A_STRONG_PASSWORD@172.17.0.1:5432/aequitas
# (172.17.0.1 = Docker bridge gateway, how containers reach the VPS host)
Firewall: PostgreSQL only needs to be reachable from within the VPS itself. Do not open port 5432 to the internet. ufw deny 5432 (or leave it closed — most VPS firewalls block it by default).
Step 3 — Understand the Environment Variables
Environment variables are configuration settings you pass to your node before it starts. Think of them like a settings file. Collect these values before deploying — you will enter them in Step 4.
Security Warning: Your RELAYER_PRIVATE_KEY is like a master password. Anyone who has it controls your node wallet. Never share it publicly, never paste it in chat or email. Use a separate MetaMask wallet for RELAYER_PRIVATE_KEY (signing). NODE_OPERATOR_WALLET (for rewards) must be your registered Aequitas human wallet.
| Variable |
Required? |
What to enter and where to find it |
| DATABASE_URL |
YES |
Your PostgreSQL connection string. Point it at the PostgreSQL you installed on this same machine. Format: postgres://user:pass@host:5432/dbname |
| RELAYER_PRIVATE_KEY |
YES |
The private key (starts with 0x, 66 characters total) of your dedicated node wallet. In MetaMask: click account icon → Account Details → Show Private Key → enter your MetaMask password → copy the key |
| RELAYER_ADDRESS |
Recommended |
The wallet address (starts with 0x, 42 characters) matching RELAYER_PRIVATE_KEY. This is the public address — safe to share. Copy it from MetaMask. A fallback exists in the node code, but setting this explicitly prevents startup errors. |
| NODE_OPERATOR_WALLET |
For rewards |
Your Aequitas human wallet address — the one you registered with via the Android app. This wallet receives your daily validator rewards (40% of all protocol fees). Must be a registered human on Aequitas. Find it in the app under your profile. |
| PEER_SECRET |
No |
No longer required. Validator authorization is now identity-based: a verified NODE_OPERATOR_WALLET plus the binding signature below is enough — there is nothing to obtain from the network operator for this step. |
| NODE_OPERATOR_BINDING_SIGNATURE |
For multi-node |
Proves you own NODE_OPERATOR_WALLET — without it, anyone could claim your wallet as their own node's operator and permanently lock you out of it. Generate it at /node-binding: connect the SAME wallet you registered with, it signs a short message naming your node's signing address, and shows you this value to copy here. To move your validator to a new machine later, just generate a new signature there for the new signing address — no need to contact anyone. |
| SELF_URL |
YES |
Your node's own public URL (e.g. http://YOUR-IP:8080, or an https:// hostname if you put a reverse proxy in front). Without it the node starts in isolated mode — it cannot register with peers, cannot propagate blocks, and other nodes cannot reach it. |
| PRIMARY_NODE_URL |
For multi-node |
Set to: https://aequitas.digital — the primary node your node registers with for automatic peer discovery. On startup your node posts its URL + signing address to the primary, gets the full peer list back, and joins the network automatically. No manual PEER_NODES list needed. |
| PORT |
No |
Leave unset unless your host requires a specific port. Default is 8080. |
| NODE_KEY |
No |
Base64-encoded libp2p private key for stable P2P identity. If not set: auto-generated on first start and printed to stderr. Copy the base64 string from SAVE THIS AS NODE_KEY ENVIRONMENT VAR: <base64> and paste it here to keep a stable peer ID across restarts. |
| IS_PRIMARY_NODE |
No |
Removed — does nothing. Leave unset. |
| DISTRIBUTION_ENABLED |
No |
Leave unset for normal operation — all nodes are eligible to trigger the daily pool distribution by default. Three-layer dedup (cross-node last_ubi_at check + intra-node CAS lock + replay pre-pass) prevents double-credit even when multiple nodes fire at the same time. Set to false only if you explicitly want to opt this node out of running distributions (e.g. a resource-constrained replica). |
| BOOTSTRAP_SNAPSHOT_URL |
Multi-node |
Set to https://aequitas.digital/api/snapshot on a fresh node. If the local DB has 0 humans at startup, the node automatically downloads and imports the full state from this URL — fixing StateRoot mismatches immediately. Also set BOOTSTRAP_SIGNER. SNAPSHOT_TOKEN is optional — only needed if you want the full export instead of the public bootstrap tier. |
| BOOTSTRAP_SIGNER |
Multi-node |
Ethereum signing address of the primary node. Required when BOOTSTRAP_SNAPSHOT_URL is set. Get it from https://aequitas.digital/api/status → signing_address field. Prevents importing a tampered snapshot. |
| SNAPSHOT_TOKEN |
No |
Optional — no longer required to bootstrap a new node. Without a token, BOOTSTRAP_SNAPSHOT_URL still downloads everything a node needs to run correctly (accounts, balances, pool, config). A token only unlocks the FULL export (nullifier→wallet linkage + bio_registrations), used for authoritative resync/recovery of an already-diverged node — get it from the network operator only if you actually need that. |
| RESYNC_FROM_SNAPSHOT |
No |
Recovery tool for a node KNOWN to have diverged — unlike BOOTSTRAP_SNAPSHOT_URL (which only merges into an empty DB), this REPLACES local accounts, pool, nullifiers, and chain_config with exactly what the snapshot contains, discarding anything local that doesn't match. Set to true together with BOOTSTRAP_SNAPSHOT_URL and BOOTSTRAP_SIGNER (mandatory here, no unsigned fallback), restart once, then remove it. Combine with RESET_DB_STATE=true for the cleanest result. |
| AUTO_HEAL_ON_DIVERGENCE |
Strongly recommended |
Important for network security and speed: if your node's chain ever diverges from the network (e.g. after downtime or a bad restart), set this to true together with PRIMARY_NODE_URL, BOOTSTRAP_SNAPSHOT_URL, and BOOTSTRAP_SIGNER — your node then compares itself against PRIMARY_NODE_URL every few minutes and resyncs itself automatically, no manual RESYNC_FROM_SNAPSHOT needed. A node that stays diverged and keeps broadcasting its own blocks can slow down or destabilize the network for every other operator (confirmed live: this is what caused a network-wide slowdown on 2026-07-02). |
| SNAPSHOT_RESTRICT_TO_PRIVATE_NETWORK |
No |
Opt-in: when set to true, /api/snapshot only answers requests from private/loopback addresses instead of any caller with the right token. Off by default because this project's bootstrap/resync mechanism relies on cross-provider access between servers; only enable this if every node you run shares a private network. |
| RESET_STATE |
No |
DANGEROUS: Setting this to true wipes your entire database on every restart. Development use only. Never in production. |
| RESET_DB_STATE |
No |
DANGEROUS, one-time use: truncates bootstrap-related tables (including evm_upgrade_relationship_slots) so a node can re-sync clean from genesis. Only takes effect within the first few minutes after process start to avoid repeated wipes on a crash-restart loop, and also requires ALLOW_DESTRUCTIVE_MAINTENANCE (see below). On success the process exits immediately instead of continuing to start — remove this variable (and ALLOW_DESTRUCTIVE_MAINTENANCE) and redeploy to bring the node back up. |
| CLEAR_REGISTRATIONS |
No |
DANGEROUS, one-time use: wipes all human registration data (chain_accounts' human flags, nullifiers, bio_hashes, liquidity_pool, evm_upgrade_relationship_slots) so everyone can re-register. Same 5–minute-from-startup guard as RESET_DB_STATE, plus also requires CLEAR_REGISTRATIONS_CONFIRM (see below) and ALLOW_DESTRUCTIVE_MAINTENANCE. On success the process exits immediately instead of continuing to start — remove all three variables and redeploy to bring the node back up. |
| CLEAR_REGISTRATIONS_CONFIRM |
No |
Required alongside CLEAR_REGISTRATIONS=true on both this service and the proof-server — must be set to the exact literal string I_UNDERSTAND_THIS_DELETES_ALL_REGISTRATIONS. Without it, CLEAR_REGISTRATIONS=true alone is refused. Exists so a single boolean set by accident (copy-pasted env file, typo elsewhere) can't wipe every human's registration on the next restart. |
| ALLOW_DESTRUCTIVE_MAINTENANCE |
No |
Required alongside RESET_DB_STATE=true or CLEAR_REGISTRATIONS=true — must be set to true. Without it, both are refused even with their other confirmation values correct. One more explicit gate so a wrong server selection or a stray copy-pasted env file can't trigger either destructive path alone. Visible at /api/health/combined (destructive_flags_set) whenever any destructive flag is currently set, even if it was refused. |
| BOOTSTRAP_P2P_ADDR |
No |
Overrides the built-in libp2p bootstrap multiaddress (see Step 7 below). Only needed if you want to pin a specific entry point; the two validator addresses are compiled in as defaults again in the future — set this instead of waiting for a code deploy. |
Optional — Help check for duplicate registrations
Your node can also help verify that nobody registers twice, without ever seeing anyone's biometric data. Each participating validator holds one mathematical share of every enrolled template — noise on its own — and they compare a new capture together, so no single machine can reconstruct anything. This is entirely optional: a small committee is drawn automatically from the validators that offer the service, and a node that does not offer it is never drawn and runs completely normally. If you want to take part, set the three variables below and ask the operator for your share file.
-e MPC_ENABLED="true" \
-e MPC_COMMITTEE_SIZE="2" \
-e MPC_TRIPLE_FILE="/data/triples-party-N.bin" \
The share file contains one-time randomness that only your node may hold — never copy it to another machine and never commit it anywhere. Your node is identified to the other committee members by the same signing key it already uses for blocks, so there is no additional secret to obtain and no extra step when a new validator joins.
Step 4 — Alternative: Deploy on a VPS with Docker
For your own server (Contabo, Hetzner, DigitalOcean). Requires Docker installed on the VPS and a local PostgreSQL database set up via Step 2 Option B above. Do not point two nodes at one PostgreSQL — each node must have its own separate database. NODE_OPERATOR_WALLET must be a registered Aequitas human wallet.
# 1. Install Docker (if not already installed)
curl -fsSL https://get.docker.com | sh
# 2. Clone and build the node (~3 min Go compile)
git clone https://github.com/hanoi96international-gif/Aequitas && cd Aequitas
docker build -t aequitas-node .
# 3. First start (NODE_KEY will be printed in logs — see step 4)
# DATABASE_URL uses 172.17.0.1 = Docker bridge gateway → host PostgreSQL
# (set up PostgreSQL first via Step 2 Option B above)
docker run -d --name aequitas-node --restart unless-stopped \
-e DATABASE_URL="postgres://aequitas:YOUR_DB_PASSWORD@172.17.0.1:5432/aequitas" \
-e RELAYER_PRIVATE_KEY="0xYOUR_PRIVATE_KEY" \
-e RELAYER_ADDRESS="0xYOUR_NODE_SIGNING_ADDRESS" \
-e NODE_OPERATOR_WALLET="0xYOUR_REGISTERED_HUMAN_WALLET" \
-e NODE_OPERATOR_BINDING_SIGNATURE="generate-at-/node-binding" \
-e SELF_URL="http://YOUR-SERVER-IP:8080" \
-e PRIMARY_NODE_URL="https://aequitas.digital" \
-e BOOTSTRAP_SNAPSHOT_URL="https://aequitas.digital/api/snapshot" \
-e BOOTSTRAP_SIGNER="0x92cbedec9d348b4762cb9af99500ee6139c5b671" \
-e AUTO_HEAL_ON_DIVERGENCE="true" # strongly recommended \
-p 8080:8080 -p 4001:4001 aequitas-node
# 4. Copy NODE_KEY from logs (do this once — gives your node a stable P2P identity)
docker logs aequitas-node 2>&1 | grep "SAVE THIS AS NODE_KEY"
# 5. Stop, add NODE_KEY, restart permanently:
docker stop aequitas-node && docker rm aequitas-node
docker run -d --name aequitas-node --restart unless-stopped \
-e DATABASE_URL="postgres://aequitas:YOUR_DB_PASSWORD@172.17.0.1:5432/aequitas" \
-e RELAYER_PRIVATE_KEY="0xYOUR_PRIVATE_KEY" \
-e RELAYER_ADDRESS="0xYOUR_NODE_SIGNING_ADDRESS" \
-e NODE_OPERATOR_WALLET="0xYOUR_REGISTERED_HUMAN_WALLET" \
-e NODE_OPERATOR_BINDING_SIGNATURE="generate-at-/node-binding" \
-e NODE_KEY="base64-from-step-4" \
-e SELF_URL="http://YOUR-SERVER-IP:8080" \
-e PRIMARY_NODE_URL="https://aequitas.digital" \
-e BOOTSTRAP_SNAPSHOT_URL="https://aequitas.digital/api/snapshot" \
-e BOOTSTRAP_SIGNER="0x92cbedec9d348b4762cb9af99500ee6139c5b671" \
-e AUTO_HEAL_ON_DIVERGENCE="true" # strongly recommended \
-p 8080:8080 -p 4001:4001 aequitas-node
Tip: Save all vars in /root/.aequitas.env (chmod 600) and use --env-file /root/.aequitas.env instead of listing each -e — keeps secrets out of shell history and simplifies updates.
Port requirements: TCP 8080 must be open inbound (API + RPC). TCP 4001 is optional (P2P — enables direct node-to-node connections). If P2P is firewalled, HTTP sync still works. On Linux: ufw allow 8080/tcp
Step 5 — Verify Your Node is Running
Open these URLs in your browser. Replace YOUR-NODE-URL with your server's address.
https://YOUR-NODE-URL/api/status
→ Expected: {"height": 1234, "total_humans": N, "aequitas_index": N}
https://YOUR-NODE-URL/rpc
→ Expected: {"jsonrpc":"2.0","error":"method not specified"} — this confirms RPC is alive
The block height should match the primary node within 1–2 blocks within seconds of startup. If it stays at 0, check that PRIMARY_NODE_URL=https://aequitas.digital is set and reachable.
Step 5b — Link Wallet for Rewards
✓ Usually automatic — most users skip this step
When your node starts, it
automatically connects to the network and registers for block production. If you set
NODE_OPERATOR_WALLET in your environment variables (Step 4), your wallet is already linked and you will receive validator rewards automatically.
You only need Step 5b if:
- Your node logs show
[NODE] validator key not authorized
- You want to change your reward wallet without restarting the node
- You are running a Docker/VPS node and auto-registration failed
Check if already registered: Look in your node logs for [PEERS] Registered with primary node. If you see it — you're done, no manual step needed.
Step 6 — Connect MetaMask to Your Node (Optional)
You can use your own node as a custom RPC in MetaMask so your wallet connects through your node instead of the shared public node. In MetaMask: click the network dropdown at the top → Add network → Add a network manually, then enter:
| Network Name | Aequitas Chain |
| RPC URL | https://YOUR-NODE-URL/rpc |
| Chain ID | 1926 |
| Currency Symbol | AEQ |
| Decimals | 18 |
| Block Explorer | https://aequitas.digital |
Step 7 — Earning Validator Rewards
The Validators Pool collects 40% of all protocol fees (swap fees, demurrage, wealth cap overflow). Every day at 20:00 Berlin time (CEST/CET, handles DST automatically) the primary node distributes the pool balance to all registered node operator wallets proportionally. The more consistently your node runs, the larger your share.
1.Make sure you are registered as a human on Aequitas. If not: install the Android app and complete biometric registration first. You will receive a wallet address and 1,000 AEQ.
2.Set NODE_OPERATOR_WALLET = your Aequitas human wallet address in your node's environment
3.Restart the node so it picks the value up: docker restart aequitas-node
4.In your node logs, confirm: [NODE] Registered node operator wallet: 0x...
5.Rewards are distributed automatically every day at 20:00 Berlin time (CEST/CET). Just keep your node running — no further action needed.
Troubleshooting
| Symptom |
Likely cause |
Solution |
| Block height stays at 0 |
PRIMARY_NODE_URL not set or wrong |
Set PRIMARY_NODE_URL=https://aequitas.digital and redeploy. Also set SELF_URL to your own node's public URL. |
| DATABASE_URL error on startup |
Wrong connection string or PostgreSQL unreachable |
Check format: postgres://user:pass@host:5432/dbname — make sure PostgreSQL is running and accessible |
| "no code at address" in logs |
V7 contract not yet deployed in this EVM |
Normal on first start when RELAYER_ADDRESS is set — node auto-deploys V7. Wait a few seconds and check again. |
| "NODE_OPERATOR_WALLET not set" in logs |
Missing environment variable |
Add NODE_OPERATOR_WALLET=0xYOUR_HUMAN_WALLET to your variables. Node runs fine without it but you won't receive rewards. |
| Node container exits immediately |
Build or startup failure |
Run docker logs aequitas-node for the error message. Most common cause: DATABASE_URL missing or RELAYER_PRIVATE_KEY in wrong format (must start with 0x). |
| Port 8080 not reachable (Docker) |
Firewall or cloud provider config |
Open TCP port 8080 inbound in your firewall or cloud security group settings. |
| Docker build fails with module error |
No internet access during build |
The Docker build needs outbound internet to download Go modules. Check the VPS firewall allows outbound HTTPS. |
| ⚠ P2P bootstrap unreachable (HTTP sync still works) |
libp2p port 4001 firewalled (very common) |
Not critical — HTTP block sync is the primary mechanism and runs automatically. Add -p 4001:4001 and ufw allow 4001/tcp to enable P2P as well. |
| Bootstrap snapshot failed / StateRoot mismatch |
SNAPSHOT_TOKEN not set on primary, or BOOTSTRAP_SIGNER wrong |
Set BOOTSTRAP_SNAPSHOT_URL=https://aequitas.digital/api/snapshot, BOOTSTRAP_SIGNER=0x92cbedec9d348b4762cb9af99500ee6139c5b671, and SNAPSHOT_TOKEN (from network operator). Restart — node imports state automatically if DB is empty. |
| Node not in block explorer / no MERGE blocks |
Port 8080 not reachable from outside OR Step 5b not done |
1) Open port 8080 inbound (ufw allow 8080/tcp). 2) Set SELF_URL=http://YOUR-IP:8080. 3) Complete Step 5b to register your signing key. Then the primary node syncs your blocks and MERGE events appear. |
| MetaMask shows 0 AEQ or wrong balance after registration |
Stale network config in MetaMask (cached old RPC data) |
MetaMask → Settings → Networks → delete all "Aequitas Chain" entries → re-add via the "+ ADD AEQUITAS NETWORK" button on this website. Balance will update immediately. |
| NODE_KEY generating new key on every restart |
NODE_KEY env var not set |
On first start, look for SAVE THIS AS NODE_KEY ENVIRONMENT VAR: <base64> in logs. Copy that value and add it as NODE_KEY environment variable. Restart once — P2P identity is now stable across all future restarts. |
Questions / Feedback
Open an issue on
GitHub, ask in the
Telegram group, or reach the team on
X (@AequitasMoney). Feedback on node setup, performance, and documentation gaps is especially welcome. Download this guide as a PDF in your selected language using the button above.