README.md

---

🏗️ 4-DNA Membrane Architecture

ValiChord is built as four distinct Holochain DNAs — four separate peer-to-peer networks — ensuring absolute data sovereignty and GDPR compliance by architecture, not policy.

DNA	Purpose	Access Control
DNA 1 — Researcher Repository	Private storage of raw code, data, protocols, and snapshots. At submission, lock_researcher_result seals result metrics with a cryptographic nonce — only the hash leaves.	Private — single agent, never enters DHT
DNA 2 — Validator Workspace	Where the reproduction work happens. Private attestation sealed here during the commit phase.	Private — single agent, never enters DHT
DNA 3 — Attestation	Shared DHT for validation requests, blind commitment anchors, and public attestations. Credentialed membrane.	Credentialed — institutional membrane proof required
DNA 4 — Governance & Harmony	Public results, Harmony Records, Reproducibility Badges, and validator reputation. HTTP Gateway target.	Open read — no Holochain node required

---

🔐 Trust & Identity Model

ValiChord separates identity assurance from consensus. Sybil resistance is not achieved through staking, proof-of-work, or token economics — it is achieved through membrane proofs: every validator must present a cryptographically signed joining certificate issued by a trusted credentialing authority before their attestations are accepted by the network.

This means:

• The validator set is permissioned — open participation is deliberately excluded
• Real-world identity is bound to on-chain agent keys at the membrane boundary
• A validator cannot trivially multiply their influence by creating additional identities, as each identity requires a separate institutional credential
• All commit-reveal commitments and attestations are therefore attributable to a verified real-world entity

ValiChord does not attempt to solve Sybil resistance in an open network. It delegates identity assurance to institutional credentialing — the appropriate mechanism for high-integrity scientific and regulatory validation contexts. Trust in the issuer is externalised: it derives from institutional legitimacy (journals, funders, accrediting bodies) rather than on-chain consensus. ValiChord intentionally bridges real-world authority into the protocol rather than attempting to replace it.

Credential Issuance & Governance

The credentialing authority is set via the authorized_joining_certificate_issuer DNA property at network instantiation.

Phase 0 (current): Certificate issuance is operated by ValiChord as a single trusted authority. This is a deliberate bootstrap choice — establishing a known, accountable issuer before governance infrastructure matures — rather than an architectural limitation.

Phase 1 roadmap: Credential issuance will be extended to support multiple issuers (journals, funders, professional bodies) and governance-controlled issuer rotation, allowing institutional participants to federate trust without depending on a single point of authority.

A compromised issuer cannot retroactively alter existing attestation records on the DHT — issued certificates are agent-key-bound and non-transferable. However, issuer compromise can affect the integrity of future attestations by allowing unauthorised validators to enter the network, which is why issuer rotation and governance controls are part of the Phase 1 roadmap.

---

✅ Implementation Status

The four-DNA infrastructure is built and tested. This is not a whitepaper or a design document — it is working Rust/Holochain code with a passing integration test suite.

valichord/
├── shared_types/           — cross-DNA types (pure rlib)
├── dnas/
│   ├── attestation/        — DNA 3: shared DHT, credentialed membrane
│   ├── researcher_repository/ — DNA 1: private, single-agent
│   ├── validator_workspace/   — DNA 2: private, single-agent  
│   └── governance/         — DNA 4: public DHT, HTTP Gateway
├── sweettest_integration/  — Rust sweettest suite (native conductor) — the integration suite
├── wind-tunnel/            — Wind-Tunnel performance scenarios (throughput, DHT propagation, load)
└── happ.yaml               — all four DNA roles bundled

valichord-ui/               — Svelte 5 + TypeScript browser UI
├── src/
│   ├── App.svelte          — shell, port detection, signal handling
│   ├── lib/holochain.ts    — AppWebsocket singleton + callZome wrapper
│   ├── lib/types.ts        — TypeScript mirrors of all Rust types
│   ├── lib/store.ts        — Svelte stores
│   ├── lib/ResearcherView.svelte
│   ├── lib/ValidatorView.svelte
│   └── lib/GovernanceView.svelte
├── tests/e2e/              — Playwright suite against a real conductor (runs in CI)
└── FRONTEND.md             — UX walkthrough and setup guide

