DarkCircle Suite Docs
Docs / Getting started

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

ToolVersionNeeded for
Node.js22+everything
pnpm10every app is a pnpm workspace
Blender5.xonly to regenerate the 3D scene (optional; the committed .glb is what ships)
Foundryrecentoptional 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:

  1. Verify the 3D asset, check portal sources are pure ASCII, test the redirect router, run the Circleswap unit tests.
  2. Refresh the Quainance launchpad snapshot (best effort), then build Circleswap and DarkSafe.
  3. Build Dark Questate and DarkOrder, run their tests and their integrity gates (a failure stops the deploy).
  4. tools/assemble_site.sh _site.
  5. 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

GateCommandWhat it catches
Asset structurenode tools/verify_qrb_assets.mjsWrong up-axis, orb/room scale, physical light units, stalled animation loops, unused UVs, budgets
Token metadatanode --test q0/packages/quai-service/test/tokenMetadata.test.tsUntrusted contract decoding, chain-first precedence, icon URLs, TTL and negative caching
Redirect routernode tools/test_404_router.mjsProject-pages prefix loss, subdomain and deep-link redirects
Brandbash tools/check_legacy_name.shThe retired product name reappearing in tracked text
Bundle integritybash tools/assemble_site.shA navigation target or vendored module missing from the bundle
Dark Questate integritycd b6 && pnpm integrityLegacy demo artifacts, wrong chain ids, the dev wallet in the production bundle
DarkOrder integritycd d0 && pnpm integrityLegacy codenames, foreign chain ids, dev wallet in bundle, voice grammar accepting a raw address
DarkOrder fuzzcd d0/packages/contracts && forge test43 fuzz properties and 3 invariant campaigns over the shipped bytecode
Dark Questate fuzzcd b6/packages/contracts && forge test27+ fuzz properties and 2 invariant campaigns over the shipped bytecode
Next

Learn to drive the front door: the portal guide, or jump to an app guide from the navigation bar.