Simple Summary
Enables an eWallet server to perform exchanges and transfers from/to different minted tokens within its own eWallet environment.
Abstract
This RFC describes the standard endpoints, flows, request/response formats, error codes needed to allow an eWallet server to perform cross-token exchanges within its own eWallet environment.
It is expected that there will be following RFCs for exchanges across eWallet environments and across the OMG network.
Motivation
Prior to this RFC, the eWallet server is able to transfer values between accounts and/or users, if and only if the from and to are of the same minted token.
One of the main purposes of the eWallet is to enable exchanges of different minted tokens. Since, different mechanisms could be used and potentially impact future integrations with centralized & decentralized exchanges, it is important for this mechanism to be put up as an RFC and discussed before implementing.
Specification
Definitions
-
Internal exchange: An exchange transaction that happens within the same eWallet environment.
-
External exchange: An exchange transaction that involves a third-party, e.g. exchanging with a centralized or decentralized exchange services. The external exchange is out of scope of this RFC.
-
Exchange pair: A pair of minted tokens that are allowed to be exchanged.
-
Same-token transfer: A transaction whose its from_address and to_address are different, but from_token_uuid and to_token_uuid are the same.
-
Exchange transaction: A transaction whose its from_address and to_address are the same, but the from_token_uuid and to_token_uuid are different.
-
Exchange transfer: A transaction whose its from_address and to_address are different, and the from_token_uuid and to_token_uuid are also different.
Data schemas
EWalletDB.ExchangePair: Contains the data about a pair of minted tokens that are allowed to be exchanged.
from_minted_token (string)to_minted_token (string)rate (float)reversible (boolean)effective_at (datetime) - so the exchange rate can be set in advance
EWalletDB.Transfer: Contains the data about each transaction that happened.
- To add:
from_amount (integer)from_token_uuid (uuid)to_amount (integer)to_token_uuid (uuid)metadata.exchange_rate (float, containing the exchange rate used for the transfer)
- To migrate:
from_amount <- amountfrom_token_uuid <- token_uuidto_amount <- amountto_token_uuid <- token_uuid
- To remove:
amount (use from_amount and to_amount instead)token_uuid (use from_token_uuid and to_token_uuid instead)
LocalLedgerDB.Transaction: A logical group of ledger entries that represents a single business event (e.g. a same-token transfer, an exchange transaction, an exchange transfer).
Each EWalletDB.Transfer item is one LocalLedgerDB.Transaction. One LocalLedgerDB.Transaction for an exchange has at least 4 LocalLedgerDB.Entry. For example:
- transaction.type = “exchange”
- transaction.metadata
- exchange_pair_id
- exchange_rate
- exchange_reversed
- transaction.entry[0], e.g. credit user 10 OMG
- transaction.entry[1], e.g. debit exchange account 10 OMG
- transaction.entry[2], e.g. credit exchange account 1 ETH
- transaction.entry[3], e.g. debit user 1 ETH
Mechanisms
For internal exchanges, the operation happens at the DB's transaction level so it should be seamlessly handled within the eWallet server as long as the exchange operations are wrapped inside a single DB transaction.
At the API level, this can be represented as a typical /transfer endpoint, where the only difference is that for exchanges, the from_token_id and to_token_id have different values.
Same-token transfers (existing feature)
- Alice has 100 AAA
- Alice wants to send 10 AAA to Bob
- Alice sends 10 AAA to Bob
- Bob receives the 10 AAA from Alice
Example:
(Assuming subunit_to_unit = 1 for simplicity)
# EWalletDB.Transfer
{
"id": "tfr_1234567890",
"type": "internal",
"from": "bal_alice_1111",
"from_amount": 10,
"from_token_id": "tok_AAA_1234",
"to": "bal_bob_2222",
"to_amount": 10,
"to_token_id": "tok_AAA_1234"
}
# LocalLedgerDB.Transaction
{
"uuid": "44d7fc38-b250-4456-a4e8-0d23dc52f310",
}
# LocalLedgerDB.Entry
[
{
"transaction_uuid": "44d7fc38-b250-4456-a4e8-0d23dc52f310",
"type": "debit",
"amount": 10,
"wallet_address": "bal_alice_1111",
"token_id": "tok_AAA_1234"
},
{
"transaction_uuid": "44d7fc38-b250-4456-a4e8-0d23dc52f310",
"type": "credit",
"amount": 10,
"wallet_address": "bal_bob_2222",
"token_id": "tok_AAA_1234"
}
]Exchange transaction (proposed by this RFC)
This is when a user wants to exchange a token for another, where the sender and the receiver is the same address.
- Alice has 100 AAA
- Alice wants to exchange 10 AAA for 1 BBB with ExchangeAccount
- Alice sends 10 AAA to ExchangeAccount
- ExchangeAccount sends 1 BBB to Alice
- If 3. or 4. fails, the transaction is reverted
Example:
(Assuming subunit_to_unit = 1 for simplicity)
# EWalletDB.Transfer
{
"id": "tfr_1234567890",
"type": "exchange",
"from": "bal_alice_1111",
"from_amount": 10,
"from_token_id": "tok_AAA_1234",
"to": "bal_alice_1111",
"to_amount": 1,
"to_token_id": "tok_BBB_1234"
}
# LocalLedgerDB.Transaction
{
"uuid": "44d7fc38-b250-4456-a4e8-0d23dc52f310",
}
# LocalLedgerDB.Entry
[
{
"transaction_uuid": "44d7fc38-b250-4456-a4e8-0d23dc52f310",
"type": "debit",
"amount": 10,
"wallet_address": "bal_alice_1111",
"token_id": "tok_AAA_1234"
},
{
"transaction_uuid": "44d7fc38-b250-4456-a4e8-0d23dc52f310",
"type": "credit",
"amount": 10,
"wallet_address": "bal_exchange_2222",
"token_id": "tok_AAA_1234"
},
{
"transaction_uuid": "44d7fc38-b250-4456-a4e8-0d23dc52f310",
"type": "debit",
"amount": 1,
"wallet_address": "bal_exchange_2222",
"token_id": "tok_BBB_1234"
},
{
"transaction_uuid": "44d7fc38-b250-4456-a4e8-0d23dc52f310",
"type": "credit",
"amount": 1,
"wallet_address": "bal_alice_1111",
"token_id": "tok_BBB_1234"
}
]Exchange transfers (proposed by this RFC)
This is when a sender wants to transfer a token and expects the receiver at a different address to receive a different token.
- Alice has 100 AAA
- Alice wants to send 1 BBB to Bob using his/her funds of 100 AAA via ExchangeAccount that has liquidity
- Bob receives the 10 OMG from Alice (via ExchangeAccount)
Example:
(Assuming subunit_to_unit = 1 for simplicity)
# EWalletDB.Transfer
{
"id": "tfr_1234567890",
"type": "exchange_transfer",
"from": "bal_alice_1111",
"from_amount": 10,
"from_token_id": "tok_AAA_1234",
"to": "bal_bob_2222",
"to_amount": 1,
"to_token_id": "tok_BBB_1234"
}
# LocalLedgerDB.Transaction
{
"uuid": "44d7fc38-b250-4456-a4e8-0d23dc52f310",
}
# LocalLedgerDB.Entry
[
{
"transaction_uuid": "44d7fc38-b250-4456-a4e8-0d23dc52f310",
"type": "debit",
"amount": 10,
"wallet_address": "bal_alice_1111",
"token_id": "tok_AAA_1234"
},
{
"transaction_uuid": "44d7fc38-b250-4456-a4e8-0d23dc52f310",
"type": "credit",
"amount": 10,
"wallet_address": "bal_exchange_3333",
"token_id": "tok_AAA_1234"
},
{
"transaction_uuid": "44d7fc38-b250-4456-a4e8-0d23dc52f310",
"type": "debit",
"amount": 1,
"wallet_address": "bal_exchange_3333",
"token_id": "tok_BBB_1234"
},
{
"transaction_uuid": "44d7fc38-b250-4456-a4e8-0d23dc52f310",
"type": "credit",
"amount": 1,
"wallet_address": "bal_bob_2222",
"token_id": "tok_BBB_1234"
}
]Rounding method
The rounding method to use is "Round half to even", or the banker's rounding.
Exchange rates
Transactions are always made with the exchange amounts, not the rate. Although an exchange transaction is based on the exchange rate, the parties agree on the exchanging amounts, not the rate. This is important because the division remainders and the rounding will almost always cause the exchanging parties to get more or less tokens depending on the rounding method used.
Consequently, the UI must display the exchanging amounts and asks user to confirm the amount, not the rate. The rate can be displayed as a complimenting information.
/exchange.calculate endpoint
Calculate the amount of minted tokens to be exchanged, used for confirming the exact amount with the user before executing the actual exchange.
- Use this endpoint to avoid discrepancies between how endpoint consumer and the server calculates the exchange amount.
- Errors are returned if it is anticipated to happen in an actual transfer.
Request
Fields
from_amount (integer, optional)from_token_id (string, required)to_amount (integer, optional)to_token_id (string, required)
Conditions
- If
from_amount is provided, to_amount will be calculated based on the exchange rate and rounding method.
- If
to_amount is provided, from_amount will be calculated based on the exchange rate and rounding method.
- If both
from_amount and to_amount are provided, and the amounts are the same as the server's calculation, a successful response is returned.
- If both
from_amount and to_amount are provided, but the amounts are different from the server's calculation, an exchange:invalid_rate response is returned.
Example
{
"from_amount": 100,
"from_token_id": "tok_AAA_1234",
"to_amount": 100,
"to_token_id": "tok_BBB_1234"
}Response
{
"version": "1",
"success": true,
"data": {
"object": "exchange_calculation",
"from_amount": 100,
"from_token_id": "tok_AAA_1234",
"to_amount": 100,
"to_token_id": "tok_BBB_1234",
"exchange_pair": "exg_AAA_BBB_123456",
"exchange_rate": "1.00",
"exchange_reversed": false
}
}/transfer endpoint
Exchange a certain amount of minted tokens between two addresses.
Request
Fields
from_amount (integer, optional)from_token_id (string, required)from_address (string, required)to_amount (integer, optional)to_token_id (string, required)to_address (string, required)exchange_account_id (string, optional)
The request may be sent without from_amount or to_amount and subjects to the same conditions as /exchange.calculate.
If the exchange_account_id is not provided, the exchange will be performed with the master account.
Example
{
"from_token_id": "tok_AAA_1234",
"from_address": "81e75f46-ee14-4e4c-a1e5-cddcb26dce9c",
"to_amount": 100,
"to_token_id": "tok_BBB_1234",
"to_address": "4aa07691-2f99-4cb1-b36c-50763e2d2ba8",
"exchange_account_id": "acc_01ca2p8jqans5aty5gj5etmjcf",
"metadata": {},
"encrypted_metadata": {}
}Response
Use the current response format (returns a list of affected wallets).
Error codes
transaction:insufficient_funds - when requestor does not have enough funds to exchange.exchange:insufficient_funds - when the counterparty does not have enough funds to exchange back. It is important to distinguish between the user and the counterparty so that user-friendly error message can be displayed, and the user knows if its the counterparty's funds or theirs that is insufficient.exchange:pair_not_found - when request requires an exchange pair that does not exist.exchange:pair_not_reversible - when request requires an exchange pair that exists, but the pair does not allow to be exchanged in the opposite direction.exchange:invalid_rate - when the provided exchange amounts or the exchange rate is invalid.
Rationale
-
Round-half-to-even or banker's rounding is used as it is commonly used in financial systems. It is also the default rounding mode for IEEE 754 (IEEE Standard for Floating-Point Arithmetic).
-
The exchange account defaults to the master account (the top-level account) for ease of use. However, for larger use cases, it's expected that an exchange_account_id is provided as it's probably not ideal for all exchange transactions to go through the master account (for separation of concerns and accountability). This exchange_account_id would also allow for more use cases, e.g. dedicate an account as the exchange account and put funds in there. It is then possible to limit the amount of tokens that can be exchanged by limiting the funds that the account has.
-
This RFC chose to reuse the /transfer endpoint because of its similarities to an exchange transaction and exchange transfer. An exchange transaction is basically a transfer of different tokens to the same address, while an exchange transfer can be represented by a transfer that has different from/to tokens.
-
There could be a discrepancy between the time /exchange.calculate is made and when /transfer happens. Given that this is an internal exchange and exchange rates are fixed, unchanged for most of the time. The discrepancy will be very rare to occur.
References
Mostly from internal discussions. Any suggestions for the references (either for or against this RFC) is appreciated.
React
Typescript
Django
Laravel
Facebook
Microsoft
Google
Alibaba
D3
Tencent