@shelby-protocol/sdk 0.3.0 → 0.4.0

package/dist/core/clients/utils.mjs

@@ -1,9 +1,68 @@
-import {
-  getAptosConfig,
-  getShelbyRPCBaseUrl
-} from "../../chunk-V4B3GAMQ.mjs";
-import "../../chunk-MNCQBEMS.mjs";
-import "../../chunk-7P6ASYW6.mjs";
+// src/core/clients/utils.ts
+import { AptosConfig } from "@aptos-labs/ts-sdk";
+
+// src/core/constants.ts
+import { Network } from "@aptos-labs/ts-sdk";
+var NetworkToShelbyRPCBaseUrl = {
+  [Network.SHELBYNET]: "https://shelby.shelbynet.shelby.xyz/shelby",
+  [Network.NETNA]: void 0,
+  [Network.DEVNET]: void 0,
+  [Network.TESTNET]: "https://api.testnet.shelby.xyz/shelby",
+  [Network.MAINNET]: void 0,
+  [Network.LOCAL]: "http://localhost:9090",
+  [Network.CUSTOM]: void 0
+};
+var NetworkToShelbyBlobIndexerBaseUrl = {
+  [Network.SHELBYNET]: "https://api.shelbynet.aptoslabs.com/nocode/v1/public/alias/shelby/shelbynet/v1/graphql",
+  [Network.NETNA]: void 0,
+  [Network.DEVNET]: void 0,
+  [Network.TESTNET]: "https://api.testnet.aptoslabs.com/nocode/v1/public/alias/shelby/testnet/v1/graphql",
+  [Network.MAINNET]: void 0,
+  [Network.LOCAL]: "http://localhost:8091/v1/graphql",
+  [Network.CUSTOM]: void 0
+};
+var NetworkToGasStationBaseUrl = {
+  [Network.SHELBYNET]: "https://api.shelbynet.shelby.xyz/gs/v1",
+  [Network.NETNA]: void 0,
+  [Network.DEVNET]: void 0,
+  [Network.TESTNET]: "https://api.testnet.shelby.xyz/gs/v1",
+  [Network.MAINNET]: void 0,
+  [Network.LOCAL]: void 0,
+  [Network.CUSTOM]: void 0
+};
+
+// src/core/clients/utils.ts
+var getAptosConfig = (config) => {
+  const baseFaucetConfig = config.faucet?.authToken ? { AUTH_TOKEN: config.faucet.authToken } : void 0;
+  if (config.aptos) {
+    return new AptosConfig({
+      // Spread user's aptos config first
+      ...config.aptos,
+      // Network from top-level is authoritative - cannot be overridden
+      network: config.network,
+      // Merge clientConfig with API_KEY default
+      clientConfig: {
+        API_KEY: config.apiKey,
+        ...config.aptos.clientConfig
+      },
+      // Merge faucetConfig: aptos config first, then base authToken (authoritative)
+      faucetConfig: {
+        ...config.aptos.faucetConfig,
+        ...baseFaucetConfig
+      }
+    });
+  }
+  return new AptosConfig({
+    network: config.network,
+    clientConfig: {
+      API_KEY: config.apiKey
+    },
+    faucetConfig: baseFaucetConfig
+  });
+};
+var getShelbyRPCBaseUrl = (config) => {
+  return config.rpc?.baseUrl ?? NetworkToShelbyRPCBaseUrl[config.network] ?? NetworkToShelbyRPCBaseUrl.testnet;
+};
 export {
   getAptosConfig,
   getShelbyRPCBaseUrl

package/dist/core/commitments.d.ts

@@ -42,6 +42,17 @@ declare const ChunksetCommitmentSchema: z.ZodEffects<z.ZodObject<{
 }>;
 type ChunksetCommitment = z.infer<typeof ChunksetCommitmentSchema>;
 declare function expectedTotalChunksets(rawSize: number, chunksetSize?: number): number;
+/**
+ * Expected number of 32-byte sibling hashes in a chunkset-to-blob inclusion proof.
+ *
+ * The blob merkle tree uses incremental odd-level zero-hash padding (see
+ * `generateMerkleRoot`). A single-chunkset blob is already the root, so the
+ * proof is empty (CLI sends header value `"NONE"`).
+ *
+ * For n > 1 chunksets, the proof length equals the number of levels from leaf
+ * to root, which is `ceil(log2(n))` — not `ceil(log2(n)) - 1`.
+ */
+declare function expectedChunksetInclusionProofHashes(numChunksets: number): number;
 /**
  * Represents the (serializable) commitment schema for a single blob.
  */
@@ -124,4 +135,4 @@ declare function generateMerkleRoot(leafHashes: Hex[]): Promise<Hex>;
  */
 declare function generateCommitments(provider: ErasureCodingProvider, fullData: ReadableStream<Uint8Array> | Uint8Array, onChunk?: (chunksetIdx: number, chunkIdx: number, chunkData: Uint8Array) => Promise<void> | void): Promise<BlobCommitments>;
 
-export { type BlobCommitments, BlobCommitmentsSchema, COMMITMENT_SCHEMA_VERSION, type ChunksetCommitment, ChunksetCommitmentSchema, expectedTotalChunksets, generateCommitments, generateMerkleRoot };
+export { type BlobCommitments, BlobCommitmentsSchema, COMMITMENT_SCHEMA_VERSION, type ChunksetCommitment, ChunksetCommitmentSchema, expectedChunksetInclusionProofHashes, expectedTotalChunksets, generateCommitments, generateMerkleRoot };

package/dist/core/commitments.mjs

@@ -1,19 +1,285 @@
+// src/core/commitments.ts
+import { Hex as Hex2 } from "@aptos-labs/ts-sdk";
+import { z } from "zod";
+
+// src/core/erasure/constants.ts
+var ERASURE_CODE_PARAMS = {
+  ["ClayCode_16Total_10Data_13Helper" /* ClayCode_16Total_10Data_13Helper */]: {
+    // total chunks (data + parity)
+    erasure_n: 16,
+    // data chunks
+    erasure_k: 10,
+    // helper nodes
+    erasure_d: 13,
+    // enum index
+    enumIndex: 0
+  },
+  ["ClayCode_4Total_2Data_3Helper" /* ClayCode_4Total_2Data_3Helper */]: {
+    // total chunks (data + parity)
+    erasure_n: 4,
+    // data chunks
+    erasure_k: 2,
+    // helper nodes
+    erasure_d: 3,
+    // enum index
+    enumIndex: 1
+  }
+};
+var DEFAULT_ERASURE_N = ERASURE_CODE_PARAMS["ClayCode_16Total_10Data_13Helper" /* ClayCode_16Total_10Data_13Helper */].erasure_n;
+var DEFAULT_ERASURE_K = ERASURE_CODE_PARAMS["ClayCode_16Total_10Data_13Helper" /* ClayCode_16Total_10Data_13Helper */].erasure_k;
+var DEFAULT_ERASURE_D = ERASURE_CODE_PARAMS["ClayCode_16Total_10Data_13Helper" /* ClayCode_16Total_10Data_13Helper */].erasure_d;
+var DEFAULT_ERASURE_M = DEFAULT_ERASURE_N - DEFAULT_ERASURE_K;
+
+// src/core/chunk.ts
+var CHUNK_SIZE_PARAMS = {
+  ["ChunkSet10MiB_Chunk1MiB" /* ChunkSet10MiB_Chunk1MiB */]: {
+    // 1MiB
+    chunkSizeBytes: 1 * 1024 * 1024,
+    // 10MiB
+    chunksetSizeBytes: 10 * 1024 * 1024
+  },
+  ["ChunkSet2MiB_Chunk1MiB" /* ChunkSet2MiB_Chunk1MiB */]: {
+    // 1MiB
+    chunkSizeBytes: 1 * 1024 * 1024,
+    // 2MiB
+    chunksetSizeBytes: 2 * 1024 * 1024
+  }
+};
+var DEFAULT_CHUNK_SIZE_BYTES = CHUNK_SIZE_PARAMS["ChunkSet10MiB_Chunk1MiB" /* ChunkSet10MiB_Chunk1MiB */].chunkSizeBytes;
+var DEFAULT_CHUNKSET_SIZE_BYTES = CHUNK_SIZE_PARAMS["ChunkSet10MiB_Chunk1MiB" /* ChunkSet10MiB_Chunk1MiB */].chunksetSizeBytes;
+var ERASURE_CODE_AND_CHUNK_MAPPING = {
+  ["ClayCode_16Total_10Data_13Helper" /* ClayCode_16Total_10Data_13Helper */]: {
+    ...CHUNK_SIZE_PARAMS.ChunkSet10MiB_Chunk1MiB
+  },
+  ["ClayCode_4Total_2Data_3Helper" /* ClayCode_4Total_2Data_3Helper */]: {
+    ...CHUNK_SIZE_PARAMS.ChunkSet2MiB_Chunk1MiB
+  }
+};
+
+// src/core/utils.ts
 import {
-  BlobCommitmentsSchema,
-  COMMITMENT_SCHEMA_VERSION,
-  ChunksetCommitmentSchema,
-  expectedTotalChunksets,
-  generateCommitments,
-  generateMerkleRoot
-} from "../chunk-RNNJXTX2.mjs";
-import "../chunk-UEZNZBJO.mjs";
-import "../chunk-JTXYKO3U.mjs";
-import "../chunk-AUQDI5BS.mjs";
-import "../chunk-7P6ASYW6.mjs";
+  AccountAddress,
+  Hex
+} from "@aptos-labs/ts-sdk";
+async function* readInChunks(input, chunkSize) {
+  let idx = 0;
+  if (isReadableStream(input)) {
+    const reader = input.getReader();
+    let buffer = new Uint8Array(chunkSize);
+    let bufferWriteOffset = 0;
+    try {
+      while (true) {
+        const { value, done } = await reader.read();
+        if (done) break;
+        if (value === void 0) continue;
+        let srcOffset = 0;
+        while (srcOffset < value.length) {
+          const remainingCapacity = chunkSize - bufferWriteOffset;
+          const bytesToCopy = Math.min(
+            remainingCapacity,
+            value.length - srcOffset
+          );
+          buffer.set(
+            value.subarray(srcOffset, srcOffset + bytesToCopy),
+            bufferWriteOffset
+          );
+          bufferWriteOffset += bytesToCopy;
+          srcOffset += bytesToCopy;
+          if (bufferWriteOffset >= chunkSize) {
+            yield [idx++, buffer];
+            buffer = new Uint8Array(chunkSize);
+            bufferWriteOffset = 0;
+          }
+        }
+      }
+    } finally {
+      reader.releaseLock();
+    }
+    if (bufferWriteOffset > 0) {
+      yield [idx++, buffer.subarray(0, bufferWriteOffset)];
+    }
+    return;
+  }
+  const view = toUint8Array(input);
+  for (let offset = 0; offset < view.byteLength; offset += chunkSize) {
+    yield [
+      idx++,
+      view.subarray(offset, Math.min(offset + chunkSize, view.byteLength))
+    ];
+  }
+}
+function zeroPadBytes(buffer, desiredLength) {
+  if (buffer.byteLength === desiredLength) {
+    return buffer;
+  }
+  if (buffer.byteLength > desiredLength) {
+    return buffer.subarray(0, desiredLength);
+  }
+  const paddedBuffer = new Uint8Array(desiredLength);
+  paddedBuffer.set(buffer);
+  return paddedBuffer;
+}
+async function concatHashes(parts) {
+  const chunks = parts.map((part) => Hex.fromHexInput(part).toUint8Array());
+  const totalLength = chunks.reduce((sum, chunk) => sum + chunk.byteLength, 0);
+  const combined = new Uint8Array(totalLength);
+  let offset = 0;
+  for (const chunk of chunks) {
+    combined.set(chunk, offset);
+    offset += chunk.byteLength;
+  }
+  return Hex.fromHexInput(
+    new Uint8Array(await crypto.subtle.digest("SHA-256", combined))
+  );
+}
+function isReadableStream(value) {
+  return typeof value === "object" && value !== null && "getReader" in value && typeof value.getReader === "function";
+}
+function toUint8Array(view) {
+  return view instanceof Uint8Array ? view : new Uint8Array(view.buffer, view.byteOffset, view.byteLength);
+}
+
+// src/core/commitments.ts
+var COMMITMENT_SCHEMA_VERSION = "1.3";
+var ChunksetCommitmentSchema = z.object({
+  // Chunkset root (vector commitment of child chunks)
+  chunkset_root: z.string(),
+  // the size is known statically from the current configuration
+  chunk_commitments: z.array(z.string())
+}).refine(
+  (data) => {
+    return data.chunk_commitments.length === DEFAULT_ERASURE_K + DEFAULT_ERASURE_M;
+  },
+  {
+    message: `Chunkset must have exactly ${DEFAULT_ERASURE_K + DEFAULT_ERASURE_M} chunks (ERASURE_K + ERASURE_M = ${DEFAULT_ERASURE_K} + ${DEFAULT_ERASURE_M})`,
+    path: ["chunk_commitments"]
+  }
+);
+function expectedTotalChunksets(rawSize, chunksetSize = DEFAULT_CHUNKSET_SIZE_BYTES) {
+  if (chunksetSize <= 0) {
+    throw new Error("chunksetSize must be positive");
+  }
+  if (rawSize === 0) return 1;
+  return Math.ceil(rawSize / chunksetSize);
+}
+function expectedChunksetInclusionProofHashes(numChunksets) {
+  if (numChunksets < 1) {
+    throw new Error("numChunksets must be positive");
+  }
+  return Math.ceil(Math.log2(numChunksets));
+}
+var BlobCommitmentsSchema = z.object({
+  schema_version: z.string(),
+  raw_data_size: z.number(),
+  // FIXME I am not sure about this being here, or if it should be somewhere else
+  blob_merkle_root: z.string(),
+  chunkset_commitments: z.array(ChunksetCommitmentSchema)
+}).refine(
+  (data) => {
+    return expectedTotalChunksets(data.raw_data_size) === data.chunkset_commitments.length;
+  },
+  {
+    message: "Total chunkset count mismatches with raw data size",
+    // FIXME put more details in here
+    path: ["chunkset_commitments"]
+  }
+);
+async function generateMerkleRoot(leafHashes) {
+  if (!leafHashes.length) {
+    throw new Error(
+      "An empty array cannot be used to construct a Merkle tree."
+    );
+  }
+  const zeroArray = new Uint8Array(leafHashes[0].toUint8Array().length);
+  const zeroBytes = Hex2.fromHexInput(zeroArray);
+  let currentLeaves = leafHashes;
+  while (currentLeaves.length > 1) {
+    if (currentLeaves.length % 2 !== 0) {
+      currentLeaves.push(zeroBytes);
+    }
+    const nextLeaves = [];
+    for (let i = 0; i < currentLeaves.length; i += 2) {
+      nextLeaves.push(
+        await concatHashes([
+          currentLeaves[i].toUint8Array(),
+          currentLeaves[i + 1].toUint8Array()
+        ])
+      );
+    }
+    currentLeaves = nextLeaves;
+  }
+  return currentLeaves[0];
+}
+async function generateChunksetCommitments(chunksetIdx, chunksetData, expectedChunksetSize, provider, onChunk) {
+  const { erasure_n } = provider.config;
+  const chunksetPayload = zeroPadBytes(chunksetData, expectedChunksetSize);
+  const { chunks } = provider.encode(chunksetPayload);
+  if (chunks.length !== erasure_n) {
+    throw new Error(
+      `Erasure provider produced ${chunks.length} chunks, expected ${erasure_n}.`
+    );
+  }
+  const chunkRoots = provider.getChunkMerkleRoots();
+  let chunkIdx = 0;
+  for (const chunkData of chunks) {
+    if (onChunk !== void 0) {
+      await onChunk(chunksetIdx, chunkIdx, chunkData);
+    }
+    chunkIdx += 1;
+  }
+  const a = await generateMerkleRoot(
+    chunkRoots.map((a2) => Hex2.fromHexInput(a2))
+  );
+  const entry = {
+    chunkset_root: a.toString(),
+    chunk_commitments: chunkRoots.map(
+      (chunk) => Hex2.fromHexInput(chunk).toString()
+    )
+  };
+  return { h: a, entry };
+}
+async function generateCommitments(provider, fullData, onChunk) {
+  const expectedChunksetSize = provider.config.chunkSizeBytes * provider.config.erasure_k;
+  const chunksetCommitments = [];
+  const chunksetCommitmentHashes = [];
+  let rawDataSize = 0;
+  const chunksetGen = readInChunks(fullData, expectedChunksetSize);
+  for await (const [chunksetIdx, chunksetData] of chunksetGen) {
+    rawDataSize += chunksetData.length;
+    const { h, entry } = await generateChunksetCommitments(
+      chunksetIdx,
+      chunksetData,
+      expectedChunksetSize,
+      provider,
+      onChunk
+    );
+    chunksetCommitments.push(entry);
+    chunksetCommitmentHashes.push(h);
+  }
+  if (rawDataSize === 0) {
+    const zeroChunkset = new Uint8Array(expectedChunksetSize);
+    const { h, entry } = await generateChunksetCommitments(
+      0,
+      zeroChunkset,
+      expectedChunksetSize,
+      provider,
+      onChunk
+    );
+    chunksetCommitments.push(entry);
+    chunksetCommitmentHashes.push(h);
+  }
+  return {
+    schema_version: COMMITMENT_SCHEMA_VERSION,
+    raw_data_size: rawDataSize,
+    blob_merkle_root: (await generateMerkleRoot(chunksetCommitmentHashes)).toString(),
+    chunkset_commitments: chunksetCommitments
+  };
+}
 export {
   BlobCommitmentsSchema,
   COMMITMENT_SCHEMA_VERSION,
   ChunksetCommitmentSchema,
+  expectedChunksetInclusionProofHashes,
   expectedTotalChunksets,
   generateCommitments,
   generateMerkleRoot

package/dist/core/constants.d.ts

@@ -1,12 +1,12 @@
 declare const DEFAULT_PROJECT_NAME = "shelby";
 declare const DEFAULT_PROJECT_DESCRIPTION = "High performance, decentralized storage";
 declare const NetworkToShelbyRPCBaseUrl: {
-    readonly shelbynet: "https://api.shelbynet.shelby.xyz/shelby";
+    readonly shelbynet: "https://shelby.shelbynet.shelby.xyz/shelby";
     readonly netna: undefined;
     readonly devnet: undefined;
     readonly testnet: "https://api.testnet.shelby.xyz/shelby";
     readonly mainnet: undefined;
-    readonly local: undefined;
+    readonly local: "http://localhost:9090";
     readonly custom: undefined;
 };
 /**
@@ -18,7 +18,7 @@ declare const NetworkToShelbyBlobIndexerBaseUrl: {
     readonly devnet: undefined;
     readonly testnet: "https://api.testnet.aptoslabs.com/nocode/v1/public/alias/shelby/testnet/v1/graphql";
     readonly mainnet: undefined;
-    readonly local: undefined;
+    readonly local: "http://localhost:8091/v1/graphql";
     readonly custom: undefined;
 };
 /**

package/dist/core/constants.mjs

@@ -1,19 +1,42 @@
-import {
-  DEFAULT_PROJECT_DESCRIPTION,
-  DEFAULT_PROJECT_NAME,
-  MICROPAYMENTS_DEPLOYER,
-  NetworkToGasStationBaseUrl,
-  NetworkToShelbyBlobIndexerBaseUrl,
-  NetworkToShelbyRPCBaseUrl,
-  SHELBYUSD_FA_METADATA_ADDRESS,
-  SHELBYUSD_TOKEN_ADDRESS,
-  SHELBYUSD_TOKEN_MODULE,
-  SHELBYUSD_TOKEN_NAME,
-  SHELBY_DEPLOYER,
-  TOKEN_DEPLOYER,
-  TOKEN_OBJECT_ADDRESS
-} from "../chunk-MNCQBEMS.mjs";
-import "../chunk-7P6ASYW6.mjs";
+// src/core/constants.ts
+import { Network } from "@aptos-labs/ts-sdk";
+var DEFAULT_PROJECT_NAME = "shelby";
+var DEFAULT_PROJECT_DESCRIPTION = "High performance, decentralized storage";
+var NetworkToShelbyRPCBaseUrl = {
+  [Network.SHELBYNET]: "https://shelby.shelbynet.shelby.xyz/shelby",
+  [Network.NETNA]: void 0,
+  [Network.DEVNET]: void 0,
+  [Network.TESTNET]: "https://api.testnet.shelby.xyz/shelby",
+  [Network.MAINNET]: void 0,
+  [Network.LOCAL]: "http://localhost:9090",
+  [Network.CUSTOM]: void 0
+};
+var NetworkToShelbyBlobIndexerBaseUrl = {
+  [Network.SHELBYNET]: "https://api.shelbynet.aptoslabs.com/nocode/v1/public/alias/shelby/shelbynet/v1/graphql",
+  [Network.NETNA]: void 0,
+  [Network.DEVNET]: void 0,
+  [Network.TESTNET]: "https://api.testnet.aptoslabs.com/nocode/v1/public/alias/shelby/testnet/v1/graphql",
+  [Network.MAINNET]: void 0,
+  [Network.LOCAL]: "http://localhost:8091/v1/graphql",
+  [Network.CUSTOM]: void 0
+};
+var NetworkToGasStationBaseUrl = {
+  [Network.SHELBYNET]: "https://api.shelbynet.shelby.xyz/gs/v1",
+  [Network.NETNA]: void 0,
+  [Network.DEVNET]: void 0,
+  [Network.TESTNET]: "https://api.testnet.shelby.xyz/gs/v1",
+  [Network.MAINNET]: void 0,
+  [Network.LOCAL]: void 0,
+  [Network.CUSTOM]: void 0
+};
+var SHELBY_DEPLOYER = "0x85fdb9a176ab8ef1d9d9c1b60d60b3924f0800ac1de1cc2085fb0b8bb4988e6a";
+var MICROPAYMENTS_DEPLOYER = "0x1ae7275148bf6ef742b658fd9cbcc2e094201606f4a7bc707bab0201da8043ee";
+var TOKEN_DEPLOYER = "0x33009e852be7f93762dd0bf303383c2cb2c5cab7a30d8238ca5f9f177ae75124";
+var TOKEN_OBJECT_ADDRESS = "0x249f5c642a63885ff88a5113b3ba0079840af5a1357706f8c7f3bfc5dd12511f";
+var SHELBYUSD_TOKEN_ADDRESS = TOKEN_OBJECT_ADDRESS;
+var SHELBYUSD_TOKEN_MODULE = "shelby_usd";
+var SHELBYUSD_TOKEN_NAME = "ShelbyUSD";
+var SHELBYUSD_FA_METADATA_ADDRESS = "0x1b18363a9f1fe5e6ebf247daba5cc1c18052bb232efdc4c50f556053922d98e1";
 export {
   DEFAULT_PROJECT_DESCRIPTION,
   DEFAULT_PROJECT_NAME,

package/dist/core/erasure/clay-codes.mjs

@@ -1,8 +1,133 @@
+// src/core/erasure/clay-codes.ts
 import {
-  ClayErasureCodingProvider,
-  buildClayConfig
-} from "../../chunk-OEK24ON7.mjs";
-import "../../chunk-7P6ASYW6.mjs";
+  createDecoder,
+  createEncoder
+} from "@shelby-protocol/clay-codes";
+function getTotalChunks(config) {
+  return config.erasure_n;
+}
+var ClayErasureCodingProvider = class _ClayErasureCodingProvider {
+  config;
+  encoderCache;
+  decoderCache;
+  lastFunction;
+  constructor(config) {
+    this.config = config;
+    this.lastFunction = "none" /* NONE */;
+  }
+  /**
+   * Static factory method to create an initialized ClayErasureCodingProvider
+   */
+  static async create(config) {
+    const provider = new _ClayErasureCodingProvider(config);
+    [provider.encoderCache, provider.decoderCache] = await Promise.all([
+      createEncoder({
+        n: getTotalChunks(config),
+        k: config.erasure_k,
+        d: config.erasure_d,
+        chunkSizeBytes: config.chunkSizeBytes
+      }),
+      createDecoder({
+        n: getTotalChunks(config),
+        k: config.erasure_k,
+        d: config.erasure_d,
+        chunkSizeBytes: config.chunkSizeBytes,
+        erasedChunkIndexes: []
+      })
+    ]);
+    return provider;
+  }
+  encode(data) {
+    const { erasure_k, chunkSizeBytes } = this.config;
+    if (!this.encoderCache) {
+      throw new Error("Encoder cache is missing");
+    }
+    const systematicCapacity = erasure_k * chunkSizeBytes;
+    if (data.byteLength > systematicCapacity) {
+      throw new Error(
+        `Data size ${data.byteLength} bytes exceeds systematic capacity ${systematicCapacity} bytes (erasure_k=${erasure_k} * chunkSizeBytes=${chunkSizeBytes}).`
+      );
+    }
+    if (this.requiresPadding(data.length)) {
+      throw new Error(
+        `Data size ${data.length} bytes does not match systematic capacity ${systematicCapacity} bytes (erasure_k=${erasure_k} * chunkSizeBytes=${chunkSizeBytes}). Provide pre-padded data before encoding.`
+      );
+    }
+    this.lastFunction = "encoded" /* ENCODED */;
+    return this.encoderCache.erasureCode(data);
+  }
+  decode(available, config) {
+    if (!this.decoderCache) {
+      throw new Error("Decoder cache is missing");
+    }
+    const { erasure_k, chunkSizeBytes } = this.config;
+    if (available.length < erasure_k) {
+      throw new Error(
+        `Insufficient available chunks: need at least ${erasure_k}, received ${available.length}.`
+      );
+    }
+    for (let i = 0; i < available.length; i++) {
+      const chunk = available[i];
+      if (chunk.length !== chunkSizeBytes) {
+        throw new Error(
+          `Chunk ${i} size ${chunk.length} bytes does not match expected chunkSizeBytes ${chunkSizeBytes}.`
+        );
+      }
+    }
+    this.lastFunction = "decoded" /* DECODED */;
+    return this.decoderCache.decode(available, config);
+  }
+  getChunkMerkleRoots() {
+    if (this.decoderCache && this.lastFunction === "decoded" /* DECODED */)
+      return this.decoderCache.getChunkMerkleRoots();
+    if (this.encoderCache && this.lastFunction === "encoded" /* ENCODED */)
+      return this.encoderCache.getChunkMerkleRoots();
+    throw new Error(
+      "You must call encode or decode before calling getChunkMerkleRoots"
+    );
+  }
+  /**
+   * Determines if data can be erasure coded as-is or requires padding.
+   *
+   * Data can be erasure coded without padding if its size exactly matches
+   * the total systematic data capacity (k * chunkSizeBytes).
+   *
+   * @param dataSize - Size of the data in bytes
+   * @returns true if data needs padding, false if it can be coded as-is
+   */
+  requiresPadding(dataSize) {
+    const { erasure_k, chunkSizeBytes } = this.config;
+    const systematicCapacity = erasure_k * chunkSizeBytes;
+    return dataSize !== systematicCapacity;
+  }
+};
+function buildClayConfig(input) {
+  const { erasure_n, erasure_k, erasure_d, chunkSizeBytes, enumIndex } = input;
+  if (erasure_n <= 0)
+    throw new Error("erasure_n (total number of chunks) must be > 0");
+  if (erasure_k <= 0)
+    throw new Error("erasure_k (number of data chunks) must be > 0");
+  if (erasure_k >= erasure_n)
+    throw new Error(
+      `erasure_k (${erasure_k}) must be < erasure_n (${erasure_n})`
+    );
+  if (erasure_d <= erasure_k)
+    throw new Error(
+      `erasure_d (${erasure_d}) must be > erasure_k (${erasure_k})`
+    );
+  if (erasure_d >= erasure_n)
+    throw new Error(
+      `erasure_d (${erasure_d}) must be < erasure_n (${erasure_n})`
+    );
+  if (chunkSizeBytes <= 0) throw new Error("chunkSizeBytes must be > 0");
+  return {
+    erasure_n,
+    erasure_k,
+    erasure_d,
+    chunkSizeBytes,
+    enumIndex
+  };
+}
 export {
   ClayErasureCodingProvider,
   buildClayConfig

package/dist/core/erasure/constants.d.ts

@@ -36,6 +36,21 @@ declare const ERASURE_CODE_PARAMS: {
         readonly enumIndex: 1;
     };
 };
