# 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:

```sh
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.

#### Indexers (how many, and why)

Subnets have two important Autobase roles:

* **writers**: can append subnet ops
* **indexers**: participate in linearization/indexing (what advances the subnet signed/confirmed view)

Rule of thumb:

* **Non-financial apps**: run **1 indexer**
* **Financial / “value” apps**: run **3 indexers**

For 3-indexer deployments, prefer:

* different datacenters/regions
* different authorities/teams (if possible)

Common practice:

* the **first indexer is the admin** (the initial bootstrap peer)

### 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`)