List XAG as an Exchange

This document describes the steps that an exchange needs to take to list XAG.

Alpha Exchange

For illustrative purposes, this document uses a fictitious business called Alpha Exchange to explain the high-level steps required to list XAG. For the purposes of this document, Alpha Exchange:

  • Currently specializes in listing BTC/USD

  • Wants to add BTC/XAG and XAG/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/XAG and XAG/USD trading pairs partially because listing these pairs benefits its users. Specifically, this support wants to enable its users to:

  • Deposit XAG to Alpha Exchange from the XAG Ledger

  • Withdraw XAG from Alpha Exchange to the XAG Ledger

  • Trade XAG with other currencies, such as BTC, USD, among others

Prerequisites for Supporting XAG

To support XAG, Alpha Exchange must:

Partial Payments

Before integrating, exchanges should be aware of the partial payments feature. This feature allows XAG Ledger users to send successful payments that reduce the amount received instead of increasing the SendMax. This feature can be useful for returning payments without incurring additional cost as the sender.

Partial Payments Warning

When the tfPartialPayment flag is enabled, the Amount field is not guaranteed to be the amount received. The delivered_amount field of a payment's metadata indicates the amount of currency actually received by the destination account. When receiving a payment, use delivered_amount instead of the Amount field to determine how much your account received instead.

Warning: Be aware that malicious actors could exploit this. For more information, see Partial Payments.

Accounts

XAG is held in accounts (also referred to as wallets or addresses ) on the XAG Ledger. Accounts on the XAG Ledger are different than accounts on other blockchain ledgers, such as Bitcoin, where accounts incur little to no overhead. In the XAG Ledger, account state is stored per ledger and accounts are not easy to delete. To offset the costs associated with storing accounts, each account must hold a separate reserve of XAG that cannot be sent to others. For these reasons, Ripple recommends that institutions not create excessive or needless accounts.

To follow Ripple's recommended best practices, Alpha Exchange should create at least two new accounts on the XAG Ledger. To minimize the risks associated with a compromised secret key, Ripple recommends creating cold, hot, and warm accounts (these are sometimes referred to, respectively, as cold, hot, and warm wallets). The hot/warm/cold model is intended to balance security and convenience. Exchanges listing XAG should create the following accounts:

  • A cold wallet to securely hold the majority of XAG and customers' funds. For exchanges, this is also the address to which its users send deposits. To provide optimal security, this account's secret key should be offline.

    If a malicious actor compromises an exchange's cold wallet, the possible consequences are:

    • The malicious actor gets full access to all XAG in the cold wallet.

    • If the master key is compromised, the malicious actor can irrevocably take control of the cold wallet forever (by disabling the master key and setting a new regular key or signer list). This would also give the malicious actor control over all future XAG received by the cold wallet.

      • If this happens, the exchange has to make a new cold wallet address and tell its customers the new address.

    • If the regular key or signer list are compromised, the exchange can regain control of the cold wallet. However, some of a malicious actor's actions cannot easily be undone:

      • The malicious actor could issue currency in the XAG Ledger by using the cold wallet, but that currency should not be valued by anyone (unless the exchange explicitly stated it was also a gateway).

      • If a malicious actor sets the asfRequireAuth flag for the account, that cannot be unset, although this only relates to issuing currency and should not affect an exchange that is not also a gateway. Any other settings a malicious actor sets or unsets with a master key can be reverted.

  • One or more hot wallets to conduct the day-to-day business of managing customers' XAG withdrawals and deposits. For example, with a hot wallet, exchanges can securely support these types of automated XAG transfers. Hot wallets need to be online to service instant withdrawal requests.

    For more information about the possible consequences of a compromised hot wallet, see Operational Account Compromise.

  • Optionally, one or more warm wallets to provide an additional layer of security between the cold and hot wallets. Unlike a hot wallet, the secret key of a warm wallet does not need to be online. Additionally, you can distribute the secret keys for the warm wallet to several different people and implement multi-signing to increase security.

    For more information about the possible consequences of a compromised warm wallet, see Standby Account Compromise.

Balance Sheets

To custody its customers' XAG, Alpha Exchange must track each customer's XAG balance and its own holdings. To do this, Alpha Exchange must create and maintain an additional balance sheet or accounting system. The following table illustrates what this balance sheet might look like.

The new XAG Ledger accounts (Alpha Hot, Alpha Warm, Alpha Cold) are in the User column of the XAG Balances on XAG Ledger table.

The Alpha Exchange XAG Balances table represents new, additional balance sheet. Alpha Exchange’s software manages their users’ balances of XAG on this accounting system.

XAG Balances on XAG Ledger Alpha Exchange XAG 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 Hot 0 ...
Alpha Warm 0
Alpha Cold 0
...

XAG Amounts

Amounts of XAG are represented on the XAG Ledger as an unsigned integer count of drops, where one XAG is 1,000,000 drops. Ripple recommends that software store XAG balances as integer amounts of drops, and perform integer arithmetic on these values. However, user interfaces should present balances in units of XAG.

