Skip to content

feat: LEP-5 availability commitment support#6

Open
mateeullahmalik wants to merge 1 commit intomasterfrom
feat/lep5-availability-commitment
Open

feat: LEP-5 availability commitment support#6
mateeullahmalik wants to merge 1 commit intomasterfrom
feat/lep5-availability-commitment

Conversation

@mateeullahmalik
Copy link
Contributor

What

Adds client-side LEP-5 availability commitment support to the JS SDK. During cascade registration, the SDK now builds a BLAKE3 Merkle tree over the file's chunks, derives deterministic challenge indices from the root, and includes the AvailabilityCommitment in the on-chain cascade metadata.

Why

LEP-5 introduces Storage Verification Challenges. The client computes the commitment at registration time so the chain can later verify that supernodes actually stored the data. The supernode independently verifies the root and generates chunk proofs during finalization.

How it works

  1. SDK reads svc_challenge_count and svc_min_chunks_for_challenge from chain params (zero → defaults 8/4)
  2. Chunks the file (starting at 256 KiB, halving until ≥ minChunks chunks exist)
  3. Builds a BLAKE3 Merkle tree with domain-separated leaf/node hashing (matching the Go implementation)
  4. Derives challenge indices via BLAKE3(root || uint32be(counter)) mod numChunks
  5. Attaches the AvailabilityCommitment to cascade metadata in the registration transaction
  6. Files < 4 bytes skip commitment (too small for meaningful SVC)

Compatibility

  • Lumera chain (PR #103): Validates the commitment structure and verifies chunk proofs during finalization
  • Supernode (PR #274): Verifies the Merkle root, generates chunk proofs, submits them in the finalize transaction
  • Backward compatible: Pre-LEP-5 chains (params = 0) fall back to defaults. Files without commitments still work.

Changes

  • src/cascade/commitment.ts (new): selectChunkSize, buildTree, deriveIndices, buildCommitment
  • src/codegen/lumera/action/v1/params.ts: Added svcChallengeCount (field 12), svcMinChunksForChallenge (field 13)
  • src/codegen/lumera/action/v1/metadata.ts: Added AvailabilityCommitment, ChunkProof, HashAlgo types + fields 8/9 on CascadeMetadata
  • src/cascade/uploader.ts: Reads SVC params, builds commitment, includes in registration metadata
  • src/cascade/ports.ts: Extended CascadeActionParams with SVC fields
  • src/blockchain/interfaces.ts: Extended ActionParams with SVC fields
  • src/blockchain/client.ts + adapters/cascade-port.ts: Maps new params from chain query
  • src/index.ts: Exports new types and commitment functions

Testing

  • 21 new tests in tests/cascade/commitment.test.ts covering tree construction, index derivation, determinism, and edge cases
  • Zero regressions on existing test suite (same 8 pre-existing failures from WASM/env issues)

@roomote-v0
Copy link

roomote-v0 bot commented Mar 8, 2026

Rooviewer Clock   See task

Re-reviewed after 9f77216. The previous critical issue (commitment being silently dropped) is now fixed -- the adapter spreads availability_commitment into the serialized metadata. No new issues found. Implementation looks solid.

  • availability_commitment is silently dropped by BlockchainActionAdapter.requestActionTx -- the adapter's hardcoded JSON.stringify only forwards 5 fields and omits the new commitment field
Previous reviews

Mention @roomote in a comment to request specific changes to this pull request or fix all unresolved issues.

Comment on lines +339 to +349
if (availabilityCommitment) {
msg.availability_commitment = {
commitment_type: availabilityCommitment.commitmentType,
hash_algo: availabilityCommitment.hashAlgo,
chunk_size: availabilityCommitment.chunkSize,
total_size: availabilityCommitment.totalSize.toString(),
num_chunks: availabilityCommitment.numChunks,
root: Array.from(availabilityCommitment.root),
challenge_indices: availabilityCommitment.challengeIndices,
};
}
Copy link

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This availability_commitment is attached to msg here, but BlockchainActionAdapter.requestActionTx (cascade-port.ts lines 215-221) hardcodes exactly five fields when serializing the metadata into JSON.stringify: data_hash, file_name, rq_ids_ic, signatures, public. The availability_commitment key is silently dropped and never reaches the chain. The adapter's JSON.stringify call needs to be updated to forward this field as well, otherwise the entire commitment computation is wasted.

Fix it with Roo Code or mention @roomote and request a fix.

Add client-side Merkle tree construction and challenge index derivation
for the Storage Verification Challenge. During cascade registration, the
SDK now builds a BLAKE3 Merkle tree over file chunks, derives
deterministic challenge indices from the root, and includes the
AvailabilityCommitment in the on-chain metadata.

- New commitment module (cascade/commitment.ts): selectChunkSize,
  buildTree, deriveIndices, buildCommitment
- Updated codegen types: Params (svcChallengeCount, svcMinChunksForChallenge),
  CascadeMetadata (availabilityCommitment, chunkProofs),
  AvailabilityCommitment, ChunkProof, HashAlgo
- Uploader reads SVC params from chain, builds commitment during registration
- 21 new tests covering tree construction, index derivation, edge cases
- Zero regressions on existing test suite
@mateeullahmalik mateeullahmalik force-pushed the feat/lep5-availability-commitment branch from 63a3acc to 9f77216 Compare March 8, 2026 12:27
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant