Verdikta Dispatcher Smart Contracts¶

This documentation is auto-generated from NatSpec comments in the smart contract source code.

Available Contracts¶

ArbiterOperator¶

IArbiterOperator

Author: Verdikta Team

Marker interface for Verdikta ArbiterOperator with access control capabilities

Technical Details: Specialized interface implemented ONLY by ArbiterOperator contracts.

Public Functions¶

fulfillOracleRequestV()¶

Marker interface for Verdikta ArbiterOperator with access control capabilities

Technical: Specialized interface implemented ONLY by ArbiterOperator contracts.

function fulfillOracleRequestV(
        bytes32 requestId,
        uint256 payment,
        address callbackAddress,
        bytes4  callbackFunctionId,
        uint256 expiration,
        bytes   calldata data
    ) external returns (bool success);

    /**
     * @notice Check if an address is a registered ReputationKeeper
     * @dev Used by ReputationKeeper contracts to verify operator compliance
     * @param rkAddr Address to check
     * @return bool True if address is a registered ReputationKeeper
     */
    function isReputationKeeper(address rkAddr) external view returns (bool);

    /**
     * @notice Check if the ReputationKeeper allow-list is empty
     * @dev When empty, all requests are allowed (access control disabled)
     * @return bool True if no ReputationKeepers are registered
     */
    function isReputationKeeperListEmpty() external view returns (bool);
}

/* ────────────────────────────────────────────────────────────── */
/*  ArbiterOperator                                              */
/* ────────────────────────────────────────────────────────────── */

/**
 * @title ArbiterOperator
 * @author Verdikta Team
 * @notice Specialized Chainlink Operator with access control and multi-word response support
 * @dev Extended Chainlink Operator that:
 *      1) Provides `fulfillOracleRequestV` for multi-word responses (complex data structures)
 *      2) Enforces access control via ReputationKeeper allow-list before oracle requests
 *      3) Implements IArbiterOperator interface for Verdikta ecosystem integration
 *      
 *      Access control is enforced BEFORE OracleRequest events are emitted,
 *      ensuring Chainlink nodes never start processing unauthorized jobs.
 */
contract ArbiterOperator is OperatorMod, ERC165, IArbiterOperator

Parameters:

requestId: The Chainlink request ID to fulfill
payment: Payment amount in LINK tokens
callbackAddress: Address of the contract to call back
callbackFunctionId: Function selector to call on callback
expiration: Request expiration timestamp
data: Multi-word response data to send to callback
rkAddr: Address to check

Returns:

success Whether the callback was successful
bool True if address is a registered ReputationKeeper
bool True if no ReputationKeepers are registered

addReputationKeeper()¶

Add a ReputationKeeper contract to the access control allow-list

Technical: Only approved ReputationKeeper contracts can authorize consumer requests.

function addReputationKeeper(address rkAddr) external onlyOwner

Parameters:

rkAddr: Address of the ReputationKeeper contract to add

removeReputationKeeper()¶

Remove a ReputationKeeper contract from the access control allow-list

Technical: Removes authorization capability for the specified ReputationKeeper

function removeReputationKeeper(address rkAddr) external onlyOwner

Parameters:

rkAddr: Address of the ReputationKeeper contract to remove

isReputationKeeper()¶

Check if an address is a registered ReputationKeeper

Technical: Part of IArbiterOperator interface for ReputationKeeper verification

function isReputationKeeper(address rkAddr) external view override returns (bool)

Parameters:

rkAddr: Address to check

Returns:

bool True if address is in the ReputationKeeper allow-list

isReputationKeeperListEmpty()¶

Check if the ReputationKeeper allow-list is empty

Technical: When empty, access control is disabled and all requests are allowed

function isReputationKeeperListEmpty() external view override returns (bool)

Returns:

bool True if no ReputationKeepers are registered

supportsInterface()¶

Technical: Check if a requester is approved by any registered ReputationKeeper

function supportsInterface(bytes4 interfaceId)
        public
        view
        override(ERC165, IERC165)
        returns (bool)

Parameters:

requester: Address of the contract requesting oracle services

Returns:

bool True if approved by at least one ReputationKeeper, or if allow-list is empty

Events¶

ReputationKeeperAdded¶

Minimal view used by ArbiterOperator to consult allow-lists.

ReputationAggregator¶

ReputationAggregator commit-reveal edition (ASCII only)

Author: Verdikta Team

Two phase polling system for secure oracle aggregation with commit-reveal mechanism

Technical Details: Implements a sophisticated oracle aggregation system with the following phases:

Public Functions¶

setPhaseCounts()¶

Two phase polling system for secure oracle aggregation with commit-reveal mechanism

Technical: Implements a sophisticated oracle aggregation system with the following phases:

function setPhaseCounts(uint256 _k, uint256 _m, uint256 _n, uint256 _p) external onlyOwner

Parameters:

aggRequestId: Unique aggregator request identifier ///
cids: Array of IPFS CIDs containing evidence to evaluate event RequestAIEvaluation(bytes32 indexed aggRequestId, string[] cids); ///
aggRequestId: The aggregator request identifier ///
aggregated: Final aggregated likelihood scores ///
justifications: Combined IPFS CIDs of justifications from clustered oracles event FulfillAIEvaluation(bytes32 indexed aggRequestId, uint256[] aggregated, string justifications); ///
aggRequestId: The aggregator request identifier ///
pollIndex: The oracle's slot index in the polling array ///
operator: Address of the oracle operator ///
commitHash: Hash of the oracle's commitment event CommitReceived(bytes32 indexed aggRequestId, uint256 pollIndex, address operator, bytes16 commitHash); ///
aggRequestId: The aggregator request identifier event CommitPhaseComplete(bytes32 indexed aggRequestId); ///
aggRequestId: The aggregator request identifier ///
pollIndex: The oracle's slot index ///
commitHash: The commit hash being revealed event RevealRequestDispatched(bytes32 indexed aggRequestId, uint256 pollIndex, bytes16 commitHash); ///
requestId: The Chainlink request identifier ///
pollIndex: The oracle's slot index ///
operator: Address of the oracle operator event NewOracleResponseRecorded(bytes32 requestId, uint256 pollIndex, bytes32 indexed aggRequestId, address operator); ///
operator: Address of the oracle operator receiving bonus ///
bonusFee: Amount of bonus LINK tokens paid event BonusPayment(address indexed operator, uint256 bonusFee); ///
aggRequestId: The aggregator request identifier event EvaluationTimedOut(bytes32 indexed aggRequestId); ///
aggRequestId: The aggregator request identifier ///
phase: The phase where failure occurred ("commit" or "reveal") event EvaluationFailed(bytes32 indexed aggRequestId, string phase); ///
oracle: Address of the oracle ///
jobId: Job identifier ///
reason: Reason for skipping the update event OracleScoreUpdateSkipped(address oracle, bytes32 jobId, string reason); ///
aggRequestId: Aggregator request id ///
pollIndex: Oracle’s slot index ///
operator: Oracle operator address (msg.sender) ///
expectedHash: The hash stored from the commit ///
gotHash: Hash recomputed from the reveal payload event RevealHashMismatch( bytes32 indexed aggRequestId, uint256 indexed pollIndex, address operator, bytes16 expectedHash, bytes16 gotHash ); ///
oldKeeper: Address of the previous ReputationKeeper ///
newKeeper: Address of the new ReputationKeeper event ReputationKeeperChanged(address indexed oldKeeper, address indexed newKeeper); ///
clusteredTimeliness: New timeliness delta when clustered. ///
clusteredQuality: New quality delta when clustered. ///
selectedTimeliness: New timeliness delta when selected but not clustered. ///
selectedQuality: New quality delta when selected but not clustered. ///
revealedTimeliness: New timeliness delta when revealed but not selected. ///
revealedQuality: New quality delta when revealed but not selected. ///
committedTimeliness: New timeliness delta when committed but not revealed. ///
committedQuality: New quality delta when committed but not revealed. event ScoreDeltasUpdated( int8 clusteredTimeliness, int8 clusteredQuality, int8 selectedTimeliness, int8 selectedQuality, int8 revealedTimeliness, int8 revealedQuality, int8 committedTimeliness, int8 committedQuality); ///
aggRequestId: Aggregator‑level request identifier. ///
pollIndex: Zero‑based index of the oracle in the polling array. ///
operator: Address of the oracle operator (msg.sender). ///
badCid: The exact malformed cid:salt string that was rejected. event InvalidRevealFormat(bytes32 indexed aggRequestId, uint256 indexed pollIndex, address operator, string badCid); ///
aggRequestId: Aggregator-level request identifier ///
pollIndex: Zero-based slot number (0‥K-1) ///
oracle: Oracle operator address ///
jobId: Job-ID used for this request event OracleSelected( bytes32 indexed aggRequestId, uint256 indexed pollIndex, address oracle, bytes32 jobId ); ///
aggRequestId: Aggregator request identifier ///
pollIndex: Oracle's slot index ///
operator: Oracle operator address ///
responseLength: Length of the response array provided ///
maxAllowed: Maximum allowed length (maxLikelihoodLength) event RevealTooManyScores( bytes32 indexed aggRequestId, uint256 indexed pollIndex, address operator, uint256 responseLength, uint256 maxAllowed ); ///
aggRequestId: Aggregator request identifier ///
pollIndex: Oracle's slot index ///
operator: Oracle operator address ///
responseLength: Length of the response array provided ///
expectedLength: Expected length based on first successful reveal event RevealWrongScoreCount( bytes32 indexed aggRequestId, uint256 indexed pollIndex, address operator, uint256 responseLength, uint256 expectedLength ); ///
aggRequestId: Aggregator request identifier ///
pollIndex: Oracle's slot index ///
operator: Oracle operator address ///
responseLength: Length of the response array provided event RevealTooFewScores( bytes32 indexed aggRequestId, uint256 indexed pollIndex, address operator, uint256 responseLength ); // ---------------------------------------------------------------------- // STRUCTS // ---------------------------------------------------------------------- /
_k: Number of oracles to poll in commit phase (commitOraclesToPoll)
_m: Number of reveals requested from first M commits (oraclesToPoll)
_n: Number of reveals required for final aggregation (requiredResponses)
_p: Cluster size for bonus payments (clusterSize)

setCommitOraclesToPoll()¶

Set the number of oracles to poll in commit phase

Technical: Must be greater than or equal to oraclesToPoll (M)

function setCommitOraclesToPoll(uint256 _k) external onlyOwner

Parameters:

_k: Number of oracles to poll in commit phase

setResponseTimeout()¶

Set the response timeout in seconds

Technical: Timeout applies to both commit and reveal phases

function setResponseTimeout(uint256 _seconds) external onlyOwner

Parameters:

_seconds: Timeout duration in seconds

