@shelby-protocol/sdk 0.3.0 → 0.4.0

package/dist/core/clients/ShelbyBlobClient.mjs

@@ -1,22 +1,1291 @@
+// 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://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";
+
+// src/core/types/blobs.ts
+var BLOB_ENCRYPTION_TO_MOVE_ENUM_INDEX = {
+  Unencrypted: 0,
+  AES_GCM_V1: 1
+};
+function blobEncryptionToMoveEnumIndex(encryption) {
+  return BLOB_ENCRYPTION_TO_MOVE_ENUM_INDEX[encryption];
+}
+function blobEncryptionFromMoveVariant(variant) {
+  switch (variant) {
+    case "Unencrypted":
+      return "Unencrypted";
+    case "AES_GCM_V1":
+      return "AES_GCM_V1";
+    default:
+      throw new Error(
+        "Could not parse encryption from Shelby Smart Contract, this SDK is out of date."
+      );
+  }
+}
+
+// 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) {
+    uid
+    object_name
+    owner
+    blob_commitment
+    created_at
+    expires_at
+    updated_at
+    num_chunksets
+    size
+    slice_address
+    placement_group
+    is_persisted
+    is_committed
+    is_deleted
+  }
+}
+    `;
+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
+  ) {
+    uid
+    object_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 COMMIT_REJECTION_REASONS = /* @__PURE__ */ new Set([
+  "AlreadyExists",
+  "NoPriorVersion",
+  "EtagMismatch"
+]);
+var ObjectCommitRejectedError = class extends Error {
+  constructor(blobName, uid, reason) {
+    super(
+      `commit_object rejected the write for '${blobName}' (uid ${uid}): ${reason}`
+    );
+    this.blobName = blobName;
+    this.uid = uid;
+    this.reason = reason;
+    this.name = "ObjectCommitRejectedError";
+  }
+};
+function encryptionFunctionArgs(params) {
+  if (params.omitEncryptionArg) {
+    if (params.encryption && params.encryption !== "Unencrypted") {
+      throw new Error(
+        `Blob encryption (${params.encryption}) is not supported on this network: the deployed contract predates the encryption upgrade (#1739).`
+      );
+    }
+    return [];
+  }
+  return [blobEncryptionToMoveEnumIndex(params.encryption ?? "Unencrypted")];
+}
+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 = {
+      locationHint: config.locationHint,
+      ...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,
+      selectedLocation: options?.selectedLocation ?? this.defaultOptions.selectedLocation,
+      locationHint: options?.locationHint ?? this.defaultOptions.locationHint
+    };
+  }
+  /**
+   * 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.getFullObjectMetadata({
+   *   account: AccountAddress.fromString("0x1"),
+   *   name: "foo/bar.txt",
+   * });
+   * ```
+   */
+  async getFullObjectMetadata(params) {
+    try {
+      const rawMetadata = await this.aptos.view({
+        payload: {
+          function: `${this.deployer.toString()}::blob_metadata::get_full_object_metadata`,
+          functionArguments: [
+            createBlobKey({
+              account: params.account,
+              blobName: params.name
+            })
+          ]
+        }
+      });
+      if (!rawMetadata?.[0]?.vec?.[0]) {
+        return void 0;
+      }
+      const view = rawMetadata[0].vec[0];
+      return this.parseBlobMetadata(view.blob_metadata, {
+        uid: BigInt(view.object_metadata.current_blob_uid),
+        name: params.name,
+        // Any blob bound under an object name has cleared the commit-time
+        // `is_written()` check, so a resolved object is always written.
+        isWritten: true
+      });
+    } 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") || error.message?.includes("EOBJECT_NOT_FOUND"))) {
+        return void 0;
+      }
+      throw error;
+    }
+  }
+  /**
+   * Retrieves blob metadata directly by its on-chain UID, including blobs in
+   * the pending (registered-but-not-yet-committed) state that
+   * {@link getFullObjectMetadata} cannot resolve by object name. Returns `undefined`
+   * if no blob has that UID.
+   *
+   * The returned `name`/`blobNameSuffix` are empty: the blob layer is keyed by
+   * UID and carries no object name (a name binding is established only at
+   * commit). `isWritten` reflects whether the blob has been committed.
+   */
+  async getFullObjectMetadataByUid(uid) {
+    try {
+      const rawMetadata = await this.aptos.view(
+        {
+          payload: {
+            function: `${this.deployer.toString()}::blob_metadata::get_blob_metadata`,
+            functionArguments: [uid]
+          }
+        }
+      );
+      if (!rawMetadata?.[0]?.vec?.[0]) {
+        return void 0;
+      }
+      const raw = rawMetadata[0].vec[0];
+      return this.parseBlobMetadata(raw, {
+        uid,
+        name: "",
+        isWritten: raw.state.__variant__ === "CommittedObject"
+      });
+    } catch (error) {
+      if (error instanceof Error && (error.message?.includes("sub_status: Some(404)") || error.message?.includes("EBLOB_NOT_FOUND"))) {
+        return void 0;
+      }
+      throw error;
+    }
+  }
+  /**
+   * Parse the on-chain `BlobMetadata::V1` view shape into the SDK
+   * {@link FullObjectMetadata}. `uid` / `name` / `isWritten` are supplied by the
+   * caller since they depend on the lookup path (by object name vs by UID).
+   */
+  parseBlobMetadata(raw, extra) {
+    const { content } = raw;
+    const variant = content.encoding.__variant__;
+    if (variant !== "ClayCode_16Total_10Data_13Helper" && variant !== "ClayCode_4Total_2Data_3Helper") {
+      throw new Error(
+        "Could not parse encoding from Shelby Smart Contract, this SDK is out of date."
+      );
+    }
+    const encoding = {
+      variant: "clay",
+      ...ERASURE_CODE_PARAMS[variant],
+      ...ERASURE_CODE_AND_CHUNK_MAPPING[variant]
+    };
+    const encryption = blobEncryptionFromMoveVariant(
+      content.encryption?.__variant__ ?? "Unencrypted"
+    );
+    return {
+      uid: extra.uid,
+      blobMerkleRoot: Hex3.fromHexInput(content.blob_commitment).toUint8Array(),
+      owner: normalizeAddress(raw.owner),
+      name: extra.name,
+      blobNameSuffix: extra.name ? getBlobNameSuffix(extra.name) : "",
+      size: Number(content.blob_size),
+      encoding,
+      encryption,
+      expirationMicros: Number(raw.expiration_micros),
+      creationMicros: Number(raw.creation_micros),
+      sliceAddress: normalizeAddress(raw.slice.inner),
+      isWritten: extra.isWritten
+    };
+  }
+  /**
+   * 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
+   * // FullObjectMetadata[]
+   * 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
+    });
+  }
+  /**
+   * Object-facing default filter: only committed, non-deleted, unexpired rows.
+   * The blobs table is UID-keyed, so during an atomic overwrite a single
+   * object_name transiently has two non-deleted rows — the currently committed
+   * blob and the new pending (is_committed = "0") blob. Filtering on
+   * is_committed keeps name lookups/listings pinned to the committed object and
+   * avoids returning or duplicating the in-flight pending row. Applied to
+   * getBlobs *and* the getBlobsCount / getTotalBlobsSize aggregates so counts
+   * and sizes agree with the listing mid-overwrite. Callers can override any
+   * key (e.g. is_committed) via their own `where`.
+   */
+  activeBlobsWhere(where) {
+    const defaultActiveFilter = {
+      expires_at: { _gte: String(Date.now() * 1e3) },
+      is_deleted: { _eq: "0" },
+      is_committed: { _eq: "1" }
+    };
+    return { ...defaultActiveFilter, ...where };
+  }
+  /**
+   * 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
+   * // FullObjectMetadata[]
+   * 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 finalWhere = this.activeBlobsWhere(where);
+    const { blobs } = await this.indexer.getBlobs({
+      where: finalWhere,
+      limit,
+      offset,
+      orderBy
+    });
+    return blobs.map(
+      (blob) => ({
+        uid: BigInt(blob.uid),
+        owner: normalizeAddress(blob.owner),
+        name: blob.object_name,
+        blobNameSuffix: getBlobNameSuffix(blob.object_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_persisted)),
+        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::BlobPersistedEvent`]: "write_blob",
+      [`${this.deployer.toStringLong()}::blob_metadata::ObjectCommittedEvent`]: "commit_object",
+      [`${this.deployer.toStringLong()}::blob_metadata::ObjectDeletedEvent`]: "delete_object",
+      [`${this.deployer.toStringLong()}::blob_metadata::ObjectCommitRejectedEvent`]: "reject_object_commit"
+    };
+    return blob_activities.map(
+      (activity) => ({
+        blobName: activity.object_name,
+        accountAddress: normalizeAddress(activity.object_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 { blobs_aggregate } = await this.indexer.getBlobsCount({
+      where: this.activeBlobsWhere(params.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 { blobs_aggregate } = await this.indexer.getTotalBlobsSize({
+      where: this.activeBlobsWhere(params.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,
+        selectedLocation: options.selectedLocation,
+        locationHint: options.locationHint,
+        blobSize: params.size,
+        blobMerkleRoot: params.blobMerkleRoot,
+        numChunksets: expectedTotalChunksets(params.size, chunksetSize),
+        expirationMicros: params.expirationMicros,
+        useSponsoredUsdVariant: options.usdSponsor !== void 0,
+        encoding: config.enumIndex,
+        encryption: params.encryption
+      }),
+      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.deleteObject({
+   *   account: signer,
+   *   blobName: "foo/bar.txt",
+   * });
+   * ```
+   */
+  async deleteObject(params) {
+    const transaction = await this.aptos.transaction.build.simple({
+      options: this.orderlessTxOptions(params.options),
+      data: _ShelbyBlobClient.createDeleteObjectPayload({
+        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.
+   *
+   * 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.deleteMultipleObjects({
+   *   account: signer,
+   *   blobNames: ["foo/bar.txt", "baz.txt"],
+   * });
+   * ```
+   */
+  async deleteMultipleObjects(params) {
+    const transaction = await this.aptos.transaction.build.simple({
+      options: this.orderlessTxOptions(params.options),
+      data: _ShelbyBlobClient.createDeleteMultipleObjectsPayload({
+        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,
+        selectedLocation: options.selectedLocation,
+        locationHint: options.locationHint,
+        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,
+        encryption: params.encryption
+      })
+    };
+    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
+      })
+    };
+  }
+  /**
+   * Extracts the on-chain UIDs assigned at registration from a committed
+   * register transaction's events.
+   *
+   * `register_blob` / `register_multiple_blobs` create *pending* blobs and emit
+   * one `BlobRegisteredEvent` per blob. The UID is published only on this event
+   * (the blob is not yet in the `objects` map, so it cannot be read back by
+   * name), so callers must parse it here before uploading bytes or committing.
+   *
+   * @param events - The committed transaction's events (from `waitForTransaction`).
+   * @param deployer - The contract deployer address.
+   * @returns One entry per registered blob, keyed by its full object name
+   *   (`@<owner>/<suffix>`, matching {@link createBlobKey}).
+   */
+  static registeredBlobUids(events, deployer) {
+    const eventType = `${deployer.toStringLong()}::blob_metadata::BlobRegisteredEvent`;
+    return events.filter((event) => event.type === eventType).map((event) => {
+      const data = event.data;
+      return { objectName: data.object_name, uid: BigInt(data.uid) };
+    });
+  }
+  /**
+   * Detects whether `commit_object` rejected the write for `uid` rather than
+   * applying it. A rejected commit is still a *successful* transaction — the
+   * contract tears down the pending blob and emits `ObjectCommitRejectedEvent`
+   * instead of aborting — so callers must inspect the finalized transaction's
+   * events to tell a durable write apart from a silent no-op.
+   *
+   * @param events - The committed transaction's events (from `waitForTransaction`).
+   * @param deployer - The contract deployer address.
+   * @param uid - The UID passed to `commit_object`.
+   * @returns The rejection reason, or `undefined` if the commit was applied.
+   */
+  static findObjectCommitRejection(events, deployer, uid) {
+    const eventType = `${deployer.toStringLong()}::blob_metadata::ObjectCommitRejectedEvent`;
+    const rejection = events.find(
+      (event) => event.type === eventType && BigInt(event.data.uid) === uid
+    );
+    if (!rejection) {
+      return void 0;
+    }
+    const reason = rejection.data.rejection_reason.__variant__;
+    if (!COMMIT_REJECTION_REASONS.has(reason)) {
+      throw new Error(
+        `Unrecognized ObjectCommitRejectedEvent rejection_reason '${reason}' for uid ${uid}`
+      );
+    }
+    return reason;
+  }
+  /**
+   * 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.
+   */
+  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.selectedLocation ?? null,
+        params.locationHint ?? null,
+        params.expirationMicros,
+        Hex3.fromHexString(params.blobMerkleRoot).toUint8Array(),
+        params.numChunksets,
+        params.blobSize,
+        // TODO
+        0,
+        // payment tier
+        params.encoding,
+        ...encryptionFunctionArgs(params)
+      ]
+    };
+  }
+  /**
+   * 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.
+   */
+  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.selectedLocation ?? null,
+        params.locationHint ?? null,
+        params.expirationMicros,
+        blobMerkleRoots,
+        blobNumChunksets,
+        blobSizes,
+        // TODO
+        0,
+        // payment tier
+        params.encoding,
+        ...encryptionFunctionArgs(params)
+      ]
+    };
+  }
+  /**
+   * 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_object Move function.
+   */
+  static createDeleteObjectPayload(params) {
+    return {
+      function: `${(params.deployer ?? SHELBY_DEPLOYER).toString()}::blob_metadata::delete_object`,
+      // Second arg is `if_match_etag: Option<vector<u8>>`; `null` => None
+      // (unconditional delete).
+      functionArguments: [params.blobName, null]
+    };
+  }
+  /**
+   * Creates a transaction payload to delete multiple blobs on the blockchain.
+   * This is a static helper method for constructing the Move function call payload.
+   *
+   * 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_objects Move function.
+   */
+  static createDeleteMultipleObjectsPayload(params) {
+    return {
+      function: `${(params.deployer ?? SHELBY_DEPLOYER).toString()}::blob_metadata::delete_multiple_objects`,
+      // Second arg is `if_match_etags: vector<Option<vector<u8>>>`; an empty
+      // vector means "no etag check on any object" (unconditional delete).
+      functionArguments: [params.blobNames, []]
+    };
+  }
+  /**
+   * Sort acks by slot and reduce to the `(ack_bits, signatures)` pair the
+   * contract expects: it walks the set bits low-to-high and consumes the
+   * signatures in that same order.
+   */
+  static encodeAcks(storageProviderAcks) {
+    const sortedAcks = [...storageProviderAcks].sort((a, b) => a.slot - b.slot);
+    const ackBitMask = sortedAcks.reduce(
+      (acc, ack) => acc | 1 << ack.slot,
+      0
+    );
+    return {
+      ackBits: new U32(Number(ackBitMask)),
+      signatures: sortedAcks.map((ack) => ack.signature)
+    };
+  }
+  /**
+   * Payload for `commit_object(uid, object_name_suffix, overwrite, if_match_etag,
+   * ack_bits, signatures)` — binds a written pending blob under its object name,
+   * finalizing the upload. SP acks may be batched in here (the contract applies
+   * them before the `is_written` check), so register → upload → commit needs
+   * only a single finalize transaction.
+   *
+   * @param params.uid - The blob UID returned at registration.
+   * @param params.blobName - The object name suffix the blob was registered under.
+   * @param params.overwrite - Allow replacing an existing binding under this name.
+   * @param params.storageProviderAcks - Acks applied atomically with the commit.
+   */
+  static createCommitObjectPayload(params) {
+    const { ackBits, signatures } = _ShelbyBlobClient.encodeAcks(
+      params.storageProviderAcks
+    );
+    return {
+      function: `${(params.deployer ?? SHELBY_DEPLOYER).toString()}::blob_metadata::commit_object`,
+      functionArguments: [
+        params.uid,
+        params.blobName,
+        params.overwrite,
+        // `if_match_etag: Option<vector<u8>>` is `null` => None; conditional
+        // (CAS) writes are not yet exposed by the SDK.
+        null,
+        ackBits,
+        signatures
+      ]
+    };
+  }
+  async commitObject(params) {
+    const transaction = await this.aptos.transaction.build.simple({
+      ...params.options?.build,
+      options: this.orderlessTxOptions(params.options?.build?.options),
+      data: _ShelbyBlobClient.createCommitObjectPayload({
+        deployer: this.deployer,
+        uid: params.uid,
+        blobName: params.blobName,
+        overwrite: params.overwrite,
+        storageProviderAcks: params.storageProviderAcks
+      }),
+      sender: params.account.accountAddress
+    });
+    return {
+      transaction: await this.aptos.signAndSubmitTransaction({
+        signer: params.account,
+        transaction
+      })
+    };
+  }
+};
 export {
   MissingTransactionSubmitterError,
+  ObjectCommitRejectedError,
   ShelbyBlobClient
 };