150 automated tests across three suites (114 Rust sweettest, 30 Rust unit, 6 Playwright browser e2e) — all running in CI, none skipped. The system is also integration-ready: a REST API (POST /validate, GET /result/<job_id>) connects the analysis pipeline to the live Holochain network, and a working HTTP Gateway exposes Harmony Records as publicly verifiable links. The API supports API key authentication, webhook callbacks, and a full OpenAPI 3.0 spec with Swagger UI at GET /docs. Any tool that can make an HTTP request can integrate.

ValiChord has been demonstrated running as a real multi-node network. Integration tests launch up to 7 independent Holochain conductors — each with its own agent identity, source chain, and DHT participation — executing the full blind commit-reveal protocol and producing a Harmony Record on a shared live DHT. This is not a simulation: each conductor is an independent process with separate state, communicating over a real peer-to-peer network. The constraint is infrastructure RAM, not architecture.

What the tests prove, in brief:

• The full blind commit-reveal protocol, end to end across all four DNAs — sealing, public commitment anchors, DHT-poll-driven phase transitions, symmetric dual reveal, and HarmonyRecord assembly including mixed/Divergent outcomes
• On-chain enforcement is real, not aspirational — a verdict altered between sealing and reveal is rejected with a hash mismatch (security sweettests S7/S8); all public record types are immutable, with no delete functions exposed
• The membrane works — real Ed25519 membrane-proof verification: issuer-signed proofs accepted, forged signatures rejected
• Privacy holds across agents — private attestations and locked results are unreadable by peers and never enter the DHT
• The study lifecycle survives real-world failure — claims with conflict-of-interest rejection at the integrity layer, capacity checks, dropout reclaim, reduced-quorum force-finalisation, and deliberate abstention as a first-class recorded act
• Discovery and analytics indexes resolve correctly — by discipline, institution (conflict-of-interest), badge type, difficulty, and data hash
• Adversarial inputs are guarded — duplicate commitments/attestations rejected, self-claim prevented with no dev bypass, TOCTOU-safe phase writes, deterministic link resolution
• The browser UI drives the real protocol — Playwright exercises the Svelte forms against a live conductor with no mocks, on every push, in ~2 minutes
• Performance is measured, not assumed — five Wind-Tunnel load scenarios; a live 3-conductor run measured median cross-agent DHT propagation at ≈ 185 ms

📄 Full test inventory, per-suite run commands, and CI layout → TESTING.md

---

🔐 The Blind Commit-Reveal Protocol — Fully Symmetric (March 2026)

This is the core anti-gaming guarantee that makes ValiChord different from every other reproducibility system.

For the first time, a computational reproducibility system provides cryptographic proof of four things simultaneously:

• Validators could not see each other's findings before committing their own
• Validators could not see the researcher's claimed values before forming their own verdict — only the commitment hash is visible during the commit phase, preventing anchoring or bias
• The researcher could not change their claimed results after seeing any validator's findings
• The comparison of researcher-declared values against validator-reproduced values is cryptographically genuine — not self-reported or trust-based

Neither party can move the goalposts. The envelopes are sealed before anyone opens theirs.

The protocol is implemented across all four DNAs and is fully tested:

