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

inc'd feedback

Browse Source
This commit is contained in:
Jennifer Hasegawa
2018-05-18 13:46:38 -07:00
parent 529cd1f13c
commit 57606ae12a
9 changed files with 66 additions and 83 deletions
Download Patch File Download Diff File Expand all files Collapse all files

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

@@ -11,7 +11,7 @@
[result code]: transaction-results.html
[seconds since the Ripple Epoch]: basic-data-types.html#specifying-time
[Sequence Number]: basic-data-types.html#account-sequence
[SHA-512Half]: ledger-data-formats.html#sha512half
[SHA-512Half]: ledger-object-ids.html#sha512half
[Specifying Currency Amounts]: basic-data-types.html#specifying-currency-amounts
[Specifying Ledgers]: basic-data-types.html#specifying-ledgers
[Specifying Time]: basic-data-types.html#specifying-time

7
content/concepts/payment-system-basics/ledgers.md
View File

@@ -23,12 +23,11 @@ As its name might suggest, a ledger's state tree is a tree data structure. Each
In the case of transactions, the identifying hash is based on the signed transaction instructions, but the contents of the transaction object when you look it up also contain the results and metadata of the transaction, which are not taken into account when generating the hash.
## Object IDs
<a id="sha512half"></a>
All objects in a ledger' 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 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.
## See Also
For more information about ledger headers, ledger object IDs, and ledger object types, see [Ledger Data Formats](ledger-data-formats.html)
![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)
<!--{# common link defs #}-->
{% include '_snippets/rippled-api-links.md' %}

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

@@ -164,9 +164,9 @@ When the server is in the progress of fetching a ledger, but has not yet finishe
|:----------------------------|:-----------------|:----------------------------|
| `hash` | String | (May be omitted) The [Hash][] of the requested ledger, if the server knows it. |
| `have_header` | Boolean | Whether the server has the header section of the requested ledger. |
| `have_state` | Boolean | (May be omitted) Whether the server has the [account-state section](ledger-data-formats.html#tree-format) of the requested ledger. |
| `have_state` | Boolean | (May be omitted) Whether the server has the [account-state section](ledgers.html#tree-format) of the requested ledger. |
| `have_transactions` | Boolean | (May be omitted) Whether the server has the transaction section of the requested ledger. |
| `needed_state_hashes` | Array of Strings | (May be omitted) Up to 16 hashes of objects in the [state tree](ledger-data-formats.html#tree-format) that the server still needs to retrieve. |
| `needed_state_hashes` | Array of Strings | (May be omitted) Up to 16 hashes of objects in the [state tree](ledgers.html#tree-format) that the server still needs to retrieve. |
| `needed_transaction_hashes` | Array of Strings | (May be omitted) Up to 16 hashes of objects in the transaction tree that the server still needs to retrieve. |
| `peers` | Number | How many peers the server is querying to find this ledger. |
| `timeouts` | Number | Number of times fetching this ledger has timed out so far. |

28
content/references/rippled-api/ledger-data-formats/ledger-header.md
View File

@@ -3,18 +3,18 @@
Every ledger version has a unique header that describes the contents. You can look up a ledger's header information with the [ledger method][]. The contents of the ledger header are as follows:
| Field | JSON Type | [Internal Type][] | Description |
|-----------------|-----------|-------------------|-------------|
| [`ledger_index`][Ledger Index] | String | UInt32 | The sequence number of the ledger. Some API methods display this as a quoted integer; some display it as a native JSON number. |
| `ledger_hash` | String | Hash256 | The [SHA-512Half][] of the ledger header, excluding the `ledger_hash` itself. This serves as a unique identifier for this ledger and all its contents. |
| `account_hash` | String | Hash256 | The [SHA-512Half][] of this ledger's state tree information. |
| `close_time` | Number | UInt32 | The approximate time this ledger closed, as the number of seconds since the Ripple Epoch of 2000-01-01 00:00:00. This value is rounded based on the `close_time_resolution`, so later ledgers can have the same value. |
| `closed` | Boolean | bool | If true, this ledger version is no longer accepting new transactions. (However, unless this ledger version is validated, it might be replaced by a different ledger version with a different set of transactions.) |
| `parent_hash` | String | Hash256 | The `ledger_hash` value of the previous ledger that was used to build this one. If there are different versions of the previous ledger index, this indicates from which one the ledger was derived. |
| `total_coins` | String | UInt64 | The total number of [drops of XRP][XRP, in drops] owned by accounts in the ledger. This omits XRP that has been destroyed by transaction fees. The actual amount of XRP in circulation is lower because some accounts are "black holes" whose keys are not known by anyone. |
| `transaction_hash` | String | Hash256 | The [SHA-512Half][] of the transactions included in this ledger. |
| `close_time_resolution` | Number | Uint8 | An integer in the range \[2,120\] indicating the maximum number of seconds by which the `close_time` could be rounded. |
| [`closeFlags`](#close-flags) | (Omitted) | UInt8 | A bit-map of flags relating to the closing of this ledger. |
| Field | JSON Type | [Internal Type][] | Description |
|:-------------------------------|:----------|:------------------|:------------|
| [`ledger_index`][Ledger Index] | String | UInt32 | The sequence number of the ledger. Some API methods display this as a quoted integer; some display it as a native JSON number. |
| `ledger_hash` | String | Hash256 | The [SHA-512Half][] of the ledger header, excluding the `ledger_hash` itself. This serves as a unique identifier for this ledger and all its contents. |
| `account_hash` | String | Hash256 | The [SHA-512Half][] of this ledger's state tree information. |
| `close_time` | Number | UInt32 | The approximate time this ledger closed, as the number of seconds since the Ripple Epoch of 2000-01-01 00:00:00. This value is rounded based on the `close_time_resolution`, so later ledgers can have the same value. |
| `closed` | Boolean | bool | If true, this ledger version is no longer accepting new transactions. (However, unless this ledger version is validated, it might be replaced by a different ledger version with a different set of transactions.) |
| `parent_hash` | String | Hash256 | The `ledger_hash` value of the previous ledger that was used to build this one. If there are different versions of the previous ledger index, this indicates from which one the ledger was derived. |
| `total_coins` | String | UInt64 | The total number of [drops of XRP][XRP, in drops] owned by accounts in the ledger. This omits XRP that has been destroyed by transaction fees. The actual amount of XRP in circulation is lower because some accounts are "black holes" whose keys are not known by anyone. |
| `transaction_hash` | String | Hash256 | The [SHA-512Half][] of the transactions included in this ledger. |
| `close_time_resolution` | Number | Uint8 | An integer in the range \[2,120\] indicating the maximum number of seconds by which the `close_time` could be rounded. |
| [`closeFlags`](#close-flags) | (Omitted) | UInt8 | A bit-map of flags relating to the closing of this ledger. |
## Ledger Index
@@ -29,6 +29,10 @@ The ledger has only one flag defined for closeFlags: **sLCF_NoConsensusTime** (v
The `closeFlags` field is not included in any JSON representations of a ledger, but is included in the binary representation of a ledger, and is one of the fields that determine the ledger's hash.
## See Also
For ledger basics, see [Ledgers](ledgers.html).
<!--{# common link defs #}-->
{% include '_snippets/rippled-api-links.md' %}

17
content/references/rippled-api/ledger-data-formats/ledger-object-ids.md Normal file
View File

@@ -0,0 +1,17 @@
# 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.
![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)
## See Also
For ledger basics, see [Ledgers](ledgers.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/ledger-data-formats/ledger-object-types/directorynode.md
View File

@@ -1,7 +1,7 @@
# DirectoryNode
[[Source]<br>](https://github.com/ripple/rippled/blob/5d2d88209f1732a0f8d592012094e345cbe3e675/src/ripple/protocol/impl/LedgerFormats.cpp#L44 "Source")
The `DirectoryNode` object type provides a list of links to other objects in the ledger's state tree. A single conceptual _Directory_　takes the form of a doubly linked list, with one or more DirectoryNode objects each containing up to 32 [IDs](ledger-data-formats.html#tree-format) of other objects. The first object is called the root of the directory, and all objects other than the root object can be added or deleted as necessary.
The `DirectoryNode` object type provides a list of links to other objects in the ledger's state tree. A single conceptual _Directory_　takes the form of a doubly linked list, with one or more DirectoryNode objects each containing up to 32 [IDs](ledgers.html#tree-format) of other objects. The first object is called the root of the directory, and all objects other than the root object can be added or deleted as necessary.
There are two kinds of Directories:

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

@@ -1,47 +0,0 @@
# Ledger Object Types
Following are the different kinds of objects that can appear in the ledger's state tree. Each ledger object consists of several fields. In the peer protocol that `rippled` servers use to communicate with each other, ledger objects are represented in their raw binary format. In the [`rippled` API](rippled-api.html), ledger objects are represented as JSON objects.
* [**AccountRoot**](accountroot.html)
The settings, XRP balance, and other metadata for one account.
* [**Amendments**](amendments.html)
Singleton object with status of enabled and pending amendments.
* [**Check**](check.html)
A check that can be redeemed for money by its destination.
* [**DirectoryNode**](directorynode.html)
Contains links to other objects.
* [**Escrow**](escrow.html)
Contains XRP held for a conditional payment.
* [**FeeSettings**](feesettings.html)
Singleton object with consensus-approved base transaction cost and reserve requirements.
* [**LedgerHashes**](ledgerhashes.html)
Lists of prior ledger versions' hashes for history lookup.
* [**Offer**](offer.html)
An offer to exchange currencies, known in finance as an _order_.
* [**PayChannel**](paychannel.html)
A channel for asynchronous XRP payments.
* [**RippleState**](ripplestate.html)
Links two accounts, tracking the balance of one currency between them. The concept of a _trust line_ is really an abstraction of this object type.
* [**SignerList**](signerlist.html)
A list of addresses for multi-signing transactions.

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

@@ -58,11 +58,11 @@ The full list of parameters recognized by this method is as follows:
|:------------------------|:---------------------------|:----------------------|
| `index` | String | _(Optional)_ Specify the unique identifier of a single ledger entry to retrieve. |
| `account_root` | String - [Address][] | _(Optional)_ Specify an [AccountRoot object](accountroot.html) to retrieve. |
| `directory` | Object or String | _(Optional)_ Specify a [DirectoryNode](directorynode.html). (DirectoryNode objects each contain a list of IDs for things contained in them.) If a string, interpret as the [unique index](ledger-data-formats.html#tree-format) to the directory, in hex. If an object, requires either `dir_root` or `owner` as a sub-field, plus optionally a `sub_index` sub-field. |
| `directory` | Object or String | _(Optional)_ Specify a [DirectoryNode](directorynode.html). (DirectoryNode objects each contain a list of IDs for things contained in them.) If a string, interpret as the [unique index](ledgers.html#tree-format) to the directory, in hex. 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 [Directory](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 |
| `offer` | Object or String | _(Optional)_ Specify an [Offer object](offer.html) to retrieve. If a string, interpret as the [unique index](ledger-data-formats.html#tree-format) to the Offer. If an object, requires the sub-fields `account` and `seq` to uniquely identify the offer. |
| `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. |
| `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. |

38
dactyl-config.yml
View File

@@ -1799,15 +1799,25 @@ pages:
targets:
- local
- md: references/rippled-api/ledger-data-formats/ledger-object-types/ledger-object-types.md
- md: references/rippled-api/ledger-data-formats/ledger-object-ids.md
html: ledger-object-ids.html
funnel: Docs
doc_type: References
supercategory: rippled API
category: Ledger Data Formats
blurb: All objects in a ledger's state tree have a unique ID.
targets:
- local
- name: Ledger Object Types
html: ledger-object-types.html
funnel: Docs
doc_type: References
supercategory: rippled API
category: Ledger Data Formats
subcategory: Ledger Object Types
# template: template-landing-children.html #TODO: consider dropping the md since the page children handles this OK
blurb: Specifications for the types of objects that can be stored in a ledger's state tree.
template: template-landing-children.html #TODO: consider dropping the md since the page children handles this OK
blurb: Each ledger's state tree consists of a set of ledger objects, which collectively represent all settings, balances, and relationships in the shared ledger. In the peer protocol that rippled servers use to communicate with each other, ledger objects are represented in their raw binary format. In the rippled API, ledger objects are represented as JSON objects.
targets:
- local
@@ -1818,7 +1828,7 @@ pages:
supercategory: rippled API
category: Ledger Data Formats
subcategory: Ledger Object Types
# blurb: The settings, XRP balance, and other metadata for one account.
blurb: The settings, XRP balance, and other metadata for one account.
targets:
- local
@@ -1829,7 +1839,7 @@ pages:
supercategory: rippled API
category: Ledger Data Formats
subcategory: Ledger Object Types
# blurb: Singleton object with status of enabled and pending amendments.
blurb: Singleton object with status of enabled and pending amendments.
targets:
- local
@@ -1840,7 +1850,7 @@ pages:
supercategory: rippled API
category: Ledger Data Formats
subcategory: Ledger Object Types
# blurb: A check that can be redeemed for money by its destination.
blurb: A check that can be redeemed for money by its destination.
targets:
- local
@@ -1851,7 +1861,7 @@ pages:
supercategory: rippled API
category: Ledger Data Formats
subcategory: Ledger Object Types
# blurb: Contains links to other objects.
blurb: Contains links to other objects.
targets:
- local
@@ -1862,7 +1872,7 @@ pages:
supercategory: rippled API
category: Ledger Data Formats
subcategory: Ledger Object Types
# blurb: Contains XRP held for a conditional payment.
blurb: Contains XRP held for a conditional payment.
targets:
- local
@@ -1873,7 +1883,7 @@ pages:
supercategory: rippled API
category: Ledger Data Formats
subcategory: Ledger Object Types
# blurb: Singleton object with consensus-approved base transaction cost and reserve requirements.
blurb: Singleton object with consensus-approved base transaction cost and reserve requirements.
targets:
- local
@@ -1884,7 +1894,7 @@ pages:
supercategory: rippled API
category: Ledger Data Formats
subcategory: Ledger Object Types
# blurb: Lists of prior ledger versions' hashes for history lookup.
blurb: Lists of prior ledger versions' hashes for history lookup.
targets:
- local
@@ -1895,7 +1905,7 @@ pages:
supercategory: rippled API
category: Ledger Data Formats
subcategory: Ledger Object Types
# blurb: An order to make a currency trade.
blurb: An order to make a currency trade.
targets:
- local
@@ -1906,7 +1916,7 @@ pages:
supercategory: rippled API
category: Ledger Data Formats
subcategory: Ledger Object Types
# blurb: A channel for asynchronous XRP payments.
blurb: A channel for asynchronous XRP payments.
targets:
- local
@@ -1917,7 +1927,7 @@ pages:
supercategory: rippled API
category: Ledger Data Formats
subcategory: Ledger Object Types
# blurb: Links two accounts, tracking the balance of one currency between them. The concept of a trust line is an abstraction of this object type.
blurb: Links two accounts, tracking the balance of one currency between them. The concept of a trust line is an abstraction of this object type.
targets:
- local
@@ -1928,7 +1938,7 @@ pages:
supercategory: rippled API
category: Ledger Data Formats
subcategory: Ledger Object Types
# blurb: A list of addresses for multi-signing transactions.
blurb: A list of addresses for multi-signing transactions.
targets:
- local