Production notes

This page captures operational guidance for running trac-peer “for real” (public URLs, wallets/dApps, and multiple subnets).

1) Security boundaries (what is safe to expose)

trac-peer has two user classes:

• Operator (node owner): uses the interactive CLI to administer a subnet (admin, writer/indexer management, chat moderation, deployment).

• Client (wallet/dApp): uses HTTP RPC to read schema/state and optionally submit signed contract txs.

Design rule:

• Do not expose operator actions via HTTP.

• Only expose wallet/dApp endpoints via HTTP.

In this repo, the public RPC is intentionally limited to:

• health/status

• schema/context/nonce

• state reads

• tx submission (only when explicitly enabled)

2) RPC exposure (--rpc + --api-tx-exposed)

Start RPC:

npm run peer:run -- --rpc --rpc-host 127.0.0.1 --rpc-port 5001 ...

Tx submission is opt-in:

• --api-tx-exposed (or PEER_API_TX_EXPOSED=1)

If you start without --rpc, --api-tx-exposed is ignored.

CORS

Set --rpc-allow-origin (defaults to *).

For production, prefer a strict origin list (or terminate behind a reverse proxy that handles CORS).

Body limits

Request bodies are capped (default 1_000_000 bytes).

Override with:

• --rpc-max-body-bytes <n>

Keep this bounded; large bodies can become a DoS vector.

3) Recommended deployment topology

Typical patterns:

• One public RPC per subnet/app (a “gateway peer”), behind TLS and rate limits.

• Multiple internal peers to increase redundancy/availability (not necessarily exposed publicly).

Notes:

• A wallet needs the peer URL to fetch subnet state and tx details.

• If you plan to run many subnets/apps, you’ll eventually want a registry/explorer that maps “app identity” → peer URLs.

4) Reverse proxy + TLS (recommended)

Run the peer RPC on localhost and expose it via:

• nginx / Caddy / Cloudflare / API gateway

Why:

• TLS termination

• request size limits

• rate limiting

• access logs

• origin restrictions

5) Key management

Each peer has:

• MSB client keypair: stores/<msb-store>/db/keypair.json

• subnet peer keypair: stores/<peer-store>/db/keypair.json

Rules:

• Treat these files like private keys.

• Back up stores if you need persistence across restarts.

• Rotating keys effectively creates a new identity (and may lose admin/writer privileges).

6) Fees and “what can a contract do”

Contract transactions are MSB operations of type = 12.

• They can spend MSB fees (the requester must have an MSB entry and enough fee balance).

• They cannot transfer TNK to an arbitrary recipient (no to/amount in type-12 contract tx).

If you ever add native TNK transfer support, it must be a different MSB operation type and should be clearly surfaced in wallet UI (recipient/amount).

7) Observability (what to monitor)

On the peer CLI:

• /stats — subnet writer/indexer state, connectivity, DAG lengths

• /msb (demo protocol command) — prints MSB txv + lengths + fee + peer MSB balance

On RPC:

• GET /v1/status — peer + embedded MSB view summary

Recommended to monitor:

• RPC process uptime

• memory and CPU

• swarm connection counts

• subnet signedLength advancing

• MSB signedLength advancing (from embedded MSB client)

8) Confirmed vs unconfirmed reads

GET /v1/state?confirmed=... refers to the subnet view:

• confirmed=true: subnet signed view

• confirmed=false: latest local view

This is not identical to “MSB finality”; it reflects subnet indexing/signed length.

Client guidance:

• Use confirmed=false for fast UI updates.

• Use confirmed=true for “final” UI states if you require subnet-signed snapshots.

9) Rate limiting and abuse prevention

If you expose POST /v1/contract/tx publicly:

• enforce rate limits per IP/origin

• enforce burst limits

• keep request size bounded

• consider requiring a wallet connect / origin allowlist at the application layer

Even with signature validation, the RPC can be abused for compute-heavy simulations.

10) Upgrades / compatibility

For production, pin versions:

• trac-peer

• trac-msb

• trac-wallet

When upgrading:

• validate tx signing preimage compatibility (/v1/contract/tx/context fields)

• validate RPC endpoint compatibility

• validate contract schema compatibility (/v1/contract/schema)