|
| 1 | +package cascadekit |
| 2 | + |
| 3 | +import ( |
| 4 | + "fmt" |
| 5 | + "io" |
| 6 | + "os" |
| 7 | + |
| 8 | + actiontypes "github.com/LumeraProtocol/lumera/x/action/v1/types" |
| 9 | + "github.com/LumeraProtocol/lumera/x/action/v1/merkle" |
| 10 | + "lukechampine.com/blake3" |
| 11 | +) |
| 12 | + |
| 13 | +const ( |
| 14 | + // DefaultChunkSize is the default chunk size for LEP-5 commitment (256 KiB). |
| 15 | + DefaultChunkSize = 262144 |
| 16 | + // MinChunkSize is the minimum allowed chunk size. |
| 17 | + MinChunkSize = 1 |
| 18 | + // MaxChunkSize is the maximum allowed chunk size. |
| 19 | + MaxChunkSize = 262144 |
| 20 | + // MinTotalSize is the minimum file size for LEP-5 commitment. |
| 21 | + MinTotalSize = 4 |
| 22 | + // CommitmentType is the commitment type constant for LEP-5. |
| 23 | + CommitmentType = "lep5/chunk-merkle/v1" |
| 24 | +) |
| 25 | + |
| 26 | +// SelectChunkSize returns the optimal chunk size for a given file size and |
| 27 | +// minimum chunk count. It starts at DefaultChunkSize and halves until the |
| 28 | +// file produces at least minChunks chunks. |
| 29 | +func SelectChunkSize(fileSize int64, minChunks uint32) uint32 { |
| 30 | + s := uint32(DefaultChunkSize) |
| 31 | + for numChunks(fileSize, s) < minChunks && s > MinChunkSize { |
| 32 | + s /= 2 |
| 33 | + } |
| 34 | + return s |
| 35 | +} |
| 36 | + |
| 37 | +func numChunks(fileSize int64, chunkSize uint32) uint32 { |
| 38 | + n := uint32(fileSize / int64(chunkSize)) |
| 39 | + if fileSize%int64(chunkSize) != 0 { |
| 40 | + n++ |
| 41 | + } |
| 42 | + return n |
| 43 | +} |
| 44 | + |
| 45 | +// ChunkFile reads a file and returns its chunks using the given chunk size. |
| 46 | +func ChunkFile(path string, chunkSize uint32) ([][]byte, error) { |
| 47 | + f, err := os.Open(path) |
| 48 | + if err != nil { |
| 49 | + return nil, fmt.Errorf("open file: %w", err) |
| 50 | + } |
| 51 | + defer f.Close() |
| 52 | + |
| 53 | + fi, err := f.Stat() |
| 54 | + if err != nil { |
| 55 | + return nil, fmt.Errorf("stat file: %w", err) |
| 56 | + } |
| 57 | + |
| 58 | + totalSize := fi.Size() |
| 59 | + n := numChunks(totalSize, chunkSize) |
| 60 | + chunks := make([][]byte, 0, n) |
| 61 | + |
| 62 | + buf := make([]byte, chunkSize) |
| 63 | + for { |
| 64 | + nr, err := io.ReadFull(f, buf) |
| 65 | + if nr > 0 { |
| 66 | + chunk := make([]byte, nr) |
| 67 | + copy(chunk, buf[:nr]) |
| 68 | + chunks = append(chunks, chunk) |
| 69 | + } |
| 70 | + if err == io.EOF || err == io.ErrUnexpectedEOF { |
| 71 | + break |
| 72 | + } |
| 73 | + if err != nil { |
| 74 | + return nil, fmt.Errorf("read chunk: %w", err) |
| 75 | + } |
| 76 | + } |
| 77 | + return chunks, nil |
| 78 | +} |
| 79 | + |
| 80 | +// BuildCommitmentFromFile constructs an AvailabilityCommitment for a file. |
| 81 | +// It chunks the file, builds a Merkle tree, and generates challenge indices. |
| 82 | +// challengeCount and minChunks are the SVC parameters from the chain. |
| 83 | +func BuildCommitmentFromFile(filePath string, challengeCount, minChunks uint32) (*actiontypes.AvailabilityCommitment, *merkle.Tree, error) { |
| 84 | + fi, err := os.Stat(filePath) |
| 85 | + if err != nil { |
| 86 | + return nil, nil, fmt.Errorf("stat file: %w", err) |
| 87 | + } |
| 88 | + totalSize := fi.Size() |
| 89 | + if totalSize < MinTotalSize { |
| 90 | + return nil, nil, fmt.Errorf("file too small: %d bytes (minimum %d)", totalSize, MinTotalSize) |
| 91 | + } |
| 92 | + |
| 93 | + chunkSize := SelectChunkSize(totalSize, minChunks) |
| 94 | + nc := numChunks(totalSize, chunkSize) |
| 95 | + if nc < minChunks { |
| 96 | + return nil, nil, fmt.Errorf("file produces %d chunks, need at least %d", nc, minChunks) |
| 97 | + } |
| 98 | + |
| 99 | + chunks, err := ChunkFile(filePath, chunkSize) |
| 100 | + if err != nil { |
| 101 | + return nil, nil, err |
| 102 | + } |
| 103 | + |
| 104 | + tree, err := merkle.BuildTree(chunks) |
| 105 | + if err != nil { |
| 106 | + return nil, nil, fmt.Errorf("build merkle tree: %w", err) |
| 107 | + } |
| 108 | + |
| 109 | + // Generate challenge indices — simple deterministic selection using tree root as entropy. |
| 110 | + m := challengeCount |
| 111 | + if m > nc { |
| 112 | + m = nc |
| 113 | + } |
| 114 | + indices := deriveSimpleIndices(tree.Root[:], nc, m) |
| 115 | + |
| 116 | + commitment := &actiontypes.AvailabilityCommitment{ |
| 117 | + CommitmentType: CommitmentType, |
| 118 | + HashAlgo: actiontypes.HashAlgo_HASH_ALGO_BLAKE3, |
| 119 | + ChunkSize: chunkSize, |
| 120 | + TotalSize: uint64(totalSize), |
| 121 | + NumChunks: nc, |
| 122 | + Root: tree.Root[:], |
| 123 | + ChallengeIndices: indices, |
| 124 | + } |
| 125 | + |
| 126 | + return commitment, tree, nil |
| 127 | +} |
| 128 | + |
| 129 | +// GenerateChunkProofs produces Merkle proofs for the challenge indices in the commitment. |
| 130 | +func GenerateChunkProofs(tree *merkle.Tree, indices []uint32) ([]*actiontypes.ChunkProof, error) { |
| 131 | + proofs := make([]*actiontypes.ChunkProof, len(indices)) |
| 132 | + for i, idx := range indices { |
| 133 | + p, err := tree.GenerateProof(int(idx)) |
| 134 | + if err != nil { |
| 135 | + return nil, fmt.Errorf("generate proof for chunk %d: %w", idx, err) |
| 136 | + } |
| 137 | + |
| 138 | + pathHashes := make([][]byte, len(p.PathHashes)) |
| 139 | + for j, h := range p.PathHashes { |
| 140 | + pathHashes[j] = h[:] |
| 141 | + } |
| 142 | + |
| 143 | + proofs[i] = &actiontypes.ChunkProof{ |
| 144 | + ChunkIndex: p.ChunkIndex, |
| 145 | + LeafHash: p.LeafHash[:], |
| 146 | + PathHashes: pathHashes, |
| 147 | + PathDirections: p.PathDirections, |
| 148 | + } |
| 149 | + } |
| 150 | + return proofs, nil |
| 151 | +} |
| 152 | + |
| 153 | +// VerifyCommitmentRoot rebuilds the Merkle tree from a file and checks it matches the on-chain root. |
| 154 | +func VerifyCommitmentRoot(filePath string, commitment *actiontypes.AvailabilityCommitment) (*merkle.Tree, error) { |
| 155 | + if commitment == nil { |
| 156 | + return nil, nil // pre-LEP-5 action, nothing to verify |
| 157 | + } |
| 158 | + |
| 159 | + chunks, err := ChunkFile(filePath, commitment.ChunkSize) |
| 160 | + if err != nil { |
| 161 | + return nil, fmt.Errorf("chunk file for verification: %w", err) |
| 162 | + } |
| 163 | + |
| 164 | + if uint32(len(chunks)) != commitment.NumChunks { |
| 165 | + return nil, fmt.Errorf("chunk count mismatch: got %d, expected %d", len(chunks), commitment.NumChunks) |
| 166 | + } |
| 167 | + |
| 168 | + tree, err := merkle.BuildTree(chunks) |
| 169 | + if err != nil { |
| 170 | + return nil, fmt.Errorf("build merkle tree for verification: %w", err) |
| 171 | + } |
| 172 | + |
| 173 | + if tree.Root != [merkle.HashSize]byte(commitment.Root) { |
| 174 | + return nil, fmt.Errorf("merkle root mismatch: computed %x, expected %x", tree.Root[:], commitment.Root) |
| 175 | + } |
| 176 | + |
| 177 | + return tree, nil |
| 178 | +} |
| 179 | + |
| 180 | +// deriveSimpleIndices generates m unique indices in [0, numChunks) using BLAKE3(root || counter). |
| 181 | +func deriveSimpleIndices(root []byte, numChunks, m uint32) []uint32 { |
| 182 | + if numChunks == 0 || m == 0 { |
| 183 | + return nil |
| 184 | + } |
| 185 | + |
| 186 | + indices := make([]uint32, 0, m) |
| 187 | + used := make(map[uint32]struct{}, m) |
| 188 | + counter := uint32(0) |
| 189 | + |
| 190 | + for uint32(len(indices)) < m { |
| 191 | + // BLAKE3(root || uint32be(counter)) |
| 192 | + buf := make([]byte, len(root)+4) |
| 193 | + copy(buf, root) |
| 194 | + buf[len(root)] = byte(counter >> 24) |
| 195 | + buf[len(root)+1] = byte(counter >> 16) |
| 196 | + buf[len(root)+2] = byte(counter >> 8) |
| 197 | + buf[len(root)+3] = byte(counter) |
| 198 | + |
| 199 | + h := blake3.Sum256(buf) |
| 200 | + // Use first 8 bytes as uint64 mod numChunks |
| 201 | + val := uint64(h[0])<<56 | uint64(h[1])<<48 | uint64(h[2])<<40 | uint64(h[3])<<32 | |
| 202 | + uint64(h[4])<<24 | uint64(h[5])<<16 | uint64(h[6])<<8 | uint64(h[7]) |
| 203 | + idx := uint32(val % uint64(numChunks)) |
| 204 | + |
| 205 | + if _, exists := used[idx]; !exists { |
| 206 | + used[idx] = struct{}{} |
| 207 | + indices = append(indices, idx) |
| 208 | + } |
| 209 | + counter++ |
| 210 | + } |
| 211 | + return indices |
| 212 | +} |
0 commit comments