From 4e84d80f3e55ac3093005c8089186d68ee62541d Mon Sep 17 00:00:00 2001 From: Rootul P Date: Thu, 29 Feb 2024 15:13:37 -0500 Subject: [PATCH] docs: improve README with package comments (#34) --- README.md | 15 +++++++++++++-- blob/blob.go | 3 +++ inclusion/blob_share_commitment_rules.go | 20 +++++++++----------- inclusion/commitment.go | 6 +++--- inclusion/commitment_test.go | 2 +- inclusion/doc.go | 3 +++ namespace/namespace.go | 1 + shares/shares.go | 1 + square/square.go | 2 ++ 9 files changed, 36 insertions(+), 17 deletions(-) create mode 100644 inclusion/doc.go diff --git a/README.md b/README.md index 265c369..e70c804 100644 --- a/README.md +++ b/README.md @@ -1,6 +1,17 @@ # go-square -`go-square` is a Go library designed to provide utility functions for data square operations. +[![Go Reference](https://pkg.go.dev/badge/github.com/celestiaorg/go-square.svg)](https://pkg.go.dev/github.com/celestiaorg/go-square) + +`go-square` is a Go module that provides data structures and utilities for interacting with data squares in the Celestia network. The data square is a special form of block serialization in the Celestia blockchain. This repo deals with the original data square which is distinct from the extended data square. Operations on the extended data square are handled by [rsmt2d](https://github.com/celestiaorg/rsmt2d). + +Package | Description +----------|--------------------------------------------------------------------------------------------------------------------- +blob | Package blob provides types and functions for working with blobs, blob transactions, and index wrapper transactions. +inclusion | Package inclusion contains functions to generate the blob share commitment from a given blob. +merkle | Package merkle computes a deterministic minimal height Merkle tree hash. +namespace | Package namespace contains the Namespace data structure. +shares | Package shares contains the Share data structure. +square | Package square implements the logic to construct the original data square based on a list of transactions. ## Installation @@ -38,4 +49,4 @@ make lint # Perform benchmarking make bench -``` \ No newline at end of file +``` diff --git a/blob/blob.go b/blob/blob.go index 291b981..8fe310f 100644 --- a/blob/blob.go +++ b/blob/blob.go @@ -1,3 +1,5 @@ +// Package blob provides types and functions for working with blobs, blob +// transactions, and index wrapper transactions. package blob import ( @@ -98,6 +100,7 @@ func MarshalBlobTx(tx []byte, blobs ...*Blob) ([]byte, error) { return proto.Marshal(bTx) } +// Sort sorts the blobs by their namespace. func Sort(blobs []*Blob) { sort.SliceStable(blobs, func(i, j int) bool { return bytes.Compare(blobs[i].Namespace().Bytes(), blobs[j].Namespace().Bytes()) < 0 diff --git a/inclusion/blob_share_commitment_rules.go b/inclusion/blob_share_commitment_rules.go index 2a0a205..0204b1a 100644 --- a/inclusion/blob_share_commitment_rules.go +++ b/inclusion/blob_share_commitment_rules.go @@ -7,9 +7,9 @@ import ( "golang.org/x/exp/constraints" ) -// BlobSharesUsedNonInteractiveDefaults returns the number of shares used by a given set -// of blobs share lengths. It follows the blob share commitment rules and -// returns the share indexes for each blob. +// BlobSharesUsedNonInteractiveDefaults returns the number of shares used by a +// given set of blobs share lengths. It follows the blob share commitment rules +// and returns the total shares used and share indexes for each blob. func BlobSharesUsedNonInteractiveDefaults(cursor, subtreeRootThreshold int, blobShareLens ...int) (sharesUsed int, indexes []uint32) { start := cursor indexes = make([]uint32, len(blobShareLens)) @@ -34,13 +34,13 @@ func NextShareIndex(cursor, blobShareLen, subtreeRootThreshold int) int { // merkle mountain range that makes up the blob share commitment (given the // subtreeRootThreshold and the BlobMinSquareSize). treeWidth := SubTreeWidth(blobShareLen, subtreeRootThreshold) - // We round up the cursor to the next multiple of this value i.e. if the cursor - // was at 13 and the tree width was 4, we return 16. + // Round up the cursor to the next multiple of treeWidth. For example, if + // the cursor was at 13 and the tree width is 4, return 16. return RoundUpByMultipleOf(cursor, treeWidth) } // RoundUpByMultipleOf rounds cursor up to the next multiple of v. If cursor is divisible -// by v, then it returns cursor +// by v, then it returns cursor. func RoundUpByMultipleOf(cursor, v int) int { if cursor%v == 0 { return cursor @@ -54,13 +54,11 @@ func BlobMinSquareSize(shareCount int) int { return shares.RoundUpPowerOfTwo(int(math.Ceil(math.Sqrt(float64(shareCount))))) } -// SubTreeWidth determines the maximum number of leaves per subtree in the share +// SubTreeWidth returns the maximum number of leaves per subtree in the share // commitment over a given blob. The input should be the total number of shares -// used by that blob. The reasoning behind this algorithm is discussed in depth -// in ADR013 -// (celestia-app/docs/architecture/adr-013-non-interative-default-rules-for-zero-padding). +// used by that blob. See ADR-013. func SubTreeWidth(shareCount, subtreeRootThreshold int) int { - // per ADR013, we use a predetermined threshold to determine width of sub + // Per ADR-013, we use a predetermined threshold to determine width of sub // trees used to create share commitments s := (shareCount / subtreeRootThreshold) diff --git a/inclusion/commitment.go b/inclusion/commitment.go index 889d829..d84b4e2 100644 --- a/inclusion/commitment.go +++ b/inclusion/commitment.go @@ -43,15 +43,15 @@ func CreateCommitment(blob *blob.Blob, merkleRootFn MerkleRootFn, subtreeRootThr cursor += treeSize } - // create the commitments by pushing each leaf set onto an nmt + // create the commitments by pushing each leaf set onto an NMT subTreeRoots := make([][]byte, len(leafSets)) for i, set := range leafSets { - // create the nmt todo(evan) use nmt wrapper + // Create the NMT. TODO: use NMT wrapper. tree := nmt.New(sha256.New(), nmt.NamespaceIDSize(ns.NamespaceSize), nmt.IgnoreMaxNamespace(true)) for _, leaf := range set { // the namespace must be added again here even though it is already // included in the leaf to ensure that the hash will match that of - // the nmt wrapper (pkg/wrapper). Each namespace is added to keep + // the NMT wrapper (pkg/wrapper). Each namespace is added to keep // the namespace in the share, and therefore the parity data, while // also allowing for the manual addition of the parity namespace to // the parity data. diff --git a/inclusion/commitment_test.go b/inclusion/commitment_test.go index 61a9b08..60d9b37 100644 --- a/inclusion/commitment_test.go +++ b/inclusion/commitment_test.go @@ -13,7 +13,7 @@ import ( "github.com/stretchr/testify/require" ) -func Test_MerkleMountainRangeHeights(t *testing.T) { +func TestMerkleMountainRangeSizes(t *testing.T) { type test struct { totalSize uint64 squareSize uint64 diff --git a/inclusion/doc.go b/inclusion/doc.go new file mode 100644 index 0000000..cea07fc --- /dev/null +++ b/inclusion/doc.go @@ -0,0 +1,3 @@ +// Package inclusion contains functions to generate the blob share commitment +// from a given blob. +package inclusion diff --git a/namespace/namespace.go b/namespace/namespace.go index 3186d78..1feb6f9 100644 --- a/namespace/namespace.go +++ b/namespace/namespace.go @@ -1,3 +1,4 @@ +// Package namespace contains the Namespace data structure. package namespace import ( diff --git a/shares/shares.go b/shares/shares.go index 08025e5..e4e60f2 100644 --- a/shares/shares.go +++ b/shares/shares.go @@ -1,3 +1,4 @@ +// Package shares contains the Share data structure. package shares import ( diff --git a/square/square.go b/square/square.go index 53b0e18..777d189 100644 --- a/square/square.go +++ b/square/square.go @@ -1,3 +1,5 @@ +// Package square implements the logic to construct the original data square +// based on a list of transactions. package square import (