# Running trac-peer

## Running `trac-peer` Nodes

This page documents the node runners, CLI flags/env, and how “bootstrapping vs joining” works.

### Two layers run together

`trac-peer` currently runs *on top of an in-process MSB client node* (from `trac-msb`).

That MSB client node is required to:

* broadcast subnet deployments + contract tx payloads to MSB, and
* observe MSB “confirmed” state to decide which MSB txs can be executed locally in the subnet.

You still run your own MSB network separately; `trac-peer` just joins it via this embedded client node.

### Runners

#### Node runner (recommended to start)

```sh
npm run peer:run -- --msb-bootstrap=<hex32> --msb-channel=<string>
```

#### Pear runner

```sh
npm run peer:pear -- --msb-bootstrap=<hex32> --msb-channel=<string>
```

Pear is useful when you want parity with Pear-based MSB runs. If Pear warns about PATH, follow its message once so `pear` resolves directly.

### Required MSB params

You must provide:

* `--msb-bootstrap=<hex32>` (64 hex chars)
* `--msb-channel=<string>`

Or env vars:

* `MSB_BOOTSTRAP`
* `MSB_CHANNEL`

### Stores (running multiple nodes on one machine)

Each node has:

* a **peer store** (subnet state/logs)
* an **msb store** (embedded MSB client state/logs)

Use distinct names when running multiple nodes locally:

```sh
npm run peer:run -- \
  --msb-bootstrap=<hex32> \
  --msb-channel=<string> \
  --msb-store-name=peer-msb-1 \
  --peer-store-name=peer1
```

Defaults:

* `--peer-stores-directory` defaults to `stores/`
* `--msb-stores-directory` defaults to `stores/`
* `--msb-store-name` defaults to `<peer-store-name>-msb`

Keypairs are stored at:

* `stores/<msb-store>/db/keypair.json`
* `stores/<peer-store>/db/keypair.json`

### Subnet identity: channel + bootstrap

All nodes in the same subnet must share:

* `--subnet-channel=<string>`
* `--subnet-bootstrap=<hex32>`

#### Creating a new subnet (bootstrap node)

If you omit `--subnet-bootstrap`, `trac-peer` will generate one and persist it to:

* `stores/<peer-store-name>/subnet-bootstrap.hex`

That file is the join-code for other peers.

#### Joining an existing subnet (joiners)

Pass the bootstrap hex and the same channel:

```sh
npm run peer:run -- \
  --msb-bootstrap=<hex32> \
  --msb-channel=<string> \
  --msb-store-name=peer-msb-2 \
  --peer-store-name=peer2 \
  --subnet-channel=tuxedex-v1 \
  --subnet-bootstrap=<SUBNET_BOOTSTRAP_HEX32>
```

### RPC mode vs interactive CLI

`scripts/run-peer.mjs` disables the interactive terminal when RPC is enabled.

Enable RPC:

```sh
npm run peer:run -- \
  --msb-bootstrap=<hex32> \
  --msb-channel=<string> \
  --rpc \
  --rpc-host=127.0.0.1 \
  --rpc-port=5001
```

If you also want dApps/wallets to submit txs over HTTP, add:

```txt
--api-tx-exposed
```

If you start without `--rpc`, `--api-tx-exposed` is ignored (operator safety).

Env equivalents:

* `PEER_RPC=1`
* `PEER_RPC_HOST=127.0.0.1`
* `PEER_RPC_PORT=5001`
* `PEER_API_TX_EXPOSED=1`

### Flag format (important for shells)

Both are accepted:

* `--subnet-bootstrap=<hex32>`
* `--subnet-bootstrap <hex32>`

When using `npm run ...`, remember the double-dash:

```sh
npm run peer:run -- --msb-bootstrap=<hex32> --msb-channel=<string>
```

Without the second `--`, npm will swallow flags.