diff --git a/concept-amendments.html b/concept-amendments.html index 1c48e1c7b5..cb53e2322e 100644 --- a/concept-amendments.html +++ b/concept-amendments.html @@ -74,6 +74,7 @@
  • Reserves
  • Freeze
  • Amendments
    • +
  • Stand-Alone Mode
  • @@ -120,6 +121,7 @@
  • Reserves
  • Freeze
  • Amendments
    • +
  • Stand-Alone Mode
    • In this page:
    diff --git a/concept-fee-voting.html b/concept-fee-voting.html index 87158c643f..819271ddf7 100644 --- a/concept-fee-voting.html +++ b/concept-fee-voting.html @@ -74,6 +74,7 @@
  • Reserves
  • Freeze
  • Amendments
    • +
  • Stand-Alone Mode
  • @@ -120,6 +121,7 @@
  • Reserves
  • Freeze
  • Amendments
    • +
  • Stand-Alone Mode
    • In this page:
    diff --git a/concept-fees.html b/concept-fees.html index 72612f9fdf..5bfbbb2269 100644 --- a/concept-fees.html +++ b/concept-fees.html @@ -74,6 +74,7 @@
  • Reserves
  • Freeze
  • Amendments
    • +
  • Stand-Alone Mode
  • @@ -120,6 +121,7 @@
  • Reserves
  • Freeze
  • Amendments
    • +
  • Stand-Alone Mode
    • In this page:
    diff --git a/concept-freeze.html b/concept-freeze.html index 5f11ded28d..698212cc31 100644 --- a/concept-freeze.html +++ b/concept-freeze.html @@ -74,6 +74,7 @@
  • Reserves
  • Freeze
  • Amendments
    • +
  • Stand-Alone Mode
  • @@ -120,6 +121,7 @@
  • Reserves
  • Freeze
  • Amendments
    • +
  • Stand-Alone Mode
    • In this page:
    diff --git a/concept-issuing-and-operational-addresses.html b/concept-issuing-and-operational-addresses.html index 5899c0bd45..215d010645 100644 --- a/concept-issuing-and-operational-addresses.html +++ b/concept-issuing-and-operational-addresses.html @@ -74,6 +74,7 @@
  • Reserves
  • Freeze
  • Amendments
    • +
  • Stand-Alone Mode
  • diff --git a/concept-paths.html b/concept-paths.html index e75dd477ae..6825135c6b 100644 --- a/concept-paths.html +++ b/concept-paths.html @@ -74,6 +74,7 @@
  • Reserves
  • Freeze
  • Amendments
    • +
  • Stand-Alone Mode
  • @@ -120,6 +121,7 @@
  • Reserves
  • Freeze
  • Amendments
    • +
  • Stand-Alone Mode
    • In this page:
    diff --git a/concept-reserves.html b/concept-reserves.html index a457f82400..2bf281ca19 100644 --- a/concept-reserves.html +++ b/concept-reserves.html @@ -74,6 +74,7 @@
  • Reserves
  • Freeze
  • Amendments
    • +
  • Stand-Alone Mode
  • @@ -120,6 +121,7 @@
  • Reserves
  • Freeze
  • Amendments
    • +
  • Stand-Alone Mode
    • In this page:
    diff --git a/concept-stand-alone-mode.html b/concept-stand-alone-mode.html new file mode 100644 index 0000000000..5740eaf662 --- /dev/null +++ b/concept-stand-alone-mode.html @@ -0,0 +1,234 @@ + + + + + + + +Stand-Alone Mode - Ripple Developer Portal + + + + + + + + + + + + + + + + + + + + + +
    + +
    +
    +

    Stand-Alone Mode

    +

    You can run rippled in stand-alone mode without a consensus of trusted servers. In stand-alone mode, rippled does not communicate with any other servers in the Ripple peer-to-peer network, but you can perform most of the same actions on your local server only. Stand-alone provides a method for testing rippled behavior, including the effects of Amendments before those Amendments have gone into effect across the decentralized network.

    +

    When you run rippled in stand-alone mode, you have to tell it what ledger version to start from:

    + +

    Caution: In stand-alone mode, you must manually advance the ledger.

    +

    New Genesis Ledger

    +

    In stand-alone mode, you can have rippled create a new genesis ledger. This provides a known state, with none of the ledger history from the production Ripple network. (This is very useful for unit tests, among other things.)

    +
      +
    • To start rippled in stand-alone mode with a new genesis ledger, use the -a and --start options:
      • +
    +
    rippled -a --start --conf=/path/to/rippled.cfg
+
    +

    In a genesis ledger, the genesis account holds all 100 billion XRP. The keys of the genesis account are hardcoded as follows:

    +

    Address: rHb9CJAWyB4rj91VRWn96DkukG4bwdtyTh

    +

    Secret: snoPBrXtMeMyMHUVTgbuqAfg1SUTb ("masterpassphrase")

    +

    Load Saved Ledger

    +

    You can start with a ledger version that was saved to disk if your rippled server was previously synced with the Ripple peer-to-peer network (either the production network or the Test Net).

    +

    1. To retrieve existing ledgers, start rippled normally:

    +
    rippled --conf=/path/to/rippled.cfg
+
    +

    2. Wait until rippled is synced:

    +

    When rippled is synced with the state of the network, the response from the server_info command shows a server_state value that is full, proposing, or validating.

    +

    3. (Optional) Retrieve specific ledger versions:

    +

    If you only want the most recent ledger, you can skip this step.

    +

    If you want to load a specific historical ledger version, use the ledger_request command to make rippled fetch it. If rippled does not already have the ledger version, you may have to run the ledger_request command multiple times until it has finished retrieving the ledger.

    +

    If you want to replay a specific historical ledger version, you must fetch both the ledger version to replay and the ledger version immediately before it.

    +

    4. Shut down rippled:

    +
    rippled stop --conf=/path/to/rippled.cfg
+
    +

    5. Start rippled in stand-alone mode, loading the saved ledger.

    +

    To load the most recent ledger version, you can use the -a and --load options:

    +
    rippled -a --load --conf=/path/to/rippled.cfg
+
    +

    To instead load a specific historical ledger, use the --ledger parameter with the ledger index or identifying hash of the ledger version to load:

    +
    rippled -a --ledger 19860944 --conf=/path/to/rippled.cfg
