Skip to content

Commit

Permalink
docs: use QGB permalinks to appease markdown link check (#2750)
Browse files Browse the repository at this point in the history
Part of #2749 

Note: we've discussed avoiding backporting docs changes so we can close
this PR if we're okay with markdown link check failing on the v1.x
branch from now on.

## Testing

On the v1.x branch, locally `make markdown-link-check` passes
  • Loading branch information
rootulp authored Nov 6, 2023
1 parent 98d0550 commit 9cae513
Show file tree
Hide file tree
Showing 2 changed files with 10 additions and 10 deletions.
2 changes: 1 addition & 1 deletion x/qgb/README.md
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
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

0 comments on commit 9cae513

Please sign in to comment.