ARCHIVE/xrpl-dev-portal
1
0
Fork 0
mirror of https://github.com/XRPLF/xrpl-dev-portal.git synced 2025-11-28 07:35:50 +00:00
Code Issues Packages Projects Releases Wiki Activity

xrpl.js 2.0: update some 'RippleAPI' mentions

Browse Source 
Starts moving freeze example code into separate tutorial pages.
This commit is contained in:
mDuo13
2021-10-14 16:31:55 -07:00
parent 69641175ce
commit 8a33b84711
15 changed files with 644 additions and 360 deletions
Download Patch File Download Diff File Expand all files Collapse all files

5
content/_snippets/checkcash-prereqs.ja.md
View File

@@ -5,6 +5,5 @@ Checkを換金するための前提条件は、正確な金額を換金する場
- Checkに記載されている受取人の**アドレス**と**秘密鍵**。このアドレスは、Checkオブジェクトの`Destination`アドレスと一致している必要があります。
- 発行済み通貨用のCheckの場合は、ご自身（受取人）にイシュアーに対するトラストラインがある必要があります。このトラストライン上のご自身の限度額は、受け取る金額を追加するための残高より十分高くなければなりません。
- トラストラインと限度額について詳しくは、[発行済み通貨](issued-currencies.html)および[トラストラインと発行](trust-lines-and-issuing.html)を参照してください。
- トランザクションに安全に署名できる手段（[RippleAPI][]や各自の[`rippled`サーバー](install-rippled.html)など）。
- `rippled`サーバーに接続できるクライアントライブラリ（[RippleAPI][]、HTTPライブラリ、WebSocketライブラリなど）。
- 詳細は、[`rippled` APIの使用開始](get-started-using-http-websocket-apis.html)を参照してください。
- [トランザクションに安全に署名できる手段](set-up-secure-signing.html)。
- XRP Ledgerに接続できる[クライアントライブラリ](client-libraries.html)か、それとも[HTTPライブラリ、WebSocketライブラリなど](get-started-using-http-websocket-apis.html)。

5
content/_snippets/checkcash-prereqs.md
View File

@@ -5,6 +5,5 @@ The prerequisites for cashing a check are the same whether you are cashing it fo
- The **address** and **secret key** of the Check's stated recipient. The address must match the `Destination` address in the Check object.
- If the Check is for an issued currency, you (the recipient) must have a trust line to the issuer. Your limit on that trust line must be enough higher than the balance to add the amount you would receive.
- For more information on trust lines and limits, see [Issued Currencies](issued-currencies.html) and [Trust Lines and Issuing](trust-lines-and-issuing.html).
- A secure way to sign transactions, such as [RippleAPI][] or your own [`rippled` server](install-rippled.html).
- A client library that can connect to a `rippled` server, such as [RippleAPI][] or any HTTP or WebSocket library.
- For more information, see [Get Started with the `rippled` API](get-started-using-http-websocket-apis.html).
- A [secure way to sign transactions](set-up-secure-signing.html).
- A [client library](client-libraries.html) that can connect to the XRP Ledger, or [any HTTP or WebSocket client](get-started-using-http-websocket-apis.html).

4
content/_snippets/tutorial-sign-step.ja.md
View File

@@ -1,3 +1,3 @@
トランザクションに署名する最も安全な方法は、[RippleAPI](rippleapi-reference.html)などの署名ライブラリーを使用してローカルで署名することです。[signメソッド](sign.html)を使用してトランザクションに署名することもできますが、その場合は信頼できる暗号化された接続を使用するか、ローカル接続を使用して、自分が管理しているサーバーに対してのみに行うようにしてください。
トランザクションに署名する最も安全な方法は、[クライアントライブラリ](client-libraries.html)を使用してローカルで署名することです。[signメソッド](sign.html)を使用してトランザクションに署名することもできますが、その場合は信頼できる暗号化された接続を使用するか、ローカル接続を使用して、自分が管理しているサーバーに対してのみに行うようにしてください。
いずれの場合も、後のために、署名したトランザクションの識別用ハッシュを書き留めておいてください。
いずれの場合も、後のために、署名したトランザクションの識別用ハッシュを書き留めておいてください。

2
content/_snippets/tutorial-sign-step.md
View File

@@ -1,3 +1,3 @@
The most secure way to sign a transaction is to do it locally with a signing library, such as [RippleAPI](rippleapi-reference.html). Alternatively, you can sign the transaction using the [sign method](sign.html), but this must be done through a trusted and encrypted connection, or through a local connection, and only to a server you control.
The most secure way to sign a transaction is to do it locally with a [client library](client-libraries.html). Alternatively, if you run your own `rippled` node you can sign the transaction using the [sign method](sign.html), but this must be done through a trusted and encrypted connection, or through a local (same-machine) connection.
In all cases, note the signed transaction's identifying hash for later.

2
content/concepts/consensus-network/transaction-malleability.ja.md
View File

@@ -53,7 +53,7 @@ ECDSA署名はRおよびSと呼ばれる2つの整数で構成されています
完全に正規であるECDSA署名を計算するには、SとN-Sを比較していずれが小さいかを見極めて、トランザクションの`Signature`フィールドにその値を使用する必要があります。
Rippleが公開しているすべてのXRP Ledgerソフトウェア（`rippled`およびripple-lib/RippleAPIを含む）では、完全に正規である署名のみが生成されます。ユーザーの保護を強化するため、Rippleは、可能な限りデフォルトで**tfFullyCanonicalSig**フラグを有効にするようにコードを構成しています。XRP Ledgerソフトウェアのサードパーティ実装においても、完全に正規である署名だけを生成し、デフォルトでトランザクションのtfFullyCanonicalSigが有効にすることを強く推奨します。
Rippleが公開しているすべてのXRP Ledgerソフトウェア（`rippled`およびripple-lib/xrpl.jsを含む）では、完全に正規である署名のみが生成されます。ユーザーの保護を強化するため、Rippleは、可能な限りデフォルトで**tfFullyCanonicalSig**フラグを有効にするようにコードを構成しています。XRP Ledgerソフトウェアのサードパーティ実装においても、完全に正規である署名だけを生成し、デフォルトでトランザクションのtfFullyCanonicalSigが有効にすることを強く推奨します。
次の2つの状況においては、RippleのXRP Ledgerの署名実装によってtfFullyCanonicalSigフラグが自動的に有効になりません。次の状況では、フラグを慎重に設定する必要があります。

