auction-keeperand 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-keepercan participate in three different types of auctions:
deal(claiming a winning bid / settling a completed auction) if the Keeper's address won the auction.
Flopperauction 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-keeperprocess. 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.
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-keepernot only monitors existing auctions and discovers new ones, but it also identifies and takes opportunities to create new auctions.
--modelcommand-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
Flippercontract (only for
flapper- Ethereum address of the
Flappercontract (only for
flopper- Ethereum address of the
Floppercontract (only for
bid- current highest bid (will go up for
lot- amount being currently auctioned (will go down for
tab- bid value (not to be confused with the bid price) which will cause the auction to enter the
dentphase (only for
beg- minimum price increment (
1.05means 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 (
Noneif no bids yet).
end- time when the entire auction will expire (end is set to
0is the auction is no longer live).
price- current price being tendered (can be
Noneif price is infinity).
auction-keeperto periodically send the same message(s) to bidding models.
auction-keeperreads 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
flopauctions) or the minimum (for
flapauctions) price the model is willing to bid.
gasPrice(optional) - gas price in Wei to use when sending a bid.
flopauctions) or the collateral price expressed in DAI for
flipauctions (for example, OMG/DAI).
pip install --upgrade pip.
flipauctions) or MKR (for
sleeplocks 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).
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.
networkparameter. 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|kovanin and it will load the required JSON files bundled within auction-keeper (or pymaker).
chmod +xboth of them.
flip-eth-a.sh model-eth.shto pass your bidding model into your Auction Keeper script.
./flip-eth-a.sh model-eth.shcommand you will see an output like this:
flipof each collateral type, as well as one for
flapand another for
--type- the type of auction the keeper is used for. In this particular scenario, it will be set to
--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
dealing an auction.
--model- the bidding model that will be used for bidding.
--from-blockto 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 --helpfor a complete list of arguments.
End). If global settlement occurs while a winning bid is outstanding, the Keeper will not request a
yankto refund the bid. The workaround is to call
flopin 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.
flipauctions) in the
Vat. More explicitly speaking:
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-gem-in-vat-on-exitswitches, respectively. The use of an
eth-fromaccount 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
exitDAI from the
Vatwill be shared across all of the Keepers. If using this feature, you should set
--vat-dai-targetto the same value for each Keeper, as well as sufficiently high in order to cover total desired exposure.
flapauctions is directly withdrawn from your token balance. The MKR won at
flopauctions is directly deposited to your token balance.
0x94598157fcf0715c3bc9b4a35450cce82ac57b20address is the faucet that issues 1 MKR per request.
0xaaf64bfcc32d0f15873a02163e7e500671a4ffcdaddress is that of the MCD K-MKR token. It will issue 1 MKR.
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.