# Amnaya Ethereum provenance framework v0.1 An executable reference for transparency, accountability and provenance across Amnaya projects. Draft operating model, not an adopted policy or audited production system. No public-chain deployment has been made. Local tests use disposable in-memory accounts with no real assets. ## Business architecture Participant → evidence capture → private encrypted evidence store → independent review → Ethereum commitment and lifecycle events → independently readable verification view. Each project has an opaque project ID, a named legal entity and accountable lead, a signed governance charter, record schema, territorial/sector applicability register, reviewer appointments, retention schedule, dispute process and operating budget. Generate identifiers randomly; do not hash predictable names, patient numbers or farmer identities into public identifiers. Ethereum provides signature-authenticated transactions, ordered events and shared verification. Solidity implements the registry; OpenZeppelin provides tested administrative access-control building blocks. These do not establish the accuracy of physical-world evidence. AI never establishes truth or unilaterally approves records. ## Network strategy 1. Begin with local EVM tests; this kit implements that stage. 2. Use an Ethereum-compatible test network only after network/addresses are configured and approved. There is no automatic deploy script or funded wallet in this kit. 3. For production evaluate Ethereum mainnet against an Ethereum-settled L2: transaction cost, settlement/finality, sequencer outages, data availability, admin/upgrade risk and recovery. No L2 has been selected. An Ethereum-compatible private chain does not inherit mainnet settlement/security merely by using the EVM. 4. Choose one chain per initial pilot; avoid bridges and financial settlement complexity. No token, NFT, cryptocurrency sale or escrow is necessary for this provenance model. Gas still requires a separately approved operational arrangement. ## What executes in the reference contract - Project creation with an immutable policy commitment and quorum of 2–8 independent reviewer addresses. Material charter/quorum/owner changes require a new project version; preserve old IDs and map migration offchain. - Per-project operator/reviewer/resolver membership; roles cannot cross project boundaries. - Unique evidence records: opaque subject ID, salted evidence commitment, predecessor and approval deadline (up to 30 days). - Submitter cannot review their own record. Reviewers cannot vote twice. Revoked reviewers no longer count toward pending quorum. Revocation does not retroactively erase completed approval history. - Finalization requires live quorum, an unexpired proposal and the current predecessor. This prevents two competing corrections becoming current. Original commitments remain available. - Dispute and resolution with nonzero reason commitments; resolver cannot be the submitter or an earlier reviewer of that record. Revoked/disputed current records block custody handover. Any authorized project participant may challenge; external complaints must enter through a named human intake, with timeliness tracked. - Initial recorded custodian is the submitter of the first approved record; this is a workflow designation, not proof of legal title or physical possession. Set onboarding procedures accordingly. - Two-sided custody handover, accepted only by the designated active recipient with unchanged approved evidence, active sender and unexpired deadline (up to 7 days). Rejected/expired/stale requests must be cancelled and reproposed. Cancellation remains possible during pause. - Emergency project pause. Evidence remains readable. Administrators retain material governance power; this is disclosed, not a trustless system. Contract: `contracts/AmnayaEvidenceRegistry.sol`. SDK commitment helper: `evidence.mjs`. ## Evidence format and verification Use a versioned JSON envelope with schema version, random record/subject ID, project ID, event type, observed time, units, evidence-file SHA-256 digests, source/device identity reference, predecessor, reviewer findings and policy version. Full participant identity, evidence files, contracts, location and commercial/personal information stay offchain. A block time is an anchoring time, not proof of when an observation occurred. `canonical()` sorts object keys, preserves array order, uses JSON number/string encodings, and rejects unsupported/nonfinite values. This is this kit's versioned encoding, not a claim of RFC 8785 compliance. Cross-language integrations must match fixtures. SHA-256 hashes the canonical JSON; file hashes must already be in that envelope. `commit()` ABI-encodes a domain separator, chain ID, registry address, opaque project/subject IDs, document digest and private random 32-byte salt, then applies Ethereum keccak256. Store the salt privately with the document; retain recoverable encrypted backups. Do not publish a raw low-entropy hash and call it anonymous. Verification: retrieve the authorized envelope/salt, recompute using exact chain/address/domain, compare to the onchain commitment, check role/lifecycle events, predecessor/latest pointer, dispute/revocation status and network finality. A matching hash establishes consistency with the anchored bytes, not truth, regulatory approval or authenticity of the physical item. Public page file hashing is a local SHA-256 integrity demonstration only, not the Ethereum commitment helper. No file is uploaded. Never represent a browser simulation as an anchored record. ## Roles and governance Appoint actual people and organizations under written terms; distinct wallets alone do not establish independence. Maintain an identity/conflict-of-interest register offchain. Recommended minimum: one project lead, one evidence operator, two independent reviewers, one independent dispute resolver and named security/data stewards. Small teams may share duties only where required separation is preserved. Governance administrator: production multisig with documented member replacement, quorum, secure signing devices, transaction review and delayed default-admin transfer. OpenZeppelin default-admin transfer has a two-day delay in this contract. Governor and project-owner operational permissions do NOT all have a timelock. The project owner can change membership; administrator compromise or collusion can defeat governance. The reference project owner cannot be rotated in place; recovery needs reviewed migration to a new project/registry. Do not deploy without a rehearsed recovery plan. Before granting a role, verify legal identity, delegation, competence and conflicts. Remove access at offboarding; review outstanding proposals. Maintain offchain governance change evidence. A malicious owner could register multiple controlled addresses: contractual oversight, independent auditors and monitoring remain necessary. ## AI and oracle boundaries Proposed assistants: source extraction, schema completeness, anomaly screening, policy applicability retrieval and report drafting. They may read only approved project data and prepare suggestions; record model/version, inputs/source references, output, uncertainty and human action. No signer secrets, role grants, final approval, dispute resolution, payment or unrestricted cross-project data access. AI is not integrated or deployed by this kit. Sensors/oracles require device enrollment, signed observations, calibration, clock checks, duplicate/replay detection, missing-data handling, independent sampling and a named source owner. The contract does not implement an IoT oracle, cryptographic device attestation or data-quality engine. Those are adapter work packages, not delivered capabilities. ## Project adaptation `project-presets.json` contains eight illustrative profiles. All evidence, checkpoints and targets are planning examples, not claims of current operations or accomplishments. Map each schema to actual workflows, project legal entity, participant agreements and regulatory advice. Healthcare: procurement/equipment provenance only; no patient identity/clinical data onchain. Food: batch IDs, supplier/lab/cold-chain evidence; legal food-safety checks remain independent. Energy: equipment, inspection and milestone evidence; no assertion of certified carbon/renewable credits. ## 100-day execution model Days 1–7: appoint owner and select one traceability decision; document why a database alone is insufficient. Gate: approved mandate. Days 8–21: map participants/custody, schema, baseline, rights and threat model. Gate: signed participant/data charter and testable target. Days 22–42: implement private-store adapter, EVM registry, roles and verification service; test unauthorized paths. Gate: independent architecture/security review. Days 43–56: run synthetic end-to-end records, backup/key recovery, dispute drills and cost measurements. Gate: permission to pilot with approved data and spend cap. Days 57–70: limited real pilot (suggested 20 authorized subjects, not a promise), daily reconciliation and sampled physical checks. Gate: findings review. Days 71–84: correct anomalies, evaluate access/independence, test participant exit and outages. Gate: resilience review. Days 85–100: compare measured results with baseline, document cost/benefit and incidents; independent review and owner decision: proceed, revise, hold or stop. No automatic mainnet launch. Planning targets: 100% required evidence fields and authorized lifecycle actions; zero self-approvals; >=95% pilot subjects with complete required chain of custody; 100% discovered invalid records flagged; dispute acknowledgment within one business day; resolution target within five business days subject to escalation; >=95% retrieval/verification success in an authorized audit sample. Assign denominators, owners, sample size and exception definitions before adoption. Contract does not enforce these service targets. ## Controls, costs and limitations Monitor unresolved disputes, missing evidence, duplicate submissions, unauthorized attempts, late approvals, anchoring delay, verification failures and custody gaps. Chart rates with actual denominators; control limits need a sufficiently stable baseline and must not be confused with business targets. Collect raw observations; no synthetic charts presented as accomplishments. Costs = deployment + gas per lifecycle transaction + RPC/indexing + private storage/backup + integration + independent audit + reviewer labor + support. One basic record with quorum 2 uses propose + two reviews + finalize = four transactions, before custody or disputes. Browser estimator is manually parameterized, excludes deployment and non-gas costs, and is not a quote. Never infer live gas/ETH prices from its illustrative defaults. Private-store adapters must implement per-project authorization, encrypted storage, malware scanning, signed short-lived downloads, retention/deletion and audit export. Do not assume the existing website vault has these project-level controls: it currently has team-level access. No automatic onchain writer, indexer, finality tracker, wallet login, key manager, public verifier API or evidence-vault integration has been deployed. These are required next steps before production use. A production indexer must be idempotent on chain ID/contract/transaction hash/log index, handle reorgs and distinguish submitted, included, confirmed and finalized. Public display must redact source data while honestly showing disputed/revoked/outdated status. RPC outage must queue records privately, not falsely label them anchored. No public gateway URL or unrestricted IPFS document publishing for confidential evidence. Contract has not undergone independent audit, fuzzing, formal verification or production deployment. Tests verify selected lifecycle invariants, not complete security. Ganache is a local test tool and can use its JavaScript transport fallback on Node 24; do not use its accounts or provider in production. ## Developer runbook Install Node 24+ and pnpm. From this directory: `pnpm install --frozen-lockfile --ignore-scripts`, `pnpm test`, `pnpm compile`. Dependencies pinned in package.json and pnpm-lock.yaml. Test chain 31337 is in memory, has no external RPC and is discarded after testing. Compiled ABI/bytecode in artifacts can be used by an approved testnet integration, after independent review. No private keys or funded network access required for tests. Do not add live credentials to source or a public website download. ## Primary references - Ethereum smart contracts: https://ethereum.org/developers/docs/smart-contracts/ - Oracles and external-data boundary: https://ethereum.org/developers/docs/oracles/ - Ethereum scaling: https://ethereum.org/developers/docs/scaling/ - OpenZeppelin access control: https://docs.openzeppelin.com/contracts/5.x/access-control - OpenZeppelin contracts source/version: https://github.com/OpenZeppelin/openzeppelin-contracts/tree/v5.6.1 No named technology provider, research institution or consortium is represented as an Amnaya collaborator by this framework. Operational policies remain subject to actual adoption and territorial/sector review. ## Pay-and-use commercial model Pay-and-Use-Guidelines.md and pay-use-clauses.json provide 18 proposed clauses and practices. The website worksheet exports draft order assumptions only. No tariff, billing engine, payment, subscription, acceptance or smart-contract fee collection is implemented. Project-level rates, payer/provider identities, cap, taxes, credits, service levels, liability and territorial terms require actual approval. Distinguish internal cost allocation from a contract between separate legal entities.