Village Gateway: technical details
How a Village Gateway decision is signed, time-stamped, anchored and checked, for the people who will integrate it or audit it.
Check a record yourself About Village Gateway Read the step-by-step guide
What is in a record
Each decision is recorded as a receipt. The receipt carries an Ed25519 signature over its canonical form, and it names its signer: the decentralised identifier (DID) of the Village and the id of the key that signed it.
A decision record is exported as one envelope, gw/export/v1, holding the decision, its approvals, the receipt and the events. The export signature covers the whole export, including the time_attestation block described below, so a change to any field of it fails the check.
An allowed request is given a single-use permit. The permit is signed on its own and carries a unique value, its nullifier, that stops it being used twice. The system that carries out the action redeems it exactly once. The permit sits beside the export and is checked separately.
The public keys travel in a trust bundle that the Village supplies. The checking program takes that bundle as its input and trusts a key for one reason only: you hold the bundle. A key that appears inside the export is never trusted.
The outside time stamp
For each receipt, Village Gateway asks Certum in Poland, an outside time-stamping authority, for an RFC 3161 time stamp. The daily estate root is stamped separately, by two authorities, as the section on the daily root below sets out.
The authority time-stamps a hash of the signed receipt. The imprint is sha256('gw/receipt-stamp/v1\n' + canonical signed receipt), with the receipt's signature included.
A stamp shows that the hash existed no later than the authority's stated time. It does not stamp the decision time, the events or the permit and redeem times.
If the authority does not answer, the receipt is still issued and the export shows the stamp as pending. Nothing waits for the stamp. A nightly pass asks again for any stamp that was missed. This is not a qualified time-stamp.
The checking program checks a stamp offline: it recomputes the imprint itself, checks the hash inside the token and the authority's signature, and builds the certificate chain from the certificates in the token and those fixed inside the program, ending on a key fixed inside the program. A certificate supplied in the export or in the bundle is ignored.
The keys of four European time-stamping authorities are fixed inside the checking program: Certum (Poland), BOSA (Belgium), CESNET (Czechia) and the Portuguese state's Cartão de Cidadão authority. It verifies a stamp from any of them.
The daily root and Midnight
Where a Village hosted in the EU has turned daily sealing on, each day's decisions are sealed into one day root for that Village. The day root is itself signed and time-stamped. It joins the daily estate root. Anchoring a hash of the estate root record (its date, root and previous root) on Midnight mainnet is built; the anchors in the published index so far were made on Midnight's Preview network.
The daily estate root is time-stamped by two European authorities: Certum (Poland) and the Portuguese state's Cartão de Cidadão authority. The published index of estate roots, GET /api/email-decision-record/estate-root/index, shows both stamps on 36 of the 36 roots up to 8 November 2026.
No request or decision content leaves the Village. Where anchoring is turned on for a Village hosted in the EU, only a hash of the daily estate root record goes to Midnight, never content.
The anchor proof comes from the Village's own route, GET /api/v1/gateway/decisions/:id/anchor-proof. The ledger reading is the text printed when the Village or MDSL runs midnight-anchor/verify-anchor.mjs.
The checking program can read an anchor proof and a ledger reading that you supply, with the options --anchor-proof and --anchor-check. It recomputes the receipt's leaf, the leaf's path to the Village's day root, that root's path to the estate root and the anchor key for the date, and it opens no connection to any ledger. The anchor line is supplementary: it never changes the exit code.
Check a record yourself
The checking program is one JavaScript file you can read. It needs Node.js version 20 or newer, opens no network connection and needs no product installed.
A decision record can be exported with its approvals, receipt and events, and an offline checker (Node 20, no network, no product installed) verifies the export against a bundle of public keys.
Village Gateway sends every receipt it signs to an outside time-stamping authority (Certum), and the checking program verifies the RFC 3161 stamp offline when an export carries one; on 4 Nov 2026 a decision was held, approved with a step-up sign-in, given a one-use permit and exported, and the checking program returned verified, including the Certum stamp.
Download the checking program Sample exported record Sample bundle of public keys
SHA-256 of the checking program, as this site serves it:
2140b79aa2d2bd717bce326d2920ec7f37685c5e223e2128b5ee6ee7dcb37a29
node gateway-evidence-verifier.js gateway-export-sample.json --bundle gateway-trust-bundle-sample.json
The two samples are synthetic: a key made only for these samples, and invented values. Run on the sample, the checking program exits with 1, by design. The sample export was made before any outside time stamp had been obtained for its signed receipt, so the checking program reports the time-stamp check as incomplete, and a mandatory check that cannot be made is counted as not passed, so the program exits with 1. When an export carries a stamp, the checking program checks it offline. Exit codes: 0 every mandatory check passed; 1 a check failed or could not be made; 2 a usage error or an unreadable file; 3 a version this copy does not know.
- That the signed receipt and the exported record carry valid signatures from a key in the bundle of public keys you hold, and, where the bundle states a validity period, that the key was valid when the decision was made.
- That the approvals and the events agree with the decision's final state, and that a decision does not show a state its events do not reach.
- That the checking program is the file described here: compare its SHA-256 with the value above.
Publishing the checking program is for reading and checking. It is not a licence to anything.
What the checking program verifies
- The export is a well-formed record with a closed schema: a field it does not know fails the check.
- Both signatures, on the receipt and on the export, are checked with the key the trust bundle lists under that key id, at the decision time the record states; where the bundle gives the key's validity period, the program checks it.
- The decision block repeats exactly what the signed receipt says.
- The action commitment recomputes from the exported action.
- The approvals and the events agree with the finding and with each other: their count, their times and their order.
- When a permit is supplied: its signature, its claims and its nullifier.
- The RFC 3161 time stamp: it is read with strict DER, the program recomputes the imprint itself, and the certificate chain must end on a key fixed inside the program.
- The approver ids named in the record are distinct.
- For a version 2 receipt, the mandate block; and, where the decision carries one, the category fields: each closed, well formed and the same on the receipt and the decision block.
Revocation of keys and certificates is not checked beyond what the trust bundle records: the program opens no network connection, so a key or certificate revoked after the bundle was made is not known to it.
When every mandatory check has passed, that shows the record is exactly as Village Gateway signed it and that its parts agree, and nothing more. It does not show that the action was sensible or that it was carried out.
Connecting a system that carries out actions
Putting Village Gateway in the path of an action takes four steps.
- The agent describes what it wants to do, and Village Gateway answers: go ahead, wait for approval, or no.
- A cleared action receives a permit made for exactly that action.
- The system that carries out the action checks the permit with Village Gateway before it acts, and each permit works once.
- The outcome is reported back and joins the record.
A reference resource shows how a protected system redeems a Gateway permit over HTTP: an allowed request executes exactly once, an approval-gated request waits and executes once after approval, and the resource reports the outcome back to the record.
The reference program is built and tested, and it is available on request.
The post-quantum signature, and what comes next
A second, post-quantum signature (ML-DSA-65, FIPS 204) is built into several Village record kinds and turned on per account. Next, it will be added to Gateway receipts, and each receipt will be sent to more than one time-stamping authority. The post-quantum implementation is our own and has not been independently audited.