docs: add inclusion proofs documentation #160

rach-id · 2023-07-26T13:33:16Z

Overview

Closes #143 and #193

Checklist

New and updated code has appropriate documentation
New and updated code has new and/or updated testing
Required CI checks are passing
Visual proof for any user facing features like CLI or documentation updates
Linked issues closed with keywords

docs/fraud-proofs.md

Co-authored-by: John Adler <[email protected]>

evan-forbes

This is a good start, and there's a lot of good info here, but I think it would be helpful to devs to make a clearer distinction between what the qgb contracts are doing, inclusion proofs, and then talk more about an example fraud proof system that uses those inclusion proofs to prove fraud (and not necessarily a bunch of different new fraud proof types).

If we want to discuss the details of what inclusion proofs actually look like under the hood, then we should specify that (which would also be useful)

docs/fraud-proofs.md

evan-forbes · 2023-07-28T09:07:46Z

docs/fraud-proofs.md

+Fraud proofs is the mechanism used to inform light clients in the case of an invalid rollup state transition or unavailable rollup block data. They rely on rollup full nodes getting the data that was published to Celestia, and executing all the state transitions to verify the rollup state. If they discover an invalid state transition or unavailable rollup data, they emit a fraud proof with the necessary information to convince light clients that fraud happened. This allows for trust-minimized light clients, as the network only needs one honest full node to create the fraud proof and propagate it.
+
+If the Celestium is settlement smart contract based, then the contract would only need to receive a fraud proof to decide whether data was published correctly or not.


are there types of celestiums that aren't smart contract based?

I guess they all are smart contract based, but light clients also can verify the proofs before the settlement smart contract executes them.

evan-forbes · 2023-07-28T09:17:28Z

docs/fraud-proofs.md