0. Researcher seals result (at submission, months before validators begin) — lock_researcher_result in DNA 1 generates a 32-byte random nonce, computes commitment_hash = SHA-256(rmp_serde::to_vec_named(metrics) || nonce), stores the structured metrics and nonce as a private LockedResult entry that never leaves the researcher's device, and automatically publishes only the hash to DNA 3 as a ResearcherResultCommitment. Validators can verify this commitment exists before accepting a study — the researcher is bound to their result from day one. Critically, only the hash is published: validators cannot see the actual metric values until after they have committed their own verdicts, preventing anchoring bias.
1. Validators commit — each validator seals their private assessment as a ValidatorPrivateAttestation in their own DNA 2 workspace. seal_private_attestation generates a random nonce and computes commitment_hash = SHA-256(msgpack(ValidationAttestation) || nonce). The entry — including the nonce — never leaves their machine. A validator who ran tooling may also set reproduction_bundle_hash, the content_hash of their own valichord_attestation bundle; because it is part of the hashed struct it is sealed into the commitment automatically, so their verdict is bound to a specific set of per-sample outputs rather than to the bare word "Reproduced". The field is optional and None is a legitimate permanent state — an unbound verdict, not a missing one. It binds which results the validator stands behind; it does not prove the bundle came from a real run, and it does not catch a validator who genuinely computes the wrong answer.
2. Anchors published — DNA 2's post_commit automatically calls notify_commitment_sealed() in DNA 3, writing a public CommitmentAnchor to the shared DHT containing the commitment_hash. Everyone can verify the commitment happened and that it is cryptographically bound to a specific assessment — but the assessment content remains hidden.
3. Phase opens — when all expected CommitmentAnchor entries are present, DNA 3 writes a PhaseMarker(RevealOpen) to the DHT. Validators discover this by polling, not by signal — ensuring no validator is disadvantaged by network latency.
4. Dual reveal (both parties simultaneously) — the researcher calls reveal_researcher_result in DNA 3, which verifies SHA-256(rmp_serde::to_vec_named(metrics) || nonce) == result_commitment_hash on-chain and writes an immutable ResearcherReveal to the DHT. Each validator retrieves their sealed nonce from DNA 2 via get_private_attestation_for_task and calls submit_attestation in DNA 3, which verifies SHA-256(msgpack(attestation) || nonce) == CommitmentAnchor.commitment_hash on-chain. Neither party can reveal different values than they committed to, and neither could see the other's committed content before committing their own.
5. Harmony — once all attestations are present, DNA 4 assembles a HarmonyRecord on the public DHT, assesses agreement, and optionally issues a ReproducibilityBadge. The researcher's verified ResearcherReveal metrics and each validator's produced_value fields are both on the public DHT — the comparison is genuine and independently verifiable by anyone. Badge tiers (Gold ≥ 7, Silver ≥ 5, Bronze ≥ 3 validators) reflect agreement level and participant count. The record also carries validators_requested beside the participant list, so a round that closed early reads "3 of 7" rather than silently "3" — the denominator is part of the permanent record, not dropped from it. Phase 0 note: validator experience is not yet tracked in production — see the Architecture doc for the Phase 0 badge caveat.

---

⚖️ Governance Philosophy: Designing Against Domestication

Most validation systems fail not because of bad technology but because of institutional capture — funders, publishers, or powerful research groups gradually bend the rules in their favour. ValiChord's governance framework is designed from the ground up to resist this.

The core principle is structural independence: no single institution, funder, or validator cohort can control outcomes. This is achieved through:

• Blind commitment — validators cannot see each other's findings before revealing their own, preventing social conformity and last-mover advantage
• Credentialed membranes — only institutionally verified validators can participate; anonymous or self-certified participation is architecturally impossible
• Immutable public records — Harmony Records on the public DHT cannot be altered or deleted by anyone, including ValiChord's own operators
• Distributed governance — no central server, no single point of control; the network is the authority
• Transparent disagreement — where validators diverge, the disagreement is recorded in full, not averaged away

The governance framework explicitly addresses what happens when ValiChord itself comes under pressure — from funders seeking favourable results, from institutions protecting reputations, or from validators gaming the system for reputation scores. The answer in each case is the same: the architecture makes corruption structurally difficult rather than relying on policy or goodwill.

📄 Read the full Governance Framework — published as a Zenodo preprint: 10.5281/zenodo.18878108

---

🔑 Configurable Trust

ValiChord's trust model is set by the deployment, not by the protocol. The membrane proof system is a dial: operators configure the credential threshold appropriate to their context, and the protocol runs identically regardless of where that dial is set.

Some contexts demand high bars. Scientific reproducibility validation requires credentialed evaluators — you cannot allow unverified agents to attest whether a genomics workflow reproduces correctly, or whether an AI system's capability claim holds. The integrity of the record depends on the institutional standing of those who sign it.

Other contexts call for openness. Community fact-checking, citizen science, and decentralised forecasting may configure minimal credential requirements or none at all — broad participation is a feature, not a liability.

As ValiChord is adopted across domains, each deployment will calibrate this dial to its own trust requirements. The protocol — blind commit, DHT-anchored reveal, immutable Harmony Record — is the same in every case. Only the membrane configuration changes.

---

🗺️ Landscape: Where ValiChord Fits

ValiChord is not a replacement for existing reproducibility tools — it is the coordination, governance, and certification layer that those tools operate within.

