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

package/dist/chunk-XGMJ4CG4.mjs

@@ -0,0 +1,384 @@
+import {
+  getShelbyIndexerClient
+} from "./chunk-75VHXY5P.mjs";
+import {
+  getAptosConfig
+} from "./chunk-RBFWGDMY.mjs";
+import {
+  createBlobKey
+} from "./chunk-OTBLZL2S.mjs";
+import {
+  expectedTotalChunksets
+} from "./chunk-LTV26KU4.mjs";
+import {
+  SHELBY_DEPLOYER
+} from "./chunk-HPVCKAN2.mjs";
+import {
+  DEFAULT_CHUNKSET_SIZE_BYTES,
+  ERASURE_CODE_AND_CHUNK_MAPPING
+} from "./chunk-APML3CGJ.mjs";
+import {
+  ERASURE_CODE_PARAMS
+} from "./chunk-ZPW742E7.mjs";
+
+// src/core/clients/ShelbyBlobClient.ts
+import {
+  AccountAddress,
+  Aptos,
+  AptosConfig,
+  Hex,
+  MoveVector
+} from "@aptos-labs/ts-sdk";
+var ShelbyBlobClient = class _ShelbyBlobClient {
+  aptos;
+  deployer;
+  indexer;
+  /**
+   * The ShelbyBlobClient is used to interact with the Shelby contract on the Aptos blockchain. This
+   * includes functions for registering blob commitments and retrieving blob metadata.
+   *
+   * @param config - The client configuration object.
+   * @param config.network - The Shelby network to use.
+   *
+   * @example
+   * ```typescript
+   * const blobClient = new ShelbyBlobClient({
+   *   aptos: {
+   *     network: Network.SHELBYNET,
+   *     clientConfig: {
+   *       API_KEY: "AG-***",
+   *     },
+   *   },
+   * });
+   * ```
+   */
+  constructor(config) {
+    const baseAptosConfig = getAptosConfig(config);
+    const aptosConfig = new AptosConfig({
+      ...baseAptosConfig,
+      clientConfig: {
+        ...baseAptosConfig.clientConfig,
+        // Only use top-level apiKey if no API_KEY is already provided in Aptos settings
+        API_KEY: baseAptosConfig.clientConfig?.API_KEY ?? config.apiKey
+      }
+    });
+    this.aptos = new Aptos(aptosConfig);
+    this.deployer = config.deployer ?? AccountAddress.fromString(SHELBY_DEPLOYER);
+    this.indexer = getShelbyIndexerClient(config);
+  }
+  /**
+   * Retrieves the blob metadata from the blockchain. If it does not exist,
+   * returns `undefined`.
+   *
+   * @param params.account - The account namespace the blob is stored in (e.g. "0x1")
+   * @param params.name - The name of the blob (e.g. "foo/bar")
+   * @returns The blob metadata.
+   *
+   * @example
+   * ```typescript
+   * const metadata = await client.getBlobMetadata({
+   *   account: AccountAddress.fromString("0x1"),
+   *   name: "foo/bar.txt",
+   * });
+   * ```
+   */
+  async getBlobMetadata(params) {
+    try {
+      const rawMetadata = await this.aptos.view({
+        payload: {
+          function: `${this.deployer.toString()}::global_metadata::get_blob_metadata`,
+          functionArguments: [
+            createBlobKey({
+              account: params.account,
+              blobName: params.name
+            })
+          ]
+        }
+      });
+      if (!rawMetadata?.[0]?.vec?.[0]) {
+        return void 0;
+      }
+      const metadata = rawMetadata[0].vec[0];
+      let encoding;
+      if (metadata.encoding.__variant__ === "ClayCode_16Total_10Data_13Helper") {
+        encoding = {
+          variant: "clay",
+          ...ERASURE_CODE_PARAMS[metadata.encoding.__variant__],
+          ...ERASURE_CODE_AND_CHUNK_MAPPING[metadata.encoding.__variant__]
+        };
+      } else {
+        throw new Error(
+          "Could not parse encoding from Shelby Smart Contract, this SDK is out of date."
+        );
+      }
+      return {
+        blobMerkleRoot: Hex.fromHexInput(
+          metadata.blob_commitment
+        ).toUint8Array(),
+        owner: AccountAddress.fromString(metadata.owner),
+        name: params.name,
+        size: Number(metadata.blob_size),
+        encoding,
+        expirationMicros: metadata.expiration_micros,
+        sliceAddress: AccountAddress.fromString(metadata.slice.inner),
+        isWritten: metadata.is_written
+      };
+    } catch (error) {
+      if (error instanceof Error && // Depending on the network, the error message may show up differently.
+      (error.message?.includes("sub_status: Some(404)") || error.message?.includes("EBLOB_NOT_FOUND"))) {
+        return void 0;
+      }
+      throw error;
+    }
+  }
+  /**
+   * Retrieves all the blobs and their metadata for an account from the
+   * blockchain.
+   *
+   * @param params.account - The account namespace the blobs are stored in (e.g. "0x1")
+   * @param params.pagination (optional) - The pagination options.
+   * @param params.orderBy (optional) - The order by clause to sort the blobs by.
+   * @returns The blob metadata for all the blobs for the account.
+   *
+   * @example
+   * ```typescript
+   * // BlobMetadata[]
+   * const blobs = await client.getAccountBlobs({
+   *   account: AccountAddress.fromString("0x1"),
+   * });
+   * ```
+   */
+  getAccountBlobs(params) {
+    return this.getBlobs({
+      where: { owner: { _eq: AccountAddress.from(params.account).toString() } },
+      pagination: params.pagination,
+      orderBy: params.orderBy
+    });
+  }
+  /**
+   * Retrieves blobs and their metadata from the blockchain.
+   *
+   * @param params.where (optional) - The where clause to filter the blobs by.
+   * @param params.pagination (optional) - The pagination options.
+   * @param params.orderBy (optional) - The order by clause to sort the blobs by.
+   * @returns The blob metadata for all the blobs that match the where clause.
+   *
+   * @example
+   * ```typescript
+   * // BlobMetadata[]
+   * const blobs = await client.getBlobs({
+   *   where: { owner: { _eq: AccountAddress.fromString("0x1").toString() } },
+   * });
+   * ```
+   */
+  async getBlobs(params = {}) {
+    const { limit, offset } = params.pagination ?? {};
+    const { orderBy, where } = params;
+    const { blobs } = await this.indexer.getBlobs({
+      where,
+      limit,
+      offset,
+      orderBy
+    });
+    return blobs.map(
+      (blob) => ({
+        owner: AccountAddress.from(blob.owner),
+        name: blob.blob_name,
+        blobMerkleRoot: Hex.fromHexInput(blob.blob_commitment).toUint8Array(),
+        size: blob.size,
+        // TODO: Add encoding when supported in NCI
+        encoding: {
+          variant: "clay",
+          ...ERASURE_CODE_PARAMS.ClayCode_16Total_10Data_13Helper,
+          ...ERASURE_CODE_AND_CHUNK_MAPPING.ClayCode_16Total_10Data_13Helper
+        },
+        expirationMicros: blob.expires_at,
+        sliceAddress: AccountAddress.from(blob.slice_address),
+        isWritten: blob.is_written
+      })
+    );
+  }
+  async getBlobActivities(params) {
+    const { limit, offset } = params.pagination ?? {};
+    const { orderBy, where } = params;
+    const { blob_activities } = await this.indexer.getBlobActivities({
+      where,
+      limit,
+      offset,
+      orderBy
+    });
+    const activityTypeMapping = {
+      [`${this.deployer.toStringLong()}::global_metadata::BlobRegisteredEvent`]: "register_blob",
+      [`${this.deployer.toStringLong()}::global_metadata::BlobDeletedEvent`]: "delete_blob",
+      [`${this.deployer.toStringLong()}::global_metadata::BlobExpirationExtendedEvent`]: "extend_blob_expiration",
+      [`${this.deployer.toStringLong()}::global_metadata::BlobWrittenEvent`]: "write_blob"
+    };
+    return blob_activities.map(
+      (activity) => ({
+        blobName: activity.blob_name,
+        accountAddress: AccountAddress.from(
+          activity.blob_name.substring(1, 65)
+        ),
+        type: activityTypeMapping[activity.event_type] ?? "unknown",
+        eventType: activity.event_type,
+        eventIndex: activity.event_index,
+        transactionHash: activity.transaction_hash,
+        transactionVersion: activity.transaction_version,
+        timestamp: activity.timestamp
+      })
+    );
+  }
+  /**
+   * Retrieves the blob chunks for a given blob from the blockchain. The blob chunk will contain
+   * the commitment, the storage provider location, and the status of the chunk (stored or pending).
+   *
+   * @deprecated Will need to get reworked when we are acking blobs from storage providers.
+   *
+   * @param params.account - The account namespace the blob is stored in (e.g. "0x1")
+   * @param params.name - The name of the blob (e.g. "foo/bar")
+   * @returns The chunks that make up the blob.
+   *
+   * @example
+   * ```typescript
+   * // BlobChunk[]
+   * const chunks = await client.getBlobChunks({
+   *   account: AccountAddress.fromString("0x1"),
+   *   name: "foo/bar.txt",
+   * });
+   *
+   * const isStored = chunks.every((c) => c.location.variant === "stored");
+   * ```
+   */
+  getBlobChunks(_params) {
+    throw new Error("Not implemented");
+  }
+  /**
+   * Registers a blob on the blockchain by writing its merkle root and metadata.
+   *
+   * @param params.account - The account that is signing and paying for the transaction.
+   * @param params.blobName - The name/path of the blob (e.g. "foo/bar.txt").
+   * @param params.blobMerkleRoot - The merkle root of the blob commitments.
+   * @param params.size - The size of the blob in bytes.
+   * @param params.expirationMicros - The expiration time of the blob in microseconds.
+   * @param params.options - Optional transaction building options.
+   * @param params.options.chunksetSizeBytes - Custom chunkset size (defaults to DEFAULT_CHUNKSET_SIZE_BYTES).
+   * @param params.options.build - Additional Aptos transaction building options.
+   *
+   * @returns An object containing the pending transaction.
+   *
+   * @example
+   * ```typescript
+   * const provider = await ClayErasureCodingProvider.create();
+   * const blobCommitments = await generateCommitments(provider, data);
+   *
+   * const { transaction } = await client.registerBlob({
+   *   account: signer,
+   *   blobName: "foo/bar.txt",
+   *   blobMerkleRoot: blobCommitments.blob_merkle_root,
+   *   size: data.length,
+   *   expirationMicros: Date.now() * 1000 + 3600_000_000, // 1 hour from now in microseconds
+   * });
+   * ```
+   */
+  async registerBlob(params) {
+    const chunksetSize = params.options?.chunksetSizeBytes ?? DEFAULT_CHUNKSET_SIZE_BYTES;
+    const transaction = await this.aptos.transaction.build.simple({
+      ...params.options?.build,
+      data: _ShelbyBlobClient.createRegisterBlobPayload({
+        deployer: this.deployer,
+        account: params.account.accountAddress,
+        blobName: params.blobName,
+        blobSize: params.size,
+        blobMerkleRoot: params.blobMerkleRoot,
+        numChunksets: expectedTotalChunksets(params.size, chunksetSize),
+        expirationMicros: params.expirationMicros
+      }),
+      sender: params.account.accountAddress
+    });
+    return {
+      transaction: await this.aptos.signAndSubmitTransaction({
+        signer: params.account,
+        transaction
+      })
+    };
+  }
+  /**
+   * Creates a transaction payload to register a blob on the blockchain.
+   * This is a static helper method for constructing the Move function call payload.
+   *
+   * @param params.deployer - Optional deployer account address. Defaults to SHELBY_DEPLOYER.
+   * @param params.account - The account that will own the blob.
+   * @param params.blobName - The name/path of the blob (e.g. "foo/bar.txt").
+   * @param params.blobSize - The size of the blob in bytes.
+   * @param params.blobMerkleRoot - The merkle root of the blob commitments as a hex string.
+   * @param params.expirationMicros - The expiration time of the blob in microseconds.
+   * @param params.numChunksets - The total number of chunksets in the blob.
+   *
+   * @returns An Aptos transaction payload data object for the register_blob Move function.
+   *
+   * @see https://github.com/shelby/shelby/blob/e08e84742cf2b80ad8bb7227deb3013398076d53/move/shelby_contract/sources/global_metadata.move#L357
+   */
+  static createRegisterBlobPayload(params) {
+    return {
+      function: `${(params.deployer ?? SHELBY_DEPLOYER).toString()}::global_metadata::register_blob`,
+      functionArguments: [
+        params.blobName,
+        params.expirationMicros,
+        MoveVector.U8(params.blobMerkleRoot),
+        params.numChunksets,
+        params.blobSize,
+        // TODO
+        0,
+        // payment tier
+        0
+        // encoding
+      ]
+    };
+  }
+  /**
+   * Creates a transaction payload to register multiple blobs on the blockchain.
+   * This is a static helper method for constructing the Move function call payload.
+   *
+   * @param params.deployer - Optional deployer account address. Defaults to SHELBY_DEPLOYER.
+   * @param params.account - The account that will own the blobs.
+   * @param params.expirationMicros - The expiration time of the blobs in microseconds.
+   * @param params.blobs - The blobs to register.
+   * @param params.blobs.blobName - The name/path of the blob (e.g. "foo/bar.txt").
+   * @param params.blobs.blobSize - The size of the blob in bytes.
+   * @param params.blobs.blobMerkleRoot - The merkle root of the blob commitments as a hex string.
+   * @param params.blobs.numChunksets - The total number of chunksets in the blob.
+   *
+   * @returns An Aptos transaction payload data object for the register_multiple_blobs Move function.
+   *
+   * @see https://github.com/shelby/shelby/blob/e08e84742cf2b80ad8bb7227deb3013398076d53/move/shelby_contract/sources/global_metadata.move#L357
+   */
+  static createBatchRegisterBlobsPayload(params) {
+    const blobNames = [];
+    const blobMerkleRoots = [];
+    const blobNumChunksets = [];
+    const blobSizes = [];
+    params.blobs.forEach((blob) => {
+      blobNames.push(blob.blobName);
+      blobMerkleRoots.push(MoveVector.U8(blob.blobMerkleRoot));
+      blobNumChunksets.push(blob.numChunksets);
+      blobSizes.push(blob.blobSize);
+    });
+    return {
+      function: `${(params.deployer ?? SHELBY_DEPLOYER).toString()}::global_metadata::register_multiple_blobs`,
+      functionArguments: [
+        blobNames,
+        params.expirationMicros,
+        blobMerkleRoots,
+        blobNumChunksets,
+        blobSizes,
+        // TODO
+        0,
+        0
+      ]
+    };
+  }
+};
+
+export {
+  ShelbyBlobClient
+};

