auction-keeper
and interact with a Kovan deployment of the Multi Collateral Dai (MCD) smart contracts. More specifically, the guide will showcase how to set up and run an Auction Keeper bot for yourself. After going through this guide, you will achieve the following:auction-keeper
can participate in three different types of auctions:deal
(claiming a winning bid / settling a completed auction) if the Keeper's address won the auction.Flipper
, Flapper
and Flopper
auction contracts deployed to the Ethereum mainnet. All decisions which involve pricing details are delegated to the bidding models. The Bidding models are simply executable strategies, external to the main auction-keeper
process. This means that the bidding models themselves do not have to know anything about the Ethereum blockchain and its smart contracts, as they can be implemented in basically any programming language. However, they do need to have the ability to read and write JSON documents, as this is how they communicate/exchange with auction-keeper
. It's important to note that as a developer running an Auction Keeper, it is required that you have basic knowledge on how to properly start and configure the auction-keeper. For example, providing startup parameters as keystore / password are required to setup and run a Keeper. Additionally, you should be familiar with the MCD system, as the model will receive auction details from auction-keeper in the form of a JSON message containing keys such as lot, beg, guy, etc.1
to kicks
. When this occurs, even when the bidding model decides to send a bid, it will not be processed by the Keeper until the next iteration of that loop. It's important to note that the auction-keeper
not only monitors existing auctions and discovers new ones, but it also identifies and takes opportunities to create new auctions.--model
command-line parameter. These processes are automatically terminated (via SIGKILL
) by the keeper shortly after their associated auction expires. Whenever the bidding model process dies, it gets automatically re-spawned by the Keeper.id
- auction identifier.flipper
- Ethereum address of the Flipper
contract (only for flip
auctions).flapper
- Ethereum address of the Flapper
contract (only for flap
auctions).flopper
- Ethereum address of the Flopper
contract (only for flop
auctions).bid
- current highest bid (will go up for flip
and flap
auctions).lot
- amount being currently auctioned (will go down for flip
and flop
auctions).tab
- bid value (not to be confused with the bid price) which will cause the auction to enter the dent
phase (only for flip
auctions).beg
- minimum price increment (1.05
means minimum 5% price increment).guy
- Ethereum address of the current highest bidder.era
- current time (in seconds since the UNIX epoch).tic
- time when the current bid will expire (None
if no bids yet).end
- time when the entire auction will expire (end is set to 0
is the auction is no longer live).price
- current price being tendered (can be None
if price is infinity).auction-keeper
to periodically send the same message(s) to bidding models.auction-keeper
reads one-line messages from the standard output of the bidding model process and tries to parse them as JSON documents. It will then extract the two following fields from that document:price
- the maximum (for flip
and flop
auctions) or the minimum (for flap
auctions) price the model is willing to bid.gasPrice
(optional) - gas price in Wei to use when sending a bid.flap
and flop
auctions) or the collateral price expressed in DAI for flip
auctions (for example, OMG/DAI).auction-keeper
repository:auction-keeper
directory:pip install --upgrade pip
.kovan-addresses.json
in lib/pymaker/config/kovan-addresses.json
flip
auctions) or MKR (for flap
and flop
auctions). The sleep
locks the price in place for a minute, after which the keeper will restart the price model and read a new price (consider this your price update interval).model-eth.sh
(or whatever name you feel seems appropriate).my_environment.sh
SERVER_ETH_RPC_HOST
- Should not be an infura node, as it doesn't provide all the functionality that the python script needs
ACCOUNT_KEY
- Should have the absolute path to the keystore and password file. Define the path as shown above, as the python script will parse through both the keystore and password files.flip-eth-a.sh
(or something similar to identify that this Auction Keeper is for a Flip Auction). In addition, make sure to verify the above copy+pasted script doesn't create extra spaces or characters on pasting+saving in your editor. You will notice an error when running it later below otherwise.network
parameter. To fix this, just omit that parameter.ilk
's) combine the name of the token and a letter corresponding to a set of risk parameters. For example, as you can see above, the example uses ETH-A. Note that ETH-A and ETH-B are two different collateral types for the same underlying token (WETH) but have different risk parameters.--network mainnet|kovan
in and it will load the required JSON files bundled within auction-keeper (or pymaker).chmod +x
both of them.flip-eth-a.sh model-eth.sh
to pass your bidding model into your Auction Keeper script../flip-eth-a.sh model-eth.sh
command you will see an output like this:flip
of each collateral type, as well as one for flap
and another for flop
.--type
- the type of auction the keeper is used for. In this particular scenario, it will be set to flip
.--ilk
- the type of collateral.--addresses
- .json of all of the addresses of the MCD contracts as well as the collateral types allowed/used in the system.--vat-dai-target
- the amount of DAI which the keeper will attempt to maintain in the Vat, to use for bidding. It will rebalance it upon keeper startup and upon deal
ing an auction.--model
- the bidding model that will be used for bidding.--from-block
to the block where the first urn was created to instruct the keeper to use logs published by the vat contract to bulid a list of urns, and then check the status of each urn.bin/auction-keeper --help
for a complete list of arguments.End
). If global settlement occurs while a winning bid is outstanding, the Keeper will not request a yank
to refund the bid. The workaround is to call yank
directly using seth
.kick
, flap
, or flop
in response to opportunities regardless of whether or not your DAI or MKR balance is sufficient to participate. This imposes a gas fee that must be paid.Vat
.flip
auctions) in the Vat
. More explicitly speaking:Vat
.Vat
.eth-from
account is exit
'ed from the Vat and added to your account token balance when the Keeper is shut down. Note that this feature may be disabled using the keep-dai-in-vat-on-exit
and keep-gem-in-vat-on-exit
switches, respectively. The use of an eth-from
account with an open CDP is discouraged, as debt will hinder the auction contracts' ability to access your DAI, and the auction-keeper
's ability to exit
DAI from the Vat
.Vat
will be shared across all of the Keepers. If using this feature, you should set --vat-dai-target
to the same value for each Keeper, as well as sufficiently high in order to cover total desired exposure.flap
auctions is directly withdrawn from your token balance. The MKR won at flop
auctions is directly deposited to your token balance.0xb64964e9c0b658aa7b448cdbddfcdccab26cc584
0xaaf64bfcc32d0f15873a02163e7e500671a4ffcd
0x94598157fcf0715c3bc9b4a35450cce82ac57b20
address is the faucet that issues 1 MKR per request.0xaaf64bfcc32d0f15873a02163e7e500671a4ffcd
address is that of the MCD K-MKR token. It will issue 1 MKR.auction-keeper
, pymaker
's auction facilities, and relevant smart contracts in dss
. For more information about testing your Auction Keeper with your own testchain visit tests/manual/README.