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

Merge pull request #448 from mDuo13/rippled_v110

Browse Source 
rippled v1.1.0 Changes [Waiting for official release]
This commit is contained in:
Rome Reginelli
2018-09-14 18:11:30 -07:00
committed by GitHub
parent 891def5003 4b30d04aa4
commit 4de64228d8
44 changed files with 615 additions and 96 deletions
Download Patch File Download Diff File Expand all files Collapse all files

2
assets/css/devportal.css
View File

@@ -381,6 +381,8 @@ pre code {
background-color: #E1E4E8;
border: 1px solid #C9CDD1;
border-radius: 4px;
display: block;
padding: 0.5em;
}
.code_sample pre code.expanded {
overflow: visible;

10
content/_snippets/depositauth-semantics-table.html
View File

@@ -70,7 +70,7 @@
<td class="depauth-maybe">Cross-currency only</td>
<td class="depauth-ok">OK</td>
<td class="depauth-spacer">&nbsp;</td>
<td class="depauth-no">No Permission</td>
<td class="depauth-maybe">Cross-currency only<sup>1</sup></td>
<td class="depauth-no">No Permission</td>
<td class="depauth-ok">OK</td>
</tr>
@@ -79,7 +79,7 @@
<td class="depauth-maybe">Cross-currency only</td>
<td class="depauth-ok">OK</td>
<td class="depauth-spacer">&nbsp;</td>
<td class="depauth-no">No Permission</td>
<td class="depauth-maybe">Cross-currency only<sup>1</sup></td>
<td class="depauth-maybe">XRP payments up to the minimum reserve</td>
<td class="depauth-ok">OK</td>
</tr>
@@ -88,7 +88,7 @@
<td class="depauth-maybe">Cross-currency only</td>
<td class="depauth-ok">OK</td>
<td class="depauth-spacer">&nbsp;</td>
<td class="depauth-no">No Permission</td>
<td class="depauth-maybe">Cross-currency only<sup>1</sup></td>
<td class="depauth-maybe">Balance changes from rippling</td>
<td class="depauth-ok">OK</td>
</tr>
@@ -97,7 +97,7 @@
<td class="depauth-maybe">Cross-currency only</td>
<td class="depauth-ok">OK</td>
<td class="depauth-spacer">&nbsp;</td>
<td class="depauth-no">No Permission</td>
<td class="depauth-maybe">Cross-currency only<sup>1</sup></td>
<td class="depauth-maybe">Balance changes from executing offers</td>
<td class="depauth-ok">OK</td>
</tr>
@@ -132,6 +132,8 @@
</tr>
</table>
<p class="depauth-subtype"><sup>1</sup>: The DepositPreauth amendment fixes a bug in DepositAuth which causes cross-currency payments to oneself to fail if the account requires deposit authorization. If the DepositPreauth amendment is not enabled, these cases result in "No Permission" instead.</p>
<style type="text/css">
.depauth-txtype {
font-weight: bold;

1
content/_snippets/public-signing-note.md Normal file
View File

@@ -0,0 +1 @@
_By default, this method is [admin-only](admin-rippled-methods.html). It can be used as a public method if the server has [enabled public signing](enable-public-signing.html)._

1
content/_snippets/rippled-api-links.md
View File

@@ -46,6 +46,7 @@
"channel_verify",
"connect",
"consensus_info",
"deposit_authorized",
"feature",
"fee",
"fetch_info",

1
content/_snippets/rippled_versions.md
View File

@@ -32,3 +32,4 @@
[New in: rippled 0.80.1]: https://github.com/ripple/rippled/releases/tag/0.80.1 "BADGE_BLUE"
[New in: rippled 0.90.0]: https://github.com/ripple/rippled/releases/tag/0.90.0 "BADGE_BLUE"
[New in: rippled 1.0.0]: https://github.com/ripple/rippled/releases/tag/1.0.0 "BADGE_BLUE"
[New in: rippled 1.1.0]: https://github.com/ripple/rippled/releases/tag/1.1.0 "BADGE_BLUE"

1
content/_snippets/tx-type-links.md
View File

@@ -3,6 +3,7 @@
"CheckCancel",
"CheckCash",
"CheckCreate",
"DepositPreauth",
"EscrowCancel",
"EscrowCreate",
"EscrowFinish",

14
content/concepts/payment-system-basics/accounts/depositauth.md
View File

@@ -70,9 +70,9 @@ Accounts with DepositAuth enabled can _preauthorize_ certain senders, to allow p
Preauthorization is currency-agnostic. You cannot preauthorize accounts for specific currencies only.
To preauthorize a particular sender, send a DepositPreauth transaction <!--{# TODO: link when the transaction reference is updated #}--> with the address of another account to preauthorize in the `Authorize` field. To revoke preauthorization, provide the other account's address in the `Unauthorize` field instead. Specify your own address in the `Account` field as usual. You can preauthorize or unauthorize accounts even if you do not currently have DepositAuth enabled; the preauthorization status you set for other accounts is saved, but has no effect unless you enable DepositAuth. An account cannot preauthorize itself.
To preauthorize a particular sender, send a [DepositPreauth transaction][] with the address of another account to preauthorize in the `Authorize` field. To revoke preauthorization, provide the other account's address in the `Unauthorize` field instead. Specify your own address in the `Account` field as usual. You can preauthorize or unauthorize accounts even if you do not currently have DepositAuth enabled; the preauthorization status you set for other accounts is saved, but has no effect unless you enable DepositAuth. An account cannot preauthorize itself. Preauthorizations are one-directional, and have no effect on payments going the opposite direction.
Preauthorizing another account adds an object to the ledger, which increases the [owner reserve](reserves.html#owner-reserves) of the account providing the authorization. If the account revokes this preauthorization, doing so removes the object and the reserve decreases accordingly.
Preauthorizing another account adds a [DepositPreauth object](depositpreauth-object.html) to the ledger, which increases the [owner reserve](reserves.html#owner-reserves) of the account providing the authorization. If the account revokes this preauthorization, doing so removes the object and the reserve decreases accordingly.
After the DepositPreauth transaction has been processed, the authorized account can send funds to your account, even if you have DepositAuth enabled, using any of the following transaction types:
@@ -82,9 +82,19 @@ After the DepositPreauth transaction has been processed, the authorized account
Preauthorization has no effect on the other ways to send money to an account with DepositAuth enabled. See [Precise Semantics](#precise-semantics) for the exact rules.
### Checking for Authorization
You can use the [deposit_authorized method][] to see if an account is authorized to deposit to another account. This method checks two things:
- Whether the destination account requires Deposit Authorization. (If it does not require authorization, then all source accounts are considered authorized.)
- Whether the source account is preauthorized to send money to the destination.
## See Also
- The [DepositPreauth transaction][] reference.
- The [DepositPreauth ledger object type](depositpreauth-object.html).
- The [deposit_authorized method][] of the [`rippled` API](rippled-api.html).
- The [Authorized Trust Lines](authorized-trust-lines.html) feature (`RequireAuth` flag) limits which counterparties can hold non-XRP currencies issued by an account.
- The `DisallowXRP` flag indicates that an account should not receive XRP. This is a softer protection than Deposit Authorization, and is not enforced by the XRP Ledger. (Client applications should honor this flag or at least warn about it.)
- The `RequireDest` flag indicates that an account can only receive currency amounts if the sending transaction specifies a [Destination Tag](become-an-xrp-ledger-gateway.html#source-and-destination-tags). This protects users from forgetting to indicate the purpose of a payment, but does not protect recipients from unknown senders, who can make up arbitrary destination tags.

2
content/news/known-amendments.md
View File

@@ -104,6 +104,8 @@ Provides users of [deposit authorization](depositauth.html) with a way to preaut
Adds a new transaction type, DepositPreauth for adding or removing preauthorization, and a DepositPreauth ledger object type for tracking preauthorizations from one account to another. Adds a JSON-RPC command, `deposit_authorized`, to query whether an account is authorized to send payments directly to another.
Also changes the behavior of cross-currency Payments from an account to itself when that account requires deposit authorization. Without this amendment, those payments always fail with the code tecNO_PERMISSION. With this amendment, those payments succeed as they would with Deposit Authorization disabled.
## EnforceInvariants
[EnforceInvariants]: #enforceinvariants

2
content/references/rippled-api/admin-rippled-methods/logging-and-data-management-methods/can_delete.md
View File

@@ -1,5 +1,5 @@
# can_delete
[[Source]<br>](https://github.com/ripple/rippled/blob/develop/src/ripple/rpc/handlers/CanDelete.cpp "Source")
[[Source]<br>](https://github.com/ripple/rippled/blob/master/src/ripple/rpc/handlers/CanDelete.cpp "Source")
With `online_delete` and `advisory_delete` configuration options enabled, the `can_delete` method informs the rippled server of the latest ledger which may be deleted.

2
content/references/rippled-api/admin-rippled-methods/server-control-methods/stop.md
View File

@@ -1,5 +1,5 @@
# stop
[[Source]<br>](https://github.com/ripple/rippled/blob/develop/src/ripple/rpc/handlers/Stop.cpp "Source")
[[Source]<br>](https://github.com/ripple/rippled/blob/master/src/ripple/rpc/handlers/Stop.cpp "Source")
Gracefully shuts down the server.

2
content/references/rippled-api/admin-rippled-methods/status-and-debugging-methods/feature.md
View File

@@ -1,5 +1,5 @@
# feature
[[Source]<br>](https://github.com/ripple/rippled/blob/develop/src/ripple/rpc/handlers/Feature1.cpp "Source")
[[Source]<br>](https://github.com/ripple/rippled/blob/master/src/ripple/rpc/handlers/Feature1.cpp "Source")
The `feature` command returns information about [amendments](amendments.html) this server knows about, including whether they are enabled and whether the server is voting in favor of those amendments in the [amendment process](amendments.html#amendment-process). [New in: rippled 0.31.0][]

1
content/references/rippled-api/commandline-usage.md
View File

@@ -116,6 +116,7 @@ While running unit tests, you can specify the [Generic Options](#generic-options
| Option | Short Version | Description |
|:-----------------------------------|:--------------|:------------------------|
| `--unittest-ipv6` | | Use [IPv6](https://en.wikipedia.org/wiki/IPv6) to connect to the local server when running unit tests. If not provided, unit tests use IPv4 instead. [New in: rippled 1.1.0][] |
| `--unittest-jobs {NUMBER_OF_JOBS}` | | Use the specified number of processes to run unit tests. This can finish running tests faster on multi-core systems. The `{NUMBER_OF_JOBS}` should be a positive integer indicating the number of processes to use. |
| `--unittest-log` | | Allow unit tests to write to logs even if `--quiet` is specified. (No effect otherwise.) |
| `--quiet` | `-q` | Print fewer diagnostic messages when running unit tests. |

2
content/references/rippled-api/ledger-data-formats/ledger-object-ids.md
View File

@@ -1,7 +1,7 @@
# Ledger Object IDs
<a id="sha512half"></a>
All objects in a ledger's state tree have a unique ID. This field is returned as the `index` field in JSON, at the same level as the object's contents. The ID is derived by hashing important contents of the object, along with a [namespace identifier](https://github.com/ripple/rippled/blob/master/src/ripple/protocol/LedgerFormats.h#L97). The [ledger object type](ledger-object-types.html) determines which namespace identifier to use and which contents to include in the hash. This ensures every ID is unique. To calculate the hash, `rippled` uses SHA-512 and then truncates the result to the first 256 bytes. This algorithm, informally called **SHA-512Half**, provides an output that has comparable security to SHA-256, but runs faster on 64-bit processors.
All objects in a ledger's state tree have a unique ID. This field is returned as the `index` field in JSON, at the same level as the object's contents. The ID is derived by hashing important contents of the object, along with a [namespace identifier](https://github.com/ripple/rippled/blob/master/src/ripple/protocol/LedgerFormats.h#L99). The [ledger object type](ledger-object-types.html) determines which namespace identifier to use and which contents to include in the hash. This ensures every ID is unique. To calculate the hash, `rippled` uses SHA-512 and then truncates the result to the first 256 bytes. This algorithm, informally called **SHA-512Half**, provides an output that has comparable security to SHA-256, but runs faster on 64-bit processors.
![Diagram: rippled uses SHA-512Half to generate IDs for ledger objects. The space key prevents IDs for different object types from colliding.](img/ledger-indexes.png)

2
content/references/rippled-api/ledger-data-formats/ledger-object-types/amendments.md
View File

@@ -1,5 +1,5 @@
# Amendments
[[Source]<br>](https://github.com/ripple/rippled/blob/develop/src/ripple/protocol/impl/LedgerFormats.cpp#L110-L113 "Source")
[[Source]<br>](https://github.com/ripple/rippled/blob/master/src/ripple/protocol/impl/LedgerFormats.cpp#L110-L113 "Source")
The `Amendments` object type contains a list of [Amendments](amendments.html) that are currently active. Each ledger version contains **at most one** `Amendments` object.

2
content/references/rippled-api/ledger-data-formats/ledger-object-types/check.md
View File

@@ -1,5 +1,5 @@
# Check
[[Source]<br>](https://github.com/ripple/rippled/blob/develop/src/ripple/protocol/impl/LedgerFormats.cpp#L158 "Source")
[[Source]<br>](https://github.com/ripple/rippled/blob/master/src/ripple/protocol/impl/LedgerFormats.cpp#L157-L170 "Source")
_Requires the [Checks Amendment](known-amendments.html#checks)._

49
content/references/rippled-api/ledger-data-formats/ledger-object-types/depositpreauth.md Normal file
View File

@@ -0,0 +1,49 @@
# DepositPreauth
[[Source]<br>](https://github.com/ripple/rippled/blob/master/src/ripple/protocol/impl/LedgerFormats.cpp#L172-L178 "Source")
A `DepositPreauth` object tracks a preauthorization from one account to another. [DepositPreauth transactions][] create these objects.
This has no effect on processing of transactions unless the account that provided the preauthorization requires [Deposit Authorization](depositauth.html). In that case, the account that was preauthorized can send payments and other transactions directly to the account that provided the preauthorization. Preauthorizations are one-directional, and have no effect on payments going the opposite direction.
## Example {{currentpage.name}} JSON
```json
{
"LedgerEntryType" : "DepositPreauth",
"Account" : "rsUiUMpnrgxQp24dJYZDhmV4bE3aBtQyt8",
"Authorize" : "rEhxGqkqPPSxQ3P25J66ft5TwpzV14k2de",
"Flags" : 0,
"OwnerNode" : "0000000000000000",
"PreviousTxnID" : "3E8964D5A86B3CD6B9ECB33310D4E073D64C865A5B866200AD2B7E29F8326702",
"PreviousTxnLgrSeq" : 7,
"index" : "4A255038CC3ADCC1A9C91509279B59908251728D0DAADB248FFE297D0F7E068C"
}
```
## {{currentpage.name}} Fields
A `DepositPreauth` object has the following fields:
| Field | JSON Type | [Internal Type][] | Description |
|:--------------------|:-----------------|:------------------|:----------------|
| `LedgerEntryType` | String | UInt16 | The value `0x0070`, mapped to the string `DepositPreauth`, indicates that this is a DepositPreauth object. |
| `Account` | String | Account | The account that granted the preauthorization. (The destination of the preauthorized payments.) |
| `Authorize` | String | Account | The account that received the preauthorization. (The sender of the preauthorized payments.) |
| `Flags` | Number | UInt32 | A bit-map of boolean flags. No flags are defined for DepositPreauth objects, so this value is always `0`. |
| `OwnerNode` | String | UInt64 | A hint indicating which page of the sender's owner directory links to this object, in case the directory consists of multiple pages. **Note:** The object does not contain a direct link to the owner directory containing it, since that value can be derived from the `Account`. |
| `PreviousTxnID` | String | Hash256 | The identifying hash of the transaction that most recently modified this object. |
| `PreviousTxnLgrSeq` | Number | UInt32 | The [index of the ledger][Ledger Index] that contains the transaction that most recently modified this object. |
## DepositPreauth ID Format
The ID of a `DepositPreauth` object is the [SHA-512Half][] of the following values, concatenated in order:
* The DepositPreauth space key (`0x0070`)
* The AccountID of the owner of this object (the sender of the [DepositPreauth transaction][] that created this object; in other words, the one that granted the preauthorization)
* The AccountID of the preauthorized account (the `Authorized` field of the [DepositPreauth transaction][] that created this object; in other words, the one that received the preauthorization)
<!--{# common link defs #}-->
{% include '_snippets/rippled-api-links.md' %}
{% include '_snippets/tx-type-links.md' %}
{% include '_snippets/rippled_versions.md' %}

4
content/references/rippled-api/ledger-data-formats/ledger-object-types/ledgerhashes.md
View File

@@ -1,5 +1,5 @@
# LedgerHashes
[[Source]<br>](https://github.com/ripple/rippled/blob/master/src/ripple/protocol/impl/LedgerFormats.cpp#L104-L107 "Source")
[[Source]<br>](https://github.com/ripple/rippled/blob/master/src/ripple/protocol/impl/LedgerFormats.cpp#L104-L108 "Source")
(Not to be confused with the ["ledger hash" string data type][Hash], which uniquely identifies a ledger version. This section describes the `LedgerHashes` ledger object type.)
@@ -57,7 +57,7 @@ The "previous history" `LedgerHashes` entries collectively contain the hash of e
The "previous history" `LedgerHashes` objects act as a [skip list](https://en.wikipedia.org/wiki/Skip_list) so you can get the hash of any historical flag ledger from its index. From there, you can use that flag ledger's "recent history" object to get the hash of any other ledger.
## LedgerHashes ID Formats
[[Source]<br>](https://github.com/ripple/rippled/blob/develop/src/ripple/protocol/impl/Indexes.cpp#L28-L43)
[[Source]<br>](https://github.com/ripple/rippled/blob/master/src/ripple/protocol/impl/Indexes.cpp#L26-L42)
There are two formats for `LedgerHashes` object IDs, depending on whether the object is a "recent history" sub-type or a "previous history" sub-type.

2
content/references/rippled-api/ledger-data-formats/ledger-object-types/paychannel.md
View File

@@ -1,5 +1,5 @@
# PayChannel
[[Source]<br>](https://github.com/ripple/rippled/blob/develop/src/ripple/protocol/impl/LedgerFormats.cpp#L134 "Source")
[[Source]<br>](https://github.com/ripple/rippled/blob/master/src/ripple/protocol/impl/LedgerFormats.cpp#L141-L155 "Source")
_(Requires the [PayChan Amendment](known-amendments.html#paychan).)_

3
content/references/rippled-api/public-rippled-methods/account-methods/account_objects.md
View File

@@ -13,6 +13,7 @@ The types of objects that may appear in the `account_objects` response for an ac
- [Escrow objects](escrow.html) for held payments that have not yet been executed or canceled.
- [PayChannel objects](paychannel.html) for open payment channels.
- [Check objects](check.html) for pending checks.
- [DepositPreauth objects](depositpreauth-object.html) for deposit preauthorizations. [New in: rippled 1.1.0][]
## Request Format
@@ -64,7 +65,7 @@ The request includes the following parameters:
| `Field` | Type | Description |
|:---------------|:-------------------------------------------|:---------------|
| `account` | String | A unique identifier for the account, most commonly the account's address. |
| `type` | String | _(Optional)_ If included, filter results to include only this type of ledger object. The valid types are: `check`, `escrow`, `offer`, `payment_channel`, `signer_list`, and `state` (trust line). <!-- Author's note: Omitted types from this list that can't be owned by an account, and ticket until Tickets are enabled: https://github.com/ripple/rippled/blob/1dbc5a57e6b0e90a9da0d6e56f2f5a99e6ac1d8c/src/ripple/rpc/impl/RPCHelpers.cpp#L676-L686 --> |
| `type` | String | _(Optional)_ If included, filter results to include only this type of ledger object. The valid types are: `check`, `deposit_preauth`, `escrow`, `offer`, `payment_channel`, `signer_list`, and `state` (trust line). <!-- Author's note: Omitted types from this list that can't be owned by an account, and ticket until Tickets are enabled: https://github.com/ripple/rippled/blob/1dbc5a57e6b0e90a9da0d6e56f2f5a99e6ac1d8c/src/ripple/rpc/impl/RPCHelpers.cpp#L676-L686 --> |
| `ledger_hash` | String | _(Optional)_ A 20-byte hex string for the ledger version to use. (See [Specifying Ledgers][]) |
| `ledger_index` | String or Unsigned Integer | _(Optional)_ The sequence number of the ledger to use, or a shortcut string to choose a ledger automatically. (See [Specifying Ledgers][]) |
| `limit` | Unsigned Integer | _(Optional)_ The maximum number of objects to include in the results. Must be within the inclusive range 10 to 400 on non-admin connections. Defaults to 200. |

22
content/references/rippled-api/public-rippled-methods/ledger-methods/ledger_entry.md
View File

@@ -51,7 +51,8 @@ This method can retrieve several different types of data. You can select which t
5. `ripple_state` - Retrieve a [RippleState object](ripplestate.html), which tracks a (non-XRP) currency balance between two accounts.
6. `check` - Retrieve a [Check object](check.html), which is a potential payment that can be cashed by its recipient. [New in: rippled 1.0.0][]
7. `escrow` - Retrieve an [Escrow object](escrow-object.html), which holds XRP until a specific time or condition is met. [New in: rippled 1.0.0][]
8. `payment_channel` - Retireve a [PayChannel object](paychannel.html), which holds XRP for asynchronous payments. [New in: rippled 1.0.0][]
8. `payment_channel` - Retrieve a [PayChannel object](paychannel.html), which holds XRP for asynchronous payments. [New in: rippled 1.0.0][]
9. `deposit_preauth` - Retrieve a [DepositPreauth object](depositpreauth-object.html), which tracks preauthorization for payments to accounts requiring [Deposit Authorization](depositauth.html). [New in: rippled 1.1.0][]
If you specify more than one of the above items, the server retrieves only one of them; it is undefined which it chooses.
@@ -62,20 +63,23 @@ The full list of parameters recognized by this method is as follows:
| `index` | String | _(Optional)_ Specify the [object ID](ledger-object-ids.html) of a single object to retrieve from the ledger. |
| `account_root` | String - [Address][] | _(Optional)_ Specify an [AccountRoot object](accountroot.html) to retrieve. |
| `check` | String | _(Optional)_ Specify the [object ID](ledger-object-ids.html) of a [Check object](check.html) to retrieve. |
| `deposit_preauth` | Object or String | _(Optional)_ Specify a [DepositPreauth object](depositpreauth-object.html) to retrieve. If a string, must be the [object ID](ledger-object-ids.html) of the DepositPreauth object, as hexadecimal. If an object, requires `owner` and `authorized` sub-fields. |
| `deposit_preauth.owner` | String - [Address][] | _(Required if `deposit_preauth` is specified as an object)_ The account that provided the preauthorization. |
| `deposit_preauth.authorized` | String - [Address][] | _(Required if `deposit_preauth` is specified as an object)_ The account that received the preauthorization. |
| `directory` | Object or String | _(Optional)_ Specify a [DirectoryNode](directorynode.html) to retrieve. If a string, must be the [object ID](ledger-object-ids.html) of the directory, as hexadecimal. If an object, requires either `dir_root` or `owner` as a sub-field, plus optionally a `sub_index` sub-field. |
| `directory.sub_index` | Unsigned Integer | _(Optional)_ If provided, jumps to a later "page" of the [DirectoryNode](directorynode.html). |
| `directory.dir_root` | String | (Required if `directory` is specified as an object and `directory.owner` is not provided) Unique index identifying the directory to retrieve, as a hex string. |
| `directory.owner` | String | (Required if `directory` is specified as an object and `directory.dir_root` is not provided) Unique address of the account associated with this directory |
| `directory.dir_root` | String | _(Required if `directory` is specified as an object and `directory.owner` is not provided)_ Unique index identifying the directory to retrieve, as a hex string. |
| `directory.owner` | String | _(Required if `directory` is specified as an object and `directory.dir_root` is not provided)_ Unique address of the account associated with this directory. |
| `escrow` | Object or String | _(Optional)_ Specify an [Escrow object](escrow-object.html) to retrieve. If a string, must be the [object ID](ledger-object-ids.html) of the Escrow, as hexadecimal. If an object, requires `owner` and `seq` sub-fields. |
| `escrow.owner` | String - [Address][] | (Required if `escrow` is specified as an object) The owner (sender) of the Escrow object. |
| `escrow.seq` | Unsigned Integer | (Required if `escrow` is specified as an object) The sequence number of the transaction that created the Escrow object. |
| `escrow.owner` | String - [Address][] | _(Required if `escrow` is specified as an object)_ The owner (sender) of the Escrow object. |
| `escrow.seq` | Unsigned Integer | _(Required if `escrow` is specified as an object)_ The sequence number of the transaction that created the Escrow object. |
| `offer` | Object or String | _(Optional)_ Specify an [Offer object](offer.html) to retrieve. If a string, interpret as the [unique index](ledgers.html#tree-format) to the Offer. If an object, requires the sub-fields `account` and `seq` to uniquely identify the offer. |
| `offer.account` | String - [Address][] | (Required if `offer` specified) The account that placed the offer. |
| `offer.seq` | Unsigned Integer | (Required if `offer` specified) The sequence number of the transaction that created the Offer object. |
| `offer.account` | String - [Address][] | _(Required if `offer` is specified)_ The account that placed the offer. |
| `offer.seq` | Unsigned Integer | _(Required if `offer` is specified)_ The sequence number of the transaction that created the Offer object. |
| `payment_channel` | String | _(Optional)_ Specify the [object ID](ledger-object-ids.html) of a [PayChannel object](paychannel.html) to retrieve. |
| `ripple_state` | Object | _(Optional)_ Object specifying the RippleState (trust line) object to retrieve. The `accounts` and `currency` sub-fields are required to uniquely specify the RippleState entry to retrieve. |
| `ripple_state.accounts` | Array | (Required if `ripple_state` specified) 2-length array of account [Address][]es, defining the two accounts linked by this [RippleState object](ripplestate.html) |
| `ripple_state.currency` | String | (Required if `ripple_state` specified) [Currency Code][] of the [RippleState object](ripplestate.html) to retrieve. |
| `ripple_state.accounts` | Array | _(Required if `ripple_state` is specified)_ 2-length array of account [Address][]es, defining the two accounts linked by this [RippleState object](ripplestate.html). |
| `ripple_state.currency` | String | _(Required if `ripple_state` is specified)_ [Currency Code][] of the [RippleState object](ripplestate.html) to retrieve. |
| `binary` | Boolean | _(Optional)_ If true, return the requested ledger object's contents as a hex string. Otherwise, return data in JSON format. The default is `true` if searching by `index` and `false` otherwise. |
| `ledger_hash` | String | _(Optional)_ A 20-byte hex string for the ledger version to use. (See [Specifying Ledgers][]) |
| `ledger_index` | String or Unsigned Integer | _(Optional)_ The sequence number of the ledger to use, or a shortcut string to choose a ledger automatically. (See [Specifying Ledgers][]) |

2
content/references/rippled-api/public-rippled-methods/path-and-order-book-methods/book_offers.md
View File

@@ -1,5 +1,5 @@
# book_offers
[[Source]<br>](https://github.com/ripple/rippled/blob/develop/src/ripple/rpc/handlers/BookOffers.cpp "Source")
[[Source]<br>](https://github.com/ripple/rippled/blob/master/src/ripple/rpc/handlers/BookOffers.cpp "Source")
The `book_offers` method retrieves a list of offers, also known as the [order book](http://www.investopedia.com/terms/o/order-book.asp), between two currencies. If the results are very large, a partial result is returned with a marker so that later requests can resume from where the previous one left off.

143
content/references/rippled-api/public-rippled-methods/path-and-order-book-methods/deposit_authorized.md Normal file
View File

@@ -0,0 +1,143 @@
# deposit_authorized
[[Source]<br>](https://github.com/ripple/rippled/blob/817d2339b8632cb2f97d3edd6f7af33aa7631744/src/ripple/rpc/handlers/DepositAuthorized.cpp "Source")
The `deposit_authorized` command indicates whether one account is authorized to send payments directly to another. See [Deposit Authorization](depositauth.html) for information on how to require authorization to deliver money to your account.
## Request Format
An example of the request format:
<!-- MULTICODE_BLOCK_START -->
*WebSocket*
```json
{
"id": 1,
"command": "deposit_authorized",
"source_account": "rEhxGqkqPPSxQ3P25J66ft5TwpzV14k2de",
"destination_account": "rsUiUMpnrgxQp24dJYZDhmV4bE3aBtQyt8",
"ledger_index": "validated"
}
```
*JSON-RPC*
```json
{
"method": "deposit_authorized",
"params": [
{
"source_account": "rEhxGqkqPPSxQ3P25J66ft5TwpzV14k2de",
"destination_account": "rsUiUMpnrgxQp24dJYZDhmV4bE3aBtQyt8",
"ledger_index": "validated"
}
]
}
```
*Commandline*
```bash
#Syntax: deposit_authorized <source_account> <destination_account> [<ledger>]
rippled deposit_authorized rEhxGqkqPPSxQ3P25J66ft5TwpzV14k2de rsUiUMpnrgxQp24dJYZDhmV4bE3aBtQyt8 validated
```
<!-- MULTICODE_BLOCK_END -->
The request includes the following parameters:
| `Field` | Type | Description |
|:----------------------|:---------------------------|:------------------------|
| `source_account` | String - [Address][] | The sender of a possible payment. |
| `destination_account` | String - [Address][] | The recipient of a possible payment. |
| `ledger_hash` | String | _(Optional)_ A 20-byte hex string for the ledger version to use. (See [Specifying Ledgers][]) |
| `ledger_index` | String or Unsigned Integer | _(Optional)_ The sequence number of the ledger to use, or a shortcut string to choose a ledger automatically. (See [Specifying Ledgers][]) |
## Response Format
An example of a successful response:
<!-- MULTICODE_BLOCK_START -->
*WebSocket*
```json
{
"id": 1,
"result": {
"deposit_authorized": true,
"destination_account": "rsUiUMpnrgxQp24dJYZDhmV4bE3aBtQyt8",
"ledger_hash": "BD03A10653ED9D77DCA859B7A735BF0580088A8F287FA2C5403E0A19C58EF322",
"ledger_index": 8,
"source_account": "rEhxGqkqPPSxQ3P25J66ft5TwpzV14k2de",
"validated": true
},
"status": "success",
"type": "response"
}
```
*JSON-RPC*
```json
{
"result": {
"deposit_authorized": true,
"destination_account": "rsUiUMpnrgxQp24dJYZDhmV4bE3aBtQyt8",
"ledger_hash": "BD03A10653ED9D77DCA859B7A735BF0580088A8F287FA2C5403E0A19C58EF322",
"ledger_index": 8,
"source_account": "rEhxGqkqPPSxQ3P25J66ft5TwpzV14k2de",
"status": "success",
"validated": true
}
}
```
*Commandline*
```json
Loading: "/etc/rippled.cfg"
2018-Jul-30 20:07:38.771658157 HTTPClient:NFO Connecting to 127.0.0.1:5005
{
"result" : {
"deposit_authorized" : true,
"destination_account" : "rsUiUMpnrgxQp24dJYZDhmV4bE3aBtQyt8",
"ledger_hash" : "BD03A10653ED9D77DCA859B7A735BF0580088A8F287FA2C5403E0A19C58EF322",
"ledger_index" : 8,
"source_account" : "rEhxGqkqPPSxQ3P25J66ft5TwpzV14k2de",
"status" : "success",
"validated" : true
}
}
```
<!-- MULTICODE_BLOCK_END -->
The response follows the [standard format][], with a successful result containing the following fields:
| `Field` | Type | Description |
|:-----------------------|:---------------------|:-----------------------------|
| `deposit_authorized` | Boolean | Whether the specified source account is authorized to send payments directly to the destination account. If `true`, either the destination account does not require [Deposit Authorization](depositauth.html) or the source account is preauthorized. |
| `destination_account` | String - [Address][] | The destination account specified in the request. |
| `ledger_hash` | String | _(May be omitted)_ The identifying hash of the ledger that was used to generate this response. |
| `ledger_index` | Number | _(May be omitted)_ The sequence number of the ledger version that was used to generate this response. |
| `ledger_current_index` | Number | _(May be omitted)_ The sequence number of the current in-progress ledger version that was used to generate this response. |
| `source_account` | String - [Address][] | The source account specified in the request. |
| `validated` | Boolean | _(May be omitted)_ If `true`, the information comes from a validated ledger version. |
**Note:** A `deposit_authorized` status of `true` does not guarantee that a payment can be sent from the specified source to the specified destination. For example, the destination account may not have a [trust line](trust-lines-and-issuing.html) for the specified currency, or there may not be sufficient liquidity to deliver a payment.
## Possible Errors
* Any of the [universal error types][].
* `invalidParams` - One or more fields are specified incorrectly, or one or more required fields are missing.
* `actMalformed` - An [Address][] specified in the `source_account` or `destination_account` field of the request was not properly formatted. (It may contain a typo or be the wrong length, causing a failed checksum.)
* `dstActNotFound` - The `destination_account` field of the request does not correspond to an account in the ledger.
* `lgrNotFound` - The ledger specified by the `ledger_hash` or `ledger_index` does not exist, or it does exist but the server does not have it.
* `srcActNotFound` - The `source_account` field of the request does not correspond to an account in the ledger.
{% include '_snippets/rippled_versions.md' %}
{% include '_snippets/rippled-api-links.md' %}

6
content/references/rippled-api/public-rippled-methods/path-and-order-book-methods/path_find.md
View File

@@ -12,7 +12,7 @@ There are three different modes, or sub-commands, of the path_find command. Spec
Although the `rippled` server tries to find the cheapest path or combination of paths for making a payment, it is not guaranteed that the paths returned by this method are, in fact, the best paths. Due to server load, pathfinding may not find the best results. Additionally, you should be careful with the pathfinding results from untrusted servers. A server could be modified to return less-than-optimal paths to earn money for its operators. If you do not have your own server that you can trust with pathfinding, you should compare the results of pathfinding from multiple servers run by different parties, to minimize the risk of a single server returning poor results. (**Note:** A server returning less-than-optimal results is not necessarily proof of malicious behavior; it could also be a symptom of heavy server load.)
## path_find create
[[Source]<br>](https://github.com/ripple/rippled/blob/master/src/ripple/rpc/handlers/PathFind.cpp#L38 "Source")
[[Source]<br>](https://github.com/ripple/rippled/blob/master/src/ripple/rpc/handlers/PathFind.cpp#L50-L56 "Source")
The `create` subcommand of `path_find` creates an ongoing request to find possible paths along which a payment transaction could be made from one specified account such that another account receives a desired amount of some currency. The initial response contains a suggested path between the two addresses that would result in the desired amount being received. After that, the server sends additional messages, with `"type": "path_find"`, with updates to the potential paths. The frequency of updates is left to the discretion of the server, but it usually means once every few seconds when there is a new ledger version.
@@ -489,7 +489,7 @@ Here is an example of an asychronous follow-up from a path_find create request:
<!-- MULTICODE_BLOCK_END -->
## path_find close
[[Source]<br>](https://github.com/ripple/rippled/blob/master/src/ripple/rpc/handlers/PathFind.cpp#L46 "Source")
[[Source]<br>](https://github.com/ripple/rippled/blob/master/src/ripple/rpc/handlers/PathFind.cpp#L58-L67 "Source")
The `close` subcommand of `path_find` instructs the server to stop sending information about the current open pathfinding request.
@@ -534,7 +534,7 @@ If there was no outstanding pathfinding request, an error is returned instead.
* `noPathRequest` - You tried to close a pathfinding request when there is not an open one.
## path_find status
[[Source]<br>](https://github.com/ripple/rippled/blob/master/src/ripple/rpc/handlers/PathFind.cpp#L57 "Source")
[[Source]<br>](https://github.com/ripple/rippled/blob/master/src/ripple/rpc/handlers/PathFind.cpp#L69-L77 "Source")
The `status` subcommand of `path_find` requests an immediate update about the client's currently-open pathfinding request.

1
content/references/rippled-api/public-rippled-methods/public-rippled-methods.md
View File

@@ -47,6 +47,7 @@ Transactions are the only thing that can modify the shared state of the XRP Ledg
Paths define a way for payments to flow through intermediary steps on their way from sender to receiver. Paths enable cross-currency payments by connecting sender and receiver through order books. Use these methods to work with paths and other books.
* **[`book_offers`](book_offers.html)** - Get info about offers to exchange two currencies.
* **[`deposit_authorized`](deposit_authorized.html)** - Look up whether one account is authorized to send payments directly to another.
* **[`path_find`](path_find.html)** - Find a path for a payment between two accounts and receive updates.
* **[`ripple_path_find`](ripple_path_find.html)** - Find a path for payment between two accounts, once.

3
content/references/rippled-api/public-rippled-methods/transaction-methods/sign.md
View File

@@ -3,6 +3,9 @@
The `sign` method takes a [transaction in JSON format](transaction-formats.html) and a secret key, and returns a signed binary representation of the transaction. The result is always different, even when you provide the same transaction JSON and secret key. To contribute one signature to a multi-signed transaction, use the [sign_for method][] instead.
{% include '_snippets/public-signing-note.md' %}
<!--_ -->
**Caution:** Unless you run the `rippled` server yourself, you should do [local signing with RippleAPI](rippleapi-reference.html#sign) instead of using this command. An untrustworthy server could change the transaction before signing it, or use your secret key to sign additional arbitrary transactions as if they came from you.
## Request Format

18
content/references/rippled-api/public-rippled-methods/transaction-methods/sign_for.md
View File

@@ -3,6 +3,9 @@
The `sign_for` command provides one signature for a [multi-signed transaction](multi-signing.html).
{% include '_snippets/public-signing-note.md' %}
<!--_ -->
This command requires the [MultiSign amendment](known-amendments.html#multisign) to be enabled. [New in: rippled 0.31.0][]
## Request Format
@@ -89,13 +92,16 @@ The request includes the following parameters:
|:-------------|:---------------------|:---------------------------------------|
| `account` | String - [Address][] | The address which is providing the signature. |
| `tx_json` | Object | The [Transaction](transaction-formats.html) to sign. Unlike using the [sign method][], all fields of the transaction must be provided, including `Fee` and `Sequence`. The transaction must include the field `SigningPubKey` with an empty string as the value. The object may optionally contain a `Signers` array with previously-collected signatures. |
| `secret` | String | _(Optional)_ The secret key to sign with. (Cannot be used with `key_type`.) |
| `passphrase` | String | _(Optional)_ A passphrase to use as the secret key to sign with. |
| `seed` | String | _(Optional)_ A [base58][]-encoded secret key to sign with. |
| `seed_hex` | String | _(Optional)_ A hexadecimal secret key to sign with. |
| `key_type` | String | _(Optional)_ The type of key to use for signing. This can be `secp256k1` or `ed25519`. (Ed25519 support is experimental.) |
| `secret` | String | _(Optional)_ Secret key of the account supplying the transaction, used to sign it. Do not send your secret to untrusted servers or through unsecured network connections. Cannot be used with `key_type`, `seed`, `seed_hex`, or `passphrase`. |
| `seed` | String | _(Optional)_ Secret key of the account supplying the transaction, used to sign it. Must be in [base58][] format. If provided, you must also specify the `key_type`. Cannot be used with `secret`, `seed_hex`, or `passphrase`. |
| `seed_hex` | String | _(Optional)_ Secret key of the account supplying the transaction, used to sign it. Must be in hexadecimal format. If provided, you must also specify the `key_type`. Cannot be used with `secret`, `seed`, or `passphrase`. |
| `passphrase` | String | _(Optional)_ Secret key of the account supplying the transaction, used to sign it, as a string passphrase. If provided, you must also specify the `key_type`. Cannot be used with `secret`, `seed`, or `seed_hex`. |
| `key_type` | String | _(Optional)_ Type of cryptographic key provided in this request. Valid types are `secp256k1` or `ed25519`. Defaults to `secp256k1`. Cannot be used with `secret`. **Caution:** Ed25519 support is experimental. |
You must provide exactly 1 field with the secret key. You can use any of the following fields: `secret`, `passphrase`, `seed`, or `seed_hex`.
You must provide **exactly 1 field** with the secret key, which can be either of the following:
* Provide a `secret` value and omit the `key_type` field. This value can be formatted as [base58][] seed, RFC-1751, hexadecimal, or as a string passphrase. (secp256k1 keys only)
* Provide a `key_type` value and exactly one of `seed`, `seed_hex`, or `passphrase`. Omit the `secret` field. (Not supported by the commandline syntax.)
## Response Format

2
content/references/rippled-api/public-rippled-methods/transaction-methods/submit.md
View File

@@ -62,6 +62,8 @@ submit 1200002280000000240000000361D4838D7EA4C6800000000000000000000000000055534
This mode signs a transaction and immediately submits it. This mode is intended to be used for testing. You cannot use this mode for [multi-signed transactions](multi-signing.html).
_By default, sign-and-submit mode is [admin-only](admin-rippled-methods.html)._ It can be used as a public method if the server has [enabled public signing](enable-public-signing.html).
You can provide the secret key used to sign the transaction in the following ways:
* Provide a `secret` value and omit the `key_type` field. This value can be formatted as [base58][] seed, RFC-1751, hexadecimal, or as a string passphrase. (secp256k1 keys only)

1
content/references/rippled-api/public-rippled-methods/transaction-methods/transaction_entry.md
View File

@@ -216,7 +216,6 @@ There are a couple possible reasons the server may fail to find the transaction:
* `lgrNotFound` - The ledger specified by the `ledger_hash` or `ledger_index` does not exist, or it does exist but the server does not have it.
* `transactionNotFound` - The transaction specified in the request could not be found in the specified ledger. (It might be in a different ledger version, or it might not be available at all.)
<!-- I think ledgerNotFound ( https://github.com/ripple/rippled/blob/develop/src/ripple/rpc/handlers/TransactionEntry.cpp#L62 ) should not occur because lookupLedger would have errored out first. -->
{% include '_snippets/rippled_versions.md' %}

1
content/references/rippled-api/transaction-formats/transaction-results/tem-codes.md
View File

@@ -25,6 +25,7 @@ These codes indicate that the transaction was malformed, and cannot succeed acco
| `temBAD_SIGNATURE` | The signature to authorize this transaction is either missing, or formed in a way that is not a properly-formed signature. (See [tecNO_PERMISSION](tec-codes.html) for the case where the signature is properly formed, but not authorized for this account.) |
| `temBAD_SRC_ACCOUNT` | The `Account` on whose behalf this transaction is being sent (the "source account") is not a properly-formed [account](accounts.html) address. |
| `temBAD_TRANSFER_RATE` | The [`TransferRate` field of an AccountSet transaction](accountset.html#transferrate) is not properly formatted or out of the acceptable range. |
| `temCANNOT_PREAUTH_SELF` | The sender of the [DepositPreauth transaction][] was also specified as the account to preauthorize. You cannot preauthorize yourself. |
| `temDST_IS_SRC` | The transaction improperly specified a destination address as the `Account` sending the transaction. This includes trust lines (where the destination address is the `issuer` field of `LimitAmount`) and payment channels (where the destination address is the `Destination` field). |
| `temDST_NEEDED` | The transaction improperly omitted a destination. This could be the `Destination` field of a [Payment transaction][], or the `issuer` sub-field of the `LimitAmount` field fo a `TrustSet` transaction. |
| `temINVALID` | The transaction is otherwise invalid. For example, the transaction ID may not be the right format, the signature may not be formed properly, or something else went wrong in understanding the transaction. |

2
content/references/rippled-api/transaction-formats/transaction-results/transaction-results.md
View File

@@ -1,6 +1,6 @@
# Transaction Results
[[Source]<br>](https://github.com/ripple/rippled/blob/develop/src/ripple/protocol/TER.h "Source")
[[Source]<br>](https://github.com/ripple/rippled/blob/master/src/ripple/protocol/TER.h "Source")
The `rippled` server summarizes transaction results with result codes, which appear in fields such as `engine_result` and `meta.TransactionResult`. These codes are grouped into several categories of with different prefixes:

2
content/references/rippled-api/transaction-formats/transaction-types/checkcancel.md
View File

@@ -1,5 +1,5 @@
# CheckCancel
[[Source]<br>](https://github.com/ripple/rippled/blob/develop/src/ripple/app/tx/impl/CancelCheck.cpp "Source") <!--{# TODO: change from develop to master when 0.90.0 is released #}-->
[[Source]<br>](https://github.com/ripple/rippled/blob/master/src/ripple/app/tx/impl/CancelCheck.cpp "Source") <!--{# TODO: change from develop to master when 0.90.0 is released #}-->
_Requires the [Checks Amendment](known-amendments.html#checks)._

2
content/references/rippled-api/transaction-formats/transaction-types/checkcash.md
View File

@@ -1,5 +1,5 @@
# CheckCash
[[Source]<br>](https://github.com/ripple/rippled/blob/develop/src/ripple/app/tx/impl/CashCheck.cpp "Source") <!--{# TODO: change from develop to master when 0.90.0 is released #}-->
[[Source]<br>](https://github.com/ripple/rippled/blob/master/src/ripple/app/tx/impl/CashCheck.cpp "Source") <!--{# TODO: change from develop to master when 0.90.0 is released #}-->
_Requires the [Checks Amendment](known-amendments.html#checks)._

2
content/references/rippled-api/transaction-formats/transaction-types/checkcreate.md
View File

@@ -1,5 +1,5 @@
# CheckCreate
[[Source]<br>](https://github.com/ripple/rippled/blob/develop/src/ripple/app/tx/impl/CreateCheck.cpp "Source") <!--{# TODO: change from develop to master when 0.90.0 is released #}-->
[[Source]<br>](https://github.com/ripple/rippled/blob/master/src/ripple/app/tx/impl/CreateCheck.cpp "Source") <!--{# TODO: change from develop to master when 0.90.0 is released #}-->
_Requires the [Checks Amendment](known-amendments.html#checks)._

46
content/references/rippled-api/transaction-formats/transaction-types/depositpreauth.md Normal file
View File

@@ -0,0 +1,46 @@
# DepositPreauth
[[Source]<br>](https://github.com/ripple/rippled/blob/master/src/ripple/app/tx/impl/DepositPreauth.cpp "Source") <!--{# TODO: change from develop to master when 1.1.0 is released #}-->
_Requires the [DepositPreauth amendment](known-amendments.html#depositpreauth)._
A DepositPreauth transaction gives another account pre-approval to deliver payments to the sender of this transaction. This is only useful if the sender of this transaction is using (or plans to use) [Deposit Authorization](depositauth.html).
**Tip:** You can use this transaction to preauthorize certain counterparties before you enable Deposit Authorization. This may be useful to ensure a smooth transition from not requiring deposit authorization to requiring it.
## Example {{currentpage.name}} JSON
```json
{
"TransactionType" : "DepositPreauth",
"Account" : "rsUiUMpnrgxQp24dJYZDhmV4bE3aBtQyt8",
"Authorize" : "rEhxGqkqPPSxQ3P25J66ft5TwpzV14k2de",
"Fee" : "10",
"Flags" : 2147483648,
"Sequence" : 2
}
```
{% include '_snippets/tx-fields-intro.md' %}
<!--{# fix md highlighting_ #}-->
| Field | JSON Type | [Internal Type][] | Description |
|:--------------|:----------|:------------------|:-----|
| `Authorize` | String | AccountID | _(Optional)_ The XRP Ledger address of the sender to preauthorize. |
| `Unauthorize` | String | AccountID | _(Optional)_ The XRP Ledger address of a sender whose preauthorization should be revoked. |
You must provide _either_ `Authorize` or `Unauthorize`, but not both.
This transaction has the following limitations:
- An account cannot preauthorize (or unauthorize) its own address. Attempting to do so fails with the result [`temCANNOT_PREAUTH_SELF`](tem-codes.html).
- Attempting to preauthorize an account which is already preauthorized fails with the result [`tecDUPLICATE`](tec-codes.html).
- Attempting to unauthorize an account which is not preauthorized fails with the result [`tecNO_ENTRY`](tec-codes.html).
- Attempting to preauthorize an address that is not funded in the ledger fails with the result [`tecNO_TARGET`](tec-codes.html).
- Adding authorization adds a [DepositPreauth object](depositpreauth-object.html) to the ledger, which counts toward the [owner reserve requirement](reserves.html#owner-reserves). If the sender of the transaction does not have enough XRP to pay for the increased reserve, the transaction fails with the result [`tecINSUFFICIENT_RESERVE`](tec-codes.html). If the sender of the account is already at the maximum number of owned objects, the transaction fails with the result [`tecDIR_FULL`](tec-codes.html).
<!--{# common link defs #}-->
{% include '_snippets/rippled-api-links.md' %}
{% include '_snippets/tx-type-links.md' %}
{% include '_snippets/rippled_versions.md' %}

2
content/references/rippled-api/transaction-formats/transaction-types/escrowcancel.md
View File

@@ -1,6 +1,6 @@
# EscrowCancel
[[Source]<br>](https://github.com/ripple/rippled/blob/develop/src/ripple/app/tx/impl/Escrow.cpp "Source")
[[Source]<br>](https://github.com/ripple/rippled/blob/master/src/ripple/app/tx/impl/Escrow.cpp "Source")
_Requires the [Escrow Amendment](known-amendments.html#escrow)._

2
content/references/rippled-api/transaction-formats/transaction-types/escrowcreate.md
View File

@@ -1,6 +1,6 @@
# EscrowCreate
[[Source]<br>](https://github.com/ripple/rippled/blob/develop/src/ripple/app/tx/impl/Escrow.cpp "Source")
[[Source]<br>](https://github.com/ripple/rippled/blob/master/src/ripple/app/tx/impl/Escrow.cpp "Source")
_Requires the [Escrow Amendment](known-amendments.html#escrow)._

2
content/references/rippled-api/transaction-formats/transaction-types/escrowfinish.md
View File

@@ -1,6 +1,6 @@
# EscrowFinish
[[Source]<br>](https://github.com/ripple/rippled/blob/develop/src/ripple/app/tx/impl/Escrow.cpp "Source")
[[Source]<br>](https://github.com/ripple/rippled/blob/master/src/ripple/app/tx/impl/Escrow.cpp "Source")
_Requires the [Escrow Amendment](known-amendments.html#escrow)._

2
content/references/rippled-api/transaction-formats/transaction-types/paymentchannelclaim.md
View File

@@ -1,5 +1,5 @@
# PaymentChannelClaim
[[Source]<br>](https://github.com/ripple/rippled/blob/develop/src/ripple/app/tx/impl/PayChan.cpp "Source")
[[Source]<br>](https://github.com/ripple/rippled/blob/master/src/ripple/app/tx/impl/PayChan.cpp "Source")
_Requires the [PayChan Amendment](known-amendments.html#paychan)._

2
content/references/rippled-api/transaction-formats/transaction-types/paymentchannelcreate.md
View File

@@ -1,5 +1,5 @@
# PaymentChannelCreate
[[Source]<br>](https://github.com/ripple/rippled/blob/develop/src/ripple/app/tx/impl/PayChan.cpp "Source")
[[Source]<br>](https://github.com/ripple/rippled/blob/master/src/ripple/app/tx/impl/PayChan.cpp "Source")
_Requires the [PayChan Amendment](known-amendments.html#paychan)._

2
content/references/rippled-api/transaction-formats/transaction-types/paymentchannelfund.md
View File

@@ -1,5 +1,5 @@
# PaymentChannelFund
[[Source]<br>](https://github.com/ripple/rippled/blob/develop/src/ripple/app/tx/impl/PayChan.cpp "Source")
[[Source]<br>](https://github.com/ripple/rippled/blob/master/src/ripple/app/tx/impl/PayChan.cpp "Source")
_Requires the [PayChan Amendment](known-amendments.html#paychan)._

86
content/tutorials/manage-the-rippled-server/build-run-rippled-ubuntu.md
View File

@@ -4,7 +4,7 @@
For an overview of `rippled`, see [Operating rippled Servers](install-rippled.html).
Use these instructions to build a `rippled` executable from source version 1.0.0 or higher on Ubuntu Linux 16.04 or higher. These instructions were tested on Ubuntu 16.04 LTS.
Use these instructions to build a `rippled` executable from source version 1.1.0 or higher on Ubuntu Linux 16.04 or higher. These instructions were tested on Ubuntu 16.04 LTS.
For information about building `rippled` for other platforms, see [Builds](https://github.com/ripple/rippled/tree/develop/Builds) in the `rippled` GitHub repository.
@@ -32,99 +32,85 @@ These instructions use Ubuntu's APT (Advanced Packaging Tool) to install the sof
sudo apt-get -y upgrade
3. Install Git.
3. Install dependencies.
sudo apt-get -y install git
sudo apt-get -y install git cmake pkg-config protobuf-compiler libprotobuf-dev libssl-dev wget
4. Install CMake.
4. Compile Boost.
sudo apt-get -y install cmake
Version 1.1.0 of `rippled` requires Boost version 1.67.0 exactly. Because Boost version 1.67.0 isn't available in the Ubuntu 16.04 software repositories, you must compile it yourself.
5. Install `pkg-config`.
If you have previously built Boost 1.67.0 for `rippled` and configured the `BOOST_ROOT` environment variable, you can skip these steps.
sudo apt-get -y install pkg-config
1. Download Boost 1.67.0.
6. Install Protocol Buffers.
wget https://dl.bintray.com/boostorg/release/1.67.0/source/boost_1_67_0.tar.gz
sudo apt-get -y install protobuf-compiler
sudo apt-get -y install libprotobuf-dev
2. Extract `boost_1_67_0.tar.gz`.
7. Install Secure Socket Layer (SSL) toolkit development files.
tar xvzf boost_1_67_0.tar.gz
sudo apt-get -y install libssl-dev
3. Change to the new `boost_1_67_0` directory.
8. Install `wget` to be able to download Boost in the next step.
cd boost_1_67_0
sudo apt-get -y install wget
9. Compile Boost.
The recommended Boost version is 1.64.0. Because Boost version 1.64.0 isn't available in the Ubuntu 16.04 repos, you must compile it yourself.
If you have previously built Boost 1.64.0 for `rippled` and configured the `BOOST_ROOT` environment variable, you can skip these steps.
1. Download Boost 1.64.0.
wget https://dl.bintray.com/boostorg/release/1.64.0/source/boost_1_64_0.tar.gz
2. Untar `boost_1_64_0.tar.gz`.
tar xvzf boost_1_64_0.tar.gz
3. Access the new `boost_1_64_0` directory:
cd boost_1_64_0
4. To prepare the Boost.Build system for use, run:
4. Prepare the Boost.Build system for use.
./bootstrap.sh
5. To invoke Boost.Build to build the separately-compiled Boost libraries, run the following command. Replace `<number of parallel jobs>` with the number of jobs to run in parallel. Choose this value based on the number of CPU cores you want to use for building. This may take about 10 minutes, depending on your hardware specs.
5. Build the separately-compiled Boost libraries. This may take about 10 minutes, depending on your hardware specs.
./b2 -j <number of parallel jobs>
./b2 -j 4
6. Set the environment variable `BOOST_ROOT` to point to the new `boost_1_64_0` directory. It's best to put this environment variable in your `.profile`, or equivalent, file for your shell so it's automatically set when you log in. Add the following line to the file:
**Tip:** This example uses 4 processes to build in parallel. The best number of processes to use depends on how many CPU cores your hardware has available. You can use `cat /proc/cpuinfo` to get information about your hardware's processor.
export BOOST_ROOT=/home/ubuntu/boost_1_64_0
6. Set the environment variable `BOOST_ROOT` to point to the new `boost_1_67_0` directory. It's best to put this environment variable in your `.profile`, or equivalent, file for your shell so it's automatically set when you log in. Add the following line to the file:
export BOOST_ROOT=/home/ubuntu/boost_1_67_0
7. Source your updated `.profile` file. For example:
source ~/.profile
10. From a working directory, get the `rippled` source code. The `master` branch has the latest released version.
5. From a working directory, get the `rippled` source code. The `master` branch has the latest released version.
cd ~
git clone https://github.com/ripple/rippled.git
cd rippled
git checkout master
11. Check the commit log to be sure you're compiling the version you intend to. The most recent commit should be signed by a well-known Ripple developer and should set the version number to the latest released version. For example:
6. Check the commit log to be sure you're compiling the version you intend to. The most recent commit should be signed by a well-known Ripple developer and should set the version number to the latest released version. For example:
$ git log
$ git log -1
commit f31ca2860fb5f045b618aa05d1e76c7e2e9494ec (HEAD, tag: 1.0.0, origin/release, origin/master, master)
Author: Nikolaos D. Bougalis <nikb@bougalis.net>
Date: Fri May 11 10:29:41 2018 -0700
commit 3e22a1e9e8f2de450eded6ca4c2db6411e329b2a
Author: Nik Bougalis <nikb@bougalis.net>
Date: Wed Sep 5 18:34:43 2018 -0700
Set version to 1.0.0
Set version to 1.1.0
12. If you previously built, or (more importantly) tried and failed to build `rippled`, you should delete the `my_build/` directory (or whatever you named it) to start clean before moving on to the next step. Otherwise, you may get unexpected behavior, like a `rippled` executable that crashes due to a segmentation fault (segfault).
7. If you previously built, or (more importantly) tried and failed to build `rippled`, you should delete the `my_build/` directory (or whatever you named it) to start clean before moving on to the next step. Otherwise, you may get unexpected behavior, like a `rippled` executable that crashes due to a segmentation fault (segfault).
If this is your first time building `rippled` 1.0.0 or higher, you won't have a `my_build/` directory and can move on to the next step.
13. Use CMake to build a `rippled` binary executable from source code. The result will be a `rippled` binary executable in the `my_build` directory.
8. Use CMake to build a `rippled` binary executable from source code. The result will be a `rippled` binary executable in the `my_build` directory.
1. Generate the build system. Builds should be performed in a directory that is separate from the source tree root. In this example, we'll use a `my_build` directory that is a subdirectory of `rippled`.
mkdir my_build
cd my_build
cmake -Dtarget=gcc.debug.unity ..
cmake ..
**Tip:** The default build includes debugging symbols, which can be useful for development but are inefficient in production. To build `rippled` for use on production servers, add the `-DCMAKE_BUILD_TYPE=Release` flag when running the `cmake` command.
2. Build the `rippled` binary executable. Replace `<number of parallel jobs>` with the number of jobs to run in parallel. Choose this value based on the number of CPU cores you want to use for building.
cmake --build . -- -j <number of parallel jobs>
cmake --build . -- -j 4
14. _(Optional)_ Run `rippled` unit tests. If there are no test failures, you can be fairly certain that your `rippled` executable compiled correctly.
**Tip:** This example uses 4 processes to build in parallel. The best number of processes to use depends on how many CPU cores your hardware has available. You can use `cat /proc/cpuinfo` to get information about your hardware's processor.
9. _(Optional)_ Run `rippled` unit tests. If there are no test failures, you can be fairly certain that your `rippled` executable compiled correctly.
./rippled -u

35
content/tutorials/manage-the-rippled-server/enable-public-signing.md Normal file
View File

@@ -0,0 +1,35 @@
# Enable Public Signing
[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-with-the-rippled-api.html), 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.
**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.
vim /etc/opt/ripple/rippled.cfg
The [recommended installation](install-rippled.html) uses the config file `/etc/opt/ripple/rippled.cfg` by default. Other places you can put a config file include `$HOME/.config/ripple/rippled.cfg` (where `$HOME` is the home directory of the user running `rippled`) or
2. Add the following stanza to your config file, and save the changes:
[signing_support]
true
3. Restart your `rippled` server:
systemctl restart rippled
<!--{# common link defs #}-->
{% include '_snippets/rippled-api-links.md' %}
{% include '_snippets/tx-type-links.md' %}
{% include '_snippets/rippled_versions.md' %}

173
content/tutorials/manage-the-rippled-server/fix-sqlite-tx-db-page-size-issue.md Normal file
View File

@@ -0,0 +1,173 @@
# Fix SQLite Transaction Database Page Size Issue
`rippled` servers with full transaction history (or a very large amount of transaction history) and a database that was initially created with a `rippled` version earlier than 0.40.0 (released January 2017) may encounter a problem with their SQLite database page size that stops the server from operating properly. Servers that store only recent transaction history (the default configuration) and servers whose database files were created with `rippled` version 0.40.0 and later are not likely to encounter this problem.
This document describes steps to detect and correct this problem if it occurs.
## Background
`rippled` servers store a copy of their transaction history in a SQLite database. Before version 0.40.0, `rippled` configured this database to have a capacity of roughly 2TB. For most uses, this is plenty. However, full transaction history back to ledger 32570 (the oldest ledger version available in the production XRP Ledger history) is likely to exceed this exceed the SQLite database capacity. `rippled` servers version 0.40.0 and later create their SQLite database files with a larger capacity, so they are unlikely to encounter this problem.
The capacity of the SQLite database is a result of the database's _page size_ parameter, which cannot be easily changed after the database is created. (For more information on SQLite's internals, see [the official SQLite documentation](https://www.sqlite.org/fileformat.html).) The database can reach its capacity even if there is still free space on the disk and filesystem where it is stored. As described in the [Fix](#fix) below, reconfiguring the page size to avoid this problem requires a somewhat time-consuming migration process.
**Tip:** Full history is not necessary to operate a `rippled` server for most use cases. Servers with full transaction history may be useful for long-term analysis and archive purposes or as a precaution against disasters. For a less resource-intense way to contribute to the storage of transaction history, see [History Sharding](history-sharding.html).
## Detection
If your server is vulnerable to this problem, you can detect it two ways:
- You can detect the problem [proactively](#proactive-detection) (before it causes problems) if your `rippled` server is [version 1.1.0][New in: rippled 1.1.0] or later.
- You can identify the problem [reactively](#reactive-detection) (when your server is crashing) on any `rippled` version.
In both cases, detection of the problem requires access to `rippled`'s server logs.
**Tip:** The location of the debug log depends on your `rippled` server's configuration file. The [default configuration](https://github.com/ripple/rippled/blob/master/cfg/rippled-example.cfg#L1139-L1142) writes the server's debug log to the file `/var/log/rippled/debug.log`.
### Proactive Detection
To detect the SQLite page size problem proactively, you must be running **[rippled 1.1.0][New in: rippled 1.1.0] or later**. The `rippled` server writes a message such as the following in its debug log periodically, at least once every 2 minutes. (The exact numeric values from the log entry and the path to your transaction database depend on your environment.)
```text
Transaction DB pathname: /opt/rippled/transaction.db; SQLite page size: 1024
bytes; Free pages: 247483646; Free space: 253423253504 bytes; Note that this
does not take into account available disk space.
```
The value `SQLite page size: 1024 bytes` indicates that your transaction database is configured with a smaller page size and does not have capacity for full transaction history. If the value is already 4096 bytes or higher, then your SQLite database should already have adequate capacity to store full transaction history and you do not need to perform the migration described in this document.
The `rippled` server halts if the `Free space` described in this log message becomes less than 524288000 bytes (500MB). If your free space is approaching that threshold, [fix the problem](#fix) to avoid an unexpected outage.
### Reactive Detection
If your server's SQLite database capacity has already been exceeded, the `rippled` service writes a log message indicating the problem and halts.
#### rippled 1.1.0 and Later
On `rippled` versions 1.1.0 and later, the server shuts down gracefully with a message such as the following in the server's debug log:
```text
Free SQLite space for transaction db is less than 512MB. To fix this, rippled
must be executed with the vacuum <sqlitetmpdir> parameter before restarting.
Note that this activity can take multiple days, depending on database size.
```
#### Earlier than rippled 1.1.0
On `rippled` versions before 1.1.0, the server crashes repeatedly with messages such as the following in the server's debug log:
```text
Terminating thread doJob: AcquisitionDone: unhandled
N4soci18sqlite3_soci_errorE 'sqlite3_statement_backend::loadOne: database or
disk is full while executing "INSERT INTO [...]
```
## Fix
You can fix this issue using `rippled` on supported Linux systems according to the steps described in this document. In the case of a full-history server with system specs approximately matching the [recommended hardware configuration](capacity-planning.html#recommendation-1), the process may take more than two full days.
### Prerequisites
- You must be running **[rippled version 1.1.0][New in: rippled 1.1.0] or later**.
- [Upgrade rippled](update-rippled.html) to the latest stable version before starting this process.
- You can check what version of `rippled` you have installed locally by running the following command:
rippled --version
- You must have enough free space to temporarily store a second copy of the transaction database, in a directory that is writable by the `rippled` user. This free space does not need to be in the same filesystem as the existing transaction database.
The transaction database is stored in the `transaction.db` file in the folder specified by your configuration's `[database_path]` setting. You can check the size of this file to see how much free space you need. For example:
ls -l /var/lib/rippled/db/transaction.db
### Migration Process
To migrate your transaction database to a larger page size, perform the following steps:
1. Check that you meet all the [prerequisites](#prerequisites).
2. Create a folder to store temporary files during the migration process.
mkdir /tmp/rippled_txdb_migration
3. Grant the `rippled` user ownership of the temporary folder so it can write files there. (This is not necessary if your temporary folder is somewhere the `rippled` user already has write access to.)
chown rippled /tmp/rippled_txdb_migration
4. Confirm that your temporary folder has enough free space to store a copy of the transaction database.
For example, compare the `Avail` output from the `df` command to the [size of your `transaction.db` file](#prerequisites).
df -h /tmp/rippled_txdb_migration
Filesystem Size Used Avail Use% Mounted on
/dev/sda2 5.4T 2.6T 2.6T 50% /tmp
5. If `rippled` is still running, stop it:
sudo systemctl stop rippled
6. Open a `screen` session (or other similar tool) so that the process does not stop when you log out:
screen
7. Become the `rippled` user:
sudo su - rippled
8. Run `rippled` executable directly, providing the `--vacuum` command with the path to the temporary directory:
/opt/ripple/bin/rippled -q --vacuum /tmp/rippled_txdb_migration
The `rippled` executable immediately displays the following message:
VACUUM beginning. page_size: 1024
9. Wait for the process to complete. This can take more than two full days.
When the process is complete, the `rippled` executable displays the following message, then exits:
VACUUM finished. page_size: 4096
While you wait, you can detach your `screen` session by pressing **CTRL-A**, then **D**. Later, you can reattach your screen session with a command such as the following:
screen -x -r
When the process is over, exit the screen session:
exit
For more information on the `screen` command, see [the official Screen User's Manual](https://www.gnu.org/software/screen/manual/screen.html) or any of the other many resources available online.
10. Restart the `rippled` service.
sudo systemctl start rippled
11. Confirm that the `rippled` service started successfully.
You can use the [commandline interface](get-started-with-the-rippled-api.html#commandline) to check the server status (unless you have configured your server not to accept JSON-RPC requests). For example:
/opt/ripple/bin/rippled server_info
For a description of the expected response from this command, see the [server_info method][] documentation.
12. Watch the server's debug log to confirm that the `SQLite page size` is now 4096:
tail -F /var/log/rippled/debug.log
The [periodic log message](#proactive-detection) should also show significantly more free pages and free pages than it did before the migration.
13. Optionally, you may now remove the temporary folder you created for the migration process.
rm -r /tmp/rippled_txdb_migration
If you mounted additional storage to hold the temporary copy of the transaction database, you can unmount and remove it now.
<!--{# common link defs #}-->
{% include '_snippets/rippled-api-links.md' %}
{% include '_snippets/tx-type-links.md' %}
{% include '_snippets/rippled_versions.md' %}

49
dactyl-config.yml
View File

@@ -902,6 +902,14 @@ pages:
targets:
- local
- md: tutorials/manage-the-rippled-server/enable-public-signing.md
html: enable-public-signing.html
funnel: Docs
doc_type: Tutorials
category: Manage the rippled Server
targets:
- local
- md: tutorials/manage-the-rippled-server/run-rippled-as-a-validator.md
html: run-rippled-as-a-validator.html
funnel: Docs
@@ -945,6 +953,14 @@ pages:
# TODO: troubleshoot rippled,
# run a validator, run in stand-alone mode, set up private peers
- md: tutorials/manage-the-rippled-server/fix-sqlite-tx-db-page-size-issue.md
html: fix-sqlite-tx-db-page-size-issue.html
funnel: Docs
doc_type: Tutorials
category: Manage the rippled Server
targets:
- local
# References -------------------------------------------------------------------
- name: References
@@ -1362,6 +1378,17 @@ pages:
targets:
- local
- md: references/rippled-api/public-rippled-methods/path-and-order-book-methods/deposit_authorized.md
html: deposit_authorized.html
funnel: Docs
doc_type: References
supercategory: rippled API
category: Public rippled Methods
subcategory: Path and Order Book Methods
blurb: Check whether an account is authorized to send money directly to another.
targets:
- local
- md: references/rippled-api/public-rippled-methods/path-and-order-book-methods/path_find.md
html: path_find.html
funnel: Docs
@@ -1887,6 +1914,17 @@ pages:
targets:
- local
- md: references/rippled-api/ledger-data-formats/ledger-object-types/depositpreauth.md
html: depositpreauth-object.html #depositpreauth.html is taken by the tx type
funnel: Docs
doc_type: References
supercategory: rippled API
category: Ledger Data Formats
subcategory: Ledger Object Types
blurb: A record of preauthorization for sending payments to an account that requires authorization.
targets:
- local
- md: references/rippled-api/ledger-data-formats/ledger-object-types/directorynode.md
html: directorynode.html
funnel: Docs
@@ -2052,6 +2090,17 @@ pages:
targets:
- local
- md: references/rippled-api/transaction-formats/transaction-types/depositpreauth.md
html: depositpreauth.html
funnel: Docs
doc_type: References
supercategory: rippled API
category: Transaction Formats
subcategory: Transaction Types
blurb: Preauthorizes an account to send payments to this one.
targets:
- local
- md: references/rippled-api/transaction-formats/transaction-types/escrowcancel.md
html: escrowcancel.html
funnel: Docs