setMaxLikelihoodLength()¶

Set the maximum allowed length of the likelihood vector

Technical: Prevents gas‑exhaustion by very large oracle payloads.

function setMaxLikelihoodLength(uint256 _len) external onlyOwner

Parameters:

_len: New upper bound (must be >= 2)

setMaxOracleFee()¶

Set the maximum oracle fee in LINK tokens

Technical: This limits the maximum fee that can be paid to any oracle

function setMaxOracleFee(uint256 _newMax) external onlyOwner

Parameters:

_newMax: Maximum oracle fee in LINK wei

maxTotalFee()¶

Estimate the maximum LINK needed for complete evaluation with bonuses

Technical: Calculates: fee × (K + bonus_multiplier × P) for worst-case scenario

function maxTotalFee(uint256 requestedMaxOracleFee) public view returns (uint256)

Parameters:

requestedMaxOracleFee: Requested maximum fee per oracle

Returns:

Maximum total LINK required for the evaluation

requestAIEvaluationWithApproval()¶

Request AI evaluation with user-funded LINK payment

Technical: Main entry point for requesting AI evaluation using commit-reveal aggregation.

function requestAIEvaluationWithApproval(
        string[] memory cids,
        string memory addendumText,
        uint256 _alpha,
        uint256 _maxOracleFee,
        uint256 _estimatedBaseCost,
        uint256 _maxFeeBasedScalingFactor,
        uint64 _requestedClass
    ) public nonReentrant returns (bytes32)

Parameters:

cids: Array of IPFS CIDs containing evidence/data to evaluate
addendumText: Additional text to append to the evaluation request
_alpha: Reputation weight factor for oracle selection (0-1000)
_maxOracleFee: Maximum fee per oracle in LINK wei
_estimatedBaseCost: Estimated base cost for evaluation
_maxFeeBasedScalingFactor: Maximum scaling factor for fee-based selection
_requestedClass: Oracle class/category requested for evaluation

Returns:

bytes32 Unique aggregator request ID for tracking the evaluation

finalizeEvaluationTimeout()¶

Finalize an evaluation that has timed out

Technical: Can be called by anyone to finalize evaluations that have exceeded responseTimeoutSeconds.

function finalizeEvaluationTimeout(bytes32 aggId) external nonReentrant

Parameters:

aggId: The aggregator request ID to finalize

fulfill()¶

Callback function called by Chainlink oracles with their responses

Technical: Handles both commit and reveal phases based on payload structure.

function fulfill(
        bytes32 requestId,
        uint256[] memory response,
        string memory cid
    ) public recordChainlinkFulfillment(requestId) nonReentrant

Parameters:

requestId: The Chainlink request ID
response: Array of likelihood scores (reveal) or single hash value (commit)
cid: IPFS CID with salt (reveal phase) or empty string (commit phase)

getCurrentRequestCounter()¶

Get the current request counter value

Technical: Used for generating unique aggregator request IDs

function getCurrentRequestCounter() external view returns (uint256)

Returns:

Current request counter value

getEvaluation()¶

Get the evaluation results for a completed aggregation

Technical: Pay bonus to an operator

function getEvaluation(bytes32 reqId) public view returns (uint256[] memory, string memory, bool)

Parameters:

reqId: The aggregator request ID

Returns:

likelihoods Array of aggregated likelihood scores (0-100)
justifications Combined IPFS CIDs of justifications from clustered oracles
hasValidData Whether the evaluation completed successfully with valid data

evaluations()¶

Get evaluation results (legacy interface for backwards compatibility)

Technical: Simplified interface that returns only scores and justifications

function evaluations(bytes32 reqId) external view returns (uint256[] memory, string memory)

Parameters:

reqId: The aggregator request ID

Returns:

likelihoods Array of aggregated likelihood scores
justifications Combined IPFS CIDs of justifications

getContractConfig()¶

Get contract configuration (legacy interface)

Technical: Returns basic contract configuration for backwards compatibility

function getContractConfig()
        public view returns (
            address oracleAddr,
            address linkAddr,
            bytes32 jobId,
            uint256 fee
        )

Returns:

oracleAddr Placeholder oracle address (always returns zero)
linkAddr Address of the LINK token contract
jobId Placeholder job ID (always returns zero)
fee Placeholder fee (always returns zero)

withdrawLink()¶

Withdraw LINK tokens from the contract

Technical: Only callable by contract owner for emergency recovery

function withdrawLink(address payable _to, uint256 _amount) external onlyOwner

Parameters:

_to: Address to receive the LINK tokens
_amount: Amount of LINK tokens to withdraw (in wei)

setReputationKeeper()¶

Set a new ReputationKeeper contract address

Technical: Updates the reputation management contract used for oracle selection and scoring

function setReputationKeeper(address newKeeper) external onlyOwner

Parameters:

newKeeper: Address of the new ReputationKeeper contract

setConfig()¶

Set all configuration parameters at once

Technical: Preferred method for updating configuration with validation

function setConfig(
        uint256 _k,
        uint256 _m,
        uint256 _n,
        uint256 _p,
        uint256 _timeoutSecs
    ) external onlyOwner

Parameters:

_k: Number of oracles to poll in commit phase (commitOraclesToPoll)
_m: Number of reveals requested from first M commits (oraclesToPoll)
_n: Number of reveals required for final aggregation (requiredResponses)
_p: Cluster size for bonus payments (clusterSize)
_timeoutSecs: Response timeout in seconds

setBonusMultiplier()¶

