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
| Contract | Role | Pausable |
|---|---|---|
QuantLayerIdentityRegistry | DID hash → controller, status (Active / Suspended / Deactivated), document hash, version | Registration and updates. Suspend and deactivate are never paused. |
QuantLayerKeyRegistry | Versioned keys per (DID, key id): algorithm, purposes, expiry, public-key hash, EVM signer | Add and rotate. Revoke is never paused. |
QuantLayerCredentialRegistry | Issuers, allowed credential types, Merkle roots (with grace period and immediate revocation), credential status | Issuer registration. Root publication, revocation and status changes are never paused. |
QuantLayerNullifierRegistry | Protocol-wide spent set: (scope, nullifier) pairs and single-use contexts/nonces | No: there is nothing to halt, and the registry only ever adds entries. |
QuantLayerProofVerifier | ZK proof verification with full binding, through versioned proof-system adapters | Verification. |
UltraHonkVerifierAdapter | Wraps one generated Barretenberg verifier as proof system 1, with its verification-key hash | — |
QuantLayerPqcAttestationVerifier | k-of-n EIP-712 attestations of off-chain post-quantum / credential verification | — (no state changes) |
QuantLayerAuthorizationManager | QuantLayer authorization requests under versioned policies, for every mode | New 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.
| Role | Held on | Can |
|---|---|---|
DEFAULT_ADMIN_ROLE | every contract | grant and revoke roles. In production this belongs to a timelocked multisig. |
REGISTRAR | identities | register identities |
GUARDIAN | identities, keys | suspend, reinstate and deactivate identities, and revoke keys (compromise response) |
ALGORITHM_ADMIN | keys | enable or disable algorithms and set key lengths (crypto agility) |
ISSUER_ADMIN | credentials | register and deactivate issuers, and allow credential types |
| issuer authority | credentials (per issuer) | publish and revoke roots, and set credential status |
CIRCUIT_ADMIN | proof verifier | configure proof systems and circuits, and set maxProofAge |
CONSUMER | nullifiers | spend nullifiers and consume contexts. Granted only to the proof verifier and the manager. |
POLICY_ADMIN | manager | publish, retire and version policies |
ATTESTOR_ADMIN | attestation verifier | replace the attestor set and threshold |
PAUSER | every pausable contract | pause 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, thenacceptController); - add, rotate and revoke keys;
- deactivate the identity.
3. Replay protection, expiry and domain separation
| Threat | Defence |
|---|---|
| Same authorization twice | Each (subject, nonce) is consumed once in QuantLayerNullifierRegistry, across every mode. nonceKey also binds the chain and the manager address. |
| Same ZK proof twice | Each proof context is consumed once (contextKey(context)). |
| Same holder claims twice with fresh proofs | The nullifier is spent once per scope. Scope = (chain, verifier, app, action), shared across circuits and consumers. |
| Signature or proof replayed on another chain or deployment | EIP-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 action | The policy binds keccak256(appDomain) and keccak256(action), and optionally a required calling contract (consumer). |
| Stale or long-lived requests | expiresAt > now, issuedAt ≤ now + clockSkew and expiresAt − issuedAt ≤ maxLifetime. |
| Stale proofs | now − provenAt ≤ maxProofAge, and the root must be current or within its grace period. |
| Stale attestations | verifiedAt ≤ 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 signatures | OpenZeppelin 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 byONCHAIN_ALGORITHM_IDSin@quantlayer-protocol/authorization):Family Identifiers Ed25519 0x0001ES256K 0x0002ES256K-EIP712 0x0003(the key is a 20-byte EVM address)ML-DSA-44 / 65 / 87 0x11/0x12/0x13SLH-DSA-SHA2-128s / 128f / 256s 0x21/0x22/0x23ML-KEM-512 / 768 / 1024 0x31/0x32/0x33Public-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]. RaisingminVersionretires 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:
- An attestor runs QuantLayer's engine (
@quantlayer-protocol/authorizationwith QuantLayer Quantum / libcrux) on the request and its evidence. - The attestor builds an attestation only for an
allowdecision, usingattestPostQuantumAuthorization. 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.
- The attestor signs the EIP-712
PqcAttestation. Its domain is "QuantLayer PQC Attestation", version 1, chain id, and the verifier address. The digest ispqcAttestationDigest, and a test checks it equals the contract's. - 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.
- checks that the key is usable in
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:
| Mode | Evidence | Assurance |
|---|---|---|
| 1 classical | EIP-712 ECDSA by the registered ES256K-EIP712 key | Trustless |
| 2 post-quantum | ML-DSA / SLH-DSA, attested | Attested |
| 3 hybrid | ECDSA half verified on-chain and PQ half attested | Attested (the PQ guarantee rests on attestors; the attestors alone can't authorize) |
| 4 credential | Status checked on-chain (issuer active, credential Active, type), presentation attested | Attested |
| 5 ZK eligibility | UltraHonk proof verified on-chain, bound to the request digest | Trustless |
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
thresholdandcredentialType, so the policy pins them (credentialTypeIndex/credentialType,thresholdIndex/minThreshold).
6. Events
Events are indexed for off-chain indexers and relying parties.
| Contract | Event |
|---|---|
| Manager | Authorized(digest, policyKey, subjectHash, mode, assurance, nullifier) |
| Proof verifier | ProofVerified(circuitId, consumer, appId, context, nullifier). Relying parties confirm it from their own node with confirmOnChainVerification. |
| Nullifier registry | NullifierSpent and ContextConsumed |
| Configuration | PolicyConfigured, ProofSystemConfigured, CircuitRegistered, CircuitDisabled, AttestorSetUpdated, AlgorithmConfigured |
| Lifecycle | Identity, 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).
| Kind | Where | What |
|---|---|---|
| Unit | test/identity, test/credentials, test/zk, test/pqc, test/authorization | every state transition, revert path, role check and pause rule |
| Fuzz | the same files (testFuzz_*) | field ranges, lengths, callers, status sequences, time windows, corrupted proofs, attestation fields |
| Invariant | test/invariant/ProtocolInvariants.t.sol | no double spend or consume; deactivation terminal; versions monotonic; one active key version, the latest; key and credential revocation terminal |
| Integration | test/integration/ProtocolLifecycle.t.sol | full identity lifecycle across all modes; the manager with real UltraHonk proofs, including one generated for an authorization request whose digest TypeScript computed |
| Real ZK | test/zk/QuantLayerProofVerifier.t.sol | all six circuits with committed proofs, plus every binding and replay rejection |
| Feasibility | test/bench/PqcFeasibility.t.sol | Keccak-f and NTT correctness and gas (§5) |
| Deployment | test/script/DeployQuantLayer.t.sol | the 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_ROLEto 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.
- give