Getting Started

XKeep3r is a public good for on-chain automation. It should be very easy to create a job which can be run both by Keep3r, Gelato, Autonolas, or any other keeper out there. We have also deployed compatible relays to ensure seamless integration, but xKeeper is designed to work with any keeper of your choice, providing you with the flexibility to select the one that best suits your needs.

Repositories

• Core Contracts

Deployments

Mainnet

Sepolia

• AutomationVaultFactory: 0xFfA518751B1489BA60f30274F86C5B2fa67a568b
• AutomationVault: 0x0e35Eae5eA725eB86415e99308a460888908753F
• GelatoRelay: 0x0e35eae5ea725eb86415e99308a460888908753f
• OpenRelay: 0x5f1e19C9748e99ec382F62F2D0988bB83ea2DF9E
• Keep3rRelay: 0x9D11bB1Eb9EF71a62285cc4DDA777b3EbEb80F71
• Keep3rBondedRelay: 0x8422F45a763a2b608D8a748D52886ab825329d95
• XKeeperMetadata: 0x4208102475d40bE64E8610BA7C87A7F7b961e35d

Licensing

The primary license for xKeeper is AGPL-3.0

Contributors

XKeeper was built with ❤️ by Wonderland.

Wonderland is a team of top Web3 researchers, developers, and operators who believe that the future needs to be open-source, permissionless, and decentralized.

DeFi sucks, but Wonderland is here to make it better.

XKeeper

Why XKeeper?

XKeeper offers a powerful solution for on-chain automation. Here's why you should consider using it:

• Simplicity: With the assistance of our relays and vault, you'll be able to easily manage automation for your contracts, and the payment process will be smoother than ever before.

• Versatility: XKeeper is built to be compatible with various keeper services, including Keep3r, Gelato, Autonolas, and others. You have the freedom to choose the keeper that best fits your requirements.

• Public Good: We're committed to contributing to the blockchain community by offering XKeeper as an open and free resource, promoting automation and efficiency across the ecosystem.

Join us in simplifying on-chain automation with XKeeper.

Tutorial: Deployment and Configuration of Automation Vault

This guide provide all information needed to deploy and configure an AutomationVault. You can do it easily using " XKEPPER WEBSITE".

Step 1: Deployment of the Automation Vault

Deploy Automation Vault:

• Use the AutomationVaultFactory contract to deploy a new instance of AutomationVault. Make sure to provide the owner parameter. The native token will be taken directly from the connected network.

Step 2: Adding Balance to the Automation Vault

Transfer Funds to the Vault:

• Transfer the necessary funds to the automation vault to cover the costs associated with task execution. This could include Native token as ETH in Ethereum network or ERC-20 tokens, depending on the protocol requirements.

Step 3: Approval of Callers and Relays for a specific relay

Add relay:

• Use functions in the automation vault to approve specific relay. This might include relays such as Keep3rRelay, Keep3rBondedRelay, GelatoRelay, or OpenRelay, depending on the protocol's needs. The params needed to approve it will be:

a) The relay address

b) The callers who will be authorized to call the selected relay.

c) The Job Data which contains the job and selectors. To enable task executions, you need to approve specific jobs that the automation vault will interact with and will be allowed. Additionally, you need to approve specific function selectors for each approved job. This ensures that only designated functions within the approved jobs can be executed.

Step 4: Tracking and Monitoring

Tracking and Monitoring:

• Monitor task executions through emitted events and other relevant metrics.

With these steps, you should have a solid guide for a protocol to deploy its automation vault, configure necessary permissions and relays, add balance, and execute automated tasks.

Core Contracts

The core contracts of the XKeeper project are the backbone of the framework. They can be used to generate new vaults, manage balances and approve and revoke permissions for callers and relays.

Core Contracts

• The AutomationVault contract manages on-chain job execution with relays, streamlining payment and serving as a core component in user-friendly on-chain automation.

• The AutomationVaultFactory contract is responsible for deploying new instances of automation vaults.

For more detailed information about each contract, please refer to the respective documentation pages.

For more technical details about the interfaces of the core contracts, please refer to the Interfaces section in the technical documentation.

⚠️ Please note that the code has not been audited yet, so use it with caution.

Automation Vault

