EVM verifier

This page shows how to verify a Molpha attestation in a Solidity contract and act on its value in the same transaction. It is for EVM developers; the second half is the contract reference. The verifier is a stateless view contract. It checks that enough selected nodes signed the payload under the stated registry version, and optionally that the payload is fresh. Your contract owns source and threshold policy, replay protection and value decoding.

Install

The interface, result codes and consumer library live in molpha/evm-verifier (Apache-2.0). Add it as a Foundry dependency:

forge install molpha/evm-verifier@chivchyn

chivchyn is the release tag that matches the deployed verifier.

remappings.txt

@molpha/evm-verifier/=lib/evm-verifier/src/

import {IVerifier} from "@molpha/evm-verifier/interfaces/IVerifier.sol";
import {MolphaLib} from "@molpha/evm-verifier/consumer/MolphaLib.sol";
import {VerifyCodes} from "@molpha/evm-verifier/libs/VerifyCodes.sol";

These three files compile on >=0.8.4 <0.9.0 and import nothing outside the package. The Verifier contract itself (Solidity 0.8.31, Cancun) is only needed if you run the repository’s tests. Pin a deployed verifier address from Deployments.

Verify an attestation

Accept the attestation as calldata

Your function takes an IVerifier.Attestation calldata: the signed payload plus its aggregate signature. A relayer, keeper or user submits it in the transaction that uses the value.

Check source, threshold, freshness and signature

MolphaLib.requireValid checks that sourceId matches yours and that signaturesRequired is at least your minimum, then calls verify with your maxAge. It reverts on the first failure.

Guard against replay

verify is view, so the same attestation verifies any number of times. latest.acceptNewer accepts only a strictly newer timestamp.

Decode the value and act

value is an opaque bytes32. Decode it with your source’s encoding, for example MolphaLib.asInt256.

// SPDX-License-Identifier: MIT
pragma solidity >=0.8.4 <0.9.0;

import {IVerifier} from "@molpha/evm-verifier/interfaces/IVerifier.sol";
import {MolphaLib} from "@molpha/evm-verifier/consumer/MolphaLib.sol";

contract MyConsumer {
    using MolphaLib for IVerifier;
    using MolphaLib for MolphaLib.Latest;

    IVerifier public immutable VERIFIER;
    MolphaLib.Policy internal policy;
    MolphaLib.Latest internal latest;

    int256 public lastValue;

    constructor(IVerifier verifier, bytes32 sourceId, uint32 minSignatures, uint64 maxAge) {
        VERIFIER = verifier;
        // minSignatures is a floor: attestations with signaturesRequired >= minSignatures pass.
        // maxAge is in seconds; 0 disables the freshness check.
        policy = MolphaLib.Policy({sourceId: sourceId, minSignatures: minSignatures, maxAge: maxAge});
    }

    function settle(IVerifier.Attestation calldata att) external {
        VERIFIER.requireValid(att, policy);              // source, threshold floor, freshness, signature
        latest.acceptNewer(att.payload);                 // replay guard
        lastValue = MolphaLib.asInt256(att.payload.value);
    }
}

This follows examples/SettleOnWord.sol in the repository, which also has LatestStore.sol and StructuredPayload.sol. To get a sourceId, see Feeds. Without the library, call verify and apply the same checks yourself:

error NotVerified(uint8 code);

(bool ok, uint8 code) = VERIFIER.verify(att, MAX_AGE); // MAX_AGE: uint64 seconds, 0 disables freshness
if (!ok) revert NotVerified(code);
require(att.payload.sourceId == EXPECTED_SOURCE, "wrong source");
require(att.payload.signaturesRequired >= MIN_SIGNATURES, "threshold too low");
// guard replay, then decode att.payload.value

verify does not revert on a rejected attestation. A bad signature, stale timestamp or malformed field returns (false, code). A contract that ignores success accepts unverified data.

Enforce signaturesRequired as a minimum (>=), never as equality. sourceId does not commit the threshold: whoever requests the attestation chooses it. The full list of consumer duties is in the consumer checklist. For unit tests, src/test-utils/MockVerifier.sol exposes a verify with a configurable result (setResult, setResultFor) and no cryptography.

Build the arguments off-chain

buildEvmVerifierArgs maps the Attestation returned by sdk.gateway.requestSignedData (see the backend quickstart) onto the on-chain structs. It has no viem or ethers dependency. maxAge is required: seconds, 0 to disable freshness.

import { buildEvmVerifierArgs, MOLPHA_VERIFIER_ABI, parseEvmVerifyResult } from "@molpha/sdk";

const { attestation, maxAge } = buildEvmVerifierArgs(result, { maxAge: 60 });

// Dry-run against the verifier (viem). Pass `attestation` to your own contract the same way.
const out = await client.readContract({
  address: verifierAddress,
  abi: MOLPHA_VERIFIER_ABI,
  functionName: "verify",
  args: [attestation, maxAge],
});
const { success, code, reason } = parseEvmVerifyResult(out);