+
    +

    (TODO: test this)

    +

    6. Manually advance the ledger.

    +

    When you load a ledger with --ledger in stand-alone mode, it goes to the current open ledger, so you need to manually advance the ledger to finalize it:

    +
    rippled ledger_accept --conf=/path/to/rippled.cfg
+
    +

    Advancing Ledgers in Stand-Alone Mode

    +

    In stand-alone mode, rippled does not communicate to other members of the peer-to-peer network or participate in a consensus process. Instead, you must manually advance the ledger index using the ledger_accept command:

    +
    rippled ledger_accept --conf=/path/to/rippled.cfg
+
    +

    In stand-alone mode, rippled makes no distinction between a "closed" ledger version and a "validated" ledger version. (For more information about the difference, see The Ripple Ledger Consensus Process.)

    +

    Whenever rippled closes a ledger, it reorders the transactions according to a deterministic but hard-to-game algorithm. (This is an important part of consensus, since different rippled servers may see transactions in a different order.) When using rippled in stand-alone mode, it is important to manually advance the ledger before submitting a transaction that depends on the result of a previous transaction. Otherwise, the second transaction might be executed before the first transaction when you manually advance the ledger. Note: You can safely submit multiple transactions from a single account to a single ledger, because rippled sorts transactions from the same account in ascending order by Sequence number.

    +
    +
    +
    + + + diff --git a/concept-transaction-cost.html b/concept-transaction-cost.html index ee09630ace..9790422311 100644 --- a/concept-transaction-cost.html +++ b/concept-transaction-cost.html @@ -74,6 +74,7 @@
  • Reserves
  • Freeze
  • Amendments
    • +
  • Stand-Alone Mode
  • @@ -120,6 +121,7 @@
  • Reserves
  • Freeze
  • Amendments
    • +
  • Stand-Alone Mode
    • In this page:
    diff --git a/concept-transfer-fees.html b/concept-transfer-fees.html index a2d6c68a65..744056c8ea 100644 --- a/concept-transfer-fees.html +++ b/concept-transfer-fees.html @@ -74,6 +74,7 @@
  • Reserves
  • Freeze
  • Amendments
    • +
  • Stand-Alone Mode
  • @@ -120,6 +121,7 @@
  • Reserves
  • Freeze
  • Amendments
    • +
  • Stand-Alone Mode
    • In this page:
    diff --git a/content/concept-stand-alone-mode.md b/content/concept-stand-alone-mode.md new file mode 100644 index 0000000000..3b8bf2b21f --- /dev/null +++ b/content/concept-stand-alone-mode.md @@ -0,0 +1,94 @@ +Stand-Alone Mode +=============================================================================== + +You can run `rippled` in stand-alone mode without a consensus of trusted servers. In stand-alone mode, `rippled` does not communicate with any other servers in the Ripple peer-to-peer network, but you can perform most of the same actions on your local server only. Stand-alone provides a method for testing `rippled` behavior, including the effects of [Amendments](concept-amendments.html) before those Amendments have gone into effect across the decentralized network. + +When you run `rippled` in stand-alone mode, you have to tell it what ledger version to start from: + +* Create a [new genesis ledger](#new-genesis-ledger) from scratch. +* [Load an existing ledger version](#load-saved-ledger) from disk. + +**Caution:** In stand-alone mode, you must [manually advance the ledger](#advancing-ledgers-in-stand-alone-mode). + +New Genesis Ledger +------------------------------------------------------------------------------- +In stand-alone mode, you can have `rippled` create a new genesis ledger. This provides a known state, with none of the ledger history from the production Ripple network. (This is very useful for unit tests, among other things.) + +* To start `rippled` in stand-alone mode with a new genesis ledger, use the `-a` and `--start` options: + +``` +rippled -a --start --conf=/path/to/rippled.cfg +``` + +In a genesis ledger, the [genesis account](reference-rippled.html#special-addresses) holds all 100 billion XRP. The keys of the genesis account are [hardcoded](https://github.com/ripple/rippled/blob/94ed5b3a53077d815ad0dd65d490c8d37a147361/src/ripple/app/ledger/Ledger.cpp#L184) as follows: + +**Address:** `rHb9CJAWyB4rj91VRWn96DkukG4bwdtyTh` + +**Secret:** `snoPBrXtMeMyMHUVTgbuqAfg1SUTb` ("masterpassphrase") + + +Load Saved Ledger +------------------------------------------------------------------------------- +You can start with a ledger version that was saved to disk if your `rippled` server was previously synced with the Ripple peer-to-peer network (either the production network or the [Test Net](tutorial-rippled-setup.html#parallel-networks)). + +### 1. To retrieve existing ledgers, start `rippled` normally: ### + +``` +rippled --conf=/path/to/rippled.cfg +``` + +### 2. Wait until `rippled` is synced: ### + +When `rippled` is synced with the state of the network, the response from the [`server_info` command](reference-rippled.html#server-info) shows a `server_state` value that is `full`, `proposing`, or `validating`. + +### 3. (Optional) Retrieve specific ledger versions: ### + +If you only want the most recent ledger, you can skip this step. + +If you want to load a specific historical ledger version, use the [`ledger_request` command](reference-rippled.html#ledger-request) to make `rippled` fetch it. If `rippled` does not already have the ledger version, you may have to run the `ledger_request` command multiple times until it has finished retrieving the ledger. + +If you want to replay a specific historical ledger version, you must fetch both the ledger version to replay and the ledger version immediately before it. + +### 4. Shut down `rippled`: ### + +``` +rippled stop --conf=/path/to/rippled.cfg +``` + +### 5. Start `rippled` in stand-alone mode, loading the saved ledger. + +To load the most recent ledger version, you can use the `-a` and `--load` options: + +``` +rippled -a --load --conf=/path/to/rippled.cfg +``` + +To instead load a specific historical ledger, use the ``--ledger`` parameter with the ledger index or identifying hash of the ledger version to load: + +``` +rippled -a --ledger 19860944 --conf=/path/to/rippled.cfg +``` + +(TODO: test this) + +### 6. Manually advance the ledger. ### + +When you load a ledger with `--ledger` in stand-alone mode, it goes to the current open ledger, so you need to [manually advance the ledger](#advancing-ledgers-in-stand-alone-mode) to finalize it: + +``` +rippled ledger_accept --conf=/path/to/rippled.cfg +``` + + +Advancing Ledgers in Stand-Alone Mode +------------------------------------------------------------------------------- + +In stand-alone mode, `rippled` does not communicate to other members of the peer-to-peer network or participate in a consensus process. Instead, you must manually advance the ledger index using the [`ledger_accept` command](reference-rippled.html#ledger-accept): + +``` +rippled ledger_accept --conf=/path/to/rippled.cfg +``` + +In stand-alone mode, `rippled` makes no distinction between a "closed" ledger version and a "validated" ledger version. (For more information about the difference, see [The Ripple Ledger Consensus Process](https://ripple.com/knowledge_center/the-ripple-ledger-consensus-process/).) + +Whenever `rippled` closes a ledger, it reorders the transactions according to a deterministic but hard-to-game algorithm. (This is an important part of consensus, since different `rippled` servers may see transactions in a different order.) When using `rippled` in stand-alone mode, it is important to manually advance the ledger before submitting a transaction that depends on the result of a previous transaction. Otherwise, the second transaction might be executed before the first transaction when you manually advance the ledger. **Note:** You can safely submit multiple transactions from a single account to a single ledger, because `rippled` sorts transactions from the same account in ascending order by `Sequence` number. diff --git a/content/tutorial-multisign.md b/content/tutorial-multisign.md index 75a3e0047d..8207f3e372 100644 --- a/content/tutorial-multisign.md +++ b/content/tutorial-multisign.md @@ -1,5 +1,5 @@ Introduction to Multi-Signing -================================================================== +=============================================================================== Multi-signing in Ripple is the act of authorizing transactions for the Ripple Consensus Ledger by using a combination of multiple secret keys. After setting up multi-signing for an account, you can put the master secret in cold storage, or even disable the master key entirely. With multiple secret keys required to authorize a multi-signature, you can improve security in several ways. @@ -10,57 +10,26 @@ Multi-signing in Ripple is the act of authorizing transactions for the Ripple Co Availability of Multi-Signing ------------------------------------------------------------------ +------------------------------------------------------------------------------- -Multi-signing is due to be enabled by an **Amendment** to the Ripple Consensus Protocol. This Amendment must be approved by a consensus of validators showing consistent support for the feature over a period of time. For more information, see [Amendments](concept-amendments.html). +Multi-signing is built into `rippled` starting with version **0.31.0**. Because multi-signing is a change in transaction processing, the change is due to be enabled by an **Amendment** to the Ripple Consensus Protocol. This Amendment must be approved by a consensus of validators showing consistent support for the feature over a period of time. For more information, see [Amendments](concept-amendments.html). -You can test multi-signing by running `rippled` in stand-alone mode with the feature enabled. In stand-alone mode, `rippled` does not communicate with the rest of the Ripple peer-to-peer network, but you can perform most of the same actions on your local server only. This way, you can be sure that you are ready for multi-signing when it goes live. - - - -How to Multi-Sign -================================================================= - -The basic process of Multi-Signing a transaction is necessarily more complex than the process of signing a transaction with a single master key or regular key. - -## 1. Download and build rippled with multi-sign ## - -Until a binary for `rippled` with multi-signing is available, the best you can do is build it from source. - - $ git clone git@github.com:ripple/rippled.git - $ git checkout release - $ scons - -See [rippled build instructions](https://wiki.ripple.com/Rippled_build_instructions) for help building from source. - - -## 2. Configure rippled to enable MultiSign ## - -Add the following to the bottom of the config file: +You can test multi-signing by running `rippled` in [stand-alone mode](concept-stand-alone-mode.html) with the Multi-Sign feature enabled. To enable Multi-Sign for testing, add the following stanza to your `rippled.cfg`: [features] MultiSign -Note that this stanza is case-sensitive. -## 3. Start rippled in stand-alone mode ## +How to Multi-Sign +=============================================================================== -If you have previously synced to the network, you can have the server load the latest ledger as a starting place for stand-alone mode using the `--load` commandline option: +The basic process of Multi-Signing a transaction is necessarily more complex than the process of signing a transaction with a single master key or regular key. - $ sudo ./build/rippled --conf=/home/mduo13/.config/ripple/rippled.cfg -a --load +## 1. (Optional) Generate keys for a new wallet ## -If you'd rather start from scratch, you can use the `--start` commandline option to create a fresh ledger. In this case, the root account holds all 100 billion XRP: +This step is not strictly necessary. For this process, we generate and fund a new Ripple account and then set up multi-signing for that account. To set up multi-signing on an existing Ripple account, skip ahead to [Step 4: creating a signer list](4-create-a-signerlist-on-the-new-account-with-a-signerlistset-transaction). -**Address:** `rHb9CJAWyB4rj91VRWn96DkukG4bwdtyTh` - -**Secret:** `snoPBrXtMeMyMHUVTgbuqAfg1SUTb` ("masterpassphrase") - - -## 4. Generate keys for a new wallet ## - -This step is not strictly necessary. For this process, we generate and fund a new Ripple account and then set up multi-signing for that account. To set up multi-signing on an existing Ripple account, skip ahead to [Step 7: creating a signer list](#7-create-a-signerlist-on-the-account-with-a-signerlistset-transaction). - - $ build/rippled wallet_propose + $ rippled wallet_propose Loading: "/home/mduo13/.config/ripple/rippled.cfg" Connecting to 127.0.0.1:5005 { @@ -79,11 +48,11 @@ This step is not strictly necessary. For this process, we generate and fund a ne As always, be sure that an account's secret key never gets transmitted to anyone you don't trust with full control of that account, and certainly not unencrypted over the network. -## 5. Fund the new account with an existing wallet ## +## 2. Fund the new account with an existing wallet ## Again, this step is only necessary if you are setting up a new account to use multi-signing for this example. - $ build/rippled submit '{ + $ rippled submit '{ > "TransactionType" : "Payment", > "Account" : "", > "Destination" : "rnBFvgZphmN39GWzUJeUitaP22Fr9be75H", @@ -115,14 +84,13 @@ Again, this step is only necessary if you are setting up a new account to use mu } -## 6. Manually close the ledger ## +## 3. Close the ledger ## -In the live network, you would simply wait for the ledger to close -automatically as the result of consensus. However, a rippled node running in -stand-alone mode does not engage in consensus, so you must manually close the -ledger with the [`ledger_accept` command](rippled-apis.html#ledger-accept). +If you are using the live network, you can wait for the ledger to close automatically as the result of consensus. This typically takes 4-7 seconds. - $ build/rippled ledger_accept +If you are running `rippled` in stand-alone mode, you must manually close the ledger with the [`ledger_accept` command](reference-rippled.html#ledger-accept). + + $ rippled ledger_accept Loading: "/home/mduo13/.config/ripple/rippled.cfg" Connecting to 127.0.0.1:5005 { @@ -133,13 +101,13 @@ ledger with the [`ledger_accept` command](rippled-apis.html#ledger-accept). } -## 7. Create a SignerList on the new account with a SignerListSet transaction ## +## 4. Create a SignerList on the new account with a SignerListSet transaction ## -Before you can multi-sign transactions, you must associate a SignerList with your account, so that RCL knows which keys can be used to sign for you. You do this with a [SignerListSet transaction](transactions.html#signerlistset). +Before you can multi-sign transactions, you must associate a SignerList with your account, so that RCL knows which keys can be used to sign for you. You do this with a [SignerListSet transaction](reference-transaction-format.html#signerlistset). In this example, the SignerList has 3 members, with the weights and quorum set up such that multi-signed transactions need a signature from rsA2LpzuawewSBQXkiju3YQTMzW13pAAdW plus at least one signature from the other two members of the list. The `Account` values you use in your list can be funded accounts that exist in the ledger or just unused addresses. - $ build/rippled submit shqZZy2Rzs9ZqWTCQAdqc3bKgxnYq '{ + $ rippled submit shqZZy2Rzs9ZqWTCQAdqc3bKgxnYq '{ > "Flags": 0, > "TransactionType": "SignerListSet", > "Account": "rnBFvgZphmN39GWzUJeUitaP22Fr9be75H", @@ -210,11 +178,13 @@ In this example, the SignerList has 3 members, with the weights and quorum set u } -## 8. Manually close the ledger again ## +## 5. Close the ledger again ## -As before, you would wait for the ledger to close on a live network. We use the [`ledger_accept` command](reference-rippled.html#ledger-accept) to manually close the ledger when running `rippled` in stand-alone mode. +As before, on the live network, you can wait for the ledger to close automatically. - $ build/rippled ledger_accept +If running `rippled` in stand-alone mode, use the [`ledger_accept` command](reference-rippled.html#ledger-accept) to manually close the ledger: + + $ rippled ledger_accept Loading: "/home/mduo13/.config/ripple/rippled.cfg" Connecting to 127.0.0.1:5005 { @@ -225,11 +195,11 @@ As before, you would wait for the ledger to close on a live network. We use the } -## 9. Confirm the presence of the new signer list using account_objects ## +## 6. Confirm the presence of the new signer list using account_objects ## Normally an account has lots of different types of objects, but for this new account, the only thing we've done is add a SignerList, so it should be easy to find in the results of the [`account_objects` command](reference-rippled.html#account-objects). - $ build/rippled account_objects rnBFvgZphmN39GWzUJeUitaP22Fr9be75H + $ rippled account_objects rnBFvgZphmN39GWzUJeUitaP22Fr9be75H Loading: "/home/mduo13/.config/ripple/rippled.cfg" Connecting to 127.0.0.1:5005 { @@ -274,8 +244,7 @@ Normally an account has lots of different types of objects, but for this new acc } -10. Create a new transaction that you plan to multi-sign ------------------------------------------------------------------ +## 7. Create a new transaction that you plan to multi-sign ## You have to specify _everything_ about this transaction, including `Fee` and `Sequence`. Also include the field `SigningPubKey` as an empty string -- this @@ -307,9 +276,9 @@ it sometimes takes a while to collect signatures from multiple sources, you may want to include additional buffer in case the load fee increases in that time. -## 11. Get a signature using the sign_for command ## +## 8. Get a signature using the sign_for command ## - $ build/rippled sign_for rsA2LpzuawewSBQXkiju3YQTMzW13pAAdW '{ + $ rippled sign_for rsA2LpzuawewSBQXkiju3YQTMzW13pAAdW '{ > "TransactionType": "TrustSet", > "Account": "rnBFvgZphmN39GWzUJeUitaP22Fr9be75H", > "Flags": 262144, @@ -359,11 +328,11 @@ The valuable part in the response is the `Signers` field. This is the part that The other parts, such as the `tx_blob`, are not very useful at this point, unless you're "multi-signing" a transaction with only one signature. -## 12. Get additional signatures the same way ## +## 9. Get additional signatures the same way ## If the accounts in your SignerList are funded accounts, the secret key you use to sign for those accounts can come from the regular key (if they have one), or the master key (unless it's disabled). For accounts that don't exist in the ledger, you can only use the master secret associated with the address. - $ build/rippled sign_for rUpy3eEg8rqjqfUoLeBnZkscbKbFsKXC3v '{ + $ rippled sign_for rUpy3eEg8rqjqfUoLeBnZkscbKbFsKXC3v '{ "TransactionType": "TrustSet", "Account": "rnBFvgZphmN39GWzUJeUitaP22Fr9be75H", "Flags": 262144, @@ -411,14 +380,13 @@ If the accounts in your SignerList are funded accounts, the secret key you use t Depending on the SignerList you configured, you may need to repeat this step several times in order to get signatures from all the necessary parties. -13. Combine the signatures and submit ------------------------------------------------------------------ +## 10. Combine the signatures and submit ## Take the contents of all the `Signers` arrays from all the responses, and concatenate them in to a single `Signers` array field. The commandline syntax for the [`submit_multisigned` command](reference-rippled.html#submit-multisigned) takes a single JSON object with two elements: this combined `Signers` array; and `tx_json`, which is the transaction JSON that they signed. This command actually submits the transaction for inclusion in the ledger. In online mode, this relays it to other members of the network. - $ build/rippled submit_multisigned ' { + $ rippled submit_multisigned ' { > "Signers": [ > { > "Signer" : { @@ -494,13 +462,13 @@ This command actually submits the transaction for inclusion in the ledger. In on Take note of the `hash` value from the response (In this case, it's `878C1C988305D87070F3E961FC27AC9D02C46FFDD92FC7EBB74E962344E58C78`) so you can check the results of the transaction later. -## 14. Manually close the ledger one last time ## +## 14. Close the ledger one last time ## -Once again, you would wait for the ledger to close on a live network. We use -the [`ledger_accept` command](reference-rippled.html#ledger-accept) to manually -close the ledger when running `rippled` in stand-alone mode. +As before, on the live network, you can wait 4-7 seconds for the ledger to close automatically. - $ build/rippled ledger_accept +If running `rippled` in stand-alone mode, use the [`ledger_accept` command](reference-rippled.html#ledger-accept) to manually close the ledger: + + $ rippled ledger_accept Loading: "/home/mduo13/.config/ripple/rippled.cfg" Connecting to 127.0.0.1:5005 { @@ -515,7 +483,7 @@ close the ledger when running `rippled` in stand-alone mode. Use the hash value from the response to the `submit_multisigned` command. - $ build/rippled tx 878C1C988305D87070F3E961FC27AC9D02C46FFDD92FC7EBB74E962344E58C78 + $ rippled tx 878C1C988305D87070F3E961FC27AC9D02C46FFDD92FC7EBB74E962344E58C78 Loading: "/home/mduo13/.config/ripple/rippled.cfg" Connecting to 127.0.0.1:5005 { @@ -638,8 +606,6 @@ Use the hash value from the response to the `submit_multisigned` command. In particular, check that the `TransactionResult` is the string `tesSUCCESS`. -On the live network, you must also confirm that the `validated` field is set to -the boolean `true`. If not, you might need to wait longer for the consensus -process to finish; or your transaction may be unable to be included in a ledger -for some reason. In stand-alone mode, the server automatically considers a -ledger to be `validated` if it has been manually closed. +On the live network, you must also confirm that the `validated` field is set to the boolean `true`. If the field is not `true`, you might need to wait longer for the consensus process to finish; or your transaction may be unable to be included in a ledger for some reason. + +In stand-alone mode, the server automatically considers a ledger to be `validated` if it has been manually closed. diff --git a/data-api-v2-tool.html b/data-api-v2-tool.html index d0a712c2de..26bc275e0c 100644 --- a/data-api-v2-tool.html +++ b/data-api-v2-tool.html @@ -60,6 +60,7 @@
  • Reserves
  • Freeze
  • Amendments
    • +
  • Stand-Alone Mode
  • diff --git a/index.html b/index.html index 58ac4c14cd..c3d088bf1f 100644 --- a/index.html +++ b/index.html @@ -67,6 +67,7 @@
  • Reserves
  • Freeze
  • Amendments
    • +
  • Stand-Alone Mode
  • @@ -153,6 +154,7 @@ Ripple’s distributed settlement network is built on open-source technology tha
  • Reserves
  • Freeze
  • Amendments
    • +
  • Stand-Alone Mode
    • diff --git a/reference-data-api.html b/reference-data-api.html index f3073eb5af..4c32a369c0 100644 --- a/reference-data-api.html +++ b/reference-data-api.html @@ -74,6 +74,7 @@
  • Reserves
  • Freeze
  • Amendments
    • +
  • Stand-Alone Mode
  • diff --git a/reference-ledger-format.html b/reference-ledger-format.html index 05ac9bfa47..a8c8207562 100644 --- a/reference-ledger-format.html +++ b/reference-ledger-format.html @@ -74,6 +74,7 @@
  • Reserves
  • Freeze
  • Amendments
    • +
  • Stand-Alone Mode
  • diff --git a/reference-rippleapi.html b/reference-rippleapi.html index aa0bc9d37c..b275d4f15d 100644 --- a/reference-rippleapi.html +++ b/reference-rippleapi.html @@ -74,6 +74,7 @@
  • Reserves
  • Freeze
  • Amendments
    • +
  • Stand-Alone Mode
  • diff --git a/reference-rippled.html b/reference-rippled.html index a719b036ce..814a405814 100644 --- a/reference-rippled.html +++ b/reference-rippled.html @@ -74,6 +74,7 @@
  • Reserves
  • Freeze
  • Amendments
    • +
  • Stand-Alone Mode
  • diff --git a/reference-transaction-format.html b/reference-transaction-format.html index bd5150a04f..0d5b611f51 100644 --- a/reference-transaction-format.html +++ b/reference-transaction-format.html @@ -74,6 +74,7 @@
  • Reserves
  • Freeze
  • Amendments
    • +
  • Stand-Alone Mode
  • diff --git a/ripple-api-tool.html b/ripple-api-tool.html index 9c056723df..a747aca3f8 100644 --- a/ripple-api-tool.html +++ b/ripple-api-tool.html @@ -60,6 +60,7 @@
  • Reserves
  • Freeze
  • Amendments
    • +
  • Stand-Alone Mode
  • diff --git a/tool-jsonrpc.html b/tool-jsonrpc.html index b10b94e614..442c28d2a8 100644 --- a/tool-jsonrpc.html +++ b/tool-jsonrpc.html @@ -60,6 +60,7 @@
  • Reserves
  • Freeze
  • Amendments
    • +
  • Stand-Alone Mode
  • diff --git a/tool/dactyl-config.yml b/tool/dactyl-config.yml index 1a3d154f25..15441eebbc 100644 --- a/tool/dactyl-config.yml +++ b/tool/dactyl-config.yml @@ -172,6 +172,13 @@ pages: ripple.com: https://wiki.ripple.com/Understanding:_Feature_adoption sidebar: true + - name: Stand-Alone Mode + category: Concepts + html: concept-stand-alone-mode.html + md: concept-stand-alone-mode.md + ripple.com: https://wiki.ripple.com/Rippled#--standalone.2C_-a + sidebar: true + # "Best Practices" documents are mostly in the same category as tutorials - name: Issuing and Operational Addresses category: Best Practices diff --git a/tutorial-gateway-guide.html b/tutorial-gateway-guide.html index dca7beb6b3..573c8373f0 100644 --- a/tutorial-gateway-guide.html +++ b/tutorial-gateway-guide.html @@ -74,6 +74,7 @@
  • Reserves
  • Freeze
  • Amendments
    • +
  • Stand-Alone Mode
  • diff --git a/tutorial-multisign.html b/tutorial-multisign.html index 212bdc7553..c39d9b0ffd 100644 --- a/tutorial-multisign.html +++ b/tutorial-multisign.html @@ -74,6 +74,7 @@
  • Reserves
  • Freeze
  • Amendments
    • +
  • Stand-Alone Mode
  • @@ -126,11 +127,7 @@

    Introduction to Multi-Signing

    -

    Multi-signing in Ripple is the act of authorizing transactions for the Ripple -Consensus Ledger by using a combination of multiple secret keys. After setting -up multi-signing for an account, you can put the master secret in cold storage, -or even disable the master key entirely. With multiple secret keys required to -authorize a multi-signature, you can improve security in several ways.

    +

    Multi-signing in Ripple is the act of authorizing transactions for the Ripple Consensus Ledger by using a combination of multiple secret keys. After setting up multi-signing for an account, you can put the master secret in cold storage, or even disable the master key entirely. With multiple secret keys required to authorize a multi-signature, you can improve security in several ways.

    • If you keep an account's keys on different devices, a malicious user must compromise multiple machines in order to send transactions on your behalf.
    • If the keys to an account are in the custody of entirely different people, those people must collaborate in order to send transaction from that account.
      • @@ -138,48 +135,16 @@ authorize a multi-signature, you can improve security in several ways.

    • Even more uses than can be described here.

    Availability of Multi-Signing

    -

    Multi-signing is due to be enabled by an Amendment to the Ripple Consensus -Protocol. This Amendment must be approved by a consensus of validators showing -consistent support for the feature over a period of time. For more information, -see Amendments (TODO: link).

    -

    You can test multi-signing by running rippled in stand-alone mode with the -feature enabled. In stand-alone mode, rippled does not communicate with the -rest of the Ripple peer-to-peer network, but you can perform most of the same -actions on your local server only. This way, you can be sure that you are ready -for multi-signing when it goes live.

    -

    How to Multi-Sign

    -

    The basic process of Multi-Signing a transaction is necessarily more -complex than the process of signing a transaction with a single master key or -regular key.

    -

    1. Download and build rippled with multi-sign

    -

    Until a binary for rippled with multi-signing is available, the best you can do is build it from source.

    -
    $ git clone git@github.com:scottschurr/rippled.git (TODO: switch to a Ripple Labs repo when available)
-$ git checkout fix-sign_for
-$ scons
-
    -

    See rippled build instructions for help building from source.

    -

    2. Configure rippled to enable MultiSign

    -

    Add the following to the bottom of the config file:

    +

    Multi-signing is built into rippled starting with version 0.31.0. Because multi-signing is a change in transaction processing, the change is due to be enabled by an Amendment to the Ripple Consensus Protocol. This Amendment must be approved by a consensus of validators showing consistent support for the feature over a period of time. For more information, see Amendments.

    +

    You can test multi-signing by running rippled in stand-alone mode with the Multi-Sign feature enabled. To enable Multi-Sign for testing, add the following stanza to your rippled.cfg:

    [features]
 MultiSign
    -

    Note that this stanza is case-sensitive.

    -

    3. Start rippled in stand-alone mode

    -

    If you have previously synced to the network, you can have the server load the -latest ledger as a starting place for stand-alone mode using the --load -commandline option:

    -
    $ sudo ./build/rippled --conf=/home/mduo13/.config/ripple/rippled.cfg -a --load
-
    -

    If you'd rather start from scratch, you can use the --start commandline -option to create a fresh ledger. In this case, the root account holds all -100 billion XRP:

    -

    Address: rHb9CJAWyB4rj91VRWn96DkukG4bwdtyTh

    -

    Secret: snoPBrXtMeMyMHUVTgbuqAfg1SUTb ("masterpassphrase")

    -

    4. Generate keys for a new wallet

    -

    This step is not strictly necessary. For this process, we generate the keys to -a new Ripple account and then set up multi-signing for that account. To set up -multi-signing on an existing Ripple account, just use the keys to that account.

    -
    $ build/rippled wallet_propose
+
    How to Multi-Sign
    
+
    The basic process of Multi-Signing a transaction is necessarily more complex than the process of signing a transaction with a single master key or regular key.
    
+
    1. (Optional) Generate keys for a new wallet
    
+
    This step is not strictly necessary. For this process, we generate and fund a new Ripple account and then set up multi-signing for that account. To set up multi-signing on an existing Ripple account, skip ahead to Step 4: creating a signer list.
    
+
    $ rippled wallet_propose
 Loading: "/home/mduo13/.config/ripple/rippled.cfg"
 Connecting to 127.0.0.1:5005
 {
@@ -195,13 +160,10 @@ Connecting to 127.0.0.1:5005
    }
 }
 
    