One drop (.000001 XAG) cannot be further subdivided. Keep this in mind when calculating and displaying FX rates between XAG and other assets.

For more information, see Specifying Currency Amounts.

On-Ledger and Off-Ledger

With exchanges like Alpha Exchange, XAG can be "on-ledger" or "off-ledger":

  • On-Ledger XAG: XAG that can be queried through the public XAG Ledger by specifying the public address of the XAG holder. The counterparty to these balances is the XAG Ledger. For more information, see XAG.

  • Off-Ledger XAG: XAG that is held by the accounting system of an exchange and can be queried through the exchange interface. Off-ledger XAG balances are credit-based. The counterparty is the exchange holding the XAG.

    Off-ledger XAG balances are traded between the participants of an exchange. To support these trades, the exchange must hold a balance of on-ledger XAG equal to the aggregate amount of off-ledger XAG 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 XAG 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:

  1. Deposit XAG into Exchange

  2. Rebalance XAG Holdings

  3. Withdraw XAG from Exchange

  4. Trade XAG on the Exchange

At this point, Alpha Exchange has created hot, warm, and cold wallets on the XAG Ledger and added them to its balance sheet, but has not accepted any deposits from its users.

XAG Balances on XAG Ledger Alpha Exchange XAG 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 Hot 0 ...
Alpha Warm 0
Alpha Cold 0
...

Deposit XAG into Exchange

To track off-ledger XAG 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 XAG.

A user named Charlie wants to deposit 50,000 XAG to Alpha Exchange. Doing this involves the following steps:

  1. Charlie submits a payment of 50,000 XAG (by using RippleAPI or similar software) to Alpha Exchange's cold wallet.

    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 should have set the asfRequireDest flag on all of its accounts to require all incoming payments to have a destination tag like Charlie's. For more information, see AccountSet Flags).

  2. The software at Alpha Exchange detects the incoming payment, and recognizes 789 as the destination tag for Charlie’s account.

  3. When it detects the incoming payment, Alpha Exchange's software updates its balance sheet to indicate that the 50,000 XAG it received is controlled by Charlie.

    Charlie can now use up to 50,000 XAG on the exchange. For example, he can create offers to trade XAG with BTC or any of the other currencies Alpha Exchange supports.

XAG Balances on XAG Ledger Alpha Exchange XAG Balances
User Balance Acct # User Balance
Dave 25,000 123 Alice 0
Edward 45,000 456 Bob 0
Charlie 100,000
50,000		 789 Charlie 0
50,000
Alpha Hot 0 ...
Alpha Warm 0
Alpha Cold 0
50,000
...

Trade XAG 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 XAG Ledger, so the balance changes are not recorded on the XAG Ledger.

Customers who hold XAG in their own XAG Ledger accounts can also use the distributed exchange built into the XAG Ledger to trade currencies issued by gateways. For more information about trading on the XAG Ledger, see Lifecycle of an Offer.

Rebalance XAG Holdings

Exchanges can adjust the balances between their hot and cold wallets at any time. Each balance adjustment consumes a transaction cost, 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 enough to cover the XAG Ledger's transaction costs.)

The following table demonstrates a balance adjustment of 80,000 XAG (via a Payment transaction on the XAG Ledger) between Alpha Exchange's cold wallet and its hot wallet, where the cold wallet was debited and the hot wallet was credited. If the payment were reversed (debiting the hot wallet and crediting the cold wallet), the hot wallet balance would decrease. Balance adjustments like these allow an exchange to limit the risks associated with holding XAG in online hot wallets.

Alpha Exchange XAG Off-Ledger Balances Alpha Exchange XAG On-Ledger Balances
Acct # User Balance XAG Ledger Account Balance
123 Alice 80,000 Hot 0
80,000
456 Bob 50,000 Warm 0
…. ….
789 Charlie 50,000 Cold 180,000
100,000
... ...

Withdraw XAG from Exchange

Withdrawals allow an exchange's users to move XAG from the exchange's off-ledger balance sheet to an account on the XAG Ledger.

In this example, Charlie withdraws 25,000 XAG from Alpha Exchange. This involves the following steps:

  1. Charlie initiates the process on Alpha Exchange’s website. He provides instructions to transfer 25,000 XAG to a specific account on the XAG Ledger (named "Charlie XAG Ledger" in the following table).

  2. In response to Charlie’s instructions, Alpha Exchange does the following:

    a. Debits the amount (25,000 XAG) from Charlie’s account on its off-ledger balance sheet

    b. Submits a payment on the XAG Ledger for the same amount (25,000 XAG), from Alpha Exchange's hot wallet to Charlie’s XAG Ledger account

XAG Ledger On-Ledger XAG Balances Alpha Exchange XAG Off-Ledger Balances Alpha Exchange XAG On-Ledger Balances
User Balance Acct # User Balance XAG Ledger Account Balance
Dave 25,000 123 Alice 80,000 Hot 80,000
55,000
Edward 45,000 456 Bob 50,000 Warm 0
…. …. ….
Charlie XAG Ledger 50,000
75,000		 789 Charlie 50,000
25,000		 Cold 100,000
... ... ...