Skip to main content
The ChaosAgent system is a middleware between ChaosRiskOracle and the protocol where the update from ChaosRiskOracle must be injected.
The complete ChaosAgent implementation is available on GitHub. You can explore the full codebase, contribute, or deploy your own agents.

​
Architecture

Workflow

Workflow

​
Chaos Agent Key Components

The ChaosAgentHub acts as an orchestrator for multiple agents and is a single big monolith contract that holds all the common logic:
  • Querying from RiskOracle.
  • Performing access control checks.
  • Running GenericValidation, which includes:
    • Checking circuit breaker status.
    • Validating if the update has expired.
    • Ensuring the update hasn’t already been executed.
    • Verifying that the minimum delay since the last execution has passed.
For agentValidation—-which handles protocol-specific validation and injection, the ChaosAgentHub performs an external call to the configured agent contract.
The ChaosAgentHub serves as a central hub for multiple agents, each with protocol-specific configurations. It holds all agent configurations with access control for agent admins to update them. For example, you might have one agent for supplyCapUpdate, another for slopeOneUpdate, and so on. It provides two main methods to support both push- and pull-based architectures:
  • check(): Verifies if an agent update can be injected
  • execute(): Injects or pushes the update from the ChaosRiskOracle into the protocol

​
Inheritance Structure

The diagram below illustrates the inheritance and dependency relationships of the ChaosAgentHub:

​
Agent Features

  • Purpose-specific logic: Each agent is an independent smart contract that encapsulates logic for a single updateType like supplyCap across multiple markets. This separation ensures targeted and maintainable validation logic per protocol requirement.
  • Standardized interface: All agents implement a shared interface with two core methods: validate() and inject(). These methods are invoked by the ChaosAgentHub to perform checks such as RangeValidation and to inject updates into the underlying protocol.
  • Dynamic market support: The getMarkets() method enables agents to support dynamic market lists, which is especially useful when markets cannot be statically defined in the ChaosAgentHub.
  • Lightweight and modular: Agents are intentionally kept lightweight, because they are frequently deployed and scoped to a specific updateType. This modular design promotes scalability and simplifies upgrades.

​
Common Modules

The common modules are contracts that will be deployed once and used by multiple agents across hubs. For example, a common module is:
  • RangeValidationModule: Independent immutable contract that contains logic to validate range and also holds range configurations with access contract for different chaos hubs and agents. The range validation module can be used inside your validate() method on your agent contract to validate param ranges. The configuration can be set on the range validation module directly for your agent.
You can specify both the default range configuration, which will be common to all markets, and also the configuration specific to a market.
If the configuration does not exist for a specific market, then the module will fall back to using the default configuration for all the markets.
After you have registered your agent on the ChaosAgentHub, you can call setRangeConfigByMarket() and setDefaultRangeConfig() methods to set range configuration for your agent.

​
Access Control

The ChaosAgentHub system implements a hierarchical permissions model to ensure secure and controlled access to different functionalities.

​
Primary Actors

Primary actors are core entities with direct control over the chaos agent system. They manage agent behavior, update configurations, and have the authority to influence how risk parameters are validated and applied across protocols.

​
ChaosAgentHub owner

The highest privileged entity in the system with complete administrative control over an ChaosAgentHub instance.
  • Capabilities:
    • Register new agents
    • Transfer ownership
    • Set global configurations, for example, maxBatchSize
    • Assign agent admins
    • Update agent contract addresses
    • Perform all actions available to agent admins
    • Set range configs for all agents belonging to the hub on RangeValidationModule contract
  • Trust assumptions:
    • Complete trust required—has system-wide control and can modify any aspect of the hub configuration
    • Can potentially disrupt the entire system by registering malicious agents or modifying critical parameters
    • Expected to be a trusted multi-sig or governance of the protocol

​
ProxyAdmin owner

Entity with the power to upgrade the ChaosAgentHub contract implementation.
  • Capabilities:
    • Upgrade the ChaosAgentHub proxy to point to any implementation
    • Change the entire logic of the system through upgrades
    • Transfer ProxyAdmin ownership
  • Trust assumptions:
    • Maximum trust required—can completely replace system logic
    • If compromised, the entire system can be compromised regardless of other security measures
    • Ideally, it should be the same entity as the ChaosAgentHub Owner or have equivalent security