-
    As always, be sure that an account's secret key never gets transmitted to 
-anyone you don't trust with full control of that account, and certainly not 
-unencrypted over the network.
    
-
    5. Fund the new account with an existing wallet
    
-
    Again, this step is only necessary if you are setting up a new account to use 
-multi-signing for this example.
    
-
    $ build/rippled submit <your existing account secret> '{
+
    As always, be sure that an account's secret key never gets transmitted to anyone you don't trust with full control of that account, and certainly not unencrypted over the network.
    
+
    2. Fund the new account with an existing wallet
    
+
    Again, this step is only necessary if you are setting up a new account to use multi-signing for this example.
    
+
    $ rippled submit <your existing account secret> '{
 >   "TransactionType" : "Payment",
 >   "Account" : "<your existing account address>",
 >   "Destination" : "rnBFvgZphmN39GWzUJeUitaP22Fr9be75H",
@@ -232,12 +194,10 @@ Connecting to 127.0.0.1:5005
    }
 }
 
    
-
    6. Manually close the ledger
    
-
    In the live network, you would simply wait for the ledger to close 
-automatically as the result of consensus. However, a rippled node running in 
-stand-alone mode does not engage in consensus, so you must manually close the 
-ledger with the ledger_accept command.
    
-
    $ build/rippled ledger_accept
