Keepers are meant participate in collateral, surplus and debt auctions by directly interacting with GEB auction contracts deployed on a blockchain.
The keepers are responsible with:
- 1.Monitoring all active auctions
- 2.Starting new auctions
- 3.Discovering new auctions
- 4.Ensuring a bidding model is running for each active auction
- 5.Passing auction status to each bidding model
- 6.Processing each bidding model output and submitting bids
auction-keepercan read an auction's status directly from the blockchain or from a Graph node. Its unique feature is the ability to plug in external bidding models which tell the keeper when and how much to bid. Bid prices are received from separate bidding models.
Bidding models are simple processes that can be implemented in any programming language. They only need to pass JSON objects to and from
auction-keeper. The simplest example of a bidding model is a shell script which echoes a fixed price.
For every new block, all auctions from
auctionsStartedare checked for active status. If a new auction is detected, a new bidding model is started.
NOTE: Bidding models are only used for surplus and debt auctions, not collateral auctions.
Pre-requisites: Python 3.6+
git clone https://github.com/reflexer-finance/auction-keeper.git
git submodule update --init --recursive
pip3 install -r requirements.txt
The keeper can now be run with
Auction specific examples:
bin/auction-keeper -hto see an up-to-date list of arguments and usage information.
--type collateral|surplus|debtA keeper can only participate in one type of auction
--type=collateralis passed, the
collateral_typemust also be provided. A keeper can only bid on a single collateral type auction at a time. NOTE: Currently, only the
ETH-Acollateral type is used.
--eth-from ADDRESSAddress of the keeper. Warning: Do not use the same
eth-fromaccount on multiple keepers as it complicates
SAFEEngineinventory management and will likely cause nonce conflicts. Using an
eth-fromaccount with an open SAFE is also discouraged.
--rpc-host HOSTURI of ETH JSON-RPC node. Default
--rpc-timeout SECSDefaults to
The keeper connects to the blockchain network using Web3.py and interacts with GEB using pyflex. A connection to an Ethereum node (
--rpc-host) is required. Parity and Geth nodes are supported over HTTP. Websocket endpoints are not supported in
pyflex. A full or archive node is required; light nodes are not supported.
The following options determine the keeper's gas strategy and are mutually exclusive:
--etherscan-gas-priceUse etherscan.io for gas prices. Optional:
--etherscan-key KEY. Rate-limited to 1request/5sec w/o a key.
--fixed-gas-price GWEIUse a fixed gas price (in GWEI)
If none of these options is given or if the gas API produces no result, the keeper will fetch the gas price from the node you connected to.
--gas-initial-multiplier MULTIPLIERWhen using an API source for fetching the initial gas price, this tunes the price. It's ignored when you're using
--fixed-gas-price. In case no strategy is specified it defaults to
--gas-reactive-multiplier MULTIPLIEREvery 30 seconds, a transaction's gas price will be multiplied by this value until it is mined or
--gas-maxiumumis reached. Not used if
gasPriceis passed from your bidding model. NOTE: Parity, as of this writing, requires a minimum gas increase of
1.125to propagate a transaction replacement; this should be treated as a minimum value unless you want replacements to happen less frequently. This multiplier defaults to
1.125if no other value is given.
--gas-maximum GWEIMaximum value for gas price
By default the keeper
joins system coins to
SAFEEngineon startup and
exits all system coins and collateral upon shutdown. The keeper provides options for managing
SAFEEnginebalances, which may be turned off in case you'd like to manage balances manually.
exitsystem coin on shutdown
exitcollateral on shutdown
--return-collateral-interval SECSHow often, in seconds, the keeper
exits won collateral from
0to disable completely. Defaults to
--safe-engine-system-coin-target ALL|<integer>Amount of system coins the keeper will try to keep in
SAFEEngineby rebalancing with
exits between its own wallet and its balance inside GEB. Defaults to
ALLand the keeper will
joinall of an account's systems coins.
System coins are rebalanced per
- The keeper starts up
SAFEEnginebalance is insufficient in order to place a bid
- An auction is settled
Rebalances do not account for system coins moved from the
SAFEEngineto an auction contract for an active bid.
To avoid transaction spamming, small "dusty" system coins balances will be ignored (until the keeper exits, if so configured).
To start collateral auctions, the keeper needs a list of SAFEs and the collateralization ratio of each safe. There are two ways to retrieve the list of open SAFEs:
--from-block BLOCK_NUMBERScrape the chain for
ModifySAFECollateralizationevents, starting at
BLOCK_NUMBER. Set this to the block where the first ever SAFE was created. After startup, only new blocks will be queried. The scrape process can last a significant amount of time as the system matures. NOTE: To manage the performance of debt auction bidding, periodically adjust
--from-blockto the block number of the oldest liquidation which has not been
popDebtFromQueued yet. Defaults to
geb.starting_block_number, the block in which the system was deployed.
--graph-endpoints NODE1,NODE2Comma delimited list of Graph endpoints used to retrieve
ModifySAFECollateralizationevents. If multiple endpoints are passed, they will be pinged sequentially in the order they were specified in case one or many of them fail. NOTE: This flag is only supported for collateral auctions.
--graph-block-threshold NUMBER_OF_BLOCKSWhen the keeper fetches SAFE data to find critical safes, use the
--graph-endpointswhen the keeper's last processed block is older than
NUMBER_OF_BLOCKS. The graph will be faster than a node when fetching historical data, but recent graph blocks might be slightly delayed compared to an ethereum node. This allows the keeper to to fetch historical data from the graph, but use the node for all newer blocks. Defaults to
The following are the most recent Graph node endpoints for RAI:
--min-auction AUCTION_IDIgnore auctions older than
--max-auctions NUMBERLimit the number of bidding models created to handle active auctions.
--block-check-interval <integer>, default:1How often the keeper checks for new blocks
--bid-check-interval <integer>, default 4How often the keeper checks model processes for new bids
NOTE: if you'd like to use Infura with your keeper and prefer the free-tier (you do less than 100K requests per day),
--block-check-intervalmust be greater than
--bid-check-intervalmust be greater than 180. However, this will make your keeper slower and it will not quickly bid in auctions.
Flash swaps allow a keeper to participate in collateral auctions without any system coins. The flash swap borrows the system coin necessary for the collateral auctions, wins the collateral at a discount and transferred the won collateral back to the keeper, all in one transaction. Note: If the overall transaction is not profitable, the swap will fail. The keeper only needs enough ether to pay for the gas of the swap.
--flash-swapTurn on Uniswap flash swaps for collateral auctions. Not supported for
Bid management can be sharded across multiple keepers. If you want to proceed with sharding, set these options:
--shards NUMBER_OF_KEEPERNumber of keepers you plan to run. You must set this for all keepers
--shard-id SHARD_IDYou must specify this for every keeper, counting from 0
For example, to configure three keepers, set
--shards 3and assign
--shard-id 2for the first, second and third keeper.
NOTE: Auction starts are not sharded. Only one keeper should be configured to
liquidateSAFEs and this way
If you are sharding across multiple accounts, you may want to have a separate keeper that handles all your
settleAuctions (in the case of English collateral, debt and surplus auctions)
--settle-for <ACCOUNT1 ACCOUNT2>|NONE|ALLSpace-delimited list of accounts for which the keeper will settle auctions. Specify
NONEto disable this option. If you'd like to donate your gas to settle auctions for all participants,
ALLis also supported. Defaults to only the keeper address.
NOTE: Auction settlements are already sharded, so you should remove the sharding configuration if you're running a dedicated auction settlement keeper.
Many pending transactions can fill up the keeper's transaction queue, causing every subsequent transaction to be dropped. By waiting a small
--bid-delayafter each bid, multiple transactions can be submitted asynchronously while still allowing some time for older transactions to complete, freeing up the queue.
Many parameters determine the appropriate bid delay. For illustration purposes, assume the queue can hold 12 transactions, and gas prices are reasonable. In this setup, a bid delay of 1.2 seconds might provide ample time for transactions at the front of the queue to complete.
- If an auction started before the keeper was started, this keeper will not participate in it until the next block is mined
- This keeper does not explicitly handle Global Settlement, and may submit transactions which fail during shutdown
- Some keeper functions incur gas fees regardless of whether a bid is submitted. This includes, but is not limited to, the following actions:
- submitting token approvals
- adjusting the surplus and debt balances from
- liquidating a SAFE or starting a surplus or debt auction
- The keeper does not check model prices until an auction exists. When configured to create new auctions, it will
liquidateSAFEs or start a new surplus or debt auction regardless of whether or not your system coin or protocol token balance is sufficient to bid
- Liquidating a SAFE to start a new collateral auction is a time consuming operation. To do so without a subgraph subscription, the keeper initializes a cache of SAFEs states by scraping event logs from the chain. The keeper will then continuously refresh SAFE states and detect undercollateralized SAFEs.
- Despite batching log queries into multiple requests, Geth nodes are generally unable to initialize the SAFE state cache in a reasonable amount of time. As such, Geth is not recommended for liquidating SAFEs
- To manage resources, it is recommended to run separate keepers using separate accounts to liquidate (
--start-auctions-only) and bid (
--bid-only) in auctions
This project uses pytest for unit testing. Testing depends on a dockerized local testchain included in
In order to be able to run tests you should execute:
git clone https://github.com/reflexer-labs/auction-keeper.git
git submodule update --init --recursive
pip3 install -r requirements-dev.txt
You can then run all tests with: