From e84890d7562e678b91fd266e9252f24921228ed0 Mon Sep 17 00:00:00 2001 From: mDuo13 Date: Thu, 7 Dec 2023 13:48:22 -0800 Subject: [PATCH] Stablecoin issuer: roll 'technical details' into other pages --- .../sending-payments-to-customers.md | 10 +- .../stablecoins/configuration.md | 9 ++ .../stablecoins/precautions.md | 57 +++++++--- .../stablecoins/technical-details.md | 105 ------------------ .../tokenization/stablecoin-issuer.md | 4 +- dactyl-config.yml | 5 - 6 files changed, 62 insertions(+), 128 deletions(-) delete mode 100644 content/concepts/tokens/fungible-tokens/stablecoins/technical-details.md diff --git a/content/concepts/payment-types/sending-payments-to-customers.md b/content/concepts/payment-types/sending-payments-to-customers.md index bfefcbe45fd..2f93118408e 100644 --- a/content/concepts/payment-types/sending-payments-to-customers.md +++ b/content/concepts/payment-types/sending-payments-to-customers.md @@ -11,14 +11,16 @@ When you build an automated system to send payments into the XRP Ledger for your Generally, when sending stablecoins, you use a [Payment transaction][]. Some of the details are different depending on whether you are issuing tokens for the first time or transferring them from a hot wallet to a customer. Things to note include: +- Always specify your issuing address as the issuer of the token. Otherwise, you might accidentally use paths that deliver the same currency issued by other addresses. +- Before sending a payment into the XRP Ledger, double check the cost of the payment. A payment from your operational address to a customer should not cost more than the destination amount plus any transfer fee you have set. - When issuing new tokens from your issuing address, you should omit the `SendMax` field. Otherwise, malicious users can arrange their settings so that you issue the full `SendMax` amount instead of just the intended destination `Amount`. - When sending tokens _from a hot wallet_, you must specify `SendMax` if you have a nonzero transfer fee. In this case, set the `SendMax` field to the amount specified in the `Amount` field plus the transfer fee. (You may want to round up slightly, in case the precision of your calculations doesn't exactly match the XRP Ledger's.) For example, if you send a transaction whose `Amount` field specifies 99.47 USD, and your transfer fee is 0.25%, you should set the `SendMax` field to 124.3375, or 124.34 USD if you round up. -- Omit the `Paths` field. This field is unnecessary when sending directly from the issuer, or from a hot wallet as long as the tokens being sent and the tokens being received have the same currency code and issuer—that is, they're the same stablecoin. The `Paths` field is intended for [Cross-Currency Payments](cross-currency-payments.html) and longer multi-hop (rippling) payments. If you naively perform pathfinding and attach the paths to your transaction, your payment may take a more expensive indirect route rather than failing if the direct path is not available; malicious users can even set this up to +- Omit the `Paths` field. This field is unnecessary when sending directly from the issuer, or from a hot wallet as long as the tokens being sent and the tokens being received have the same currency code and issuer—that is, they're the same stablecoin. The `Paths` field is intended for [Cross-Currency Payments](cross-currency-payments.html) and longer multi-hop (rippling) payments. If you naively perform pathfinding and attach the paths to your transaction, your payment may take a more expensive indirect route rather than failing if the direct path is not available; malicious users can even set this up to - If you get a `tecPATH_DRY` result code, this usually indicates that either the customer doesn't have the necessary trust line set up already, or your issuer's rippling settings aren't configured correctly. For a detailed tutorial on issuing a token on the XRP Ledger, whether a stablecoin or otherwise, see [Issue a Fungible Token](issue-a-fungible-token.html). -{% include '_snippets/rippled-api-links.md' %} -{% include '_snippets/tx-type-links.md' %} -{% include '_snippets/rippled_versions.md' %} \ No newline at end of file +{% include '_snippets/rippled-api-links.md' %} +{% include '_snippets/tx-type-links.md' %} +{% include '_snippets/rippled_versions.md' %} diff --git a/content/concepts/tokens/fungible-tokens/stablecoins/configuration.md b/content/concepts/tokens/fungible-tokens/stablecoins/configuration.md index eaa57815933..e6c2d5c2d2e 100644 --- a/content/concepts/tokens/fungible-tokens/stablecoins/configuration.md +++ b/content/concepts/tokens/fungible-tokens/stablecoins/configuration.md @@ -26,6 +26,8 @@ The Default Ripple flag controls whether the balances on a trust line are allowe Before asking customers to create trust lines to its issuing address, an issuer should enable the Default Ripple flag on that address. Otherwise, the issuer must individually disable the No Ripple flag for each trust line that other addresses have created. +You should _not_ enable the Default Ripple flag on other addresses, such as your operational or standby wallets. + ## Deposit Authorization @@ -41,6 +43,13 @@ Therefore, Deposit Authorization is not recommended for stablecoin issuers unles For more information, see [Deposit Authorization](depositauth.html). +## Disallow Incoming Trust Line + +The Disallow Incoming Trust Line setting prevents other users from opening trust lines to an address. As a precaution, you should enable this setting on your operational and standby addresses so that those addresses cannot issue tokens even inadvertently. Do not enable this setting on your issuing address. + +To enable this setting, send an [AccountSet transaction](accountset.html) with `"SetFlag": 15` (`asfDisallowIncomingTrustline`). + + ## Disallow XRP The Disallow XRP setting is designed to discourage XRP Ledger users from sending XRP to an address by accident. This reduces the costs and effort of bouncing undesired payments from addresses that aren't intended to receive and hold XRP. The Disallow XRP flag is not enforced at the protocol level, because doing so could allow addresses to become permanently unusable if they run out of XRP. Client applications should honor the Disallow XRP flag by default, but may allow users to ignore it. diff --git a/content/concepts/tokens/fungible-tokens/stablecoins/precautions.md b/content/concepts/tokens/fungible-tokens/stablecoins/precautions.md index b6b49fc4172..75929493136 100644 --- a/content/concepts/tokens/fungible-tokens/stablecoins/precautions.md +++ b/content/concepts/tokens/fungible-tokens/stablecoins/precautions.md @@ -7,17 +7,48 @@ labels: --- # Stablecoin Precautions -Processing payments to and from the XRP Ledger naturally comes with some risks, so an issuer should be sure to take care in implementing these processes. As a stablecoin issuer, you should consider the following precautions: - -- Protect yourself against reversible deposits. XRP Ledger payments are irreversible, but many digital payments are not. Scammers can abuse this to take their fiat money back by canceling a deposit after receiving tokens in the XRP Ledger. -- When sending into the XRP Ledger, always specify your issuing address as the issuer of the token. Otherwise, you might accidentally use paths that deliver the same currency issued by other addresses. -- Before sending a payment into the XRP Ledger, double check the cost of the payment. A payment from your operational address to a customer should not cost more than the destination amount plus any transfer fee you have set. -- Before processing a payment out of the XRP Ledger, make sure you know the customer's identity. This makes it harder for anonymous attackers to scam you. Most anti-money-laundering regulations require this anyway. This is especially important because the users sending money from the XRP Ledger could be different than the ones that initially received the money in the XRP Ledger. -- Follow the guidelines for reliable transaction submission when sending XRP Ledger transactions. -- Robustly monitor for incoming payments, and read the correct amount. Don't mistakenly credit someone the full amount if they only sent a [partial payment](partial-payments.html). See [Robustly monitoring for payments](robustly-monitoring-for-payments.html). +Processing payments to and from the XRP Ledger naturally comes with some risks, so an issuer should be sure to take care in implementing these processes. As a stablecoin issuer, you should consider the following precautions. + + +## Infrastructure + +For your own security as well as the stability of the network, each XRP Ledger business should [run its own XRP Ledger servers](install-rippled.html), including one [validator](rippled-server-modes.html#validators). + + +## Tool Security + +Any time you submit an XRP Ledger transaction, it must be signed using your secret key. The secret key gives full control over your XRP Ledger address. Never send your secret key to a server run by someone else. Either use your own server, or sign the transactions locally using a client library. For instructions and examples of secure configurations, see [Set Up Secure Signing](secure-signing.html). + +There are several interfaces you can use to connect to the XRP Ledger, depending on your needs and your existing software: + +- [HTTP / WebSocket APIs](http-websocket-apis.html) can be used as a low-level interface to all core XRP Ledger functionality. +- [Client Libraries](client-libraries.html) are available in several programming languages to provide convenient utilities for accessing the XRP Ledger. +- Other tools such as [xApps](https://xumm.readme.io/docs/xapps) are also available. +- Third party wallet applications might also be useful, especially for humans in charge of standby addresses. + +However, take care to only use reputable tools from their official distribution channels. Malicious servers, libraries, or apps could be configured to leak secret keys to an attacker. + + +## Payments from the XRP Ledger + +When receiving payments from the XRP Ledger, it's important to recognize when a payment is final or not, and to credit the customer for the correct amount, so that your processes and integration software can't be exploited. For details and common pitfalls, see [Robustly Monitoring for Payments](robustly-monitoring-for-payments.html). + +If you receive an unexpected or unwanted payment, the standard practice is to return it to the sender. For details of how to do this without incurring additional costs, see [Bouncing Payments](bouncing-payments.html). + +Before processing a payment out of the XRP Ledger, make sure you know the customer's identity. This makes it harder for anonymous attackers to scam you. Most anti-money-laundering regulations require this anyway. This is especially important because the users sending money from the XRP Ledger could be different than the ones that initially received the money in the XRP Ledger. For more context, see [Stablecoin Compliance Guidelines](stablecoin-compliance-guidelines.html). + + +## Payments into the XRP Ledger + +When sending payments into the XRP Ledger, follow best practices to avoid overpaying on fees and roundabout paths. For details, see [Sending Payments to Customers](sending-payments-to-customers.html). + +If you accept payments from in external systems, such as bank deposits or credit/debit payments, be sure to protect yourself against reversible deposits. XRP Ledger payments are irreversible, but many other digital payments are not. Scammers can abuse this to take their fiat money back by canceling a non-XRPL transaction after you've already sent an XRP Ledger payment. + +Additionally, follow the [Reliable Transaction Submission guidelines](reliable-transaction-submission.html) to ensure that you know the final outcome of your XRP Ledger transactions even in rare circumstances like power failures or network outages. + + +## Other precautions + - Track your obligations and balances within the XRP Ledger, and compare with the assets in your collateral account. If they do not match up, stop processing withdrawals and deposits until you resolve the discrepancy. -- Avoid ambiguous situations. We recommend the following: - - Enable the `Disallow XRP` flag for the issuing address and all operational addresses, so customers do not accidentally send you XRP. (Private exchanges should *not* set this flag, since they trade XRP normally.) - - Enable the [`RequireDest` flag](require-destination-tags.html) for the issuing address and all operational addresses, so customers do not accidentally send a payment without the destination tag to indicate who should be credited. - - Enable the `RequireAuth` flag on all operational addresses so they cannot issue tokens by accident. -- Monitor for suspicious or abusive behavior. For example, a user could repeatedly send funds into and out of the XRP Ledger, as a denial of service attack that effectively empties an operational address's balance. Suspend customers whose addresses are involved in suspicious behavior by not processing their XRP Ledger payments. \ No newline at end of file +- Avoid ambiguous situations. Setting up the appropriate settings on all your addresses helps to avoid cases like accidentally issuing tokens from the wrong address or users sending money to the wrong place. For recommendations, see [Stablecoin Configuration](stablecoin-configuration.html). +- Monitor for suspicious or abusive behavior. For example, a user could repeatedly send funds into and out of the XRP Ledger, as a denial of service attack that effectively empties an operational address's balance. Suspend customers whose addresses are involved in suspicious behavior by not processing their XRP Ledger payments. diff --git a/content/concepts/tokens/fungible-tokens/stablecoins/technical-details.md b/content/concepts/tokens/fungible-tokens/stablecoins/technical-details.md deleted file mode 100644 index f1664afe8c3..00000000000 --- a/content/concepts/tokens/fungible-tokens/stablecoins/technical-details.md +++ /dev/null @@ -1,105 +0,0 @@ ---- -html: stablecoin-technical-details.html -parent: stablecoins.html -blurb: Issue your own stablecoin, based on assets of equal value outside of the XRP Ledger. -labels: - - Tokens ---- - -# Stablecoin Technical Details - -## Infrastructure - -For your own security as well as the stability of the network, each XRP Ledger business should [run its own XRP Ledger servers](install-rippled.html), including one [validator](rippled-server-modes.html#validators). - - -### APIs and Middleware - -There are several interfaces you can use to connect to the XRP Ledger, depending on your needs and your existing software: - -- [HTTP / WebSocket APIs](http-websocket-apis.html) can be used as a low-level interface to all core XRP Ledger functionality. -- [Client Libraries](client-libraries.html) are available in several programming languages to provide convenient utilities for accessing the XRP Ledger. -- Other tools such as [xApps](https://xumm.readme.io/docs/xapps) are also available. -- Third party wallet applications might also be useful, especially for humans in charge of standby addresses. - - -## Tool Security - -Any time you submit an XRP Ledger transaction, it must be signed using your secret key. The secret key gives full control over your XRP Ledger address. Never send your secret key to a server run by someone else. Either use your own server, or sign the transactions locally using a client library. - -For instructions and examples of secure configurations, see [Set Up Secure Signing](secure-signing.html). - - -## Robustly Monitoring for Payments - -To robustly check for incoming payments, issuers should do the following: - -* Keep a record of the most-recently-processed transaction and ledger. That way, if you temporarily lose connectivity, you know how far to go back. -* Check the result code of every incoming payment. Some payments go into the ledger to charge an anti-spam fee, even though they failed. Only transactions with the result code `tesSUCCESS` can change non-XRP balances. Only transactions from a validated ledger are final. -* Look out for [Partial Payments](partial-payments.html). Payments with the partial payment flag enabled can be considered "successful" if any non-zero amount is delivered, even minuscule amounts. - * Check the transaction for a [`delivered_amount` field](partial-payments.html#the-delivered_amount-field). If present, that field indicates how much money *actually* got delivered to the `Destination` address. - * In xrpl.js, you can use the [`xrpl.getBalanceChanges()` method](https://js.xrpl.org/modules.html#getBalanceChanges) to see how much each address received. In some cases, this can be divided into multiple parts on different trust lines. -* Some transactions change your balances without being payments directly to or from one of your addresses. For example, if ACME sets a nonzero transfer fee, then ACME's issuing address's outstanding obligations decrease each time Bob and Charlie exchange ACME's tokens. - -To make things simpler for your customers, we recommend accepting payments to both your operational address and your issuing addresses. - -As an added precaution, we recommend comparing the balances of your issuing address with the collateral funds in your internal accounting system as of each new ledger version. The issuing address's negative balances should match the assets you have allocated to XRP Ledger outside the network. If the two do not match up, then you should suspend processing payments into and out of the XRP Ledger until you have resolved the discrepancy. - -* Use the `gateway_balances` method to check your balances. -* If you have a Transfer Fee set, then your obligations within the XRP Ledger decrease slightly whenever other XRP Ledger addresses transfer your tokens among themselves. - -For more details on how to read the details of incoming transactions, see [Look Up Transaction Results](look-up-transaction-results.html). - - -## Sending Payments to Customers - -When you build an automated system to send payments into the XRP Ledger for your customers, you must make sure that it constructs payments carefully. Malicious actors are constantly trying to find ways to trick a system into paying them more money than it should. - -Generally, when sending stablecoins, you use a Payment transaction. Some of the details are different depending on whether you are issuing tokens for the first time or transferring them from a hot wallet to a customer. Things to note include: - -- When issuing new tokens from your issuing address, you should omit the `SendMax` field. Otherwise, malicious users can arrange their settings so that you issue the full `SendMax` amount instead of just the intended destination `Amount`. -- When sending tokens from a hot wallet, you must specify `SendMax` if you have a nonzero transfer fee. In this case, set the `SendMax` field to the amount specified in the `Amount` field plus the transfer fee. (You may want to round up slightly, in case the precision of your calculations doesn't exactly match the XRP Ledger's. For example, if you send a transaction whose `Amount` field specifies 99.47 USD, and your transfer fee is 0.25%, you should set the `SendMax` field to 124.3375, or 124.34 USD, if you round up.) -- Omit the `Paths` field. This field is unnecessary when sending directly from the issuer, or from a hot wallet as long as the tokens being sent and the tokens being received have the same currency code and issuer—that is, they're the same stablecoin. The `Paths` field is intended for cross-currency payments and longer multi-hop (rippling) payments. If you perform pathfinding and attach the paths to your transaction, your payment might take a more expensive indirect route rather than failing if the direct path is not available; malicious users can even set this up to fail. -- If you get a `tecPATH_DRY` result code, this usually indicates that either the customer doesn't have the necessary trust line set up already, or your issuer's rippling settings aren't configured correctly. - -For a detailed tutorial on issuing a token on the XRP Ledger, whether a stablecoin or otherwise, see [Issue a Fungible Token](issue-a-fungible-token.html). - - -## Bouncing Payments - -When one of your addresses receives a payment where the purpose is unclear, we recommend that you try to return the money to its sender. While this is more work than pocketing the money, it demonstrates good faith towards customers. You can have an operator bounce payments manually, or create a system to do so automatically. - -The first requirement to bouncing payments is [robustly monitoring for incoming payments](#robustly-monitoring-for-payments). You do not want to accidentally refund a customer for more than they sent you! (This is particularly important if your bounce process is automated.) Malicious users can take advantage of a naive integration by sending [partial payments](partial-payments.html#partial-payments-exploit). - -Second, you should send bounced payments as Partial Payments. Since third parties can manipulate the cost of pathways between addresses, Partial Payments allow you to divest yourself of the full amount without being concerned about exchange rates within the XRP Ledger. You should publicize your bounced payments policy as part of your terms of use. Send the bounced payment from either an operational address or a standby address. - -To send a Partial Payment, enable the [`tfPartialPayment` flag](payment.html#payment-flags) on the transaction. Set the `Amount` field to the amount you received and omit the `SendMax` field. You should use the `SourceTag` value from the incoming payment as the `DestinationTag` value for the return payment. - -To prevent two systems from bouncing payments back and forth indefinitely, you can set a new Source Tag for the outgoing return payment. If you receive an unexpected payment whose Destination Tag matches the Source Tag of a return you sent, then do not bounce it back again. - - -## Reliable Transaction Submission - -The goal of reliably submitting transactions is to achieve the following two properties in a finite amount of time: - -* Idempotency - Transactions should be processed once and only once, or not at all. -* Verifiability - Applications can determine the final result of a transaction. - -To submit transactions reliably, follow these guidelines: - -* Persist details of the transaction before submitting it. -* Use the `LastLedgerSequence` parameter. (Many [client libraries](client-libraries.html) do this by default.) -* Resubmit a transaction if it has not appeared in a validated ledger whose [ledger index][] is less than or equal to the transaction's `LastLedgerSequence` parameter. - -For more information, see [Reliable Transaction Submission](reliable-transaction-submission.html). - - -## xrp-ledger.toml File - -You can publish information about what currencies you issue, and which XRP Ledger addresses you control, to protect against impostors or confusion, using an [`xrp-ledger.toml` file](xrp-ledger-toml.html). This machine-readable format is convenient for client applications to process. If you run an XRP Ledger validator, you can also publish the key in the same file. - - - -{% include '_snippets/rippled-api-links.md' %} -{% include '_snippets/tx-type-links.md' %} -{% include '_snippets/rippled_versions.md' %} diff --git a/content/use-cases/tokenization/stablecoin-issuer.md b/content/use-cases/tokenization/stablecoin-issuer.md index 91d92fe3829..ddb89a59a08 100644 --- a/content/use-cases/tokenization/stablecoin-issuer.md +++ b/content/use-cases/tokenization/stablecoin-issuer.md @@ -68,7 +68,9 @@ Currency codes do not have to be unique. For instance, if you're issuing a stabl ### xrp-ledger.toml -You can use the _Currencies_ table in an XRPL TOML file on your website to provide additional information about your stablecoin. This makes the information about your cryptocurrency accessible in an expected place and format, and enhances transparency. See [xrp-ledger.toml File](xrp-ledger-toml.html#currencies). +You can publish information about what currencies you issue, and which XRP Ledger addresses you control, to protect against impostors or confusion, using an `xrp-ledger.toml` file on your website. This machine-readable format is convenient for client applications to process. If you run an XRP Ledger validator, you can also publish the key in the same file. + +You can use the _Currencies_ table to provide additional information about your stablecoin. This makes the information about your cryptocurrency accessible in an expected place and format, and enhances transparency. See [xrp-ledger.toml File](xrp-ledger-toml.html#currencies). ## Account and Key Management diff --git a/dactyl-config.yml b/dactyl-config.yml index ea44705b12b..18a106f20ec 100644 --- a/dactyl-config.yml +++ b/dactyl-config.yml @@ -1095,11 +1095,6 @@ pages: - en - ja - - md: concepts/tokens/fungible-tokens/stablecoins/technical-details.md - targets: - - en - - ja - - md: concepts/tokens/fungible-tokens/clawing-back-tokens.md status: not_enabled targets: