QuantLayer on-chain protocol layer

Design document, published from the repository at docs/contracts/ONCHAIN_PROTOCOL.md.

Solidity 0.8.28, Foundry 1.7.1 and OpenZeppelin Contracts 5.6.1 (both pinned in the pnpm catalog). Source: contracts/src. Target network: Arbitrum Sepolia (chain id 421614).

1. Contracts

ContractRolePausable
QuantLayerIdentityRegistryDID hash → controller, status (Active / Suspended / Deactivated), document hash, versionRegistration and updates. Suspend and deactivate are never paused.
QuantLayerKeyRegistryVersioned keys per (DID, key id): algorithm, purposes, expiry, public-key hash, EVM signerAdd and rotate. Revoke is never paused.
QuantLayerCredentialRegistryIssuers, allowed credential types, Merkle roots (with grace period and immediate revocation), credential statusIssuer registration. Root publication, revocation and status changes are never paused.
QuantLayerNullifierRegistryProtocol-wide spent set: (scope, nullifier) pairs and single-use contexts/noncesNo: there is nothing to halt, and the registry only ever adds entries.
QuantLayerProofVerifierZK proof verification with full binding, through versioned proof-system adaptersVerification.
UltraHonkVerifierAdapterWraps one generated Barretenberg verifier as proof system 1, with its verification-key hash—
QuantLayerPqcAttestationVerifierk-of-n EIP-712 attestations of off-chain post-quantum / credential verification— (no state changes)
QuantLayerAuthorizationManagerQuantLayer authorization requests under versioned policies, for every modeNew authorizations.

All contracts are written against interfaces in contracts/src/interfaces. Consumers depend on IQuantLayerAuthorizationManager, IQuantLayerProofVerifier and so on, never on implementations.

                         ┌──────────────────────────┐
  dApp ─────────────────▶│ QuantLayerAuthorizationManager │──────────────┐
                         └──┬──────┬──────┬──────┬──┘              │
            isActive        │      │      │      │ checkAttestation│
   ┌────────────────────────┘      │      │      └───────────────┐ │
   ▼              isUsable / key   ▼      │ verifyProof          ▼ ▼
 QuantLayerIdentityRegistry ◀── QuantLayerKeyRegistry │          QuantLayerPqcAttestationVerifier
                                          ▼
   QuantLayerCredentialRegistry ◀──isValidRoot── QuantLayerProofVerifier ──▶ UltraHonkVerifierAdapter ×6
          ▲ credentialStatus                      │                    └─▶ <Circuit>HonkVerifier
          └───────── manager                      ▼
                                       QuantLayerNullifierRegistry ◀── manager (nonces)

2. Access control and role separation

OpenZeppelin AccessControl is used throughout. Roles are keccak256("quantlayer.role.<name>"), defined in src/common/QuantLayerRoles.sol.

RoleHeld onCan
DEFAULT_ADMIN_ROLEevery contractgrant and revoke roles. In production this belongs to a timelocked multisig.
REGISTRARidentitiesregister identities
GUARDIANidentities, keyssuspend, reinstate and deactivate identities, and revoke keys (compromise response)
ALGORITHM_ADMINkeysenable or disable algorithms and set key lengths (crypto agility)
ISSUER_ADMINcredentialsregister and deactivate issuers, and allow credential types
issuer authoritycredentials (per issuer)publish and revoke roots, and set credential status
CIRCUIT_ADMINproof verifierconfigure proof systems and circuits, and set maxProofAge
CONSUMERnullifiersspend nullifiers and consume contexts. Granted only to the proof verifier and the manager.
POLICY_ADMINmanagerpublish, retire and version policies
ATTESTOR_ADMINattestation verifierreplace the attestor set and threshold
PAUSERevery pausable contractpause and unpause

Identity controllers act on their own identity without any role:

  • update the document (with an optimistic version check);
  • transfer control in two steps (proposeController, then acceptController);
  • add, rotate and revoke keys;
  • deactivate the identity.

3. Replay protection, expiry and domain separation

ThreatDefence
Same authorization twiceEach (subject, nonce) is consumed once in QuantLayerNullifierRegistry, across every mode. nonceKey also binds the chain and the manager address.
Same ZK proof twiceEach proof context is consumed once (contextKey(context)).
Same holder claims twice with fresh proofsThe nullifier is spent once per scope. Scope = (chain, verifier, app, action), shared across circuits and consumers.
Signature or proof replayed on another chain or deploymentEIP-712 domain {name, version, chainId, verifyingContract} for requests and attestations. The ZK context binds chain id, verifier, consumer (msg.sender), app, circuit and nonce.
Request for another app or actionThe policy binds keccak256(appDomain) and keccak256(action), and optionally a required calling contract (consumer).
Stale or long-lived requestsexpiresAt > now, issuedAt ≤ now + clockSkew and expiresAt − issuedAt ≤ maxLifetime.
Stale proofsnow − provenAt ≤ maxProofAge, and the root must be current or within its grace period.
Stale attestationsverifiedAt ≤ now < expiresAt, validity at most 1 hour, and the attestor set version must be current.
Front-running a signed request (submitting it first to burn its nonce)Set policy.consumer to the integrating contract. It is then the only accepted caller. With consumer = 0, a third party can submit a user's signed request first: nothing the user didn't sign is authorized, but the dApp's own call then fails (griefing).
Malleable signaturesOpenZeppelin ECDSA rejects high-s and invalid v. Attestor signers must be strictly ascending, so duplicates are rejected.

All writes that spend a nonce, context or nullifier happen after every check, in the same transaction. A rejected attempt consumes nothing.

4. Algorithms, versions and revocation

  • Algorithm identifiers (uint16; QuantLayerAlgorithms.sol, mirrored by ONCHAIN_ALGORITHM_IDS in @quantlayer-protocol/authorization):

    FamilyIdentifiers
    Ed255190x0001
    ES256K0x0002
    ES256K-EIP7120x0003 (the key is a 20-byte EVM address)
    ML-DSA-44 / 65 / 870x11 / 0x12 / 0x13
    SLH-DSA-SHA2-128s / 128f / 256s0x21 / 0x22 / 0x23
    ML-KEM-512 / 768 / 10240x31 / 0x32 / 0x33

    Public-key lengths are enforced exactly. KEM keys may only carry the key-agreement purpose, and signature keys never can.

  • Key versions. Rotation retires version n and activates n+1, and may change the algorithm (classical → ML-DSA migration). Invariant tests check:

    • at most one active version per key id, and it is always the latest;
    • revocation is terminal.
  • Proof-system versioning. setProofSystem(id, name, enabled). Each circuit is registered with (adapter, proofSystem, verificationKeyHash), and registration checks that the adapter reports the same proof system and key hash. Disabling a proof system (for example, a prover bug in one Barretenberg version) disables every circuit that uses it.

  • Policy versions. A policy accepts request versions in [minVersion, maxVersion]. Raising minVersion retires older requests.

  • Revocation, from fastest to slowest:

    • key revocation and identity suspension (guardian, never paused);
    • root revocation (immediate, no grace) and issuer deactivation;
    • credential status Revoked (terminal);
    • root supersession (old roots stay valid only for rootGracePeriod);
    • attestor-set rotation (invalidates every outstanding attestation).

5. Post-quantum verification: attested, not trustless

Native ML-DSA verification costs at least 22.5M gas, measured in PQC_FEASIBILITY.md. The protocol therefore does not verify post-quantum signatures on-chain. Instead:

  1. An attestor runs QuantLayer's engine (@quantlayer-protocol/authorization with QuantLayer Quantum / libcrux) on the request and its evidence.
  2. The attestor builds an attestation only for an allow decision, using attestPostQuantumAuthorization. The attestation names:
    • the request digest;
    • the subject DID hash;
    • the key id hash and version;
    • the algorithm;
    • keccak256(publicKey);
    • keccak256(signature);
    • a validity window of at most 1 hour;
    • the attestor-set version.
  3. The attestor signs the EIP-712 PqcAttestation. Its domain is "QuantLayer PQC Attestation", version 1, chain id, and the verifier address. The digest is pqcAttestationDigest, and a test checks it equals the contract's.
  4. On-chain, QuantLayerAuthorizationManager:
    • checks that the key is usable in QuantLayerKeyRegistry;
    • checks that the attestation matches exactly that registered key (algorithm and public-key hash) and this request digest;
    • requires a quorum of current attestors.