package/dist/chunk-ZPW742E7.mjs

@@ -0,0 +1,28 @@
+// src/core/erasure/constants.ts
+var ErasureCodingScheme = /* @__PURE__ */ ((ErasureCodingScheme2) => {
+  ErasureCodingScheme2["ClayCode_16Total_10Data_13Helper"] = "ClayCode_16Total_10Data_13Helper";
+  return ErasureCodingScheme2;
+})(ErasureCodingScheme || {});
+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
+  }
+};
+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;
+
+export {
+  ErasureCodingScheme,
+  ERASURE_CODE_PARAMS,
+  DEFAULT_ERASURE_N,
+  DEFAULT_ERASURE_K,
+  DEFAULT_ERASURE_D,
+  DEFAULT_ERASURE_M
+};

package/dist/clay-codes-Ce9EmXfa.d.ts

@@ -0,0 +1,129 @@
+import { ChunkCollection, DecoderReconfigureOptions } from '@shelby-protocol/clay-codes';
+
+interface ReedSolomonConfig extends ErasureCodingConfig {
+}
+type ReedSolomonProviderOptions = Partial<ReedSolomonConfig>;
+declare class ReedSolomonErasureCodingProvider implements ErasureCodingProvider {
+    readonly config: ReedSolomonConfig;
+    constructor(options?: ReedSolomonProviderOptions);
+    encode(data: Uint8Array): ChunkCollection;
+    decode(_available: Uint8Array[], _config: DecodeConfig): ChunkCollection;
+}
+
+/**
+ * Erasure coding provider abstraction for the SDK.
+ *
+ * Providers implement different erasure coding schemes (Clay, Reed-Solomon, etc.)
+ * while maintaining a consistent interface for encoding and decoding operations.
+ */
+
+/**
+ * Base configuration shared by all erasure coding schemes.
+ *
+ * All schemes must specify:
+ * - `chunkSizeBytes`: Size in bytes of each chunk
+ */
+interface ErasureCodingConfig {
+    /** Number of total chunks. */
+    erasure_n: number;
+    /** Number of data chunks. */
+    erasure_k: number;
+    /** Size in bytes of every chunk. */
+    chunkSizeBytes: number;
+}
+/**
+ * Union of all supported erasure coding configurations.
+ */
+type InitConfig = ReedSolomonConfig | ClayConfig;
+/**
+ * Base marker type for decode configuration.
+ *
+ * Specific providers extend this with their erasure pattern specification options.
+ * The configuration indicates which chunks are available/missing in the decode operation.
+ */
+type DecodeConfig = Record<string, unknown>;
+/**
+ * Contract for pluggable erasure coding backends.
+ *
+ * Implementations provide encode/decode operations for different erasure
+ * coding schemes while maintaining consistent semantics:
+ *
+ * - **Encode**: Takes raw data and produces n = k + m chunks
+ * - **Decode**: Takes n chunks (some may be missing/undefined) and recovers all chunks
+ *
+ * All implementations must support both array and flat buffer inputs.
+ */
+interface ErasureCodingProvider {
+    /** Configuration for this erasure coding instance. */
+    readonly config: ErasureCodingConfig;
+    /**
+     * Encode data into systematic and parity chunks.
+     *
+     * @param data - Raw data buffer that will be split into k chunks
+     * @returns Collection containing all n chunks (k systematic + m parity)
+     */
+    encode(data: Uint8Array): ChunkCollection;
+    /**
+     * Decode available chunks back to original data, recovering any missing chunks.
+     *
+     * @param available - Array of available chunks (must have at least k chunks)
+     * @param config - Decode configuration specifying which chunk indexes are available
+     * @returns Recovered chunk collection with all n chunks reconstructed
+     * @throws Error if fewer than k chunks are available
+     */
+    decode(available: Uint8Array[], config: DecodeConfig): ChunkCollection;
+}
+
+interface ClayConfig extends ErasureCodingConfig, ClayErasureCodeParams {
+}
+/**
+ * Parameters that define a Clay erasure coding scheme.
+ *
+ * These values specify only the coding characteristics, not
+ * implementation details like chunk size or storage layout.
+ *
+ * - `erasure_n`: Total number of chunks (data + parity)
+ * - `erasure_k`: Number of data chunks
+ * - `erasure_d`: Number of helper nodes participating in reconstruction
+ */
+interface ClayErasureCodeParams {
+    erasure_n: number;
+    erasure_k: number;
+    erasure_d: number;
+}
+type ClayProviderOptions = Partial<ClayErasureCodeParams & ErasureCodingConfig>;
+/**
+ * Clay-specific decode configuration.
+ *
+ * Supports flexible erasure pattern specification in any of three formats:
+ * - availableChunkIndexes: Array of available chunk positions
+ * - erasedChunkIndexes: Array of missing chunk positions
+ * - erasedChunksMask: Bitmask where bit i=1 means chunk i is missing
+ *
+ * Exactly one of these three options must be provided.
+ */
+type ClayDecodeConfig = DecoderReconfigureOptions;
+declare class ClayErasureCodingProvider implements ErasureCodingProvider {
+    readonly config: ClayConfig;
+    private encoderCache?;
+    private decoderCache?;
+    private constructor();
+    /**
+     * Static factory method to create an initialized ClayErasureCodingProvider
+     */
+    static create<T extends ClayProviderOptions>(options?: T): Promise<ClayErasureCodingProvider>;
+    encode(data: Uint8Array): ChunkCollection;
+    decode(available: Uint8Array[], config: ClayDecodeConfig): ChunkCollection;
+    /**
+     * 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: number): boolean;
+}
+
+export { ClayErasureCodingProvider as C, type DecodeConfig as D, type ErasureCodingConfig as E, type InitConfig as I, ReedSolomonErasureCodingProvider as R, type ErasureCodingProvider as a, type ClayProviderOptions as b, type ReedSolomonConfig as c, type ReedSolomonProviderOptions as d, type ClayConfig as e, type ClayErasureCodeParams as f, type ClayDecodeConfig as g };

package/dist/core/blobs.mjs

@@ -1,6 +1,6 @@
 import {
   createBlobKey
-} from "../chunk-QEMIORTL.mjs";
+} from "../chunk-OTBLZL2S.mjs";
 import "../chunk-7P6ASYW6.mjs";
 export {
   createBlobKey

package/dist/core/chunk.d.ts

@@ -0,0 +1,34 @@
+/**
+ * Chunk and chunkset size configurations supported by Shelby.
+ */
+declare enum ChunkSizeScheme {
+    ChunkSet10MiB_Chunk1MiB = "ChunkSet10MiB_Chunk1MiB"
+}
+/**
+ * Parameters for chunk and chunkset sizes in bytes.
+ */
+declare const CHUNK_SIZE_PARAMS: {
+    readonly ChunkSet10MiB_Chunk1MiB: {
+        readonly chunkSizeBytes: number;
+        readonly chunksetSizeBytes: number;
+    };
+};
+/**
+ * The default size of a chunk in bytes.
+ */
+declare const DEFAULT_CHUNK_SIZE_BYTES: number;
+/**
+ * The default size of a chunkset in bytes.
+ */
+declare const DEFAULT_CHUNKSET_SIZE_BYTES: number;
+/**
+ * Mapping between erasure codes and chunks
+ */
+declare const ERASURE_CODE_AND_CHUNK_MAPPING: {
+    readonly ClayCode_16Total_10Data_13Helper: {
+        readonly chunkSizeBytes: number;
+        readonly chunksetSizeBytes: number;
+    };
+};
+
+export { CHUNK_SIZE_PARAMS, ChunkSizeScheme, DEFAULT_CHUNKSET_SIZE_BYTES, DEFAULT_CHUNK_SIZE_BYTES, ERASURE_CODE_AND_CHUNK_MAPPING };

package/dist/core/chunk.mjs

@@ -0,0 +1,17 @@
+import {
+  CHUNK_SIZE_PARAMS,
+  ChunkSizeScheme,
+  DEFAULT_CHUNKSET_SIZE_BYTES,
+  DEFAULT_CHUNK_SIZE_BYTES,
+  ERASURE_CODE_AND_CHUNK_MAPPING
+} from "../chunk-APML3CGJ.mjs";
+import "../chunk-3ZDXWPYC.mjs";
+import "../chunk-ZPW742E7.mjs";
+import "../chunk-7P6ASYW6.mjs";
+export {
+  CHUNK_SIZE_PARAMS,
+  ChunkSizeScheme,
+  DEFAULT_CHUNKSET_SIZE_BYTES,
+  DEFAULT_CHUNK_SIZE_BYTES,
+  ERASURE_CODE_AND_CHUNK_MAPPING
+};