​
Agent Admin

Administrator with control over specific agent configurations, but not the entire hub.
  • Capabilities:
    • Enable/disable agents
    • Manage the permissioned senders list
    • Configure allowed/restricted markets
    • Set expiration periods and minimum delays
    • Configure agent contexts
    • Set range configs for only the agent it is an admin for on RangeValidationModule contract
  • Trust assumptions:
    • Significant trust is required for their specific agents
    • Cannot register new agents or modify global hub settings

​
Permissioned Senders

Entities authorized to trigger updates for specific agents.
  • Capabilities:
    • Call execute() for agents they’re specifically permissioned for
    • No administrative capabilities
  • Trust assumptions:
    • Limited trust required—cannot modify system configurations
    • Can only trigger updates that have passed validation
    • May be automated services, bots, or keepers

​
Secondary Actors

Secondary actors play supporting roles in the Chaos agent system, contributing to the secure and effective delivery of risk parameter updates.

​
ChaosRiskOracle (Chaos Labs)

External data provider that supplies risk parameter updates.
  • Capabilities: Produce risk parameter updates of various types
  • Trust assumptions:
    • Significant trust is required as the source of risk parameters.
    • To minimise the trust given to ChaosRiskOracle, we have strict validation on the agent side with range validation, minimum delays, and so on.
    • Expected to provide accurate, timely, and well-considered risk updates
    • Incorrect data could potentially impact protocol risk params

​
Agent Contract Deployers or Developers

Responsible for creating and deploying the agent-specific logic.
  • Capabilities:
    • Implement custom validation and injection logic
    • Define protocol-specific checks
  • Trust assumptions:
    • High trust required—designs critical protocol interaction logic
    • Errors in implementation could lead to system vulnerabilities
    • Expected to be the protocol’s core development team or trusted contractors

​
Target Protocol

The protocol receives the risk parameter updates.
  • Capabilities:
    • Implement access control for parameter updates
    • Enforce protocol-specific logic on parameter changes
  • Trust assumptions:
    • Must grant appropriate permissions to agent contracts
    • Must have proper access control on its end when invoked by the agent contract

​
Public Users (when isAgentPermissioned: false)

Anyone who can trigger permissionless updates.
  • Capabilities:
    • Call execute() for non-permissioned agents
    • No administrative capabilities
  • Trust assumptions:
    • No trust required—cannot bypass system validations
    • Can only trigger updates that would pass all validation checks
    • Might include keepers, automated services, or protocol users

​
Key Access Control Points

  • Agent registration: Only the hub owner can register new agents via registerAgent() with the onlyOwner modifier.
  • Agent configuration: Only the agent admin and hub owner can modify agent settings through the onlyOwnerOrAgentAdmin modifier.
  • Update execution: Controlled by the isAgentPermissioned flag and permissioned senders list, checked during execute().
  • Protocol interaction: Permissions for protocol updates are granted to the agent contract: agentAddress, not the hub.

​
Frequently Asked Questions

To upgrade your protocol logic:
  1. Deploy new agent contracts that reflect the protocol changes.
  2. Revoke the roles from the old agent contracts.
  3. Assign the roles to the new agent contracts.
  4. Call setAgentAddress() on the Hub for each relevant agent.
If the new version contains no breaking changes:
  1. Deploy the new Hub implementation.
  2. Use the ProxyAdmin for your existing Hub proxy to point to the new implementation.
  3. Existing agents will remain compatible.
  • If the module address is immutable in the agent contract:
    Redeploy the agent contract and use setAgentAddress() to register the new one.
  • If the module address is stored in AgentContext:
    Encode the new module address into bytes, and update it via setAgentContext()—no need to redeploy.
Each agent is bound to one updateType and multiple markets.
To handle multiple updateTypes, create multiple agents on the hub.
You can reuse the same agent contract logic by abstracting updateType handling internally.
Yes, expired updates can block downstream consumption.
To resolve this:
  • The agent admin can extend the allowed update window using the setExpirationPeriod() setter.
The RangeValidationModule supports two configurations:
  1. Default config for all markets via setDefaultRangeConfig()
  2. Per-market override via setRangeConfigByMarket()
If no override is set, the default config is applied.
⌘I