+
    3. Close the ledger
    
+
    If you are using the live network, you can wait for the ledger to close automatically as the result of consensus. This typically takes 4-7 seconds.
    
+
    If you are running rippled in stand-alone mode, you must manually close the ledger with the ledger_accept command.
    
+
    $ rippled ledger_accept
 Loading: "/home/mduo13/.config/ripple/rippled.cfg"
 Connecting to 127.0.0.1:5005
 {
@@ -247,16 +207,10 @@ Connecting to 127.0.0.1:5005
    }
 }
 
    
-
    7. Create a SignerList on the new account with a SignerListSet transaction
    
-
    Before you can multi-sign transactions, you must associate a SignerList with 
-your account, so that RCL knows which keys can be used to sign for you. You do 
-this with a SignerListSet transaction.
    
-
    In this example, the SignerList has 3 members, with the weights and quorum set 
-up such that multi-signed transactions need a signature from 
-rsA2LpzuawewSBQXkiju3YQTMzW13pAAdW plus at least one signature from the other 
-two members of the list. The Account values you use in your list can be 
-funded accounts that exist in the ledger or just unused addresses.
    
-
    $ build/rippled submit shqZZy2Rzs9ZqWTCQAdqc3bKgxnYq '{
+
    4. Create a SignerList on the new account with a SignerListSet transaction
    