Set the bonus multiplier for clustered oracles

Technical: Clustered oracles receive base_fee

function setBonusMultiplier(uint256 _m) external onlyOwner

Parameters:

_m: Bonus multiplier (0-20x), typically 3x

setScoreDeltas()¶

Updates all score‑delta parameters in one transaction.

Technical: Only callable by the contract owner. Emits a ScoreDeltasUpdated event.

function setScoreDeltas(
        int8 _clusteredTimeliness,
        int8 _clusteredQuality,
        int8 _selectedTimeliness,
        int8 _selectedQuality,
        int8 _revealedTimeliness,
        int8 _revealedQuality,
        int8 _committedTimeliness,
        int8 _committedQuality
    ) external onlyOwner

Parameters:

_clusteredTimeliness: Delta applied to timeliness when clustered.
_clusteredQuality: Delta applied to quality when clustered.
_selectedTimeliness: Delta applied to timeliness when selected but not clustered.
_selectedQuality: Delta applied to quality when selected but not clustered.
_revealedTimeliness: Delta applied to timeliness when revealed but not selected.
_revealedQuality: Delta applied to quality when revealed but not selected.
_committedTimeliness: Delta applied to timeliness when committed but not revealed.
_committedQuality: Delta applied to quality when committed but not revealed.

isFailed()¶

Check if an evaluation has failed

Technical: Returns true if the evaluation timed out or failed for other reasons

function isFailed(bytes32 aggId) external view returns (bool)

Parameters:

aggId: The aggregator request ID to check

Returns:

bool True if the evaluation failed, false otherwise

Events¶

RequestAIEvaluation¶

Emitted when a new AI evaluation request is created

FulfillAIEvaluation¶

Emitted when an AI evaluation is completed successfully

CommitReceived¶

Emitted when an oracle submits a commit hash

CommitPhaseComplete¶

Emitted when enough commits are received to start reveal phase

RevealRequestDispatched¶

Emitted when a reveal request is sent to an oracle

NewOracleResponseRecorded¶

Emitted when an oracle provides a valid reveal response

BonusPayment¶

Emitted when bonus payment is made to a clustered oracle

EvaluationTimedOut¶

Emitted when an evaluation times out

EvaluationFailed¶

Emitted when an evaluation fails in a specific phase

OracleScoreUpdateSkipped¶

Emitted when oracle score update is skipped due to error

RevealHashMismatch¶

Reveal payload failed the commit-hash check (i.e., there was a mismatch)

ReputationKeeperChanged¶

Emitted when ReputationKeeper contract is changed

ScoreDeltasUpdated¶

Emitted when the owner updates the score delta parameters.

InvalidRevealFormat¶

Emitted when an oracle’s reveal payload cannot be parsed because its

OracleSelected¶

Emitted for every oracle that is picked for a poll slot

RevealTooManyScores¶

Emitted when a reveal fails because response array is too long

RevealWrongScoreCount¶

Emitted when a reveal fails because response array length doesn't match expected

RevealTooFewScores¶

Emitted when a reveal fails because response array is too short (< 2 scores)

Data Structures¶

Response¶

Two phase polling system for secure oracle aggregation with commit-reveal mechanism

Technical: Implements a sophisticated oracle aggregation system with the following phases:

AggregatedEvaluation¶

Complete evaluation state for a single aggregation request

Technical: Tracks the entire lifecycle of a commit-reveal evaluation

ReputationKeeper¶

ReputationKeeper

Author: Verdikta Team

Manages oracle registration, reputation tracking, and selection for the Verdikta network

Technical Details: Central registry for oracle reputation management using composite keys (oracle address + jobID).

Public Functions¶

registerOracle()¶

Manages oracle registration, reputation tracking, and selection for the Verdikta network

Technical: Central registry for oracle reputation management using composite keys (oracle address + jobID).

function registerOracle(
        address _oracle,
        bytes32 _jobId,
        uint256 fee,
        uint64[] memory _classes
    ) external

Parameters:

_oracle: Address of the oracle contract (must implement IArbiterOperator)
_jobId: Chainlink job ID for this oracle instance
fee: LINK fee required for using this oracle
_classes: Array of evaluation classes this oracle supports (1-5 classes allowed)

deregisterOracle()¶

Deregister an oracle and remove it from the reputation system

Technical: Completely removes oracle record and returns staked tokens. Only callable by oracle owner or contract owner.

function deregisterOracle(address _oracle, bytes32 _jobId) external

Parameters:

_oracle: Address of the oracle contract to deregister
_jobId: Job ID of the oracle instance to deregister

setOracleActive()¶

Set an oracle's active status (pause/unpause)

Technical: Only the contract owner can perform this action. Paused oracles are excluded from selection.

function setOracleActive(address _oracle, bytes32 _jobId, bool _active) external onlyOwner

Parameters:

_oracle: Address of the oracle contract
_jobId: Job ID of the oracle instance
_active: True to activate/unpause, false to deactivate/pause

getOracleInfo()¶

Get comprehensive information about a registered oracle

Technical: Returns all oracle metadata, scores, staking, and status information

function getOracleInfo(address _oracle, bytes32 _jobId)
        external
        view
        returns (
            bool isActive,
            int256 qualityScore,
            int256 timelinessScore,
            uint256 callCount,
            bytes32 jobId,
            uint256 fee,
            uint256 stakeAmount,
            uint256 lockedUntil,
            bool blocked
        )

Parameters:

