Contract Configuration

To integrate Chaos Labs’ dynamic risk parameters into your protocol, you’ll need to coordinate with the Chaos labs team to deploy the RiskOracle contract. This smart contract acts as the on-chain source of truth for validated risk parameters such as caps, thresholds, and limits. Each oracle contract is deployed for each client’s specific needs.

Risk oracle flow

Step 1: Align on parameter requirements

Align with Chaos Labs on the parameters that should be automated. This should include:

Name of parameter: A string label such as maxOpenInterestForLongs. This is used for updateType.
Values: The expected value and type. Chaos Labs sends this encoded as bytes.
Market: The market that is the parameter target, which is also encoded as bytes or an address.
Blockchain: The chain where the RiskOracle contract is deployed.
Additional data: Any optional metadata like source, confidence score, and strategy used.

These inputs help ensure the oracle updates are processed correctly and contextually in your protocol.

Step 2: Understand the contract interface

Understanding the contract ABI is essential for secure and reliable integration. Each function and data structure defines how your protocol communicates with the RiskOracle, ensuring that updates are posted, tracked, and consumed accurately. For a detailed look at the implementation, the RiskOracle contract is open-sourced and available on GitHub.

Querying Oracle Data

These functions expose the current and historical state of risk parameter updates for external queries and verification.

Function name	Parameters	Description
`getLatestUpdateByParameterAndMarket`	`updateType` (string), `market` (address)	Returns the most recent update for a given parameter and market.
`getUpdateById`	`updateId` (uint256)	Returns a specific update by its ID.
`getAllUpdateTypes`	None	Returns all currently allowed update types, such as `maxLeverage`.
`isAuthorized`	`address` (address)	Checks if a given address is authorized to post updates.

Struct: `RiskParameterUpdate`

This struct defines the data model for each parameter update, capturing key metadata and context for auditing and integration.

Attribute	Data type	Description
`timestamp`	uint256	The block timestamp when the update was recorded.
`newValue`	bytes	The new value of the risk parameter is stored in a bytes format to support various data typologies and complexity.
`previousValue`	bytes	The parameter value before the current update, enabling historical comparison and possible rollback scenarios.
`updateType`	string	A categorization of the update, allowing different types of updates such as `maxOpenInterestForLongs`.
`updateId`	uint256	A unique identifier for the specific update.
`market`	address	An identifier for the market in which the parameter update applies.
`referenceId`	string	An external or internal reference ID linking to additional documentation, a dashboard, REST API, or data related to the parameter update.
`additionalData`	bytes	Any additional data for the update.

Events: `ParameterUpdated`

Emitted after every successful update.

Parameter	Type	Description
`referenceId`	string	Traceable identifier
`newValue`	bytes	Updated value
`previousValue`	bytes	Old value
`timestamp`	uint256	Time of update
`updateType`	string (indexed)	What was updated
`updateId`	uint256 (indexed)	Unique update ID
`market`	address (indexed)	Affected market
`additionalData`	bytes	Optional

Step 3: Integrate the Oracle

Once the RiskOracle is deployed and being updated by authorized senders, you’ll want to consume those updates inside your own contracts. This section outlines a secure and flexible consumption pattern using interface-based access.

Objective

Consume parameter updates from RiskOracle and use them to dynamically adjust logic in your own smart contracts, such as update caps, fees, interest rates.

Integration Pattern

This pattern uses two interfaces:

IRiskOracle: Use this interface to fetch updates by an ID.
IAnotherContract: A mock contract you wish to update using values from the oracle.

The RiskOracleConsumer contract fetches the update, decodes the values, and forwards them into another contract.

The following code is for illustrative purposes only, has not been audited, and should not be used in production without thorough testing.

Solidity

// SPDX-License-Identifier: MIT
pragma solidity ^0.8.25;

// Oracle interface exposing the `getUpdateById()` function
interface IRiskOracle {
    struct RiskParameterUpdate {
        uint256 timestamp;
        bytes newValue;
        string referenceId;
        bytes previousValue;
        string updateType;
        uint256 updateId;
        address market;
        bytes additionalData;
    }

    function getUpdateById(uint256 updateId) external view returns (RiskParameterUpdate memory);
}

// Mock contract that will be updated
interface IAnotherContract {
    function updateParameter(uint256 newValue, address market) external;
}

