Listing XRP as an Exchange
-This document describes the steps that an exchange needs to take to list XRP. For details about other aspects of rippled and the Ripple Consensus Ledger (RCL), see the Ripple Developer Center.
Alpha Exchange
-For illustrative purposes, this document uses a fictitious business called Alpha Exchange to explain the high-level steps required to list XRP. For the purposes of this document, Alpha Exchange:
--
-
-
-
Currently specializes in listing BTC/USD
-
- -
-
Wants to add BTC/XRP and XRP/USD trading pairs
-
- -
-
Maintains balances for all of its customers
-
- -
-
Maintains balances for each of its supported currencies
-
-
User Benefits
-Alpha Exchange wants to list BTC/XRP and XRP/USD trading pairs partially because listing these pairs will benefit its users. Specifically, this support will allow its users to:
--
-
-
-
Deposit XRP to Alpha Exchange from the RCL
-
- -
-
Withdraw XRP from Alpha Exchange to the RCL
-
- -
-
Trade XRP with other currencies, such as BTC, USD, amongst others
-
-
Prerequisites for Supporting XRP
-To support XRP, Alpha Exchange must:
--
-
-
-
Create and maintain new accounts
-
- -
-
Create and maintain balance sheets
-
-
See also:
--
-
-
-
Gateway Compliance — Gateways and exchanges are different, but exchanges should also ensure that they are complying with local regulations and reporting to the appropriate agencies.
-
- - - - -
- - - -
- - - -
Accounts
-XRP is held in accounts (sometimes referred to as wallets ) on the Ripple Consensus Ledger (RCL). Accounts on the RCL are different than accounts on other blockchain ledgers, such as Bitcoin, where accounts incur little to no overhead. To submit transactions (for example, OfferCreate and others used for trading), RCL accounts require XRP reserves to protect the ledger against spam and malicious usage. On other blockchains, balances are derived from the previous block. On the RCL, account objects describe several other properties of the account in addition to balances, so accounts are represented in each ledger and can never be destroyed or removed. Exchanges do not need to create accounts for each customer that holds XRP; they can store all of their customers’ XRP in just a few RCL accounts. For more information about RCL accounts, see the Accounts article.
-To comply with Ripple's recommend best practices, Alpha Exchange should create at least two new accounts on the RCL. To minimize the risks associated with a compromised secret key, Ripple recommends creating issuing, operational, and standby accounts (these are sometimes referred to, respectively, as cold, hot, and warm wallets). The operational/standby/issuing model is intended to balance security and convenience. Exchanges listing XRP should create the following accounts:
--
-
-
-
An issuing account to securely hold the majority of XRP and customers' funds. To provide optimal security, this account should be offline.
-For more information about the possible consequences of a compromised issuing account, see Issuing Account Compromise.
-
- -
-
One or more operational accounts to conduct the day-to-day business of managing customers' XRP withdrawals and deposits. For example, with an opertaitional wallet, exchanges can securely support these types of automated XRP transfers. Operational accounts need to be online to service instant withdrawal requests.
-For more information about the possible consequences of a compromised operational account, see Operational Account Compromise.
-
- -
-
Optionally, one or more standby accounts to provide an additional layer of security between the issuing and operational accounts. Unlike an operational account, the secret key of a standby account does not need to be online. Additionally, you can distribute the secret keys for the standby account to several different people and implement multisigning to increase security.
-For more information about the possible consequences of a compromised standby account, see Standby Account Compromise.
-
-
See also:
--
-
- - - -
- - - -
- - - -
- - - -
Balance Sheets
-Alpha Exchange will custody its customers' XRP, so it needs to track each customer's balance(s). To do this, Alpha Exchange must create and maintain an additional balance sheet. The following table illustrates what this balance sheet might look like.
-The new RCL accounts (Alpha Operational, Alpha Standby, Alpha Issuing) are in the User column of the XRP Balances on RCL table.
-The Alpha Exchange XRP Balances table represents new, additional balance sheet. Alpha Exchange’s software manages their users’ balances of XRP on this accounting system.
-| XRP Balances -on RCL | -- | - | Alpha Exchange -XRP Balances | -- | - |
| User | -Balance | -- | Acct # | -User | -Balance | -
| Dave | -25,000 | -- | 123 | -Alice | -0 | -
| Edward | -45,000 | -- | 456 | -Bob | -0 | -
| Charlie | -50,000 | -- | 789 | -Charlie | -0 | -
| Alpha Operational | -0 | -- | ... | -- | - |
| Alpha Standby | -0 | -- | - | - | - |
| Alpha Issuing | -0 | -- | - | - | - |
| ... | -- | - | - | - | - |
XRP Amounts
-Amounts of XRP are represented on the RCL as an unsigned integer count of drops, where one XRP == 1,000,000 drops. Ripple recommends that software store XRP balances as integer amounts of drops, and perform integer arithmetic on these values. However, user interfaces should present balances in units of XRP.
-One drop (.000001 XRP) cannot be further subdivided. Bear this in mind when calculating and displaying FX rates between XRP and other assets.
-For more informtion, see Specifying Currency Amounts.
-On-Ledger and Off-Ledger
-With exchanges like Alpha Exchange, XRP can be "on-ledger" or "off-ledger":
--
-
-
-
On-Ledger XRP: XRP that can be queried through the public RCL by specifying the public address of the XRP holder. The counterparty to these balances is the RCL. For more information, see Currencies.
-
- -
-
Off-Ledger XRP: XRP that is held by the accounting system of an exchange and can be queried through the exchange interface. Off-ledger XRP balances are credit-based. The counterparty is the exchange holding the XRP.
-Off-ledger XRP balances are traded between the participants of an exchange. To support these trades, the exchange must hold a balance of on-ledger XRP equal to the aggregate amount of off-ledger XRP that it makes available for trade.
-
-
Flow of Funds
-The remaining sections describe how funds flow through the accounts managed by Alpha Exchange as its users begin to deposit, trade, and redeem XRP balances. To illustrate the flow of funds, this document uses the tables introduced in the "Balance Sheets" section.
-There are four main steps involved in an exchange's typical flow of funds:
--
-
- - - -
- - - -
- - - -
- - - -
This list does not include the prerequisites required of an exchange.
-At this point, Alpha Exchange has created operational, standby, and issuing accounts on the RCL and added them to its balance sheet, but has not accepted any deposits from its users.
-| XRP Balances -on RCL | -- | - | Alpha Exchange -XRP Balances | -- | - |
| User | -Balance | -- | Acct # | -User | -Balance | -
| Dave | -25,000 | -- | 123 | -Alice | -0 | -
| Edward | -45,000 | -- | 456 | -Bob | -0 | -
| Charlie | -50,000 | -- | 789 | -Charlie | -0 | -
| Alpha Operational | -0 | -- | ... | -- | - |
| Alpha Standby | -0 | -- | - | - | - |
| Alpha Issuing | -0 | -- | - | - | - |
| ... | -- | - | - | - | - |
Deposit XRP into Exchange
-To track off-ledger XRP balances exchanges need to create new balance sheets (or similar accounting systems). The following table illustrates the balance changes that take place on Alpha Exchange's new balance sheet as users begin to deposit XRP.
-A user named Charlie wants to deposit 50,000 XRP to Alpha Exchange. Doing this involves the following steps:
--
-
-
-
Charlie submits a payment of 50,000 XRP (by using RippleAPI or similar software) to Alpha Exchange's issuing account.
-a. Charlie adds an identifier (in this case,
-789) to the payment to associate it with his account at Alpha Exchange. This is called a destination tag. (To use this, Alpha Exchange must have set the asfRequireDest flag on all of its accounts. This flag requires all incoming payments to have a destination tag like Charlie's. For more information, see AccountSet Flags.
- -
-
The software at Alpha Exchange detects the incoming payment, and recognizes
-789as the destination tag for Charlie’s account.
- -
-
When it detects the incoming payment, Alpha Exchange's software updates its balance sheet to indicate that the 50,000 XRP it received is controlled by Charlie.
-Charlie can now use up to 50,000 XRP on the exchange. For example, he can create offers to trade XRP with BTC or any of the other currencies Alpha Exchange supports.
-
-
| XRP Balances -on RCL | -- | - | Alpha Exchange -XRP Balances | -- | - |
| User | -Balance | -- | Acct # | -User | -Balance | -
| Dave | -25,000 | -- | 123 | -Alice | -0 | -
| Edward | -45,000 | -- | 456 | -Bob | -0 | -
| Charlie | -50,000 |
-- | 789 | -Charlie | -50,000 |
-
| - | - | - | - | - | - |
| Alpha Operational | -0 | -- | ... | -- | - |
| Alpha Standby | -0 | -- | - | - | - |
| Alpha Issuing | -50,000 |
-- | - | - | - |
| ... | -- | - | - | - | - |
Trade XRP on The Exchange
-Alpha Exchange users (like Charlie) can trade credit-based balances on Alpha Exchange. Alpha Exchange should keep track of user balances on its new balance sheet as these trades are made. These trades are off-ledger and independent from the RCL, so the balance changes are not recorded there.
-For more information about trading on the RCL, see Lifecycle of an Offer.
-Rebalance XRP Holdings
-Exchanges can adjust the balances between their operational and issuing accounts at any time. Each balance adjustment consumes a transaction fee, but does not otherwise affect the aggregate balance of all the accounts. The aggregate, on-ledger balance should always exceed the total balance available for trade on the exchange. (The excess should be sufficient to cover the RCL's transaction fees.)
-The following table demonstrates a balance adjustment of 80,000 XRP (via a payment on the RCL) between Alpha Exchange's issuing account and its operational account, where the issuing account was debited and the operational account was credited. If the payment were reversed (debit the operational account and credit the issuing account), the operational account balance would decrease. Balance adjustments like these allow an exchange to limit the risks associated with holding XRP in online operational accounts.
-| Alpha Exchange XRP -Off-Ledger Balances | -- | - | - | Alpha Exchange XRP On-Ledger Balances | -- |
| Acct # | -User | -Balance | -- | RCL Account | -Balance | -
| 123 | -Alice | -80,000 | -- | Operational | -80,000 |
-
| 456 | -Bob | -50,000 | -- | Standby | -0 | -
| …. | -- | - | - | …. | -- |
| 789 | -Charlie | -50,000 | -- | Issuing | -100,000 |
-
| - | - | - | - | - | - |
| ... | -- | - | - | ... | -- |
Withdraw XRP from Exchange
-Withdrawals allow an exchange's users to move XRP from the exchange's off-ledger balance sheet to an account on the RCL.
-In this example, Charlie withdraws 25,000 XRP from Alpha Exchange. This involves the following steps:
--
-
-
-
Charlie initiates the process on Alpha Exchange’s website. He provides instructions to transfer 25,000 XRP to a specific account on the RCL (named "Charlie RCL" in the following table).
-
- -
-
In response to Charlie’s instructions, Alpha Exchange does the following:
-a. Debits the amount (25,000 XRP) from Charlie’s account on its off-ledger balance sheet
-b. Submits a payment on the RCL for the same amount (25,000 XRP), from Alpha Exchange's operational account to Charlie’s RCL account
-
-
| RCL On-Ledger XRP Balances | -- | - | Alpha Exchange XRP -Off-Ledger Balances | -- | - | - | Alpha Exchange XRP On-Ledger Balances | -- |
| User | -Balance | -- | Acct # | -User | -Balance | -- | RCL Account | -Balance | -
| Dave | -25,000 | -- | 123 | -Alice | -80,000 | -- | Operational | -55,000 |
-
| Edward | -45,000 | -- | 456 | -Bob | -50,000 | -- | Standby | -0 | -
| …. | -- | - | …. | -- | - | - | …. | -- |
| Charlie RCL | -75,000 |
-- | 789 | -Charlie | -25,000 |
-- | Issuing | -100,000 | -
| - | - | - | - | - | - | - | - | - |
| ... | -- | - | ... | -- | - | - | ... | -- |