The AutomationVault contract is designed to facilitate the management of job execution with various relays and the payment of these relays for their services. The contract operates as a core component in the realm of on-chain automation. It provides a robust and user-friendly solution for defining and executing tasks while ensuring that payments are handled in a more straightforward manner.

Key Features

• Relay and Job Management: The AutomationVault contract allows users to manage approved relays and jobs efficiently. It maintains a list of approved relays and jobs, providing control over who can perform specific tasks.

• Simplified Payment Handling: Payment management has been simplified, allowing payments to be made in a more user-friendly manner. It supports both Ether (ETH) and ERC-20 tokens, ensuring that fees for job execution are processed seamlessly.

• Ownership Control: The contract incorporates ownership management to ensure control over its functions. The owner has the authority to approve or revoke relays, callers, and selectors.

• Multichain Support: The xKeeper core allows to configure the automation vaults for several chains. The native token is configurable for any automation vault.

• Flexibility: Users have the freedom to add or remove relays and select specific functions to be executed by jobs, granting them greater control over their automation processes.

Automation Vault Factory

The AutomationVaultFactory contract is specifically designed to handle the deployment and management of automation vaults within the on-chain automation ecosystem. As a factory, it plays a crucial role in streamlining the creation of new automation vaults, each serving as a dedicated entity for job execution, relay management, and payment processing.

Key Features

• Efficient Deployment: The primary function of the factory is to efficiently deploy new instances of automation vaults. This allows users to manage automation tasks, associated relays and handle balances.

• Automation Vaults Listing: Enables users to retrieve a list of deployed automation vaults, allowing for efficient tracking and monitoring.

Relays Contracts

Relay contracts in the XKeeper project play a key role in facilitating automated task executions from different networks. Each of these contracts provides specialized solutions to optimize task execution and manage the associated payments.

Relays Contracts

• The Keep3rRelay: Orchestrates and executes tasks efficiently, ensuring a harmonious automation process within the Keep3r network.

• The Keep3rBondedRelay: Introduces dynamic bonding requirements for automation vaults, enhancing security by validating tasks with bonded keepers.

• The GelatoRelay: Acts as a centralized hub for managing and executing tasks from the Gelato network, streamlining automation processes.

• The OpenRelay: Manages and facilitates the execution of tasks from various bots, ensuring efficient automation processes and fee payments.

For more detailed information about each contract, please refer to the respective documentation pages.

For more technical details about the interfaces of the relays contracts, please refer to the Interfaces section in the technical documentation.

⚠️ Please note that the code has not been audited yet, so use it with caution.

Keep3r Relay

The Keep3rRelay is meticulously crafted to orchestrate and streamline task executions from the Keep3r network, offering a cohesive solution for efficient automation processes and fee payments.

Key Features

• Task Coordination: The contract seamlessly coordinates task executions with an AutomationVault, ensuring a harmonious and streamlined automation process.

• Keeper Authorization: Validation mechanisms guarantee that only authorized keepers within the Keep3r network can initiate and execute tasks, enhancing security and control.

• Optimized Execution Array: The contract intelligently creates an array of executions, encompassing crucial steps such as keeper validation, injected execution data, and issuance of payments upon successful task completion.

• Event Transparency: Upon successful execution, the contract emits the AutomationVaultExecuted event, providing transparent insights into executed tasks and relay activities.

Keep3r Network

The Keep3rRelay combines task coordination, keeper validation, and event transparency to deliver a robust solution for streamlined automation processes within the Keep3r network. This design prioritizes efficiency, security, and user-friendly task execution.

Keep3r Bonded Relay

The Keep3rBondedRelay contract efficiently manages executions originating from the Keep3r network when the job is bonded. This contract introduces bonding requirements for automation vaults, ensuring task executions are performed by legitimate bonded keepers.

Key Features

• Dynamic Bonding Requirements: The contract introduces flexible bonding requirements for automation vaults. Vault owners can set specific bonding parameters, such as the required bond, minimum bond, earned rewards, and age, ensuring customizable security measures.

• Bonding Requirement Configuration: Through the setAutomationVaultRequirements function, automation vault owners can dynamically configure bonding requirements. This feature grants control over the security measures necessary for task execution.

