@shelby-protocol/sdk 0.0.1-experimental.4 → 0.0.1

package/README.md

@@ -29,6 +29,47 @@ import { ShelbyBlob } from '@shelby-protocol/sdk/browser';
 // Your code here...
 ```
 
+### Working with Erasure Coding Providers
+
+The SDK supports two patterns for managing erasure coding providers:
+
+#### Default Pattern (Recommended for most users)
+
+```ts
+import { ShelbyClient } from '@shelby-protocol/sdk';
+
+// Provider is created internally on first use
+const client = new ShelbyClient(config);
+
+// The client will automatically create and manage the provider
+await client.upload({
+  blobData: data,
+  signer: account,
+  blobName: "example.txt",
+  expirationMicros: Date.now() * 1000 + 3600_000_000,
+});
+```
+
+#### Shared Provider Pattern (For advanced use cases)
+
+When working with multiple clients (e.g., different networks), you can share a single provider instance:
+
+```ts
+import { ShelbyClient, ClayErasureCodingProvider } from '@shelby-protocol/sdk';
+
+// Create a single provider instance
+const provider = await ClayErasureCodingProvider.create();
+
+// Share it across multiple clients
+const mainnetClient = new ShelbyClient(mainnetConfig, provider);
+const devnetClient = new ShelbyClient(devnetConfig, provider);
+const testnetClient = new ShelbyClient(testnetConfig, provider);
+
+// All clients use the same provider instance
+await mainnetClient.upload({ /* ... */ });
+await devnetClient.upload({ /* ... */ });
+```
+
 ## Peer Dependencies
 
 - `@aptos-labs/ts-sdk`

package/dist/browser/index.d.ts

@@ -1,14 +1,23 @@
 export { ShelbyBlob, createBlobKey } from '../core/blobs.js';
+export { CHUNK_SIZE_PARAMS, ChunkSizeScheme, DEFAULT_CHUNKSET_SIZE_BYTES, DEFAULT_CHUNK_SIZE_BYTES, ERASURE_CODE_AND_CHUNK_MAPPING } from '../core/chunk.js';
 export { ShelbyBlobClient } from '../core/clients/ShelbyBlobClient.js';
-export { ShelbyClient } from '../core/clients/ShelbyClient.js';
-export { ShelbyClientConfig } from '../core/clients/ShelbyClientConfig.js';
+export { ShelbyClient, UploadOptions } from '../core/clients/ShelbyClient.js';
+export { ShelbyClientConfig, ShelbyIndexerConfig, ShelbyRPCConfig } from '../core/clients/ShelbyClientConfig.js';
 export { ShelbyRPCClient } from '../core/clients/ShelbyRPCClient.js';
-export { BlobCommitments, BlobCommitmentsSchema, ChunksetCommitment, ChunksetCommitmentSchema, generateCommitments } from '../core/commitments.js';
-export { CHUNKSET_SIZE_BYTES, DEFAULT_PROJECT_DESCRIPTION, DEFAULT_PROJECT_NAME, DEFAULT_SHELBY_BASE_URL, ERASURE_K, ERASURE_M, SHELBY_DEPLOYER, TOKEN_DEPLOYER, TOKEN_OBJECT_ADDRESS, getChunkSizeBytes, getChunksetSizeBytes } from '../core/constants.js';
-export { erasureEncode } from '../core/erasure.js';
+export { BlobCommitments, BlobCommitmentsSchema, ChunksetCommitment, ChunksetCommitmentSchema, GenerateCommitmentsOptions, expectedTotalChunksets, generateCommitments } from '../core/commitments.js';
+export { DEFAULT_PROJECT_DESCRIPTION, DEFAULT_PROJECT_NAME, NetworkToShelbyBlobIndexerBaseUrl, NetworkToShelbyRPCBaseUrl, SHELBYUSD_TOKEN_ADDRESS, SHELBYUSD_TOKEN_MODULE, SHELBYUSD_TOKEN_NAME, SHELBYUSD_TOKEN_TYPE, SHELBY_DEPLOYER, TOKEN_DEPLOYER, TOKEN_OBJECT_ADDRESS } from '../core/constants.js';
+export { C as ClayErasureCodingProvider, D as DecodeConfig, E as ErasureCodingConfig, a as ErasureCodingProvider, R as ReedSolomonErasureCodingProvider } from '../clay-codes-Ce9EmXfa.js';
+export { DEFAULT_ERASURE_D, DEFAULT_ERASURE_K, DEFAULT_ERASURE_M, DEFAULT_ERASURE_N, ERASURE_CODE_PARAMS, ErasureCodeParams, ErasureCodingScheme, ErasureSchemeParams } from '../core/erasure/constants.js';
+export { createDefaultErasureCodingProvider } from '../core/erasure/default.js';
 export { BlobName, BlobNameSchema, ChunkKey, allChunksForBlob, roundSize } from '../core/layout.js';
-export { BlobChunk, BlobEncoding, BlobMetadata, ChunkLocation, ClayEncoding, PendingChunkLocation, SignedChunkCommitment, StoredChunkLocation } from '../core/types/blobs.js';
-export { EncodingOptions } from '../core/types/encodings.js';
-export { concatHashes, readInChunks, zeroPadBuffer } from '../core/utils.js';
+export { ShelbyNetwork, isShelbyNetwork, shelbyNetworks } from '../core/networks.js';
+export { ShelbyIndexerClient, createShelbyIndexerClient, getShelbyIndexerClient } from '../core/operations/index.js';
+export { BlobActivity, BlobActivityType, BlobEncoding, BlobMetadata, ClayEncoding } from '../core/types/blobs.js';
+export { StorageProviderInfo } from '../core/types/storage_providers.js';
+export { buildRequestUrl, concatHashes, readInChunks, zeroPadBytes } from '../core/utils.js';
 import '@aptos-labs/ts-sdk';
 import 'zod';
+import '../core/operations/generated/sdk.js';
+import 'graphql';
+import 'graphql-request';
+import '@shelby-protocol/clay-codes';

package/dist/browser/index.mjs

@@ -1,65 +1,110 @@
-import "../chunk-PLUDE5C3.mjs";
+import "../chunk-TUANYVZQ.mjs";
+import "../chunk-RNXGC54D.mjs";
 import "../chunk-MWDW4ROU.mjs";
 import "../chunk-ZHXCVRZX.mjs";
-import "../chunk-IHTPXUYI.mjs";
-import "../chunk-QKT5R735.mjs";
+import "../chunk-MQUVYMNQ.mjs";
 import {
   ShelbyClient
-} from "../chunk-QM5BVKLD.mjs";
+} from "../chunk-6MDQI7PW.mjs";
 import {
   ShelbyBlobClient
-} from "../chunk-B3CB2YEO.mjs";
+} from "../chunk-XGMJ4CG4.mjs";
+import "../chunk-Z7RFCADT.mjs";
 import {
   ShelbyRPCClient
-} from "../chunk-2FF5FICZ.mjs";
+} from "../chunk-JSR44EDC.mjs";
+import {
+  createShelbyIndexerClient,
+  getShelbyIndexerClient
+} from "../chunk-75VHXY5P.mjs";
+import "../chunk-DLMDDEWF.mjs";
+import "../chunk-RBFWGDMY.mjs";
+import "../chunk-I6NG5GNL.mjs";
 import {
   createBlobKey
-} from "../chunk-QEMIORTL.mjs";
+} from "../chunk-OTBLZL2S.mjs";
 import {
   BlobCommitmentsSchema,
   ChunksetCommitmentSchema,
+  expectedTotalChunksets,
   generateCommitments
-} from "../chunk-G263DBCY.mjs";
+} from "../chunk-LTV26KU4.mjs";
 import {
+  buildRequestUrl,
   concatHashes,
   readInChunks,
-  zeroPadBuffer
-} from "../chunk-5Z3RVWU3.mjs";
+  zeroPadBytes
+} from "../chunk-KBUWZXFA.mjs";
 import {
-  erasureEncode
-} from "../chunk-P7BVGLTV.mjs";
+  DEFAULT_PROJECT_DESCRIPTION,
+  DEFAULT_PROJECT_NAME,
+  NetworkToShelbyBlobIndexerBaseUrl,
+  NetworkToShelbyRPCBaseUrl,
+  SHELBYUSD_TOKEN_ADDRESS,
+  SHELBYUSD_TOKEN_MODULE,
+  SHELBYUSD_TOKEN_NAME,
+  SHELBYUSD_TOKEN_TYPE,
+  SHELBY_DEPLOYER,
+  TOKEN_DEPLOYER,
+  TOKEN_OBJECT_ADDRESS
+} from "../chunk-HPVCKAN2.mjs";
 import {
   BlobNameSchema,
   ChunkKey,
   allChunksForBlob,
   roundSize
-} from "../chunk-GGYTHP5F.mjs";
+} from "../chunk-FIFKKWXV.mjs";
 import {
-  CHUNKSET_SIZE_BYTES,
-  DEFAULT_PROJECT_DESCRIPTION,
-  DEFAULT_PROJECT_NAME,
-  DEFAULT_SHELBY_BASE_URL,
-  ERASURE_K,
-  ERASURE_M,
-  SHELBY_DEPLOYER,
-  TOKEN_DEPLOYER,
-  TOKEN_OBJECT_ADDRESS,
-  getChunkSizeBytes,
-  getChunksetSizeBytes
-} from "../chunk-D2FERD4A.mjs";
-import "../chunk-I6NG5GNL.mjs";
+  CHUNK_SIZE_PARAMS,
+  ChunkSizeScheme,
+  ClayErasureCodingProvider,
+  DEFAULT_CHUNKSET_SIZE_BYTES,
+  DEFAULT_CHUNK_SIZE_BYTES,
+  ERASURE_CODE_AND_CHUNK_MAPPING,
+  createDefaultErasureCodingProvider
+} from "../chunk-APML3CGJ.mjs";
+import {
+  ReedSolomonErasureCodingProvider
+} from "../chunk-3ZDXWPYC.mjs";
+import {
+  DEFAULT_ERASURE_D,
+  DEFAULT_ERASURE_K,
+  DEFAULT_ERASURE_M,
+  DEFAULT_ERASURE_N,
+  ERASURE_CODE_PARAMS,
+  ErasureCodingScheme
+} from "../chunk-ZPW742E7.mjs";
+import {
+  isShelbyNetwork,
+  shelbyNetworks
+} from "../chunk-VRLIOKWG.mjs";
 import "../chunk-7P6ASYW6.mjs";
 export {
   BlobCommitmentsSchema,
   BlobNameSchema,
-  CHUNKSET_SIZE_BYTES,
+  CHUNK_SIZE_PARAMS,
   ChunkKey,
+  ChunkSizeScheme,
   ChunksetCommitmentSchema,
+  ClayErasureCodingProvider,
+  DEFAULT_CHUNKSET_SIZE_BYTES,
+  DEFAULT_CHUNK_SIZE_BYTES,
+  DEFAULT_ERASURE_D,
+  DEFAULT_ERASURE_K,
+  DEFAULT_ERASURE_M,
+  DEFAULT_ERASURE_N,
   DEFAULT_PROJECT_DESCRIPTION,
   DEFAULT_PROJECT_NAME,
-  DEFAULT_SHELBY_BASE_URL,
-  ERASURE_K,
-  ERASURE_M,
+  ERASURE_CODE_AND_CHUNK_MAPPING,
+  ERASURE_CODE_PARAMS,
+  ErasureCodingScheme,
+  NetworkToShelbyBlobIndexerBaseUrl,
+  NetworkToShelbyRPCBaseUrl,
+  ReedSolomonErasureCodingProvider,
+  SHELBYUSD_TOKEN_ADDRESS,
+  SHELBYUSD_TOKEN_MODULE,
+  SHELBYUSD_TOKEN_NAME,
+  SHELBYUSD_TOKEN_TYPE,
   SHELBY_DEPLOYER,
   ShelbyBlobClient,
   ShelbyClient,
@@ -67,13 +112,17 @@ export {
   TOKEN_DEPLOYER,
   TOKEN_OBJECT_ADDRESS,
   allChunksForBlob,
+  buildRequestUrl,
   concatHashes,
   createBlobKey,
-  erasureEncode,
+  createDefaultErasureCodingProvider,
+  createShelbyIndexerClient,
+  expectedTotalChunksets,
   generateCommitments,
-  getChunkSizeBytes,
-  getChunksetSizeBytes,
+  getShelbyIndexerClient,
+  isShelbyNetwork,
   readInChunks,
   roundSize,
-  zeroPadBuffer
+  shelbyNetworks,
+  zeroPadBytes
 };

package/dist/chunk-3ZDXWPYC.mjs

@@ -0,0 +1,65 @@
+// src/core/erasure/reed-solomon.ts
+import { createWasmReedSolomonBinding } from "@shelby-protocol/reed-solomon";
+var DEFAULT_ERASURE_K = 10;
+var DEFAULT_ERASURE_N = 16;
+var DEFAULT_CHUNK_SIZE_BYTES = 2 * 1024 * 1024;
+var ReedSolomonErasureCodingProvider = class {
+  config;
+  constructor(options) {
+    const erasure_k = options?.erasure_k ?? DEFAULT_ERASURE_K;
+    const erasure_n = options?.erasure_n ?? DEFAULT_ERASURE_N;
+    const chunkSizeBytes = options?.chunkSizeBytes ?? DEFAULT_CHUNK_SIZE_BYTES;
+    if (erasure_k <= 0)
+      throw new Error("erasure_k (number of data chunks) must be > 0");
+    if (erasure_n <= erasure_k)
+      throw new Error(
+        `erasure_n (${erasure_n}) must be > erasure_k (${erasure_k})`
+      );
+    if (chunkSizeBytes <= 0) throw new Error("chunkSizeBytes must be > 0");
+    this.config = {
+      erasure_n,
+      erasure_k,
+      chunkSizeBytes
+    };
+  }
+  encode(data) {
+    const { erasure_k, erasure_n, chunkSizeBytes } = this.config;
+    const erasure_m = erasure_n - erasure_k;
+    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 (data.byteLength !== systematicCapacity) {
+      throw new Error(
+        `Data size ${data.byteLength} bytes does not match systematic capacity ${systematicCapacity} bytes (erasure_k=${erasure_k} * chunkSizeBytes=${chunkSizeBytes}). Provide pre-padded data before encoding.`
+      );
+    }
+    const reedSolomon = createWasmReedSolomonBinding();
+    const shards = new Uint8Array(
+      systematicCapacity + erasure_m * chunkSizeBytes
+    );
+    shards.set(data, 0);
+    reedSolomon.encode(shards, erasure_k, erasure_m);
+    const chunks = new Array(erasure_n);
+    for (let idx = 0; idx < erasure_n; idx++) {
+      const start = idx * chunkSizeBytes;
+      chunks[idx] = shards.slice(start, start + chunkSizeBytes);
+    }
+    return {
+      chunks,
+      systematic: chunks.slice(0, erasure_k),
+      parity: chunks.slice(erasure_k)
+    };
+  }
+  decode(_available, _config) {
+    throw new Error(
+      "ReedSolomonErasureCodingProvider does not implement decode"
+    );
+  }
+};
+
+export {
+  ReedSolomonErasureCodingProvider
+};

package/dist/chunk-6MDQI7PW.mjs

@@ -0,0 +1,177 @@
+import {
+  ShelbyBlobClient
+} from "./chunk-XGMJ4CG4.mjs";
+import {
+  ShelbyRPCClient
+} from "./chunk-JSR44EDC.mjs";
+import {
+  getAptosConfig
+} from "./chunk-RBFWGDMY.mjs";
+import {
+  generateCommitments
+} from "./chunk-LTV26KU4.mjs";
+import {
+  NetworkToShelbyRPCBaseUrl
+} from "./chunk-HPVCKAN2.mjs";
+import {
+  ClayErasureCodingProvider
+} from "./chunk-APML3CGJ.mjs";
+
+// src/core/clients/ShelbyClient.ts
+import {
+  Aptos
+} from "@aptos-labs/ts-sdk";
+var ShelbyClient = class {
+  /**
+   * The coordination client is used to interact with the Aptos blockchain which handles the commitments
+   * and metadata for blobs.
+   */
+  coordination;
+  /**
+   * The RPC client is used to interact with the Shelby RPC node which can be responsible for storing,
+   * confirming, and retrieving blobs from the storage layer.
+   *
+   * If not provided, the default RPC client will be created.
+   */
+  rpc;
+  /**
+   * The configuration for the Shelby client.
+   */
+  config;
+  /**
+   * The Aptos client.
+   *
+   * If not provided, a default Aptos client will be created.
+   */
+  aptos;
+  /**
+   * The erasure coding provider used for encoding/decoding operations.
+   * Lazily initialized on first use if not provided.
+   */
+  _provider;
+  /**
+   * Creates a new ShelbyClient instance for interacting with the Shelby Protocol.
+   * This client combines blockchain operations (via coordination) and storage operations (via RPC).
+   *
+   * @param config - The client configuration object.
+   * @param config.aptos.config - The Aptos network configuration.
+   * @param config.shelby.rpc.baseUrl - The base URL of the Shelby RPC node (optional, defaults to devnet).
+   * @param config.shelby.indexer - The indexer configuration for GraphQL queries.
+   * @param provider - Optional erasure coding provider for encoding/decoding operations.
+   *                   If not provided, a ClayErasureCodingProvider will be created on first use.
+   *                   Pass a shared provider to reuse across multiple clients.
+   *
+   * @example
+   * ```typescript
+   * // Basic usage (provider created automatically)
+   * const client = new ShelbyClient({
+   *   network: Network.SHELBYNET,
+   * });
+   *
+   * // Advanced: Share provider across multiple clients
+   * const provider = await ClayErasureCodingProvider.create();
+   * const mainnetClient = new ShelbyClient(mainnetConfig, provider);
+   * const devnetClient = new ShelbyClient(devnetConfig, provider);
+   * ```
+   */
+  constructor(config, provider) {
+    this.config = config;
+    this.aptos = new Aptos(getAptosConfig(config));
+    this.coordination = new ShelbyBlobClient(config);
+    this.rpc = new ShelbyRPCClient(config);
+    this._provider = provider;
+  }
+  /**
+   * Get the erasure coding provider, creating it if necessary.
+   * This allows lazy initialization for users who don't provide a provider.
+   */
+  async getProvider() {
+    if (!this._provider) {
+      this._provider = await ClayErasureCodingProvider.create();
+    }
+    return this._provider;
+  }
+  /**
+   * The base URL for the Shelby RPC node.
+   */
+  get baseUrl() {
+    return this.config.rpc?.baseUrl ?? NetworkToShelbyRPCBaseUrl.shelbynet;
+  }
+  /**
+   * Uploads a blob to the Shelby network.
+   * This method handles the complete upload flow including commitment generation,
+   * blockchain registration, and storage upload.
+   *
+   * @param params.blobData - The raw data to upload as a Uint8Array.
+   * @param params.signer - The account that signs and pays for the transaction.
+   * @param params.blobName - The name/path of the blob (e.g. "folder/file.txt").
+   * @param params.expirationMicros - The expiration time in microseconds since Unix epoch.
+   * @param params.options - Optional upload configuration.
+   * @param params.options.chunksetSizeBytes - Custom chunkset size.
+   * @param params.options.build - Additional Aptos transaction options.
+   *
+   * @returns The transaction and generated blob commitments (when implemented).
+   *
+   * @example
+   * ```typescript
+   * await client.upload({
+   *   blobData: Buffer.from("Hello, World!"),
+   *   signer: account,
+   *   blobName: "hello.txt",
+   *   expirationMicros: Date.now() * 1000 + 86400_000_000 // 24 hours from now
+   * });
+   * ```
+   */
+  async upload(params) {
+    const existingBlobMetadata = await this.coordination.getBlobMetadata({
+      account: params.signer.accountAddress,
+      name: params.blobName
+    });
+    if (!existingBlobMetadata) {
+      const provider = await this.getProvider();
+      const blobCommitments = await generateCommitments(
+        provider,
+        params.blobData
+      );
+      const { transaction: pendingRegisterBlobTransaction } = await this.coordination.registerBlob({
+        account: params.signer,
+        blobName: params.blobName,
+        blobMerkleRoot: blobCommitments.blob_merkle_root,
+        size: params.blobData.length,
+        expirationMicros: params.expirationMicros
+      });
+      await this.coordination.aptos.waitForTransaction({
+        transactionHash: pendingRegisterBlobTransaction.hash
+      });
+    }
+    await this.rpc.putBlob({
+      account: params.signer.accountAddress,
+      blobName: params.blobName,
+      blobData: params.blobData
+    });
+  }
+  /**
+   * Downloads a blob from the Shelby RPC node.
+   *
+   * @param params.account - The account namespace the blob is stored in (e.g. "0x1")
+   * @param params.blobName - The name of the blob (e.g. "foo/bar")
+   * @param params.range - The range of the blob to download.
+   *
+   * @returns A `ShelbyBlob` object containing the blob data.
+   *
+   * @example
+   * ```typescript
+   * const blob = await client.download({
+   *   account,
+   *   blobName: "foo/bar.txt",
+   * });
+   * ```
+   */
+  async download(params) {
+    return await this.rpc.getBlob(params);
+  }
+};
+
+export {
+  ShelbyClient
+};

package/dist/chunk-75VHXY5P.mjs

@@ -0,0 +1,48 @@
+import {
+  getSdk
+} from "./chunk-DLMDDEWF.mjs";
+import {
+  getAptosConfig
+} from "./chunk-RBFWGDMY.mjs";
+import {
+  NetworkToShelbyBlobIndexerBaseUrl
+} from "./chunk-HPVCKAN2.mjs";
+
+// src/core/operations/index.ts
+import { Network } from "@aptos-labs/ts-sdk";
+import { GraphQLClient } from "graphql-request";
+function createShelbyIndexerClient(baseUrl, options) {
+  const graphqlClient = new GraphQLClient(baseUrl, options);
+  return getSdk(graphqlClient);
+}
+function getShelbyIndexerClient(config) {
+  const aptosConfig = config.aptos ?? getAptosConfig(config);
+  let { apiKey, baseUrl } = config.indexer ?? {};
+  if (!baseUrl) {
+    switch (aptosConfig?.network) {
+      // TODO: Add endpoints for core networks
+      case Network.MAINNET:
+      case Network.TESTNET:
+      case Network.DEVNET:
+      case Network.SHELBYNET:
+        baseUrl = NetworkToShelbyBlobIndexerBaseUrl[aptosConfig.network];
+        break;
+    }
+  }
+  if (baseUrl === void 0) {
+    throw new Error(
+      "The ShelbyClientConfig does not support the Shelby indexer. Please configure the endpoint in the ShelbyClientConfig.indexer.endpoint or provide a supported Aptos network."
+    );
+  }
+  return createShelbyIndexerClient(baseUrl, {
+    headers: {
+      ...apiKey ? { Authorization: `Bearer ${apiKey}` } : {},
+      "x-aptos-client": "shelby-ts-sdk"
+    }
+  });
+}
+
+export {
+  createShelbyIndexerClient,
+  getShelbyIndexerClient
+};