Starknet verifier

This page is for Cairo developers who consume Molpha attestations on Starknet. It covers how to depend on the verifier, how to call it from your contract, how to build the arguments off-chain, and the contract reference. The Starknet verifier is a stateless view contract. Given an Attestation, it answers one question: did enough selected Molpha nodes sign this exact payload under the stated registry version? It does not store feeds or consumed updates. Your contract owns source and threshold policy, replay protection, and value decoding. Source: molpha/starknet-verifier · Cairo / Scarb 2.18+ · snforge 0.61+. Addresses: Deployments.

Depend on the verifier

Your contract only needs the interface types and the generated dispatcher. Add the repository as a Scarb git dependency; the package is named verifier. Pin the chivchyn tag, the release that matches the deployed verifier.

Scarb.toml

[dependencies]
starknet = "2.18.0"
verifier = { git = "https://github.com/molpha/starknet-verifier.git", tag = "chivchyn" }

use verifier::interface::{Attestation, IVerifierDispatcher, IVerifierDispatcherTrait};
use verifier::verify_codes;

To build and test the contracts locally:

git clone --branch chivchyn https://github.com/molpha/starknet-verifier.git
cd starknet-verifier
scarb build
snforge test

Verify an attestation in Cairo

verify never panics on a rejected attestation. It returns (false, code), so you must check the bool before using the payload.

use starknet::ContractAddress;
use verifier::interface::{Attestation, IVerifierDispatcher, IVerifierDispatcherTrait};

const EXPECTED_SOURCE: u256 = 0x...;  // your pinned sourceId
const MIN_SIGNATURES: u8 = 3;         // your minimum threshold

fn consume_update(verifier: ContractAddress, attestation: Attestation, max_age: u64) {
    let v = IVerifierDispatcher { contract_address: verifier };

    // 1. Signature, registry version and freshness (max_age in seconds; 0 disables it).
    let (ok, _code) = v.verify(attestation, max_age);
    assert(ok, 'molpha: not verified'); // _code is a verify_codes value

    // 2. Your policy.
    let payload = attestation.payload;
    assert(payload.source_id == EXPECTED_SOURCE, 'molpha: wrong source');
    assert(payload.signatures_required >= MIN_SIGNATURES, 'molpha: low threshold');

    // 3. Replay: track the last accepted timestamp per source_id in your storage.
    // 4. Decode payload.value with the source's encoding and sanity-bound it.
}

Around every call:

Check the bool. A bad signature, a stale timestamp and a malformed field all return (false, code).
Pin source_id and enforce a minimum signatures_required (>=, not ==). source_id does not commit the threshold, so a higher threshold is always acceptable.
Pass a non-zero max_age. With 0, a correctly signed attestation keeps verifying for as long as its registry version is accepted.
Prevent replay. verify is a view call, so the same attestation verifies any number of times.
Treat value as an opaque u256 until you decode it for your source.

The full list, shared by every chain, is the consumer checklist. sourceId derivation is on Feeds.

Build the arguments off-chain

The SDK maps a gateway Attestation onto the Cairo structs, with no starknet.js runtime dependency.

import {
  buildStarknetVerifierArgs,
  encodeStarknetVerifyCalldata,
  parseStarknetVerifyResult,
} from "@molpha/sdk";

// maxAge is required: seconds, 0 disables the freshness check.
const args = buildStarknetVerifierArgs(attestation, { maxAge: 60 }); // { attestation, maxAge }
const calldata = encodeStarknetVerifyCalldata(args);                 // 13 felts

// Send `calldata` in a starknet_call to the verifier's `verify` entry point,
// then decode the two returned felts (for example ["0x1", "0x0"]):
const { success, code, reason } = parseStarknetVerifyResult(returnedFelts);

args.attestation uses the Cairo member names, so an ABI-aware client can pass it directly. parseStarknetVerifyResult also accepts a decoded (bool, u8) tuple, and throws if the two halves disagree, which means the call did not reach a Molpha verifier with this interface. See the SDK reference.

SDK `Attestation` field	Cairo field
`payload.value`	`payload.value`
`payload.sourceId`	`payload.source_id`
`payload.registryVersion`	`payload.registry_version`
`payload.signaturesRequired`	`payload.signatures_required`
`payload.timestamp`	`payload.timestamp`
`signature.s`	`signature.signature`
`signature.commitmentAddr`	`signature.commitment`
`signature.signersBitmap`	`signature.signers_bitmap`

Reference

Structs

Defined in verifier/src/interface.cairo. Field order is the order of the signed message; see Attestations for the message itself.

struct AttestationPayload {
    value: u256,              // opaque 32-byte result
    source_id: u256,
    registry_version: u32,    // snapshot the nodes signed under
    signatures_required: u8,
    timestamp: u64,           // unix milliseconds
}

struct SchnorrSignature {
    signature: u256,          // aggregate Schnorr scalar s
    commitment: felt252,      // Ethereum-style address of R; must fit 160 bits
    signers_bitmap: u256,     // bit i set iff the node at 0-based index i signed
}

struct Attestation {
    payload: AttestationPayload,
    signature: SchnorrSignature,
}

Serialized calldata for verify is 13 felts. Each u256 is two felts, low 128 bits first:

value.low, value.high, source_id.low, source_id.high, registry_version,
signatures_required, timestamp, signature.low, signature.high, commitment,
signers_bitmap.low, signers_bitmap.high, max_age

The call returns two felts: the bool and the u8 code. Calldata that does not deserialize (for example a signatures_required felt above 255) fails before verify runs instead of returning a code.

`verify`

fn verify(self: @TContractState, attestation: Attestation, max_age: u64) -> (bool, u8);

max_age is in seconds and is compared against timestamp / 1000 and the block timestamp. Checks run in this order and stop at the first failure:

Structural guards

R_MALFORMED if signatures_required == 0, signers_bitmap == 0, signature is 0 or >= Q, commitment is 0 or wider than 160 bits, or fewer bits are set than signatures_required.

Freshness (only when max_age != 0)

R_MALFORMED if timestamp / 1000 is after the block timestamp; R_STALE if it is more than max_age seconds old.

Registry version

R_BAD_REGISTRY_VERSION if the version was never published; R_NOT_YET_ACTIVE if the payload predates its activation; R_VERSION_EXPIRED if it is past the grace window below.

Signer selection

R_BAD_QUORUM if the bitmap is not within the derived selection set, or the version has no nodes.

Aggregate signature

R_BAD_AGGREGATE if the signers’ keys sum to the point at infinity; R_BAD_SIGNATURE if the Schnorr check fails. Otherwise (true, R_OK).

Selection and the Schnorr check are described in Cryptography. On Starknet the final curve check uses native secp256k1 syscalls and compares the Ethereum-style address of s·G − e·P with commitment, the same check the EVM verifier does with ecrecover.

Result codes

Codes are defined in verifier/src/verify_codes.cairo and are identical to the EVM verifier’s: see EVM result codes. The same payload produces the same code on every chain, and codes 1 and 6 are reserved and never returned.

Registry versions

Every registry change publishes a new immutable version whose activation time is the block timestamp of that transaction. A version accepts payloads whose timestamp / 1000 lies in [activates_at(v), activates_at(v + 1) + 60]; the latest version has no upper bound. The 60 s grace is checked against the payload timestamp, not the wall clock. Pass the exact registry_version the nodes signed under. Details: Registry versions.

Reads and admin functions

Function	Returns
`get_registry_version() -> u32`	Latest version
`get_activates_at(registry_version: u32) -> (u64, bool)`	Activation time (unix seconds) and whether the version exists
`get_total_nodes() -> u32`	Node count in the latest version
`is_node(node: felt252) -> bool`	Whether the address is active
`get_node_status(node: felt252) -> u8`	`0` never registered, `1` active, `2` retired
`get_node_index(node: felt252) -> u32`	0-based index; also `0` for unknown addresses, so check `is_node` first
`get_aggregate_key() -> (u256, u256)`	Plain-sum key of the latest set
`get_redundancy_buffer() -> u32`	Buffer of the latest version
`get_protocol_admin() -> ContractAddress`	Protocol admin

The protocol admin manages the node set with add_node (compressed key plus proof-of-possession), remove_node (address plus 0-based index witness), set_redundancy_buffer and transfer_protocol_admin. Each registry change publishes a new version, so attestations signed under an earlier version keep verifying against it within its window. Nodes register per deployment, with a proof-of-possession bound to the verifier’s contract address.

Gas

Measured with verifier/tests/benchmarks.cairo (snforge 0.61, scarb run bench); re-run for your configuration.

Scenario	`verify` L2 gas
12 nodes, buffer 2, `signatures_required = 5`, 7 signers	~25.1M
18 nodes, buffer 2, 3 to 18 signers	~24.4M to ~27.2M

Cost is not linear in signer count, because selection switches algorithms depending on group size relative to the node count. Registry changes copy the previous key set forward, so their cost grows with registry size.

Parity with EVM

The Cairo verifier is a port of the EVM verifier: same structs, same signed message (no chainId), same selection, same result codes and the same 60 s grace. One gateway payload verifies unmodified on Starknet and every supported EVM chain; the repository’s parity.cairo and e2e.cairo tests check this against EVM golden vectors. Bit i of the bitmap refers to the same node as index i on the EVM verifier.

Next steps

Consumer checklist

Freshness, replay and threshold rules for every chain.

Deployments

Verifier addresses and network status.

Smart contract quickstart

Fetch an attestation and verify it end to end.

Get started

Concepts

Access and payments

MCP server

Verify and publish

Protocol

Resources

Starknet verifier

Depend on the verifier

Verify an attestation in Cairo

Build the arguments off-chain

Reference

Structs

`verify`

Result codes

Registry versions

Reads and admin functions

Gas

Parity with EVM

Next steps

Consumer checklist

Deployments

Smart contract quickstart

​Depend on the verifier

​Verify an attestation in Cairo

​Build the arguments off-chain

​Reference

​Structs

​verify

​Result codes

​Registry versions

​Reads and admin functions

​Gas

​Parity with EVM

​Next steps

Consumer checklist

Deployments

Smart contract quickstart

Depend on the verifier

Verify an attestation in Cairo

Build the arguments off-chain

Reference

Structs

`verify`

Result codes

Registry versions

Reads and admin functions

Gas

Parity with EVM

Next steps