@shelby-protocol/sdk 0.3.0 → 0.3.1

package/dist/core/clients/ShelbyBlobClient.mjs

@@ -1,21 +1,1088 @@
+// src/core/clients/ShelbyBlobClient.ts
 import {
-  MissingTransactionSubmitterError,
-  ShelbyBlobClient
-} from "../../chunk-5BVSWXQJ.mjs";
-import "../../chunk-XNEIWM4O.mjs";
-import "../../chunk-NHWWORCH.mjs";
-import "../../chunk-AY3HBWXA.mjs";
-import "../../chunk-OEK24ON7.mjs";
-import "../../chunk-NEO7Z3ZQ.mjs";
-import "../../chunk-TET3DJEO.mjs";
-import "../../chunk-V4B3GAMQ.mjs";
-import "../../chunk-3NRBHSMQ.mjs";
-import "../../chunk-RNNJXTX2.mjs";
-import "../../chunk-UEZNZBJO.mjs";
-import "../../chunk-JTXYKO3U.mjs";
-import "../../chunk-AUQDI5BS.mjs";
-import "../../chunk-MNCQBEMS.mjs";
-import "../../chunk-7P6ASYW6.mjs";
+  AccountAddress as AccountAddress2,
+  Aptos,
+  Hex as Hex3,
+  U32
+} from "@aptos-labs/ts-sdk";
+
+// src/core/utils.ts
+import {
+  AccountAddress,
+  Hex
+} from "@aptos-labs/ts-sdk";
+function getBlobNameSuffix(blobName) {
+  const parts = blobName.split("/");
+  return parts.slice(1).join("/") || "";
+}
+function normalizeAddress(address) {
+  return AccountAddress.from(address, { maxMissingChars: 63 });
+}
+
+// src/core/blobs.ts
+var createBlobKey = (params) => {
+  return `@${normalizeAddress(params.account).toStringLongWithoutPrefix()}/${params.blobName}`;
+};
+
+// 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/commitments.ts
+import { Hex as Hex2 } from "@aptos-labs/ts-sdk";
+import { z } from "zod";
+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);
+}
+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"]
+  }
+);
+
+// src/core/constants.ts
+import { Network } from "@aptos-labs/ts-sdk";
+var NetworkToShelbyRPCBaseUrl = {
+  [Network.SHELBYNET]: "https://api.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";
+
+// src/core/erasure/clay-codes.ts
+import {
+  createDecoder,
+  createEncoder
+} from "@shelby-protocol/clay-codes";
+
+// src/core/erasure/default.ts
+function defaultErasureCodingConfig() {
+  const encoding = Number(process.env.SHELBY_ENCODING) || 0;
+  if (encoding === 0) {
+    return erasureCodingConfig16Total10Data13Helper();
+  }
+  return erasureCodingConfig4Total2Data3Helper();
+}
+function erasureCodingConfig16Total10Data13Helper() {
+  return erasureCodingConfig(
+    "ClayCode_16Total_10Data_13Helper" /* ClayCode_16Total_10Data_13Helper */
+  );
+}
+function erasureCodingConfig4Total2Data3Helper() {
+  return erasureCodingConfig("ClayCode_4Total_2Data_3Helper" /* ClayCode_4Total_2Data_3Helper */);
+}
+function erasureCodingConfig(encodingScheme) {
+  return {
+    erasure_n: ERASURE_CODE_PARAMS[encodingScheme].erasure_n,
+    erasure_k: ERASURE_CODE_PARAMS[encodingScheme].erasure_k,
+    erasure_d: ERASURE_CODE_PARAMS[encodingScheme].erasure_d,
+    chunkSizeBytes: DEFAULT_CHUNK_SIZE_BYTES,
+    enumIndex: ERASURE_CODE_PARAMS[encodingScheme].enumIndex
+  };
+}
+
+// src/core/erasure/reed-solomon.ts
+import { createWasmReedSolomonBinding } from "@shelby-protocol/reed-solomon";
+var DEFAULT_CHUNK_SIZE_BYTES2 = 2 * 1024 * 1024;
+
+// src/core/operations/index.ts
+import { Network as Network2 } from "@aptos-labs/ts-sdk";
+import { GraphQLClient } from "graphql-request";
+
+// src/core/clients/utils.ts
+import { AptosConfig } from "@aptos-labs/ts-sdk";
+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
+  });
+};
+
+// src/core/operations/generated/sdk.ts
+import gql from "graphql-tag";
+var GetBlobsDocument = gql`
+    query getBlobs($where: blobs_bool_exp, $orderBy: [blobs_order_by!], $limit: Int, $offset: Int) {
+  blobs(where: $where, order_by: $orderBy, limit: $limit, offset: $offset) {
+    owner
+    blob_commitment
+    blob_name
+    created_at
+    expires_at
+    num_chunksets
+    is_deleted
+    is_written
+    placement_group
+    size
+    updated_at
+    slice_address
+  }
+}
+    `;
+var GetBlobActivitiesDocument = gql`
+    query getBlobActivities($where: blob_activities_bool_exp, $orderBy: [blob_activities_order_by!], $limit: Int, $offset: Int) {
+  blob_activities(
+    where: $where
+    order_by: $orderBy
+    limit: $limit
+    offset: $offset
+  ) {
+    blob_name
+    event_index
+    event_type
+    transaction_hash
+    transaction_version
+    timestamp
+    owner
+  }
+}
+    `;
+var GetBlobsCountDocument = gql`
+    query getBlobsCount($where: blobs_bool_exp) {
+  blobs_aggregate(where: $where) {
+    aggregate {
+      count
+    }
+  }
+}
+    `;
+var GetBlobActivitiesCountDocument = gql`
+    query getBlobActivitiesCount($where: blob_activities_bool_exp) {
+  blob_activities_aggregate(where: $where) {
+    aggregate {
+      count
+    }
+  }
+}
+    `;
+var GetTotalBlobsSizeDocument = gql`
+    query getTotalBlobsSize($where: blobs_bool_exp) {
+  blobs_aggregate(where: $where) {
+    aggregate {
+      sum {
+        size
+      }
+    }
+  }
+}
+    `;
+var GetPlacementGroupSlotsDocument = gql`
+    query getPlacementGroupSlots($where: placement_group_slots_bool_exp, $orderBy: [placement_group_slots_order_by!], $limit: Int, $offset: Int) {
+  placement_group_slots(
+    where: $where
+    order_by: $orderBy
+    limit: $limit
+    offset: $offset
+  ) {
+    placement_group
+    slot_index
+    storage_provider
+    status
+    updated_at
+  }
+}
+    `;
+var GetPlacementGroupSlotsCountDocument = gql`
+    query getPlacementGroupSlotsCount($where: placement_group_slots_bool_exp) {
+  placement_group_slots_aggregate(where: $where) {
+    aggregate {
+      count
+    }
+  }
+}
+    `;
+var GetProcessorStatusDocument = gql`
+    query getProcessorStatus {
+  processor_status {
+    last_success_version
+    last_transaction_timestamp
+    last_updated
+  }
+}
+    `;
+var defaultWrapper = (action, _operationName, _operationType, _variables) => action();
+function getSdk(client, withWrapper = defaultWrapper) {
+  return {
+    getBlobs(variables, requestHeaders, signal) {
+      return withWrapper((wrappedRequestHeaders) => client.request({ document: GetBlobsDocument, variables, requestHeaders: { ...requestHeaders, ...wrappedRequestHeaders }, signal }), "getBlobs", "query", variables);
+    },
+    getBlobActivities(variables, requestHeaders, signal) {
+      return withWrapper((wrappedRequestHeaders) => client.request({ document: GetBlobActivitiesDocument, variables, requestHeaders: { ...requestHeaders, ...wrappedRequestHeaders }, signal }), "getBlobActivities", "query", variables);
+    },
+    getBlobsCount(variables, requestHeaders, signal) {
+      return withWrapper((wrappedRequestHeaders) => client.request({ document: GetBlobsCountDocument, variables, requestHeaders: { ...requestHeaders, ...wrappedRequestHeaders }, signal }), "getBlobsCount", "query", variables);
+    },
+    getBlobActivitiesCount(variables, requestHeaders, signal) {
+      return withWrapper((wrappedRequestHeaders) => client.request({ document: GetBlobActivitiesCountDocument, variables, requestHeaders: { ...requestHeaders, ...wrappedRequestHeaders }, signal }), "getBlobActivitiesCount", "query", variables);
+    },
+    getTotalBlobsSize(variables, requestHeaders, signal) {
+      return withWrapper((wrappedRequestHeaders) => client.request({ document: GetTotalBlobsSizeDocument, variables, requestHeaders: { ...requestHeaders, ...wrappedRequestHeaders }, signal }), "getTotalBlobsSize", "query", variables);
+    },
+    getPlacementGroupSlots(variables, requestHeaders, signal) {
+      return withWrapper((wrappedRequestHeaders) => client.request({ document: GetPlacementGroupSlotsDocument, variables, requestHeaders: { ...requestHeaders, ...wrappedRequestHeaders }, signal }), "getPlacementGroupSlots", "query", variables);
+    },
+    getPlacementGroupSlotsCount(variables, requestHeaders, signal) {
+      return withWrapper((wrappedRequestHeaders) => client.request({ document: GetPlacementGroupSlotsCountDocument, variables, requestHeaders: { ...requestHeaders, ...wrappedRequestHeaders }, signal }), "getPlacementGroupSlotsCount", "query", variables);
+    },
+    getProcessorStatus(variables, requestHeaders, signal) {
+      return withWrapper((wrappedRequestHeaders) => client.request({ document: GetProcessorStatusDocument, variables, requestHeaders: { ...requestHeaders, ...wrappedRequestHeaders }, signal }), "getProcessorStatus", "query", variables);
+    }
+  };
+}
+
+// src/core/operations/index.ts
+function createShelbyIndexerClient(baseUrl, options) {
+  const graphqlClient = new GraphQLClient(baseUrl, options);
+  return getSdk(graphqlClient);
+}
+function getShelbyIndexerClient(config) {
+  const aptosConfig = getAptosConfig(config);
+  let { apiKey: indexerApiKey, baseUrl } = config.indexer ?? {};
+  if (!baseUrl) {
+    switch (aptosConfig?.network) {
+      // TODO: Add endpoints for core networks
+      case Network2.MAINNET:
+      case Network2.TESTNET:
+      case Network2.DEVNET:
+      case Network2.SHELBYNET:
+      case Network2.LOCAL:
+        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."
+    );
+  }
+  const apiKey = indexerApiKey ?? config.apiKey;
+  return createShelbyIndexerClient(baseUrl, {
+    headers: {
+      ...apiKey ? { Authorization: `Bearer ${apiKey}` } : {},
+      "x-aptos-client": "shelby-ts-sdk"
+    }
+  });
+}
+
+// src/core/clients/ShelbyBlobClient.ts
+var MissingTransactionSubmitterError = class extends Error {
+  constructor() {
+    super(
+      "USD sponsorship (usdSponsor) requires a transaction submitter to be configured. The sponsored transaction is a multi-agent transaction that must be co-signed by the sponsor. Configure a transaction submitter via aptos.pluginSettings.TRANSACTION_SUBMITTER that routes transactions to a service (like a gas station) capable of providing the sponsor's signature."
+    );
+    this.name = "MissingTransactionSubmitterError";
+  }
+};
+var ShelbyBlobClient = class _ShelbyBlobClient {
+  aptos;
+  deployer;
+  indexer;
+  defaultOptions;
+  orderless;
+  /**
+   * 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.
+   * @param defaultOptions - Optional default options for blob operations.
+   *
+   * @example
+   * ```typescript
+   * const blobClient = new ShelbyBlobClient({
+   *   aptos: {
+   *     network: Network.SHELBYNET,
+   *     clientConfig: {
+   *       API_KEY: "AG-***",
+   *     },
+   *   },
+   * });
+   * ```
+   *
+   * @example
+   * ```typescript
+   * // With default options for USD sponsorship
+   * const blobClient = new ShelbyBlobClient(
+   *   {
+   *     network: Network.SHELBYNET,
+   *     aptos: {
+   *       pluginSettings: {
+   *         TRANSACTION_SUBMITTER: myGasStationSubmitter,
+   *       },
+   *     },
+   *   },
+   *   {
+   *     usdSponsor: { feePayerAddress: sponsorAddress },
+   *   }
+   * );
+   * ```
+   */
+  constructor(config, defaultOptions) {
+    this.aptos = new Aptos(getAptosConfig(config));
+    this.deployer = config.deployer ?? AccountAddress2.fromString(SHELBY_DEPLOYER);
+    this.indexer = getShelbyIndexerClient(config);
+    this.defaultOptions = defaultOptions ?? {};
+    this.orderless = config.orderless ?? false;
+  }
+  /**
+   * Merges method-level options with default options, giving precedence to method-level values.
+   */
+  mergeOptions(options) {
+    return {
+      build: options?.build ?? this.defaultOptions.build,
+      submit: options?.submit ?? this.defaultOptions.submit,
+      usdSponsor: options?.usdSponsor ?? this.defaultOptions.usdSponsor,
+      chunksetSizeBytes: options?.chunksetSizeBytes ?? this.defaultOptions.chunksetSizeBytes
+    };
+  }
+  /**
+   * Validates that if USD sponsorship is requested, a transaction submitter is
+   * configured as well. Checks both the client-level and method-level transaction
+   * submitter configurations. Throws MissingTransactionSubmitterError if usdSponsor is
+   * provided without a transaction submitter.
+   */
+  validateUsdSponsorConfig(usdSponsor, submit) {
+    if (!usdSponsor) {
+      return;
+    }
+    const hasClientSubmitter = this.aptos.config.getTransactionSubmitter();
+    const hasMethodSubmitter = submit?.transactionSubmitter !== void 0 && submit?.transactionSubmitter !== null;
+    if (!hasClientSubmitter && !hasMethodSubmitter) {
+      throw new MissingTransactionSubmitterError();
+    }
+  }
+  /**
+   * Merges orderless replay protection into transaction options when
+   * `config.orderless` is enabled. If the caller already supplies options
+   * (e.g. custom gas limits), those are preserved and the nonce is injected
+   * alongside them. When orderless mode is off, user options are returned as-is.
+   */
+  orderlessTxOptions(userOptions) {
+    if (!this.orderless) return userOptions;
+    return {
+      replayProtectionNonce: crypto.getRandomValues(new Uint32Array(1))[0],
+      ...userOptions
+    };
+  }
+  /**
+   * 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()}::blob_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 if (metadata.encoding.__variant__ === "ClayCode_4Total_2Data_3Helper") {
+        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: Hex3.fromHexInput(
+          metadata.blob_commitment
+        ).toUint8Array(),
+        owner: normalizeAddress(metadata.owner),
+        name: params.name,
+        blobNameSuffix: getBlobNameSuffix(params.name),
+        size: Number(metadata.blob_size),
+        encoding,
+        expirationMicros: Number(metadata.expiration_micros),
+        creationMicros: Number(metadata.creation_micros),
+        sliceAddress: normalizeAddress(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) {
+    const { where, ...rest } = params;
+    return this.getBlobs({
+      where: {
+        ...where,
+        owner: { _eq: normalizeAddress(params.account).toString() }
+      },
+      pagination: rest.pagination,
+      orderBy: rest.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 currentMicros = String(Date.now() * 1e3);
+    const defaultActiveFilter = {
+      expires_at: { _gte: currentMicros },
+      is_deleted: { _eq: "0" }
+    };
+    const finalWhere = where !== void 0 ? { ...defaultActiveFilter, ...where } : defaultActiveFilter;
+    const { blobs } = await this.indexer.getBlobs({
+      where: finalWhere,
+      limit,
+      offset,
+      orderBy
+    });
+    return blobs.map(
+      (blob) => ({
+        owner: normalizeAddress(blob.owner),
+        name: blob.blob_name,
+        blobNameSuffix: getBlobNameSuffix(blob.blob_name),
+        blobMerkleRoot: Hex3.fromHexInput(blob.blob_commitment).toUint8Array(),
+        size: Number(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: Number(blob.expires_at),
+        creationMicros: Number(blob.created_at),
+        sliceAddress: normalizeAddress(blob.slice_address),
+        isWritten: Boolean(Number(blob.is_written)),
+        isDeleted: Boolean(Number(blob.is_deleted))
+      })
+    );
+  }
+  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()}::blob_metadata::BlobRegisteredEvent`]: "register_blob",
+      [`${this.deployer.toStringLong()}::blob_metadata::BlobDeletedEvent`]: "delete_blob",
+      [`${this.deployer.toStringLong()}::blob_metadata::BlobExpirationExtendedEvent`]: "extend_blob_expiration",
+      [`${this.deployer.toStringLong()}::blob_metadata::BlobWrittenEvent`]: "write_blob"
+    };
+    return blob_activities.map(
+      (activity) => ({
+        blobName: activity.blob_name,
+        accountAddress: normalizeAddress(activity.blob_name.substring(1, 65)),
+        type: activityTypeMapping[activity.event_type] ?? "unknown",
+        eventType: activity.event_type,
+        eventIndex: Number(activity.event_index),
+        transactionHash: activity.transaction_hash,
+        // Using Number here in JS is technically not okay because txn version can be
+        // as large as u64::MAX, but it should be fine for a long while.
+        transactionVersion: Number(activity.transaction_version),
+        timestamp: `${activity.timestamp}Z`
+      })
+    );
+  }
+  /**
+   * Retrieves the total number of blobs from the blockchain.
+   *
+   * @param params.where (optional) - The where clause to filter the blobs by.
+   * @returns The total number of blobs.
+   *
+   * @example
+   * ```typescript
+   * const count = await client.getBlobsCount();
+   * ```
+   */
+  async getBlobsCount(params) {
+    const { where } = params;
+    const { blobs_aggregate } = await this.indexer.getBlobsCount({ where });
+    return blobs_aggregate?.aggregate?.count ?? 0;
+  }
+  /**
+   * Retrieves the total size of blobs from the blockchain.
+   *
+   * @param params.where (optional) - The where clause to filter the blobs by.
+   * @returns The total size of blobs in bytes.
+   *
+   * @example
+   * ```typescript
+   * const size = await client.getTotalBlobsSize();
+   * ```
+   */
+  async getTotalBlobsSize(params = {}) {
+    const { where } = params;
+    const { blobs_aggregate } = await this.indexer.getTotalBlobsSize({ where });
+    return Number(blobs_aggregate?.aggregate?.sum?.size ?? 0);
+  }
+  /**
+   * Retrieves the total number of blob activities from the blockchain.
+   *
+   * @param params.where (optional) - The where clause to filter the blob activities by.
+   * @returns The total number of blob activities.
+   *
+   * @example
+   * ```typescript
+   * const count = await client.getBlobActivitiesCount();
+   * ```
+   */
+  async getBlobActivitiesCount(params) {
+    const { where } = params;
+    const { blob_activities_aggregate } = await this.indexer.getBlobActivitiesCount({ where });
+    return blob_activities_aggregate?.aggregate?.count ?? 0;
+  }
+  /**
+   * 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 options = this.mergeOptions(params.options);
+    this.validateUsdSponsorConfig(options.usdSponsor, options.submit);
+    const config = params.config ?? defaultErasureCodingConfig();
+    const chunksetSize = config.chunkSizeBytes * config.erasure_k;
+    const buildArgs = {
+      ...options.build,
+      options: this.orderlessTxOptions(options.build?.options),
+      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,
+        useSponsoredUsdVariant: options.usdSponsor !== void 0,
+        encoding: config.enumIndex
+      }),
+      sender: params.account.accountAddress
+    };
+    const transaction = options.usdSponsor ? await this.aptos.transaction.build.multiAgent({
+      ...buildArgs,
+      secondarySignerAddresses: [options.usdSponsor.feePayerAddress]
+    }) : await this.aptos.transaction.build.simple(buildArgs);
+    return {
+      transaction: await this.aptos.signAndSubmitTransaction({
+        signer: params.account,
+        transaction,
+        ...options.submit
+      })
+    };
+  }
+  /**
+   * Deletes a blob on the blockchain.
+   *
+   * @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.options - Optional transaction building options.
+   *
+   * @returns An object containing the pending transaction.
+   *
+   * @example
+   * ```typescript
+   *
+   * const { transaction } = await client.deleteBlob({
+   *   account: signer,
+   *   blobName: "foo/bar.txt",
+   * });
+   * ```
+   */
+  async deleteBlob(params) {
+    const transaction = await this.aptos.transaction.build.simple({
+      options: this.orderlessTxOptions(params.options),
+      data: _ShelbyBlobClient.createDeleteBlobPayload({
+        deployer: this.deployer,
+        blobName: params.blobName
+      }),
+      sender: params.account.accountAddress
+    });
+    return {
+      transaction: await this.aptos.signAndSubmitTransaction({
+        signer: params.account,
+        transaction
+      })
+    };
+  }
+  /**
+   * Deletes multiple blobs on the blockchain in a single atomic transaction.
+   *
+   * **Note:** This function requires the `delete_multiple_blobs` entry function
+   * which will be deployed to the smart contract on 2026-02-04. Using this
+   * function before that date will result in a transaction failure.
+   *
+   * This operation is atomic: if any blob deletion fails (e.g., blob not found),
+   * the entire transaction fails and no blobs are deleted.
+   *
+   * @param params.account - The account that is signing and paying for the transaction.
+   * @param params.blobNames - Array of blob name suffixes without the account address prefix
+   *   (e.g. ["foo/bar.txt", "baz.txt"], NOT ["0x1/foo/bar.txt"]). The account address
+   *   prefix is automatically derived from the signer.
+   * @param params.options - Optional transaction building options.
+   *
+   * @returns An object containing the pending transaction.
+   *
+   * @example
+   * ```typescript
+   *
+   * const { transaction } = await client.deleteMultipleBlobs({
+   *   account: signer,
+   *   blobNames: ["foo/bar.txt", "baz.txt"],
+   * });
+   * ```
+   */
+  async deleteMultipleBlobs(params) {
+    const transaction = await this.aptos.transaction.build.simple({
+      options: this.orderlessTxOptions(params.options),
+      data: _ShelbyBlobClient.createDeleteMultipleBlobsPayload({
+        deployer: this.deployer,
+        blobNames: params.blobNames
+      }),
+      sender: params.account.accountAddress
+    });
+    return {
+      transaction: await this.aptos.signAndSubmitTransaction({
+        signer: params.account,
+        transaction
+      })
+    };
+  }
+  /**
+   * Registers multiple blobs on the blockchain by writing their merkle roots and metadata.
+   *
+   * @param params.account - The account that is signing and paying for the transaction.
+   * @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.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.batchRegisterBlobs({
+   *   account: signer,
+   *   expirationMicros: Date.now() * 1000 + 3600_000_000, // 1 hour from now in microseconds
+   *   blobs: [
+   *     {
+   *       blobName: "foo/bar.txt",
+   *       blobSize: data.length,
+   *       blobMerkleRoot: blobCommitments.blob_merkle_root,
+   *     },
+   *   ],
+   * });
+   * ```
+   */
+  async batchRegisterBlobs(params) {
+    const options = this.mergeOptions(params.options);
+    this.validateUsdSponsorConfig(options.usdSponsor, options.submit);
+    const config = params.config ?? defaultErasureCodingConfig();
+    const chunksetSize = config.chunkSizeBytes * config.erasure_k;
+    const buildArgs = {
+      ...options.build,
+      options: this.orderlessTxOptions(options.build?.options),
+      sender: params.account.accountAddress,
+      data: _ShelbyBlobClient.createBatchRegisterBlobsPayload({
+        deployer: this.deployer,
+        account: params.account.accountAddress,
+        expirationMicros: params.expirationMicros,
+        blobs: params.blobs.map((blob) => ({
+          blobName: blob.blobName,
+          blobSize: blob.blobSize,
+          blobMerkleRoot: blob.blobMerkleRoot,
+          numChunksets: expectedTotalChunksets(blob.blobSize, chunksetSize)
+        })),
+        useSponsoredUsdVariant: options.usdSponsor !== void 0,
+        encoding: config.enumIndex
+      })
+    };
+    const transaction = options.usdSponsor ? await this.aptos.transaction.build.multiAgent({
+      ...buildArgs,
+      secondarySignerAddresses: [options.usdSponsor.feePayerAddress]
+    }) : await this.aptos.transaction.build.simple(buildArgs);
+    return {
+      transaction: await this.aptos.signAndSubmitTransaction({
+        signer: params.account,
+        transaction,
+        ...options.submit
+      })
+    };
+  }
+  /**
+   * 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) {
+    const functionName = params.useSponsoredUsdVariant ? "register_blob_with_sponsor" : "register_blob";
+    return {
+      function: `${(params.deployer ?? SHELBY_DEPLOYER).toString()}::blob_metadata::${functionName}`,
+      functionArguments: [
+        params.blobName,
+        params.expirationMicros,
+        Hex3.fromHexString(params.blobMerkleRoot).toUint8Array(),
+        params.numChunksets,
+        params.blobSize,
+        // TODO
+        0,
+        // payment tier
+        params.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 functionName = params.useSponsoredUsdVariant ? "register_multiple_blobs_with_sponsor" : "register_multiple_blobs";
+    const blobNames = [];
+    const blobMerkleRoots = [];
+    const blobNumChunksets = [];
+    const blobSizes = [];
+    params.blobs.forEach((blob) => {
+      blobNames.push(blob.blobName);
+      blobMerkleRoots.push(
+        Hex3.fromHexString(blob.blobMerkleRoot).toUint8Array()
+      );
+      blobNumChunksets.push(blob.numChunksets);
+      blobSizes.push(blob.blobSize);
+    });
+    return {
+      function: `${(params.deployer ?? SHELBY_DEPLOYER).toString()}::blob_metadata::${functionName}`,
+      functionArguments: [
+        blobNames,
+        params.expirationMicros,
+        blobMerkleRoots,
+        blobNumChunksets,
+        blobSizes,
+        // TODO
+        0,
+        // payment tier
+        params.encoding
+      ]
+    };
+  }
+  /**
+   * Creates a transaction payload to delete 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.blobName - The blob name (e.g. "bar.txt", without the account address prefix).
+   *
+   * @returns An Aptos transaction payload data object for the delete_blob Move function.
+   *
+   * @see https://github.com/shelby/shelby/blob/64e9d7b4f0005e586faeb1e4085c79159234b6b6/move/shelby_contract/sources/global_metadata.move#L616
+   */
+  static createDeleteBlobPayload(params) {
+    return {
+      function: `${(params.deployer ?? SHELBY_DEPLOYER).toString()}::blob_metadata::delete_blob`,
+      functionArguments: [params.blobName]
+    };
+  }
+  /**
+   * Creates a transaction payload to delete multiple blobs on the blockchain.
+   * This is a static helper method for constructing the Move function call payload.
+   *
+   * **Note:** This function requires the `delete_multiple_blobs` entry function
+   * which will be deployed to the smart contract on 2026-02-04. Using this
+   * function before that date will result in a transaction failure.
+   *
+   * This operation is atomic: if any blob deletion fails (e.g., blob not found),
+   * the entire transaction fails and no blobs are deleted.
+   *
+   * @param params.deployer - Optional deployer account address. Defaults to SHELBY_DEPLOYER.
+   * @param params.blobNames - Array of blob name suffixes without the account address prefix
+   *   (e.g. ["foo/bar.txt", "baz.txt"], NOT ["0x1/foo/bar.txt"]). The account address
+   *   prefix is automatically derived from the transaction sender.
+   *
+   * @returns An Aptos transaction payload data object for the delete_multiple_blobs Move function.
+   *
+   * @see https://github.com/shelby/shelby/blob/main/move/shelby_contract/sources/blob_metadata.move
+   */
+  static createDeleteMultipleBlobsPayload(params) {
+    return {
+      function: `${(params.deployer ?? SHELBY_DEPLOYER).toString()}::blob_metadata::delete_multiple_blobs`,
+      functionArguments: [params.blobNames]
+    };
+  }
+  static createBlobAcknowledgementsPayload(params) {
+    const ackBitMask = params.storageProviderAcks.reduce(
+      (acc, ack) => acc | 1 << ack.slot,
+      0
+    );
+    return {
+      function: `${SHELBY_DEPLOYER}::blob_metadata::add_blob_acknowledgements`,
+      functionArguments: [
+        createBlobKey({
+          account: params.blobOwner,
+          blobName: params.blobName
+        }),
+        params.creationMicros,
+        new U32(Number(ackBitMask)),
+        params.storageProviderAcks.map((ack) => ack.signature)
+      ]
+    };
+  }
+  async addBlobAcknowledgements(params) {
+    const transaction = await this.aptos.transaction.build.simple({
+      ...params.options?.build,
+      options: this.orderlessTxOptions(params.options?.build?.options),
+      data: _ShelbyBlobClient.createBlobAcknowledgementsPayload({
+        blobOwner: params.blobOwner,
+        blobName: params.blobName,
+        creationMicros: params.creationMicros,
+        storageProviderAcks: params.storageProviderAcks
+      }),
+      sender: params.account.accountAddress
+    });
+    return {
+      transaction: await this.aptos.signAndSubmitTransaction({
+        signer: params.account,
+        transaction
+      })
+    };
+  }
+};
 export {
   MissingTransactionSubmitterError,
   ShelbyBlobClient