Project / Tool	Focus Area	Validation Model	Incentives	Governance	Integration	Tamper-Evidence
ValiChord	Distributed validation	Multi-party, Harmony Records	✅ Yes	Transparent, anti-capture	Journals, Funders, Repos	✅ Yes
Binder	Reproducible environments	Single execution	❌ No	N/A	Repos	❌ No
Code Ocean	Executable capsules	Single execution	❌ No	Proprietary	Journals	❌ No
FLINC	Reproducibility packaging	Single execution	❌ No	N/A	Repos	❌ No
PTU	Process tracing	Single execution	❌ No	N/A	Repos	❌ No
ReproZip	Packaging and portability	Single execution	❌ No	N/A	Repos	❌ No
RenkuLab	Collaborative science	Single/multi execution	❌ No	N/A	Repos	❌ No
Sciunit	Reproducibility packaging	Single execution	❌ No	N/A	Repos	❌ No
Whole Tale	Data-driven science	Single/multi execution	❌ No	N/A	Repos	❌ No

Landscape based on benchmarking by Zenodo:15167233 (2025), which evaluated these tools against 18 real computational experiments across multiple disciplines.

Every existing tool facilitates reproducibility — making it easier to run code, package environments, or share data. None of them verify that independent validators reached the same conclusion, preserve disagreement as a first-class output, compensate validators for their work, or resist institutional pressure to soften findings. That is the gap ValiChord fills.

---

🛠️ Researcher Ecosystem: ValiChord at Home

Before submitting for formal validation, researchers use ValiChord at Home to scan their deposit privately — 100+ automated checks for documentation gaps, hardcoded paths, missing dependencies, absent data dictionaries, and more. It generates proposed corrections (drafted READMEs, pinned requirements) for researcher review.

ValiChord at Home is a standalone tool in its own repository. It does not run the commit-reveal protocol — it is a pre-flight check that helps researchers make their deposits validatable.

👉 ValiChord at Home →

---

🔬 AI Evaluation Attestation — valichord_attestation

valichord_attestation/ is a Python library for producing cryptographically verifiable attestation bundles for AI evaluation runs. The same verification logic that ValiChord applies to scientific reproducibility — commit, hash, reveal — applies to AI capability benchmarks: a published accuracy score should be traceable to a specific run and independently verifiable without access to the full log.

Two properties make a bundle verifiable:

1. Deterministic hash — bundles are encoded with RFC 8785 (JSON Canonicalization Scheme), so the same run always produces the same bytes and the same SHA-256 digest.
2. Merkle root — a SHA-256 Merkle tree over per-sample outputs lets the log holder prove any individual sample to a verifier without disclosing the full log.

from valichord_attestation import build_bundle, hash_bundle, merkle_proof, verify_faithfulness

bundle = build_bundle(
    model_id="gpt-4o-2024-08-06",
    task_id="gsm8k",
    raw_metrics=[{"key": "accuracy", "value": 0.847, "stderr": 0.025}],
    samples=[{"index": i, "output": "...", "correct": True} for i in range(1319)],
    samples_total=1319,      # assert intended run size — detects silent sample omission
    repo_commit="abc123",
    harness_version="inspect_ai/0.3.19",
)
bundle_hash = hash_bundle(bundle)   # publish alongside the report
proof = merkle_proof(samples, index=42)   # selective disclosure
ok = verify_faithfulness(bundle.outputs_merkle_root, 42, samples[42], proof)

The format is harness-agnostic. An AdapterBase class and six built-in adapters cover the major evaluation harnesses:

• InspectAILogAdapter — reads inspect_ai .eval/.json log files directly via the inspect_ai Python API (no pre-parsing step)
• InspectEvalsAdapter — reads the evaluation_report: block from eval.yaml, with optional eval_yaml_metadata= enrichment (arxiv, human baseline, floating-asset warnings, requires_internet)
• LmEvalAdapter — reads lm-evaluation-harness results_*.json (+ optional samples_*.json) — the de-facto industry standard for LLM benchmarking
• AiluminateAdapter — reads MLCommons AILuminate (modelbench) safety-benchmark reports, committing model responses and grader verdicts together
• PiSessionAdapter — reads pi coding-agent session JSONL files
• WandbRunAdapter — reads Weights & Biases run metadata and summary metrics

