Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

chore: improves documentation #96

Merged
merged 56 commits into from
Feb 14, 2023
Merged
Changes from 1 commit
Commits
Show all changes
56 commits
Select commit Hold shift + click to select a range
57481a0
clarifies the unit of nidSize
staheri14 Jan 26, 2023
d842ff6
adds function description for foundInRange
staheri14 Jan 26, 2023
5495171
adds missing func descriptions or makes further clarifications
staheri14 Jan 26, 2023
f1f1a53
adds TODOs and missing function descriptions
staheri14 Jan 27, 2023
0d3d318
refactors gotLeafHashes to leafHashes
staheri14 Jan 27, 2023
be869c9
corrects the description of generateLeafData
staheri14 Jan 27, 2023
69dd211
adds todos and comments and missing description of methods/functions
staheri14 Feb 1, 2023
b02c28b
adds some optimization ideas
staheri14 Feb 1, 2023
da16c5d
adds todo for early hash calculation
staheri14 Feb 1, 2023
2c82fbb
adds two more questions about the namespace len size
staheri14 Feb 1, 2023
12cc868
modifies the Prove documentation
staheri14 Feb 1, 2023
66fd0a8
updates the comments
staheri14 Feb 1, 2023
256a705
adds godoc for calculateAbsenceIndex
staheri14 Feb 2, 2023
810de44
adds the function name to the description
staheri14 Feb 2, 2023
3dbcd83
adds further clarification about the absence proof
staheri14 Feb 2, 2023
184a0a7
deletes excess line
staheri14 Feb 2, 2023
bf514d0
removes a todo
staheri14 Feb 2, 2023
d659113
elaborates on the return values of foundInRange
staheri14 Feb 2, 2023
ef7c36f
removes a todo
staheri14 Feb 2, 2023
dc838f1
adds a suggestion for early return in VerifyNamespace
staheri14 Feb 2, 2023
28b38b3
removes some old questions
staheri14 Feb 2, 2023
393db51
explains the order of nodes in the proof
staheri14 Feb 2, 2023
33cf50f
removes a question
staheri14 Feb 2, 2023
ac87f1c
revises the type of the proof
staheri14 Feb 2, 2023
4466bf8
changes the capitalization of the end
staheri14 Feb 8, 2023
f4504d1
adds documentation for id
staheri14 Feb 8, 2023
8310cea
expands the proof module by incorporating additional questions and re…
staheri14 Feb 9, 2023
2d81750
adds documentation for the Proof and VerifyNamespace
staheri14 Feb 9, 2023
5d7a9a7
adds further documentation
staheri14 Feb 9, 2023
6b76848
explains the ignore max logic
staheri14 Feb 10, 2023
ae4ef1b
reformats the code and adds description for the IgnoreMaxNamespace flag
staheri14 Feb 10, 2023
dab15e2
cleans up todos in data.go
staheri14 Feb 10, 2023
52c87da
removes todos from nmt
staheri14 Feb 10, 2023
ebbadea
removes todos from proof
staheri14 Feb 10, 2023
f91831c
removes a todo
staheri14 Feb 10, 2023
3d295c9
revises the hasher description to better illustrate the Ignore max idea
staheri14 Feb 10, 2023
36c4ebd
fixes variable name inconsistency
staheri14 Feb 10, 2023
d161c16
adds periods
staheri14 Feb 10, 2023
0d497e7
shortens the description of IgnoreMaxNamespace
staheri14 Feb 10, 2023
b9c7736
adds description of leafRange
staheri14 Feb 10, 2023
c820e57
adds further description about NamespacedMerkleTree and its fields
staheri14 Feb 10, 2023
19d6620
minor update
staheri14 Feb 10, 2023
7dea8b9
expands on Prove and ProveRange
staheri14 Feb 10, 2023
de897e4
elaborates on ProveNamespace
staheri14 Feb 10, 2023
82f9a1e
expands on the godoc for validateandextract namespace, computeRoot, f…
staheri14 Feb 10, 2023
c60ee20
adds explanation of isMaxNamespaceIDIgnored to the Proof data type, a…
staheri14 Feb 10, 2023
0095ca6
fixes wrapped function arguments
staheri14 Feb 10, 2023
530a279
fix bugs introduced by wrapped lines
staheri14 Feb 10, 2023
9effd59
Merge tag 'v0.14.0' into nmt-improved-documentation
staheri14 Feb 10, 2023
8742307
adds newlines to the end of the files
staheri14 Feb 10, 2023
e68e750
minor change
staheri14 Feb 10, 2023
87437b1
reverts the minor change
staheri14 Feb 10, 2023
bb85479
fixes a bug
staheri14 Feb 10, 2023
f53c3af
fixes another bug
staheri14 Feb 10, 2023
26b1ea6
addresses comments
staheri14 Feb 14, 2023
04dd6f9
fixes CI failures
staheri14 Feb 14, 2023
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
Prev Previous commit
Next Next commit
adds missing func descriptions or makes further clarifications
staheri14 committed Jan 26, 2023
commit 54951718cafc827eda1dc2061db22ee7122ba3ab
18 changes: 13 additions & 5 deletions nmt.go
Original file line number Diff line number Diff line change
@@ -82,8 +82,11 @@ type NamespacedMerkleTree struct {
// store leaf hashes whenever computed (via Root() or via computeLeafHashesIfNecessary)
leafHashes [][]byte

// this can be used to efficiently lookup the range for an
// this can be used to efficiently look up the range for an
// existing namespace without iterating through the leaves
// the map key is the string representation of a namespace.ID and
// the leafRange indicates the starting position and ending position of
// the leaves matching that namespace ID in the tree
namespaceRanges map[string]leafRange
minNID namespace.ID
maxNID namespace.ID
@@ -105,6 +108,7 @@ func New(h hash.Hash, setters ...Option) *NamespacedMerkleTree {
NodeVisitor: noOp,
}

// TODO [Me] ?
for _, setter := range setters {
setter(opts)
}
@@ -159,9 +163,12 @@ func (n *NamespacedMerkleTree) ProveNamespace(nID namespace.ID) (Proof, error) {
// In the cases (nID < minNID) or (maxNID < nID),
// return empty range and no proof:
if nID.Less(n.minNID) || n.maxNID.Less(nID) {
// TODO [Me] Shouldn't we instead return the first or the last node in the tree as the exclusion proof
// TODO [Me] although I think this current logic is based on the premise that the root of the tree is trusted
return NewEmptyRangeProof(isMaxNsIgnored), nil
}

// find the range of indices of leaves with the given nID
found, proofStart, proofEnd := n.foundInRange(nID)
if !found {
// To generate a proof for an absence we calculate the
@@ -170,18 +177,19 @@ func (n *NamespacedMerkleTree) ProveNamespace(nID namespace.ID) (Proof, error) {
proofStart = n.calculateAbsenceIndex(nID)
proofEnd = proofStart + 1
}
// At this point we either found the namespace in the tree or calculated
// At this point we either found leaves with the namespace nID in the tree or calculated
// the range it would be in (to generate a proof of absence and to return
// the corresponding leaf hashes).
n.computeLeafHashesIfNecessary()
proof := n.buildRangeProof(proofStart, proofEnd)
n.computeLeafHashesIfNecessary() // TODO [Me] Why it is needed?
proof := n.buildRangeProof(proofStart, proofEnd) // TODO [Me] check whether the position of nodes are included in the proof and also verified later in the verification part

if found {
return NewInclusionProof(proofStart, proofEnd, proof, isMaxNsIgnored), nil
}
return NewAbsenceProof(proofStart, proofEnd, proof, n.leafHashes[proofStart], isMaxNsIgnored), nil
}

// TODO [Me] add a function description about how to parse the output [][]byte
func (n *NamespacedMerkleTree) buildRangeProof(proofStart, proofEnd int) [][]byte {
proof := [][]byte{}
var recurse func(start, end int, includeNode bool) []byte
@@ -408,7 +416,7 @@ func (n *NamespacedMerkleTree) updateMinMaxID(id namespace.ID) {
}
}

// computes the leaf hashes if not already done in a previously call
// computes the leaf hashes if not already done in a previous call
// of NamespacedMerkleTree.Root()
func (n *NamespacedMerkleTree) computeLeafHashesIfNecessary() {
if len(n.leafHashes) < len(n.leaves) {
2 changes: 1 addition & 1 deletion proof.go
Original file line number Diff line number Diff line change
@@ -27,7 +27,7 @@ type Proof struct {
leafHash []byte
// isMaxNamespaceIDIgnored is set to true if the tree from which
// this Proof was generated from is initialized with
// Options.IgnoreMaxNamespace == true.
// Options.IgnoreMaxNamespace == true. // TODO [Me]? not sure about the usage of this
isMaxNamespaceIDIgnored bool
}