+
    Before you can multi-sign transactions, you must associate a SignerList with your account, so that RCL knows which keys can be used to sign for you. You do this with a SignerListSet transaction.
    
+
    In this example, the SignerList has 3 members, with the weights and quorum set up such that multi-signed transactions need a signature from rsA2LpzuawewSBQXkiju3YQTMzW13pAAdW plus at least one signature from the other two members of the list. The Account values you use in your list can be funded accounts that exist in the ledger or just unused addresses.
    
+
    $ rippled submit shqZZy2Rzs9ZqWTCQAdqc3bKgxnYq '{
 >     "Flags": 0,
 >     "TransactionType": "SignerListSet",
 >     "Account": "rnBFvgZphmN39GWzUJeUitaP22Fr9be75H",
@@ -326,11 +280,10 @@ Connecting to 127.0.0.1:5005
    }
 }
 
    
-
    8. Manually close the ledger again
    
-
    As before, you would wait for the ledger to close on a live network. We use 
-the ledger_accept command to manually 
-close the ledger when running rippled in stand-alone mode.
    
-
    $ build/rippled ledger_accept
+
    5. Close the ledger again
    
+
    As before, on the live network, you can wait for the ledger to close automatically.
    
+
    If running rippled in stand-alone mode, use the ledger_accept command to manually close the ledger:
    