InspectAILogAdapter, InspectEvalsAdapter and PiSessionAdapter are exported from the package root; the rest import from their modules, e.g. from valichord_attestation.adapters.lm_eval_adapter import LmEvalAdapter.

from valichord_attestation import InspectAILogAdapter

bundle = InspectAILogAdapter().to_bundle("logs/my_eval.eval")

A probabilistic challenge-response layer (Section 6 of the spec) adds verifier-controlled randomness on top of the Merkle structure. The verifier supplies a random nonce; challenged indices are derived from HMAC-SHA256(nonce, bundle_hash) + SHA-256 counter-mode, so the holder cannot predict which samples will be inspected. The response contains only hashes and proof paths — no raw sample content. With k=60 and a 5% fabrication rate, catch probability is ~95%.

from valichord_attestation import hash_bundle, Challenge, build_response, verify_response
import os

challenge = Challenge(bundle_hash=hash_bundle(bundle), verifier_nonce=os.urandom(32), k=60)
response = build_response(challenge, samples)          # holder's side
ok = verify_response(challenge, response, bundle)      # verifier's side

Status: 487 tests, 97% line coverage, format v1.2 (dual bundle_hash/content_hash, free-form meta provenance block). Integration with ValiChord's Holochain DHT (bundles as on-chain attestations) is v2 scope — v1.x is a standalone format library.

pip install -e "valichord_attestation[dev]"
pip install "valichord_attestation[inspect-ai]"   # adds inspect_ai dependency
pytest valichord_attestation/tests/

# GSM8K demo — Mistral-7B-Instruct-v0.3 on GSM8K-100 (no GPU required)
python valichord_attestation/examples/mistral_7b_gsm8k_demo/challenge_response_demo.py

# inspect_ai demo — GPT-4o-mini on popularity task (no GPU or download required)
python valichord_attestation/examples/inspect_ai_popularity_demo/challenge_response_demo.py

📄 Format spec →  •  📦 GSM8K example →  •  📦 inspect_ai example →

---

📚 Document Library

Understanding ValiChord

Document	Description
The Basics	Non-technical introduction: what ValiChord does, how it works, and which fields it applies to
Vision & Architecture v13	What ValiChord is and why it matters
Governance Framework	How the system resists corruption
Harmony Records	What a Harmony Record is and why it matters
How a Validation Round Works	Step-by-step narrative from submission to Harmony Record
Validator Guide	What it means to be a ValiChord validator
Why Holochain?	Non-technical explanation of the architectural choice
Other Potential Use Cases	Where else the ValiChord pattern applies
ValiChord at Home	Self-service deposit quality checker — 100+ automated checks, draft generation

Architecture

Document	Description
4-DNA Architecture — Technical	Full technical architecture document for engineers
4-DNA Architecture — Plain English	Non-technical explanation of the four-membrane design
Eight-Layer Infrastructure	The full eight-layer conceptual architecture
Technical Reference v29	Full architectural narrative and engineering reference
Architecture Scaffold v13 (Rust)	Single-file representation of the four-DNA architecture

Frontend

Document	Description
Frontend UX Guide	Screen-by-screen walkthrough for researchers, validators, and governance observers; setup instructions

Integrations

Document	Description
Deployment Checklist	All DNA properties, dev/test bypass values, production requirements, and misconfiguration failure modes
Integration Guide	REST API integration guide for any tool — curl, Python, TypeScript examples, webhooks
OpenAPI 3.0 Spec	Machine-readable API spec; served live at GET /openapi.yaml
Attestation Format v1 Spec	Canonical attestation bundle format for AI evaluation runs — schema, Merkle construction, encoding rules
Nondominium Integration Vision	Design for ValiChord × Nondominium (Sensorica) open-value accounting
Nondominium Integration Status	Status and open design decisions

Funding & Research

Document	Description
Open Design Questions	Outstanding design decisions and open questions
Sponsors & Independence	Who funds ValiChord, and the six things sponsorship explicitly cannot buy

---

🔧 For Developers

The four-DNA Holochain infrastructure is built and integration-tested. The codebase is available for technical review.

