Getting started
How to build every app, assemble the unified site, serve it locally and deploy it. These are the same commands CI runs.
Prerequisites
| Tool | Version | Needed for |
|---|---|---|
| Node.js | 22+ | everything |
| pnpm | 10 | every app is a pnpm workspace |
| Blender | 5.x | only to regenerate the 3D scene (optional; the committed .glb is what ships) |
| Foundry | recent | optional fuzz / invariant campaigns in Dark Questate, DarkOrder and DarkSafe contracts |
On Windows, Blender lives at C:\Program Files\Blender Foundation\Blender 5.2\blender.exe.
1. Build the apps
Circleswap (q0)
(cd q0 && pnpm install --frozen-lockfile \
&& pnpm --filter quai-service build && pnpm --filter stats-app build)
DarkSafe (multisigows)
(cd multisigows && pnpm install --frozen-lockfile \
&& pnpm --filter @darksafe/core build && pnpm --filter @darksafe/ui build \
&& pnpm --filter @darksafe/verify build && pnpm --filter @darksafe/watcher build \
&& pnpm --filter @darksafe/web build)
Dark Questate (b6)
(cd b6 && pnpm install --frozen-lockfile \
&& pnpm build && pnpm test && pnpm integrity)
Its tests include an end-to-end run against a Hardhat node they start on
127.0.0.1:18545, so that port must be free.
DarkOrder (d0)
(cd d0 && pnpm install --frozen-lockfile \
&& pnpm build && pnpm test && pnpm integrity)
Its suites are unit tests plus Hardhat's in-process network, so they bind nothing.
DarkCircle (x402tumbler)
(cd x402tumbler && pnpm install && pnpm test && pnpm lint)
The UI (ui/) is plain HTML/JS with no build step; it is copied into the bundle as-is.
2. Assemble and serve the unified site
bash tools/assemble_site.sh _site
python -m http.server 8080 --directory _site # then open http://localhost:8080
assemble_site.sh copies the portal, the 3D asset, the vendored three.js, the docs,
the playlist and each app's static build into one directory, and exits non-zero if any
destination the portal links to is missing from the bundle.
3. Regenerate the 3D scene (optional)
blender --background --python tools/build_qrb_scene.py
blender --background --python tools/build_qrb_scene.py -- --preview out.png --frame 30 --no-export
node tools/verify_qrb_assets.mjs
The builder produces assets/3d/qrb_chamber.blend and qrb_chamber.glb
from code; the verifier is a structural gate over the exported asset (up-axis, orb and room
scale, light units, animation seams, triangle and size budgets).
Deployment
.github/workflows/deploy-pages.yml runs on every push to main:
- Verify the 3D asset, check portal sources are pure ASCII, test the redirect router, run the Circleswap unit tests.
- Refresh the Quainance launchpad snapshot (best effort), then build Circleswap and DarkSafe.
- Build Dark Questate and DarkOrder, run their tests and their integrity gates (a failure stops the deploy).
tools/assemble_site.sh _site.- Upload and deploy to GitHub Pages.
.github/workflows/ci.yml runs on every push and pull request and is what says a
change is safe: per-app types, unit and contract suites, fuzz and invariant campaigns, lint,
integrity gates and a production dependency audit for each app.
Quality gates you can run locally
| Gate | Command | What it catches |
|---|---|---|
| Asset structure | node tools/verify_qrb_assets.mjs | Wrong up-axis, orb/room scale, physical light units, stalled animation loops, unused UVs, budgets |
| Token metadata | node --test q0/packages/quai-service/test/tokenMetadata.test.ts | Untrusted contract decoding, chain-first precedence, icon URLs, TTL and negative caching |
| Redirect router | node tools/test_404_router.mjs | Project-pages prefix loss, subdomain and deep-link redirects |
| Brand | bash tools/check_legacy_name.sh | The retired product name reappearing in tracked text |
| Bundle integrity | bash tools/assemble_site.sh | A navigation target or vendored module missing from the bundle |
| Dark Questate integrity | cd b6 && pnpm integrity | Legacy demo artifacts, wrong chain ids, the dev wallet in the production bundle |
| DarkOrder integrity | cd d0 && pnpm integrity | Legacy codenames, foreign chain ids, dev wallet in bundle, voice grammar accepting a raw address |
| DarkOrder fuzz | cd d0/packages/contracts && forge test | 43 fuzz properties and 3 invariant campaigns over the shipped bytecode |
| Dark Questate fuzz | cd b6/packages/contracts && forge test | 27+ fuzz properties and 2 invariant campaigns over the shipped bytecode |
Learn to drive the front door: the portal guide, or jump to an app guide from the navigation bar.