DeFi SDK is an open-source system of smart contracts designed for precise DeFi portfolio accounting. To put it simply, DeFi SDK is the on-chain balanceOf for DeFi protocols.
If you have any questions about DeFi SDK, feel free to reach out to us on our Discord server.
How much debt does
0xdead..beef
have on Compound?
How much
cUSDC
vsETH
doesETHMACOAPY
have?
- Examples
- DeFi SDK architecture
- Addresses
- Supported protocols
- How to add your adapter
- What’s next for DeFi SDK
- Security vulnerabilities
Find more examples of defi-sdk usage here (web3js
, ethers.js
).
As of now, to get all cTokens along with a user's debt on Compound you need to perform over 10 calls to the Ethereum node to different contracts or rely on a centralized API. With DeFi SDK, you can call
getProtocolBalances('0xdead...beef', ['Compound'])
on the api.zerion.eth smart contract and get all borrowed and supplied tokens
[{
metadata: {
name: 'Compound',
description: 'Decentralized Lending & Borrowing Protocol',
websiteURL: 'compound.finance',
iconURL: 'protocol-icons.s3.amazonaws.com/compound.png',
version: '0'
},
adapterBalances: [{
metadata: {
adapterAddress: '0x90F0Ed76cfCf75Ccab31A9b4E51782F230aA0747',
adapterType: 'Asset'
},
balances: [{
base: {
metadata: {
token: '0x6C8c6b02E7b2BE14d4fA6022Dfd6d75921D90E4E',
name: 'Compound Basic Attention Token',
symbol: 'cBAT',
decimals: '8'
},
amount: '314159265'
},
underlying: [{
metadata: {
token: '0x0D8775F648430679A709E98d2b0Cb6250d2887EF',
name: 'Basic Attention Token',
symbol: 'BAT',
decimals: '18'
},
amount: '6626070040000000000'
}]
}]
},{
metadata: {
adapterAddress: '0xD0646777520Aff625F976a8D81b95B5B42cDa1B9',
adapterType: 'Debt'
},
balances: [{
base: {
metadata: {
token: '0x6B175474E89094C44Da98b954EedeAC495271d0F',
name: 'Dai Stablecoin',
symbol: 'DAI',
decimals: '18'
},
amount: '1971081500000000000'
},
underlying: []
}]
}
]
}]
Sometimes, a DeFi token contains several other tokens, and to calculate their price, you need to know their underlying assets. For example, a Uniswap V1 cDAI pool
consists of ETH
and cDAI
. cDAI
, in turn, has DAI
as an underlying token. With DeFi SDK you can call
// Uniswap V1 cDAI pool
getFinalFullTokenBalance("Uniswap V1 pool token", 0x34E89740adF97C3A9D3f63Cc2cE4a914382c230b)
and fetch the decomposition of UNI-token into ERC20 tokens, like ETH
and DAI
0.98 ETH
215.6 DAI
In case you want to get account balances across all supported DeFi protocols, you can call
// bankless.zerion.eth portfolio
getBalances(0x0ef51b7dac3933b8109482e7d910c21848e45da0f)
and obtain all balances for a given account. The response from the smart-contract will contain information about each of the protocols
100 DAI // collateral on Compound
0.1 ETH // debt on Compound
100 USDC // locked in PoolTogether
213 TUSD + 201 USDC + 82 USDT + 11 DAI // Curve Y pool
...
For the protocols that uses a lot of liquidity pools (Bancor, Balancer, Uniswap) balances are not available by default in getBalances()
function.
Balances for such protocols must be fetched by getAdapterBalance()
function with a list of pools passed as a function parameter. If you call
getBalances(
0x42b9dF65B219B3dD36FF330A4dD8f327A6Ada990, // account address
0x581Ae5AF7afa6f8171Bbf40d1981779F168A9523, // balancer adapter address
[0x53b89CE35928dda346c574D9105A5479CB87231c,
0x987D7Cc04652710b74Fff380403f5c02f82e290a] // balancer pools addresses
)
you will obtain Balancer balances for given pools. The response from the smart-contract will contain information about each of the pools
1.3 ETH + 552.4 DAI // 30% WETH + 70% DAI pool
4.2 MKR + 2.5 WETH // 75% MKR + 25% WETH pool
- ProtocolAdapter is a special contract for every protocol. Its main purpose is to wrap all the protocol interactions. There are different types of protocol adapters: "Asset" adapter returns the amount of the account's tokens held on the protocol and the "Debt" adapter returns the amount of the account's debt to the protocol. Some protocols do not use "simple" ERC20 tokens but instead have complex derivatives, for example the Compound protocol has CTokens. The ProtocolAdapter contract also provides information about the type of tokens used within it.
- TokenAdapter is a contract for every derivative token type (e.g cTokens, aTokens, yTokens, etc.) Its main purpose is to provide ERC20-style token metadata as well as information about the underlying ERC20 tokens (like DAI for cDAI). Namely, it provides addresses, types and rates of underlying tokens.
- AdapterRegistry is a contract that a) maintains a list of ProtocolAdapters and TokenAdapters and b) is called to fetch user balances.
More detailed documentation about contracts can be found in adapters and AdapterRegistry documentation.
AdapterRegistry contract's mainnet address is 0x06FE76B2f432fdfEcAEf1a7d4f6C3d41B5861672. Its source code is verified on etherscan.
All the deployed contracts' addresses are available here.
Protocol Name | Description | Protocol Adapters | Token Adapters |
---|---|---|---|
Aave | Decentralized lending & borrowing protocol. Aave market. | Asset adapter Debt adapter |
"AToken" |
Aave • Uniswap Market | Decentralized lending & borrowing protocol. Uniswap market. | Asset adapter Debt adapter |
"AToken Uniswap Market" |
Ampleforth | An adaptive money built on sound economics. | Asset adapter | — |
Balancer | Non-custodial portfolio manager, liquidity provider, and price sensor. | Asset adapter supports all Balancer pools | "Balancer pool token" |
Bancor | Automated liquidity protocol. | Asset adapter supports Bancor pools starting from version 11 | "SmartToken" |
Compound | Decentralized lending & borrowing protocol. | Asset adapter Debt adapter Governance adapter |
"CToken" |
Curve | Exchange liquidity pool for stablecoin trading. Supports all pools. | Asset adapter | "Curve pool token" |
DDEX • Lending | Decentralized margin trading | Asset adapter | — |
DDEX • Margin | Decentralized margin trading | Asset adapter Debt adapter |
— |
DDEX • Spot | Decentralized margin trading | Asset adapter | — |
DeFi Money Market | Crypto through revenue-producing real world assets. | Asset adapter | "MToken" |
dYdX | Decentralized trading platform. All 4 markets (WETH, SAI, USDC, DAI) are supported. | Asset adapter Debt adapter |
— |
Idle | Yield aggregator for lending platforms. | Asset adapter | "IdleToken" |
iearn.finance (v2/v3) | Yield aggregator for lending platforms. Protocol adapter is duplicated for v2 and v3 versions of protocol. | Asset adapter | "YToken" |
Chai | A simple ERC20 wrapper over the Dai Savings Protocol. | Asset adapter | "Chai token" |
Dai Savings Protocol | Decentralized lending protocol. | Asset adapter | — |
Maker Governance | MKR tokens locked on the MakerDAO governance contracts. | Asset adapter | — |
Multi-Collateral Dai | Collateralized loans on Maker. | Asset adapter Debt adapter |
— |
PoolTogether | Decentralized no-loss lottery. Supports SAI, DAI, and USDC pools. | Asset adapter | "PoolTogether pool" |
Synthetix | Synthetic assets protocol. Asset adapter returns amount of SNX locked as collateral. | Asset adapter Debt adapter |
— |
TokenSets | Automated asset management strategies. | Asset adapter | "SetToken" |
Uniswap V1 | Automated liquidity protocol. | Asset adapter supports all Uniswap V1 pools | "Uniswap V1 pool token" |
Uniswap V2 | Automated liquidity protocol. | Asset adapter supports all Uniswap V2 pools | "Uniswap V2 pool token" |
0x Staking | Liquidity rewards for staking ZRX. | Asset adapter | — |
The full instructions on how to add a custom adapter to the AdapterRegistry contract may be found in our wiki.
If you have questions and/or want to add your adapter to Zerion reach out to us on our Discord server.
This first version of DeFi SDK is for read-only accounting purposes. Our next step is to introduce Interactive Adapters that allow users to make cross-protocol transactions from a single interface. We are incredibly excited to work with developers, users and the wider DeFi community to make these integrations as secure and accessible as possible. Watch this space, because the “De” in DeFi is about to get a whole lot more user-friendly!
If you discover a security vulnerability within DeFi SDK, please send us an e-mail at [email protected]. All security vulnerabilities will be promptly addressed.
This project uses Truffle and web3js for all Ethereum interactions and testing.
npm run compile
npm run test
npm run coverage
Currently, unsupported files are ignored.
npm run lint
Currently, unsupported files are ignored.
npm run deploy:network
, network
is either development
or mainnet
truffle run verify ContractName@0xcontractAddress --network mainnet
All smart contracts are released under GNU LGPLv3.