For a raw eth_call, encodeEvmVerifyCalldata({ attestation, maxAge }) returns the calldata and parseEvmVerifyResult also accepts the 64-byte return data.

SDK `Attestation` field	On-chain field
`payload.value`, `sourceId`, `registryVersion`, `signaturesRequired`, `timestamp`	Same names under `payload`
`signature.s`	`signature.signature`
`signature.commitmentAddr`	`signature.commitment`
`signature.signersBitmap` (32-byte hex)	`signature.signersBitmap` (`uint256`)

Consumer library

MolphaLib (src/consumer/MolphaLib.sol) packages the checks verify leaves to you. It holds no storage and runs the cheap calldata comparisons before calling the verifier.

Item	Purpose
`Policy { bytes32 sourceId; uint32 minSignatures; uint64 maxAge; }`	The source you accept, your threshold floor (`>= 1`), and the freshness window passed to `verify`. `NO_MAX_AGE` (`0`) disables freshness.
`requireValid(verifier, att, policy)`	Checks the policy, then `verify`. Reverts on the first failure.
`requireValid(verifier, att, policy, encodedFields)`	Also requires `keccak256(encodedFields) == att.payload.value`, for sources whose `value` is the hash of an ABI-encoded tuple sent alongside as unsigned calldata.
`isValid(...)` (both overloads)	Non-reverting form returning `(bool ok, uint8 code)`, for batch and keeper contracts.
`Latest` + `acceptNewer(latest, payload)`	Accepts only a strictly newer `timestamp`. One storage slot. Keep one per source: `mapping(bytes32 => MolphaLib.Latest)`.
`Consumed` + `consumeOnce(consumed, payload)`	Accepts each attestation once, in any order. Storage grows with every attestation.
`replayKey(payload)`	`keccak256(abi.encodePacked(sourceId, timestamp))`. Excludes `registryVersion`, so the same round signed under two registry versions counts as one update.
`asUint256` / `asInt256` / `asBool` / `asAddress`	Decode a single-word `value`. `asBool` and `asAddress` revert with `MalformedWord` on non-canonical words.

Checks run in this order:

Check	`isValid` code	`requireValid` error
`policy.sourceId != 0` and `policy.minSignatures != 0`	`0xF3` `L_INVALID_POLICY`	`InvalidPolicy()`
`att.payload.sourceId == policy.sourceId`	`0xF0` `L_WRONG_SOURCE`	`WrongSource(expected, actual)`
`att.payload.signaturesRequired >= policy.minSignatures`	`0xF1` `L_THRESHOLD_POLICY`	`ThresholdBelowPolicy(minimum, actual)`
`keccak256(encodedFields) == att.payload.value` (four-argument overloads)	`0xF2` `L_PAYLOAD_MISMATCH`	`PayloadMismatch(expected, actual)`
`verifier.verify(att, policy.maxAge)`	The verifier’s code	`VerifyFailed(code)`

The replay guards revert with NotNewer(last, actual) and AlreadyConsumed(key). With NO_MAX_AGE, acceptNewer enforces ordering but not recency, so the first attestation a contract accepts can be arbitrarily old.

Reference

Structs

Defined in IVerifier. Payload field order is the order of the signed message.

struct AttestationPayload {
    bytes32 value;              // opaque 32-byte result
    bytes32 sourceId;
    uint32  registryVersion;    // registry snapshot the signature was built against
    uint8   signaturesRequired;
    uint64  timestamp;          // unix milliseconds
}

struct SchnorrSignature {
    bytes32 signature;          // aggregate Schnorr scalar s
    address commitment;         // address of the nonce point R
    uint256 signersBitmap;      // bit i set iff node index i signed
}

struct Attestation {
    AttestationPayload payload;
    SchnorrSignature signature;
}

Bit i of signersBitmap maps to 0-based node index i in that registry version. Indices can change between versions, so an index is valid for one version only.

`verify`

function verify(Attestation calldata attestation, uint64 maxAge)
    external view returns (bool success, uint8 code);

The selector is 0x67e2907b. Both structs are static, so calldata is the selector followed by nine 32-byte words: value, sourceId, registryVersion, signaturesRequired, timestamp, signature, commitment, signersBitmap, maxAge. maxAge is in seconds and is compared against timestamp / 1000 and block.timestamp. An attestation passes while block.timestamp - timestamp / 1000 <= maxAge; 0 skips the check. Calldata that does not ABI-decode (for example a signaturesRequired word above 255) reverts in the decoder instead of returning a code. Checks run in this order and stop at the first failure:

