WarpCoin WARP
← All documentation

WarpCoin Server Deployment

Production-ready packaging for running WarpCoin infrastructure: a single Docker image and entrypoint that runs any node role, plus Docker Compose, systemd, and Kubernetes manifests.

Node roles

All roles run from the same warpcoin binary and the same container image; the role is selected with the WARP_ROLE environment variable.

Role What it does Key ports
full Validating full node — verifies and relays all blocks and transactions. 8338/tcp (P2P)
seed Stable, high-peer-count node that bootstraps peer discovery. Give it a static public IP and advertise it. 8338/tcp
dnsseed Peer-routing / DNS node. Crawls the network and answers DNS A queries for a seed domain with live peer IPs, so new nodes bootstrap by resolving a name. 53/udp, 8338/tcp
verifier Transaction-verifier node. Non-mining full node exposing POST /verify to pre-flight a transaction (signature + nonce + balance) against current state without broadcasting it. 8339/tcp (RPC), 8338/tcp
explorer Block-explorer node. Serves the public explorer UI and supply API (for listing trackers like CoinGecko) over HTTP. 8340/tcp, 8338/tcp
market Market data service. In-memory order book + matching engine exposing CoinGecko/CoinMarketCap ticker, orderbook, and trade APIs. Chain-independent. 8341/tcp
miner Full node that also mines, paying rewards to WARP_MINER_ADDRESS. 8338/tcp

How bootstrapping fits together

            new node
               │  1. resolve seed.warpcoin.net (DNS)
               ▼
        ┌─────────────┐   returns peer IPs
        │  dnsseed    │──────────────┐
        │ (UDP :53)   │              │
        └─────────────┘              ▼
                              2. dial peers / seed on :8338
        ┌─────────────┐   ┌─────────────┐   ┌─────────────┐
        │   seed      │──▶│ full/verifier│◀─│   miner     │
        │ (many peers)│   │  nodes       │   │ (produces   │
        └─────────────┘   └─────────────┘   │   blocks)   │
                                             └─────────────┘

Environment variables

The entrypoint (deploy/entrypoint.sh) reads these and builds the right command:

Variable Default Notes
WARP_ROLE full full | seed | miner | verifier | dnsseed
WARP_DATADIR /var/lib/warpcoin chain data directory
WARP_P2P :8338 P2P listen address
WARP_RPC 0.0.0.0:8339 RPC listen address (bind privately in production)
WARP_SEEDS — comma-separated host:port peers to dial
WARP_MAXPEERS role-dependent peer cap (seed/dnsseed default 256)
WARP_MINER_ADDRESS — required for miner
WARP_CPUS all cores miner worker threads
WARP_EXPLORER 0.0.0.0:8340 explorer HTTP listen address (explorer role)
WARP_MARKET_HTTP 0.0.0.0:8341 market API listen address (market role)
WARP_MARKET_PAIRS WARP_USDT,WARP_BTC trading pairs (market role)
WARP_MARKET_SEED true seed demo liquidity (market role)
WARP_DNS_DOMAIN — required for dnsseed
WARP_DNS_LISTEN :53 DNS UDP listen address
WARP_DNS_TTL 60 DNS record TTL
WARP_VERBOSE false verbose logging
WARP_EXTRA_ARGS — extra flags appended verbatim

Option 1 — Docker Compose (full local network)

Brings up seed + dnsseed + verifier + full + miner together:

cp deploy/.env.example deploy/.env
# edit deploy/.env: set MINER_ADDRESS (create one with `warpcoin wallet new`)
docker compose -f deploy/docker-compose.yml up --build

Then:

curl http://localhost:8339/healthz                  # verifier health
curl http://localhost:8339/peers                    # peer routing view
curl http://localhost:8340/api/supply/circulating   # explorer supply API
open  http://localhost:8340/                         # block explorer UI
dig @localhost -p 53 seed.warpcoin.local A          # DNS seeder

Option 2 — Single Docker container

docker build -f deploy/Dockerfile -t warpcoin:latest .

# a seed node
docker run -d --name warp-seed -p 8338:8338 \
  -e WARP_ROLE=seed -v warp-seed:/var/lib/warpcoin warpcoin:latest

# a DNS seeder
docker run -d --name warp-dnsseed -p 53:53/udp \
  -e WARP_ROLE=dnsseed -e WARP_DNS_DOMAIN=seed.example.net \
  -e WARP_SEEDS=warp-seed:8338 warpcoin:latest

# a transaction verifier
docker run -d --name warp-verifier -p 8339:8339 \
  -e WARP_ROLE=verifier -e WARP_SEEDS=seed.example.net:8338 warpcoin:latest

Option 3 — systemd (bare metal / VM)

Run one role per host (the default ports are shared):

sudo deploy/install.sh                 # builds + installs binary, unit, configs
sudoedit /etc/warpcoin/seed.env        # edit the role you want
sudo systemctl enable --now warpcoin@seed
journalctl -u warpcoin@seed -f

Roles map to env files: warpcoin@seed → /etc/warpcoin/seed.env, and likewise for full, verifier, miner, dnsseed.

Option 4 — Kubernetes

docker build -f deploy/Dockerfile -t <registry>/warpcoin:latest .
docker push <registry>/warpcoin:latest
# set the image (replace REGISTRY) and miner address secret, then:
kubectl -n warpcoin create secret generic warp-miner --from-literal=address=<your-WARP-address>
kubectl apply -f deploy/k8s/warpcoin.yaml

The manifest deploys the seed as a StatefulSet (stable identity + PVC), the DNS seeder behind a UDP LoadBalancer, verifiers behind a Service, plus a miner Deployment.

Operating a DNS seed

  1. Run a dnsseed node on a host with a public IP and UDP/53 reachable.
  2. In your DNS zone, delegate the seed subdomain to that host:
    • seed.warpcoin.net. NS ns-seed.warpcoin.net.
    • ns-seed.warpcoin.net. A <public-ip-of-dnsseed-host>
  3. New nodes started with --seeds seed.warpcoin.net:8338 (or resolving the domain) receive live peer IPs and join the network.

The seeder only advertises routable IPv4 peers (loopback/private/unspecified addresses are filtered) and prefers peers it is actively connected to.

Security notes

  • The JSON-RPC API (including /verify) is unauthenticated. Keep WARP_RPC on a private interface, or front it with a reverse proxy and firewall. Only the P2P port (and DNS/53 for seeders) should face the public internet.
  • Mining rewards go to WARP_MINER_ADDRESS — use a dedicated wallet and secure its keystore off-host.
  • Run each public-facing role as the unprivileged warpcoin user (the systemd unit and Docker image already do this) with the provided sandboxing.