Skip to content

Add spec for proofs #89

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 37 commits into from
Feb 22, 2023
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
37 commits
Select commit Hold shift + click to select a range
ae6cb3d
Add spec for proofs
MavenRain Jan 3, 2023
c5e173b
Refactoring to proof attribute
MavenRain Jan 3, 2023
e0b62bc
Proof response given number 3, proof network attribute given number 1…
MavenRain Jan 4, 2023
1c4f105
Add attribute-arg to proof attribute, and change key-value-pair repre…
MavenRain Jan 4, 2023
71e0c5b
Add example proof construction to adoc
MavenRain Jan 4, 2023
f67e687
Key-value-pair change
MavenRain Jan 4, 2023
c97b7ff
Reorganizing and creating hash scheme section
MavenRain Jan 4, 2023
c583207
Add text for hash scheme
MavenRain Jan 5, 2023
2b314cb
hash attribute id comment edit
MavenRain Jan 5, 2023
521b459
Add newlines at end of file adn move hash scheme doc to separate file
MavenRain Jan 5, 2023
a3331d9
Fix typo
MavenRain Jan 5, 2023
53abb81
More newlines in files
MavenRain Jan 5, 2023
e2fc0c3
Make clear the hash function used in the hash scheme for constructing…
MavenRain Jan 5, 2023
486a3eb
Swapping contents of network proof adoc and response proof adoc
MavenRain Jan 5, 2023
333f579
Add stub for proof request attribute adoc
MavenRain Jan 9, 2023
23c2995
Rearrange items in spec to fit the attribute pattern for proofs
MavenRain Jan 10, 2023
a8053cf
Set proof structure to the response attribute arg in response cddl an…
MavenRain Jan 12, 2023
1e952c2
Add root hash to response attribute
MavenRain Jan 12, 2023
aea2dc3
Add newline
MavenRain Jan 12, 2023
12d0bd4
Complete revisions according to last set of review comments
MavenRain Jan 13, 2023
09bf877
Added newline
MavenRain Jan 13, 2023
7bce59f
Another newline
MavenRain Jan 13, 2023
4326429
Fix response attribute error
MavenRain Jan 14, 2023
3d64512
proof rule duplicate, I think
MavenRain Jan 14, 2023
bfc1a28
Rename index in proof response attribute
MavenRain Jan 14, 2023
fa244ff
Addressing group entry
MavenRain Jan 14, 2023
088b8aa
Trying to fix compilation error
MavenRain Jan 17, 2023
4a069a1
Found compilation error,as response-attribute-arg was accidentally de…
MavenRain Jan 17, 2023
9ae4a15
Remove proof prefix
MavenRain Jan 17, 2023
c0d15ed
Fix map association typo
MavenRain Jan 17, 2023
72bff56
Appears that a separate entry for attribute-related-index is needed
MavenRain Jan 17, 2023
865c9d4
looks like profo prefix is needed
MavenRain Jan 17, 2023
fee322c
Split proof into proof and proof operation to avoid anonymous enum
MavenRain Jan 23, 2023
14fed5e
Misssing memo field?
MavenRain Jan 23, 2023
428dd5b
Update attributes/network/14_proof.adoc
MavenRain Feb 22, 2023
01a9054
Update attributes/network/14_proof.adoc
MavenRain Feb 22, 2023
051eb9b
Update attributes/network/14_proof.adoc
MavenRain Feb 22, 2023
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
187 changes: 187 additions & 0 deletions attributes/network/14_proof.adoc
Original file line number Diff line number Diff line change
@@ -0,0 +1,187 @@
= Proof Attribute (#14)
:cddl: ./cddl/

This attribute represents a proof of an object requested with respect to the blockchain's underlying state represented as a Merkle tree.

== Example
The following is taken from https://github.com/liftedinit/merk/blob/develop/docs/algorithms.md#example-proofs

Let's walk through a concrete proof example. Consider the following tree:

```
5
/ \
/ \
2 9
/ \ / \
1 4 7 11
/ / \ /
3 6 8 10
```

_Small proof:_

First, let's create a proof for a small part of the tree. Let's say the user makes a query for keys `1, 2, 3, 4`.

If we follow our proof generation algorithm, we should get a proof that looks like this:

```
Push(KV(1, <value of 1>)),
Push(KV(2, <value of 2>)),
Parent,
Push(KV(3, <value of 3>)),
Push(KV(4, <value of 4>)),
Parent,
Child,
Push(KVHash(<kv_hash of 5>)),
Parent,
Push(Hash(<hash of 9>)),
Child
```

Let's step through verification to show that this proof works.
We'll create a verification stack, which starts out empty, and walk through each operator in the proof, in order:

```
Stack: (empty)
```

We will push a key/value pair on the stack, creating a node.
However, note that for verification purposes this node will only need to contain the kv_hash which we will compute at this step.

```
Operator: Push(KV(1, <value of 1>))

Stack:
1
```

```
Operator: Push(KV(2, <value of 2>))

Stack:
1
2
```

Now we connect nodes 1 and 2, with 2 as the parent.

```
Operator: Parent

Stack:
2
/
1
```

```
Operator: Push(KV(3, <value of 3>))

Stack:
2
/
1
3
```

```
Operator: Push(KV(4, <value of 4>))

Stack:
2
/
1
3
4
```

```
Operator: Parent

Stack:
2
/
1
4
/
3
```

Now connect these two graphs with 4 as the child of 2.

```
Operator: Child

Stack:
2
/ \
1 4
/
3
```

Since the user isn't querying the data from node 5, we only need its kv_hash.

```
Operator: Push(KVHash(<kv_hash of 5>))

Stack:
2
/ \
1 4
/
3
5
```

```
Operator: Parent

Stack:
5
/
2
/ \
1 4
/
3
```

We only need the hash of node 9.

```
Operator: Push(Hash(<hash of 9>))

Stack:
5
/
2
/ \
1 4
/
3
9
```

```
Operator: Child

Stack:
5
/ \
2 9
/ \
1 4
/
3
```

Now after going through all these steps, we have sufficient knowlege of the tree's structure and data to compute node hashes in order to verify.
At the end, we will have computed a hash for node 5 (the root), and we verify by comparing this hash to the one we expected.

[sources,cddl]
----
include::{cddl}14_proof.cddl
----

3 changes: 3 additions & 0 deletions attributes/network/cddl/14_proof.cddl
Original file line number Diff line number Diff line change
@@ -0,0 +1,3 @@
; Attribute id (related to hashing implementation)
proof@attribute-arg = uint

5 changes: 5 additions & 0 deletions attributes/request/3_proof.adoc
Original file line number Diff line number Diff line change
@@ -0,0 +1,5 @@
= Proof Request Attribute (#3)
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

What will go here?

:cddl: ./cddl/

This attribute is used to request a proof in the response for a particular request sent to the server.

37 changes: 37 additions & 0 deletions attributes/response/3_proof.adoc
Original file line number Diff line number Diff line change
@@ -0,0 +1,37 @@
= Proof Response Attribute (#3)
:cddl: ./cddl/

This attribute allows server to deliver the proof of an object requested.
The proof itself is a sequence of actions used to construct the state in which the object is embedded within the corresponding Merkle tree.

== Attribute Argument

This is a `uint` representing the hasher used in constructing the proofs.

* 0 - `merk` default hash (see xref:../../spec/proof_hash_scheme.adoc.)

== Returns

A proof is a collection of operations used to reconstruct a state that can be embedded into the existing state of the Merkle tree that contains it.

Each state can be represented by one of five operations:

* A node hash

* A key/value hash of a node

* A key and value pair of a node

* The "parent" operation

* The "child" operation

Interpreting these operations as acting on a stack, the first three operations listed can be interpreted as pushing data onto the stack.
In the parent operation, two items are popped from the stack, and a new item with the second item as the left child of the first item is pushed onto the stack.
In the child operation, two items are popped from the stack, and a new item with the first item as the right child of the second item is pushed back onto the stack.

[source,cddl]
....
include::{cddl}/3_proof.cddl[]
....

5 changes: 5 additions & 0 deletions attributes/response/3_proof/0_blockchain.cddl
Original file line number Diff line number Diff line change
@@ -0,0 +1,5 @@
proof@request-attribute-arg //= {
; Block height.
[3, [0, 0]] => uint
}

33 changes: 33 additions & 0 deletions attributes/response/cddl/3_proof.cddl
Original file line number Diff line number Diff line change
@@ -0,0 +1,33 @@
; Proof. If requested, this is the set of steps constituting a proof of existence of what was requested in the state of the Merkle tree.
proof@response-attribute-arg = {
; Root application hash
0 => bstr,

; The proof operations
1 => proof,

; Extensible attribute related indices for extra information (implementation specific)
* proof-attribute-related-index,
}

proof-attribute-related-index = ()

proof = [ + proof-operation ]

proof-operation = ( node-hash / key-value-hash / key-value-pair / parent / child )

; Represents a parent operation in a proof
parent = 0x10

; Represents a child operation in a proof
child = 0x11

; The hash of a key-value pair
key-value-hash = [1, bstr]

; The hash of a node in a proof, containing, in order, the hash of the key-value pair, the hash of the left child, and the hash of the right child
node-hash = [2, bstr]

; The key-value pair of a proof
key-value-pair = [3, bstr, bstr]

3 changes: 3 additions & 0 deletions gherkin-tests/src/steps/ledger.rs
Original file line number Diff line number Diff line change
Expand Up @@ -38,6 +38,7 @@ async fn id_has_x_symbols(world: &mut World, id: Identifier, amount: BigUint, sy
to: identity.address(),
amount: amount.clone() - current_balance,
symbol,
memo: None,
})
.await
.expect("Should have sent");
Expand All @@ -50,6 +51,7 @@ async fn id_has_x_symbols(world: &mut World, id: Identifier, amount: BigUint, sy
to: faucet.address(),
amount: current_balance - amount.clone(),
symbol,
memo: None,
})
.await
.expect("Should have sent");
Expand Down Expand Up @@ -79,6 +81,7 @@ async fn send_symbol(
to: receiver,
amount: amount.into(),
symbol,
memo: None,
})
.await
.unwrap();
Expand Down
1 change: 1 addition & 0 deletions spec/cddl/many.cddl
Original file line number Diff line number Diff line change
Expand Up @@ -159,3 +159,4 @@ attribute-id-custom = nint

; An attribute contains an ID and arguments.
attribute = attribute-id / [attribute-id, * attribute-arg]

17 changes: 17 additions & 0 deletions spec/proof_hash_scheme.adoc
Original file line number Diff line number Diff line change
@@ -0,0 +1,17 @@
= Proof Hash Scheme
:cddl: ./cddl/

The following list of hash schemes is ordered by attribute id

== 0

Each node contains a "kv hash", which is the hash of a prefix concatenanted with the nodes key and its value.
The hash of the node is the hash of a distinct prefix, the kv hash, and the hash of each of the left and right child nodes.

```
kv_hash = H(0x00, key.length, key, value.length, value)
node_hash = H(0x01, kv_hash, left_child_hash, right_child_hash)
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Same as above.

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Actually, the node hash does not have the lengths in the hash.

```

The hash function H is currently the blake3 hash.