_oracle: Address of the oracle contract
_jobId: Job ID of the oracle instance

Returns:

isActive Whether the oracle is currently active and available for selection
qualityScore Current quality score based on response accuracy
timelinessScore Current timeliness score based on response speed
callCount Total number of times this oracle has been called
jobId The job ID (returned for convenience)
fee LINK fee required for using this oracle
stakeAmount Amount of VDKA tokens currently staked
lockedUntil Timestamp until which oracle is locked (0 if not locked)
blocked Whether oracle is blocked from selection due to poor performance

updateScores()¶

Update reputation scores for an oracle after evaluation completion

Technical: Called by approved aggregator contracts to reward/penalize oracle performance.

function updateScores(
        address _oracle, 
        bytes32 _jobId,
        int8 qualityChange,
        int8 timelinessChange
    ) external

Parameters:

_oracle: Address of the oracle contract
_jobId: Job ID of the oracle instance
qualityChange: Change to apply to quality score (positive = reward, negative = penalty)
timelinessChange: Change to apply to timeliness score (positive = reward, negative = penalty)

getSelectionScore()¶

Calculate the weighted selection score for an oracle

Technical: Combines reputation scores with fee weighting to determine selection probability.

function getSelectionScore(
        address _oracle,
        bytes32 _jobId,
        SelectionParams memory params
    ) public view returns (uint256)

Parameters:

_oracle: Address of the oracle contract
_jobId: Job ID of the oracle instance
params: Selection parameters including alpha, fees, and scaling factors

Returns:

Weighted selection score (higher = more likely to be selected)

selectOracles()¶

Select oracles for evaluation using reputation-weighted algorithm

Technical: Uses two-stage selection: eligibility filtering, optional shortlisting, then weighted selection.

function selectOracles(
        uint256 count,
        uint256 alpha,
        uint256 maxFee,
        uint256 estimatedBaseCost,
        uint256 maxFeeBasedScalingFactor,
        uint64 requestedClass
    ) external returns (OracleIdentity[] memory)

Parameters:

count: Number of oracles to select
alpha: Reputation weight factor (0-1000, where 1000 = 100% reputation-based)
maxFee: Maximum fee willing to pay per oracle (in LINK wei)
estimatedBaseCost: Estimated base cost for the evaluation
maxFeeBasedScalingFactor: Maximum scaling factor for fee-based selection weighting
requestedClass: Evaluation class required (oracles must support this class)

Returns:

Array of selected oracle identities

recordUsedOracles()¶

Record that specific oracles were used by an approved contract

Technical: Internal helper to perform weighted selection on a given shortlist (while avoiding duplicates if possible).

function recordUsedOracles(OracleIdentity[] calldata _oracleIdentities) external

Parameters:

_oracleIdentities: Array of oracle identities that were used for evaluation

setMaxScoreHistory()¶

Set the maximum number of historical score records to maintain per oracle

Technical: Controls memory usage and affects trend analysis for performance degradation detection

function setMaxScoreHistory(uint256 _maxScoreHistory) external onlyOwner

Parameters:

_maxScoreHistory: Maximum number of score records to keep (must be > 0)

setMaxScoreForSelection()¶

Set the maximum score used for arbiter random selection probabilities

Technical: Affects selection likelihood

function setMaxScoreForSelection(uint256 _maxScoreForSelection) external onlyOwner

Parameters:

_maxScoreForSelection: Maximum score used for selection (must be > 0)

setMinScoreForSelection()¶

Set the minimum score used for arbiter random selection probabilities

Technical: Affects selection likelihood

function setMinScoreForSelection(uint256 _minScoreForSelection) external onlyOwner

Parameters:

_minScoreForSelection: Maximum score used for selection (must be > 0)

getRecentScores()¶

Get the recent score history for an oracle

Technical: Returns historical performance data used for trend analysis

function getRecentScores(address _oracle, bytes32 _jobId)
        external
        view
        returns (ScoreRecord[] memory)

Parameters:

_oracle: Address of the oracle contract
_jobId: Job ID of the oracle instance

Returns:

Array of recent score records showing performance over time

setSlashAmount()¶

Set the amount of VDKA tokens to slash for poor performance

Technical: Amount slashed when oracles fall below performance thresholds

function setSlashAmount(uint256 _slashAmount) external onlyOwner

Parameters:

_slashAmount: Amount of VDKA tokens to slash (in wei)

setLockDuration()¶

Set the duration for which poorly performing oracles are locked

Technical: Locked oracles cannot be unregistered and may be blocked from selection

function setLockDuration(uint256 _lockDuration) external onlyOwner

Parameters:

_lockDuration: Lock duration in seconds

setSevereThreshold()¶

Set the severe performance threshold for slashing and blocking

Technical: Oracles below this threshold are slashed and blocked from selection

function setSevereThreshold(int256 _threshold) external onlyOwner

Parameters:

_threshold: Severe threshold value (negative number)

setMildThreshold()¶

Set the mild performance threshold for temporary locking

Technical: Oracles below this threshold are temporarily locked but not slashed

function setMildThreshold(int256 _threshold) external onlyOwner

Parameters:

_threshold: Mild threshold value (negative number)

setVerdiktaToken()¶

Update the VDKA token contract address used for staking

Technical: Changes the token contract used for oracle staking and slashing

function setVerdiktaToken(address _newVerdiktaToken) external onlyOwner

Parameters:

_newVerdiktaToken: Address of the new VDKA token contract

manualBlockOracle()¶