2
content/concepts/introduction/software-ecosystem.ja.md
View File

@@ -32,7 +32,7 @@ XRP Ledgerの中心であるピアツーピアネットワークは、コンセ
プログラミングライブラリーは、XRP Ledgerデータにアクセスするために必ずしも必要なわけではありません。HTTPまたはWebSocketを使用すれば、[`rippled` API](rippled-api.html)に直接接続できるためです。ライブラリーは、`rippled` APIにアクセスする際の一般的な作業の一部を簡素化し、データをライブラリー内のプログラミング言語で理解しやすく、かつプログラミングしやすい形式に変換します。
[JavaScript用のRippleAPI](get-started-with-rippleapi-for-javascript.html)（「ripple-lib」とも呼ばれる）は、長年にわたって使用され、かつ十分なサポートがある、XRP Ledgerにアクセスするためのライブラリーです。多くの[ミドルウェアサービス](#ミドルウェア)が、RippleAPIのようなプログラミングライブラリーを内部で使用しています。
[JavaScript用のxrpl.js](get-started-with-rippleapi-for-javascript.html)は、長年にわたって使用され、かつ十分なサポートがある、XRP Ledgerにアクセスするためのライブラリーです。多くの[ミドルウェアサービス](#ミドルウェア)が、このような[プログラミングライブラリー](client-libraries.html)を内部で使用しています。
### ミドルウェア

4
content/concepts/introduction/software-ecosystem.md
View File

@@ -32,9 +32,9 @@ This server exposes [`rippled` APIs](rippled-api.html) for users to look up data
### Programming Libraries
Programming libraries are not strictly required to access XRP Ledger data, since you can use HTTP or WebSocket to connect to the [`rippled` APIs](rippled-api.html) directly. Libraries simplify some of the common work of accessing the `rippled` APIs, and convert the data into forms that are easier to understand and program with in the programming language of the library.
[Programming libraries](client-libraries.html) are not strictly required to access XRP Ledger data, since you can use HTTP or WebSocket to connect to the [`rippled` APIs](rippled-api.html) directly. Libraries simplify some of the common work of accessing the `rippled` APIs, and convert the data into forms that are easier to understand and program with in the programming language of the library.
[RippleAPI for JavaScript](get-started-with-rippleapi-for-javascript.html) (also called "ripple-lib") is the longest-standing, most well-supported library for accessing the XRP Ledger. Many [middleware services](#middleware) use programming libraries like RippleAPI internally.
[xrpl.js for JavaScript](get-started-with-rippleapi-for-javascript.html) (formerly called "ripple-lib") is the longest-standing, most well-supported library for accessing the XRP Ledger. Many [middleware services](#middleware) use programming libraries like this internally.
### Middleware

2
content/concepts/issued-currencies/authorized-trust-lines.ja.md
View File

@@ -22,7 +22,7 @@ Authorized Trust Lines機能を使用するには、発行アドレスでRequire
## RequireAuth設定
`RequireAuth`設定（[RippleAPI](rippleapi-reference.html)の`requireAuthorization`）をすることで、発行アドレスが当該通貨に関してその取引相手とのトラストラインを具体的に承認している場合を除き、すべての取引相手はアドレスから発行された残高を保有できなくなります。
`RequireAuth`設定をすることで、発行アドレスが当該通貨に関してその取引相手とのトラストラインを具体的に承認している場合を除き、すべての取引相手はアドレスから発行された残高を保有できなくなります。
用心として、発行ゲートウェイが[運用アドレスとスタンバイアドレス](issuing-and-operational-addresses.html)に対して`RequireAuth`を常に有効にし、これらのアドレスへのトラストラインを一切承認しないことが推奨されます。これにより、運用アドレスとスタンバイアドレスがXRP Ledgerで誤って通貨を発行することを防止できます。これは純粋な予防措置であり、発行アドレスにより作成された発行済み通貨の残高を、これらのアドレスが意図したとおりに送金することを阻止するものではありません。

2
content/concepts/issued-currencies/authorized-trust-lines.md
View File

@@ -24,7 +24,7 @@ The transaction to authorize a trust line must be signed by the issuing address,
<!-- SPELLING_IGNORE: requireauth -->
The `RequireAuth` setting (`requireAuthorization` in [RippleAPI](rippleapi-reference.html)) prevents all counterparties from holding balances issued by an address unless the issuing address has specifically approved a trust line with that counterparty for the currency in question.
The `RequireAuth` setting prevents all counterparties from holding balances issued by an address unless the issuing address has specifically approved a trust line with that counterparty for the currency in question.
As a precaution, Ripple recommends that issuing gateways always enable `RequireAuth` on [operational addresses and standby addresses](issuing-and-operational-addresses.html), and then never approve any trust lines to those addresses. This prevents operational addresses and standby addresses from issuing currency in the XRP Ledger even by accident. This is a purely precautionary measure, and does not stop those addresses from transferring issued currency balances created by the issuing address, as they are intended to do.

349
content/concepts/issued-currencies/freezes.md
View File

@@ -15,7 +15,7 @@ All non-XRP currencies can be represented in the XRP Ledger as issued currencies
In certain cases, to meet regulatory requirements, or while investigating suspicious activity, an exchange or gateway may want to quickly freeze non-XRP issued currency balances.
**Tip:** No one can freeze XRP.
**Tip:** No one can freeze XRP in the XRP Ledger. However, custodial exchanges can always freeze the funds they custody at their own discretion.
There are three settings related to freezes:
@@ -85,352 +85,15 @@ The No Freeze setting applies to all currencies issued to and from an address. I
You can only enable the No Freeze setting with a transaction signed by your address's master key secret. You cannot use a [Regular Key](setregularkey.html) or a [multi-signed transaction](multi-signing.html) to enable No Freeze.
# Technical Details
## Enabling or Disabling Individual Freeze
### Using `rippled`
To enable or disable Individual Freeze on a specific trust line, send a `TrustSet` transaction. Use the [`tfSetFreeze` flag](trustset.html#trustset-flags) to enable a freeze, and the `tfClearFreeze` flag to disable it. The fields of the transaction should be as follows:
| Field | Value | Description |
|--------------------------|--------|-------------|
| `Account` | String | The XRP Ledger address to enable or disable the freeze. |
| `TransactionType` | String | `TrustSet` |
| `LimitAmount` | Object | Object defining the trust line to freeze. |
| `LimitAmount`.`currency` | String | Currency of the trust line (cannot be XRP) |
| `LimitAmount`.`issuer` | String | The XRP Ledger address of the counterparty to freeze |
| `LimitAmount`.`value` | String | The amount of currency you trust this counterparty to issue to you, as a quoted number. From the perspective of a financial institution, this is typically `"0"`. |
| Flags | Number | To enable a freeze, use a value with the bit `0x00100000` (`tfSetFreeze`) enabled. To disable a freeze, use a value with the bit `0x00200000` (`tfClearFreeze`) enabled instead. |
Set the `Fee`, `Sequence`, and `LastLedgerSequence` parameters [in the typical way](transaction-basics.html#signing-and-submitting-transactions).
Example of submitting a TrustSet transaction to enable an individual freeze using the [WebSocket API](get-started-using-http-websocket-apis.html#websocket-api):
```json
{
"id": 12,
"command": "submit",
"tx_json": {
"TransactionType": "TrustSet",
"Account": "rf1BiGeXwwQoi8Z2ueFYTEXSwuJYfV2Jpn",
"Fee": "12000",
"Flags": 1048576,
"LastLedgerSequence": 18103014,
"LimitAmount": {
"currency": "USD",
"issuer": "rsA2LpzuawewSBQXkiju3YQTMzW13pAAdW",
"value": "110"
},
"Sequence": 340
},
"secret": "s████████████████████████████",
"offline": false,
"fee_mult_max": 1000
}
```
**Caution:** Never send your secret key to an untrusted server or over an insecure channel.
### Using RippleAPI
To enable or disable Individual Freeze on a specific trust line, prepare a `Trustline` transaction using the [`prepareTrustline()` method](rippleapi-reference.html#preparetrustline). The fields of the `trustline` parameter should be set as follows:
| Field | Value | Description |
|----------------|--------|-------------|
| `currency` | String | The [currency](rippleapi-reference.html#currency) of the trust line to freeze (cannot be XRP) |
| `counterparty` | String | The [XRP Ledger address](rippleapi-reference.html#address) of the counterparty |
| `limit` | String | The amount of currency you trust this counterparty to issue to you, as a quoted number. From the perspective of a financial institution, this is typically `"0"`. |
| `frozen` | Boolean | `true` to enable Individual Freeze on this trust line. `false` to disable Individual Freeze. |
The rest of the [transaction flow](rippleapi-reference.html#transaction-flow) is the same as any other transaction.
Example JavaScript (ECMAScript 6) code to enable Individual Freeze on a trust line:
```js
{% include '_code-samples/freeze/set-individual-freeze.js' %}
```
## Enabling or Disabling Global Freeze
### Using `rippled`
To enable Global Freeze on an address, send an `AccountSet` transaction with the [`asfGlobalFreeze` flag value](accountset.html#accountset-flags) in the `SetFlag` field. To disable Global Freeze, put the `asfGlobalFreeze` flag value in the `ClearFlag` field instead.
Example of submitting an AccountSet transaction to enable Global Freeze using the [WebSocket API](get-started-using-http-websocket-apis.html#websocket-api):
```json
{
"id": 12,
"command": "submit",
"tx_json": {
"TransactionType": "AccountSet",
"Account": "rf1BiGeXwwQoi8Z2ueFYTEXSwuJYfV2Jpn",
"Fee": "12000",
"Flags": 0,
"SetFlag": 7,
"LastLedgerSequence": 18122753,
"Sequence": 349
},
"secret": "s████████████████████████████",
"offline": false,
"fee_mult_max": 1000
}
```
**Caution:** Never send your secret key to an untrusted server or over an insecure channel.
### Using RippleAPI
To enable or disable Global Freeze on an address, prepare a **Settings** transaction using the [`prepareSettings()` method](rippleapi-reference.html#preparesettings). The `settings` parameter should be an object set as follows:
| Field | Value | Description |
|----------------|--------|-------------|
| `globalFreeze` | Boolean | `true` to enable a Global Freeze on this address. `false` to disable Global Freeze. |
The rest of the [transaction flow](rippleapi-reference.html#transaction-flow) is the same as any other transaction.
Example JavaScript (ECMAScript 6) code to enable Global Freeze on an address:
```js
{% include '_code-samples/freeze/set-global-freeze.js' %}
```
## Enabling No Freeze
### Using `rippled`
To enable No Freeze on an address, send an `AccountSet` transaction with the [`asfNoFreeze` flag value](accountset.html#accountset-flags) in the `SetFlag` field. You must sign this transaction using the master key. Once enabled, you cannot disable No Freeze.
Example of submitting an AccountSet transaction to enable No Freeze using the [WebSocket API](get-started-using-http-websocket-apis.html#websocket-api):
WebSocket request:
```json
{
"id": 12,
"command": "submit",
"tx_json": {
"TransactionType": "AccountSet",
"Account": "raKEEVSGnKSD9Zyvxu4z6Pqpm4ABH8FS6n",
"Fee": "12000",
"Flags": 0,
"SetFlag": 6,
"LastLedgerSequence": 18124917,
"Sequence": 4
},
"secret": "s████████████████████████████",
"offline": false,
"fee_mult_max": 1000
}
```
**Caution:** Never send your secret key to an untrusted server or over an insecure channel.
### Using RippleAPI
To enable No Freeze on an address, prepare a **Settings** transaction using the [`prepareSettings() method`](rippleapi-reference.html#preparesettings). Once enabled, you cannot disable No Freeze. The `settings` parameter should be an object set as follows:
| Field | Value | Description |
|------------|---------|-------------|
| `noFreeze` | Boolean | `true` |
You must [sign](rippleapi-reference.html#sign) this transaction using the master key. The rest of the [transaction flow](rippleapi-reference.html#transaction-flow) is the same as any other transaction.
Example JavaScript (ECMAScript 6) code to enable No Freeze on an address:
```js
{% include '_code-samples/freeze/set-no-freeze.js' %}
```
## Checking for Individual Freeze
### Using `rippled`
To see if a trust line has an Individual Freeze enabled, use the [account_lines method][] with the following parameters:
| Field | Value | Description |
|----------------|--------|-------------|
| `account` | String | The XRP Ledger address of the issuer |
| `peer` | String | The XRP Ledger address of the counterparty |
| `ledger_index` | String | Use `validated` to get the most recently validated information. |
The response contains an array of trust lines, for each currency in which the issuing address and the counterparty are linked. Look for the following fields in each trust line object:
| Field | Value | Description |
|---------------|---------|-------------|
| `freeze` | Boolean | (May be omitted) `true` if the issuing address has frozen this trust line. If omitted, that is the same as `false`. |
| `freeze_peer` | Boolean | (May be omitted) `true` if the counterparty has frozen this trust line. If omitted, that is the same as `false`. |
Example WebSocket request to check for individual freeze:
```json
{
"id": 15,
"command": "account_lines",
"account": "rf1BiGeXwwQoi8Z2ueFYTEXSwuJYfV2Jpn",
"ledger": "validated",
"peer": "rsA2LpzuawewSBQXkiju3YQTMzW13pAAdW"
}
```
Example WebSocket response:
```json
{
"id": 15,
"status": "success",
"type": "response",
"result": {
"account": "rf1BiGeXwwQoi8Z2ueFYTEXSwuJYfV2Jpn",
"lines": [
{
"account": "rsA2LpzuawewSBQXkiju3YQTMzW13pAAdW",
"balance": "10",
"currency": "USD",
"freeze": true,
"limit": "110",
"limit_peer": "0",
"peer_authorized": true,
"quality_in": 0,
"quality_out": 0
}
]
}
}
```
The field `"freeze": true` indicates that `rf1BiGeXwwQoi8Z2ueFYTEXSwuJYfV2Jpn` has enabled Individual Freeze on the USD trust line to `rsA2LpzuawewSBQXkiju3YQTMzW13pAAdW`. The lack of a field `"freeze_peer": true` indicates that the counterparty has _not_ frozen the trust line.
### Using RippleAPI
To see if a trust line has an Individual Freeze enabled, use the [`getTrustlines` method](rippleapi-reference.html#gettrustlines) with the following parameters:
| Field | Value | Description |
|---------------|---------|-------------|
| address | String | The XRP Ledger address of the issuer |
| options.counterparty | String | The XRP Ledger address of the counterparty |
The response contains an array of trust lines, for each currency in which the issuing address and the counterparty are linked. Look for the following fields in each trust line object:
| Field | Value | Description |
|----------------------|---------|-------------|
| specification.frozen | Boolean | (May be omitted) `true` if the issuing address has frozen the trust line. |
| counterparty.frozen | Boolean | (May be omitted) `true` if the counterparty has frozen the trust line. |
Example JavaScript (ECMAScript 6) code to check whether a trust line is frozen:
```js
{% include '_code-samples/freeze/check-individual-freeze.js' %}
```
## Checking for Global Freeze and No Freeze
### Using `rippled`
To see if an address has enabled Global Freeze, No Freeze, or both, use the [account_info method][] with the following parameters:
| Field | Value | Description |
|----------------|--------|-------------|
| `account` | String | The XRP Ledger address of the issuing address |
| `ledger_index` | String | Use `validated` to get the most recently validated information. |
Check the value of the `account_data.Flags` field of the response using the [bitwise-AND](https://en.wikipedia.org/wiki/Bitwise_operation#AND) operator:
* If `Flags` AND `0x00400000` ([`lsfGlobalFreeze`](accountroot.html#accountroot-flags)) is _nonzero_: Global Freeze is enabled.
* If `Flags` AND `0x00200000` ([`lsfNoFreeze`](accountroot.html#accountroot-flags)) is _nonzero_: No Freeze is enabled.
Example WebSocket request:
```json
{
"id": 1,
"command": "account_info",
"account": "rf1BiGeXwwQoi8Z2ueFYTEXSwuJYfV2Jpn",
"ledger_index": "validated"
}
```
WebSocket response:
```json
{
"id": 4,
"status": "success",
"type": "response",
"result": {
"account_data": {
"Account": "rf1BiGeXwwQoi8Z2ueFYTEXSwuJYfV2Jpn",
"AccountTxnID": "41320138CA9837B34E82B3B3D6FB1E581D5DE2F0A67B3D62B5B8A8C9C8D970D0",
"Balance": "100258663",
"Domain": "6D64756F31332E636F6D",
"EmailHash": "98B4375E1D753E5B91627516F6D70977",
"Flags": 12582912,
"LedgerEntryType": "AccountRoot",
"MessageKey": "0000000000000000000000070000000300",
"OwnerCount": 4,
"PreviousTxnID": "41320138CA9837B34E82B3B3D6FB1E581D5DE2F0A67B3D62B5B8A8C9C8D970D0",
"PreviousTxnLgrSeq": 18123095,
"Sequence": 352,
"TransferRate": 1004999999,
"index": "13F1A95D7AAB7108D5CE7EEAF504B2894B8C674E6D68499076441C4837282BF8",
"urlgravatar": "http://www.gravatar.com/avatar/98b4375e1d753e5b91627516f6d70977"
},
"ledger_hash": "A777B05A293A73E511669B8A4A45A298FF89AD9C9394430023008DB4A6E7FDD5",
"ledger_index": 18123249,
"validated": true
}
}
```
In the above example, the `Flags` value is 12582912. This indicates that has the following flags enabled: `lsfGlobalFreeze`, `lsfDefaultRipple`, as demonstrated by the following JavaScript code:
```js
var lsfGlobalFreeze = 0x00400000;
var lsfNoFreeze = 0x00200000;
var currentFlags = 12582912;
console.log(currentFlags & lsfGlobalFreeze); //4194304
//therefore, Global Freeze is enabled
console.log(currentFlags & lsfNoFreeze); //0
//therefore, No Freeze is not enabled
```
### Using RippleAPI
To see if an address has enabled Global Freeze, No Freeze, or both, use the [`getSettings` method](rippleapi-reference.html#getsettings) with the following parameters:
| Field | Value | Description |
|---------------|---------|-------------|
| address | String | The XRP Ledger address of the issuing address |
Look for the following values in the response object:
| Field | Value | Description |
|----------------|---------|-------------|
| `noFreeze` | Boolean | (May be omitted) `true` if No Freeze is enabled. |
| `globalFreeze` | Boolean | (May be omitted) `true` if Global Freeze is enabled. |
Example JavaScript (ECMAScript 6) code to check whether an address has Global Freeze or No Freeze enabled:
```js
{% include '_code-samples/freeze/check-global-freeze-no-freeze.js' %}
```
# See Also
- [GB-2014-02 New Feature: Balance Freeze](https://ripple.com/files/GB-2014-02.pdf)
- [Freeze Code Samples](https://github.com/XRPLF/xrpl-dev-portal/tree/master/content/_code-samples/freeze)
- **Tutorials:**
- [Enable No Freeze](enable-no-freeze.html)
- [Enact Global Freeze](enact-global-freeze.html)
- [Freeze a Trust Line](freeze-a-trust-line.html)
- **References:**
- [account_lines method][]
- [account_info method][]

154
content/tutorials/use-tokens/enable-no-freeze.md Normal file
View File

@@ -0,0 +1,154 @@
---
html: enable-no-freeze.html
parent: use-tokens.html
blurb: Permanently give up your account's ability to freeze tokens it issues.
filters:
- include_code
labels:
- Tokens
---
# Enable No Freeze
If you [issue tokens](issued-currencies.html) in the XRP Ledger, can enable the [No Freeze setting](freezes.html#no-freeze) to permanently limit your own ability to use the token freezing features of the XRP Ledger. (As a reminder, this only applies to issued tokens, not XRP.) This tutorial shows how to enable the No Freeze setting on your issuing account.
## Prerequisites
- You need a connection to the XRP Ledger network. As shown in this tutorial, you can use public servers for testing.
- You should be familiar with the Getting Started instructions for your preferred client library. This page provides examples for the following:
- **JavaScript** with the [xrpl.js library](https://github.com/XRPLF/xrpl.js/). See [Get Started Using JavaScript](get-started-using-javascript.html) for setup steps.
- You don't need to have [issued a token](issue-a-fungible-token.html) in the XRP Ledger to enable No Freeze, but the main reason you would do so is if you intend to or have already issued such a token.
## Example Code
Complete sample code for all of the steps of this tutorial is available under the [MIT license](https://github.com/XRPLF/xrpl-dev-portal/blob/master/LICENSE).
- See [Code Samples: Freeze](https://github.com/XRPLF/xrpl-dev-portal/tree/master/content/_code-samples/freeze/) in the source repository for this website.
## Steps
{% set n = cycler(* range(1,99)) %}
### {{n.next()}}. Get Credentials
To transact on the XRP Ledger, you need an address and secret key, and some XRP. If you use the best practice of having separate ["cold" and "hot" addresses](issuing-and-operational-addresses.html), you need the **master keys** to the _cold address_, which is the **issuer** of the token. Only the issuer's No Freeze setting has any effect on a token.
**Caution:** You cannot use a [regular key pair](cryptographic-keys.html) or [multi-signing](multi-signing.html) to enable the No Freeze setting.
### {{n.next()}}. Connect to the Network
You must be connected to the network to submit transactions to it. The following code shows how to connect to a public XRP Ledger Testnet server a supported [client library](client-libraries.html):
<!-- MULTICODE_BLOCK_START -->
_JavaScript_
{{ include_code("_code-samples/get-started/js/base.js", language="js") }}
<!-- MULTICODE_BLOCK_END -->
### {{n.next()}}. Send AccountSet Transaction
To enable the No Freeze setting, send an [AccountSet transaction][] with a `SetFlag` field containing the [`asfNoFreeze` value (`6`)](accountset.html#accountset-flags). To send the transaction, you first _prepare_ it to fill out all the necessary fields, then _sign_ it with your account's secret key, and finally _submit_ it to the network.
For example:
<!-- MULTICODE_BLOCK_START -->
_JavaScript_
{{ include_code("_code-samples/freeze/set-no-freeze.js", language="js") }}
_WebSocket_
```json
{
"id": 12,
"command": "submit",
"tx_json": {
"TransactionType": "AccountSet",
"Account": "raKEEVSGnKSD9Zyvxu4z6Pqpm4ABH8FS6n",
"Fee": "12",
"Flags": 0,
"SetFlag": 6,
"LastLedgerSequence": 18124917,
"Sequence": 4
},
"secret": "s████████████████████████████"
}
```
<!-- MULTICODE_BLOCK_END -->
***TODO: add start_with / end_before to all the include_code macros.***
### {{n.next()}}. Wait for Validation
Most transactions are accepted into the next ledger version after they're submitted, which means it may take 4-7 seconds for a transaction's outcome to be final. If the XRP Ledger is busy or poor network connectivity delays a transaction from being relayed throughout the network, a transaction may take longer to be confirmed. (For information on how to set an expiration for transactions, see [Reliable Transaction Submission](reliable-transaction-submission.html).)
### {{n.next()}}. Confirm Account Settings
After the transaction is validated, you can check your account's settings to confirm that the No Freeze flag is enabled. You can do this by calling the [account_info method][] and checking the value of the account's `Flags` field to see if the [`lsfNoFreeze` bit (`0x00200000`)](accountroot.html#accountroot-flags) is enabled.
***TODO: JS code sample for checking No Freeze***
<!-- MULTICODE_BLOCK_START -->
_WebSocket_
```json
Request:
{
"id": 1,
"command": "account_info",
"account": "rf1BiGeXwwQoi8Z2ueFYTEXSwuJYfV2Jpn",
"ledger_index": "validated"
}
Response:
{
"id": 4,
"status": "success",
"type": "response",
"result": {
"account_data": {
"Account": "rf1BiGeXwwQoi8Z2ueFYTEXSwuJYfV2Jpn",
"AccountTxnID": "41320138CA9837B34E82B3B3D6FB1E581D5DE2F0A67B3D62B5B8A8C9C8D970D0",
"Balance": "100258663",
"Domain": "6D64756F31332E636F6D",
"EmailHash": "98B4375E1D753E5B91627516F6D70977",
"Flags": 12582912,
"LedgerEntryType": "AccountRoot",
"MessageKey": "0000000000000000000000070000000300",
"OwnerCount": 4,
"PreviousTxnID": "41320138CA9837B34E82B3B3D6FB1E581D5DE2F0A67B3D62B5B8A8C9C8D970D0",
"PreviousTxnLgrSeq": 18123095,
"Sequence": 352,
"TransferRate": 1004999999,
"index": "13F1A95D7AAB7108D5CE7EEAF504B2894B8C674E6D68499076441C4837282BF8",
"urlgravatar": "http://www.gravatar.com/avatar/98b4375e1d753e5b91627516f6d70977"
},
"ledger_hash": "A777B05A293A73E511669B8A4A45A298FF89AD9C9394430023008DB4A6E7FDD5",
"ledger_index": 18123249,
"validated": true
}
}
```
<!-- MULTICODE_BLOCK_END -->
## See Also
***TODO***
<!--{# common link defs #}-->
{% include '_snippets/rippled-api-links.md' %}
{% include '_snippets/tx-type-links.md' %}
{% include '_snippets/rippled_versions.md' %}

220
content/tutorials/use-tokens/enact-global-freeze.md Normal file
View File

@@ -0,0 +1,220 @@
---
html: enact-global-freeze.html
parent: use-tokens.html
blurb: Freeze all tokens issued by your address.
filters:
- include_code
labels:
- Tokens
---
# Enact Global Freeze
If you [issue tokens](issued-currencies.html) in the XRP Ledger, can enact a [Global Freeze](freezes.html#global-freeze) to prevent users from sending your tokens to each other and trading your token in the [decentralized exchange](decentralized-exchange.html). This tutorial shows how to enact and end a Global Freeze. You might want to do this, for example, if you see signs of suspicious activity regarding your issuing address in the ledger, or relating to off-ledger systems you use to manage your token. (For example, if your token is a stablecoin and you process withdrawals and deposits from the ledger, you may want to freeze your token while you investigate if you suspect your systems have been hacked.) You can later disable the Global Freeze setting unless you have also enabled the [No Freeze setting](freezes.html#no-freeze).
**Tip:** As a reminder, freezes only apply to issued tokens, not XRP, and do not prevent users from sending the tokens _directly_ back to the issuer.
## Prerequisites
- You need a connection to the XRP Ledger network. As shown in this tutorial, you can use public servers for testing.
- You should be familiar with the Getting Started instructions for your preferred client library. This page provides examples for the following:
- **JavaScript** with the [xrpl.js library](https://github.com/XRPLF/xrpl.js/). See [Get Started Using JavaScript](get-started-using-javascript.html) for setup steps.
- You don't need to have [issued a token](issue-a-fungible-token.html) in the XRP Ledger to enact a Global Freeze, but the main reason you would do so is if you have already issued such a token.
## Example Code
Complete sample code for all of the steps of this tutorial is available under the [MIT license](https://github.com/XRPLF/xrpl-dev-portal/blob/master/LICENSE).
- See [Code Samples: Freeze](https://github.com/XRPLF/xrpl-dev-portal/tree/master/content/_code-samples/freeze/) in the source repository for this website.
## Steps
{% set n = cycler(* range(1,99)) %}
### {{n.next()}}. Get Credentials
To transact on the XRP Ledger, you need an address and secret key, and some XRP. If you use the best practice of having separate ["cold" and "hot" addresses](issuing-and-operational-addresses.html), you need the keys to the _cold address_, which is the **issuer** of the token. Only the issuer's Global Freeze setting has any effect on a token.
**Tip:** Unlike the No Freeze setting, you _can_ enable and disable a Global Freeze using a [regular key pair](cryptographic-keys.html) or [multi-signing](multi-signing.html).
### {{n.next()}}. Connect to the Network
You must be connected to the network to submit transactions to it. The following code shows how to connect to a public XRP Ledger Testnet server a supported [client library](client-libraries.html):
<!-- MULTICODE_BLOCK_START -->
_JavaScript_
{{ include_code("_code-samples/get-started/js/base.js", language="js") }}
<!-- MULTICODE_BLOCK_END -->
### {{n.next()}}. Send AccountSet Transaction to Enact the Freeze
To enable the Global Freeze setting, send an [AccountSet transaction][] with a `SetFlag` field containing the [`asfGlobalFreeze` value (`7`)](accountset.html#accountset-flags). To send the transaction, you first _prepare_ it to fill out all the necessary fields, then _sign_ it with your account's secret key, and finally _submit_ it to the network.
**Caution:** Enacting a global freeze affects _all tokens issued by the address._ Furthermore, if you use the No Freeze setting, you cannot undo this action.
For example:
<!-- MULTICODE_BLOCK_START -->
_JavaScript_
{{ include_code("_code-samples/freeze/set-global-freeze.js", language="js") }}
_WebSocket_
```json
{
"id": "example_enable_global_freeze",
"command": "submit",
"tx_json": {
"TransactionType": "AccountSet",
"Account": "rf1BiGeXwwQoi8Z2ueFYTEXSwuJYfV2Jpn",
"Fee": "12",
"Flags": 0,
"SetFlag": 7,
"LastLedgerSequence": 18122753,
"Sequence": 349
},
"secret": "s████████████████████████████"
}
```
<!-- MULTICODE_BLOCK_END -->
***TODO: add start_with / end_before to all the include_code macros.***
### {{n.next()}}. Wait for Validation
Most transactions are accepted into the next ledger version after they're submitted, which means it may take 4-7 seconds for a transaction's outcome to be final. If the XRP Ledger is busy or poor network connectivity delays a transaction from being relayed throughout the network, a transaction may take longer to be confirmed. (For information on how to set an expiration for transactions, see [Reliable Transaction Submission](reliable-transaction-submission.html).)
### {{n.next()}}. Confirm Account Settings
After the transaction is validated, you can check your issuing account's settings to confirm that the Global Freeze flag is enabled. You can do this by calling the [account_info method][] and checking the value of the account's `Flags` field to see if the [`lsfGlobalFreeze` bit (`0x00400000`)](accountroot.html#accountroot-flags) is on.
***TODO: JS code sample for checking Global Freeze***
<!-- MULTICODE_BLOCK_START -->
_WebSocket_
```json
Request:
{
"id": 1,
"command": "account_info",
"account": "rf1BiGeXwwQoi8Z2ueFYTEXSwuJYfV2Jpn",
"ledger_index": "validated"
}
Response:
{
"id": 4,
"status": "success",
"type": "response",
"result": {
"account_data": {
"Account": "rf1BiGeXwwQoi8Z2ueFYTEXSwuJYfV2Jpn",
"AccountTxnID": "41320138CA9837B34E82B3B3D6FB1E581D5DE2F0A67B3D62B5B8A8C9C8D970D0",
"Balance": "100258663",
"Domain": "6D64756F31332E636F6D",
"EmailHash": "98B4375E1D753E5B91627516F6D70977",
"Flags": 12582912,
"LedgerEntryType": "AccountRoot",
"MessageKey": "0000000000000000000000070000000300",
"OwnerCount": 4,
"PreviousTxnID": "41320138CA9837B34E82B3B3D6FB1E581D5DE2F0A67B3D62B5B8A8C9C8D970D0",
"PreviousTxnLgrSeq": 18123095,
"Sequence": 352,
"TransferRate": 1004999999,
"index": "13F1A95D7AAB7108D5CE7EEAF504B2894B8C674E6D68499076441C4837282BF8",
"urlgravatar": "http://www.gravatar.com/avatar/98b4375e1d753e5b91627516f6d70977"
},
"ledger_hash": "A777B05A293A73E511669B8A4A45A298FF89AD9C9394430023008DB4A6E7FDD5",
"ledger_index": 18123249,
"validated": true
}
}
```
<!-- MULTICODE_BLOCK_END -->
### Intermission: While Frozen
At this point all token issued by your address are frozen. During this time, you may want to investigate the potential security breach or take a snapshot of the balances of your token, depending on your reasons for enacting the global freeze.
Keep in mind that while a token is frozen, it is still possible for the frozen token to be sent _directly to_ or _directly from_ the issuer, so you may still want to disable any systems you have that are configured to send such transactions, and you may want to track incoming transactions without processing them so that you can eventually process the legitimate ones.
If you use a [hot wallet or operational address](issuing-and-operational-addresses.html), it has no special status compared to other users, so it also cannot send and receive the frozen tokens except when dealing directly with the issuer.
If you use the [No Freeze setting](freezes.html#no-freeze) then the Global Freeze continues forever. If you want to resume issuing tokens, you must create a new account and start over from there.
Otherwise, you can continue to the next step whenever you're ready.
### {{n.next()}}. Send AccountSet Transaction to End the Freeze
To end the Global Freeze, send an [AccountSet transaction][] with a `ClearFlag` field containing the [`asfGlobalFreeze` value (`7`)](accountset.html#accountset-flags). As always, you first _prepare_ the transaction, _sign_ it, and finally _submit_ it to the network.
For example:
<!-- MULTICODE_BLOCK_START -->
_JavaScript_
{{ include_code("_code-samples/freeze/set-global-freeze.js", language="js") }}
_WebSocket_
```json
{
"id": "example_disable_global_freeze",
"command": "submit",
"tx_json": {
"TransactionType": "AccountSet",
"Account": "rf1BiGeXwwQoi8Z2ueFYTEXSwuJYfV2Jpn",
"Fee": "12",
"Flags": 0,
"ClearFlag": 7,
"LastLedgerSequence": 18122788,
"Sequence": 350
},
"secret": "s████████████████████████████"
}
```
<!-- MULTICODE_BLOCK_END -->
### {{n.next()}}. Wait for Validation
As before, wait for the previous transaction to be validated by consensus before continuing.
### {{n.next()}}. Confirm Account Settings
After the transaction is validated, you can confirm the status of the Global Freeze flag in the same way as before: by calling the [account_info method][] and checking the value of the account's `Flags` field to see if the [`lsfGlobalFreeze` bit (`0x00400000`)](accountroot.html#accountroot-flags) is **off**.
***TODO: examples***
## See Also
***TODO***
<!--{# common link defs #}-->
{% include '_snippets/rippled-api-links.md' %}
{% include '_snippets/tx-type-links.md' %}
{% include '_snippets/rippled_versions.md' %}

230
content/tutorials/use-tokens/freeze-a-trust-line.md Normal file
View File

@@ -0,0 +1,230 @@
---
html: freeze-a-trust-line.html
parent: use-tokens.html
blurb: Freeze an individual holder of a token.
filters:
- include_code
labels:
- Tokens
---
# Freeze a Trust Line
This tutorial shows the steps to [freeze an individual trust line](freezes.html#individual-freeze). The issuer of a token in the XRP Ledger may freeze the trust line to a particular counterparty if that account is engaged in suspicious activity.
**Tip:** As a reminder, freezes only apply to issued tokens, not XRP.
## Prerequisites
- You need a connection to the XRP Ledger network. As shown in this tutorial, you can use public servers for testing.
- You should be familiar with the Getting Started instructions for your preferred client library. This page provides examples for the following:
- **JavaScript** with the [xrpl.js library](https://github.com/XRPLF/xrpl.js/). See [Get Started Using JavaScript](get-started-using-javascript.html) for setup steps.
- This tutorial assumes **you have already [issued a token](issue-a-fungible-token.html)** in the XRP Ledger.
- You **cannot** have enabled the [No Freeze setting](freezes.html#no-freeze), which gives up your ability to freeze individual trust lines.
## Example Code
Complete sample code for all of the steps of this tutorial is available under the [MIT license](https://github.com/XRPLF/xrpl-dev-portal/blob/master/LICENSE).
- See [Code Samples: Freeze](https://github.com/XRPLF/xrpl-dev-portal/tree/master/content/_code-samples/freeze/) in the source repository for this website.
## Steps
{% set n = cycler(* range(1,99)) %}
### {{n.next()}}. Get Credentials
To transact on the XRP Ledger, you need an address and secret key, and some XRP. If you use the best practice of having separate ["cold" and "hot" addresses](issuing-and-operational-addresses.html), you need the keys to the _cold address_, which is the **issuer** of the token.
### {{n.next()}}. Connect to the Network
You must be connected to the network to submit transactions to it. The following code shows how to connect to a public XRP Ledger Testnet server a supported [client library](client-libraries.html):
<!-- MULTICODE_BLOCK_START -->
_JavaScript_
{{ include_code("_code-samples/get-started/js/base.js", language="js") }}
<!-- MULTICODE_BLOCK_END -->
### {{n.next()}}. Send TrustSet Transaction to Freeze the Trust Line
To enable or disable an Individual Freeze on a specific trust line, send a [TrustSet transaction][] with the [`tfSetFreeze` flag enabled](trustset.html#trustset-flags). The fields of the transaction should be as follows:
| Field | Value | Description |
|--------------------------|--------|-------------|
| `Account` | String | Your issuing account's address. |
| `TransactionType` | String | `TrustSet` |
| `LimitAmount` | Object | Object defining the trust line to freeze. |
| `LimitAmount`.`currency` | String | Currency of the trust line (cannot be XRP) |
| `LimitAmount`.`issuer` | String | The XRP Ledger address of the counterparty to freeze |
| `LimitAmount`.`value` | String | The amount of currency you trust this counterparty to issue to you, as a quoted number. As an issuer, this is typically `"0"`. |
| `Flags` | Number | To enable a freeze, turn on the `tfSetFreeze` bit (`0x00100000`). |
As always, to send a transaction, you _prepare_ it by filling in all the necessary fields, _sign_ it with your cryptographic keys, and _submit_ it to the network. For example:
***TODO: start_with / end_before on JS code sample as appropriate***
<!-- MULTICODE_BLOCK_START -->
_JavaScript_
{{ include_code("_code-samples/freeze/set-individual-freeze.js", language="js") }}
_WebSocket_
```json
{
"id": "example_freeze_individual_line",
"command": "submit",
"tx_json": {
"TransactionType": "TrustSet",
"Account": "rf1BiGeXwwQoi8Z2ueFYTEXSwuJYfV2Jpn",
"Fee": "12",
"Flags": 1048576,
"LastLedgerSequence": 18103014,
"LimitAmount": {
"currency": "USD",
"issuer": "rsA2LpzuawewSBQXkiju3YQTMzW13pAAdW",
"value": "0"
},
"Sequence": 340
},
"secret": "s████████████████████████████"
}
```
<!-- MULTICODE_BLOCK_END -->
### {{n.next()}}. Wait for Validation
Most transactions are accepted into the next ledger version after they're submitted, which means it may take 4-7 seconds for a transaction's outcome to be final. If the XRP Ledger is busy or poor network connectivity delays a transaction from being relayed throughout the network, a transaction may take longer to be confirmed. (For information on how to set an expiration for transactions, see [Reliable Transaction Submission](reliable-transaction-submission.html).)
### {{n.next()}}. Check Trust Line Freeze Status
At this point, the trust line from the counterparty should be frozen. You can check the freeze status of any trust line using the [account_lines method][] with the following fields:
| Field | Value | Description |
|:----------|:-------|:---------------------------------------------------|
| `account` | String | Your address. (In this case, the issuing address.) |
| `peer` | String | The address of the counterparty. |
**Caution:** The response includes _all_ trust lines between the two accounts. (Each different currency code uses a different trust line.) Be sure to check the one for the right token.
In the response, the field `"freeze": true` indicates that the account from the request has enabled an Individual Freeze on that trust line. The field `"freeze_peer": true` indicates that the counterparty (`peer`) from the request has frozen the trust line.
***TODO: start_with / end_before on JS code sample as appropriate***
<!-- MULTICODE_BLOCK_START -->
_JavaScript_
{{ include_code("_code-samples/freeze/check-individual-freeze.js", language="js") }}
_WebSocket_
```json
Example Request:
{
"id": "example_check_individual_freeze",
"command": "account_lines",
"account": "rf1BiGeXwwQoi8Z2ueFYTEXSwuJYfV2Jpn",
"ledger": "validated",
"peer": "rsA2LpzuawewSBQXkiju3YQTMzW13pAAdW"
}
Example Response:
{
"id": "example_check_individual_freeze",
"status": "success",
"type": "response",
"result": {
"account": "rf1BiGeXwwQoi8Z2ueFYTEXSwuJYfV2Jpn",
"lines": [
{
"account": "rsA2LpzuawewSBQXkiju3YQTMzW13pAAdW",
"balance": "10",
"currency": "USD",
"freeze": true,
"limit": "0",
"limit_peer": "110",
"quality_in": 0,
"quality_out": 0
}
]
}
}
```
<!-- MULTICODE_BLOCK_END -->
### {{n.next()}}. (Optional) Send TrustSet Transaction to End the Freeze
If you decide that the trust line no longer needs to be frozen (for example, you investigated and decided that the suspicious activity was benign), you can end the individual freeze in much the same way that you froze the trust line in the first place. To end an individual freeze, send a [TrustSet transaction][] with the [`tfClearFreeze` flag enabled](trustset.html#trustset-flags). The other fields of the transaction should be the same as when you froze the trust line:
| Field | Value | Description |
|--------------------------|--------|-------------|
| `Account` | String | Your issuing account's address. |
| `TransactionType` | String | `TrustSet` |
| `LimitAmount` | Object | Object defining the trust line to unfreeze. |
| `LimitAmount`.`currency` | String | Currency of the trust line (cannot be XRP) |
| `LimitAmount`.`issuer` | String | The XRP Ledger address of the counterparty to unfreeze |
| `LimitAmount`.`value` | String | The amount of currency you trust this counterparty to issue to you, as a quoted number. As an issuer, this is typically `"0"`. |
| `Flags` | Number | To end an individual freeze, turn on the `tfClearFreeze` bit (`0x00200000`) |
As always, to send a transaction, you _prepare_ it by filling in all the necessary fields, _sign_ it with your cryptographic keys, and _submit_ it to the network. For example:
***TODO: start_with / end_before on JS code sample as appropriate***
<!-- MULTICODE_BLOCK_START -->
_JavaScript_
{{ include_code("_code-samples/freeze/set-individual-freeze.js", language="js") }}
_WebSocket_
```json
{
"id": "example_end_individual_freeze",
"command": "submit",
"tx_json": {
"TransactionType": "TrustSet",
"Account": "rf1BiGeXwwQoi8Z2ueFYTEXSwuJYfV2Jpn",
"Fee": "12",
"Flags": 2097152,
"LastLedgerSequence": 18105115,
"LimitAmount": {
"currency": "USD",
"issuer": "rsA2LpzuawewSBQXkiju3YQTMzW13pAAdW",
"value": "0"
},
"Sequence": 341
},
"secret": "s████████████████████████████"
}
```
<!-- MULTICODE_BLOCK_END -->
### {{n.next()}}. Wait for Validation
As before, wait for the previous transaction to be validated by consensus before continuing.
## See Also
***TODO***
<!--{# common link defs #}-->
{% include '_snippets/rippled-api-links.md' %}
{% include '_snippets/tx-type-links.md' %}
{% include '_snippets/rippled_versions.md' %}