+## Unavailable data fraud proof
+
+By construction, the rollup block data is the sequence of spans defined in the header. Thus, proving that the data is unavailable goes back to proving that the sequence of spans doesn't belong to the Celestia block, i.e. the span is out of bounds.
+
+We could prove that via creating a binary [Merkle proof](https://github.com/celestiaorg/celestia-core/blob/c3ab251659f6fe0f36d10e0dbd14c29a78a85352/crypto/merkle/proof.go#L19-L31) of any row/column to the Celestia data root. This proof will provide the `Total` which is the number of rows/columns in the extended data square. And, we can use that to calculate the square size.
+
+Then, we will use that information to check if the provided transaction index, in the header, is out of the square size bounds.
+
+For the data root, we will use a binary Merkle proof to prove its inclusion in a data root tuple root that was committed to by the QGB smart contract. More on this in [here](#1-data-root-inclusion-proof).


this is important info! but I'm not sure making it its own type of fraud proof is our best option. Or imo we pick a different name for the proof.

The main reasoning I'm seeing not to is because we want fraud proofs to be as normal as possible. The only thing that changes here is if an error is thrown when checking for inclusion, then we know that the data was not posted to celestia. This is essentially all we need to communicate, that there is an edge case where the location in the header doesn't exist, in which case no further action is required to verify the normal fraud proof.

This is just providing a distinction of the type of frauds that can happen from the QGB/Celestia perspective so that rollups can incorporate them in their proofs.

What do you think about switching the titles:
## Unavailable data fraud proof => ## Proving unavailable data?

evan-forbes · 2023-07-28T09:18:53Z

docs/fraud-proofs.md

+> [!NOTE]  
+> The sequence of spans can be defined using the following: `Height`, `start index`, and `length` in the Celestia block, in the case of a single Celestia block. However, it could be generalized to span over multiple blocks.
+
+For the rest of the document, we will suppose that the sequence of spans only references one Celestia block.


sequence of spans

sequence of data?

something like this: https://github.com/celestiaorg/quantum-gravity-bridge/blob/28ffbdd1f20798b410ee2d3a213e70df8edfebd3/src/lib/verifier/test/RollupFraudProof.t.sol#L22-L35

docs/fraud-proofs.md

evan-forbes · 2023-07-28T09:19:52Z

docs/fraud-proofs.md

+Rollups can adopt many approaches to prove that fraud happened. One of which could be having the following fields in the rollup header:
+
+- Rollup block state root
+- A sequence of spans in Celestia: which references where the rollup data was published in the Celestia chain.


A sequence of spans

what is a span?

something like this: https://github.com/celestiaorg/quantum-gravity-bridge/blob/28ffbdd1f20798b410ee2d3a213e70df8edfebd3/src/lib/verifier/test/RollupFraudProof.t.sol#L22-L35

evan-forbes · 2023-07-28T09:31:37Z

docs/fraud-proofs.md

+### 1. Data root inclusion proof
+
+To prove the data root is committed to by the QGB smart contract, we will need to provide a Merkle proof of the data root tuple to a data root tuple root. This can be created using the [`data_root_inclusion_proof`](https://github.com/celestiaorg/celestia-core/blob/c3ab251659f6fe0f36d10e0dbd14c29a78a85352/rpc/client/http/http.go#L492-L511) query.
+
+### 2. Transaction inclusion proof
+
+To prove that a rollup transaction is part of the data root, we will need to provide two proofs: a namespace Merkle proof of the transaction to a row root. This could be done via proving the shares that contain the transaction to the row root using a namespace Merkle proof. And, a binary Merkle proof of the row root to the data root.
+
+These proofs can be generated using the [`ProveShares`](https://github.com/celestiaorg/celestia-core/blob/c3ab251659f6fe0f36d10e0dbd14c29a78a85352/rpc/client/http/http.go#L526-L543) query.
+
+### 3. Transaction part of the rollup sequence
+
+The Celestia block is a 2d matrix of rows and columns, where the row roots and column roots are committed to in the data root. We can use this property to point which rows and columns does the transaction shares belong to. Then, we will use those coordinates to calculate the row major index of the transaction, and verify if it is part of the sequence span.
+
+The coordinates can be gotten using a namespace Merkle proof of the shares to the row root, and also to the column root. Then, we will create Merkle proofs of that row root and column root to the data root. These [proofs](https://github.com/celestiaorg/celestia-core/blob/c3ab251659f6fe0f36d10e0dbd14c29a78a85352/crypto/merkle/proof.go#L19-L31) will contain the [`Index`](https://github.com/celestiaorg/celestia-core/blob/c3ab251659f6fe0f36d10e0dbd14c29a78a85352/crypto/merkle/proof.go#L28) of the row/column, and the [`Total`](https://github.com/celestiaorg/celestia-core/blob/c3ab251659f6fe0f36d10e0dbd14c29a78a85352/crypto/merkle/proof.go#L27) number of rows/columns in the proofs which would allow us to calculate the row major index of the transaction.


I'm not sure this is the best spot for this or if the user needs to know these things when thinking about fraud proofs.

mostly, we just need to communicate what can possibly occur when using the fraud proofs. Either the inclusion proof is valid or invalid, and if its invalid what are the reasons for it being invalid (the portion about the data not being posted to the square).

I think this document is generally not making a clear enough distinction between what the qgb contracts are doing, which is just inclusion proofs, not really fraud proofs.

Fraud proofs are important, but I think keeping those more separate is good.

this part was removed and a different explanation is provided

evan-forbes · 2023-07-28T09:32:45Z

docs/fraud-proofs.md

+> [!NOTE]  
+> The sequence of spans can be defined using the following: `Height`, `start index`, and `length` in the Celestia block, in the case of a single Celestia block. However, it could be generalized to span over multiple blocks.
+
+For the rest of the document, we will suppose that the sequence of spans only references one Celestia block.


what occurs when the celestium needs to prove inclusion to multiple chunks of data?

That depends on how they want to separate their data. Generally, they would have multiple references to data in Celestia blocks and they would prove inclusion to one of them

rach-id · 2023-07-28T09:44:20Z

@evan-forbes This is just the first part of the documentation that gives a general overview of how the fraud proofs for QGB work. I am working on an example rollup, in a test, where I will use real Celestia blocks, and create each type of fraud proofs + write comments explaining each step. This will be in a subsequent PR

Co-authored-by: Evan Forbes <[email protected]>

src/lib/verifier/DAVerifier.sol

docs/fraud-proofs.md

Co-authored-by: John Adler <[email protected]>

rach-id · 2023-09-18T15:22:28Z

CI will be fixed in here: #197

## Overview  closes #193 The test that fails if this fix is absent is in here: #160 ## Checklist  - [ ] New and updated code has appropriate documentation - [ ] New and updated code has new and/or updated testing - [ ] Required CI checks are passing - [ ] Visual proof for any user facing features like CLI or documentation updates - [ ] Linked issues closed with keywords

rach-id · 2023-09-25T11:36:15Z

Merging, if there are any hanging questions or fixes, we can create separate issues for them.

Thanks a lot guys for the reviews 👍 👍

docs: add fraud proofs documentation

583d0ba

rach-id added the documentation Improvements or additions to documentation label Jul 26, 2023

rach-id requested review from adlerjohn and evan-forbes July 26, 2023 13:33

rach-id self-assigned this Jul 26, 2023

chore: fix links

d18e7f1

adlerjohn reviewed Jul 28, 2023

View reviewed changes

rach-id and others added 10 commits July 28, 2023 10:23

Update docs/fraud-proofs.md

98146f9

Co-authored-by: John Adler <[email protected]>

Update docs/fraud-proofs.md

db8cebc

Co-authored-by: John Adler <[email protected]>

Update docs/fraud-proofs.md

0bb7331

Co-authored-by: John Adler <[email protected]>

Update docs/fraud-proofs.md

deb892d

Co-authored-by: John Adler <[email protected]>

Update docs/fraud-proofs.md

9613782

Co-authored-by: John Adler <[email protected]>

Update docs/fraud-proofs.md

4cd1b15

Co-authored-by: John Adler <[email protected]>

Update docs/fraud-proofs.md

143a8ed

Co-authored-by: John Adler <[email protected]>

Update docs/fraud-proofs.md

a1f1f93

Co-authored-by: John Adler <[email protected]>

Update docs/fraud-proofs.md

a744e5f

Co-authored-by: John Adler <[email protected]>

Merge branch 'master' into fraud_proofs_docs

a162e36

rach-id requested a review from adlerjohn July 28, 2023 08:26

evan-forbes reviewed Jul 28, 2023

View reviewed changes

rach-id added 2 commits September 11, 2023 12:24

Merge branch 'master' into fraud_proofs_docs

1532c35

feat: add rollup fraud proof test

d8afca4

rach-id linked an issue Sep 12, 2023 that may be closed by this pull request

Invalid row root namespace node when verifying proofs #193

Closed

rach-id and others added 4 commits September 12, 2023 17:51

Update docs/fraud-proofs.md

318f355

Co-authored-by: Evan Forbes <[email protected]>

Update docs/fraud-proofs.md

7087ccf

Co-authored-by: Evan Forbes <[email protected]>

Update docs/fraud-proofs.md

2376626

Co-authored-by: Evan Forbes <[email protected]>

Update docs/fraud-proofs.md

28ffbdd

Co-authored-by: Evan Forbes <[email protected]>

rach-id marked this pull request as draft September 12, 2023 18:33

rach-id commented Sep 13, 2023

View reviewed changes

src/lib/verifier/DAVerifier.sol Outdated Show resolved Hide resolved

feat: add share inside spans sequence verification

cdcdf90

rach-id added 2 commits September 13, 2023 13:52

feat: better details on position of the share in the matrix

4fcd55e

chore: fmt

4c0a688

rach-id marked this pull request as ready for review September 13, 2023 12:59

rach-id requested a review from evan-forbes September 13, 2023 12:59

rach-id changed the title ~~docs: add fraud proofs documentation~~ docs: add inclusion proofs documentation Sep 13, 2023

adlerjohn reviewed Sep 15, 2023

View reviewed changes

rach-id and others added 13 commits September 16, 2023 10:35

Update docs/fraud-proofs.md

28b05c1

Co-authored-by: John Adler <[email protected]>

Update docs/fraud-proofs.md

feeba92

Co-authored-by: John Adler <[email protected]>

Update docs/fraud-proofs.md

40ac2b4

Co-authored-by: John Adler <[email protected]>

Update docs/fraud-proofs.md

eafab55

Co-authored-by: John Adler <[email protected]>

Update docs/fraud-proofs.md

079a7a2

Co-authored-by: John Adler <[email protected]>

Update docs/fraud-proofs.md

b60d942

Co-authored-by: John Adler <[email protected]>

Update docs/fraud-proofs.md

a2c7e43

Co-authored-by: John Adler <[email protected]>

Update docs/fraud-proofs.md

eaca8b1

Co-authored-by: John Adler <[email protected]>

Update docs/fraud-proofs.md

ea4ae1f

Co-authored-by: John Adler <[email protected]>

Update docs/fraud-proofs.md

820280c

Co-authored-by: John Adler <[email protected]>

Update docs/fraud-proofs.md

5e615eb

Co-authored-by: John Adler <[email protected]>

Update docs/fraud-proofs.md

68b1a02

Co-authored-by: John Adler <[email protected]>

Update docs/fraud-proofs.md

0a32cf9

Co-authored-by: John Adler <[email protected]>

rach-id mentioned this pull request Sep 18, 2023

fix: fix da verifier row root node creation #197

Merged

5 tasks

chore: revert da verifier fix

630e9d8

Merge branch 'master' into fraud_proofs_docs

e059edc

chore: lint

1caee0c

rach-id requested a review from adlerjohn September 22, 2023 20:17

adlerjohn approved these changes Sep 22, 2023

View reviewed changes

rach-id merged commit 22b310c into master Sep 25, 2023

rach-id deleted the fraud_proofs_docs branch September 25, 2023 11:36

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

docs: add inclusion proofs documentation #160

docs: add inclusion proofs documentation #160

rach-id commented Jul 26, 2023 •

edited

Loading

evan-forbes left a comment •

edited

Loading

evan-forbes Jul 28, 2023

rach-id Sep 12, 2023

evan-forbes Jul 28, 2023

rach-id Sep 12, 2023

evan-forbes Jul 28, 2023

rach-id Sep 12, 2023

evan-forbes Jul 28, 2023

rach-id Sep 12, 2023

evan-forbes Jul 28, 2023

rach-id Sep 13, 2023

evan-forbes Jul 28, 2023

rach-id Jul 28, 2023

rach-id commented Jul 28, 2023 •

edited

Loading

rach-id commented Sep 18, 2023

rach-id commented Sep 25, 2023

		Fraud proofs is the mechanism used to inform light clients in the case of an invalid rollup state transition or unavailable rollup block data. They rely on rollup full nodes getting the data that was published to Celestia, and executing all the state transitions to verify the rollup state. If they discover an invalid state transition or unavailable rollup data, they emit a fraud proof with the necessary information to convince light clients that fraud happened. This allows for trust-minimized light clients, as the network only needs one honest full node to create the fraud proof and propagate it.

		If the Celestium is settlement smart contract based, then the contract would only need to receive a fraud proof to decide whether data was published correctly or not.

docs: add inclusion proofs documentation #160

docs: add inclusion proofs documentation #160

Conversation

rach-id commented Jul 26, 2023 • edited Loading

Overview

Checklist

evan-forbes left a comment • edited Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

rach-id commented Jul 28, 2023 • edited Loading

rach-id commented Sep 18, 2023

rach-id commented Sep 25, 2023

rach-id commented Jul 26, 2023 •

edited

Loading

evan-forbes left a comment •

edited

Loading

rach-id commented Jul 28, 2023 •

edited

Loading