Checks and troubleshooting

Run the commands from the repository root. Use Node.js 22.12 or later, pnpm 11, and Foundry. Keep keys in the root .env file. Keep the public browser settings in web/.env.local.

Choose the test

Test	Necessary processes and accounts
UI layout preview	Web server only. No funded account.
MetaMask connection	Web server and the installed extension. No gas for the connection.
Live market display	Web server, API, configured RPC, and a deployment file
Browser trading	Web, API, operator loop, funded relayer, two funded makers, and a funded browser wallet
Oracle shock only, testnet	Deployment file and funded deployer. The shock command does not need a maker key or a relayer key.
Hedging demo	The full local exchange. See Hedging demo.

An oracle price alone does not create a funded trader position or valid book depth. A useful trading demonstration needs the two.

UI preview

pnpm install
pnpm dev:web

Open http://localhost:3000. Without API data, the panels show labeled samples and trading is disabled. Connect MetaMask separately to test the extension prompt.

Automated checks

pnpm contracts:test
pnpm typecheck
pnpm test
pnpm test:abi
pnpm build

Command	Scope
pnpm contracts:build	forge build --root contracts
pnpm contracts:test	The Foundry suite: accounting, matching, ladders, the queue, sessions, risk, and gas measurements
pnpm typecheck	TypeScript in the workspace packages, integration/, and scripts/
pnpm test	Unit tests of the workspace packages and the LP model test in integration/ui-math.test.ts
pnpm test:abi	Compares the shared ABIs with the compiled Solidity. Build the contracts first.
pnpm test:budget	Cost records and pending transaction recovery of the fast testnet loop
pnpm test:smoke	An Anvil integration check through the relayer. Do not point it at the public testnet.
pnpm test:ui	Playwright layout checks. They need a running web server and an installed Chromium.
pnpm build	Builds all workspace packages that have a build script, the documentation site included

For the browser layout check:

pnpm exec playwright install chromium
pnpm test:ui

This check covers the offline preview and the narrow screen layout. It does not cover wallet transactions.

Python reference

The Python research checks are separate:

uv run --project simulation python -m unittest discover -s simulation -p 'test_*.py' -v
python3 integration/reference.py

The reference script uses the standard Python library and the market model in simulation/. The Solidity test testPythonReferenceFortyOneContracts checks the same trade and funding path to within 0.000001 USDC.

What a passing check proves

A successful build does not prove that wallet transactions work on testnet. Passing accounting tests do not establish economic safety. See the verification record in Decisions and open work.

Failure diagnosis

Symptom	Check
The terminal shows sample data	The API process, the API URL in web/.env.local, the deployment file, and RPC access
MetaMask cannot connect	The extension is available and the selected network matches NEXT_PUBLIC_CHAIN_ID
The wallet shows a nonce error on the local chain	Reset the account activity in the wallet after each restart of Anvil
Orders cannot be relayed	A funded relayer, an active session, GET /health, and the gas cap RELAYER_MAX_GAS
The banner says that the relayer has no gas account	RELAYER_PRIVATE_KEY is not set for the API
An order confirms with zero fills	Read OrderResult. The price limit did not cross, or an observation was due.
Mark frozen	Two-owner depth, the spread, and the quote age on the two sides. Is the operator loop running?
Observation overdue	The operator loop. Stop it before an explicit recovery.
Oracle halted	The gap limit passed. Run the recover command for that deployment.
Position closed but margin kept	The funding position stays until the next accepted observation
A withdrawal fails with free collateral above zero	The mark is frozen, an observation is due, or the oracle is halted
The shock bar does not show	GET /health must report shockEnabled: true. This needs the test oracle and either chain 31337 or SHOCK_ENABLED=true for the API.
The API stops with a chain ID error	RPC_URL and DEPLOYMENT_FILE select different chains
Old history after a new local deployment	Delete .local/local-indexer.json and start the API again
The RPC host does not resolve	Network and DNS access. No deployment can continue without it.

The API binds to 127.0.0.1. A testnet contract deployment does not publish the web application. Shared public access needs a separate hosting setup.

Local scripts and testnet scripts

	Local	Testnet
Chain ID	31337	10143
Commands	pnpm local:deploy, pnpm demo ...	pnpm testnet ...
Keys	Public Anvil accounts	Private accounts in .env
Deployment file	deployments/local.json	deployments/monad-testnet.json by default

Each script checks the chain ID before it sends a transaction. Do not interchange them.