• Task Execution with Bonded Keepers: The contract efficiently executes tasks with bonded keepers, validating their bonding status based on the configured requirements. This ensures that only legitimate bonded keepers can initiate and complete tasks.

• Event Emission: Upon successful execution, the contract emits the AutomationVaultExecuted event. This event provides transparency into executed tasks, including details on the associated automation vault and the executed data.

Keep3r Network

The Keep3rBondedRelay contract introduces a novel approach by incorporating dynamic bonding requirements for automation vaults. This design enhances security and control, allowing vault owners to customize bonding parameters and ensuring task executions are carried out by validated bonded keepers.

Gelato Relay

The GelatoRelay contract, serves as a central hub for managing and executing tasks originating from the Gelato network, contributing to seamless automation processes and fee payments.

Key Features

• Task Execution Coordination: The contract, in collaboration with the Gelato network, coordinates and executes tasks efficiently, ensuring a smooth and reliable automation process.

• Automation Vault Interaction: This interaction centralizes multiple tasks within a single relay, streamlining the management of various tasks and their associated payments in a single function call. This feature enhances efficiency and reduces the complexity of task management, allowing users to handle multiple tasks simultaneously.

• Event Transparency: Upon successful execution, the contract emits the AutomationVaultExecuted event, providing transparent insights into executed tasks and relay activities.

Gelato Network

The GelatoRelay contract seamlessly integrates with the Gelato network, offering a robust solution for the execution of automated tasks while maintaining transparency in fee calculations and execution events.

Open Relay

The OpenRelay is designed to manage and facilitate the execution of tasks coming from various bots, ensuring efficient automation processes and fee payments.

Key Features

• Gas Management: The contract employs gas management to optimize transaction costs. It calculates the gas spent and provides a gas bonus to ensure that the execution is efficient and cost-effective.

• Automated Fee Calculation: The contract automatically calculates and handles fees for task execution. It uses gas metrics to determine the appropriate payment to be made to the automation vault.

• Seamless Task Execution: The contract allows the execution of tasks within an automation vault. It ensures that all tasks are carried out smoothly, and fees are promptly paid to the designated fee recipient.

• Event Transparency: Upon successful execution, the contract emits the AutomationVaultExecuted event, providing transparent insights into executed tasks and relay activities.

Gas Metrics

• GAS_BONUS: 53,000
• GAS_MULTIPLIER: 12,000
• BASE: 10,000

These gas metrics play a vital role in paying the caller for the work performed.

Peripheral Contracts

Peripheral contracts serve as supportive components that extend the capabilities of the core system. Among these, the XKeeperMetadata contract stands out as a crucial peripheral contract, specifically designed for managing and streamlining metadata associated with automation vaults.

Peripheral Contracts

• The XKeeperMetadata: Manages and organizes metadata for automation vaults within the system, ensuring accurate and secure data handling while enhancing the overall efficiency of metadata management processes.

For more detailed information about each contract, please refer to the respective documentation pages.

For more technical details about the interfaces of the relays contracts, please refer to the Interfaces section in the technical documentation.

⚠️ Please note that the code has not been audited yet, so use it with caution.

XKeeperMetadata

The XKeeperMetadata contract is a pivotal component in managing the metadata associated with automation vaults. It offers a structured and efficient way to handle metadata operations, providing essential features and interactions for users. Automation vaults owners can define all information related with their protocols to provide information about how to work their jobs.

Key Features

• Metadata Management: The contract is primarily focused on handling the metadata of automation vaults, providing a structured and consistent approach to managing information.

• Robust Querying: Users can query metadata for an array of automation vaults simultaneously, ensuring efficient data retrieval and management.

• Secure Metadata Modification: The contract ensures that only the owner of an automation vault can modify its metadata, maintaining the integrity and security of the data.

Contents

• core
• for-test
• periphery
• relays

Contents

• IAutomationVault
• IAutomationVaultFactory

IAutomationVault

Git Source

Functions

owner

Returns the owner address

function owner() external view returns (address _owner);

Returns

NATIVE_TOKEN

Returns the address of the native token

function NATIVE_TOKEN() external view returns (address _nativeToken);

Returns

pendingOwner

Returns the pending owner address

function pendingOwner() external view returns (address _pendingOwner);

Returns

getRelayData

