Maker Protocol Technical Docs
Search…
Getting Started
Smart Contract Modules
Deployment Addresses
Security
Building on top of the Maker Protocol
Keepers
Command-line Interfaces
Pymaker
A Python API for the Maker Smart Contracts
Introduction
The Maker Protocol incentivizes external agents, called keepers, to automate certain operations around the Ethereum blockchain. In order to ease their development, an API around most of the Maker contracts has been created. It can be used not only by keepers, but may also be found useful by authors of some other, unrelated utilities aiming to interact with these contracts.
Based on the Pymaker API, a set of reference Maker keepers is being developed. They all used to reside in this repository, but now each of them has an individual one: bite-keeper (SCD only), arbitrage-keeper, auction-keeper (MCD only), cdp-keeper (SCD only), market-maker-keeper.
You only need to install this project directly if you want to build your own keepers, or if you want to play with this API library itself. If you just want to install one of reference keepers, go to one of the repositories linked above and start from there. Each of these keepers references some version of
pymaker via a Git submodule.Installation
This project uses Python 3.6.6.
In order to clone the project and install required third-party packages please execute:
1
git clone https://github.com/makerdao/pymaker.git
2
cd pymaker
3
pip3 install -r requirements.txt
Copied!
Known Ubuntu issues
In order for the
secp256k Python dependency to compile properly, following packages will need to be installed:1
sudo apt-get install build-essential automake libtool pkg-config libffi-dev python-dev python-pip libsecp256k1-dev
Copied!
(for Ubuntu 18.04 Server)
Known macOS issues
In order for the Python requirements to install correctly on macOS, please install
openssl, libtool, pkg-config and automake using Homebrew:1
brew install openssl libtool pkg-config automake
Copied!
and set the
LDFLAGS environment variable before you run pip3 install -r requirements.txt:1
export LDFLAGS="-L$(brew --prefix openssl)/lib" CFLAGS="-I$(brew --prefix openssl)/include"
Copied!
Available APIs
The current version provides APIs around:
ERC20Token,0x v2Dai Savings Rate (Pot)(https://github.com/makerdao/pymaker/blob/master/tests/manual_test_dsr.py#L29)
APIs around the following functionality have not been implemented:
Global Settlement (End)Governance (DSAuth, DSChief, DSGuard, DSSpell, Mom)
Contributions from the community are much appreciated!
Code samples
Below you can find some code snippets demonstrating how the API can be used both for developing your own keepers and for creating some other utilities interacting with the Maker Protocol ecosystem contracts.
Token transfer
This snippet demonstrates how to transfer some SAI from our default address. The SAI token address is discovered by querying the
Tub, so all we need as a Tub address:1
from web3 import HTTPProvider, Web3
2
​
3
from pymaker import Address
4
from pymaker.token import ERC20Token
5
from pymaker.numeric import Wad
6
from pymaker.sai import Tub
7
​
8
​
9
web3 = Web3(HTTPProvider(endpoint_uri="http://localhost:8545"))
10
​
11
tub = Tub(web3=web3, address=Address(' 0xb7ae5ccabd002b5eebafe6a8fad5499394f67980'))
12
sai = ERC20Token(web3=web3, address=tub.sai())
13
​
14
sai.transfer(address=Address(' 0x0000000000111111111100000000001111111111'),
15
value=Wad.from_number(10)).transact()
Copied!
Updating a DSValue
This snippet demonstrates how to update a
DSValue with the ETH/USD rate pulled from CryptoCompare:1
import json
2
import urllib.request
3
​
4
from web3 import HTTPProvider, Web3
5
​
6
from pymaker import Address
7
from pymaker.feed import DSValue
8
from pymaker.numeric import Wad
9
​
10
​
11
def cryptocompare_rate() -> Wad:
12
with urllib.request.urlopen("https://min-api.cryptocompare.com/data/price?fsym=ETH&tsyms=USD") as url:
13
data = json.loads(url.read().decode())
14
return Wad.from_number(data['USD'])
15
​
16
​
17
web3 = Web3(HTTPProvider(endpoint_uri="http://localhost:8545"))
18
​
19
dsvalue = DSValue(web3=web3, address=Address(' 0x038b3d8288df582d57db9be2106a27be796b0daf'))
20
dsvalue.poke_with_int(cryptocompare_rate().value).transact()
Copied!
SAI introspection
This snippet demonstrates how to fetch data from
Tub and Tap contracts:1
from web3 import HTTPProvider, Web3
2
​
3
from pymaker import Address
4
from pymaker.token import ERC20Token
5
from pymaker.numeric import Ray
6
from pymaker.sai import Tub, Tap
7
​
8
​
9
web3 = Web3(HTTPProvider(endpoint_uri="http://localhost:8545"))
10
​
11
tub = Tub(web3=web3, address=Address(' 0x448a5065aebb8e423f0896e6c5d525c040f59af3'))
12
tap = Tap(web3=web3, address=Address(' 0xbda109309f9fafa6dd6a9cb9f1df4085b27ee8ef'))
13
sai = ERC20Token(web3=web3, address=tub.sai())
14
skr = ERC20Token(web3=web3, address=tub.skr())
15
gem = ERC20Token(web3=web3, address=tub.gem())
16
​
17
print(f"")
18
print(f"Token summary")
19
print(f"-------------")
20
print(f"SAI total supply : {sai.total_supply()} SAI")
21
print(f"SKR total supply : {skr.total_supply()} SKR")
22
print(f"GEM total supply : {gem.total_supply()} GEM")
23
print(f"")
24
print(f"Collateral summary")
25
print(f"------------------")
26
print(f"GEM collateral : {tub.pie()} GEM")
27
print(f"SKR collateral : {tub.air()} SKR")
28
print(f"SKR pending liquidation: {tap.fog()} SKR")
29
print(f"")
30
print(f"Debt summary")
31
print(f"------------")
32
print(f"Debt ceiling : {tub.cap()} SAI")
33
print(f"Good debt : {tub.din()} SAI")
34
print(f"Bad debt : {tap.woe()} SAI")
35
print(f"Surplus : {tap.joy()} SAI")
36
print(f"")
37
print(f"Feed summary")
38
print(f"------------")
39
print(f"REF per GEM feed : {tub.pip()}")
40
print(f"REF per SKR price : {tub.tag()}")
41
print(f"GEM per SKR price : {tub.per()}")
42
print(f"")
43
print(f"Tub parameters")
44
print(f"--------------")
45
print(f"Liquidation ratio : {tub.mat()*100} %")
46
print(f"Liquidation penalty : {tub.axe()*100 - Ray.from_number(100)} %")
47
print(f"Stability fee : {tub.tax()} %")
48
print(f"")
49
print(f"All cups")
50
print(f"--------")
51
for cup_id in range(1, tub.cupi()+1):
52
cup = tub.cups(cup_id)
53
print(f"Cup #{cup_id}, lad={cup.lad}, ink={cup.ink} SKR, tab={tub.tab(cup_id)} SAI, safe={tub.safe(cup_id)}")
Copied!
Multi-collateral Dai
This snippet demonstrates how to create a CDP and draw Dai.
1
import sys
2
from web3 import Web3, HTTPProvider
3
​
4
from pymaker import Address
5
from pymaker.deployment import DssDeployment
6
from pymaker.keys import register_keys
7
from pymaker.numeric import Wad
8
​
9
​
10
web3 = Web3(HTTPProvider(endpoint_uri="https://localhost:8545",
11
request_kwargs={"timeout": 10}))
12
web3.eth.defaultAccount = sys.argv[1] # ex: 0x0000000000000000000000000000000aBcdef123
13
register_keys(web3, [sys.argv[2]]) # ex: key_file=~keys/default-account.json,pass_file=~keys/default-account.pass
14
​
15
mcd = DssDeployment.from_json(web3=web3, conf=open("tests/config/kovan-addresses.json", "r").read())
16
our_address = Address(web3.eth.defaultAccount)
17
​
18
​
19
# Choose the desired collateral; in this case we'll wrap some Eth
20
collateral = mcd.collaterals['ETH-A']
21
ilk = collateral.ilk
22
collateral.gem.deposit(Wad.from_number(3)).transact()
23
​
24
# Add collateral and allocate the desired amount of Dai
25
collateral.approve(our_address)
26
collateral.adapter.join(our_address, Wad.from_number(3)).transact()
27
mcd.vat.frob(ilk, our_address, dink=Wad.from_number(3), dart=Wad.from_number(153)).transact()
28
print(f"CDP Dai balance before withdrawal: {mcd.vat.dai(our_address)}")
29
​
30
# Mint and withdraw our Dai
31
mcd.approve_dai(our_address)
32
mcd.dai_adapter.exit(our_address, Wad.from_number(153)).transact()
33
print(f"CDP Dai balance after withdrawal: {mcd.vat.dai(our_address)}")
34
​
35
# Repay (and burn) our Dai
36
assert mcd.dai_adapter.join(our_address, Wad.from_number(153)).transact()
37
print(f"CDP Dai balance after repayment: {mcd.vat.dai(our_address)}")
38
​
39
# Withdraw our collateral
40
mcd.vat.frob(ilk, our_address, dink=Wad(0), dart=Wad.from_number(-153)).transact()
41
mcd.vat.frob(ilk, our_address, dink=Wad.from_number(-3), dart=Wad(0)).transact()
42
collateral.adapter.exit(our_address, Wad.from_number(3)).transact()
43
print(f"CDP Dai balance w/o collateral: {mcd.vat.dai(our_address)}")
Copied!
Asynchronous invocation of Ethereum transactions
This snippet demonstrates how multiple token transfers can be executed asynchronously:
1
from web3 import HTTPProvider
2
from web3 import Web3
3
​
4
from pymaker import Address, synchronize
5
from pymaker.numeric import Wad
6
from pymaker.sai import Tub
7
from pymaker.token import ERC20Token
8
​
9
​
10
web3 = Web3(HTTPProvider(endpoint_uri="http://localhost:8545"))
11
​
12
tub = Tub(web3=web3, address=Address(' 0x448a5065aebb8e423f0896e6c5d525c040f59af3'))
13
sai = ERC20Token(web3=web3, address=tub.sai())
14
skr = ERC20Token(web3=web3, address=tub.skr())
15
​
16
synchronize([sai.transfer(Address(' 0x0101010101020202020203030303030404040404'), Wad.from_number(1.5)).transact_async(),
17
skr.transfer(Address(' 0x0303030303040404040405050505050606060606'), Wad.from_number(2.5)).transact_async()])
Copied!
Multiple invocations in one Ethereum transaction
This snippet demonstrates how multiple token transfers can be executed in one Ethereum transaction. A
TxManager instance has to be deployed and owned by the caller.1
from web3 import HTTPProvider
2
from web3 import Web3
3
​
4
from pymaker import Address
5
from pymaker.approval import directly
6
from pymaker.numeric import Wad
7
from pymaker.sai import Tub
8
from pymaker.token import ERC20Token
9
from pymaker.transactional import TxManager
10
​
11
​
12
web3 = Web3(HTTPProvider(endpoint_uri="http://localhost:8545"))
13
​
14
tub = Tub(web3=web3, address=Address(' 0x448a5065aebb8e423f0896e6c5d525c040f59af3'))
15
sai = ERC20Token(web3=web3, address=tub.sai())
16
skr = ERC20Token(web3=web3, address=tub.skr())
17
​
18
tx = TxManager(web3=web3, address=Address(' 0x57bFE16ae8fcDbD46eDa9786B2eC1067cd7A8f48'))
19
tx.approve([sai, skr], directly())
20
​
21
tx.execute([sai.address, skr.address],
22
[sai.transfer(Address(' 0x0101010101020202020203030303030404040404'), Wad.from_number(1.5)).invocation(),
23
skr.transfer(Address(' 0x0303030303040404040405050505050606060606'), Wad.from_number(2.5)).invocation()]).transact()
Copied!
Ad-hoc increasing of gas price for asynchronous transactions
1
import asyncio
2
from random import randint
3
​
4
from web3 import Web3, HTTPProvider
5
​
6
from pymaker import Address
7
from pymaker.gas import FixedGasPrice
8
from pymaker.oasis import SimpleMarket
9
​
10
​
11
web3 = Web3(HTTPProvider(endpoint_uri=f"http://localhost:8545"))
12
otc = SimpleMarket(web3=web3, address=Address(' 0x375d52588c3f39ee7710290237a95C691d8432E7'))
13
​
14
​
15
async def bump_with_increasing_gas_price(order_id):
16
gas_price = FixedGasPrice(gas_price=1000000000)
17
task = asyncio.ensure_future(otc.bump(order_id).transact_async(gas_price=gas_price))
18
​
19
while not task.done():
20
await asyncio.sleep(1)
21
gas_price.update_gas_price(gas_price.gas_price + randint(0, gas_price.gas_price))
22
​
23
return task.result()
24
​
25
​
26
bump_task = asyncio.ensure_future(bump_with_increasing_gas_price(otc.get_orders()[-1].order_id))
27
event_loop = asyncio.get_event_loop()
28
bump_result = event_loop.run_until_complete(bump_task)
29
​
30
print(bump_result)
31
print(bump_result.transaction_hash)
Copied!
Testing
Prerequisites:
This project uses pytest for unit testing. Testing of Multi-collateral Dai is performed on a Dockerized local testchain included in
tests\config.In order to be able to run tests, please install development dependencies first by executing:
1
pip3 install -r requirements-dev.txt
Copied!
You can then run all tests with:
1
./test.sh
Copied!
If you have questions regarding Pymaker, please reach out to us on the #keeper channel on chat.makerdao.com.
Last modified 2yr ago
Export as PDF
Copy link