Trust model. Accepting Attested evidence means trusting that at least threshold registered attestors verified honestly and that their secp256k1 keys are uncompromised. The attestation layer itself is not post-quantum secure. Every result reports its assurance in the Authorized event:

ModeEvidenceAssurance
1 classicalEIP-712 ECDSA by the registered ES256K-EIP712 keyTrustless
2 post-quantumML-DSA / SLH-DSA, attestedAttested
3 hybridECDSA half verified on-chain and PQ half attestedAttested (the PQ guarantee rests on attestors; the attestors alone can't authorize)
4 credentialStatus checked on-chain (issuer active, credential Active, type), presentation attestedAttested
5 ZK eligibilityUltraHonk proof verified on-chain, bound to the request digestTrustless

Further rules:

  • With three or more attestors, the threshold must be at least 2.
  • With no attestor set, the post-quantum, hybrid and credential modes fail closed.
  • In ZK mode, the subject DID is not authenticated by the proof. The proof is anonymous: the subject must be an active identity, but it is not bound to the prover.
  • The policy decides what a ZK statement must say. The prover chooses public inputs such as threshold and credentialType, so the policy pins them (credentialTypeIndex / credentialType, thresholdIndex / minThreshold).

6. Events

Events are indexed for off-chain indexers and relying parties.

ContractEvent
ManagerAuthorized(digest, policyKey, subjectHash, mode, assurance, nullifier)
Proof verifierProofVerified(circuitId, consumer, appId, context, nullifier). Relying parties confirm it from their own node with confirmOnChainVerification.
Nullifier registryNullifierSpent and ContextConsumed
ConfigurationPolicyConfigured, ProofSystemConfigured, CircuitRegistered, CircuitDisabled, AttestorSetUpdated, AlgorithmConfigured
LifecycleIdentity, key, issuer, root and credential-status events

No event carries witness data, balances or credential attributes.

7. Tests

cd contracts && pnpm exec forge test: 123 tests, no forge-std (see test/utils/Vm.sol).

KindWhereWhat
Unittest/identity, test/credentials, test/zk, test/pqc, test/authorizationevery state transition, revert path, role check and pause rule
Fuzzthe same files (testFuzz_*)field ranges, lengths, callers, status sequences, time windows, corrupted proofs, attestation fields
Invarianttest/invariant/ProtocolInvariants.t.solno double spend or consume; deactivation terminal; versions monotonic; one active key version, the latest; key and credential revocation terminal
Integrationtest/integration/ProtocolLifecycle.t.solfull identity lifecycle across all modes; the manager with real UltraHonk proofs, including one generated for an authorization request whose digest TypeScript computed
Real ZKtest/zk/QuantLayerProofVerifier.t.solall six circuits with committed proofs, plus every binding and replay rejection
Feasibilitytest/bench/PqcFeasibility.t.solKeccak-f and NTT correctness and gas (§5)
Deploymenttest/script/DeployQuantLayer.t.solthe deploy script wires everything, and refuses other chains

The TypeScript harnesses run the same contracts on ethereumjs:

  • packages/zk-noir/src/evm.test.ts;
  • packages/authorization/src/engine/evm.test.ts. This test also shows an ML-DSA-65 signature verified by the engine being accepted on-chain through a 2-of-3 attestation.

8. Deployment (Arbitrum Sepolia)

cd contracts
pnpm exec forge test                                    # must pass first
pnpm exec forge script script/DeployQuantLayer.s.sol \
  --rpc-url "$ARBITRUM_SEPOLIA_RPC_URL" \
  --account quantlayer-testnet --sender "$DEPLOYER" --broadcast
  • Keys. The signing key comes from a Foundry keystore (cast wallet import) or a hardware wallet. It is never read from a file or environment variable.
  • Output. Addresses are written to deployments/421614.json.
  • Chains. The script refuses any chain other than 421614 or a local chain.
  • Testnet roles. On testnet the deployer holds every role. For production:
    • give DEFAULT_ADMIN_ROLE to a timelocked multisig;
    • give each operational role to its own account;
    • have the deployer renounce its roles;
    • register an attestor set before enabling the post-quantum, hybrid or credential policies.