Skip to content

Commit

Permalink
docs: Rectify typographical inaccuracies (#3675)
Browse files Browse the repository at this point in the history
This PR addresses several typographical errors across various files in
the project. The changes improve readability and maintain the
professional standard of the documentation and code comments.

Justification
Typographical errors, while minor, can detract from the overall quality
of the project. Correcting these errors ensures clarity and
professionalism, making the project more accessible and understandable
for current and future contributors.

Hope it helps.

---------

Co-authored-by: CHAMI Rachid <[email protected]>
Co-authored-by: nina / ნინა <[email protected]>
  • Loading branch information
3 people authored Jul 13, 2024
1 parent 80517d3 commit 6116a2e
Show file tree
Hide file tree
Showing 4 changed files with 4 additions and 4 deletions.
2 changes: 1 addition & 1 deletion docs/architecture/adr-001-abci++-adoption.md
Original file line number Diff line number Diff line change
Expand Up @@ -127,7 +127,7 @@ func (cs *State) defaultDoPrevote(height int64, round int32) {
cs.Logger.Error("state machine returned an error when trying to process proposal block", "err", err)
}

// Vote nil if application invalidated the block
// Vote nil if the application invalidated the block
if !stateMachineValidBlock {
// Consensus says we must vote nil
logger.Error("prevote step: consensus deems this block to be mustVoteNil", "err", err)
Expand Down
2 changes: 1 addition & 1 deletion docs/architecture/adr-002-qgb-valset.md
Original file line number Diff line number Diff line change
Expand Up @@ -16,7 +16,7 @@ PS: The `ValsetConfirm` have been updated in `adr-005-qgb-reduce-state-usage`. P

## Detailed Design

Since the QGB is only a one-way bridge and is not transferring assets, it doesn't require the portions of the gravity module that recreate the state from the bridged chain. We only need to keep things relating to signing over the validator set (such as`MsgSetOrchestratorAddress` and `MsgValsetConfirm`) and relayer queries (such as `ValsetConfirm` and `GetDelegateKeyByOrchestrator`).
Since the QGB is only a one-way bridge and does not transfer assets, it doesn't require the portions of the gravity module that recreate the state from the bridged chain. We only need to keep things relating to signing over the validator set (such as`MsgSetOrchestratorAddress` and `MsgValsetConfirm`) and relayer queries (such as `ValsetConfirm` and `GetDelegateKeyByOrchestrator`).

It works by relying on a set of signers to attest to some event on Celestia: the Celestia validator set.

Expand Down
2 changes: 1 addition & 1 deletion docs/architecture/adr-006-non-interactive-defaults.md
Original file line number Diff line number Diff line change
Expand Up @@ -242,7 +242,7 @@ func (app *App) PrepareProposal(req abci.RequestPrepareProposal) abci.ResponsePr
// squares but can only return values within the min and max square size.
squareSize, totalSharesUsed := estimateSquareSize(parsedTxs, req.BlockData.Evidence)

// the totalSharesUsed can be larger that the max number of shares if we
// the totalSharesUsed can be larger than the max number of shares if we
// reach the max square size. In this case, we must prune the deprioritized
// txs (and their messages if they're pfb txs).
if totalSharesUsed > int(squareSize*squareSize) {
Expand Down
2 changes: 1 addition & 1 deletion docs/architecture/adr-018-network-upgrades.md
Original file line number Diff line number Diff line change
Expand Up @@ -50,7 +50,7 @@ The height of the the v1 -> v2 upgrade will initially be supplied via CLI flag (
- Upgrading needs to support state migrations. These must happen to all nodes at the same moment between heights. Ideally all migrations that affect state would correspond at the height of the new app version i.e. after `Commit` and before processing of the transactions at that height. `BeginBlock` seems like an ideal area to perform these upgrades however these might affect the way that `PrepareProposal` and `ProcessProposal` is conducted thus they must be performed even prior to these ABCI calls. A simpler implementation would have been for the proposer to immediately propose a block with the next version i.e. v2. However that would require the proposer to first migrate state (taking an unknown length of time) and for the validators receiving that proposal to first migrate before validating and given that the upgrade is not certain, there would need to be a mechanism to migrate back to v1 (NOTE: this remains the case if we wish to support downgrading which is discussed later). To overcome these requirements, the proposer must signal in the prior height the intention to upgrade to a new version. This is done with a new message type, `MsgVersionChange`, which must be put as the first transaction in the block. Validators read this and if they are in agreement to supporting the version change they vote on the block accordingly. If the block reaches consensus then all validators will update the app version at `EndBlock`. CometBFT will then propose the next block using that version. Nodes that have not upgraded and don't support the binary will error and exit. Given that the previous block was approved by more than 2/3 of the network we have a strong guarantee that this block will be accepted by the network. However, it's worth noting that given a security model that must withstand 1/3 byzantine nodes, even a single byzantine node that voted for the upgrade yet doesn't vote for the following block can stall the network until > 2/3 nodes upgrade and vote on the following block.
- Given uncertainty in scheduling, the system must be able to handle changes to the upgrade height that most commonly would come in the form of delays. Embedding the upgrade schedule in the binary is convenient for node operators and avoids the possibility for user errors. However, binaries are static. If the community wished to push back the upgrade by two weeks there is the possibility that some nodes would not rerun the new binary thus we'd get a split between nodes running the old schedule and nodes running the new schedule. To overcome this, proposers will only propose a version change in the first round of each height, thus allowing transactions to still be committed even under circumstances where there is no consensus on upgrading. Secondly, we define a range in which nodes will attempt to upgrade the app version and failing this will continue to run the current version. Lastly, the binary will have the ability to manually specify the app version height mapping and override the built-in values either through a flag or in the `app.toml` config. This is expected to be used in testing and in emergency situations only. Another example to keep in mind is if a quorum outright rejects an upgrade. If some of the validators are for the change they should have some way to continue participating in the network. Therefore we employ a range that nodes will attempt to upgrade and afterwards will continue on normally with the new binary however running the older version.
- The system needs to be tolerant of unexpected faults in the upgrade process. This can be:
- The community/contributors realise there is a bug in the new version after the binary has been released. Node operators will need to downgrade back to the previous version and restart their node.
- The community/contributors realize there is a bug in the new version after the binary has been released. Node operators will need to downgrade back to the previous version and restart their node.
- There is a halting bug in the migration or in processing of the first transactions. This most likely would be in the form of an apphash mismatch. This becomes more problematic with delayed execution as the block (with v2 transactions) has already been committed. Immediate execution has the advantage of the apphash mismatch being realised before the data is committed. It's still however feasible to over come this but it involves nodes rolling back the previous state and re-exectuing the transactions using the v1 state machine (which will skip over the v2 transactions). This means node operators should be able to manually override the app version that the proposer will propose with. Lastly, if state migrations occurred between v2 and v1, a reverse migration would need to be performed which would make things especially difficult. If we are unable to fallback to the previous version and continue then the other option is to remain halted until the bug is patched and the network can update and continue
- There is a bug that is detected that could halt the chain but hasn't yet. There are other things we can develop to combat such scenarios. One thing we can do is develop a circuit breaker similar to the designs proposed in [Cosmos SDK](https://github.com/cosmos/cosmos-sdk/tree/main/x/circuit). This can disable certain message types or modules either in `CheckTx` or `ProcessProposal`. This violates the consistency property between `PrepareProposal` and `ProcessProposal` but so long as a quorum are the same, will still allow the chain to progress (inconsistency here can be interpreted as byzantine).

Expand Down

0 comments on commit 6116a2e

Please sign in to comment.