ICU DEX GUI

A dapp for token discovery, trading, liquidity, treasury operations and PulseChain bridge transfers.

Build and run

Use Go 1.26, Node 22.23.3 and Bun 1.4.0.

Wallet-flow tests opt in with ICU_FORK=1 and ICU_FORK_RPC. They require a loopback Anvil endpoint using local chain ID 31337 and the pinned PulseChain block in walletFlows.live.test.ts. ICU_FORK_BLOCK and ICU_FORK_BLOCK_HASH can select another independently verified snapshot.

(cd frontend && bun install --frozen-lockfile && bun run build:preview)
(cd backend && go build -o server ./cmd/server)

Run the backend with the configuration below and serve the frontend build output. The protected /admin route shares the app navigation and wallet controls; admin sections use a sidebar. The admin/ package retains its editor tests and captures. See backend/README.md for server commands and contracts/README.md for the Foundry helpers.

Configuration

The backend requires PostgreSQL and DATABASE_URL. Set JWT_SECRET for admin access. Token discovery follows pool-creation events; keep chains.<id>.discovery.censusMode off for pool-based indexing. Additional TT discovery runs only on chain 369 and requires an RPC supporting trace_filter. Set chains.<id>.rpc.urls, browser-reachable chains.<id>.rpc.publicUrls, frontend.rpcFallbackUrls (ordered URL lists keyed by chain ID), and contract addresses through the admin panel or data/config/config.json; see config.example.json and .env.example. Bootstrap the first admin wallet with server -set-admin 0xYourAdminWalletAddress. RPC endpoints are operator configuration; no endpoint lists are bundled.

Optional R2 mirroring uses chains.<id>.exports.r2AccountId, r2Bucket, r2Prefix, r2AccessKeyFile, r2SecretKeyFile and r2PublicBase. Credential fields name protected backend files, never key values. The public base URL must include the configured object-key prefix. Browser readers try local snapshots before R2; allow their origins through bucket CORS. Mutable JSON revalidates, while content-addressed LP chunks are immutable. Upload failures retain the last published copy and retry without stopping indexing or local exports.

The admin quick-select page manages lists by chain and purpose, including address-list paste and JSON import/export. Treasury shortcuts start empty; indexed tokens, parent tokens and personal favorites remain available. Catalog request budgets use limits.browseRateLimitRpm and limits.browseRateLimitIpRpm.

Fresh databases contain no curated recipes. Import operator-provided JSON through the admin panel or server -import-content-file <file.json>.

Wallet signing and submission stay with the connected wallet. LP discovery checkpoints are scoped by wallet and chain in browser storage; clearing that storage removes the checkpoints.

Public API

Chain APIs use /api/{chainId}/. Token feeds support search and cursor pagination; GET /api/{chainId}/tokens?includeTotal=0 omits total calculation and returns totalEstimate: -1. Bridge catalogs expose freshness information and conditional ETag reads at /api/{chainId}/bridge/tokens. See the backend documentation for additional endpoints. Authenticated DEX factory listings at GET /api/{chainId}/admin/dex-labels accept q, offset and limit, and return total and nextOffset. Quick-select reads use GET /api/{chainId}/quick-select?purpose=dex-swap; supported purposes are dex-swap, dex-liquidity, bridge, treasury-convert and launch-parent.

GET /api/{chainId}/pool/{ref}?includeTokens=all includes all registered token addresses, including pool shares and native currency sentinels. tokensComplete indicates whether full membership is known. The pool list accepts GET /api/{chainId}/pools?includeTokens=all for the same complete member data; includeTokens=1 retains the liquidity-picker view.

Deployment

Use the tracked docker-compose.yml with an existing database. Set DATABASE_URL, FRONTEND_HOST, JWT_SECRET and VERSION; preserve the database, configuration and snapshot mounts during upgrades. Run one backend instance.

VERSION must be the exact tag matching the frontend package version. Preview builds show a -dev footer. From frontend/, set VITE_RELEASE_VERSION to v followed by the version in package.json for bun run build:release. bun run smoke checks a served app using SMOKE_ORIGIN, BROWSERLESS_URL and BROWSERLESS_TOKEN. The routing adapter image retains its dependency licenses and corresponding router source.

Font licenses

Inter Variable and JetBrains Mono Variable use SIL Open Font License 1.1. Their licenses ship in frontend/public/licenses/ and are served at /licenses/ separately from the project license.

License

MIT — see LICENSE.