# App dev

## App Development (Protocol + Contract)

In Trac, an “app” is a subnet:

* the subnet is a P2P ordered log
* the contract is executed locally on every node from that ordered log
* MSB settlement is used as the global source of truth for tx finality and fee checks

This repo ships a demo app:

* `dev/tuxemonProtocol.js`
* `dev/tuxemonContract.js`

### 1) Protocol: map user input into `{ type, value }`

Protocols extend `src/artifacts/protocol.js` and should implement:

* `mapTxCommand(commandString)`

This is used by the interactive CLI `/tx --command "..."`.

dApps generally skip string parsing and send a structured `prepared_command` directly.

### 2) Contract: deterministic state machine

Contracts extend `src/artifacts/contract.js`.

Important rules:

* contracts must be deterministic (no network IO, no system time)
* all nodes execute the same ordered ops and must reach the same result

The contract uses a key/value state store. App-defined state should live under:

* `app/<your-app>/...`

### 3) Exposing “ABI-like” contract schema

Wallets/dApps need to know which tx types exist and what their input shapes are.

`trac-peer` exposes a discovery document at:

* `GET /v1/contract/schema`

The base contract supports metadata registration:

* `addFunction(type)` — declares a tx type exists (untyped inputs)
* `addSchema(type, schema)` — declares a tx type + a validator schema (preferred)

If you don’t register schemas, clients can still submit txs, but they’ll have to treat `value` as opaque.

### 4) Read APIs (Protocol API)

The protocol instance exposes `protocol.api`, which is intended for read/query methods.

Those methods can be reflected in the RPC schema so dApps can discover them (similar to “read-only RPC calls” in other ecosystems).

### 5) Where to wire your app

The default runner `scripts/run-peer.mjs` currently wires the demo app.

For your own app:

1. add your protocol/contract under `dev/`
2. create a new runner script that imports them
3. run that runner with the same MSB/subnet flags

See `intercom` in this workspace for a reference project that uses `trac-peer` as a dependency.

*