ERC-8084 ZK proof metadata standard (Zero-knowledge proof metadata)
Draft · Names & metadata · created 2025-11-10
Lets contracts expose a proof's circuit identifier, version, public input schema, and verification key location through standard functions, so wallets, explorers, and prover networks can interpret and process proofs without custom integration.
Why it is needed
ZK applications have no standard way to expose the shape of a proof. Since proving systems like Groth16, Plonk, Halo2, and zkVM each lead projects to deploy different artifacts, integrators must build a new custom adapter every time a new project appears. As a result, block explorers cannot decode a proof's public inputs and show only raw hex, and proof generation networks (solvers) have no way to automatically discover new jobs and fetch circuit artifacts, requiring manual integration each time. There is also no standard means to detect when a circuit version is silently rolled back to a vulnerable prior version or when constraints change without notice.
What to implement
event CircuitMetadataUpdated(bytes32 indexed circuitId, uint64 circuitVersion, bytes4 proofSystem);: An event emitted when stored circuit metadata changes.function circuitId() external view returns (bytes32);: Returns the content address identifier of the circuit definition artifact used to derive the verification key.function circuitVersion() external view returns (uint64);: Returns the circuit version. The upper 32 bits are the major version and the lower 32 bits are the minor version.function publicInputsSchemaHash() external view returns (bytes32);: Returns the canonical hash of the public input schema document.function publicInputsSchemaURI() external view returns (string memory);: Returns the location (URI) of the public input schema document.function verificationKeyURI() external view returns (string memory);: Returns the location (URI) where the verification key can be found.function proofSystem() external view returns (bytes4);: Returns the identifier of the proving system in use (e.g. Groth16, Plonk, Halo2).
In depth
6 core fields
IZKMetadata consists of 6 getters and a CircuitMetadataUpdated event: circuitId (content hash of the circuit definition artifact), circuitVersion (a semver-style version packing uint32.uint32 into a uint64), publicInputsSchemaHash and publicInputsSchemaURI (hash and location of the public input schema document), verificationKeyURI (location where the verification key can be found), and proofSystem (proving system identifier). Together these act as a 'ZK ABI,' letting integrators query each project's proof shape in code.
Proof system registry
proofSystem is represented as a bytes4 identifier: 0x0001 denotes Groth16 (BN254, e.g. snarkjs), 0x0002 denotes Plonk (a BN254 variant), 0x0003 denotes Halo2 (Plonkish family), 0x0004 denotes zkSTARK (generic STARK provers), and 0x0005 denotes zkVM (RISC-V/Jolt/RISC Zero, etc.). Additional identifiers must be proposed on the discussion thread, must not conflict with existing values, and tooling must treat unknown identifiers as unsupported.
Content hash and versioning rules
circuitId() must be the content hash (keccak256 or multihash) of the canonical circuit artifact used to derive the verification key. circuitVersion() must increase whenever an incompatible change occurs to the constraints or the meaning of the public inputs, and projects are recommended to use the upper 32 bits of the uint64 for the major version and the lower 32 bits for the minor version.
Schema and verification key integrity requirements
publicInputsSchemaHash() must match the document at publicInputsSchemaURI(). Schema and verification key URIs are recommended to use content addressing such as ipfs://, ar://, or bzz://; if HTTPS is used, the URI must include a URL fragment (e.g. #0x...) containing the hex-encoded Keccak-256 hash of the resource's content. Tooling must verify that the hash of the fetched schema document matches publicInputsSchemaHash(), and must also confirm that the verification key's content hash matches the hash fragment in the URI.
Event-driven updates
CircuitMetadataUpdated must be emitted within the same transaction in which the new metadata becomes observable. This requirement exists to prevent race conditions for indexers. Indexers and explorers are recommended to subscribe to this event rather than periodically polling the getters.
Backward compatibility
Existing contracts can accommodate this by deploying a separate adapter that implements IZKMetadata. It can take the form of an on-chain-only facade or an off-chain router, and does not modify the existing ERC.
A proposal that has not yet been finalized
This standard is currently in Draft status; specific fields or requirements may change during discussion, or the proposal may stall.
Things to watch out for
- Schema integrity: If tooling does not verify publicInputsSchemaHash() against the downloaded document, a malicious frontend or gateway could serve a tampered schema. In this case, an attacker could, for example, disguise a token amount field as a nonce field, tricking the user about what the proof actually attests to.
- Verification key mutability: Relying on an HTTP URI without a hash fragment lets a server administrator secretly change the verification key. While the contract still points to the old URI, there is a risk that the administrator could generate fake proofs using a tampered circuit.
- Indexer race condition: If the CircuitMetadataUpdated event is not emitted atomically with the state change, an off-chain indexer may read stale metadata (e.g. an outdated verification key) while processing the event. This could lead to widespread denial of service for proof generation.