Returns the approved relay callers and selectors for a specific relay and job

function getRelayData(address _relay)
  external
  returns (address[] memory _callers, IAutomationVault.JobData[] memory _jobsData);

Parameters

Returns

relays

Returns the approved relays

function relays() external view returns (address[] memory _listRelays);

Returns

changeOwner

Propose a new owner for the contract

The new owner will need to accept the ownership before it is transferred

function changeOwner(address _pendingOwner) external;

Parameters

acceptOwner

Accepts the ownership of the contract

function acceptOwner() external;

withdrawFunds

Withdraws funds deposited in the contract

Only the owner can call this function

function withdrawFunds(address _token, uint256 _amount, address _receiver) external;

Parameters

addRelay

Add a new relay to the automation vault with the desired callers, jobs and selectors

If the relay is valid, it can be passed with all the fields or only the necessary ones, passing the empty argument in the unwanted ones

function addRelay(address _relay, address[] calldata _callers, IAutomationVault.JobData[] calldata _jobsData) external;

Parameters

deleteRelay

Revokes the approval of a specific relay

The callers, jobs and selectors will be deleted

function deleteRelay(address _relay) external;

Parameters

modifyRelay

Modify the callers, jobs and selectors of a specific relay

If any of the arguments is empty, the data will be deleted

function modifyRelay(
  address _relay,
  address[] calldata _callers,
  IAutomationVault.JobData[] calldata _jobsData
) external;

Parameters

modifyRelayCallers

Modify the callers of a specific relay

If the array is empty, the data will be deleted

function modifyRelayCallers(address _relay, address[] calldata _callers) external;

Parameters

modifyRelayJobs

Modify the jobs and selectors of a specific relay

If the array is empty, the data will be deleted, also if the function selectors array is empty

function modifyRelayJobs(address _relay, IAutomationVault.JobData[] calldata _jobsData) external;

Parameters

exec

Executes a job and issues a payment to the fee data receivers

The function can be called with only execData, only feeData or both. The strategy of the payment will be different depending on which relay is calling the function

function exec(address _relayCaller, ExecData[] calldata _execData, FeeData[] calldata _feeData) external;

Parameters

Events

ChangeOwner

Emitted when the owner is proposed to change

event ChangeOwner(address indexed _pendingOwner);

Parameters

AcceptOwner

Emitted when the owner is accepted

event AcceptOwner(address indexed _owner);

Parameters

WithdrawFunds

Emitted when funds are withdrawn

event WithdrawFunds(address indexed _token, uint256 _amount, address indexed _receiver);

Parameters

ApproveRelay

Emitted when a relay is approved

event ApproveRelay(address indexed _relay);

Parameters

DeleteRelay

Emitted when a relay is deleted

event DeleteRelay(address indexed _relay);

Parameters

ApproveRelayCaller

Emitted when a relay caller is approved

event ApproveRelayCaller(address indexed _relay, address indexed _caller);

Parameters

ApproveJob

Emitted when job is approved

event ApproveJob(address indexed _job);

Parameters

ApproveJobSelector

Emitted when job selector is approved

event ApproveJobSelector(address indexed _job, bytes4 indexed _functionSelector);

Parameters

JobExecuted

Emitted when a job is executed

event JobExecuted(address indexed _relay, address indexed _relayCaller, address indexed _job, bytes _jobData);

Parameters

IssuePayment

Emitted when a payment is issued

event IssuePayment(
  address indexed _relay, address indexed _relayCaller, address indexed _feeRecipient, address _feeToken, uint256 _fee
);

Parameters

NativeTokenReceived

Emitted when native token is received in the automation vault

event NativeTokenReceived(address indexed _sender, uint256 _amount);

Parameters

Errors

AutomationVault_RelayZero

Thrown when the the relay is the zero address

error AutomationVault_RelayZero();

AutomationVault_RelayAlreadyApproved

Thrown when the relay is already approved

error AutomationVault_RelayAlreadyApproved();

AutomationVault_NativeTokenTransferFailed

Thrown when ether transfer fails

error AutomationVault_NativeTokenTransferFailed();

AutomationVault_NotApprovedRelayCaller

Thrown when a not approved relay caller is trying to execute a job

error AutomationVault_NotApprovedRelayCaller();