Manually block a specific oracle for a given duration

Technical: Only callable by the contract owner.

function manualBlockOracle(
        address _oracle,
        bytes32 _jobId,
        uint256 _duration
    ) external onlyOwner

Parameters:

_oracle: The oracle contract address
_jobId: The job-ID of that oracle instance
_duration: How long to block it,

resetAllReputations()¶

Hard-reset all reputation data.

function resetAllReputations() external onlyOwner

getRegisteredOraclesCount()¶

Get the total number of registered oracles

Technical: Returns the count of all oracle identities in the system

function getRegisteredOraclesCount() external view returns (uint256)

Returns:

Total number of registered oracle identities

getOracleClasses()¶

Get the evaluation classes supported by an oracle at a specific index

Technical: Check if an oracle supports a specific evaluation class

function getOracleClasses(uint256 index) public view returns (uint64[] memory)

Parameters:

classes: Array of classes supported by the oracle
requestedClass: The class being requested
index: Index in the registeredOracles array

Returns:

bool True if the oracle supports the requested class
Array of evaluation classes supported by the oracle

getOracleClassesByKey()¶

Get the evaluation classes supported by a specific oracle identity

Technical: Returns classes for oracle identified by address and job ID

function getOracleClassesByKey(address _oracle, bytes32 _jobId) public view returns (uint64[] memory)

Parameters:

_oracle: Address of the oracle contract
_jobId: Job ID of the oracle instance

Returns:

Array of evaluation classes supported by the oracle

setShortlistSize()¶

Set the maximum number of oracles to consider in second-stage selection

Technical: Controls the shortlist size for weighted selection when many oracles are available

function setShortlistSize(uint256 newSize) external onlyOwner

Parameters:

newSize: Maximum shortlist size (must be > 0)

approveContract()¶

Approve a contract to select and use oracles from the reputation system

Technical: Only approved contracts can call selectOracles, recordUsedOracles, and updateScores

function approveContract(address contractAddress) external onlyOwner

Parameters:

contractAddress: Address of the contract to approve (typically an aggregator contract)

isContractApproved()¶

Check if a contract is approved to use the reputation system

Technical: Lightweight getter for contract approval status

function isContractApproved(address contractAddress) external view returns (bool)

Parameters:

contractAddress: Address of the contract to check

Returns:

bool True if the contract is approved, false otherwise

removeContract()¶

Revoke a contract's approval to use oracles

Technical: Removes the contract's ability to select oracles and update scores

function removeContract(address contractAddress) external onlyOwner

Parameters:

contractAddress: Address of the contract to remove approval from

pushEntropy()¶

Update entropy buffer with new randomness from aggregator contracts

Technical: Called by approved aggregators to provide entropy for oracle selection randomization.

function pushEntropy(bytes16 e) external

Parameters:

e: New entropy value to add to the buffer

Events¶

OracleRegistered¶

Minimal interface to query an oracle contract's owner.

Data Structures¶

OracleIdentity¶

Manages oracle registration, reputation tracking, and selection for the Verdikta network

Technical: Central registry for oracle reputation management using composite keys (oracle address + jobID).

ScoreRecord¶

Historical score record for tracking oracle performance trends

Technical: Used to detect consistent performance degradation over time

OracleInfo¶

Complete information about a registered oracle

Technical: Stores all oracle metadata, scores, staking, and status information

ContractInfo¶

Contract approval and usage tracking data

Technical: Tracks which contracts are approved to use oracles and which oracles they've used

SelectionParams¶

Parameters for oracle selection algorithm

Technical: Groups selection parameters to reduce stack usage in complex functions

ReputationSingleton¶

ReputationSingleton

Author: Verdikta Team

Minimal single-oracle version of the reputation aggregator for fast evaluations

Technical Details: Simplified aggregator that selects one oracle for quick AI evaluations.

Public Functions¶

setAlpha()¶

Minimal single-oracle version of the reputation aggregator for fast evaluations

Technical: Simplified aggregator that selects one oracle for quick AI evaluations.

function setAlpha(uint256 _a) external onlyOwner

Parameters:

requestId: Unique request identifier ///
cids: Array of IPFS CIDs containing evidence to evaluate event RequestAIEvaluation(bytes32 indexed requestId, string[] cids); ///
requestId: The request identifier ///
likelihoods: Final likelihood scores from the oracle ///
justificationCID: IPFS CID containing the oracle's justification event EvaluationFulfilled(bytes32 indexed requestId, uint256[] likelihoods, string justificationCID); ///
requestId: The request identifier that failed event EvaluationFailed(bytes32 indexed requestId); ///
requestId: The request identifier ///
oracle: Address of the oracle receiving the bonus ///
amount: Amount of LINK tokens paid as bonus event BonusPaid(bytes32 indexed requestId, address oracle, uint256 amount); /
_a: Reputation weight factor (0-1000, where 1000 = 100% reputation-based)

getAlpha()¶

Get the current reputation weight factor

Technical: Returns the alpha value used for oracle selection

function getAlpha() external view returns (uint256)

Returns:

Current alpha value (0-1000)

setMaxOracleFee()¶

Set the maximum oracle fee for selection

Technical: Limits the maximum fee that can be paid to any oracle

function setMaxOracleFee(uint256 f) external onlyOwner

Parameters:

f: Maximum oracle fee in LINK wei

setBaseFeePct()¶

Set the base fee percentage for oracle selection

Technical: Base fee is used as minimum cost estimate (1-100%)