+
    $ rippled ledger_accept
 Loading: "/home/mduo13/.config/ripple/rippled.cfg"
 Connecting to 127.0.0.1:5005
 {
@@ -340,12 +293,9 @@ Connecting to 127.0.0.1:5005
    }
 }
 
    
-
    9. Confirm the presence of the new signer list using account_objects
    
-
    Normally an account has lots of different types of objects, but for this new 
-account, the only thing we've done is add a SignerList, so it should be easy to 
-find in the results of the 
-account_objects command.
    
-
    $ build/rippled account_objects rnBFvgZphmN39GWzUJeUitaP22Fr9be75H
+
    6. Confirm the presence of the new signer list using account_objects
    
+
    Normally an account has lots of different types of objects, but for this new account, the only thing we've done is add a SignerList, so it should be easy to find in the results of the account_objects command.
    
+
    $ rippled account_objects rnBFvgZphmN39GWzUJeUitaP22Fr9be75H
 Loading: "/home/mduo13/.config/ripple/rippled.cfg"
 Connecting to 127.0.0.1:5005
 {
@@ -389,9 +339,9 @@ Connecting to 127.0.0.1:5005
    }
 }
 
    
-
    10. Create a new transaction that you plan to multi-sign
    
-
    You have to specify everything about this transaction, including Fee and 
