Skip to content

Commit 90c6de9

Browse files
mvadarimvadari
authored
Merge branch 'master' into copilot/fix-4d7baae3-30e8-449c-9911-511e99961dd6
2 parents fdfee5b + b9f312d commit 90c6de9

File tree

3 files changed

+394
-0
lines changed

3 files changed

+394
-0
lines changed

‎XLS-0025-enhanced-secret-numbers/README.md‎

Lines changed: 102 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,102 @@
1+
<pre>
2+
xls: 25
3+
title: Enhanced Secret Numbers
4+
description: Enhances XLS-12 secret number format by introducing an additional block for encoding ancillary information, and supporingt for longer secrets.
5+
author: Nik Bougalis (nikb@bougalis.net)
6+
status: Final
7+
category: Community
8+
created: 2021-12-10
9+
</pre>
10+
11+
# Enhanced Secret Numbers
12+
13+
## Abstract
14+
The Secret Numbers proposal **<a href="https://github.com/XRPLF/XRPL-Standards/tree/master/XLS-12">XLS-12</a>** introduces a new format for secrets - based on blocks of numbers/digits (0-9) with block-level checksums - to generate XRP Ledger account keys and address. This draft proposes augmenting and enhancing **XLS-12** to make the format more flexible and more robust.
15+
16+
### Motivation
17+
The XRP Ledger typically uses 128-bit seeds as the cryptographic material from which cryptographic keys for accounts are derived. Such seeds are generally too long for humans to remember and the existing formats are hard to <em>transcribe</em>. Prior to XLS-12, there were 4 canonical encoding for the seed data:
18+
19+
1. A Base58-based encoding scheme beginning with the letter `s` (in this format, the result is often, but _incorrectly_, referred to as a private key); or
20+
2. A word-based "mnemonic", encoded using a variant of RFC 1751; or
21+
3. A raw hex string, directly representing the 128-bit seed; or
22+
3. A passphrase, an arbitrary string of words which is hashed to produce a seed.
23+
24+
By way of example, let's use the well-known [genesis account](https://xrpl.org/accounts.html#special-addresses), `rHb9CJAWyB4rj91VRWn96DkukG4bwdtyTh`, which has an associated **`secp256k`** key:
25+
26+
1. The seed for the account is `snoPBrXtMeMyMHUVTgbuqAfg1SUTb`;
27+
2. The mnemonic is `I IRE BOND BOW TRIO LAID SEAT GOAL HEN IBIS IBIS DARE`;
28+
3. The raw hex is `DEDCE9CE67B451D852FD4E846FCDE31C`; and
29+
3. The corresponding passphrase is `masterpassphrase`.
30+
31+
The **XLS-12** standard introduced a new format, secret mumbers, which consists of 8 blocks of 6 digits, where the first five digits correspoding to a 16-bit number (from 0 to 65535) and the 6th digit is a checksum based on the five preceding digits and the index of the block. The **XLS-12** secret numbers for the genesis account are: `570521-598543-265488-209520-212450-201006-286214-581400`.
32+
33+
### Issues with XLS-12
34+
35+
The **XLS-12** specification, while convenient and easier to transcribe, has several drawbacks:
36+
37+
First, it encodes no ancillary information about the information encoded (e.g. whether it is meant to derive a **secp256k1** or an **Ed25519** key) and is limited to only encoding seeds, from which keys are then derived. Second, the block-level checksum is inefficient and detects only a small percentage of errors.
38+
39+
Lastly, it's unclear whether the secret numbers should be used to create a **secp256k1** or an **Ed25519** key. For example, given the above `570521-598543-265488-209520-212450-201006-286214-581400` secret numbers, an implementation could derive an **Ed25519** and, therefore, an account that is not the well-known genesis account. Tools that support secret numbers typically resort to detecting the type of account, usually in a semi- automated fashion, but on occasion by resorting to asking the user to confirm their intended public address.
40+
41+
### Enhancements to XLS-12
42+
43+
This proposal aims to address these problems by proposing extensions to **XLS-12** which retaining backwards compatibility. There are three primary changes:
44+
45+
1. Using a simplified but more powerful per-block checksum;
46+
2. Introducing an additional block, which is used to encode ancillary information; and
47+
3. Support for longer blocks, allowing encoding of 128-bit and 256-bit secrets.
48+
49+
Secret numbers compatible with this specification will always be composed of an odd number of blocks; secret numbers compatible with the **XLS-12** specification will always be composed of an even number of blocks&mdash;or more specifically, precisely 8 blocks. This makes it possible to seamlessly detect which standard was used and allows for backwards compatibility.
50+
51+
#### Per-block checksusm
52+
53+
Under **XLS-12** the Nth block consists of 16 bits of raw key material, and an additional checksum digit. Assuming the keying material has value `X` the N<sub>th</sub> block would be: `(X * 10) + ((X * (N * 2 + 1)) % 9)`.
54+
55+
In theory, the checksum digit can take any value from [0,...,9] but, by construction, not all checksum digits are equally likely across all blocks, reducing their usefulness. For blocks at positions 2 and 8, the only valid checksum digits are `0`, `3` and `6`; blocks at position 5 are worse, with `0` being the _only_ valid checksum digit.
56+
57+
This proposal simplifies the checksum function for key blocks by reducing it to a simple multiplication by 13, a prime number. That is, the N<sub>th</sub> key block simply becomes: `X * 13`. Under this scheme, the possible values are multiple of 13 and and the range is from [0,...,851955]. This scheme avoids the position-dependent behavior observed with the existing scheme and allows for more efficient error detection.
58+
59+
#### Information Block
60+
61+
This proposal _prepends_ an additional 6-digit block, composed of two 16-bit values, that encodes ancillary information about the content and a checksum of the blocks that can be used to detect whole-block transposition, or incorrect blocks.
62+
63+
First, calculate the checksum of all blocks as `(∑(𝑥[i] * π[i]>)) mod 256`, where `𝑥[i]` is the i<sup>th</sup> 16-bit block of data being encoded and `π[i]` is the i<sup>th</sup> prime number. The result is an 8-bit value, `C`.
64+
65+
##### Flags
66+
The proposal also defines an 8-bit field, that can be used to specify details or ancillary information about the key. This proposal defines this as a bitfield named `F`. The following flags are defined:
67+
68+
|Value | Meaning |
69+
|------|----------------------------------------------------------------------------------------------------------------------------|
70+
| `0x01` |The data block represents a raw 128-bit _seed_, from which private keys can be derived using the derivation algorithm defined in `rippled`. |
71+
| `0x02` |The private key calculated or derived from this block of data is used with the **secp256k1** algorithm. |
72+
| `0x04` |The private key calculated or derived from this block of data is used with the **Ed25519** algorithm. |
73+
| `0x08` |The data block represents an **Ed25519** validator master key. This flag cannot be combined with any other flags. |
74+
| `0x10` |The data block represents the fulfillment of a `PREIMAGE-SHA256` cryptocondition. This flag cannot be combined with any other flags. |
75+
76+
##### Using Flags
77+
78+
The different flags used with extended keys make it possible to directly encode different types of keys as well as allow for 128-bit and 256-bit keys.
79+
80+
For example:
81+
82+
- A 256-bit **`secp256k`** (or **`Ed25519`**, if the `0x08` flag is included) key can be directly encoded as 17 groups, if they information block does not include the `0x01` flag.
83+
- A 256-bit preimage for a cryptocondition can be encoded as 17 groups, if the information block includes the `0x10` flag.
84+
85+
Other flags may be added in the future. A compliant implementation of this proposal _SHOULD_ fail if any flags other than the ones it understands are used.
86+
87+
88+
##### Information Block Checksum
89+
90+
By construction, no valid XLS12 block can have a value greater than 655356 (i.e. 65535 * 10 + (65535 % 9)). This means that any block that begins with a 7, 8 or 9 cannot be a valid XLS12 block. This means that we can construct the first block in such a way so as to allow for automatic detection of "classic" XLS-12 keys and "extended" keys as defined in this proposal.
91+
92+
Again, assume that C is the checksum described above and F is the flag bitfield, then the information block checksum `X` is defined as:
93+
94+
X = (F ^ C) % 3
95+
96+
The information block itself is then calculated as:
97+
98+
A = ((X + 7) * 100000) + (C * 256 + F)
99+
100+
The end result is an A block that begins with 7, 8 or 9, which means it cannot be a valid XLS12 block, while still retaining a checksum in the A block.
101+
102+

