⚔️ 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/
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 — the treasury and the permissions. Everything goes through
execute, callable only by a holder ofEXECUTE_ROLE.payTribute(invoiceId)receives native QUAI and emitsTributeReceived— the on-chain x402 receipt. - GovernanceToken — ERC-20 + Votes checkpoints. The guild owns it, so minting is a governance act. Balances count only once delegated.
- MajorityVoting — token-hall module. Thresholds are snapshotted per proposal; one vote per address; early execution when yes beats the whole supply.
- CouncilMultisig — council-hall module. Fixed members, N-of-M approvals, an approval can carry try-execution.
- GuildFactory + GuildNameRegistry — the Founding Rite: one transaction deploys and wires everything, mints the founder's power, registers the handle, and leaves the factory with nothing. TokenStackDeployer exists because EIP-170 caps bytecode at 24 KiB.
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)
- Contract calls only work on a zone endpoint; everything here is Cyprus-1
(
0x00..., second byte below0x80), enforced inpackages/core/src/address.ts. - A reverted transaction burns its whole gas limit, so every transaction is simulated
(
quai_call), gas-estimated and access-listed before the wallet is asked to sign. - Deploys grind a CREATE salt until the predicted address lands in-zone; the deploy script
signs from an encrypted keystore only and verifies code hashes on chain before writing
packages/core/src/deployments.ts. - Hardhat cannot build Quai transactions; the Hardhat network here is for tests only.