Merge remote-tracking branch 'origin/broader_scope_docs' into broader…

…_scope_docs

x/qgb/overview.md

@@ -1,20 +1,20 @@
 # Overview
 
-The Quantum Gravity Bridge (QGB) is a one way bridge from Celestia to EVM chains. It provides a way for rollups using Celestia for DA, and an EVM chain as a settlment 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 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 settlment 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).
 
 ## [State machine](https://github.com/celestiaorg/celestia-app/tree/main/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) and then submitted to the QGB smart contract, deployed to some EVM chain, using [relayers](https://github.com/celestiaorg/orchestrator-relayer/blob/main/docs/relayer.md).
+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.
 
 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).
 
-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 attestations submissions.
+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)
 
-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 allows tracking of the validator set changes inside the QGB smart contract and for verification of the signatures.
+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 is [generated](https://github.com/celestiaorg/celestia-app/blob/34d725993a3b2c7cbbf6e62c83bbfd90ad94657e/x/qgb/abci.go#L84-L135) 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 validator set have submitted their signatures, it is relayed 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).
 
@@ -24,49 +24,49 @@ The QGB smart contract keeps track of the [last validator set hash](https://gith
 
 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).
 
-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/a1b07a1e6c77595466da9c61b37c83b4769b47e7/rpc/core/blocks.go#L529), the [height](https://github.com/celestiaorg/celestia-core/blob/a1b07a1e6c77595466da9c61b37c83b4769b47e7/rpc/core/blocks.go#L528) and the [square size](https://github.com/celestiaorg/celestia-core/blob/a1b07a1e6c77595466da9c61b37c83b4769b47e7/rpc/core/blocks.go#L530). This commitment can be queried from core using the [`DataCommitment`](https://github.com/celestiaorg/celestia-core/blob/a1b07a1e6c77595466da9c61b37c83b4769b47e7/rpc/core/blocks.go#L177C1-L194) query and allows generating merkle inclusion proofs for any blob in any block in the set.
+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/a1b07a1e6c77595466da9c61b37c83b4769b47e7/rpc/core/blocks.go#L529), the [height](https://github.com/celestiaorg/celestia-core/blob/a1b07a1e6c77595466da9c61b37c83b4769b47e7/rpc/core/blocks.go#L528) and the [square size](https://github.com/celestiaorg/celestia-core/blob/a1b07a1e6c77595466da9c61b37c83b4769b47e7/rpc/core/blocks.go#L530). This commitment can be queried from core using the [`DataCommitment`](https://github.com/celestiaorg/celestia-core/blob/a1b07a1e6c77595466da9c61b37c83b4769b47e7/rpc/core/blocks.go#L177C1-L194) query and allows generating Merkle inclusion proofs for any blob in any block in the set.
 
 When an orchestrator sees a newly generated data commitment, it queries the previous valset and checks whether it's part of its validator set. Then, the orchestrator signs the new data commitment and submits that signature to the [QGB P2P network](https://github.com/celestiaorg/orchestrator-relayer/pull/66). Otherwise, it ignores it and waits for new attestations.
 
-After the relayer finds more than 2/3rd signatures of that data commitment, it relays the commitment along with the signatures to the QGB smart contract where they get [verified](https://github.com/celestiaorg/quantum-gravity-bridge/blob/3cef3f5dfd37c3086fa40a6324f144595726dc16/src/QuantumGravityBridge.sol#L172-L211). Then, the smart contract [saves](https://github.com/celestiaorg/quantum-gravity-bridge/blob/3cef3f5dfd37c3086fa40a6324f144595726dc16/src/QuantumGravityBridge.sol#L331-L332) the commitment to the [state](https://github.com/celestiaorg/quantum-gravity-bridge/blob/3cef3f5dfd37c3086fa40a6324f144595726dc16/src/QuantumGravityBridge.sol#L50-L51) thus allowing for merkle-based inclusion proof verification for any blob posted to any committed block.
+After the relayer finds more than 2/3rd signatures of that data commitment, it relays the commitment along with the signatures to the QGB smart contract where they get [verified](https://github.com/celestiaorg/quantum-gravity-bridge/blob/3cef3f5dfd37c3086fa40a6324f144595726dc16/src/QuantumGravityBridge.sol#L172-L211). Then, the smart contract [saves](https://github.com/celestiaorg/quantum-gravity-bridge/blob/3cef3f5dfd37c3086fa40a6324f144595726dc16/src/QuantumGravityBridge.sol#L331-L332) the commitment to the [state](https://github.com/celestiaorg/quantum-gravity-bridge/blob/3cef3f5dfd37c3086fa40a6324f144595726dc16/src/QuantumGravityBridge.sol#L50-L51) thus allowing for Merkle-based inclusion proof verification for any blob posted to any committed block.
 
 ## [Orchestrator-relayer](https://github.com/celestiaorg/orchestrator-relayer)
 
 The [orchestrator-relayer](https://github.com/celestiaorg/orchestrator-relayer) contains the implementation of the QGB orchestrator and relayer.
 
 ### [Orchestrator](https://github.com/celestiaorg/orchestrator-relayer/blob/main/docs/orchestrator.md)
 
-An [orchestrator](https://github.com/celestiaorg/orchestrator-relayer/blob/main/docs/orchestrator.md) is the software responsible for querying the state machine for new attestations, as described above, sign them, and then submit them to the QGB P2P network.
+An [orchestrator](https://github.com/celestiaorg/orchestrator-relayer/blob/main/docs/orchestrator.md) is the software responsible for querying the state machine for new attestations, signs them, and then submits them to the QGB P2P network.
 
 At startup, it [loads](https://github.com/celestiaorg/orchestrator-relayer/blob/main/docs/orchestrator.md#evm-key) the EVM private key corresponding to the address used when creating the validator. Then, it uses it to sign the attestations digests before submitting them to the P2P network.
 
-An attestation digest is a bytes array containing a digest of the attestation relevant information. More on this in the [hashes formats](#hashes-format) section.
+An attestation digest is a bytes array containing a digest of the attestation relevant information. More on this in the [hashes format](#hashes-format) section.
 
 The orchestrator generally needs access to the validator's RPC/gRPC endpoints. However, it still can use public ones if needed. Its only hard requirement is having access to the specific private key for the target validator. Otherwise, the signatures will be invalid and the validator could get slashed in future versions.
 
-### [Relayer](https://github.com/celestiaorg/orchestrator-relayer/blob/main/docs/orchestrator.md)
+### [Relayer](https://github.com/celestiaorg/orchestrator-relayer/blob/main/docs/relayer.md)
 
-A [relayer](https://github.com/celestiaorg/orchestrator-relayer/blob/main/docs/orchestrator.md) is the software responsible for querying the signatures of a validator set from the P2P network and aggregate them into a format that the [QGB smart contract](https://github.com/celestiaorg/quantum-gravity-bridge/blob/3cef3f5dfd37c3086fa40a6324f144595726dc16/src/QuantumGravityBridge.sol) understands.
+A [relayer](https://github.com/celestiaorg/orchestrator-relayer/blob/main/docs/relayer.md) is the software responsible for querying the signatures of a validator set from the P2P network and aggregating them into a format that the [QGB smart contract](https://github.com/celestiaorg/quantum-gravity-bridge/blob/3cef3f5dfd37c3086fa40a6324f144595726dc16/src/QuantumGravityBridge.sol) understands.
 
 It uses the previous valset to that attestation to know which validators should sign. Then, it looks for all of those signatures.
 
 When the relayer finds more than 2/3rds of the signatures, it immediately relays them to the QGB smart contract to be persisted, and starts again.
 
-For a [QGB smart contract](https://github.com/celestiaorg/quantum-gravity-bridge/blob/3cef3f5dfd37c3086fa40a6324f144595726dc16/src/QuantumGravityBridge.sol) not to halt, it needs at least one relayer relaying signatures to it regularly. Otherwise, the QGB contract will be out of sync and will not be able to commit to new data.
+For a [QGB smart contract](https://github.com/celestiaorg/quantum-gravity-bridge/blob/3cef3f5dfd37c3086fa40a6324f144595726dc16/src/QuantumGravityBridge.sol) to not halt, it needs at least one relayer relaying signatures to it regularly. Otherwise, the QGB contract will be out of sync and will not be able to commit to new data.
 
 ## [QGB smart contract](https://github.com/celestiaorg/quantum-gravity-bridge)
 
 The [QGB smart contract](https://github.com/celestiaorg/quantum-gravity-bridge/blob/3cef3f5dfd37c3086fa40a6324f144595726dc16/src/QuantumGravityBridge.sol) is the source of truth for Celestiums. It allows proving/verifying that data was posted to the Celestia blockchain.
 
-In order to reflect the Celestia chain data, the [QGB smart contract](https://github.com/celestiaorg/quantum-gravity-bridge/blob/3cef3f5dfd37c3086fa40a6324f144595726dc16/src/QuantumGravityBridge.sol) keeps track of the validator set changes, via valset updates, and commits to batches of blocks information, via data commitments.
+In order to reflect the Celestia chain data, the [QGB smart contract](https://github.com/celestiaorg/quantum-gravity-bridge/blob/3cef3f5dfd37c3086fa40a6324f144595726dc16/src/QuantumGravityBridge.sol) keeps track of the validator set changes, via valset updates, and commits to batches of block information, via data commitments.
 
 ### Validator set changes
 
 In order to submit a validator set change, the QGB smart contract provides the [`updateValidatorSet()`](https://github.com/celestiaorg/quantum-gravity-bridge/blob/3cef3f5dfd37c3086fa40a6324f144595726dc16/src/QuantumGravityBridge.sol#L213-L273) `external` method that takes the previous valset nonce, the new one's nonce, its power threshold and its hash, along with the actual validator set and the corresponding signatures, as `calldata` to be verified. Then, it [persists](https://github.com/celestiaorg/quantum-gravity-bridge/blob/3cef3f5dfd37c3086fa40a6324f144595726dc16/src/QuantumGravityBridge.sol#L266-L268) the nonce, the valset hash and the threshold in state so they can be used for future valset and data commitment updates.
 
 ### Batches
 
-The batches in the QGB smart contract refer to the `data root tuple root`s described above. These are submitted using the [`submitDataRootTupleRoot()`](https://github.com/celestiaorg/quantum-gravity-bridge/blob/3cef3f5dfd37c3086fa40a6324f144595726dc16/src/QuantumGravityBridge.sol#L275-L337) `external` method. This latter takes the new batch nonce, its corresponding valset, the `data root tuple root`, along with the actual validator set and their corresponding signatures as `calldata`. Then, it verifies the signature and [persists](https://github.com/celestiaorg/quantum-gravity-bridge/blob/3cef3f5dfd37c3086fa40a6324f144595726dc16/src/QuantumGravityBridge.sol#L331-L332) the new `data root tuple root` to the state along with the new nonce.
+The batches in the QGB smart contract refer to the `data root tuple root`s described above. These are submitted using the [`submitDataRootTupleRoot()`](https://github.com/celestiaorg/quantum-gravity-bridge/blob/3cef3f5dfd37c3086fa40a6324f144595726dc16/src/QuantumGravityBridge.sol#L275-L337) `external` method. This latter takes the new batch nonce, its corresponding valset, the `data root tuple root`, along with the actual validator set and their corresponding signatures as `calldata`. Then, it verifies the signature and [persists](https://github.com/celestiaorg/quantum-gravity-bridge/blob/3cef3f5dfd37c3086fa40a6324f144595726dc16/src/QuantumGravityBridge.sol#L331-L332) the new data root tuple root to the state along with the new nonce.
 
 ### Hashes format
 
@@ -91,7 +91,7 @@ A data commitment digest is created inside the [`domainSeparateDataRootTupleRoot
 
 ### Signatures
 
-The signature scheme used for signing the above hashes follow the [EIP-191](https://eips.ethereum.org/EIPS/eip-191) signing standard. It uses the `ECDSA` algorithm with the `secp256k1` curve. So, the orchestrator uses the keystore to [generate]((https://github.com/celestiaorg/orchestrator-relayer/blob/09ebfdc312c0d9e08856fb98cfd089e956ab7f3a/evm/ethereum_signature.go#L18-L28)) these signatures.
+The signature scheme used for signing the above hashes follow the [EIP-191](https://eips.ethereum.org/EIPS/eip-191) signing standard. It uses the `ECDSA` algorithm with the `secp256k1` curve. So, the orchestrator uses the keystore to [generate](https://github.com/celestiaorg/orchestrator-relayer/blob/09ebfdc312c0d9e08856fb98cfd089e956ab7f3a/evm/ethereum_signature.go#L18-L28) these signatures.
 
 The output signature is in the `[R || S || V]` format where `V` is `0` or `1`. This is defined in the QGB smart contract using the [Signature](https://github.com/celestiaorg/quantum-gravity-bridge/blob/3cef3f5dfd37c3086fa40a6324f144595726dc16/src/QuantumGravityBridge.sol#L17-L21) struct.