‎XLS-0041-xpop/README.md‎

Lines changed: 130 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,130 @@
1+
<pre>
2+
xls: 41
3+
title: XRPL Proof of Payment Standard (XPOP)
4+
author: Richard Holland (RichardAH)
5+
description: An offline non-interactive cryptographic proof that a transaction was successfully submitted to the XRP Ledger and what its impact (metadata) was
6+
created: 2023-05-04
7+
status: Final
8+
category: Community
9+
</pre>
10+
# XLS-41d
11+
12+
# Abstract
13+
14+
An XRPL Proof of Payment (XPOP) is an offline non-interactive cryptographic proof that a transaction was successfully submitted to the XRP Ledger and what its impact (metadata) was.
15+
16+
# Background
17+
18+
The XRPL is comprised of a chain of blocks (Ledgers) co-operatively and deterministically computed, shared and subsequently signed (validated) by a quorum of rippled nodes (validators) operating in a socially trusted group known as a Unique Node List (UNL). The UNL is typically published by a trusted third party in a format known as a Validator List (VL). (Examples: https://vl.xrplf.com, https://vl.ripple.com). Each VL is cryptographically signed by a master publishing key. Users of the network ultimately trust this publisher (key) to choose appropriate validators for the UNL that will co-operate to make forward progress and not conspire to defraud them.
19+
20+
# Proof
21+
22+
Each VL contains a list of validators signed for by the VL publisher key.
23+
24+
Each validator is a key that signs validation messages over each Ledger header.
25+
26+
Each Ledger header contains the root hash of two patricia merkle tries:
27+
28+
- the current (”account”) state for the ledger, and
29+
- the transactions and their metadata in that Ledger.
30+
31+
A quorum (from a given VL) of signed validation messages proves a Ledger was correctly closed and became part of the block chain.
32+
33+
Thus if one trusts the VL publisher key, then one can form a complete chain of validation from the VL key down to a transaction and its meta data without connectivity to the internet. This is an XPOP.
34+
35+
# Format
36+
37+
XPOPs are a JSON object with the following schema:
38+
39+
```
40+
{
41+
"ledger": {
42+
"acroot": merkle root of account state map | hex string,
43+
"txroot": merkle root of transaction map | hex string ,
44+
"close": close time | int,
45+
"coins": total drops | int or string,
46+
"cres": close time resolution | int,
47+
"flags": ledger flags | int,
48+
"pclose": parent close time | int,
49+
"phash": parent hash | hex string,
50+
},
51+
"transaction": {
52+
"blob": serialized transaction | hex string,
53+
"meta": serialized metadata | hex string,
54+
"proof": <see below>
55+
},
56+
"validation": {
57+
"data": {
58+
validator pub key or master key | base58 string : serialized validation message | hex string
59+
... for each validation message
60+
},
61+
"unl": {
62+
"blob": base64 encoded VL blob as appearing on vl site | base64 string,
63+
... remaining fields from vl site
64+
}
65+
}
66+
}
67+
```
68+
69+
The `proof` key inside `transaction` section has one of two possible forms:
70+
71+
1. List form:
72+
73+
In this form the merkle proof is a list of lists (and strings) containing the minimum number of entries to form the merkle proof. Each list contains 16 entries (branches `0` through `F`). For each branch either the the root hash of that branch is provided as a 64 hex nibble string, or a further list of 16 entries is provided, until the transaction that the proof proves is reached. If a list contains fewer than 16 entries then the verifier should infer that the remaining entries are all null entries (hash strings that are sequences of 0s).
74+
75+
76+
```
77+
# list form
78+
"proof": [
79+
hex string for branch '0',
80+
...
81+
hex string for branch 'A',
82+
# branch 'B' is a list
83+
[
84+
hex string for branch 'B0',
85+
... ,
86+
hex string for branch 'BE',
87+
# branch 'BF' is a list
88+
[
89+
hex string for branch 'BF0',
90+
...
91+
]
92+
],
93+
hex string for branch 'C',
94+
...
95+
]
96+
97+
```
98+
99+
1. Tree form:
100+
101+
In this form the merkle proof is an object of objects containing the entire transaction map for the ledger. This form is useful if many XPOPs must be generated for the same ledger and the size of each individual XPOP is less relevant than the amount of work to make and store the XPOPs. Each object contains three keys: `children`, `hash`, `key`.
102+
103+
- The `children` key is always either an empty object or is keyed with only the branches which actually exist there, each as a single hex nibble `0` - `F`.
104+
- The `hash` key is always a 64 nibble hex string: either the hash over the children (with appropriate namespace) or, if a leaf node, the hash over the node (with appropriate namespace).
105+
- The `key` key is always a 64 nibble hex string: the keylet (index) of the object at this location.
106+
107+
```
108+
# tree form
109+
"proof": {
110+
"hash" : hex string,
111+
"key" : hex string,
112+
"children" : {
113+
"0":
114+
{
115+
"children": {},
116+
"hash": hex string,
117+
"key": hex string
118+
},
119+
...
120+
"F":
121+
{ ...}
122+
}
123+
}
124+
```
125+
126+
# Verifying
127+
128+
See reference implementation at: [xpop-verifier-py](https://github.com/RichardAH/xpop-verifier-py/blob/main/verify.py)
129+
130+

0 commit comments

Comments
 (0)