> For the complete documentation index, see [llms.txt](https://docs.trac.network/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.trac.network/documentation/developers/mainnet/dapp-developer-guide/references-examples/trac-dapp-example.md).

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


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.trac.network/documentation/developers/mainnet/dapp-developer-guide/references-examples/trac-dapp-example.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.