# Trac dApp Example

## Example dApp: `trac-dapp-example` (Wallet + Peer RPC)

This workspace contains a minimal reference dApp that demonstrates the intended client flow:

* dApp talks to a `trac-peer` HTTP RPC (a URL)
* dApp fetches schema + nonce + tx context
* wallet signs the contract tx (`window.tracnetwork.signTracTx(...)`)
* dApp submits `sim=true` then `sim=false`
* dApp reads contract state via `GET /v1/state`

In this workspace, that dApp lives in the folder:

* `trac-dapp-example/`

For documentation purposes we refer to it as [**`trac-dapp-example`**](https://github.com/Trac-Systems/trac-dapp-example) (it is a “catch creatures” demo).

***

### 1) Start a peer RPC node (the backend the dApp talks to)

You need a `trac-peer` node running with RPC enabled.

Example:

```sh
cd trac-peer

npm run peer:run -- \
  --msb-bootstrap=<MSB_BOOTSTRAP_HEX32> \
  --msb-channel=<MSB_CHANNEL> \
  --peer-store-name=peer-rpc \
  --msb-store-name=peer-rpc-msb \
  --subnet-channel=tuxedex-v1 \
  --rpc \
  --api-tx-exposed \
  --rpc-host 127.0.0.1 \
  --rpc-port 5001
```

Quick checks:

```sh
curl -s http://127.0.0.1:5001/v1/health | jq
curl -s http://127.0.0.1:5001/v1/contract/schema | jq
curl -s http://127.0.0.1:5001/v1/contract/tx/context | jq
```

Notes:

* `--api-tx-exposed` is required for the dApp to submit `POST /v1/contract/tx`.
* The peer must have enough MSB fee balance for contract txs; fund its printed `Peer MSB address` on MSB.

***

### 2) Install and run the dApp

```sh
cd trac-pokemon-hack
npm install
```

The Next.js server proxies requests to the peer RPC via env vars:

```sh
UPSTREAM_PROTOCOL=http \
UPSTREAM_HOST=127.0.0.1 \
UPSTREAM_PORT=5001 \
UPSTREAM_PREFIX=/v1 \
npm run dev
```

Open:

* `http://127.0.0.1:3000`

***

### 3) Wallet requirements

The dApp expects a browser wallet extension that injects:

* `window.tracnetwork`

and supports:

* `requestAccount()`
* `getAddress()`
* `getPublicKey()`
* `signTracTx(contractTx)`

In this workspace, see:

* `tap-wallet-extension/`

***

### 4) What happens when you click “Catch”

The dApp:

1. calls `GET /v1/contract/schema` (checks the contract supports `catch`)
2. calls `GET /v1/contract/nonce`
3. calls `GET /v1/contract/tx/context`
4. builds the wallet signing payload (`contractTx`) with:
   * `{ prepared_command, nonce, context }`
5. calls `window.tracnetwork.signTracTx(contractTx)` to get `{ tx, signature }`
6. calls `POST /v1/contract/tx` with `sim=true`
7. calls `POST /v1/contract/tx` with `sim=false`
8. polls state under:
   * `app/tuxedex/<pubKeyHex>` (unconfirmed view)

The peer’s demo contract writes the user’s “dex” under that key.

***

### 5) Troubleshooting

#### “Wallet extension not detected”

The dApp can’t find `window.tracnetwork`. Install/enable the wallet extension and reload the page.

#### “Requester address not found in state” / insufficient fee balance

Fund the **wallet’s MSB address** (the requester) on MSB so it can pay MSB fees for `type=12` contract txs.

Also ensure the peer’s own MSB address is funded so it can operate reliably.

#### Wrong peer / wrong contract

If `GET /v1/contract/schema` does not include `"catch"` in `contract.txTypes`, you’re pointing the dApp at a peer running a different contract/app.