Skip to content

Commit

Permalink
docs: improve README with package comments (#34)
Browse files Browse the repository at this point in the history
  • Loading branch information
rootulp authored Feb 29, 2024
1 parent c20eda9 commit 4e84d80
Show file tree
Hide file tree
Showing 9 changed files with 36 additions and 17 deletions.
15 changes: 13 additions & 2 deletions README.md
Original file line number Diff line number Diff line change
@@ -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

Expand Down Expand Up @@ -38,4 +49,4 @@ make lint

# Perform benchmarking
make bench
```
```
3 changes: 3 additions & 0 deletions blob/blob.go
Original file line number Diff line number Diff line change
@@ -1,3 +1,5 @@
// Package blob provides types and functions for working with blobs, blob
// transactions, and index wrapper transactions.
package blob

import (
Expand Down Expand Up @@ -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
Expand Down
20 changes: 9 additions & 11 deletions inclusion/blob_share_commitment_rules.go
Original file line number Diff line number Diff line change
Expand Up @@ -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))
Expand All @@ -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
Expand All @@ -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)

Expand Down
6 changes: 3 additions & 3 deletions inclusion/commitment.go
Original file line number Diff line number Diff line change
Expand Up @@ -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.
Expand Down
2 changes: 1 addition & 1 deletion inclusion/commitment_test.go
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down
3 changes: 3 additions & 0 deletions inclusion/doc.go
Original file line number Diff line number Diff line change
@@ -0,0 +1,3 @@
// Package inclusion contains functions to generate the blob share commitment
// from a given blob.
package inclusion
1 change: 1 addition & 0 deletions namespace/namespace.go
Original file line number Diff line number Diff line change
@@ -1,3 +1,4 @@
// Package namespace contains the Namespace data structure.
package namespace

import (
Expand Down
1 change: 1 addition & 0 deletions shares/shares.go
Original file line number Diff line number Diff line change
@@ -1,3 +1,4 @@
// Package shares contains the Share data structure.
package shares

import (
Expand Down
2 changes: 2 additions & 0 deletions square/square.go
Original file line number Diff line number Diff line change
@@ -1,3 +1,5 @@
// Package square implements the logic to construct the original data square
// based on a list of transactions.
package square

import (
Expand Down

0 comments on commit 4e84d80

Please sign in to comment.