VerificationEngine

The VerificationEngine (Solidity name NotareumVerificationEngine) drives the attestation lifecycle for registered resources. A resource owner requests verification at a target level; validators from the staking contract submit attestations; when quorum is met the engine finalizes the request and records the resulting verification level on the resource. The contract is the sole mutator of verification state.

Verification levels

enum VerificationLevel {
    Unverified,     // 0: registered only
    Basic,          // 1: 3 validators, 67% quorum
    Enhanced,       // 2: 7 validators, 75% quorum
    Institutional   // 3: 15 validators, 75% quorum
}

Higher levels require more validators and stricter quorum, reducing the probability of a coordinated bad attestation but raising the fee and latency.

Request lifecycle

Requests that never reach quorum before deadline expire; the fee is partially refunded (see FeeManager). Finalized requests enter a fixed dispute window (default 72 hours); a guilty ruling during the window reverts the verification level and slashes offending validators.

Data structures

enum RequestStatus { Open, Finalized, Expired, Disputed, Reverted }

struct VerificationRequest {
    bytes32 resourceId;
    address requester;
    VerificationLevel targetLevel;
    uint64 createdAt;
    uint64 deadline;
    uint32 attestCount;
    uint32 approveCount;
    RequestStatus status;
    uint256 feePaid;
}

struct Attestation {
    address validator;
    uint64 submittedAt;
    bool approve;         // true = approve, false = reject
    bytes32 evidenceHash; // keccak256 of off-chain evidence payload
}

Attestations are indexed per (requestId, validator) with a uniqueness guard.

Functions

`requestVerification`

function requestVerification(
    bytes32 resourceId,
    VerificationLevel targetLevel
) external payable returns (bytes32 requestId);

Opens a verification request for a registered resource at the target level. The caller pays the level-dependent fee (see FeeManager). Reverts if:

The resource does not exist.
The resource is revoked.
A non-expired open request already exists for the resource.
The fee is insufficient.

Emits VerificationRequested(requestId, resourceId, requester, targetLevel, deadline). The deadline is block.timestamp + requestTTL[targetLevel], where the TTL defaults to 7 days for Basic, 10 days for Enhanced, 14 days for Institutional.

`submitAttestation`

function submitAttestation(
    bytes32 requestId,
    bool approve,
    bytes32 evidenceHash
) external;

Submits one validator’s attestation. Reverts if:

The caller is not a registered validator in good standing (checked via ValidatorStaking.isActive(msg.sender)).
The caller has already attested for this requestId.
The validator’s tier is below the minimum for targetLevel.
The request is not in Open state.
The request deadline has passed.

The validator’s tier must meet the minimum for the target level:

Target level	Minimum validator tier
Basic	Basic
Enhanced	Professional
Institutional	Enterprise

Emits AttestationSubmitted(requestId, validator, approve, evidenceHash).

`finalizeRequest`

function finalizeRequest(bytes32 requestId) external;

Callable by anyone once quorum is reached. Computes whether the request met both the required totalValidators and the required approval ratio:

function quorumParams(VerificationLevel level) public pure returns (
    uint32 totalValidators,
    uint32 approvalNumer,
    uint32 approvalDenom
) {
    if (level == VerificationLevel.Basic)
        return (3, 2, 3);       // 67%
    if (level == VerificationLevel.Enhanced)
        return (7, 3, 4);       // 75%
    if (level == VerificationLevel.Institutional)
        return (15, 3, 4);      // 75%
    revert("level");
}

A request finalizes as approved when:

attestCount >= totalValidators &&
approveCount * approvalDenom >= attestCount * approvalNumer

On approval the engine calls into NotaRegistry.setVerificationLevel(resourceId, targetLevel). On rejection the resource stays at its prior level. Validators receive their attestation rewards from ValidatorStaking.creditAttestationReward. Emits VerificationFinalized(requestId, status, finalLevel).

`openDispute`

function openDispute(bytes32 requestId, bytes32 evidenceHash) external payable;

Within the dispute window, any veNOTA holder can open a dispute by posting a bond (the bond scales with targetLevel). The engine transitions the request to Disputed. Governance (or a fast-track dispute committee) resolves via resolveDispute.

`resolveDispute`

function resolveDispute(
    bytes32 requestId,
    bool disputantWins
) external; // role: DISPUTE_JUDGE

