# 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: ```solidity 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: ```solidity 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: ```solidity 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: ```solidity 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; } ``` 3. **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` * Mantle: `0x55Ee887dB181B41f69b3313065b1eD6BEE3336A1` * Sei: `0x55Ee887dB181B41f69b3313065b1eD6BEE3336A1` * Monad-testnet: `0x55Ee887dB181B41f69b3313065b1eD6BEE3336A1` * Taiko: `0x55Ee887dB181B41f69b3313065b1eD6BEE3336A1` * Celo: `0x55Ee887dB181B41f69b3313065b1eD6BEE3336A1` * Linea: `0x55Ee887dB181B41f69b3313065b1eD6BEE3336A1` * Injective-testnet: `0x55Ee887dB181B41f69b3313065b1eD6BEE3336A1` * Irys-testnet: `0x07bbC170f188a307161e7d0cD4Eb0CF0Cae39405` * Somnia-testnet: `0x07bbC170f188a307161e7d0cD4Eb0CF0Cae39405` * Soneium: `0x07bbC170f188a307161e7d0cD4Eb0CF0Cae39405` * Fraxtal: `0x7eb5b9b83E1aA1AbafE7243A79910FC9AEdD6Ff2` #### 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](https://github.com/Rivalz-ai/ADCS-core/tree/main/contracts/src/mock) **We currently support 4 data types for fulfillment:** 1. **Uint256** ```solidity abstract contract ADCSConsumerFulfillUint256 is ADCSConsumerBase { function fulfillDataRequest(uint256 requestId, uint256 response) internal virtual; function rawFulfillDataRequest( uint256 requestId, uint256 response ) external verifyRawFulfillment { fulfillDataRequest(requestId, response); } } ``` 2. **Bool** ```solidity abstract contract ADCSConsumerFulfillBool is ADCSConsumerBase { function fulfillDataRequest(uint256 requestId, bool response) internal virtual; function rawFulfillDataRequest(uint256 requestId, bool response) external verifyRawFulfillment { fulfillDataRequest(requestId, response); } } ``` 3. **Bytes32** ```solidity abstract contract ADCSConsumerFulfillBytes32 is ADCSConsumerBase { function fulfillDataRequest(uint256 requestId, bytes32 response) internal virtual; function rawFulfillDataRequest( uint256 requestId, bytes32 response ) external verifyRawFulfillment { fulfillDataRequest(requestId, response); } } ``` 4. **Bytes** ```solidity 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); } } ``` 5. **StringAndBool** ```solidity 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); } } ``` --- # Agent Instructions: Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter: ``` GET https://docs.rivalz.ai/adcs-ai-oracles/core-components.md?ask= ``` The question should be specific, self-contained, and written in natural language. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.