Resource	Link
Codebase (Rust / Holochain)	valichord/
AI eval attestation library (Python)	valichord_attestation/
Browser UI (Svelte 5)	valichord-ui/
Frontend UX guide	valichord-ui/FRONTEND.md
Testing guide — all four layers, run commands, coverage inventory	TESTING.md
Test suite + build instructions	TESTING.md
Wind-Tunnel performance scenarios	valichord/wind-tunnel/
Architecture Scaffold v12	docs/4_ValiChord_RUST_Scaffold.rs
Technical Architecture	docs/7_ValiChord_4-DNA_architecture_technical.md
Technical Reference v29	docs/3_ValiChord_Technical_Reference.md
Deployment Checklist	docs/DEPLOYMENT_CHECKLIST.md
Engineer Handover	docs/13_Valichord_Engineer_Handover.md

Integration partners, domain validators (HPC, clinical, environmental), and frontend contributors are equally welcome — the protocol is language-agnostic and the REST API is the entry point for non-Rust contributors.

⚡ Quickstart — clone to passing tests

# 1. Prerequisites (Holochain 0.7.0 toolchain — or just run ./setup_holochain.sh)
rustup target add wasm32-unknown-unknown
cargo install holochain           --version 0.7.0 --locked
cargo install holochain_cli       --version 0.7.0 --locked   # provides the `hc` CLI
cargo install kitsune2_bootstrap_srv --version 0.5.0 --locked

# 2. Clone and build
git clone https://github.com/ValiChord/ValiChord.git
cd ValiChord/valichord
cargo build --target wasm32-unknown-unknown --release

# 3. Pack the four DNAs and bundle the hApp
hc dna pack dnas/attestation            -o workdir/attestation.dna
hc dna pack dnas/researcher_repository  -o workdir/researcher_repository.dna
hc dna pack dnas/validator_workspace    -o workdir/validator_workspace.dna
hc dna pack dnas/governance             -o workdir/governance.dna
hc app pack .                           -o workdir/valichord.happ

# 4. Run the integration tests (sweettest — in-process Rust conductors)
pkill -x holochain; pkill -x lair-keystore; sleep 2   # -x, never -f: -f matches this shell
./run-sweettest.sh attestation
./run-sweettest.sh governance
./run-sweettest.sh researcher_repository
./run-sweettest.sh validator_workspace
./run-sweettest.sh security
./run-sweettest.sh membrane_proof

For full build details, troubleshooting, and test architecture see the Developer Guide wiki.

Running the demo: See demo/DECENTRALISED_DEMO.md for full instructions.

Browser UI: A Svelte 5 + TypeScript UI (valichord-ui/) runs against a live Holochain 0.7.0 conductor, with a Playwright e2e suite (npm run test:e2e) exercising the real browser-to-conductor journey in CI. bash dev.sh starts the conductor and writes the auth token; npm run dev -- --host serves the UI. See valichord-ui/README.md for the quick start and valichord-ui/FRONTEND.md for the full UX walkthrough.

---

📊 Roadmap

Phase	Focus	Status
Phase 0	Workload Discovery: Empirical study to quantify the true cost of validation — how long it takes, what makes it difficult, what it costs.	Seeking funding / may be superseded by direct project engagement.
Phase 1	Full MVP: UI layer, researcher and validator dashboards, live network deployment.	Browser UI browser-tested on Holochain 0.7.0 (valichord-ui/). Live network deployment pending first real validation engagement.
Phase 2	Integration at scale: Always-on hosting, journal and funder API deployments, persistent AI validator nodes.	REST API open: API keys, webhooks, OpenAPI spec, Swagger UI. HTTP Gateway working. Nondominium integration in design.

Probabilistic challenge-response is shipped in valichord_attestation (format v1.2). Hardware-attested execution via TEE is the next step toward report faithfulness verifiable without log access.

---

ValiChord is built on Holochain — an end-to-end open-source agent-centric P2P application framework.

---

Author: Ceri John  •  Contact: topeuph@gmail.com

Feedback & conversations: Arthur Brock (Holochain co-founder), Paul D'Aoust (Holochain Foundation), Joel Marcey (Rust Foundation)

ValiChord's code was written with significant AI-assistant help (Anthropic Claude) under human direction and review; the protocol design, architecture, and governance framework are the author's own intellectual work.

License: ValiChord is open source under the Apache License 2.0. You are free to use, modify, and distribute this software, including in commercial products, provided you retain the copyright notice and license text.