function setBaseFeePct(uint256 p) external onlyOwner

Parameters:

p: Base fee percentage (1-100)

setMaxFeeBasedScalingFactor()¶

Set the maximum fee-based scaling factor

Technical: Controls how much fee differences affect oracle selection

function setMaxFeeBasedScalingFactor(uint256 f) external onlyOwner

Parameters:

f: Maximum scaling factor (must be >= 1)

setChainlinkToken()¶

Set the Chainlink token address

Technical: Updates the LINK token contract used for payments

function setChainlinkToken(address a) external onlyOwner

Parameters:

a: Address of the LINK token contract

setReputationKeeper()¶

Set the ReputationKeeper contract address

Technical: Updates the reputation management contract used for oracle selection

function setReputationKeeper(address a) external onlyOwner

Parameters:

a: Address of the ReputationKeeper contract

setResponseTimeout()¶

Set the response timeout for evaluations

Technical: Timeout duration after which evaluations can be marked as failed

function setResponseTimeout(uint256 s) external onlyOwner

Parameters:

s: Timeout duration in seconds (30 seconds to 1 day)

maxTotalFee()¶

Calculate the maximum total LINK required including bonus payment

Technical: Returns 2x the effective fee (base fee + bonus payment)

function maxTotalFee(uint256 requested) public view returns (uint256)

Parameters:

requested: Requested maximum fee per oracle

Returns:

Maximum total LINK required for evaluation with bonus

getEstimatedBaseCost()¶

Get the estimated base cost for oracle evaluation

Technical: Calculates base cost as percentage of maximum oracle fee

function getEstimatedBaseCost() public view returns (uint256)

Returns:

Estimated base cost in LINK wei

requestAIEvaluationWithApproval()¶

Request AI evaluation with user-funded LINK payment (single oracle)

Technical: Main entry point for requesting single-oracle AI evaluation.

function requestAIEvaluationWithApproval(
        string[] calldata cids,
        string   calldata addendumText,
        uint256  _alpha,
        uint256  _maxOracleFee,
        uint256  _estimatedBaseCost,
        uint256  _maxFeeBasedScalingFactor,
        uint64   _requestedClass
    ) external nonReentrant returns (bytes32 requestId)

Parameters:

cids: Array of IPFS CIDs containing evidence/data to evaluate
addendumText: Additional text to append to the evaluation request
_alpha: Reputation weight factor for oracle selection (0-1000)
_maxOracleFee: Maximum fee per oracle in LINK wei
_estimatedBaseCost: Estimated base cost for evaluation
_maxFeeBasedScalingFactor: Maximum scaling factor for fee-based selection
_requestedClass: Oracle class/category requested for evaluation

Returns:

requestId Unique request ID for tracking the evaluation

fulfill()¶

Callback function called by the selected oracle with evaluation results

Technical: Stores results and automatically pays bonus to oracle upon completion

function fulfill(bytes32 requestId,
                     uint256[] calldata likelihoods,
                     string    calldata justificationCID)
        public
        recordChainlinkFulfillment(requestId)

Parameters:

requestId: The Chainlink request ID
likelihoods: Array of likelihood scores from the oracle
justificationCID: IPFS CID containing the oracle's justification

finalizeEvaluationTimeout()¶

Finalize an evaluation that has timed out

Technical: Can be called by anyone to finalize evaluations that have exceeded responseTimeoutSeconds

function finalizeEvaluationTimeout(bytes32 requestId) external nonReentrant

Parameters:

requestId: The request ID to finalize

isFailed()¶

Check if an evaluation has failed

Technical: Returns true if the evaluation timed out or failed for other reasons

function isFailed(bytes32 requestId) external view returns(bool)

Parameters:

requestId: The request ID to check

Returns:

bool True if the evaluation failed, false otherwise

getEvaluation()¶

Get the evaluation results for a completed request

Technical: Returns the likelihood scores and justification from the oracle

function getEvaluation(bytes32 id)
        external view
        returns (uint256[] memory l,string memory j,bool exists)

Parameters:

id: The request ID

Returns:

l Array of likelihood scores (0-100)
j IPFS CID containing the justification
exists Whether valid evaluation data exists for this request

getContractConfig()¶

Get contract configuration (legacy interface for compatibility)

Technical: Returns basic contract configuration for front-end compatibility

function getContractConfig()
        external view
        returns (address oracleAddr,address linkAddr,bytes32 jobId,uint256 fee)

Returns:

oracleAddr Placeholder oracle address (always returns zero)
linkAddr Address of the LINK token contract
jobId Placeholder job ID (always returns zero)
fee Placeholder fee (always returns zero)

withdrawLink()¶

Withdraw LINK tokens from the contract

Technical: Only callable by contract owner for emergency recovery

function withdrawLink(address payable to,uint256 amount) external onlyOwner

Parameters:

to: Address to receive the LINK tokens
amount: Amount of LINK tokens to withdraw (in wei)

Events¶

RequestAIEvaluation¶

Emitted when a new single-oracle AI evaluation request is created

EvaluationFulfilled¶

Emitted when an AI evaluation is completed successfully

EvaluationFailed¶

Emitted when an evaluation fails or times out

BonusPaid¶

Emitted when bonus payment is made to the oracle

Data Structures¶

ReqMeta¶

Minimal single-oracle version of the reputation aggregator for fast evaluations

Technical: Simplified aggregator that selects one oracle for quick AI evaluations.

SimpleContract¶

SimpleContract

Author: Verdikta Team