Calldata guards: signaturesRequired, signersBitmap, signature or commitment is zero, signature >= Q, or fewer set bits than signaturesRequired → R_MALFORMED.
Freshness, only when maxAge != 0: timestamp in a future second → R_MALFORMED; older than maxAge → R_STALE.
Registry version lifetime → R_BAD_REGISTRY_VERSION, R_NOT_YET_ACTIVE or R_VERSION_EXPIRED.
Signers outside the derived selection set → R_BAD_QUORUM. Selection math is on Cryptography.
Aggregate key is the point at infinity → R_BAD_AGGREGATE.
Schnorr check fails → R_BAD_SIGNATURE.

Result codes

Defined in src/libs/VerifyCodes.sol. The numbering is shared with the Starknet verifier.

Code	Name	Meaning
0	`R_OK`	Valid
1	`R_FEED_WITNESS`	Reserved, never returned
2	`R_BAD_REGISTRY_VERSION`	The registry version does not exist on this verifier
3	`R_MALFORMED`	A calldata guard failed, or the timestamp is in the future when `maxAge != 0`
4	`R_NOT_YET_ACTIVE`	`timestamp / 1000` is before the version’s activation
5	`R_VERSION_EXPIRED`	The version was superseded more than 60 s before `timestamp / 1000`
6	`R_COMPROMISED_QUORUM`	Reserved, never returned
7	`R_BAD_QUORUM`	Signers are not within the selection set, or the version has no nodes
8	`R_BAD_AGGREGATE`	The signers’ aggregate public key is the point at infinity
9	`R_BAD_SIGNATURE`	The aggregate Schnorr signature does not verify
10	`R_STALE`	Older than `maxAge`

Registry versions

Every registry change publishes a new version whose activatesAt is the block timestamp of that transaction. A version accepts payloads whose timestamp / 1000 lies in [activatesAt(v), activatesAt(v + 1) + 60]; the latest version has no upper bound. The test uses the payload timestamp, not the current block time, so a round signed inside that window keeps verifying with maxAge = 0. Pass the exact registryVersion the nodes signed under. See Registry versions. Useful reads: getRegistryVersion(), activatesAt(uint256), retiredAt(uint256), isLatestVersion(uint256), getTotalNodes(), isNode(address), nodeStatus(address) (0 never registered, 1 active, 2 retired) and redundancyBuffer(). Version-keyed reads revert with InvalidRegistryVersion for a version that was never published.

Admin functions

These belong to the verifier’s owner (Solady Ownable); other callers revert with Unauthorized(). Each call publishes a new registry version and emits RegistryAdvanced(newVersion, newRoot, op).

Function	Effect
`addNode(bytes compressedPubKey, SchnorrProof pop)`	Registers a node after checking its proof-of-possession. Up to 256 nodes; a previously registered address cannot be added again. Emits `LogNodeAdded`.
`removeNode(address node, uint256 index)`	Removes the node at `index` (swap-and-pop). Emits `LogNodeRemoved`.
`setRedundancyBuffer(uint256)`	Changes the selection buffer (max 256) under a new version, so earlier signatures keep verifying against their own version. Emits `LogRedundancyBufferUpdated`.
`transferOwnership(address)`	Inherited from Solady `Ownable`, with the two-step handover and `renounceOwnership()`.

Gas

Measured with test/gas/Verifier.gas.t.sol (VerifierGasTest, redundancy buffer 2, maxAge = 0, Solidity 0.8.31, Cancun, IR, 1M optimizer runs); re-run for your configuration:

FOUNDRY_PROFILE=gas forge test -vv --match-contract VerifierGasTest

Active nodes	Signers	Cold total	Warm total	Warm execution
8	5	40,022	37,996	14,652
256	1	36,932	34,300	10,956
256	5	45,163	41,909	18,529
256	9	51,680	47,837	24,421
256	18	63,684	59,426	35,914
256	32	81,477	76,397	52,837
256	64	120,798	115,104	91,436

Totals include calldata gas and the 21,000 base. Cost grows with the number of signers, not the registry size: verify reads only the signers’ keys and does one EC addition per signer. Report vulnerabilities through SECURITY.md, not public issues. Trust assumptions are on Security model.

Next steps

Smart contract quickstart

Request an attestation and verify it end to end.

Deployments

Verifier addresses per network.

Consumer checklist

Freshness, replay and threshold rules for every chain.

Get started

Concepts

Access and payments

MCP server

Verify and publish

Protocol

Resources

Install

Verify an attestation

Build the arguments off-chain

Consumer library

Reference

Structs

`verify`

Result codes

Registry versions

Admin functions

Gas

Next steps

Smart contract quickstart

Deployments

Consumer checklist

​Install

​Verify an attestation

​Build the arguments off-chain

​Consumer library

​Reference

​Structs

​verify

​Result codes

​Registry versions

​Admin functions

​Gas

​Next steps

Smart contract quickstart

Deployments

Consumer checklist

Install

Verify an attestation

Build the arguments off-chain

Consumer library

Reference

Structs

`verify`

Result codes

Registry versions

Admin functions

Gas

Next steps