Core components

ADCS Oracle Contracts

The ADCS Oracle contracts are the cornerstone of the ADCS platform, responsible for managing data requests and fulfillment between blockchain applications and AI providers. The system is built around the ADCSCoordinator contract, which handles oracle registration, request management, and data fulfillment.

Key Components

1. Oracle Management

The coordinator maintains a registry of authorized oracles with a maximum limit of 255 oracles. Key functions include:

function registerOracle(address oracle) external onlyOwner {
    if (sOracles.length >= MAX_ORACLES) {
        revert TooManyOracles();
    }
    // ... registration logic
}

function deregisterOracle(address oracle) external onlyOwner {
    // ... deregistration logic
}

2. Request Management

Each data request is uniquely identified and tracked using a commitment-based system:

function requestData(
    uint256 callbackGasLimit,
    ADCS.Request memory req
) external returns (uint256) {
    // Validate gas limit
    // Generate unique requestId
    // Store request commitment
    // Emit DataRequested event
}

3. Data Fulfillment

The contract supports multiple data types for fulfillment:

• uint256: Numerical values

• bool: Boolean values

• bytes32: Fixed-size byte arrays

• bytes: Dynamic byte arrays

• StringAndBool: Combined string and boolean values

Example of fulfillment function:

function fulfillDataRequestStringAndBool(
    uint256 requestId,
    StringAndBool memory response,
    RequestCommitment memory rc
) external {
    validateDataResponse(rc, requestId);
    // Process submission
    // Execute callback
    // Cleanup and emit event
}

Security Features

1. Request Validation: Each request is validated using a commitment scheme that ensures:

   • Oracle authentication

   • Request integrity

   • Single submission per oracle

   • Proper gas limit enforcement

2. Reentrancy Protection: The contract implements reentrancy guards to prevent malicious callbacks:

function fulfill(bytes memory resp, RequestCommitment memory rc) private returns (bool) {
    sConfig.reentrancyLock = true;
    (bool sent, ) = rc.sender.call(resp);
    sConfig.reentrancyLock = false;
    return sent;
}

1. Access Control: Only registered oracles can fulfill requests, and only the contract owner can manage oracle registration.

Event System

The contract emits detailed events for tracking and monitoring:

• OracleRegistered: When a new oracle is registered

• DataRequested: When a new request is created

• DataRequestFulfilled: When data is successfully delivered

• Various typed fulfillment events for different response types

Integration Points

Coordinator Contract Addresses

• Arbitrum: 0x07811b8B6151db734b8D1568918d3A62607879a7

• Base: 0x91c5d6e9F50ec656e7094df9fC035924AAA428bb

• Avalanche: 0x55Ee887dB181B41f69b3313065b1eD6BEE3336A1

• Berachain: 0x55Ee887dB181B41f69b3313065b1eD6BEE3336A1

• Bsc: 0xcb8BaEf34aDBB414fAB51EC6Ac1C0e4D0340e824

• OP: 0x55Ee887dB181B41f69b3313065b1eD6BEE3336A1

• Polygon: 0x55Ee887dB181B41f69b3313065b1eD6BEE3336A1

• Sonic: 0x55Ee887dB181B41f69b3313065b1eD6BEE3336A1

Request Flow

1. Consumer contracts make requests through the coordinator

2. Registered oracles monitor for DataRequested events

3. Oracles process requests and submit responses

4. The coordinator validates and forwards responses to consumers

5. Consumers receive data through their fulfillment functions

Error Handling

The contract includes comprehensive error handling:

• TooManyOracles: When oracle limit is reached

• UnregisteredOracleFulfillment: When unregistered oracle attempts fulfillment

• InvalidJobId: For malformed job identifiers

• OracleAlreadySubmitted: To prevent duplicate submissions

Providers

ADCS Providers are the actual LLM models and the entities that host them. A provider can be a single LLM model or a group of models that perform different tasks. This is the brain of the inference process where users can specify extra context and parameters via an Adaptor. Provider attributes include:

• Provider Name

• LLM Model Name or list of LLM models

• Provider Description

• Provider API Endpoint

• Provider API Documentation

• Example execution result

How to Become a Provider

Adaptors

ADCS Adaptors act as bridges between the ADCS Oracle contracts and the Providers. They are responsible for providing extra context and formatting the request and response data between the two.

Adaptors can be created by leveraging other adaptors and providers as context. This composability allows developers to build more complex and specialized adaptors by combining the functionality of existing components, enabling greater flexibility and reusability within the ADCS ecosystem.

Adaptor attributes include:

• Adaptor Name

• Adaptor ID

• Category

• Network

• Providers Used

• Output Type

• Integration Code Example

• Playground for Testing

  • Parameters Required for Execution

  • Thinking Process

  • Correct Output Format

Consumer Contracts

ADCS Consumer contracts request and process data from the ADCS platform. You can find example consumer contracts here

We currently support 4 data types for fulfillment:

1. Uint256

abstract contract ADCSConsumerFulfillUint256 is ADCSConsumerBase {
    function fulfillDataRequest(uint256 requestId, uint256 response) internal virtual;

    function rawFulfillDataRequest(
        uint256 requestId,
        uint256 response
    ) external verifyRawFulfillment {
        fulfillDataRequest(requestId, response);
    }
}

1. Bool

abstract contract ADCSConsumerFulfillBool is ADCSConsumerBase {
    function fulfillDataRequest(uint256 requestId, bool response) internal virtual;

    function rawFulfillDataRequest(uint256 requestId, bool response) external verifyRawFulfillment {
        fulfillDataRequest(requestId, response);
    }
}

1. Bytes32

abstract contract ADCSConsumerFulfillBytes32 is ADCSConsumerBase {
    function fulfillDataRequest(uint256 requestId, bytes32 response) internal virtual;

    function rawFulfillDataRequest(
        uint256 requestId,
        bytes32 response
    ) external verifyRawFulfillment {
        fulfillDataRequest(requestId, response);
    }
}

1. Bytes

abstract contract ADCSConsumerFulfillBytes is ADCSConsumerBase {
    function fulfillDataRequest(uint256 requestId, bytes memory response) internal virtual;

    function rawFulfillDataRequest(
        uint256 requestId,
        bytes memory response
    ) external verifyRawFulfillment {
        fulfillDataRequest(requestId, response);
    }
}

1. StringAndBool

abstract contract ADCSConsumerFulfillStringAndBool is ADCSConsumerBase {
    function fulfillDataRequest(uint256 requestId, StringAndBool memory response) internal virtual;

    function rawFulfillDataRequest(
        uint256 requestId,
        StringAndBool memory response
    ) external verifyRawFulfillment {
        fulfillDataRequest(requestId, response);
    }
}