+/**
+ * Look up an erasure coding scheme by its total-chunk count (`erasure_n`).
+ * Returns the `[scheme, params]` entry, or `undefined` if no scheme matches.
+ * Shared by callers that need to recover a scheme's `erasure_k`/`erasure_d`
+ * (or its key for {@link ERASURE_CODE_AND_CHUNK_MAPPING}) from `erasure_n`
+ * alone, so the lookup stays in one place as schemes are added.
+ */
+declare function findErasureSchemeByErasureN(erasureN: number): [ErasureCodingScheme, ErasureSchemeParams] | undefined;
+/**
+ * Number of storage-provider acknowledgements required to finalize a blob on
+ * chain: the erasure scheme's helper-node count (`erasure_d`), recovered from
+ * the scheme's total-chunk count (`erasure_n`). Throws if `erasureN` matches no
+ * known scheme.
+ */
+declare function requiredAckCount(erasureN: number): number;
 /**
  * The total number of chunks (data + parity) in the erasure coding scheme.
  */
@@ -57,4 +72,4 @@ declare const DEFAULT_ERASURE_M: number;
  */
 declare const DEFAULT_SAMPLE_SIZE = 1024;
 
-export { DEFAULT_ERASURE_D, DEFAULT_ERASURE_K, DEFAULT_ERASURE_M, DEFAULT_ERASURE_N, DEFAULT_SAMPLE_SIZE, ERASURE_CODE_PARAMS, type ErasureCodeParams, ErasureCodingScheme, type ErasureSchemeParams };
+export { DEFAULT_ERASURE_D, DEFAULT_ERASURE_K, DEFAULT_ERASURE_M, DEFAULT_ERASURE_N, DEFAULT_SAMPLE_SIZE, ERASURE_CODE_PARAMS, type ErasureCodeParams, ErasureCodingScheme, type ErasureSchemeParams, findErasureSchemeByErasureN, requiredAckCount };