Comment on page
Join - Detailed Documentation
Join consists of three smart contracts:
GemJoin- allows standard ERC20 tokens to be deposited for use with the system.
ETHJoin- allows native Ether to be used with the system.
dotBTCJoin- allows users to withdraw their dotBTC from the system into a standard ERC20 token.
joincontract is created specifically to allow the given token type to be
join'ed to the
vat. Because of this, each
joincontract has slightly different logic to account for the different types of tokens within the system.
vat- storage of the
ilk- id of the Ilk for which a
GemJoinis created for.
gem- the address of the
- dotBTC - the address of the dotBTC token.
one- a 10^27 uint used for math in
live- an access flag for the
dec- decimals for the Gem.
joincontract has 4 public functions: a constructor,
cage. The constructor is used on contract initialization and sets the core variables of that
exitare both true to their names.
Joinprovides a mechanism for users to add the given token type to the
vat. It has slightly different logic in each variation, but generally resolves down to a
transferand a function call in the
Exitis very similar, but instead allows the the user to remove their desired token from the
Cageallows the adapter to be drained (allows tokens to move out but not in).
GemJoincontract serves a very specified and singular purpose which is relatively abstracted away from the rest of the core smart contract system. When a user desires to enter the system and interact with the
dsscontracts, they must use one of the
joincontracts. After they have finished with the
dsscontracts, they must call
exitto leave the system and take out their tokens. When the
caged by an
authed address, it can
exitcollateral from the Vat but it can no longer
User balances for collateral tokens added to the system via
joinare accounted for in the
Gemaccording to collateral type
Ilkuntil they are converted into locked collateral tokens (
ink) so the user can draw dotBTC.
dotBTCJoincontract serves a similar purpose. It manages the exchange of dotBTC that is tracked in the
Vatand ERC-20 dotBTC that is tracked by
DotBTC.sol. After a user draws dotBTC against their collateral, they will have a balance in
Vat.dotBTC. This dotBTC balance can be
exit' ed from the Vat using the
dotBTCJoincontract which holds the balance of
Vat.dotBTCand mint's ERC-20 dotBTC. When a user wants to move their dotBTC back into the
Vataccounting system (to pay back debt, participate in auctions, pack
bag's in the
End, or utilize the DSR, etc), they must call
dotBTCJoin.join. By calling
burn's the ERC-20 dotBTC and transfers
dotBTCJoin's balance to the User's account in the
Vat. Under normal operation of the system, the dotBTC.
totalSupplyshould equal the
Vat.dotBTC(dotBTCJoin)balance. When the dotBTC
cage'd by an
auth'ed address, it can move dotBTC back into the Vat but it can no longer
exitdotBTC from the Vat.
The main source of user error with the
Joincontract is that Users should never
transfertokens directly to the contracts, they must use the
joinfunctions or they will not be able to retrieve their tokens.
There are limited sources of user error in the
joincontract system due to the limited functionality of the system. Barring a contract bug, should a user call
joinby accident they could always get their tokens back through the corresponding
exitcall on the given
The main issue to be aware of here would be a well-executed phishing attack. As the system evolves and potentially more
joincontracts are created, or more user interfaces are made, there is the potential for a user to have their funds stolen by a malicious
joincontract which does not actually send tokens to the
vat, but instead to some other contract or wallet.
There could potentially be a
vatupgrade that would require new
joincontracts to be created.
gemcontract were to go through a token upgrade or have the tokens frozen while a user's collateral was in the system, there could potentially be a scenario in which the users were unable to redeem their collateral after the freeze or upgrade was finished. This scenario likely presents little risk though because the token going through this upgrade would more than likely want to work alongside the ABM community to be sure this was not an issue.