How-to guide

Set up Trading development

Use this guide to get the Trading contracts, SDK, and UI compiled and running on your machine.

Where the code lives

Path Contents
solidity/contracts/trading/ Immutable-fee factory, ERC-20 LP pair, stateless router, full-precision math, interfaces, and harnesses compiled by the main Solidity pipeline
shared/trading/ts/trading/ Exact bigint quote math and the maximum insured-exit search; transaction helpers live in ui/trading/ts/protocol/
solidity/ts/trading/deploy/ Deployment from an existing Zoltar core manifest
ui/trading/ Standalone Preact application and walletless TEVM simulation
solidity/deployments/trading/ Generated local deployment manifests; no public addresses are invented here

Build and run

  1. From the repository root, confirm dependencies with test -d node_modules. If they are missing, run bun install --frozen-lockfile && bun run setup.
  2. Run bun run trading:compile. It compiles the core artifacts and then runs the Trading vendor build, which generates ui/trading/ts/generated/contractArtifact.ts. Never edit generated files.
  3. Run bun run trading:test and bun run trading:ui:build.
  4. Start bun run app:serve:trading, then open http://localhost:4163/?simulate=1#/market for the shared browser-local TEVM simulator.

To run the standalone UI in Docker instead, complete the repository-root setup first, then from ui/trading:

docker network inspect zoltar >/dev/null 2>&1 \
  || docker network create zoltar
docker compose up --build --force-recreate

Then open http://localhost:4163/#/market. On Windows, ui/trading/start.bat runs the same Compose command. The final image runs as an unprivileged user and exposes a health check at /. The Docker image copies the canonical mainnet and Sepolia core deployment addresses from the root documentation manifests.

Test transactions against an external node

Start Anvil and create a complete local Zoltar deployment with an operational binary SecurityPool. Export its manifest path as ZOLTAR_DEPLOYMENT_MANIFEST, then run bun run trading:deploy:local for script and integration testing. Deploy the Trading contracts walks through the full Anvil flow. The live UI uses the canonical networks copied from the root deployment manifests; ?simulate=1 instead boots the same browser-local TEVM environment used by Zoltar and Statoblast.

Commands

Command Purpose
bun run setup Frozen install and compile
bun run trading:compile Compile contracts and reusable Trading TypeScript through the main pipelines
bun run trading:test Run SDK, contract-facing, and UI Trading tests
bun run trading:coverage:contracts Trace Solidity execution and require at least 99% production-contract line coverage
bun run trading:check Tests plus the bigint-number-cast guard
bun run trading:ui:build / bun run app:serve:trading Build or serve ui/trading
bun run trading:deploy:local Deploy against an existing local Zoltar manifest
cd ui/trading && bun run docker:build / docker:run Build or run the standalone UI container
bun run trading:gas-costs Report bytecode sizes and funded-fixture operation gas

All root aliases use the trading:* prefix.