AutomationVault_NotApprovedJobSelector

Thrown when a not approved job selector is trying to be executed

error AutomationVault_NotApprovedJobSelector();

AutomationVault_ExecFailed

Thrown when a job execution fails

error AutomationVault_ExecFailed();

AutomationVault_OnlyOwner

Thrown when the caller is not the owner

error AutomationVault_OnlyOwner();

AutomationVault_OnlyPendingOwner

Thrown when the caller is not the pending owner

error AutomationVault_OnlyPendingOwner();

Structs

ExecData

The data to execute a job

struct ExecData {
  address job;
  bytes jobData;
}

Properties

FeeData

The data to issue a payment

struct FeeData {
  address feeRecipient;
  address feeToken;
  uint256 fee;
}

Properties

JobData

The data of a job

struct JobData {
  address job;
  bytes4[] functionSelectors;
}

Properties

IAutomationVaultFactory

Git Source

Functions

totalAutomationVaults

Get the total amount of automation vaults deployed by the factory

function totalAutomationVaults() external view returns (uint256 _totalAutomationVaults);

Returns

automationVaults

Get a certain amount of automation vaults deployed by the factory

function automationVaults(uint256 _startFrom, uint256 _amount) external view returns (address[] memory _list);

Parameters

Returns

deployAutomationVault

Deploy a new automation vault

function deployAutomationVault(
  address _owner,
  address _nativeToken,
  uint256 _salt
) external returns (IAutomationVault _automationVault);

Parameters

Returns

Events

DeployAutomationVault

Emitted when a new automation vault is deployed

event DeployAutomationVault(address indexed _owner, address indexed _automationVault);

Parameters

Errors

AutomationVaultFactory_Create2Failed

Thrown when the automation vault factory fails to deploy a new automation vault

error AutomationVaultFactory_Create2Failed();

Contents

• IBasicJob
• IBasicJobChecker

IBasicJob

Git Source

Functions

work

This function will be called by automation vaults

function work() external;

workHard

This function will be called by automation vaults

function workHard(uint256 _howHard) external;

Parameters

Events

Worked

Emitted when work is done

event Worked();

IBasicJobChecker

Git Source

Functions

checker

This function checks whether the job can be executed by the automation vault

function checker(
  IAutomationVault _automationVault,
  IBasicJob _basicJob
) external pure returns (bool canExec, bytes memory execPayload);

Parameters

Returns

Contents

• IXKeeperMetadata

IXKeeperMetadata

Git Source

Functions

automationVaultMetadata

Returns the metadata of the automation vault

function automationVaultMetadata(IAutomationVault _automationVault)
  external
  view
  returns (string calldata _name, string calldata _description);

Parameters

Returns

automationVaultsMetadata

Returns the metadata of the automation vault

function automationVaultsMetadata(IAutomationVault[] calldata _automationVault)
  external
  view
  returns (IXKeeperMetadata.AutomationVaultMetadata[] memory _metadata);

Parameters

Returns

setAutomationVaultMetadata

Sets the metadata of the automation vault

function setAutomationVaultMetadata(
  IAutomationVault _automationVault,
  AutomationVaultMetadata calldata _automationVaultMetadata
) external;

Parameters

Events

AutomationVaultMetadataSetted

Emitted when the metadata of an automation vault is set

event AutomationVaultMetadataSetted(IAutomationVault indexed _automationVault, string _name, string _description);

Parameters

Errors

XKeeperMetadata_OnlyAutomationVaultOwner

The caller is not the owner of the automation vault

error XKeeperMetadata_OnlyAutomationVaultOwner();

Structs

AutomationVaultMetadata

The metadata of the automation vault

struct AutomationVaultMetadata {
  string name;
  string description;
}

Properties

Contents

• IGelatoRelay
• IKeep3rBondedRelay
• IKeep3rRelay
• IOpenRelay

IGelatoRelay

Git Source

Functions

automate

Returns the automate contract of the gelato network

function automate() external view returns (IAutomate _automate);

Returns

gelato

Returns the gelato contract of the gelato network

function gelato() external view returns (IGelato _gelato);

Returns

feeCollector

Returns the fee collector of the gelato network

function feeCollector() external view returns (address _feeCollector);

Returns

exec