-Sequence. Also include the field SigningPubKey as an empty string -- this
+
    7. Create a new transaction that you plan to multi-sign
    
+
    You have to specify everything about this transaction, including Fee and
+Sequence. Also include the field SigningPubKey as an empty string -- this
 indicates that the transaction is multi-signed.
    
 
    Here's an example transaction we can send from our test account:
    
 
    {
@@ -408,15 +358,15 @@ indicates that the transaction is multi-signed.
    
     "Fee": "12000"
 }
 
    
-
    (If you started from a fresh ledger, you first need to fund the account 
+
    (If you started from a fresh ledger, you first need to fund the account
 specified by the issuer in this example, and then manually close the ledger.)
    
-
    Keep in mind that the Fee for multi-signed transactions is significantly 
-higher than for regularly-signed transactions. It should be (N+1) times the 
+
    Keep in mind that the Fee for multi-signed transactions is significantly
+higher than for regularly-signed transactions. It should be (N+1) times the
 normal fee, where N is the number of signatures you plan to provide. Given that
 it sometimes takes a while to collect signatures from multiple sources, you may
 want to include additional buffer in case the load fee increases in that time.
    
-
    11. Get a signature using the sign_for command
    
-
    $ build/rippled sign_for rsA2LpzuawewSBQXkiju3YQTMzW13pAAdW <rsA2's secret> '{
+
    8. Get a signature using the sign_for command
    
+
    $ rippled sign_for rsA2LpzuawewSBQXkiju3YQTMzW13pAAdW <rsA2's secret> '{
 >     "TransactionType": "TrustSet",
 >     "Account": "rnBFvgZphmN39GWzUJeUitaP22Fr9be75H",
 >     "Flags": 262144,
@@ -461,17 +411,11 @@ Connecting to 127.0.0.1:5005
    }
 }
 
    
-
    The valuable part in the response is the Signers field. This is the part that 
-you're going to need later in order to construct the full, multi-signed 
-transaction.
    
-
    The other parts, such as the tx_blob, are not very useful at this point, 
-unless you're "multi-signing" a transaction with only one signature.
    
-
    12. Get additional signatures the same way
    
-
    If the accounts in your SignerList are funded accounts, the secret key you use 
-to sign for those accounts can come from the regular key (if they have one), or 
-the master key (unless it's disabled). For accounts that don't exist in the 
-ledger, you can only use the master secret associated with the address.
    
-
    $ build/rippled sign_for rUpy3eEg8rqjqfUoLeBnZkscbKbFsKXC3v <rUpy's secret> '{
+
    The valuable part in the response is the Signers field. This is the part that you're going to need later in order to construct the full, multi-signed transaction.
    
+
    The other parts, such as the tx_blob, are not very useful at this point, unless you're "multi-signing" a transaction with only one signature.
    
+
    9. Get additional signatures the same way
    
+
    If the accounts in your SignerList are funded accounts, the secret key you use to sign for those accounts can come from the regular key (if they have one), or the master key (unless it's disabled). For accounts that don't exist in the ledger, you can only use the master secret associated with the address.
    
+
    $ rippled sign_for rUpy3eEg8rqjqfUoLeBnZkscbKbFsKXC3v <rUpy's secret> '{
     "TransactionType": "TrustSet",
     "Account": "rnBFvgZphmN39GWzUJeUitaP22Fr9be75H",
     "Flags": 262144,
@@ -516,17 +460,11 @@ Connecting to 127.0.0.1:5005
    }
 }
 
    
-
    Depending on the SignerList you configured, you may need to repeat this step
-several times in order to get signatures from all the necessary parties.
    
-
    13. Combine the signatures and submit
    
-
    Take the contents of all the Signers arrays from all the responses, and 
-concatenate them in to a single Signers array field. The commandline syntax 
-for the submit_multisigned command 
-takes a single JSON object with two elements: this combined Signers array; 
-and tx_json, which is the transaction JSON that they signed.
    
-
    This command actually submits the transaction for inclusion in the ledger. In 
-online mode, this relays it to other members of the network.
    
-
    $ build/rippled submit_multisigned '    {
+
    Depending on the SignerList you configured, you may need to repeat this step several times in order to get signatures from all the necessary parties.
    
+
    10. Combine the signatures and submit
    
+
    Take the contents of all the Signers arrays from all the responses, and concatenate them in to a single Signers array field. The commandline syntax for the submit_multisigned command takes a single JSON object with two elements: this combined Signers array; and tx_json, which is the transaction JSON that they signed.
    
+
    This command actually submits the transaction for inclusion in the ledger. In online mode, this relays it to other members of the network.
    
+
    $ rippled submit_multisigned '    {
 >         "Signers": [
 >             {
 >                 "Signer" : {
@@ -599,14 +537,11 @@ Connecting to 127.0.0.1:5005
    }
 }
 
    
-
    Take note of the hash value from the response (In this case, it's
-878C1C988305D87070F3E961FC27AC9D02C46FFDD92FC7EBB74E962344E58C78) so you can 
-check the results of the transaction later.
    
-
    14. Manually close the ledger one last time
    
-
    Once again, you would wait for the ledger to close on a live network. We use 
-the ledger_accept command to manually 
-close the ledger when running rippled in stand-alone mode.
    
-
    $ build/rippled ledger_accept
+
    Take note of the hash value from the response (In this case, it's 878C1C988305D87070F3E961FC27AC9D02C46FFDD92FC7EBB74E962344E58C78) so you can check the results of the transaction later.
    
+
    14. Close the ledger one last time
    
+
    As before, on the live network, you can wait 4-7 seconds for the ledger to close automatically.
    
+
    If running rippled in stand-alone mode, use the ledger_accept command to manually close the ledger:
    
+
    $ rippled ledger_accept
 Loading: "/home/mduo13/.config/ripple/rippled.cfg"
 Connecting to 127.0.0.1:5005
 {
@@ -618,7 +553,7 @@ Connecting to 127.0.0.1:5005
 
    
 
    15. Confirm the results of the transaction
    
 
    Use the hash value from the response to the submit_multisigned command.
    
-
    $ build/rippled tx 878C1C988305D87070F3E961FC27AC9D02C46FFDD92FC7EBB74E962344E58C78
+
    $ rippled tx 878C1C988305D87070F3E961FC27AC9D02C46FFDD92FC7EBB74E962344E58C78
 Loading: "/home/mduo13/.config/ripple/rippled.cfg"
 Connecting to 127.0.0.1:5005
 {
@@ -739,12 +674,9 @@ Connecting to 127.0.0.1:5005
    }
 }
 
    
-
    In particular, check that the TransactionResult is the string tesSUCCESS. 
    
-
    On the live network, you must also confirm that the validated field is set to 
-the boolean true. If not, you might need to wait longer for the consensus 
-process to finish; or your transaction may be unable to be included in a ledger 
-for some reason. In stand-alone mode, the server automatically considers a 
-ledger to be validated if it has been manually closed.
    
+
    In particular, check that the TransactionResult is the string tesSUCCESS.
    
+
    On the live network, you must also confirm that the validated field is set to the boolean true. If the field is not true, you might need to wait longer for the consensus process to finish; or your transaction may be unable to be included in a ledger for some reason.
    
+
    In stand-alone mode, the server automatically considers a ledger to be validated if it has been manually closed.
    • diff --git a/tutorial-reliable-transaction-submission.html b/tutorial-reliable-transaction-submission.html index a70b478382..5d528f8201 100644 --- a/tutorial-reliable-transaction-submission.html +++ b/tutorial-reliable-transaction-submission.html @@ -74,6 +74,7 @@
  • Reserves
  • Freeze
  • Amendments
    • +
  • Stand-Alone Mode
  • diff --git a/tutorial-rippleapi-beginners-guide.html b/tutorial-rippleapi-beginners-guide.html index b6883e0dc5..1d7625718e 100644 --- a/tutorial-rippleapi-beginners-guide.html +++ b/tutorial-rippleapi-beginners-guide.html @@ -74,6 +74,7 @@
  • Reserves
  • Freeze
  • Amendments
    • +
  • Stand-Alone Mode
  • diff --git a/tutorial-rippled-setup.html b/tutorial-rippled-setup.html index 8d71922483..bb8f52b4ac 100644 --- a/tutorial-rippled-setup.html +++ b/tutorial-rippled-setup.html @@ -74,6 +74,7 @@
  • Reserves
  • Freeze
  • Amendments
    • +
  • Stand-Alone Mode