From c3e7f5d5da4b7d54762037424bf92fbb9fcb324e Mon Sep 17 00:00:00 2001 From: mikko tarkiainen Date: Thu, 20 Aug 2026 21:28:18 +0300 Subject: [PATCH] docs(readme): add bilingual DDN discoverability --- README.fi.md | 152 +++++++++++++++++++++++++++++++++++++++++++++++++++ README.md | 140 ++++++++++++++++++++++++++++++++++++++--------- 2 files changed, 267 insertions(+), 25 deletions(-) create mode 100644 README.fi.md diff --git a/README.fi.md b/README.fi.md new file mode 100644 index 0000000..f6fc155 --- /dev/null +++ b/README.fi.md @@ -0,0 +1,152 @@ +[English](README.md) | **Suomi** + +# DDN — Deterministic Decision Network -referenssitoteutus + +Avoimen lähdekoodin referenssiarkkitehtuuri kryptografisesti todennettaville +päätöksille, jotka suorittaa deterministinen, versioitu liiketoimintasääntö. + +DDN on referenssitoteutus, ei tuotantovalidaattoriverkko, eikä osoitus siitä, +että taustalla oleva liiketoimintasääntö on oikea, reilu, lainmukainen tai +sopiva tiettyyn käyttötarkoitukseen. Se näyttää konkreettisesti, miltä +deterministinen policyn suoritus yhdistettynä kynnysarvopohjaisesti +allekirjoitettuun attestointiin ja auditoitaviin päätöskuitteihin voi +näyttää päästä päähän — policy-as-code-määrittelystä riippumattomaan +kuitin todentamiseen asti, ilman että kenenkään tarvitsee luottaa +koordinaattorin omaan väitteeseen siitä, että päätös on lopullinen. + +## Mikä DDN on + +Referenssipino käynnistää yhden Rust-validaattoribinäärin kolmena +eristettynä aliprosessina samalla hostilla. Päätös hyväksytään vain, kun +vähintään kaksi konfiguroidun kolmen jäsenen trusted validator setin +jäsentä tuottaa keskenään yhtenevän Ed25519-allekirjoitetun attestoinnin +samasta suoritustuloksesta. Kyseessä on kiinteä 2-of-3-luottamusmalli, ei +permissionless-verkko eikä riippumattomien operaattoreiden välinen +Byzantine-fault-tolerant-konsensusprotokolla. + +Hyväksytty päätös tuottaa sisältöosoitteisen `DecisionReceiptV1`-kuitin. +Kuitti sisältää kunkin hyväksyvän validaattorin Ed25519-allekirjoitetun +attestoinnin; koordinaattori ei lisää erillistä allekirjoitusta koko +kuitin ylle. Standardi verifier tarkistaa attestoinnit, kynnyksen, +request-bindingit, hashit, Merkle-todisteen ja konfiguroidun EVM-ankkurin. +Policyn semantiikan uudelleensuoritus vaatii erillisen +`replay-verify`-polun ja täsmällisen policy-paketin. + +Repositorio sisältää canonical JSON- ja crypto-toteutukset, WebAssemblyksi +käännetyn deterministisen neuvottelupolicyn, TypeScript-API:n ja SDK:t, +kuittiverifierin, Merkle-batchauksen, Solidity-ankkurisopimuksen ja +selaindemon. Blocking full-chain E2E käyttää oikeita +validaattorialiprosesseja, API:a, selainsovelluksia, paikallista +Anvil-ketjua ja sopimusta ilman mockeja. Tämä väite ei koske jokaista +yksikkötestiä. + +## Kenelle referenssi on tarkoitettu + +Referenssi on tarkoitettu insinööreille ja arkkitehdeille, jotka arvioivat +arkkitehtuurimalleja automaattisille päätöksentekojärjestelmille, jotka +tarvitsevat todennettavan jäljen — tiimeille, jotka tutkivat +deterministisen policyn suoritusta, kynnysarvopohjaisesti allekirjoitettua +attestointia tai auditoitavia päätöskuitteja suunnittelumallina, sekä +turvallisuus- tai protokolla-arvioijille, jotka haluavat konkreettisen, +ajettavan artefaktin tutkittavaksi whitepaperin sijaan. Se ei ole +suoraan käyttöönotettava tuotantopalvelu, eikä sitä tarjota sellaisena. + +## Mitä päätöskuitti todistaa + +Kolmas osapuoli, joka vastaanottaa `DecisionReceiptV1`-kuitin ja ajaa +julkaistun verifierin — luottamatta koordinaattorin "finalized"-väitteeseen +— voi itsenäisesti tarkistaa, että: + +- syöte on kanonisoitu ja sidottu täsmällisiin policy-, manifest- ja + execution-profile-hasheihin; +- vähintään kaksi kolmesta konfiguroidusta trusted-validaattorista on + itsenäisesti suorittanut saman WASM-policy-paketin ja tuottanut + keskenään yhtenevät Ed25519-allekirjoitetut attestoinnit tuloksesta; +- kuitin muoto, hashit, request-bindingit, validaattori-identiteetit ja + -allekirjoitukset sekä konfiguroitu kynnysarvo ovat kaikki voimassa; +- Merkle-todiste sitoo kuitin batch-juureen, ja juuri vastaa sitä, mitä + konfiguroitu EVM-ankkurisopimus palauttaa konfiguroidun + RPC-päätepisteen kautta — tähän mennessä osoitettu paikallisella + Anvil-ketjulla. + +## Mitä DDN ei todista + +- Että policyyn koodattu liiketoimintasääntö on oikea, reilu, lainmukainen + tai sopiva tiettyyn käyttötarkoitukseen. DDN todistaa, että policyn + suoritus tapahtui deterministisesti ja attestoitiin — ei sitä, että + itse sääntö on hyvä. +- Että tavallinen verifier tarkisti policyn semantiikan. Se ei suorita + policya; vain erillinen `replay-verify`-polku, täsmällisellä + policy-paketilla, tekee sen. +- Että kolme validaattoria ovat riippumatonta infrastruktuuria. + Referenssideploymentissa ne ovat yhden binäärin aliprosesseja samalla + hostilla saman operaattorin alla, eivät riippumattomien operaattoreiden + verkko. +- Että ankkuri on julkisesti havaittavissa. Tässä osoitettu EVM-ankkurointi + ajetaan paikallisella Anvil-ketjulla, ei julkisessa testiverkossa tai + mainnetissa. +- Että päätöstila säilyy. Koordinaattorin ja ankkurin repositoriot ovat + muistissa eivätkä säily uudelleenkäynnistyksen yli. +- Että DDN tarjoaa KMS/HSM-pohjaisen avainten säilytyksen, rotaation tai + peruutuksen. Allekirjoitusavaimet ovat tässä referenssissä + paikallisia tiedostoja. +- Että DDN arvioi tai varmentaa tekoälymallin vapaamuotoista päättelyä. + Järjestelmässä, joka hyödyntää myös LLM:ää tai muuta tekoälymallia, + DDN:n deterministinen policykerros voi toimia auditointirajana niille + päätöksen osille, jotka on koodattu policy-as-codena — mutta se ei + varmenna, rajoita eikä auditoi itse mallin päättelyä. +- Että DDN käsittelee maksuja. Ei käsittele. + +## Referenssiarkkitehtuuri + +- `apps/` — TypeScript-palvelut (`api`, `coordinator`, `anchor-service`, + `explorer`, `demo-reference`) sekä Rust-validaattoripalvelu + (`apps/validator`). +- `packages/` — jaetut kirjastot. `canonical-json` ja `crypto` sisältävät + sekä TypeScript- että Rust-toteutuksen, jotka on ristiinvarmennettu + toisiaan vasten jaettujen testivektoreiden avulla. +- `policies/` — versioidut päätöspolicyt, kirjoitettu Rustilla, käännetty + WebAssemblyksi. +- `contracts/` — Foundry (Solidity) -projekti, joka sisältää + decision-anchor-sopimuksen. +- `infra/` — Dockerfilet toistettaville ja eristetyille + build-profiileille. + +Katso [CONTRIBUTING.md](./CONTRIBUTING.md) täydellinen repositorion +rakenne ja arkkitehtuuripäätökset (ADR:t) hakemistosta `docs/decisions/`. + +## Nykyinen näyttö ja rajoitukset + +Nykyinen näyttö on tarkoituksella suppea: + +- kolme validaattoria ajetaan yhdellä hostilla samalla binäärillä; +- EVM-ankkurointi on osoitettu vain paikallisella Anvil-ketjulla; +- verifier luottaa konfiguroituun RPC-päätepisteeseen eikä ole light + client; +- repositorio- ja idempotenssitila ovat muistissa eivätkä säily + uudelleenkäynnistyksen yli; +- KMS/HSM:ää, avainrotaatiota tai riippumattomia validaattorioperaattoreita + ei ole toteutettu; +- policyn toistettavuus on osoitettu pinnatulle Linux/arm64-profiilille; + Linux/amd64 on edelleen kokeellinen eikä julkaisuväite; +- DDN ei käsittele maksuja eikä korvaa liiketoimintasääntöä, jota se + varmentaa; +- tämä referenssitoteutus ei ole aktiivinen tuotantointegraatio. + +Lue [luottamusmalli](./docs/trust-model.md), +[tunnetut rajoitukset](./docs/limitations.md) ja +[uhkamalli](./docs/threat-model.md) ennen koodin arviointia tai ajamista. +Vahvistettu julkisen projektin kuvaus löytyy +[englanniksi ja suomeksi](./docs/public-project-description.md). + +## Aloittaminen + +Katso [CONTRIBUTING.md](./CONTRIBUTING.md) esivaatimukset, koko +repositorion rakenne ja yleiset komennot (`pnpm install`, build/lint/test, +policyn build ja verifiointi sekä oikea end-to-end-testisarja). + +## Tietoturva + +Katso [SECURITY.md](./SECURITY.md). Älä avaa julkista issueta epäillystä +haavoittuvuudesta — käytä sen sijaan tämän repositorion GitHub Private +Vulnerability Reportingia. diff --git a/README.md b/README.md index 2ee0cbd..f17e7cf 100644 --- a/README.md +++ b/README.md @@ -1,53 +1,143 @@ +**English** | [Suomi](README.fi.md) + # DDN — Deterministic Decision Network reference implementation -DDN is a reference implementation for checking significant decisions made -by deterministic, versioned business rules. It is not a production validator -network and it is not evidence that the underlying business rule is correct, -fair, lawful, or suitable for a particular use. +Open-source reference architecture for cryptographically verifiable decisions +executed by deterministic, versioned business rules. + +DDN is a reference implementation, not a production validator network, and +not evidence that the underlying business rule is correct, fair, lawful, or +suitable for a particular use. It shows, concretely, what deterministic +policy execution combined with threshold-signed attestation and auditable +decision receipts can look like end to end — from a policy-as-code +definition through independent receipt verification, without asking anyone +to trust the coordinator's own claim that a decision was finalized. + +## What DDN is The reference stack starts one Rust validator binary as three isolated child processes on the same host. A decision is accepted only when at least two -members of the configured three-member trusted validator set attest to the -same execution result. This is a fixed 2-of-3 trust model, not a permissionless -network or a Byzantine-fault-tolerant consensus protocol between independent -operators. +members of the configured three-member trusted validator set produce +matching Ed25519-signed attestations over the same execution result. This is +a fixed 2-of-3 trust model, not a permissionless network or a +Byzantine-fault-tolerant consensus protocol between independent operators. An accepted decision produces a content-addressed `DecisionReceiptV1`. The receipt contains each agreeing validator's Ed25519-signed attestation; the coordinator does not add a separate signature over the receipt as a whole. The standard verifier checks the attestations, threshold, request bindings, -hashes, Merkle proof and configured EVM anchor. Re-executing policy semantics -requires the separate `replay-verify` path and the exact policy package. +hashes, Merkle proof and configured EVM anchor. Re-executing policy +semantics requires the separate `replay-verify` path and the exact policy +package. The repository includes canonical JSON and crypto implementations, a -deterministic negotiation policy compiled to WebAssembly, a TypeScript API and -SDKs, a receipt verifier, Merkle batching, a Solidity anchor contract and a -browser demo. The blocking full-chain E2E uses real validator subprocesses, -API, browser applications, local Anvil chain and contract without mocks. That -statement does not apply to every unit test. +deterministic negotiation policy compiled to WebAssembly, a TypeScript API +and SDKs, a receipt verifier, Merkle batching, a Solidity anchor contract +and a browser demo. The blocking full-chain E2E uses real validator +subprocesses, API, browser applications, local Anvil chain and contract +without mocks. That statement does not apply to every unit test. + +## Who it is for + +This reference is for engineers and architects evaluating architectural +patterns for automated decision systems that need a verifiable trail — +teams researching deterministic policy execution, threshold-signed +attestation, or auditable decision receipts as a design pattern, and +security or protocol reviewers who want a concrete, runnable artifact to +study rather than a whitepaper. It is not a drop-in production service and +is not offered as one. + +## What a decision receipt proves + +A third party who receives a `DecisionReceiptV1` and runs the published +verifier — without trusting the coordinator's "finalized" claim — can +independently check that: + +- the input was canonicalized and bound to specific policy, manifest and + execution-profile hashes; +- at least two of the three configured trusted validators independently + executed the same WASM policy package and produced matching + Ed25519-signed attestations over the result; +- the receipt's shape, hashes, request bindings, validator identities and + signatures, and the configured quorum threshold are all valid; +- a Merkle proof ties the receipt into a batch root, and that root matches + what the configured EVM anchor contract returns via the configured RPC + endpoint — demonstrated so far on a local Anvil chain. + +## What DDN does not prove + +- That the business rule encoded in the policy is correct, fair, lawful or + suitable for a given use. DDN verifies that policy execution happened + deterministically and was attested to — not that the policy itself is a + good rule. +- That the ordinary verifier checked policy semantics. It does not execute + the policy; only the separate `replay-verify` path, given the exact + policy package, does that. +- That the three validators are independent infrastructure. In the + reference deployment they are child processes of one binary on one host + under one operator, not a network of independent operators. +- That the anchor is publicly observable. The EVM anchoring shown here runs + on a local Anvil chain, not a public testnet or mainnet. +- That decision state persists. The coordinator and anchor repositories are + in memory and do not survive a restart. +- That DDN provides KMS/HSM-backed key custody, rotation or revocation. + Signing keys are local files in this reference. +- That DDN evaluates or verifies an AI model's free-form reasoning. In a + system that also relies on an LLM or other AI model, DDN's deterministic + policy layer can act as an audit boundary for the parts of a decision + that are encoded as policy-as-code — but it does not verify, constrain or + audit the model's own reasoning. +- That DDN processes payments. It does not. + +## Reference architecture + +- `apps/` — TypeScript services (`api`, `coordinator`, `anchor-service`, + `explorer`, `demo-reference`) and the Rust validator service + (`apps/validator`). +- `packages/` — shared libraries. `canonical-json` and `crypto` ship both a + TypeScript and a Rust implementation, cross-verified against each other + via shared test vectors. +- `policies/` — versioned decision policies, written in Rust, compiled to + WebAssembly. +- `contracts/` — a Foundry (Solidity) project with the decision-anchor + contract. +- `infra/` — Dockerfiles for reproducible and isolated build profiles. + +See [CONTRIBUTING.md](./CONTRIBUTING.md) for the full repository layout and +the architectural decision records under `docs/decisions/`. + +## Current evidence and limitations Current evidence is intentionally narrow: - the three validators run on one host and use the same binary; - EVM anchoring has been exercised on a local Anvil chain only; -- the verifier trusts its configured RPC endpoint and is not a light client; -- repository and idempotency state are in memory and do not survive restart; -- no KMS/HSM, key rotation or independent validator operators are included; -- policy reproducibility is established for the pinned Linux/arm64 profile; - Linux/amd64 remains experimental and is not a release claim; -- DDN neither processes payments nor replaces the business rule it verifies; +- the verifier trusts its configured RPC endpoint and is not a light + client; +- repository and idempotency state are in memory and do not survive + restart; +- no KMS/HSM, key rotation or independent validator operators are + included; +- policy reproducibility is established for the pinned Linux/arm64 + profile; Linux/amd64 remains experimental and is not a release claim; +- DDN neither processes payments nor replaces the business rule it + verifies; - this reference implementation is not an active production integration. Read [the trust model](./docs/trust-model.md), [known limitations](./docs/limitations.md), and -[threat model](./docs/threat-model.md) before evaluating or running the code. -The verified public-project wording is available in +[threat model](./docs/threat-model.md) before evaluating or running the +code. The verified public-project wording is available in [English and Finnish](./docs/public-project-description.md). ## Getting started -See [CONTRIBUTING.md](./CONTRIBUTING.md) for setup and common commands. +See [CONTRIBUTING.md](./CONTRIBUTING.md) for prerequisites, the full +repository layout, and common commands (`pnpm install`, build/lint/test, +policy build and verification, and the real end-to-end suite). ## Security -See [SECURITY.md](./SECURITY.md). +See [SECURITY.md](./SECURITY.md). Do not open a public issue for a +suspected vulnerability — use GitHub Private Vulnerability Reporting on +this repository instead.