DarkCircle Suite Docs
Docs / DarkOrder

⚔️ DarkOrder · Grand Guild Halls Showcase

Guild governance for the DarkCircle suite on Quai Network (Cyprus-1). Found a guild in one transaction, govern it by checkpointed token vote or council multisig, govern members by QNS name (quaidomains.com), pay or charge x402 tribute, and drive every flow with a voice seneschal. Source: d0/ · Route: /darkorder/

Where it stands

The contracts (GuildFactory, GuildHall, TokenStackDeployer) are not deployed on Orchard or mainnet, so the site runs as a labelled showcase: invented sample halls, marked as such, with every transaction switched off. QNS names resolve only against a live deployment. No independent audit.

The protocol

Guild profiles and the steward's desk

A guild's on-chain metadata string is its charter. Plain text reads as the description; the structured form is a one-line marker plus JSON (darkorder:profile:1\n{"description","avatar","links"}). Crests are raster data URIs (PNG/JPEG/GIF/WebP, ≤ 24 KB so they fit one transaction) or https/ipfs pointers; link URLs are https/ipfs only, so the hall page never renders a javascript: payload.

Each hall page carries the steward's desk: a connected key holding SET_METADATA_ROLE rewrites the charter directly, a key holding ROOT_ROLE grants and revokes roles, and anyone can route either change through a proposal instead — the proposal executes as the guild itself, which holds every permission. The War Room decodes setMetadata / grant / revoke proposal actions into plain language before a vote.

Voice seneschal

packages/core/src/voice is a grammar, not a language model: a closed intent list, the same answer every time, offline. Hard rules: voice never carries an address (checked before tokenization), it never sends payments to spoken names, and tribute always names its asset. Planned actions get a spoken 3-digit confirmation code with a 3-minute TTL. The web page asks before opening the microphone (cloud transcription), and the typed command line is always first-class. The steward's desk is voice-reachable too: "open the steward's desk", "edit the charter" or "grant metadata power to ..." all walk to the desk of the current hall.

x402 tribute

packages/core/src/x402/challenge.ts parses DarkCircle-compatible challenges (RFC 7807 body → WWW-Authenticate → X-Payment-*) and adds the native quai_native_tribute scheme: the recipient is the guild contract and the body carries payTribute(invoiceId) calldata, so paying the invoice writes the invoice id into the guild's event log. Token decimals are validated against the known-token registry; a challenge that misstates them is rejected.

Build, test, rehearse

cd d0
pnpm install
pnpm build          # contracts compile, core + web type-check and build
pnpm test           # hardhat tests + vitest (core incl. a live-chain suite + web)
pnpm integrity      # static gate
pnpm dev            # the site on http://localhost:5300
pnpm rehearse:local # deploy to a local Hardhat node, found two halls, walk the steward paths

Rehearsal chain. pnpm rehearse:local starts a Hardhat node on port 8646, deploys the protocol, founds crimsonvigil (token) and ashencouncil (council) with structured charters, and writes apps/web/.env.localchain.local. Then pnpm dev:local serves the site with a dev wallet in the network picker: account 0 is the founder, 1 the voted-in steward, 2-3 council members. pnpm integrity checks the dev wallet is absent from production builds.

Foundry assurance. cd packages/contracts && forge test runs 43 fuzz properties (x1000 runs) and 3 invariant campaigns over the exact Hardhat-compiled bytecode: the QNS charset rule, the permission wall, all-or-nothing batches, vote tallies and threshold arithmetic, quorum at execution and treasury accounting. Slither runs in CI and fails on medium or higher.

Quai specifics (learned on Cyprus-1)