Reword content articles to use "tokens"

This replaces the old wording of "issued currencies" and introduces broader usage of the term "stablecoins" to more closely match the terminology in use by the wider industry. I've also added a draft "Common Misunderstandings about Freezes" page so that the Freeze page doesn't have to protest quite so much, and written a very brief word on tokens' use for community credit. This commit only covers the Concepts section, in English, and likely leaves some links to the old URLs for the renamed pages.
2025-11-04 11:55:50 +00:00 · 2022-02-11 17:58:39 -08:00
parent d0dd8e75b0
commit a6d9b53b61
25 changed files with 445 additions and 368 deletions
--- a/content/concepts/tokens/authorized-trust-lines.md
+++ b/content/concepts/tokens/authorized-trust-lines.md
@@ -0,0 +1,136 @@
+---
+html: authorized-trust-lines.html
+parent: tokens.html
+blurb: Authorized trust lines is a setting to limit who can hold a token.
+labels:
+  - Tokens
+  - Security
+---
+# Authorized Trust Lines
+
+The Authorized Trust Lines feature enables issuers to create tokens that can only be held by accounts that the issuer specifically authorizes. This feature only applies to tokens, not XRP.
+
+To use the Authorized Trust Lines feature, enable the `RequireAuth` flag on your issuing account. While the setting is enabled, other accounts can only hold tokens you issue if you have authorized those accounts' trust lines to your issuing account.
+
+You can authorize a trust line by sending a [TrustSet transaction][] from your issuing address, configuring the trust line between your account and the account to authorize. After you have authorized a trust line, you can never revoke that authorization. (You can, however, [freeze](freezes.html) that trust line if you need to.)
+
+The transaction to authorize a trust line must be signed by the issuing address, which unfortunately means an increased risk exposure for that address.
+
+**Caution:** You can only enable `RequireAuth` if your account has no trust lines and no Offers in the XRP Ledger, so you must decide whether or not to use it _before_ you start issuing tokens.
+
+## With Stablecoin Issuing
+
+With a stablecoin on the XRP Ledger and use Authorized Trust Lines, the process of onboarding a new customer might look something like the following:
+
+1. The customer registers with the stablecoin issuer's systems and sends proof of their identity (also known as "Know Your Customer", or KYC, information).
+2. The customer and stablecoin issuer tell each other their XRP Ledger addresses.
+3. The customer sends a [TrustSet transaction][] to create a trust line to the issuer's address, with a positive limit.
+4. The issuer sends a TrustSet transaction to authorize the customer's trust line.
+
+**Tip:** The issuer can authorize a trust line preemptively (step 3), before the customer has created it. This creates a trust line with zero limit, so that the customer's TrustSet transaction (step 2) sets the limit on the pre-authorized trust line. _(Added by the [TrustSetAuth amendment][].)_
+
+## As a Precaution
+
+Even if you don't intend to use Authorized Trust Lines, you can enable the `RequireAuth` setting on [operational and standby accounts](issuing-and-operational-addresses.html), and then never have those accounts approve any trust lines. This prevents those accounts from issuing tokens by accident (for example, if a user accidentally trusts the wrong address). This is a purely precautionary measure, and does not stop the operational and standby accounts from transferring the _issuer's_ tokens, as intended.
+
+
+## Technical Details
+<!--{# TODO: split these off into one or more tutorials on using authorized trust lines, preferably with both JavaScript and Python code samples. #}-->
+
+### Enabling RequireAuth
+
+The following is an example of using a locally-hosted `rippled`'s [submit method][] to send an [AccountSet transaction][] to enable the `RequireAuth` flag: (This method works the same way regardless of whether the address is an issuing address, operational address, or standby address.)
+
+Request:
+
+```json
+POST http://localhost:5005/
+{
+    "method": "submit",
+    "params": [
+        {
+            "secret": "s████████████████████████████",
+            "tx_json": {
+                "Account": "rUpy3eEg8rqjqfUoLeBnZkscbKbFsKXC3v",
+                "Fee": "15000",
+                "Flags": 0,
+                "SetFlag": 2,
+                "TransactionType": "AccountSet"
+            }
+        }
+    ]
+}
+```
+
+{% include '_snippets/secret-key-warning.md' %}
+<!--{#_ #}-->
+
+## Checking Whether an Account Has RequireAuth Enabled
+
+To see whether an account has the `RequireAuth` setting enabled, use the [account_info method][] to look up the account. Compare the value of the `Flags` field (in the `result.account_data` object) with the [bitwise flags defined for an AccountRoot ledger object](accountroot.html).
+
+If the result of the `Flags` value bitwise-AND the `lsfRequireAuth` flag value (`0x00040000`) is nonzero, then the account has `RequireAuth` enabled. If the result is zero, then the account has `RequireAuth` disabled.
+
+## Authorizing Trust Lines
+
+If you are using the Authorized Trust Lines feature, others cannot hold balances you issue unless you first authorize their trust lines to you. If you issue more than one currency, you must separately authorize trust lines for each currency.
+
+To authorize a trust line, submit a [TrustSet transaction][] from your issuing address, with the user to trust as the `issuer` of the `LimitAmount`. Leave the `value` (the amount to trust them for) as **0**, and enable the [`tfSetfAuth`](trustset.html#trustset-flags) flag for the transaction.
+
+The following is an example of using a locally-hosted `rippled`'s [submit method][] to send a TrustSet transaction authorizing the customer address `rf1BiGeXwwQoi8Z2ueFYTEXSwuJYfV2Jpn` to hold USD issued by the address `rsA2LpzuawewSBQXkiju3YQTMzW13pAAdW`:
+
+Request:
+
+```json
+POST http://localhost:8088/
+
+{
+    "method": "submit",
+    "params": [
+        {
+            "secret": "s████████████████████████████",
+            "tx_json": {
+                "Account": "rsA2LpzuawewSBQXkiju3YQTMzW13pAAdW",
+                "Fee": "15000",
+                "TransactionType": "TrustSet",
+                "LimitAmount": {
+                    "currency": "USD",
+                    "issuer": "rf1BiGeXwwQoi8Z2ueFYTEXSwuJYfV2Jpn",
+                    "value": 0
+                },
+                "Flags": 65536
+            }
+        }
+    ]
+}
+```
+
+{% include '_snippets/secret-key-warning.md' %}
+<!--{#_ #}-->
+
+## Checking Whether Trust Lines Are Authorized
+
+To see whether a trust line has been authorized, use the [account_lines method][] to look up the trust line. In the request, provide the customer's address in the `account` field and the issuer's address in the `peer` field.
+
+In the response's `result.lines` array, find the object whose `currency` field indicates that it represents a trust line for the currency you want. If that object has a `peer_authorized` field with the value `true`, then the issuer (the address you used as the request's `peer` field) has authorized the trust line.
+
+
+## See Also
+
+- **Concepts:**
+    - [Deposit Authorization](depositauth.html)
+    - [Freezing Issued Currencies](freezes.html)
+- **Tutorials:**
+    - [Become an XRP Ledger Gateway](become-an-xrp-ledger-gateway.html)
+- **References:**
+    - [account_lines method][]
+    - [account_info method][]
+    - [AccountSet transaction][]
+    - [TrustSet transaction][]
+    - [AccountRoot Flags](accountroot.html#accountroot-flags)
+    - [RippleState (trust line) Flags](ripplestate.html#ripplestate-flags)
+
+<!--{# common link defs #}-->
+{% include '_snippets/rippled-api-links.md' %}			
+{% include '_snippets/tx-type-links.md' %}			
+{% include '_snippets/rippled_versions.md' %}