Skip to content

Commit

Permalink
docs: corrections and clarifications (#2937)
Browse files Browse the repository at this point in the history
### Summary
This pull request addresses several minor issues in the project's
documentation, enhancing clarity and consistency.

### Changes
1. **ADR 020 Section (Commit 97456f2)**: Fixed a grammatical error for
better readability.
2. **Blobstream README (Commit 4c94077)**: Corrected wording in the
Pruning section.
3. **Blobstream README (Commit d9a20ad)**: Standardized the spelling of
'unbonding'.
4. **Testground README (Commit 009b954)**: Clarified Kubernetes port
forwarding instructions for Grafana.
5. **Wrapper README (Commit 57ba44f)**: Fixed a typo in the Namespaced
Merkle Tree Wrapper section.

Happy to contribute these enhancements to the documentation of this
amazing project. A big thank you to the maintainers for their ongoing
efforts.
  • Loading branch information
joaolago1113 authored Dec 14, 2023
1 parent e0edb4c commit d13d002
Show file tree
Hide file tree
Showing 4 changed files with 5 additions and 5 deletions.
Original file line number Diff line number Diff line change
Expand Up @@ -11,7 +11,7 @@ Implemented in <https://github.com/celestiaorg/celestia-app/pull/1690>

## Context

The current protocol around the construction of an original data square (ODS) is based around a set of constraints that are enforced during consensus through validation (See `ProcessProposal`). Block proposers are at liberty to choosing not only what transactions are included and in what order but can effectively decide on the amount of padding (i.e. where each blob is located in the square) and the size of the square. This degree of control leaks needless complexity to users with little upside and allows for adverse behaviour.
The current protocol around the construction of an original data square (ODS) is based around a set of constraints that are enforced during consensus through validation (See `ProcessProposal`). Block proposers are at liberty to choose not only what transactions are included and in what order but can effectively decide on the amount of padding (i.e. where each blob is located in the square) and the size of the square. This degree of control leaks needless complexity to users with little upside and allows for adverse behaviour.

Earlier designs were incorporated around the notion of interaction between the block proposer and the transaction submitter. A user that wanted to submit a PFB would go to a potential block proposer, provide them with the transaction, the proposer would then reserve a position in the square for the transaction and finally the transaction submitter would sign the transaction with the provided share index. However, Celestia may have 100 potential block proposers which are often hidden from the network. Furthermore, transactions often reach a block proposer through a gossip network, severing the ability for the block proposer to directly communicate with the transaction submitter. Lastly, new transactions with greater fees might arrive causing the block proposer to want to shuffle the transactions around in the square. The response to these problems was to come up with "non-interactive defaults" (first mentioned in [ADR006](./adr-006-non-interactive-defaults.md)).

Expand Down
2 changes: 1 addition & 1 deletion pkg/wrapper/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -28,7 +28,7 @@ At its core, it is an [NMT][nmtlink] and is defined by a similar set of paramete
Namely, the [namespace ID size `NamespaceIDSize`][nmt-ds-link],
the underlying hash function for the digest calculation of the [namespaced hashes][nmt-hash-link],
and the [`IgnoreMaxNamespace` flag][nmt-ignoremax-link] which dictates how namespace range of non-leaf nodes are calculated.
In addition, the NMT wrapper is configured with the original data square size `SqaureSize` (`k` in the above example), and the index of the row or column it represents `AxisIndex` which is a value in `[0, 2*SquareSize)`.
In addition, the NMT wrapper is configured with the original data square size `SquareSize` (`k` in the above example), and the index of the row or column it represents `AxisIndex` which is a value in `[0, 2*SquareSize)`.
These additional configurations are used to determine the namespace ID of the shares that the NMT wrapper represents based on the quadrants to which they belong.

NMT wrapper supports [Merkle inclusion proof][nmtlink] for the given share index and [Merkle range proof][nmtlink] for a range of share indices.
Expand Down
2 changes: 1 addition & 1 deletion test/testground/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -95,7 +95,7 @@ testground terminate --runner cluster:k8s
### Grafana

All metrics data is logged to a separate testground specific grafana/influx
node. To access that node, forward the ports use kubectl.
node. To access that node, forward the ports using kubectl.

```sh
export POD_NAME=$(kubectl get pods --namespace default -l "app.kubernetes.io/name=grafana,app.kubernetes.io/instance=tg-monitoring" -o jsonpath="{.items[0].metadata.name}")
Expand Down
4 changes: 2 additions & 2 deletions x/blobstream/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -159,7 +159,7 @@ To check if the latest attestation nonce is defined in store, use the [`CheckLat

### Latest unbonding height

The latest unbonding height indicates the most recent height at which some validator started unbdonding. It is not initialized in genesis, and the keeper getter
The latest unbonding height indicates the most recent height at which some validator started unbonding. It is not initialized in genesis, and the keeper getter
[`GetLatestUnBondingBlockHeight(...)`](https://github.com/celestiaorg/celestia-app/blob/9bf0cf1dd9ce31a3fecb51310c3913820b21a8c2/x/qgb/keeper/keeper_valset.go#L66-L77) returns **0** if the value is still not defined.

| Name | Key |
Expand Down Expand Up @@ -222,7 +222,7 @@ The Blobstream state machine prunes old attestations up to the specified [`Attes

So, on every block height, the state machine [checks](https://github.com/celestiaorg/celestia-app/blob/0629c757ef35a24187a8d7a4c706c7cdc894c8b6/x/qgb/abci.go#L140-L157) whether there are any [`expired`](https://github.com/celestiaorg/celestia-app/blob/0629c757ef35a24187a8d7a4c706c7cdc894c8b6/x/qgb/abci.go#L22-L25) attestations. Then, it starts [pruning](https://github.com/celestiaorg/celestia-app/blob/0629c757ef35a24187a8d7a4c706c7cdc894c8b6/x/qgb/abci.go#L161-L182) via calling the [`DeleteAttestation(...)`](https://github.com/celestiaorg/celestia-app/blob/0629c757ef35a24187a8d7a4c706c7cdc894c8b6/x/qgb/keeper/keeper_attestation.go#L128-L139) method. Then, it [`prints`](https://github.com/celestiaorg/celestia-app/blob/0629c757ef35a24187a8d7a4c706c7cdc894c8b6/x/qgb/abci.go#L186-L194) a log message specifying the number of pruned attestations.

If the all the attestations in store are expired, which is an edge case that should never occur, the Blobstream state machine [doesn't prune](https://github.com/celestiaorg/celestia-app/blob/0629c757ef35a24187a8d7a4c706c7cdc894c8b6/x/qgb/abci.go#L161) the latest attestation.
If all the attestations in store are expired, which is an edge case that should never occur, the Blobstream state machine [doesn't prune](https://github.com/celestiaorg/celestia-app/blob/0629c757ef35a24187a8d7a4c706c7cdc894c8b6/x/qgb/abci.go#L161) the latest attestation.

### Hooks

Expand Down

0 comments on commit d13d002

Please sign in to comment.