0016. On-chain protocol layer and attested post-quantum verification

Design document, published from the repository at docs/adr/0016-onchain-protocol-layer.md.

  • Status: Accepted
  • Date: 2026-11-13

Context

QuantLayer needs an on-chain layer for identities, keys, credentials, ZK proofs, nullifiers and authorization, deployed first to Arbitrum Sepolia. Earlier tasks left a minimal QuantLayerRootRegistry, an Owned single-owner pattern and a reference QuantLayerAuthorizationGate. The Gate failed closed for the post-quantum, hybrid and credential modes.

Post-quantum signatures are the hard part. The EVM has no ML-DSA or SHAKE precompile, and a measured lower bound for native ML-DSA-65 is about 22.5M gas (docs/contracts/PQC_FEASIBILITY.md).

Decision

  1. Six core contracts behind interfaces:

    • QuantLayerIdentityRegistry
    • QuantLayerKeyRegistry
    • QuantLayerCredentialRegistry
    • QuantLayerNullifierRegistry
    • QuantLayerProofVerifier (proof-system adapters)
    • QuantLayerAuthorizationManager

    QuantLayerPqcAttestationVerifier sits alongside them. They replace QuantLayerRootRegistry, Owned and QuantLayerAuthorizationGate.

  2. Roles and pausing.

    • Use OpenZeppelin 5.6.1 AccessControl with separated operational roles.
    • Use Pausable only where halting is safe: registration, updates, verification and authorization. Revocation and suspension paths are never pausable.
  3. One shared nullifier registry, consumed only by trusted CONSUMER contracts. A nullifier is spent once per scope, whichever circuit or consumer is used.

  4. Proof systems are versioned. Each circuit records its adapter, proof system id and verification-key hash, and registration checks the adapter's own claims.

  5. Post-quantum verification happens off-chain, with k-of-n EIP-712 attestations.

    • The trust model is stated in code and docs.
    • Every authorization reports its assurance: Trustless or Attested.
    • Hybrid mode always verifies its classical half on-chain.
  6. Toolchain. Foundry and OpenZeppelin are installed through the pnpm catalog (@foundry-rs/forge, @openzeppelin/contracts).

    • We don't use forge-std; the npm package of that name is not published by Foundry.
    • Tests use a minimal cheatcode interface.
    • Fixed-address test deployments run the constructor in place (Deploy.at), so production contracts carry no test-only initializers.

Consequences

  • What's easier. All five authorization modes now work on-chain, with an honest assurance level for each, instead of three of them failing closed.
  • What's harder. Attested modes depend on attestor key security and liveness. Attestor sets must be operated, rotated and monitored, and rotating the set invalidates outstanding attestations.
  • Follow-up. Evaluate Arbitrum Stylus (WASM ML-DSA via libcrux), a precompile, or a ZK proof of ML-DSA verification to make post-quantum modes trustless. The interfaces already carry algorithm and proof-system identifiers for this.
  • Production. Deployment must move admin roles to a timelocked multisig before mainnet.