If the disputant wins, the engine reverts the verification level, triggers slashing on the majority-approving validators via SlashingManager.slash(validator, reason), and returns the bond plus a portion of the slashed amount to the disputant. If the disputant loses, the bond is split between the approving validators and the treasury.

Quorum math, formally

For a target level with n required validators and ratio r/d:

approve_needed = ceil(attestCount * r / d)
quorum_met = (attestCount >= n) AND (approveCount >= approve_needed)

Using integer comparisons avoids rounding pitfalls. The engine checks approveCount * d >= attestCount * r which is exact.

Byzantine fault margin

With n = 15 and honest-validator probability p_h = 0.95, the probability that at least 4 of 15 validators are Byzantine (breaking 75% approval) is:

P_fail = sum(k=4..15, C(15,k) * (1-p_h)^k * p_h^(15-k))

At p_h = 0.95, P_fail ≈ 7.4e-4. With the Institutional tier’s economic stake of 1M NOTA per validator, the capital required to mount a successful attack exceeds 4M NOTA across coordinated validators, and the SlashingManager slashes the full stake on successful dispute.

Dispute window

Dispute windows default to:

Basic: 24 hours
Enhanced: 48 hours
Institutional: 72 hours

During the window, the verification level is live but marked disputable: true in view functions. Wallets rendering a resource mid-window can choose to surface a “verification pending confirmation” signal. After the window closes with no disputes, the status becomes permanent (modulo owner revocation or later slashing events).

Events

event VerificationRequested(
    bytes32 indexed requestId,
    bytes32 indexed resourceId,
    address indexed requester,
    VerificationLevel targetLevel,
    uint64 deadline
);
event AttestationSubmitted(
    bytes32 indexed requestId,
    address indexed validator,
    bool approve,
    bytes32 evidenceHash
);
event VerificationFinalized(
    bytes32 indexed requestId,
    RequestStatus status,
    VerificationLevel finalLevel
);
event DisputeOpened(
    bytes32 indexed requestId,
    address indexed disputant,
    uint256 bond
);
event DisputeResolved(
    bytes32 indexed requestId,
    bool disputantWins
);

Gas notes

requestVerification: ≈120k gas (single SSTORE + fee transfer).
submitAttestation: ≈95k gas per call (struct write + counter updates).
finalizeRequest: ≈140k gas base + ≈20k per attestation in the reward distribution loop. For Institutional (15 validators), expect ≈440k gas.

SDK usage

import { Notareum } from "@notareum/sdk";

const ntm = Notareum({ provider, signer, contracts });

// Owner opens a request
const reqTx = await ntm.verification.requestVerification(resourceId, {
  level: "enhanced",
});
const { requestId } = await reqTx.wait();

// Validator submits
await ntm.verification.submitAttestation(requestId, {
  approve: true,
  evidenceHash: keccak256("...evidence..."),
});

// Anyone finalizes once quorum is met
await ntm.verification.finalizeRequest(requestId);

// Read current state
const state = await ntm.verification.getRequest(requestId);

Invariants

A validator submits at most one attestation per requestId.
A request transitions out of Open exactly once.
finalizeRequest never increases a resource’s level on rejection; it only increases on approval.
Slashing on dispute targets only the validators whose attestation matches the disproven side.

Getting Started

Protocol

Token

SDKs

Guides

Use Cases

Smart Contracts

Reference

Resources

Verification engine

VerificationEngine

Verification levels

Request lifecycle

Data structures

Functions

`requestVerification`

`submitAttestation`

`finalizeRequest`

`openDispute`

`resolveDispute`

Quorum math, formally

Byzantine fault margin

Dispute window

Events

Gas notes

SDK usage

Invariants

​VerificationEngine

​Verification levels

​Request lifecycle

​Data structures

​Functions

​requestVerification

​submitAttestation

​finalizeRequest

​openDispute

​resolveDispute

​Quorum math, formally

​Byzantine fault margin

​Dispute window

​Events

​Gas notes

​SDK usage

​Invariants

​Related pages

VerificationEngine

Verification levels

Request lifecycle

Data structures

Functions

`requestVerification`

`submitAttestation`

`finalizeRequest`

`openDispute`

`resolveDispute`

Quorum math, formally

Byzantine fault margin

Dispute window

Events

Gas notes

SDK usage

Invariants

Related pages