-
Notifications
You must be signed in to change notification settings - Fork 2
Ampleforth Exchange Integration Guide
We are happy to assist, please reach out to us at dev-support@ampleforth.org
With Ampleforth team’s support, Bitfinex was able to complete integration with one engineer over the course of 1 week.
The Ampleforth AMPL token is a standard ERC-20 token deployed on Ethereum, with one unique piece of behavior: it has a rebase
function that adjusts the total supply up or down. The size of this adjustment is calculated automatically. For full context about the economic motivation for this solution please see the whitepaper.
Each time a rebase
changes the total supply, all user wallets holding AMPL tokens adjust up or down globally by the same scaling factor. This global balance update happens atomically for all wallets in a single transaction. Ultimately, this means that when an exchange's pooled wallet balance is adjusted, user balances need to be adjusted accordingly.
Each time a rebase
executes succesfully, the function emits a log message that includes an updated totalSupply
event LogRebase(
uint256 indexed epoch,
uint256 totalSupply
);
This new totalSupply
value from the log output, can be used to safely update user balances on centralized exchanges.
The rebase
method strictly adheres to a simple set of rules. Specifically, rebases:
- Occur at most once per day.
- Only occur within the block timestamp window: 2:00AM UTC - 2:20AM UTC.
- Can execute with zero supply adjustment.
Please note that block timestamps may have slight deviation from wall timestamps. Continue reading below to learn about the integration steps in greater detail.
All integration steps derive from the observation that user-balances may change in the rebase window. For centralized exchanges, there are two key things to note: 1) When a user’s balance changes on-chain it must be propagated to off-chain accounting, and 2) If a user’s balance decreases, some orders may then be unable to be filled. To safely manage this, centralized exchanges need to sequentially:
- PAUSE withdrawals and trading
- UPDATE balances
- RESUME withdrawals and trading
Below is a sample timeline of events that safely propagates supply changes to users on a centralized exchange.
1:50am UTC - AMPL deposits and withdrawals are paused
1:55am UTC - AMPL trading is paused
1:56am UTC - Begin watching for rebase event
2:04am UTC - Rebase is detected
2:06am UTC - Rebase event has passed X confirmations. Balances are updated
2:07am UTC - Trading unpaused, deposits/withdrawals unpaused
It is recommended that the exchange listens for or polls the rebase log message (LogRebase) and wait for X confirmations before applying the result.
Listening should begin with the first block whose timestamp is within the window. If the exchange listening process uses wall time, they should begin watching X minutes before window start to account for block timestamp drift.
Listening should go until at least X confirmation blocks after the last block whose timestamp is within the window. This accounts for any uncle blocks or chain reorganizations.
- Deposits and withdrawals of AMPLs should be paused X minutes before the window start. This ensures there’s no race condition between balance adjustments onchain and offchain.
- These can be unpaused after the window end or rebase transaction is confirmed, after all balances have been updated and trading has resumed.
- If there are pending withdrawals, they must either be cancelled or scaled when balances are scaled.
Note that if an incoming deposit were to happen during a pause window, the block timestamp of that deposit should be observed. Before crediting a user’s account, check if the transfer happened before or after the rebase operation, because the scaling factor may need to be applied.
If balance updates are a non-atomic operation in your infrastructure, AMPL trading should be paused before updating user balances. Every balance is then adjusted by the same, global scaling factor. The scaling factor S
is calculated as follows:
S = new_supply / old_supply
The old_supply
is the last supply that was used for exchange balance updates. This is important, in case a previous rebase event was missed. The new_supply
is simply the current totalSupply()
, X confirmations after the rebase.
AMPL trading should be paused before balance and order book updates.
- During pause window, it is recommended that trades are cancellable.
- During pause window, it is recommended that when a user tries to place a new order a helpful message is displayed.
In the case where balances decrease, there may be some open orders in the book which cannot be filled. For example:
1. Alice has 10 AMPL
2. Alice places a sell order for 9.9 AMPL
3. Supply decreases, and Alice has 9.5 AMPL
4. The sell amount is greater than Alice’s balance.
There are three options for handling these orders:
- Orders are left unchanged. When matched, they are filled as much as possible with the rest being cancelled.
- During trading pause and after balance updates, orders which cannot be filled are cancelled.
- Alice can only place orders up to X% of her balance, so the order couldn't be placed to begin with.
The first option is the least disruptive and may also be the easiest if the exchange supports margin trading. The second option can be done with a linear scan over the order book. The third option works best with "time in force" for order expiration.
To test and deploy your integration, please refer to:
For assistance, please reach out to us at dev-support@ampleforth.org