Execute an automation vault which will execute the jobs and will manage the payment to the fee data receivers

function exec(IAutomationVault _automationVault, IAutomationVault.ExecData[] calldata _execData) external;

Parameters

Events

AutomationVaultExecuted

Emitted when an automation vault is executed

event AutomationVaultExecuted(
  address indexed _automationVault,
  address indexed _relayCaller,
  IAutomationVault.ExecData[] _execData,
  IAutomationVault.FeeData[] _feeData
);

Parameters

IKeep3rBondedRelay

Git Source

Inherits: IKeep3rRelay

Functions

automationVaultRequirements

Get the automation vault bonded requirements

function automationVaultRequirements(IAutomationVault _automationVault)
  external
  view
  returns (address _bond, uint256 _minBond, uint256 _earned, uint256 _age);

Parameters

Returns

setAutomationVaultRequirements

Set the automation vault requirements when bonded job is required

Only the owner of the automation vault can set the requirements

function setAutomationVaultRequirements(
  IAutomationVault _automationVault,
  IKeep3rBondedRelay.Requirements memory _requirements
) external;

Parameters

Events

AutomationVaultRequirementsSetted

Emitted when the automation vault requirements are setted

event AutomationVaultRequirementsSetted(
  address indexed _automationVault, address _bond, uint256 _minBond, uint256 _earned, uint256 _age
);

Parameters

Errors

Keep3rBondedRelay_NotVaultOwner

Thrown when the caller is not the automation vault owner

error Keep3rBondedRelay_NotVaultOwner();

Keep3rBondedRelay_NotAutomationVaultRequirement

Thrown when the automation vault requirements are not setted

error Keep3rBondedRelay_NotAutomationVaultRequirement();

Keep3rBondedRelay_NotBondedKeeper

Thrown when the keeper doesn't meet the requirements set by the automation vault

error Keep3rBondedRelay_NotBondedKeeper();

Structs

Requirements

The requirements needed when bonded job is required

struct Requirements {
  address bond;
  uint256 minBond;
  uint256 earned;
  uint256 age;
}

Properties

IKeep3rRelay

Git Source

Functions

exec

Execute an automation vault which will execute the jobs and will manage the payment to the fee data receivers

The payment will be managed by keep3r network. The first and last exec data are assembled by the relay in order to be able to work with keep3r network

function exec(IAutomationVault _automationVault, IAutomationVault.ExecData[] calldata _execData) external;

Parameters

Events

AutomationVaultExecuted

Emitted when an automation vault is executed

event AutomationVaultExecuted(
  address indexed _automationVault, address indexed _relayCaller, IAutomationVault.ExecData[] _execData
);

Parameters

Errors

Keep3rRelay_NoExecData

Thrown when the exec data is empty

error Keep3rRelay_NoExecData();

Keep3rRelay_NotKeeper

Thrown when the caller is not a keeper

error Keep3rRelay_NotKeeper();

Keep3rRelay_Keep3rNotAllowed

Thrown when the exec data contains Keep3r V2

error Keep3rRelay_Keep3rNotAllowed();

IOpenRelay

Git Source

Functions

GAS_BONUS

Returns the gas bonus

function GAS_BONUS() external view returns (uint256 _gasBonus);

Returns

GAS_MULTIPLIER

Returns the gas multiplier

function GAS_MULTIPLIER() external view returns (uint256 _gasMultiplier);

Returns

BASE

Returns the base used for the payment calculation

function BASE() external view returns (uint32 _base);

Returns

exec

Execute an automation vault which will execute the jobs and will manage the payment to the fee data receivers

The payment will be calculated on the basis of several variables like the gas spent, the base fee, the gas bonus and the gas multiplier

function exec(
  IAutomationVault _automationVault,
  IAutomationVault.ExecData[] calldata _execData,
  address _feeRecipient
) external;

Parameters

Events

AutomationVaultExecuted

Emitted when an automation vault is executed

event AutomationVaultExecuted(
  address indexed _automationVault,
  address indexed _relayCaller,
  IAutomationVault.ExecData[] _execData,
  IAutomationVault.FeeData[] _feeData
);

Parameters

Errors

OpenRelay_NoExecData

Thrown when the exec data is empty

error OpenRelay_NoExecData();