Skip to content
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.

Sign up for GitHub

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

docs: use QGB permalinks to appease markdown link check #2750

Merged
merged 2 commits into from
Nov 6, 2023
Merged

docs: use QGB permalinks to appease markdown link check #2750

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
447e267
docs: use QGB permalinks to appease markdown link check
rootulp Oct 23, 2023
42f8503
Merge branch 'v1.x' into rp/fix-qgb-links
rootulp Oct 29, 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
2 changes: 1 addition & 1 deletion x/qgb/README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -8,7 +8,7 @@ The QGB state machine is responsible for creating attestations which are signed

### Attestations types

[Attestations](https://github.com/celestiaorg/celestia-app/blob/main/x/qgb/types/attestation.go#L10-L18) are requests for signatures generated by the state machine during the `EndBlock` phase. They facilitate alignment between orchestrators and relayers on which data to sign, and when to relay it.
[Attestations](https://github.com/celestiaorg/celestia-app/blob/74d47e13458d332cd8a0c7485e3dc88017b97e23/x/qgb/types/attestation.go#L10-L18) are requests for signatures generated by the state machine during the `EndBlock` phase. They facilitate alignment between orchestrators and relayers on which data to sign, and when to relay it.

There are two types of attestations, [valsets](https://github.com/celestiaorg/celestia-app/blob/376a1d4c0f321f12ba78279d2bd34fc6cb5e6dc2/proto/celestia/qgb/v1/types.proto#L18-L33) and [data commitments](https://github.com/celestiaorg/celestia-app/blob/376a1d4c0f321f12ba78279d2bd34fc6cb5e6dc2/proto/celestia/qgb/v1/types.proto#L35-L55).

Expand Down
18 changes: 9 additions & 9 deletions x/qgb/overview.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -2,27 +2,27 @@

The Quantum Gravity Bridge (QGB) is a one way bridge from Celestia to EVM chains. It provides a way for rollups using Celestia for Data Availability (DA), and an EVM chain as a settlement layer, to prove on-chain that the rollup data was correctly posted to Celestia and verify fraud proofs otherwise. These types of rollups are called Celestiums and are discussed in the [Quantum Gravity Bridge: Secure Off-Chain Data Availability for Ethereum L2s with Celestia](https://blog.celestia.org/celestiums) blog post.

The QGB implementation consists of three components: The [state machine](https://github.com/celestiaorg/celestia-app/tree/main/x/qgb), the [orchestrator-relayer](https://github.com/celestiaorg/orchestrator-relayer), and the [QGB smart contract](https://github.com/celestiaorg/quantum-gravity-bridge).
The QGB implementation consists of three components: The [state machine](https://github.com/celestiaorg/celestia-app/tree/74d47e13458d332cd8a0c7485e3dc88017b97e23/x/qgb), the [orchestrator-relayer](https://github.com/celestiaorg/orchestrator-relayer), and the [QGB smart contract](https://github.com/celestiaorg/quantum-gravity-bridge).

## [State machine](https://github.com/celestiaorg/celestia-app/tree/main/x/qgb)
## [State machine](https://github.com/celestiaorg/celestia-app/tree/74d47e13458d332cd8a0c7485e3dc88017b97e23/x/qgb)

The state machine is the `qgb` module implementation. It is responsible for creating [attestations](https://github.com/celestiaorg/celestia-app/blob/main/x/qgb/types/attestation.go#L10-L18) which are signed by [orchestrators](https://github.com/celestiaorg/orchestrator-relayer/blob/main/docs/orchestrator.md). Each Celestia validator is expected to also run an orchestrator. [Relayers](https://github.com/celestiaorg/orchestrator-relayer/blob/main/docs/relayer.md) periodically query the Celestia state for attestations and submit them to the QGB smart contract deployed on some EVM chain.
The state machine is the `qgb` module implementation. It is responsible for creating [attestations](https://github.com/celestiaorg/celestia-app/blob/74d47e13458d332cd8a0c7485e3dc88017b97e23/x/qgb/types/attestation.go#L10-L18) which are signed by [orchestrators](https://github.com/celestiaorg/orchestrator-relayer/blob/main/docs/orchestrator.md). Each Celestia validator is expected to also run an orchestrator. [Relayers](https://github.com/celestiaorg/orchestrator-relayer/blob/main/docs/relayer.md) periodically query the Celestia state for attestations and submit them to the QGB smart contract deployed on some EVM chain.

There are two types of [attestations](https://github.com/celestiaorg/celestia-app/blob/main/x/qgb/types/attestation.go#L10-L18): [valsets](https://github.com/celestiaorg/celestia-app/blob/376a1d4c0f321f12ba78279d2bd34fc6cb5e6dc2/proto/celestia/qgb/v1/types.proto#L18-L33) and [data commitments](https://github.com/celestiaorg/celestia-app/blob/376a1d4c0f321f12ba78279d2bd34fc6cb5e6dc2/proto/celestia/qgb/v1/types.proto#L35-L55).
There are two types of [attestations](https://github.com/celestiaorg/celestia-app/blob/74d47e13458d332cd8a0c7485e3dc88017b97e23/x/qgb/types/attestation.go#L10-L18): [valsets](https://github.com/celestiaorg/celestia-app/blob/376a1d4c0f321f12ba78279d2bd34fc6cb5e6dc2/proto/celestia/qgb/v1/types.proto#L18-L33) and [data commitments](https://github.com/celestiaorg/celestia-app/blob/376a1d4c0f321f12ba78279d2bd34fc6cb5e6dc2/proto/celestia/qgb/v1/types.proto#L35-L55).

All attestations have a [`nonce`](https://github.com/celestiaorg/celestia-app/blob/8ae6a84b2c99e55625bbe99f70db1e5a985c9675/x/qgb/types/attestation.go#L16) field that defines the order in which the attestations are generated. This nonce is stored in the QGB smart contract as per [ADR-004](https://github.com/celestiaorg/celestia-app/blob/main/docs/architecture/adr-004-qgb-relayer-security.md#decision), and is used to order attestation submissions on the EVM chain.

### [Valsets](https://github.com/celestiaorg/celestia-app/tree/main/x/qgb#valsets)
### [Valsets](https://github.com/celestiaorg/celestia-app/blob/74d47e13458d332cd8a0c7485e3dc88017b97e23/x/qgb/README.md?plain=1#L15)

A [valset](https://github.com/celestiaorg/celestia-app/tree/main/x/qgb#valsets) represents a validator set snapshot. It contains a list of validators' EVM addresses along with their [QGB staking power](https://github.com/celestiaorg/celestia-app/tree/main/x/qgb#validator-power-normalization). It enables the QGB smart contract to track the state of the Celestia validator set. This is necessary so that the QGB smart contract can determine when a 2/3 threshold has signed that a particular data hash has been made available on Celestia.
A [valset](https://github.com/celestiaorg/celestia-app/blob/74d47e13458d332cd8a0c7485e3dc88017b97e23/x/qgb/README.md?plain=1#L15) represents a validator set snapshot. It contains a list of validators' EVM addresses along with their [QGB staking power](https://github.com/celestiaorg/celestia-app/blob/74d47e13458d332cd8a0c7485e3dc88017b97e23/x/qgb/README.md?plain=1#L59). It enables the QGB smart contract to track the state of the Celestia validator set. This is necessary so that the QGB smart contract can determine when a 2/3 threshold has signed that a particular data hash has been made available on Celestia.

A valset is [generated](https://github.com/celestiaorg/celestia-app/tree/main/x/qgb#valset-handler) inside the state machine. It is then queried, signed, and submitted to the [QGB P2P network](https://github.com/celestiaorg/orchestrator-relayer/pull/66) by orchestrators. After more than 2/3rds of the Celestia validator set have submitted their signatures, [relayers](https://github.com/celestiaorg/orchestrator-relayer/blob/main/docs/relayer.md) relay the attestation to the QGB smart contract along with the signatures to be [verified](https://github.com/celestiaorg/quantum-gravity-bridge/blob/3cef3f5dfd37c3086fa40a6324f144595726dc16/src/QuantumGravityBridge.sol#L172-L211) and eventually [stored](https://github.com/celestiaorg/quantum-gravity-bridge/blob/3cef3f5dfd37c3086fa40a6324f144595726dc16/src/QuantumGravityBridge.sol#L266-L268).
A valset is [generated](https://github.com/celestiaorg/celestia-app/blob/74d47e13458d332cd8a0c7485e3dc88017b97e23/x/qgb/README.md?plain=1#L189) inside the state machine. It is then queried, signed, and submitted to the [QGB P2P network](https://github.com/celestiaorg/orchestrator-relayer/pull/66) by orchestrators. After more than 2/3rds of the Celestia validator set have submitted their signatures, [relayers](https://github.com/celestiaorg/orchestrator-relayer/blob/main/docs/relayer.md) relay the attestation to the QGB smart contract along with the signatures to be [verified](https://github.com/celestiaorg/quantum-gravity-bridge/blob/3cef3f5dfd37c3086fa40a6324f144595726dc16/src/QuantumGravityBridge.sol#L172-L211) and eventually [stored](https://github.com/celestiaorg/quantum-gravity-bridge/blob/3cef3f5dfd37c3086fa40a6324f144595726dc16/src/QuantumGravityBridge.sol#L266-L268).

The QGB smart contract keeps track of the [last validator set hash](https://github.com/celestiaorg/quantum-gravity-bridge/blob/3cef3f5dfd37c3086fa40a6324f144595726dc16/src/QuantumGravityBridge.sol#L44-L45) and its corresponding [power threshold](https://github.com/celestiaorg/quantum-gravity-bridge/blob/3cef3f5dfd37c3086fa40a6324f144595726dc16/src/QuantumGravityBridge.sol#L46-L47). This way, the contract will always be able to verify if attestations were signed using the correct Celestia validator set, and if the provided signatures represent a majority.

### [Data commitments](https://github.com/celestiaorg/celestia-app/tree/main/x/qgb#data-commitments)
### [Data commitments](https://github.com/celestiaorg/celestia-app/blob/74d47e13458d332cd8a0c7485e3dc88017b97e23/x/qgb/README.md?plain=1#L73)

A [data commitment](https://github.com/celestiaorg/celestia-app/tree/main/x/qgb#data-commitments) is an attestation type representing a request to commit over a set of blocks. It provides an end exclusive range of blocks for orchestrators to sign over and propagate in the QGB P2P network. The range is defined by the param [`DataCommitmentWindow`](https://github.com/celestiaorg/celestia-app/blob/fc83b04c3a5638ac8d415770e38a4046b84fa128/x/qgb/keeper/keeper_data_commitment.go#L44-L50).
A [data commitment](https://github.com/celestiaorg/celestia-app/blob/74d47e13458d332cd8a0c7485e3dc88017b97e23/x/qgb/README.md?plain=1#L73) is an attestation type representing a request to commit over a set of blocks. It provides an end exclusive range of blocks for orchestrators to sign over and propagate in the QGB P2P network. The range is defined by the param [`DataCommitmentWindow`](https://github.com/celestiaorg/celestia-app/blob/fc83b04c3a5638ac8d415770e38a4046b84fa128/x/qgb/keeper/keeper_data_commitment.go#L44-L50).

The data commitment is a Merkle tree over a sequential set of blocks. These blocks are represented as a tuple of the [data root](https://github.com/celestiaorg/celestia-core/blob/6933af1ead0ddf4a8c7516690e3674c6cdfa7bd8/rpc/core/blocks.go#L549), and the [height](https://github.com/celestiaorg/celestia-core/blob/6933af1ead0ddf4a8c7516690e3674c6cdfa7bd8/rpc/core/blocks.go#L548). This commitment can be queried from core using the [`DataCommitment`](https://github.com/celestiaorg/celestia-core/blob/6933af1ead0ddf4a8c7516690e3674c6cdfa7bd8/rpc/core/blocks.go#L210-L227) query and allows generating Merkle inclusion proofs for any blob in any block in the set.

Expand Down
Loading