Basic single-oracle contract for development and testing purposes

Technical Details: Simplified oracle contract that works with a single pre-configured oracle.

Public Functions¶

setResponseTimeout()¶

Basic single-oracle contract for development and testing purposes

Technical: Simplified oracle contract that works with a single pre-configured oracle.

function setResponseTimeout(uint256 secs) external /* onlyOwner stub */

Parameters:

requestId: Unique request identifier ///
cids: Array of IPFS CIDs containing evidence to evaluate event RequestAIEvaluation (bytes32 indexed requestId, string[] cids); ///
requestId: The request identifier ///
likelihoods: Final likelihood scores from the oracle ///
justificationCID: IPFS CID containing the oracle's justification event FulfillAIEvaluation (bytes32 indexed requestId, uint256[] likelihoods, string justificationCID); ///
requestId: The request identifier ///
caller: Address of the fulfilling oracle ///
len: Number of likelihood scores received ///
justificationCID: IPFS CID of the justification event FulfillmentReceived (bytes32 indexed requestId, address caller, uint256 len, string justificationCID); ///
requestId: The request identifier that failed event EvaluationFailed (bytes32 indexed requestId); ///
requestId: The request identifier ///
oracle: Address of the oracle receiving the bonus ///
amount: Amount of LINK tokens paid as bonus event BonusPaid (bytes32 indexed requestId, address oracle, uint256 amount); /

requestAIEvaluationWithApproval()¶

Request AI evaluation with pre-configured oracle

Technical: Main entry point for requesting AI evaluation. User must approve 2x LINK (base + bonus).

function requestAIEvaluationWithApproval(
        string[] memory cids,
        string   memory addendumText,
        uint256, uint256, uint256, uint256,      /* ignored */
        uint64   _requestedClass
    ) external returns (bytes32 requestId)

Parameters:

cids: Array of IPFS CIDs containing evidence/data to evaluate
addendumText: Additional text to append to the evaluation request
_requestedClass: Oracle class required (must match contract's requiredClass)

Returns:

requestId Unique request ID for tracking the evaluation

fulfill()¶

Callback function called by the oracle with evaluation results

Technical: Stores results and automatically pays bonus to oracle upon completion

function fulfill(
        bytes32   _requestId,
        uint256[] calldata likelihoods,
        string    calldata justificationCID
    ) external recordChainlinkFulfillment(_requestId)

Parameters:

_requestId: The Chainlink request ID
likelihoods: Array of likelihood scores from the oracle
justificationCID: IPFS CID containing the oracle's justification

finalizeEvaluationTimeout()¶

Finalize an evaluation that has timed out

Technical: Can be called by anyone to finalize evaluations that have exceeded responseTimeoutSeconds

function finalizeEvaluationTimeout(bytes32 requestId) external

Parameters:

requestId: The request ID to finalize

isFailed()¶

Check if an evaluation has failed

Technical: Returns true if the evaluation timed out or failed for other reasons

function isFailed(bytes32 requestId) external view returns (bool)

Parameters:

requestId: The request ID to check

Returns:

bool True if the evaluation failed, false otherwise

maxTotalFee()¶

Calculate the maximum total LINK required including bonus payment

Technical: Returns 2x the base fee (base fee + bonus payment)

function maxTotalFee(uint256) external view returns (uint256)

Returns:

Maximum total LINK required for evaluation with bonus

getContractConfig()¶

Get contract configuration information

Technical: Returns oracle address, LINK token, job ID, and current fee

function getContractConfig()
        external
        view
        returns (address oracleAddr, address linkAddr, bytes32 jId, uint256 currentFee)

Returns:

oracleAddr Address of the configured oracle
linkAddr Address of the LINK token contract
jId Job ID for the oracle
currentFee Current fee amount in LINK wei

getEvaluation()¶

Get the evaluation results for a completed request

Technical: Returns the likelihood scores and justification from the oracle

function getEvaluation(bytes32 id)
        external
        view
        returns (uint256[] memory likelihoods, string memory cid, bool exists)

Parameters:

id: The request ID

Returns:

likelihoods Array of likelihood scores (0-100)
cid IPFS CID containing the justification
exists Whether valid evaluation data exists for this request

withdrawLink()¶

Withdraw LINK tokens from the contract

Technical: Emergency function for recovering LINK tokens (no access control in test contract)

function withdrawLink(address payable to, uint256 amount) external /* onlyOwner stub */

Parameters:

to: Address to receive the LINK tokens
amount: Amount of LINK tokens to withdraw (in wei)

Events¶

RequestAIEvaluation¶

Emitted when a new AI evaluation request is created

FulfillAIEvaluation¶

Emitted when an AI evaluation is completed successfully

FulfillmentReceived¶

Emitted when fulfillment data is received (debugging event)

EvaluationFailed¶

Emitted when an evaluation fails or times out

BonusPaid¶

Emitted when bonus payment is made to the oracle

Data Structures¶

ReqMeta¶

Basic single-oracle contract for development and testing purposes

Technical: Simplified oracle contract that works with a single pre-configured oracle.

Evaluation¶

Complete evaluation result from oracle

Technical: Stores the final evaluation data returned by the oracle

Integration¶

All contracts implement comprehensive NatSpec documentation. For detailed integration examples and usage patterns, see the individual contract documentation pages.

Network Information¶

Network: Base Sepolia (Testnet)
Documentation: Generated from source code NatSpec comments
Last Updated: 2025-09-06 12:27:07 UTC