pocket-relay-miner

README

Pocket RelayMiner

Every relay you serve, paid on chain.

Pocket RelayMiner is the supplier side of Pocket Network: it serves relays from gateways to your backends on every transport, charges each one against the application's stake before serving it, and turns what it served into claims and proofs that settle on chain -- through crashes, restarts, Redis outages and partial rejections.

Measured for v0.1.0 on 1 relayer, 1 miner and 1 Redis: 10.7 M relays served at ~2,400 relays/s, through 4 session windows with 6 sessions of 50 suppliers each, and 1,501 of 1,501 claims settled, with the miner killed twice on purpose along the way. The numbers are in the capacity report.

Standalone mode, measured for v0.1.3 with the same load and tests on 1 process: 10.5 M relays at ~2,400 relays/s and 1,500 of 1,500 claims settled, with the process killed twice. The numbers, request latency included, are in the standalone capacity report.

Why operators run it

It gets every relay paid

• Claims and proofs are submitted automatically for every session, and watched until the chain includes them; what did not land is resubmitted while its window is still open.
• A claim or a proof is never lost to a crash, a rollout or a batch the chain partly refuses: the message the chain names leaves the batch, the rest goes through.
• Every relay is charged against the application's stake before it is served, so the relayer does not serve work the session can no longer pay for. If Redis cannot confirm the budget, the relay is refused rather than served for free.

It serves every transport

• JSON-RPC over HTTP, WebSocket, gRPC, REST and streaming (SSE), and CometBFT, routed to your backends per service.
• Ring signatures and sessions are verified on every relay, and every response is signed with the supplier's key.

It scales and survives failure

• Relayers keep no state of their own: all of it lives in one Redis, which every relayer and miner of a deployment shares.
• Miners elect a leader through Redis; a standby takes over when it stops.
• Memory and Redis are bounded at every stage: under pressure it refuses new work cleanly instead of running out of memory.

It refuses to run unsafe

• validate checks a config offline and lists every problem in one pass; --check-stake finds staked services with no backend.
• Both processes refuse to start on a Redis that could lose data (no maxmemory, an evicting policy, a version older than 8.10).

It shows you what it is doing

• Prometheus metrics with a triage order for incidents (docs/METRICS_TRIAGE.md).
• pocket-relay-miner redis decodes sessions, streams, claim trees, meters and every claim and proof submission straight from Redis.

It is built to build on

• pocket-relay-miner relay sends single relays and load tests on every transport, and simulated relays exercise a live relayer end to end without staking or billing anything (docs/SIMULATED_RELAYS.md).
• The bLSAG ring signature a relay carries is documented byte for byte, with working signers in Node.js, Python and Rust and a Go oracle to check yours (examples/relay-signing/).
• Supplier keys come from a keys file or a keyring and reload without a restart (docs/SUPPLIER_KEYS.md).

How it fits

It runs in 1 of 2 modes. High-availability mode: relayers and miners as separate processes, sharing 1 Redis, with replicas:

                 gateways
                    │
        ┌───────────┼───────────┐
        ▼           ▼           ▼
   ┌─────────┐ ┌─────────┐ ┌─────────┐
   │ relayer │ │ relayer │ │ relayer │ ──> your backends
   └────┬────┘ └────┬────┘ └────┬────┘     (stateless: validate, charge, serve, sign)
        └───────────┼───────────┘
                    ▼
               ┌─────────┐
               │  Redis  │  relays, claim trees, the stake meter
               └────┬────┘
            ┌───────┴───────┐
            ▼               ▼
      ┌──────────┐    ┌──────────┐
      │  miner   │    │  miner   │ ──> Pocket chain (claims, proofs)
      │ (leader) │    │(standby) │
      └──────────┘    └──────────┘

1 binary, 2 processes, 1 Redis shared by all of them, every process on the same version. v0.1.0 was tested on 1 relayer + 1 miner and on 2 relayers + 2 miners (the latter at lower load); the load tests and the capacity figures are from 1 relayer + 1 miner.

Standalone mode: 1 process (pocket-relay-miner standalone) runs the relayer and the miner together, keeps its state in an embedded store on local disk, and needs no Redis; no replicas. Released in v0.1.3, and not yet load-tested:

   gateways ──> ┌──────────── standalone ────────────┐ ──> your backends
                │ relayer ──(in the process)──> miner │ ──> Pocket chain
                └─────────────────┬──────────────────┘
                                  ▼
                   embedded store (local disk, no Redis)

docs/deploy/README.md, "Choose a mode" compares the two.

Where to start

Deploy. An AI agent starts at AGENTS.md: the rules and the invariants that stop a deployment.

I want to...	Read
choose a mode and a path, check prerequisites and ports	docs/deploy/README.md
run it with Docker Compose, on beta first	high availability: docs/deploy/DOCKER_COMPOSE.md; standalone: docs/deploy/DOCKER_COMPOSE_STANDALONE.md
run it on a host, binary and systemd	high availability: docs/deploy/HOST.md; standalone: docs/deploy/HOST_STANDALONE.md
run the relayer and the miner in one process, with no Redis	docs/STANDALONE.md
use Kubernetes	no example in v0.1.0; tilt/ runs the stack on a local kind cluster and is a starting point for your own manifests

Configure. The relayer reads its config once, at startup: restart it after every change.

I want to...	Read
see every key, its default and why to change it	high availability: config.relayer.example.yaml, config.miner.example.yaml; standalone: config.standalone.example.yaml
check a config against its schema	config.relayer.schema.yaml, config.miner.schema.yaml, and pocket-relay-miner relayer|miner validate --config <file>
set up Redis (high-availability mode)	config.redis.example.conf
set up supplier keys	docs/SUPPLIER_KEYS.md
start from a minimal config that works	examples/docker-compose/config/, examples/host/

Operate.

I want to...	Read
fix a deployment that does not start or does not serve	docs/deploy/TROUBLESHOOTING.md
know what changed in a version, and what to do before upgrading	the release notes of each version: https://github.com/pokt-network/pocket-relay-miner/releases
run Prometheus and Grafana with ready dashboards	examples/observability/
know which metrics to read, in order	docs/METRICS_TRIAGE.md, and scripts/observability/triage.sh to check them against Prometheus
inspect what is in Redis (high-availability mode)	pocket-relay-miner redis --help; what each key holds: docs/REDIS.md. In standalone mode: the metrics and the logs (docs/STANDALONE.md)
size memory, CPU and Redis for your load	docs/benchmarks/: the v0.1.0 capacity report (high-availability mode), the v0.1.3 one (standalone mode), and how to read them

Test and measure.

I want to...	Read
send a relay or a load test to a relayer, on any transport	docs/testing/DIRECT_CLI.md
test a live relayer without staking or billing	docs/SIMULATED_RELAYS.md
size the connection pool for each backend	scripts/loadtest/README.md
sign a relay from another language	examples/relay-signing/

Understand.

I want to...	Read
follow a relay into a claim, a proof and a reward	docs/CLAIM_PROOF_LIFECYCLE.md
know when two relays count as one	docs/CLAIM_LEAF_MODEL.md
learn the protocol per entity, and where the money moves	docs/protocol/
know what a gateway, the relayer and a backend expect of each other	docs/PROTOCOL_SPEC.md, docs/WEBSOCKET_HANDSHAKE_PROTOCOL.md

Develop. CONTRIBUTING.md: the package map, the development environment, the workflow and every rule for changing the code. Testing guides: docs/testing/ and scripts/README.md.

License

MIT License - see LICENSE