Start here
From nothing to sealed governance
Five steps, in order. Most people should stop after the second one — and that is a real recommendation, not modesty. Steps 3 onwards commit you to processing personal data about your voters, and that deserves a decision rather than momentum.
See what your governance could prove
Paste your Snapshot space or Safe address into the scan. It reads your last 90 days and grades every action by how strongly it is bound to observable reality.
Run the scanNothing is sealed, no record is created, and no wallet address is retained.
Run it yourself, against your own data
Same code, on your machine, with no credential and no writes. If the scan interested you, this is where you confirm it is real.
# A Snapshot space:
npx witness-dao ingest --dao your-space.eth --source snapshot
# Or a Safe (--chain-id 1 Ethereum, 10 Optimism, 8453 Base, 42161 Arbitrum):
npx witness-dao ingest --dao 0xYourSafe... --source safe --chain-id 1
# What WOULD be sealed — builds the requests, sends nothing.
npx witness-dao seal --dao your-space.eth --source snapshot --dry-runPass --source, and expect exit code 4 if you don’t. Every configured source runs unless you narrow it, so a Snapshot space id handed to the Safe reader fails — and this tool treats a failed source as a gap in the evidence trail, prints it, and exits 4 rather than quietly returning what it did manage to read. That is the behaviour you want in a scheduled job at 3am. It is merely startling the first time you meet it.
A good place to stop. Everything above is free, read-only and permanent-consequence-free. If you only ever use Witness-DAO to understand your own evidence position, that is a legitimate use of it and you owe us nothing.
Decide before you seal
Sealing builds permanent, externally anchored records about identified natural persons — your voters and signers, who are not your customers and are never asked. Three things need answering first, and none of them is technical:
- Your lawful basis. Legitimate interests with a documented assessment is the likely route, and the balancing test differs sharply between “defending our own signer” and “monitoring everyone who votes here”.
- Your retention period, derived from a limitation-period analysis. A retention period you cannot point at in writing is not a retention period.
- Who signs the attestation. This product produces evidence; turning it into a regulatory artefact needs an accountable human. Many DAOs have not decided who that is, and the wrapper is usually the answer.
Read DATA-PROTECTION.md before your first seal — it contains a DPIA input pack and an Article 30 template, and it is explicit about what the product cannot supply for you.
Set up the trail
Two inputs: a credential, and a directory of governance rules held in git. The rules are what make the evidence worth anything — a decision recorded without the rule that authorised it is a log line, not governance evidence.
# 1. A key. Self-serve mints the free Sealed tier — DEVELOPMENT ONLY,
# because Sealed records are never anchored and that state is terminal.
npx witness-dao keys mint
# 2. Bind a controller key on day one. Witness keys are short-lived; without
# this there is nothing to renew with and sealing eventually just stops.
openssl genpkey -algorithm ed25519 -out controller.pem && chmod 600 controller.pem
export WITNESS_DAO_CONTROLLER_KEY_FILE=$PWD/controller.pem
npx witness-dao keys bind-controller
# 3. Your ratified rules, in git. ruleVersion resolves to the commit SHA,
# which is what makes a charter-versus-code dispute resolvable later.
export WITNESS_DAO_RULES_DIR=./governance-rules
# 4. Confirm the wiring. Seals nothing, spends no quota.
npx witness-dao selftestThe rules directory is a trust boundary. Its contents are sealed verbatim into every matching record and git metadata inside it is executed against. Write-restrict it to the people entitled to change your governance, and never point it at a path a third party can write to.
Schedule four jobs, not one
This is the part that decides whether you actually have an evidence trail in six months. Sealing is fail-open by design, so an outage never takes down your governance pipeline — but that is only safe because something drains the queue afterwards.
| Job | Cadence | Skip it and… |
|---|---|---|
seal --dao <id> --since | hourly | nothing is recorded at all |
seal --dao <id> --retry | every 15–30 min | failed seals are never replayed, and once --since moves past that window those actions are absent from the trail permanently |
anchor upgrade | hourly | records stay SIGNED_PENDING forever |
keys renew | daily | the short-lived key expires and sealing stops |
RUNBOOK.md ships systemd timers and Kubernetes CronJobs for all four, plus the metrics worth alerting on. Read §6 too: anchor-runs.json is the only copy of your anchor proof material and it cannot be reconstructed from anywhere. Back it up.
What you get at the end
A governance evidence report
Every sealed decision in a period, the version of the rule that authorised it, and the verification verdict for its record. Reproducible offline — opposing counsel can regenerate it and get yours.
A liability-defence pack
For a named signer: what they did, and — the valuable half after Ooki and Lido — what they provably did not do, with the basis for each absence claim stated explicitly rather than assumed.
Both refuse to build from unanchored Sealed-tier records by default, and out of the box no anchor can be independently verified — so records cap at SIGNED_PENDING until you supply pinned trust material. That is the honest ceiling of a free deployment and it is stated in every report. See pricing for what changes it.
If you get stuck
npx witness-dao <command> --help— every flag is documented, and the help text states the honesty properties rather than just usage.- Exit codes are meaningful and stable:
3means a record verifiedBROKEN(possible tampering),4means a gap in the trail. Never treat4as success. - RUNBOOK.md is written for whoever gets paged and assumes they did not write the code.
- Verify anything you are handed at /verify, or fetch the signing key yourself from
https://witness.getvda.ai/.well-known/did.json.