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

Merge pull request #485 from mDuo13/hash_clarifications

Browse Source 
Hashes - clarify hash prefixes, SHA-512Half size.
This commit is contained in:
Rome Reginelli
2018-12-18 11:59:55 -08:00
committed by GitHub
parent 2dc69e94ee a6b82ff599
commit 5308d5d1d9
5 changed files with 33 additions and 5 deletions
Download Patch File Download Diff File Expand all files Collapse all files

2
content/_snippets/data_types/hash.md
View File

@@ -1,4 +1,4 @@
Many objects in the XRP Ledger, particularly transactions and ledgers, are uniquely identified by a 256-bit hash value. This value is typically calculated as a "SHA-512Half", which calculates a [SHA-512](http://dx.doi.org/10.6028/NIST.FIPS.180-4) hash from some contents, then takes the first 64 characters of the hexadecimal representation. Since the hash of an object is derived from the contents in a way that is extremely unlikely to produce collisions, two objects with the same hash can be considered the same.
Many objects in the XRP Ledger, particularly transactions and ledgers, are uniquely identified by a 256-bit hash value. This value is typically calculated as a "SHA-512Half", which calculates a [SHA-512](http://dx.doi.org/10.6028/NIST.FIPS.180-4) hash from some contents, then takes the first half of the output. (That's 256 bits, which is 32 bytes, or 64 characters of the hexadecimal representation.) Since the hash of an object is derived from the contents in a way that is extremely unlikely to produce collisions, two objects with the same hash can be considered the same.
An XRP Ledger hash value has the following characteristics:

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

@@ -12,7 +12,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-object-ids.html#sha512half
[SHA-512Half]: basic-data-types.html#hashes
[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

27
content/references/rippled-api/api-conventions/basic-data-types.md
View File

@@ -21,6 +21,33 @@ Each closed [Ledger](ledger-data-formats.html) has a [Ledger Index][] and a [Has
{% include '_snippets/data_types/hash.md' %}
<!--{#_ #}-->
### Hash Prefixes
[[Source]<br>](https://github.com/ripple/rippled/blob/master/src/ripple/protocol/HashPrefix.h "Source")
In many cases, the XRP Ledger prefixes an object's binary data with a 4-byte code before calculating its hash, so that objects of different types have different hashes even if their binary formats are the same. The existing 4-byte codes are structured as three alphabetic characters, encoded as ASCII, followed by a zero byte.
Some types of hash appear in API requests and responses. Others are only calculated as the first step of signing a certain type of data, or calculating a higher-level hash. The following table shows all 4-byte hash prefixes the XRP Ledger uses:
| Object Type | API Fields | Hash Prefix (Hex) | Hash Prefix (Text) |
|:--------------------------------------|:-------------------------------------|:------------------|:--|
| Consensus proposal | N/A | `0x50525000` | `PRP\0` |
| Ledger Version | `ledger_hash` | `0x4C575200` | `LWR\0` |
| Ledger state data | `account_state` in [ledger header][] | `0x4D4C4E00` | `MLN\0` |
| Ledger data inner node | N/A | `0x4D494E00` | `MIN\0` |
| Ledger data inner node ([SHAMapv2][]) | N/A | `0x494E5200` | `INR\0` |
| Payment Channel Claim | N/A | `0x434C4D00` | `CLM\0` |
| Signed Transaction | `hash` of transactions | `0x54584E00` | `TXN\0` |
| Transaction with metadata | N/A | `0x534E4400` | `SND\0` |
| Unsigned Transaction (Single-signing) | N/A | `0x53545800` | `STX\0` |
| Unsigned Transaction (Multi-signing) | N/A | `0x534D5400` | `SMT\0` |
| Validation vote | N/A | `0x56414C00` | `VAL\0` |
| Validator subkey authorization ("validator manifest") | N/A | `0x4D414E00` | `MAN\0` |
[ledger header]: ledger-header.html
[SHAMapv2]: known-amendments.html#shamapv2
[Ledger objects IDs](ledger-object-ids.html) are calculated in a similar way, but they use a 2-byte prefix called a "space key" instead of a prefix in the form described here.
## Account Sequence
[Sequence Number]: #account-sequence

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

@@ -6,7 +6,7 @@ Every ledger version has a unique header that describes the contents. You can lo
| 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. |
| `ledger_hash` | String | Hash256 | The [SHA-512Half][] of this ledger version. 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.) |

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

@@ -1,14 +1,15 @@
# 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#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.
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 bits. 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).
- For more information how the XRP Ledger creates and uses hashes, see [Hashes](basic-data-types.html#hashes).
- For ledger basics, see [Ledgers](ledgers.html).
<!--{# common link defs #}-->