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

Update configuration topics

Browse Source
This commit is contained in:
ddawson
2023-01-31 17:11:28 -08:00
parent 3a36ce209a
commit 659b676770
24 changed files with 155 additions and 90 deletions
Download Patch File Download Diff File Expand all files Collapse all files

9
content/tutorials/build-apps/build-a-desktop-wallet-in-python.md
View File

@@ -553,4 +553,11 @@ Now that you have a functional wallet, you can take it in several new directions
- Example code for displaying token balances and other objects: [`7_owned_objects.py`]({{target.github_forkurl}}/tree/{{target.github_branch}}/content/_code-samples/build-a-wallet/py/7_owned_objects.py)
- Allow the user to trade in the [decentralized exchange](decentralized-exchange.html)
- Add a way to request payments, such as with QR codes or URIs that open in your wallet.
- Support better account security including [regular key pairs](cryptographic-keys.html#regular-key-pair) or [multi-signing](multi-signing.html).
- Support better account security including [regular key pairs](cryptographic-keys.html#regular-key-pair) or [multi-signing](multi-signing.html).
<!--{# common link defs #}-->
{% include '_snippets/rippled-api-links.md' %}
{% include '_snippets/tx-type-links.md' %}
{% include '_snippets/rippled_versions.md' %}

6
content/tutorials/get-started/get-started-using-http-websocket-apis.md
View File

@@ -108,3 +108,9 @@ For a full list of API methods, see:
- [Manage the rippled Server](manage-the-rippled-server.html)
- **References:**
- [rippled API Reference](http-websocket-apis.html)
<!--{# common link defs #}-->
{% include '_snippets/rippled-api-links.md' %}
{% include '_snippets/tx-type-links.md' %}
{% include '_snippets/rippled_versions.md' %}

7
content/tutorials/get-started/get-started-using-java.md
View File

@@ -219,3 +219,10 @@ Now that you know how to use `xrpl4j` to connect to the XRP Ledger, generate a w
* [Send XRP](send-xrp.html).
* [Set up secure signing](set-up-secure-signing.html) for your account.
<!--{# common link defs #}-->
{% include '_snippets/rippled-api-links.md' %}
{% include '_snippets/tx-type-links.md' %}
{% include '_snippets/rippled_versions.md' %}

8
content/tutorials/get-started/get-started-using-javascript.md
View File

@@ -166,3 +166,11 @@ Now that you know how to use `xrpl.js` to connect to the XRP Ledger, generate a
- [API Conventions](api-conventions.html)
- [base58 Encodings](base58-encodings.html)
- [Transaction Formats](transaction-formats.html)
<!--{# common link defs #}-->
{% include '_snippets/rippled-api-links.md' %}
{% include '_snippets/tx-type-links.md' %}
{% include '_snippets/rippled_versions.md' %}

7
content/tutorials/get-started/get-started-using-python.md
View File

@@ -225,3 +225,10 @@ Now that you know how to use `xrpl-py` to connect to the XRP Ledger, generate a
* [Send XRP](send-xrp.html).
* [Set up secure signing](set-up-secure-signing.html) for your account.
<!--{# common link defs #}-->
{% include '_snippets/rippled-api-links.md' %}
{% include '_snippets/tx-type-links.md' %}
{% include '_snippets/rippled_versions.md' %}

9
content/tutorials/get-started/get-started.md
View File

@@ -114,4 +114,11 @@ When you're ready to move on, continue using the XRP Ledger with these resources
- [Send XRP](send-xrp.html) to send your first transaction.
- [Understand the Concepts](concepts.html) behind the XRP Ledger's design.
- [Install `rippled`](install-rippled.html) to participate in the network.
- [Get Testnet XRP](xrp-testnet-faucet.html) to try sending and receiving payments.
- [Get Testnet XRP](xrp-testnet-faucet.html) to try sending and receiving payments.
<!--{# common link defs #}-->
{% include '_snippets/rippled-api-links.md' %}
{% include '_snippets/tx-type-links.md' %}
{% include '_snippets/rippled_versions.md' %}

7
content/tutorials/get-started/monitor-incoming-payments-with-websocket.md
View File

@@ -502,3 +502,10 @@ _Go_
- [Transaction Types](transaction-types.html)
- [Transaction Metadata](transaction-metadata.html) - Summary of the metadata format and fields that appear in metadata
- [Transaction Results](transaction-results.html) - Tables of all possible result codes for transactions.
<!--{# common link defs #}-->
{% include '_snippets/rippled-api-links.md' %}
{% include '_snippets/tx-type-links.md' %}
{% include '_snippets/rippled_versions.md' %}

6
content/tutorials/get-started/public-servers.md
View File

@@ -26,3 +26,9 @@ If you don't run your own `rippled` server, you can use the following public ser
<a id="footnote-2"></a>² `xrpl.ws` is an alias for `xrplcluster.com`. However, the `.ws` top-level domain's reliability may be unsuitable for production uses.
<!--{# common link defs #}-->
{% include '_snippets/rippled-api-links.md' %}
{% include '_snippets/tx-type-links.md' %}
{% include '_snippets/rippled_versions.md' %}

7
content/tutorials/get-started/send-xrp.md
View File

@@ -417,3 +417,10 @@ After completing this tutorial, you may want to try the following:
- Learn how [Transaction Metadata](transaction-metadata.html) describes the outcome of a transaction in detail.
- Explore more [Payment Types](payment-types.html) such as Escrows and Payment Channels.
- Read best practices for [XRP Ledger Businesses](xrp-ledger-businesses.html).
<!--{# common link defs #}-->
{% include '_snippets/rippled-api-links.md' %}
{% include '_snippets/tx-type-links.md' %}
{% include '_snippets/rippled_versions.md' %}

19
content/tutorials/manage-account-settings/assign-a-regular-key-pair.md
View File

@@ -8,16 +8,15 @@ labels:
---
# Assign a Regular Key Pair
The XRP Ledger allows an account to authorize a secondary key pair, called a _[regular key pair](cryptographic-keys.html)_, to sign future transactions. If the private key of a regular key pair is compromised, you can remove or replace it without changing the rest of your [account](accounts.html) and re-establishing its relationships to other accounts. You can also rotate a regular key pair proactively. (Neither of those things is possible for the master key pair of an account, which is intrinsically linked to the account's address.)
The XRP Ledger allows an account to authorize a secondary key pair, called a _[regular key pair](cryptographic-keys.html)_, to sign future transactions. If the private key of a regular key pair is compromised, you can remove or replace it without changing the rest of your account and re-establishing its relationships to other accounts. You can also rotate a regular key pair proactively. (Neither of those things is possible for the master key pair of an account, which is intrinsically linked to the account's address.)
For more information about master and regular key pairs, see [Cryptographic Keys](cryptographic-keys.html).
This tutorial walks through the steps required to assign a regular key pair to your account:
1. [Generate a key pair](#1-generate-a-key-pair)
2. [Assign the key pair to your account as a regular key pair](#2-assign-the-key-pair-to-your-account-as-a-regular-key-pair)
3. [Verify the regular key pair](#3-verify-the-regular-key-pair)
4. [Explore next steps](#see-also)
1. Generate a Key Pair
2. Assign the Key Pair to Your Account as a Regular Key Pair
3. Verify the Regular Key Pair
## 1. Generate a Key Pair
@@ -703,11 +702,7 @@ Now that you're familiar with the benefits of assigning a regular key pair to an
- [SetRegularKey transaction][]
- [AccountRoot object](accountroot.html) where the regular key is stored in the field `RegularKey`
<!--{# common link defs #}-->
{% include '_snippets/rippled-api-links.md' %}
{% include '_snippets/tx-type-links.md' %}
{% include '_snippets/rippled_versions.md' %}
{% include '_snippets/rippled-api-links.md' %}
{% include '_snippets/tx-type-links.md' %}
{% include '_snippets/rippled_versions.md' %}

11
content/tutorials/manage-account-settings/change-or-remove-a-regular-key-pair.md
View File

@@ -8,7 +8,7 @@ labels:
---
# Change or Remove a Regular Key Pair
The XRP Ledger allows an account to authorize a secondary key pair, called a _[regular key pair](cryptographic-keys.html)_, to sign future transactions. If your [account](accounts.html)'s regular key pair is compromised, or if you want to periodically change the regular key pair as a security measure, use a [SetRegularKey transaction][] to remove or change the regular key pair for your account.
The XRP Ledger allows an account to authorize a secondary key pair, called a _regular key pair_, to sign future transactions. If your account's regular key pair is compromised, or if you want to periodically change the regular key pair as a security measure, use a [SetRegularKey transaction][] to remove or change the regular key pair for your account.
For more information about master and regular key pairs, see [Cryptographic Keys](cryptographic-keys.html).
@@ -22,7 +22,7 @@ For more information about master and regular key pairs, see [Cryptographic Keys
## Removing a Regular Key Pair
If you want to remove a compromised regular key pair from your account, you don't need to generate a key pair first. Use a [SetRegularKey transaction][], omitting the `RegularKey` field. Note that the transaction fails if you don't have another way of signing for your account currently enabled (either the master key pair or a [signer list](multi-signing.html)).
If you want to remove a compromised regular key pair from your account, you don't need to generate a key pair first. Use a [SetRegularKey transaction][], omitting the `RegularKey` field. Note that the transaction fails if you don't have another way of signing for your account currently enabled (either the master key pair or a signer list).
When removing a regular key pair to your account, the `SetRegularKey` transaction requires signing by your account's master private key (secret) or existing regular key pair. Transmitting your master or regular private key is dangerous, so we'll complete this transaction in two steps to keep transaction signing separate from transaction submission to the network.
@@ -361,7 +361,7 @@ An example of a successful response:
<!-- MULTICODE_BLOCK_END -->
In some cases, you can even use the `SetRegularKey` transaction to send a [key reset transaction](transaction-cost.html#key-reset-transaction) without paying the [transaction cost](transaction-cost.html). The XRP Ledger's [transaction queue](transaction-queue.html) prioritizes key reset transactions above other transactions even though the nominal transaction cost of a key reset transaction is zero.
In some cases, you can even use the `SetRegularKey` transaction to send a key reset transaction without paying the transaction cost. The XRP Ledger's transaction queue prioritizes key reset transactions above other transactions even though the nominal transaction cost of a key reset transaction is zero.
- **Concepts:**
@@ -379,7 +379,8 @@ In some cases, you can even use the `SetRegularKey` transaction to send a [key r
- [AccountRoot object](accountroot.html) where the regular key is stored in the field `RegularKey`
<!--{# common link defs #}-->
{% include '_snippets/rippled-api-links.md' %}
{% include '_snippets/tx-type-links.md' %}
{% include '_snippets/rippled-api-links.md' %}
{% include '_snippets/tx-type-links.md' %}
{% include '_snippets/rippled_versions.md' %}

12
content/tutorials/manage-account-settings/disable-master-key-pair.md
View File

@@ -8,9 +8,9 @@ labels:
---
# Disable Master Key Pair
This page describes how to disable the [master key pair](cryptographic-keys.html) that is mathematically associated with an [account](accounts.html)'s address. You should do this if your account's master key pair may have been compromised, or if you want to make [multi-signing](multi-signing.html) the _only_ way to submit transactions from your account.
This page describes how to disable the master key pair that is mathematically associated with an account's address. You should do this if your account's master key pair may have been compromised, or if you want to make multi-signing the _only_ way to submit transactions from your account.
**Warning:** Disabling the master key pair removes one method of [authorizing transactions](transaction-basics.html#authorizing-transactions). You should be sure you can use one of the other ways of authorizing transactions, such as with a regular key or by multi-signing, before you disable the master key pair. (For example, if you [assigned a regular key pair](assign-a-regular-key-pair.html), make sure that you can successfully submit transactions with that regular key.) Due to the decentralized nature of the XRP Ledger, no one can restore access to your account if you cannot use the remaining ways of authorizing transactions.
**Warning:** Disabling the master key pair removes one method of authorizing transactions. You should be sure you can use one of the other ways of authorizing transactions, such as with a regular key or by multi-signing, before you disable the master key pair. (For example, if you assigned a regular key pair, make sure that you can successfully submit transactions with that regular key.) Due to the decentralized nature of the XRP Ledger, no one can restore access to your account if you cannot use the remaining ways of authorizing transactions.
**To disable the master key pair, you must use the master key pair.** However, you can _re-enable_ the master key pair using any other method of authorizing transactions.
@@ -18,7 +18,7 @@ This page describes how to disable the [master key pair](cryptographic-keys.html
To disable the master key pair for an account, you must meet the following prerequisites:
- You must have an XRP Ledger [account](accounts.html) and you must be able to sign and submit transactions from that account using the master key pair. See also: [Set Up Secure Signing](set-up-secure-signing.html). Two common ways this can work are:
- You must have an XRP Ledger account and you must be able to sign and submit transactions from that account using the master key pair. See also: [Set Up Secure Signing](set-up-secure-signing.html). Two common ways this can work are:
- You know the account's master seed value. A seed value is commonly represented as a [base58][] value starting with "s", such as `sn3nxiW7v8KXzPzAqzyHXbSSKNuN9`.
- Or, you use a [dedicated signing device](set-up-secure-signing.html#use-a-dedicated-signing-device) that stores the seed value securely, so you don't need to know it.
- Your account must have at least one method of authorizing transactions other than the master key pair. In other words, you must do one or both of the following:
@@ -31,7 +31,7 @@ To disable the master key pair for an account, you must meet the following prere
### {{n.next()}}. Construct Transaction JSON
Prepare an [AccountSet transaction][] from your account with the field `"SetValue": 4`. This is the value for the AccountSet flag "Disable Master" (`asfDisableMaster`). The only other required fields for this transaction are the required [common fields](transaction-common-fields.html). For example, if you leave off the [auto-fillable fields](transaction-common-fields.html#auto-fillable-fields), the following transaction instructions are enough:
Prepare an [AccountSet transaction][] from your account with the field `"SetValue": 4`. This is the value for the AccountSet flag "Disable Master" (`asfDisableMaster`). The only other required fields for this transaction are the required common fields. For example, if you leave off the auto-fillable fields, the following transaction instructions are enough:
```json
{
@@ -41,7 +41,7 @@ Prepare an [AccountSet transaction][] from your account with the field `"SetValu
}
```
**Tip:** It is strongly recommended to also provide the `LastLedgerSequence` field so that you can [reliably get the outcome of the transaction in a predictable amount of time](reliable-transaction-submission.html).
**Tip:** It is strongly recommended to also provide the `LastLedgerSequence` field so that you can reliably get the outcome of the transaction in a predictable amount of time. See: [Reliable Transaction Submission](reliable-transaction-submission.html).
### {{n.next()}}. Sign Transaction
@@ -498,7 +498,7 @@ This operation has only two possible outcomes:
- A nonzero result, equal to the `lsfDisableMaster` value, indicates **the master key has been successfully disabled**.
- A zero result indicates the account's master key is not disabled.
If the result does not match your expectations, check whether the transaction you sent in the previous steps has executed successfully. It should be the most recent entry in the account's transaction history ([account_tx method][]) and it should have the result code `tesSUCCESS`. If you see any other [result code](transaction-results.html), the transaction was not executed successfully. Depending on the cause of the error, you may want to restart these steps from the beginning.
If the result does not match your expectations, check whether the transaction you sent in the previous steps has executed successfully. It should be the most recent entry in the account's transaction history ([account_tx method][]) and it should have the result code `tesSUCCESS`. If you see any other result code, the transaction was not executed successfully. Depending on the cause of the error, you may want to restart these steps from the beginning.

8
content/tutorials/manage-account-settings/offline-account-setup.md
View File

@@ -8,7 +8,7 @@ labels:
---
# Offline Account Setup Tutorial
A highly secure [signing configuration](set-up-secure-signing.html) involves keeping an XRP Ledger [account](accounts.html)'s [cryptographic keys](cryptographic-keys.html) securely on an offline, air-gapped machine. After setting up this configuration, you can sign a variety of transactions, transfer only the signed transactions to an online computer, and submit them to the XRP Ledger network without ever exposing your secret key to malicious actors online.
A highly secure signing configuration involves keeping an XRP Ledger account's cryptographic keys securely on an offline, air-gapped machine. After setting up this configuration, you can sign a variety of transactions, transfer only the signed transactions to an online computer, and submit them to the XRP Ledger network without ever exposing your secret key to malicious actors online.
**Caution:** Proper operational security is necessary to protect your offline machine. For example, the offline machine must be physically located where untrusted people cannot get access to it, and trusted operators must be careful not to transfer compromised software onto the machine. (For example, do not use a USB drive that was previously attached to a network-connected computer.)
@@ -16,8 +16,8 @@ A highly secure [signing configuration](set-up-secure-signing.html) involves kee
To use offline signing, you must meet the following prerequisites:
- You must have one computer to use as an offline machine. This machine must be set up with a [supported operating system](system-requirements.html). See your operating system's support for offline setup instructions. (For example, [Red Hat Enterprise Linux DVD ISO installation instructions](https://access.redhat.com/solutions/7227).) Be sure that the software and physical media you use are not infected with malware.
- You must have a separate computer to use as an online machine. This machine does not need to run `rippled` but it must be able to connect to the XRP Ledger network and receive accurate information about the state of the shared ledger. For example, you can use a [WebSocket connection to a public server](get-started-using-http-websocket-apis.html).
- You must have one computer to use as an offline machine. This machine must be set up with a supported operating system. See [System Requirements](system-requirements.html), and your operating system's support for offline setup instructions. (For example, [Red Hat Enterprise Linux DVD ISO installation instructions](https://access.redhat.com/solutions/7227).) Be sure that the software and physical media you use are not infected with malware.
- You must have a separate computer to use as an online machine. This machine does not need to run `rippled` but it must be able to connect to the XRP Ledger network and receive accurate information about the state of the shared ledger. For example, you can use a WebSocket connection to a public server. See [Get Started Using HTTP WebSocket APIs](get-started-using-http-websocket-apis.html).
- You must have a secure way to transfer signed transaction binary data from the offline machine to the online machine.
- One way to do this is with a QR code generator on the offline machine, and a QR code scanner on the online machine. (In this case, your "online machine" could be a handheld device such as a smartphone.)
- Another way is to copy files from the offline machine to an online machine using physical media. If you use this method, be sure not to use physical media that could infect your offline machine with malicious software. (For example, do not reuse the same USB drive on both online and offline machines.)
@@ -30,7 +30,7 @@ To use offline signing, you must meet the following prerequisites:
### {{n.next()}}. Set up offline machine
The offline machine needs secure persistent storage (for example, an encrypted disk drive) and a way to [sign transactions](set-up-secure-signing.html). For an offline machine, you typically use physical media to transfer any necessary software after downloading it from an online machine. You must be sure that the online machine, the physical media, and the software itself are not infected with malware.
The offline machine needs secure persistent storage (for example, an encrypted disk drive) and a way to sign transactions. For an offline machine, you typically use physical media to transfer any necessary software after downloading it from an online machine. You must be sure that the online machine, the physical media, and the software itself are not infected with malware.
Software options for signing on the XRP Ledger include:

8
content/tutorials/manage-account-settings/send-a-multi-signed-transaction.md
View File

@@ -11,16 +11,18 @@ The following procedure demonstrates how to create, sign, and submit a multi-sig
## Prerequisites
- You must have already [set up multi-signing](set-up-multi-signing.html) for your address.
- You must have already for your address.
- Multi-signing must be available. Multi-signing has been enabled by an [**Amendment**](amendments.html) to the XRP Ledger Consensus Protocol since 2016-06-27.
- Multi-signing must be available.
See [set up multi-signing](set-up-multi-signing.html).
## 1. Create the transaction
Create a JSON object that represents the transaction you want to submit. You have to specify _everything_ about this transaction, including `Fee` and `Sequence`. Also include the field `SigningPubKey` as an empty string, to indicate that the transaction is multi-signed.
Keep in mind that the `Fee` for multi-signed transactions is significantly higher than for regularly-signed transactions. It should be at least (N+1) times the normal [transaction cost](transaction-cost.html), where N is the number of signatures you plan to provide. Since it sometimes takes a while to collect signatures from multiple sources, you may want to specify more than the current minimum, in case the [transaction cost](transaction-cost.html) increases in that time.
Keep in mind that the `Fee` for multi-signed transactions is significantly higher than for regularly signed transactions. It should be at least (N+1) times the normal transaction cost, where N is the number of signatures you plan to provide. Since it sometimes takes a while to collect signatures from multiple sources, you may want to specify more than the current minimum, in case the transaction cost increases in that time. See [transaction cost](transaction-cost.html).
Here's an example transaction ready to be multi-signed:

14
content/tutorials/manage-account-settings/set-up-multi-signing.md
View File

@@ -7,24 +7,24 @@ labels:
---
# Set Up Multi-Signing
[Multi-signing](multi-signing.html) is one of three ways to authorize [transactions](transaction-basics.html) for the XRP Ledger, alongside signing with [regular keys and master keys](cryptographic-keys.html). You can configure your [address](accounts.html) to allow any combination of the three methods to authorize transactions.
Multi-signing is one of three ways to authorize transactions for the XRP Ledger, alongside signing with regular keys and master keys. You can configure your address to allow any combination of the three methods to authorize transactions.
This tutorial demonstrates how to enable multi-signing for an address.
## Prerequisites
- You must have a funded XRP Ledger [address](accounts.html) with enough spare XRP to send transactions and meet the [reserve requirement](reserves.html) of a new signer list.
- You must have a funded XRP Ledger account with enough spare XRP to send transactions and meet the reserve requirement of a new signer list.
- With the [MultiSignReserve amendment][] enabled, multi-signing requires 2 XRP for the account reserve, regardless of the number of signers and signatures you use. (The MultiSignReserve amendment has been enabled in the production XRP Ledger since **2019-04-07**.)
- Multi-signing requires 2 XRP for the account reserve, regardless of the number of signers and signatures you use.
- If you are on a test network that does not have the [MultiSignReserve amendment][] enabled, multi-signing requires more than the usual amount of XRP for the [account reserve](reserves.html), increasing with the number of signers in the list.
- If you are on a test network that does not have the [MultiSignReserve amendment][] enabled, multi-signing requires more than the usual amount of XRP for the account reserve, increasing with the number of signers in the list.
- You must have access to a tool that can generate key pairs in the XRP Ledger format. If you are using a `rippled` server for this, you must have admin access because the [wallet_propose method][] is admin-only.
- Alternatively, if you are authorizing others who already have XRP Ledger addresses to be signers for your address, you only need to know the account addresses of those people or entities.
- Multi-signing must be available. (The MultiSign amendment has been enabled in the production XRP Ledger since **2016-06-27**.)
- Multi-signing must be available.
## 1. Design Your Configuration
@@ -135,9 +135,9 @@ In this example, the signer list has 3 members, with the weights and quorum set
}
}
Make sure that the [Transaction Result](transaction-results.html) is [**`tesSUCCESS`**](tes-success.html). Otherwise, the transaction failed. If you have a problem in stand-alone mode or a non-production network, check that [multi-sign is enabled](start-a-new-genesis-ledger-in-stand-alone-mode.html#settings-in-new-genesis-ledgers).
Make sure that the transaction result is **`tesSUCCESS`**. Otherwise, the transaction failed. If you have a problem in stand-alone mode or a non-production network, check that [multi-sign is enabled](start-a-new-genesis-ledger-in-stand-alone-mode.html#settings-in-new-genesis-ledgers).
**Note:** Without the [MultiSignReserve amendment][], the more members in the signer list, the more XRP your address must have for purposes of the [owner reserve](reserves.html#owner-reserves). If your address does not have enough XRP, the transaction fails with [`tecINSUFFICIENT_RESERVE`](tec-codes.html). With the [MultiSignReserve amendment][] enabled, the XRP your address must have for purposes of the [owner reserve](reserves.html#owner-reserves) is 5 XRP, regardless of the number of members in the signer list. See also: [Signer Lists and Reserves](signerlist.html#signer-lists-and-reserves).
**Note:** Without the MultiSignReserve amendment, the more members in the signer list, the more XRP your address must have for purposes of the owner reserve. If your address does not have enough XRP, the transaction fails with `tecINSUFFICIENT_RESERVE`. With the MultiSignReserve amendment enabled, the XRP your address must have for purposes of the owner reserve is 5 XRP, regardless of the number of members in the signer list. See also: [Signer Lists and Reserves](signerlist.html#signer-lists-and-reserves).
## 4. Wait for validation

15
content/tutorials/manage-account-settings/use-tickets.md
View File

@@ -11,7 +11,7 @@ labels:
---
# Use Tickets
[Tickets](tickets.html) provide a way to send transactions out of the normal order. This tutorial walks through the steps of creating a Ticket, then using it to send another transaction.
Tickets provide a way to send transactions out of the normal order. This tutorial walks through the steps of creating a ticket, then using it to send another transaction.
## Prerequisites
@@ -19,12 +19,11 @@ labels:
<script type="application/javascript" src="assets/js/tutorials/use-tickets.js"></script>
{% set use_network = "Devnet" %}<!--TODO: change to Testnet eventually. NOTE, Testnet is a few days behind Mainnet in getting the amendment one enabled -->
This page provides JavaScript examples that use the [xrpl.js](https://js.xrpl.org/) library. See [Get Started Using JavaScript](get-started-using-javascript.html) for setup instructions.
This page provides JavaScript examples that use the `xrpl.js` library. See [Get Started Using JavaScript](get-started-using-javascript.html) for setup instructions.
Since JavaScript works in the web browser, you can read along and use the interactive steps without any setup.
## Steps
{% set n = cycler(* range(1,99)) %}
@@ -41,7 +40,7 @@ To transact on the XRP Ledger, you need an address and secret key, and some XRP.
{% include '_snippets/interactive-tutorials/generate-step.md' %}
When you're [building production-ready software](production-readiness.html), you should use an existing account, and manage your keys using a [secure signing configuration](set-up-secure-signing.html).
When you're building production-ready software](production-readiness.html), you should use an existing account, and manage your keys using a secure signing configuration. See [Production Readiness](production-readiness.html) and [Set Up Secure Signing](set-up-secure-signing.html).
### {{n.next()}}. Connect to Network
@@ -95,7 +94,7 @@ _JavaScript_
<!-- MULTICODE_BLOCK_END -->
Record the transaction's hash and `LastLedgerSequence` value so you can [be sure whether or not it got validated](reliable-transaction-submission.html) later.
Record the transaction's hash and `LastLedgerSequence` value so you can later [verify it was validated](reliable-transaction-submission.html) .
{{ start_step("Prepare & Sign") }}
@@ -180,7 +179,7 @@ _JavaScript_
Now that you have a Ticket available, you can prepare a transaction that uses it.
This can be any [type of transaction](transaction-types.html) you like. The following example uses a no-op [AccountSet transaction][] since that doesn't require any other setup in the ledger. Set the `Sequence` field to `0` and include a `TicketSequence` field with the Ticket Sequence number of one of your available Tickets.
This can be any type of transaction you like. The following example uses a no-op [AccountSet transaction][] since that doesn't require any other setup in the ledger. Set the `Sequence` field to `0` and include a `TicketSequence` field with the Ticket Sequence number of one of your available Tickets.
<!-- MULTICODE_BLOCK_START -->
@@ -233,9 +232,9 @@ Ticketed transactions go through the consensus process the same way that Sequenc
## With Multi-Signing
One of the main use cases for Tickets is to be able to collect signatures for several [multi-signed transactions](multi-signing.html) in parallel. By using a Ticket, you can send a multi-signed transaction as soon as it is fully signed and ready to go, without worrying about which one will be ready first.
One of the main use cases for Tickets is to be able to collect signatures for several multi-signed transactions in parallel. By using a ticket, you can send a multi-signed transaction as soon as it is fully signed and ready to go, without worrying about which one will be ready first. See [Multi-signing](multi-signing.html)
In this scenario, [step 8, "Prepare Ticketed Transaction"](#8-prepare-ticketed-transaction) is slightly different. Instead of preparing and signing all at once, you would follow the steps for [sending any multi-signed transaction](send-a-multi-signed-transaction.html): first prepare the transaction, then circulate it among trusted signers to collect their signatures, and finally combine the signatures into the final multi-signed transaction.
In this scenario, [step 8, "Prepare Ticketed Transaction"](#8-prepare-ticketed-transaction) is slightly different. Instead of preparing and signing all at once, you would follow the steps for sending any multi-signed transaction: first prepare the transaction, then circulate it among trusted signers to collect their signatures, and finally combine the signatures into the final multi-signed transaction.
You could do this in parallel for several different potential transactions as long as each one uses a different Ticket.

12
content/tutorials/manage-the-rippled-server/configuration/configure-advisory-deletion.md
View File

@@ -8,7 +8,7 @@ labels:
---
# Configure Advisory Deletion
The default config file sets [`rippled`](xrpl-servers.html) to automatically delete outdated [history](ledger-history.html) of XRP Ledger state and transactions as new ledger versions become available. If your server uses most of its hardware resources during peak hours, you can configure the server to delete ledgers only when prompted by a command scheduled to run during off-peak hours, so that online deletion is less likely to impact [server performance](capacity-planning.html).
The default config file sets `rippled` to automatically delete outdated history of XRP Ledger state and transactions as new ledger versions become available. If your server uses most of its hardware resources during peak hours, you can configure the server to delete ledgers only when prompted by a command scheduled to run during off-peak hours, so that online deletion is less likely to impact server performance.
## Prerequisites
@@ -16,7 +16,7 @@ This tutorial assumes your server meets the following prerequisites:
- You are on a supported operating system: Ubuntu Linux, Red Hat Enterprise Linux (RHEL), or CentOS.
- The `rippled` server is already [installed](install-rippled.html) and [online deletion](online-deletion.html) is enabled.
- The `rippled` server is already installed with online deletion enabled. See [Install rippled](install-rippled.html) and [online deletion](online-deletion.html)
The default config file enables online deletion after 2000 ledger versions.
@@ -30,7 +30,9 @@ This tutorial assumes your server meets the following prerequisites:
- Your server has enough disk space to store your chosen amount of history in its ledger store.
See [Capacity Planning](capacity-planning.html) for details of how much storage is required for different configurations. With advisory deletion enabled, the maximum history a server may accumulate before deletion is equal to the number of ledger versions configured in the `online_delete` setting **plus** the amount of time between online deletion prompts.
See [Capacity Planning](capacity-planning.html) for details of how much storage is required for different configurations.
With advisory deletion enabled, the maximum history a server can accumulate before deletion is equal to the number of ledger versions configured in the `online_delete` setting **plus** the amount of time between online deletion prompts.
- You know which hours are least busy for your server.
@@ -52,7 +54,7 @@ To configure advisory deletion with a daily schedule, perform the following step
2. Test running the [can_delete method][] to prompt the server to run online deletion.
You can use the [`rippled` commandline interface](get-started-using-http-websocket-apis.html#commandline) to run this command. For example:
You can use the `rippled` commandline interface to run this command. For example:
$ rippled --conf=/etc/opt/ripple/rippled.cfg can_delete now
@@ -98,7 +100,7 @@ If online deletion does not seem to be running after configuring it, try the fol
- Check that the user who configured the `cron` job has permissions to run the `rippled` server as a commandline client.
- Check the syntax of your `cron` job and the time when it is supposed to run.
- Check that the `rippled` executable is available at the path specified in your `cron` configuration. If necessary, specify the absolute path to the executable, such as `/opt/ripple/bin/rippled`.
- Check your `rippled` logs for messages that begin with `SHAMapStore::WRN`. This can indicate that [online deletion is being interrupted](online-deletion.html#interrupting-online-deletion) because your server fell out of sync with the network.
- Check your `rippled` logs for messages that begin with `SHAMapStore::WRN`. This can indicate that online deletion is being interrupted because your server fell out of sync with the network.
## See Also

4
content/tutorials/manage-the-rippled-server/configuration/configure-amendment-voting.md
View File

@@ -8,7 +8,7 @@ labels:
---
# Configure Amendment Voting
Servers configured as validators can vote on [amendments](amendments.html) to the XRP Ledger protocol using the [feature method][]. (This method requires [admin access](get-started-using-http-websocket-apis.html#admin-access).)
Servers configured as validators can vote on amendments to the XRP Ledger protocol using the [feature method][]. This method requires admin access.
For example, to vote against the "SHAMapV2" amendment, run the following command:
@@ -47,7 +47,7 @@ rippled feature SHAMapV2 reject
<!-- MULTICODE_BLOCK_END -->
**Note:** The short name of the amendment is case-sensitive. You can also use an amendment's ID as hexadecimal, which is not case sensitive.
**Note:** The short name of the amendment is case sensitive. You can also use an amendment's ID as hexadecimal, which is not case sensitive.
## Using the Config File

6
content/tutorials/manage-the-rippled-server/configuration/configure-history-sharding.md
View File

@@ -8,7 +8,7 @@ labels:
---
# Configure History Sharding
[History Sharding](history-sharding.html) lets servers contribute to preserving historical XRP Ledger data without each server needing to store the full history. By default, `rippled` servers do not store history shards.
History Sharding lets servers contribute to preserving historical XRP Ledger data without each server needing to store the full history. By default, `rippled` servers do not store history shards.
**Tip:** While both validator and tracking (or stock) `rippled` servers can be configured to store history shards, Ripple recommends _not_ configuring validator `rippled` servers to store shards, to reduce overhead on those servers. If you run a validator and want to contribute to storing XRP Ledger history, Ripple recommends you run a separate `rippled` server with history sharding enabled.
@@ -25,7 +25,7 @@ Before you configure your `rippled` server to store history shards, you must dec
- The history shard store and the ledger store _MUST_ be stored at different file paths. You can configure the ledger store and history store to be on different disks or partitions if desired.
- It is possible but redundant to hold full ledger history in both the ledger store and the history shard store.
- The time to acquire a shard, number of file handles needed by the `rippled` server, and memory cache usage is directly affected by the size of the shard.
- You can specify additional paths to store older history shards by providing a `[historical_shard_paths]` stanza. These paths may be on different, slower disks because they hold data that is used less often. The most recent two shards (the ones with the largest ledger indexes) are always stored in the path specified in the `[shard_db]` stanza. [New in: rippled 1.7.0][]
- You can specify additional paths to store older history shards by providing a `[historical_shard_paths]` stanza. These paths may be on different, slower disks because they hold data that is used less often. The most recent two shards (the ones with the largest ledger indexes) are always stored in the path specified in the `[shard_db]` stanza.
## 2. Edit rippled.cfg
@@ -48,7 +48,7 @@ max_historical_shards=12
/mnt/disk2
```
The `type` field of `[shard_db]` can be omitted. If present, it _MUST_ be `NuDB`. [New in: rippled 1.3.1][]
The `type` field of `[shard_db]` can be omitted. If present, it _MUST_ be `NuDB`.
**Caution:** If `rippled` detects the wrong type of data in the shard store path, it may [fail to start](server-wont-start.html). You should use a new folder for the shard store. If you previously used a RocksDB shard store (`rippled` 1.2.x and lower), use a different path or delete the RocksDB shard data.

8
content/tutorials/manage-the-rippled-server/configuration/configure-online-deletion.md
View File

@@ -8,7 +8,7 @@ labels:
---
# Configure Online Deletion
In its default configuration, [the `rippled` server](xrpl-servers.html) [deletes history](online-deletion.html) older than the most recent 2000 [ledger versions](ledgers.html), keeping approximately 15 minutes of [ledger history](ledger-history.html) (based on the current rate between ledgers). This page describes how to configure the amount of history your `rippled` server stores before deleting.
In its default configuration, the `rippled` server deletes history older than the most recent 2000 ledger versions, keeping approximately 15 minutes of ledger history (based on the current rate between ledgers). This page describes how to configure the amount of history your `rippled` server stores before deleting.
## Prerequisites
@@ -16,11 +16,11 @@ This tutorial assumes your server meets the following prerequisites:
- You are on a supported operating system: Ubuntu Linux, Red Hat Enterprise Linux (RHEL), or CentOS.
- The `rippled` server is already [installed](install-rippled.html) and [online deletion](online-deletion.html) is enabled.
- The `rippled` server is already installed and online deletion is enabled. See [Install rippled](install-rippled.html) and [online deletion](online-deletion.html).
If you followed the installation instructions for a recommended platform, online deletion is enabled by default.
- Your server has [enough disk space](capacity-planning.html#disk-space) to store your chosen amount of history in its ledger store.
- Your server has enough disk space to store your chosen amount of history in its ledger store. See [Capacity Planning](capacity-planning.html#disk-space).
## Configuration Steps
@@ -58,7 +58,7 @@ To change the amount of history your server stores, perform the following steps:
After online deletion runs, the `complete_ledgers` range reflects that older ledgers are no longer available. As your server accumulates history, the total number of ledgers available should slowly increase to twice the `online_delete` value you configured, then decrease when online deletion runs.
0. Monitor your `rippled` logs for messages that begin with `SHAMapStore::WRN`. This can indicate that [online deletion is being interrupted](online-deletion.html#interrupting-online-deletion) because your server fell out of sync with the network.
0. Monitor your `rippled` logs for messages that begin with `SHAMapStore::WRN`. This can indicate that online deletion is being interrupted because your server fell out of sync with the network.
If this happens regularly, your server may not have sufficient specifications to keep up with the ledger while running online deletion. Check that other services on the same hardware (such as scheduled backups or security scans) aren't competing with the `rippled` server for resources. You may want to try any of the following:

4
content/tutorials/manage-the-rippled-server/configuration/connect-your-rippled-to-the-xrp-test-net.md
View File

@@ -9,9 +9,9 @@ labels:
---
# Connect Your rippled to a Parallel Network
Various [alternative test and development networks](parallel-networks.html) exist for developers to test their apps or experiment with features without risking real money. **The funds used on these networks are not real funds and are intended for testing only.** You can connect your [`rippled` server](xrpl-servers.html) to any of these test networks.
Various alternative test and development networks exist for developers to test their apps or experiment with features without risking real money. **The funds used on these networks are not real funds and are intended for testing only.** You can connect your `rippled` server to any of these test networks.
**Caution:** On test networks with new and experimental features, you may need to run a pre-production release of the server to sync with the network. See the [Parallel Networks Page](parallel-networks.html) for information on what code version each network needs.
**Caution:** On test networks with new and experimental features, you may need to run a pre-production release of the server to sync with the network. See [Parallel Networks](parallel-networks.html) for information on what code version each network requires.
## Steps

8
content/tutorials/manage-the-rippled-server/configuration/enable-public-signing.md
View File

@@ -8,21 +8,21 @@ labels:
---
# Enable Public Signing
By default, the signing methods for [`rippled`](xrpl-servers.html) are limited to [administrative connections](admin-api-methods.html). If you want to allow signing methods to be used as public API methods (like with versions of `rippled` before v1.1.0), you can enable it with a configuration change. [New in: rippled 1.1.0][]
By default, the signing methods for `rippled` are limited to administrative connections. If you want to allow signing methods to be used as public API methods (like with versions of `rippled` before v1.1.0), you can enable it with a configuration change.
This enables the following methods to be used on "public" [JSON-RPC and WebSocket connections](get-started-using-http-websocket-apis.html), if your server accepts them:
This enables the following methods to be used on "public" JSON-RPC and WebSocket connections, if your server accepts them:
- [sign][sign method]
- [sign_for][sign_for method]
- [submit][submit method] (in "sign-and-submit" mode)
You **do not** need to enable public signing to use these methods from an admin connection.
You _do not_ need to enable public signing to use these methods from an admin connection.
**Caution:** Ripple does not recommend enabling public signing. Like the [wallet_propose method][], the signing commands do not perform any actions that would require administrative-level permissions, but restricting them to admin connections protects users from irresponsibly sending or receiving secret keys over unsecured communications, or to servers they do not control.
To enable public signing, perform the following steps:
1. Edit your `rippled`'s config file.
1. Edit your `rippled` config file.
vim /etc/opt/ripple/rippled.cfg

10
content/tutorials/manage-the-rippled-server/configuration/run-rippled-as-a-stock-server.md
View File

@@ -7,19 +7,19 @@ labels:
---
# Run rippled as a Stock Server
A stock server is a multipurpose configuration for `rippled`. With a stock server, you can submit transactions to the XRP Ledger, access ledger history, and use the latest [tools](software-ecosystem.html) to integrate with XRP. It is also a server that you can use to connect a wallet with the XRPL.
A stock server is a multipurpose configuration for `rippled`. With a stock server, you can submit transactions to the XRP Ledger, access ledger history, and use the latest tools to integrate with XRP. It is also a server that you can use to connect a wallet with the XRPL.
A stock server does all of the following:
- Connects to a [network of peers](consensus-network.html)
- Connects to a network of peers
- Relays cryptographically signed [transactions](transaction-basics.html)
- Relays cryptographically signed transactions
- Maintains a local copy of the complete shared global [ledger](ledgers.html)
- Maintains a local copy of the complete shared global ledger
To participate in the [consensus process](consensus.html) as a validator, [run rippled as a validator](run-rippled-as-a-validator.html) instead.
To participate in the consensus process as a validator, run rippled as a validator instead. See [Run rippled as a validator](run-rippled-as-a-validator.html)
## Install and run `rippled`

40
content/tutorials/manage-the-rippled-server/configuration/run-rippled-as-a-validator.md
View File

@@ -10,24 +10,23 @@ top_nav_name: Join UNL
---
# Run rippled as a Validator
A [`rippled` server](xrpl-servers.html) running in [validator mode](rippled-server-modes.html) does everything a stock server does:
A `rippled` server running in validator mode does everything a stock server does:
- Connects to a [network of peers](consensus-network.html)
- Connects to a network of peers
- Relays cryptographically signed [transactions](transaction-basics.html)
- Relays cryptographically signed transactions
- Maintains a local copy of the complete shared global [ledger](ledgers.html)
- Maintains a local copy of the complete shared global ledger
What makes a validator _different_ is that it also issues validation messages, which are sets of candidate transactions for evaluation by the XRP Ledger network during the [consensus process](consensus-principles-and-rules.html#how-consensus-works).
What makes a validator _different_ is that it also issues validation messages, which are sets of candidate transactions for evaluation by the XRP Ledger network during the consensus process.
Issuing validation messages does not automatically give your validator a say in the consensus process, so the system is not vulnerable to a [Sybil attack](https://en.wikipedia.org/wiki/Sybil_attack). Other servers ignore your validation messages unless they add your validator to their Unique Node List (UNL). If your validator is included in a UNL, it is a _trusted_ validator and its proposals are considered in the consensus process by the servers that trust it.
Even if your validator isn't a _trusted_ validator, it stills plays an important role in the overall health of the network. These validators help set the standard that trusted validators are measured against. For example, if a trusted validator is disagreeing with a lot of these validators that aren't listed in UNLs, that might indicate a problem.
Even if your validator isn't a _trusted_ validator, it still plays an important role in the overall health of the network. These validators help set the standard that trusted validators are measured against. For example, if a trusted validator is disagreeing with a lot of these validators that aren't listed in UNLs, that might indicate a problem.
**Warning:** Validators should not be accessible to the public. Do not allow public WebSocket access to your validator server or any other form of public access.
## 1. Understand the traits of a good validator
Strive to have your validator always embody the following properties. Being a good validator helps `rippled` server operators and validator list publishers (such as https://vl.coil.com, https://vl.ripple.com, and https://vl.xrplf.org), to trust your validator before adding it to their UNLs.
@@ -38,17 +37,17 @@ Strive to have your validator always embody the following properties. Being a go
- **In agreement**
A good validator's votes match the outcome of the consensus process as often as possible. To do otherwise could indicate that your validator's software is outdated, buggy, or intentionally biased. Always run the [latest `rippled` release](https://github.com/XRPLF/rippled/tree/release) without modifications. [Watch `rippled` releases](https://github.com/XRPLF/rippled/releases) and subscribe to the [Google Group](https://groups.google.com/g/ripple-server) to be notified of new releases.
A good validator's votes match the outcome of the consensus process as often as possible. To do otherwise could indicate that your validator's software is outdated, buggy, or intentionally biased. Always run the latest `rippled` release without modifications. Watch [`rippled` releases](https://github.com/XRPLF/rippled/releases) and subscribe to the [Google Group](https://groups.google.com/g/ripple-server) to be notified of new releases.
- **Issuing timely votes**
A good validator's votes arrive quickly and not after a consensus round has already finished. To keep your votes timely, make sure your validator meets the recommended [system requirements](system-requirements.html), which include a fast internet connection.
A good validator's votes arrive quickly and not after a consensus round has already finished. To keep your votes timely, make sure your validator meets the recommended system requirements, which include a fast internet connection. See [system requirements](system-requirements.html).
It is possible to submit new transactions and query data using a validator, but heavy loads of API queries may make the validator less reliable at keeping up with consensus. If your API needs are light enough, then you can use a server for both purposes. Ideally, a validator should be dedicated to participating in consensus.
- **Identified**
A good validator has a clearly identified owner. Providing [domain verification](#6-provide-domain-verification) is a good start. Ideally, XRP Ledger network UNLs include validators run by different owners in multiple legal jurisdictions and geographic areas. This reduces the chance that any localized events could interfere with the impartial operations of trusted validators.
A good validator has a clearly identified owner. Providing domain verification is a good start. Ideally, XRP Ledger network UNLs include validators run by different owners in multiple legal jurisdictions and geographic areas. This reduces the chance that any localized events could interfere with the impartial operations of trusted validators.
It is strongly recommended that operators use the list providers that are present in this [example file](https://github.com/XRPLF/rippled/blob/develop/cfg/validators-example.txt).
@@ -59,7 +58,6 @@ It is strongly recommended that operators use the list providers that are presen
For more information, see [Install `rippled`](install-rippled.html).
## 3. Enable validation on your `rippled` server
Enabling validation on your `rippled` server means providing a validator token in your server's `rippled.cfg` file. You can use the `validator-keys` tool (included in `rippled` packages) to securely generate and manage your validator keys and tokens.
@@ -134,33 +132,39 @@ On your validator:
This section describes three different configurations you can use to connect your validator to the XRP Ledger network. Use the configuration that best suits your use case.
- [Discovered peers](#connect-using-discovered-peers): Connect to any servers in the peer-to-peer network.
- Discovered peers: Connect to any servers in the peer-to-peer network.
- [Proxies](#connect-using-proxies): Run stock `rippled` servers as proxies between your validator and the rest of the peer-to-peer network.
- Proxies: Run stock `rippled` servers as proxies between your validator and the rest of the peer-to-peer network.
- [Public hubs](#connect-using-public-hubs): Connect only to specific public servers with a high reputation.
- Public hubs: Connect only to specific public servers with a high reputation.
For a comparison of these approaches, see [Pros and Cons of Peering Configurations](peer-protocol.html#pros-and-cons-of-peering-configurations).
### Connect using discovered peers
This configuration connects your validator to the XRP Ledger network using [discovered peers](peer-protocol.html#peer-discovery). This is the default behavior for `rippled` servers.
This configuration connects your validator to the XRP Ledger network using discovered peers. This is the default behavior for `rippled` servers.
_**To connect your validator to the XRP Ledger network using discovered peers,**_ omit the `[peer_private]` stanza or set it to `0` in your validator's `rippled.cfg` file. The [example `rippled.cfg` file](https://github.com/ripple/rippled/blob/develop/cfg/rippled-example.cfg) is delivered with this configuration.
See [Peer Discovery](peer-protocol.html#peer-discovery).
### Connect using proxies
This configuration connects your validator to the network through stock `rippled` servers that you run yourself. These proxy servers sit between your validator and inbound and outbound network traffic.
<!-- not sure why we're using this heading type - haven't seen it anywhere else, so far-->
_**To connect your validator to the XRP Ledger network using proxies:**_
1. Set up stock `rippled` servers. For more information, see [Install rippled](install-rippled.html).
2. Configure your validator and stock `rippled` servers to run in a [cluster](cluster-rippled-servers.html).
2. Configure your validator and stock `rippled` servers to run in a cluster. See [Cluster rippled Servers](cluster-rippled-servers.html).
3. In your validator's `rippled.cfg` file, set `[peer_private]` to `1`. This prevents your validator's IP address from being forwarded. For more information, see [Private Peers](peer-protocol.html#private-peers). It also prevents your validator from connecting to servers other than those defined in the `[ips_fixed]` stanza you defined to run your validator in a cluster.
3. In your validator's `rippled.cfg` file, set `[peer_private]` to `1`. This prevents your validator's IP address from being forwarded. For more information, see [Private Peers](peer-protocol.html#private-peers).
It also prevents your validator from connecting to servers other than those defined in the `[ips_fixed]` stanza you defined to run your validator in a cluster.
**Warning:** Be sure that you don't publish your validator's IP address in other ways.
@@ -183,7 +187,7 @@ _**To connect your validator to the XRP Ledger network using proxies:**_
### Connect using public hubs
This configuration connects your validator to the network using three [public hubs](rippled-server-modes.html#public-hubs). This configuration is similar to [connecting using proxies you run yourself](#connect-using-proxies), but instead you connect through public hubs.
This configuration connects your validator to the network using three [public hubs](rippled-server-modes.html#public-hubs). This configuration is similar to connecting using proxies you run yourself, but instead you connect through public hubs.
_**To connect your validator to the network using public hubs:**_