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

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:

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

cd trac-pokemon-hack
npm install

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

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.