contract RiskOracleConsumer {
    IRiskOracle public riskOracle;
    IAnotherContract public anotherContract;

    constructor(address _riskOracleAddress, address _anotherContractAddress) {
        riskOracle = IRiskOracle(_riskOracleAddress);
        anotherContract = IAnotherContract(_anotherContractAddress);
    }

    /**
     * @notice Requests an update by ID and decodes the newValue and market parameters.
     * @param updateId The ID of the update to request.
     * @return Decoded newValue as uint256 and market as address
     */
    function requestAndDecodeUpdate(uint256 updateId) public view returns (uint256, address) {
        IRiskOracle.RiskParameterUpdate memory update = riskOracle.getUpdateById(updateId);
        uint256 decodedValue = _decodeNewValue(update.newValue);
        address decodedMarket = _decodeMarket(update.market);
        return (decodedValue, decodedMarket);
    }

    /**
     * @notice Uses values decoded from Risk Oracle to interact with another contract.
     * @param updateId The ID of the update to request and use.
     */
    function updateAnotherContract(uint256 updateId) external {
        (uint256 newValue, address market) = requestAndDecodeUpdate(updateId);
        anotherContract.updateParameter(newValue, market);
    }

    /**
     * @dev Decodes a bytes value to uint256 using abi.decode.
     * @param data The bytes value to decode.
     * @return The decoded uint256 value.
     */
    function _decodeNewValue(bytes memory data) internal pure returns (uint256) {
        return abi.decode(data, (uint256));
    }

    /**
     * @dev Decodes a bytes value to address using abi.decode.
     * @param data The bytes value to decode.
     * @return The decoded address value.
     */
    function _decodeMarket(bytes memory data) internal pure returns (address) {
        return abi.decode(data, (address));
    }
}

Breakdown Function

These helper functions handle decoding and forwarding of update data, enabling seamless integration with other contracts.

Function	Roles or description
`requestAndDecodeUpdate()`	Pulls the update by ID and decodes `newValue` and `market`.
`updateAnotherContract()`	Uses the decoded values to interact with another contract.
`_decodeNewValue()`	Converts `bytes` → `uint256`. Assumes `newValue` is a `uint256`.
`_decodeMarket()`	Converts `bytes` → `address`. Assumes `market` is encoded that way.

This consumption pattern lets you:

Safely integrate dynamic risk parameters.
Offload value validation and signing to Chaos Labs.
Keep your contracts modular and upgrade-friendly.

Step 4: Go-live checklist

Before deploying your integration in production, follow these implementation and deployment steps to ensure secure and reliable operation of your RiskOracle setup.

Part A: Implementation Steps

Get your RiskOracle contract address
- Obtain the specific RiskOracle contract address from the Chaos Labs team
- This contract will be customized for your protocol’s needs
- Verify the contract is deployed on your target network

Coordinate message format

Work with Chaos Labs to define the exact format of the parameter updates
For example, if implementing a supply cap:

Solidity

// Example parameter format for a supply cap
struct SupplyCapUpdate {
    uint256 maxSupply;
    address asset;
    uint256 timestamp;
}

Setup your consumer contract

Implement the IRiskOracle interface in your contract
Define the parameter struct matching the agreed format

Solidity

contract YourContract {
    IRiskOracle public riskOracle;
    
    constructor(address _riskOracleAddress) {
        riskOracle = IRiskOracle(_riskOracleAddress);
    }
    
    function getLatestSupplyCap(address market) public view returns (uint256) {
        RiskParameterUpdate memory update = riskOracle.getLatestUpdateByParameterAndMarket("supplyCap", market);
        return abi.decode(update.newValue, (uint256));
    }
}

Implement update retrieval
- Add functions to fetch and decode the latest parameter values
- Include proper error handling for cases when updates aren’t available
- Test the integration with sample data from Chaos Labs

Part B: Deployment and Monitoring

Set up event monitoring

Implement monitoring for the ParameterUpdated event
This allows your protocol or off-chain services like (Gelato) to react to new risk parameter updates in real time
Example monitoring setup:

Javascript

riskOracle.on("ParameterUpdated", (referenceId, newValue, previousValue, timestamp, updateType, updateId, market) => {
    if (updateType === "supplyCap") {
        // Handle supply cap update
        updateProtocolLimits(market, newValue);
    }
});

Verify integration
- Test the complete flow with actual parameter updates
- Verify parameter values are correctly decoded and applied
- Monitor the first few updates in production closely
Document integration details
- Record all parameter types and their encoding formats
- Document the update frequency and monitoring setup
- Maintain contact information for the Chaos Labs team

Remember to implement proper access controls and validation checks in your consumer contract to ensure only authorized updates are processed.

Getting started

Oracles

Integration Guides

Step 1: Align on parameter requirements

Step 2: Understand the contract interface

Querying Oracle Data

Struct: `RiskParameterUpdate`

Events: `ParameterUpdated`

Step 3: Integrate the Oracle

Objective

Integration Pattern

Breakdown Function

Step 4: Go-live checklist

Part A: Implementation Steps

Part B: Deployment and Monitoring

Getting started

Oracles

Integration Guides

​Step 1: Align on parameter requirements

​Step 2: Understand the contract interface

​Querying Oracle Data

​Struct: RiskParameterUpdate

​Events: ParameterUpdated

​Step 3: Integrate the Oracle

​Objective

​Integration Pattern

​Breakdown Function

​Step 4: Go-live checklist

​Part A: Implementation Steps

​Part B: Deployment and Monitoring

Step 1: Align on parameter requirements

Step 2: Understand the contract interface

Querying Oracle Data

Struct: `RiskParameterUpdate`

Events: `ParameterUpdated`

Step 3: Integrate the Oracle

Objective

Integration Pattern

Breakdown Function

Step 4: Go-live checklist

Part A: Implementation Steps

Part B: Deployment and Monitoring