immutrace-contracts

On-chain layer of the IMMUTRACE immutable-traceability protocol, plus an EVM checkpoint registry for the DAIMON Layer 1 chain. Built with Foundry and OpenZeppelin 5, deployed on Polygon Amoy.

IMMUTRACE's Python backend collects traceability events, batches them, and computes a Merkle root per batch. That root is anchored on-chain by AnchorRegistry: from that moment anyone can prove that a specific event belongs to an anchored batch — with a standard Merkle inclusion proof — without trusting the backend, which can no longer rewrite history. Anchoring is role-gated and optionally strengthened by an EIP-712 counter-signature from an independent attestor (two-party control).

DaimonCheckpoint provides dual anchoring for DAIMON, a from-scratch Python L1: DAIMON attestors co-sign periodic checkpoints (height, block hash, state hash) and any relayer records them in an immutable, light-client-style EVM registry with an M-of-N quorum. The registry is deliberately not upgradeable and has no admin — for a checkpoint registry, immutability is the feature.

Architecture

flowchart LR
    subgraph IMMUTRACE
        E[Traceability events] --> B[Python backend]
        B -->|Merkle root per batch| AR
    end

    subgraph DAIMON["DAIMON L1 (Python)"]
        BL[Blocks] --> AT[Attestors]
        AT -->|EIP-712 checkpoint signatures, M-of-N| DC
    end

    subgraph Polygon["Polygon (Amoy)"]
        AR[AnchorRegistry\nUUPS proxy]
        DC[DaimonCheckpoint\nimmutable]
    end

    V[Verifier] -->|Merkle inclusion proof| AR
    V -->|checkpoint lookup| DC

Loading

Contracts

Contract	Pattern	Purpose
AnchorRegistry	UUPS upgradeable, AccessControl, Pausable, EIP-712	Write-once anchoring of IMMUTRACE batch Merkle roots; on-chain inclusion verification
DaimonCheckpoint	Immutable, no admin	M-of-N attested, hash-linked DAIMON checkpoint chain

Build and test

Requires Foundry.

git clone --recurse-submodules https://github.com/stoneproof-tech/immutrace-contracts
cd immutrace-contracts
forge build
forge test                    # 70 tests: unit, fuzz, invariant, upgrade
forge coverage --no-match-coverage "(test|script)"   # 100% on src/
forge snapshot                # gas benchmarks

Coverage and gas details: docs/COVERAGE.md, docs/GAS_REPORT.md.

Deploy

cp .env.example .env          # fill in PRIVATE_KEY, AMOY_RPC_URL, ETHERSCAN_API_KEY
source .env
forge script script/Deploy.s.sol --rpc-url "$AMOY_RPC_URL" --broadcast

Deployed contracts (Polygon Amoy, chainId 80002)

Contract	Address	Explorer
AnchorRegistry (proxy)	pending deployment	—
AnchorRegistry (implementation)	pending deployment	—
DaimonCheckpoint	pending deployment	—

Full deployment details (tx hashes, init parameters, end-to-end anchoring demo): docs/DEPLOYMENTS.md.

Security

Threat model, static-analysis triage (Slither/Aderyn) and residual trust assumptions are documented in docs/SECURITY_REVIEW.md. Key design points:

• anchors and checkpoints are write-once; no role can rewrite history;
• attested anchoring needs two parties (ANCHOR_ROLE sender + ATTESTOR_ROLE EIP-712 signature with per-attestor nonce and deadline);
• UUPS upgrades are gated by a dedicated UPGRADER_ROLE, which in production belongs behind a multisig and timelock;
• DaimonCheckpoint has no owner and no upgrade path by design.

These contracts have not been externally audited.

License

MIT