@shelby-protocol/sdk 0.3.0 → 0.4.0

package/dist/node/clients/ShelbyNodeClient.mjs

@@ -1,28 +1,3241 @@
+// src/core/clients/ShelbyClient.ts
 import {
-  ShelbyNodeClient
-} from "../../chunk-V46D5NBW.mjs";
-import "../../chunk-6XSZRDLJ.mjs";
-import "../../chunk-WFWRBNTW.mjs";
-import "../../chunk-5BVSWXQJ.mjs";
-import "../../chunk-XNEIWM4O.mjs";
-import "../../chunk-NHWWORCH.mjs";
-import "../../chunk-AY3HBWXA.mjs";
-import "../../chunk-OEK24ON7.mjs";
-import "../../chunk-6FJNAUU5.mjs";
-import "../../chunk-KG2TMLEV.mjs";
-import "../../chunk-NEO7Z3ZQ.mjs";
-import "../../chunk-TET3DJEO.mjs";
-import "../../chunk-V4B3GAMQ.mjs";
-import "../../chunk-Z4FZ7W6L.mjs";
-import "../../chunk-I6NG5GNL.mjs";
-import "../../chunk-M3CP5TFP.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";
+  Aptos as Aptos3,
+  DEFAULT_TXN_TIMEOUT_SEC,
+  Network as Network3,
+  TransactionResponseType
+} from "@aptos-labs/ts-sdk";
+import pLimit from "p-limit";
+
+// src/core/utils.ts
+import {
+  AccountAddress,
+  Hex
+} from "@aptos-labs/ts-sdk";
+async function* readInChunks(input, chunkSize) {
+  let idx = 0;
+  if (isReadableStream(input)) {
+    const reader = input.getReader();
+    let buffer = new Uint8Array(chunkSize);
+    let bufferWriteOffset = 0;
+    try {
+      while (true) {
+        const { value, done } = await reader.read();
+        if (done) break;
+        if (value === void 0) continue;
+        let srcOffset = 0;
+        while (srcOffset < value.length) {
+          const remainingCapacity = chunkSize - bufferWriteOffset;
+          const bytesToCopy = Math.min(
+            remainingCapacity,
+            value.length - srcOffset
+          );
+          buffer.set(
+            value.subarray(srcOffset, srcOffset + bytesToCopy),
+            bufferWriteOffset
+          );
+          bufferWriteOffset += bytesToCopy;
+          srcOffset += bytesToCopy;
+          if (bufferWriteOffset >= chunkSize) {
+            yield [idx++, buffer];
+            buffer = new Uint8Array(chunkSize);
+            bufferWriteOffset = 0;
+          }
+        }
+      }
+    } finally {
+      reader.releaseLock();
+    }
+    if (bufferWriteOffset > 0) {
+      yield [idx++, buffer.subarray(0, bufferWriteOffset)];
+    }
+    return;
+  }
+  const view = toUint8Array(input);
+  for (let offset = 0; offset < view.byteLength; offset += chunkSize) {
+    yield [
+      idx++,
+      view.subarray(offset, Math.min(offset + chunkSize, view.byteLength))
+    ];
+  }
+}
+function zeroPadBytes(buffer, desiredLength) {
+  if (buffer.byteLength === desiredLength) {
+    return buffer;
+  }
+  if (buffer.byteLength > desiredLength) {
+    return buffer.subarray(0, desiredLength);
+  }
+  const paddedBuffer = new Uint8Array(desiredLength);
+  paddedBuffer.set(buffer);
+  return paddedBuffer;
+}
+async function concatHashes(parts) {
+  const chunks = parts.map((part) => Hex.fromHexInput(part).toUint8Array());
+  const totalLength = chunks.reduce((sum, chunk) => sum + chunk.byteLength, 0);
+  const combined = new Uint8Array(totalLength);
+  let offset = 0;
+  for (const chunk of chunks) {
+    combined.set(chunk, offset);
+    offset += chunk.byteLength;
+  }
+  return Hex.fromHexInput(
+    new Uint8Array(await crypto.subtle.digest("SHA-256", combined))
+  );
+}
+function isReadableStream(value) {
+  return typeof value === "object" && value !== null && "getReader" in value && typeof value.getReader === "function";
+}
+function toUint8Array(view) {
+  return view instanceof Uint8Array ? view : new Uint8Array(view.buffer, view.byteOffset, view.byteLength);
+}
+function buildRequestUrl(path, baseUrl) {
+  const baseHasSlash = baseUrl.endsWith("/");
+  const safeBase = baseHasSlash ? baseUrl : `${baseUrl}/`;
+  const safePath = path.replace(/^\/+/, "");
+  return new URL(safePath, safeBase);
+}
+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/commitments.ts
+import { Hex as Hex2 } from "@aptos-labs/ts-sdk";
+import { z } from "zod";
+
+// src/core/erasure/constants.ts
+var ERASURE_CODE_PARAMS = {
+  ["ClayCode_16Total_10Data_13Helper" /* ClayCode_16Total_10Data_13Helper */]: {
+    // total chunks (data + parity)
+    erasure_n: 16,
+    // data chunks
+    erasure_k: 10,
+    // helper nodes
+    erasure_d: 13,
+    // enum index
+    enumIndex: 0
+  },
+  ["ClayCode_4Total_2Data_3Helper" /* ClayCode_4Total_2Data_3Helper */]: {
+    // total chunks (data + parity)
+    erasure_n: 4,
+    // data chunks
+    erasure_k: 2,
+    // helper nodes
+    erasure_d: 3,
+    // enum index
+    enumIndex: 1
+  }
+};
+function findErasureSchemeByErasureN(erasureN) {
+  return Object.entries(ERASURE_CODE_PARAMS).find(
+    ([, params]) => params.erasure_n === erasureN
+  );
+}
+function requiredAckCount(erasureN) {
+  const scheme = findErasureSchemeByErasureN(erasureN);
+  if (!scheme) {
+    throw new Error(`Unknown erasure coding scheme with erasure_n=${erasureN}`);
+  }
+  return scheme[1].erasure_d;
+}
+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
+var COMMITMENT_SCHEMA_VERSION = "1.3";
+var ChunksetCommitmentSchema = z.object({
+  // Chunkset root (vector commitment of child chunks)
+  chunkset_root: z.string(),
+  // the size is known statically from the current configuration
+  chunk_commitments: z.array(z.string())
+}).refine(
+  (data) => {
+    return data.chunk_commitments.length === DEFAULT_ERASURE_K + DEFAULT_ERASURE_M;
+  },
+  {
+    message: `Chunkset must have exactly ${DEFAULT_ERASURE_K + DEFAULT_ERASURE_M} chunks (ERASURE_K + ERASURE_M = ${DEFAULT_ERASURE_K} + ${DEFAULT_ERASURE_M})`,
+    path: ["chunk_commitments"]
+  }
+);
+function expectedTotalChunksets(rawSize, chunksetSize = DEFAULT_CHUNKSET_SIZE_BYTES) {
+  if (chunksetSize <= 0) {
+    throw new Error("chunksetSize must be positive");
+  }
+  if (rawSize === 0) return 1;
+  return Math.ceil(rawSize / chunksetSize);
+}
+var BlobCommitmentsSchema = z.object({
+  schema_version: z.string(),
+  raw_data_size: z.number(),
+  // FIXME I am not sure about this being here, or if it should be somewhere else
+  blob_merkle_root: z.string(),
+  chunkset_commitments: z.array(ChunksetCommitmentSchema)
+}).refine(
+  (data) => {
+    return expectedTotalChunksets(data.raw_data_size) === data.chunkset_commitments.length;
+  },
+  {
+    message: "Total chunkset count mismatches with raw data size",
+    // FIXME put more details in here
+    path: ["chunkset_commitments"]
+  }
+);
+async function generateMerkleRoot(leafHashes) {
+  if (!leafHashes.length) {
+    throw new Error(
+      "An empty array cannot be used to construct a Merkle tree."
+    );
+  }
+  const zeroArray = new Uint8Array(leafHashes[0].toUint8Array().length);
+  const zeroBytes = Hex2.fromHexInput(zeroArray);
+  let currentLeaves = leafHashes;
+  while (currentLeaves.length > 1) {
+    if (currentLeaves.length % 2 !== 0) {
+      currentLeaves.push(zeroBytes);
+    }
+    const nextLeaves = [];
+    for (let i = 0; i < currentLeaves.length; i += 2) {
+      nextLeaves.push(
+        await concatHashes([
+          currentLeaves[i].toUint8Array(),
+          currentLeaves[i + 1].toUint8Array()
+        ])
+      );
+    }
+    currentLeaves = nextLeaves;
+  }
+  return currentLeaves[0];
+}
+async function generateChunksetCommitments(chunksetIdx, chunksetData, expectedChunksetSize, provider, onChunk) {
+  const { erasure_n } = provider.config;
+  const chunksetPayload = zeroPadBytes(chunksetData, expectedChunksetSize);
+  const { chunks } = provider.encode(chunksetPayload);
+  if (chunks.length !== erasure_n) {
+    throw new Error(
+      `Erasure provider produced ${chunks.length} chunks, expected ${erasure_n}.`
+    );
+  }
+  const chunkRoots = provider.getChunkMerkleRoots();
+  let chunkIdx = 0;
+  for (const chunkData of chunks) {
+    if (onChunk !== void 0) {
+      await onChunk(chunksetIdx, chunkIdx, chunkData);
+    }
+    chunkIdx += 1;
+  }
+  const a = await generateMerkleRoot(
+    chunkRoots.map((a2) => Hex2.fromHexInput(a2))
+  );
+  const entry = {
+    chunkset_root: a.toString(),
+    chunk_commitments: chunkRoots.map(
+      (chunk) => Hex2.fromHexInput(chunk).toString()
+    )
+  };
+  return { h: a, entry };
+}
+async function generateCommitments(provider, fullData, onChunk) {
+  const expectedChunksetSize = provider.config.chunkSizeBytes * provider.config.erasure_k;
+  const chunksetCommitments = [];
+  const chunksetCommitmentHashes = [];
+  let rawDataSize = 0;
+  const chunksetGen = readInChunks(fullData, expectedChunksetSize);
+  for await (const [chunksetIdx, chunksetData] of chunksetGen) {
+    rawDataSize += chunksetData.length;
+    const { h, entry } = await generateChunksetCommitments(
+      chunksetIdx,
+      chunksetData,
+      expectedChunksetSize,
+      provider,
+      onChunk
+    );
+    chunksetCommitments.push(entry);
+    chunksetCommitmentHashes.push(h);
+  }
+  if (rawDataSize === 0) {
+    const zeroChunkset = new Uint8Array(expectedChunksetSize);
+    const { h, entry } = await generateChunksetCommitments(
+      0,
+      zeroChunkset,
+      expectedChunksetSize,
+      provider,
+      onChunk
+    );
+    chunksetCommitments.push(entry);
+    chunksetCommitmentHashes.push(h);
+  }
+  return {
+    schema_version: COMMITMENT_SCHEMA_VERSION,
+    raw_data_size: rawDataSize,
+    blob_merkle_root: (await generateMerkleRoot(chunksetCommitmentHashes)).toString(),
+    chunkset_commitments: chunksetCommitments
+  };
+}
+
+// src/core/erasure/clay-codes.ts
+import {
+  createDecoder,
+  createEncoder
+} from "@shelby-protocol/clay-codes";
+function getTotalChunks(config) {
+  return config.erasure_n;
+}
+var ClayErasureCodingProvider = class _ClayErasureCodingProvider {
+  config;
+  encoderCache;
+  decoderCache;
+  lastFunction;
+  constructor(config) {
+    this.config = config;
+    this.lastFunction = "none" /* NONE */;
+  }
+  /**
+   * Static factory method to create an initialized ClayErasureCodingProvider
+   */
+  static async create(config) {
+    const provider = new _ClayErasureCodingProvider(config);
+    [provider.encoderCache, provider.decoderCache] = await Promise.all([
+      createEncoder({
+        n: getTotalChunks(config),
+        k: config.erasure_k,
+        d: config.erasure_d,
+        chunkSizeBytes: config.chunkSizeBytes
+      }),
+      createDecoder({
+        n: getTotalChunks(config),
+        k: config.erasure_k,
+        d: config.erasure_d,
+        chunkSizeBytes: config.chunkSizeBytes,
+        erasedChunkIndexes: []
+      })
+    ]);
+    return provider;
+  }
+  encode(data) {
+    const { erasure_k, chunkSizeBytes } = this.config;
+    if (!this.encoderCache) {
+      throw new Error("Encoder cache is missing");
+    }
+    const systematicCapacity = erasure_k * chunkSizeBytes;
+    if (data.byteLength > systematicCapacity) {
+      throw new Error(
+        `Data size ${data.byteLength} bytes exceeds systematic capacity ${systematicCapacity} bytes (erasure_k=${erasure_k} * chunkSizeBytes=${chunkSizeBytes}).`
+      );
+    }
+    if (this.requiresPadding(data.length)) {
+      throw new Error(
+        `Data size ${data.length} bytes does not match systematic capacity ${systematicCapacity} bytes (erasure_k=${erasure_k} * chunkSizeBytes=${chunkSizeBytes}). Provide pre-padded data before encoding.`
+      );
+    }
+    this.lastFunction = "encoded" /* ENCODED */;
+    return this.encoderCache.erasureCode(data);
+  }
+  decode(available, config) {
+    if (!this.decoderCache) {
+      throw new Error("Decoder cache is missing");
+    }
+    const { erasure_k, chunkSizeBytes } = this.config;
+    if (available.length < erasure_k) {
+      throw new Error(
+        `Insufficient available chunks: need at least ${erasure_k}, received ${available.length}.`
+      );
+    }
+    for (let i = 0; i < available.length; i++) {
+      const chunk = available[i];
+      if (chunk.length !== chunkSizeBytes) {
+        throw new Error(
+          `Chunk ${i} size ${chunk.length} bytes does not match expected chunkSizeBytes ${chunkSizeBytes}.`
+        );
+      }
+    }
+    this.lastFunction = "decoded" /* DECODED */;
+    return this.decoderCache.decode(available, config);
+  }
+  getChunkMerkleRoots() {
+    if (this.decoderCache && this.lastFunction === "decoded" /* DECODED */)
+      return this.decoderCache.getChunkMerkleRoots();
+    if (this.encoderCache && this.lastFunction === "encoded" /* ENCODED */)
+      return this.encoderCache.getChunkMerkleRoots();
+    throw new Error(
+      "You must call encode or decode before calling getChunkMerkleRoots"
+    );
+  }
+  /**
+   * Determines if data can be erasure coded as-is or requires padding.
+   *
+   * Data can be erasure coded without padding if its size exactly matches
+   * the total systematic data capacity (k * chunkSizeBytes).
+   *
+   * @param dataSize - Size of the data in bytes
+   * @returns true if data needs padding, false if it can be coded as-is
+   */
+  requiresPadding(dataSize) {
+    const { erasure_k, chunkSizeBytes } = this.config;
+    const systematicCapacity = erasure_k * chunkSizeBytes;
+    return dataSize !== systematicCapacity;
+  }
+};
+
+// 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/errors.ts
+var ShelbyLocationErrorCodes = {
+  E_LOCATION_NOT_FOUND: "E_LOCATION_NOT_FOUND",
+  E_SELECTED_LOCATION_CONFLICTS_WITH_LOCK: "E_SELECTED_LOCATION_CONFLICTS_WITH_LOCK",
+  E_NO_LOCATION_SELECTED: "E_NO_LOCATION_SELECTED",
+  E_LOCATION_WRITES_FROZEN: "E_LOCATION_WRITES_FROZEN",
+  E_LOCATION_NOT_ACTIVATED: "E_LOCATION_NOT_ACTIVATED"
+};
+function describeLocationError(errorMessage) {
+  if (errorMessage.includes(ShelbyLocationErrorCodes.E_LOCATION_WRITES_FROZEN)) {
+    return "Cannot write: the resolved location is frozen and not currently accepting new data.";
+  }
+  if (errorMessage.includes(ShelbyLocationErrorCodes.E_LOCATION_NOT_ACTIVATED)) {
+    return "Cannot write: the resolved location is not activated yet.";
+  }
+  if (errorMessage.includes(
+    ShelbyLocationErrorCodes.E_SELECTED_LOCATION_CONFLICTS_WITH_LOCK
+  )) {
+    return "Cannot write: the selected location conflicts with the account's locked location preference.";
+  }
+  if (errorMessage.includes(ShelbyLocationErrorCodes.E_NO_LOCATION_SELECTED)) {
+    return "No write location could be resolved: none was selected and the account has no default location or location hint.";
+  }
+  if (errorMessage.includes(ShelbyLocationErrorCodes.E_LOCATION_NOT_FOUND)) {
+    return "Cannot write: the requested location does not exist.";
+  }
+  return void 0;
+}
+
+// src/core/clients/ShelbyBlobClient.ts
+import {
+  AccountAddress as AccountAddress2,
+  Aptos,
+  Hex as Hex3,
+  U32
+} from "@aptos-labs/ts-sdk";
+
+// src/core/constants.ts
+import { Network } from "@aptos-labs/ts-sdk";
+var NetworkToShelbyRPCBaseUrl = {
+  [Network.SHELBYNET]: "https://shelby.shelbynet.shelby.xyz/shelby",
+  [Network.NETNA]: void 0,
+  [Network.DEVNET]: void 0,
+  [Network.TESTNET]: "https://api.testnet.shelby.xyz/shelby",
+  [Network.MAINNET]: void 0,
+  [Network.LOCAL]: "http://localhost:9090",
+  [Network.CUSTOM]: void 0
+};
+var NetworkToShelbyBlobIndexerBaseUrl = {
+  [Network.SHELBYNET]: "https://api.shelbynet.aptoslabs.com/nocode/v1/public/alias/shelby/shelbynet/v1/graphql",
+  [Network.NETNA]: void 0,
+  [Network.DEVNET]: void 0,
+  [Network.TESTNET]: "https://api.testnet.aptoslabs.com/nocode/v1/public/alias/shelby/testnet/v1/graphql",
+  [Network.MAINNET]: void 0,
+  [Network.LOCAL]: "http://localhost:8091/v1/graphql",
+  [Network.CUSTOM]: void 0
+};
+var NetworkToGasStationBaseUrl = {
+  [Network.SHELBYNET]: "https://api.shelbynet.shelby.xyz/gs/v1",
+  [Network.NETNA]: void 0,
+  [Network.DEVNET]: void 0,
+  [Network.TESTNET]: "https://api.testnet.shelby.xyz/gs/v1",
+  [Network.MAINNET]: void 0,
+  [Network.LOCAL]: void 0,
+  [Network.CUSTOM]: void 0
+};
+var SHELBY_DEPLOYER = "0x85fdb9a176ab8ef1d9d9c1b60d60b3924f0800ac1de1cc2085fb0b8bb4988e6a";
+var MICROPAYMENTS_DEPLOYER = "0x1ae7275148bf6ef742b658fd9cbcc2e094201606f4a7bc707bab0201da8043ee";
+
+// 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/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
+  });
+};
+var getShelbyRPCBaseUrl = (config) => {
+  return config.rpc?.baseUrl ?? NetworkToShelbyRPCBaseUrl[config.network] ?? NetworkToShelbyRPCBaseUrl.testnet;
+};
+
+// 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"
+]);
+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
+      })
+    };
+  }
+};
+
+// src/core/clients/ShelbyMetadataClient.ts
+import {
+  AccountAddress as AccountAddress3,
+  Aptos as Aptos2,
+  Hex as Hex4
+} from "@aptos-labs/ts-sdk";
+
+// src/core/types/storage_providers.ts
+var ACTIVE_PROVIDER_CONDITIONS = [
+  "Normal",
+  "Faulty",
+  "Leaving",
+  "Evicted",
+  "PendingLeaving"
+];
+function isActiveProviderCondition(value) {
+  return typeof value === "string" && ACTIVE_PROVIDER_CONDITIONS.includes(value);
+}
+
+// src/core/clients/ShelbyMetadataClient.ts
+function parseActiveProviderCondition(raw) {
+  const variant = raw?.__variant__;
+  if (!isActiveProviderCondition(variant)) {
+    throw new Error(
+      `Unknown ActiveProviderCondition variant: ${JSON.stringify(raw)}`
+    );
+  }
+  return variant;
+}
+function parseStorageProviderState(raw) {
+  switch (raw.__variant__) {
+    case "Active":
+      return {
+        variant: "Active",
+        quota: raw.quota.value,
+        stakeAtStartOfStakingEpoch: raw.stake_at_start_of_staking_epoch,
+        condition: parseActiveProviderCondition(raw.condition)
+      };
+    case "Waitlisted":
+      return {
+        variant: "Waitlisted"
+      };
+    case "Frozen":
+      return {
+        variant: "Frozen",
+        frozenReason: raw.frozen_reason,
+        frozenFrom: raw.frozen_from,
+        frozenTill: raw.frozen_till
+      };
+    default:
+      throw new Error(
+        `Unknown StorageProviderStateDetails variant: ${JSON.stringify(raw)}`
+      );
+  }
+}
+var ShelbyMetadataClient = class {
+  aptos;
+  deployer;
+  /**
+   * The ShelbyMetadataClient is used to interact with the Shelby contract on the Aptos blockchain. This
+   * includes functions like gathering basic details about the Shelby system, including storage provider information.
+   *
+   * @param config.aptos.config - The Aptos config.
+   * @param config.shelbyDeployer - The deployer account address of the Shelby contract. If not provided, the default deployer address will be used.
+   *
+   * @example
+   * ```typescript
+   * const aptos = new Aptos(new AptosConfig({ network: Network.TESTNET }));
+   * const metadataClient = new ShelbyMetadataClient({ aptos });
+   * ```
+   */
+  constructor(config) {
+    this.aptos = new Aptos2(getAptosConfig(config));
+    this.deployer = config.deployer ?? AccountAddress3.fromString(SHELBY_DEPLOYER);
+  }
+  /**
+   * Retrieves storage provider list from the blockchain.
+   *
+   * @returns A list of storage providers, or empty array if none exist.
+   *
+   * @example
+   * ```typescript
+   * const spList = await client.getStorageProviders();
+   * ```
+   */
+  async getStorageProviders() {
+    try {
+      const rawMetadata = await this.aptos.view({
+        payload: {
+          function: `${this.deployer.toString()}::storage_provider_registry::get_all_storage_providers`,
+          functionArguments: []
+        }
+      });
+      const metadata = rawMetadata[0];
+      return metadata.map((provider) => ({
+        address: normalizeAddress(provider.address),
+        ipAddress: provider.ip_address,
+        port: provider.port,
+        blsPublicKey: Hex4.fromHexInput(provider.bls_public_key).toUint8Array(),
+        availabilityZone: provider.availability_zone,
+        state: parseStorageProviderState(provider.state)
+      }));
+    } catch (error) {
+      if (error instanceof Error && // Depending on the network, the error message may show up differently.
+      error.message?.includes("sub_status: Some(404)")) {
+        return [];
+      }
+      throw error;
+    }
+  }
+  /**
+   * Retrieves the names of every activated location (region). Locations that are
+   * registered but not yet brought online are admin-internal and not listed.
+   *
+   * @returns The location name list.
+   *
+   * @example
+   * ```typescript
+   * const locations = await client.getLocationNames();
+   * ```
+   */
+  async getLocationNames() {
+    const names = await this.aptos.view({
+      payload: {
+        function: `${this.deployer.toString()}::location::activated_location_names`,
+        functionArguments: []
+      }
+    });
+    return names[0];
+  }
+  /**
+   * Retrieves the list of placement group addresses in a location.
+   *
+   * @param locationName - The location whose placement groups to list.
+   * @returns The placement group address list, or an empty array if none exist.
+   *
+   * @example
+   * ```typescript
+   * const pgList = await client.getPlacementGroupAddresses("us-east-1");
+   * ```
+   */
+  async getPlacementGroupAddresses(locationName) {
+    try {
+      const pgSizeMetadata = await this.aptos.view({
+        payload: {
+          function: `${this.deployer.toString()}::placement_group_registry::get_number_of_placement_groups`,
+          functionArguments: [locationName]
+        }
+      });
+      if (Number(pgSizeMetadata[0]) === 0) {
+        return [];
+      }
+      const finalPlacementGroupIndex = pgSizeMetadata[0] - 1;
+      const addressMetadataArray = await this.aptos.view({
+        payload: {
+          function: `${this.deployer.toString()}::placement_group_registry::get_placement_group_addresses`,
+          functionArguments: [locationName, 0, finalPlacementGroupIndex]
+        }
+      });
+      const metadata = addressMetadataArray[0];
+      return metadata.map((pg) => normalizeAddress(pg));
+    } 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("E_PLACEMENT_GROUP_NOT_FOUND"))) {
+        return [];
+      }
+      throw error;
+    }
+  }
+  /**
+   * Retrieves the list of slice addresses in a location.
+   *
+   * @param locationName - The location whose slices to list.
+   * @returns The slice group list, or an empty array if none exist.
+   *
+   * @example
+   * ```typescript
+   * const pgList = await client.getSliceAddresses("us-east-1");
+   * ```
+   */
+  async getSliceAddresses(locationName) {
+    try {
+      const sliceSizeMetadata = await this.aptos.view({
+        payload: {
+          function: `${this.deployer.toString()}::slice_registry::get_number_of_slices`,
+          functionArguments: [locationName]
+        }
+      });
+      if (Number(sliceSizeMetadata[0]) === 0) {
+        return [];
+      }
+      const finalSliceIndex = sliceSizeMetadata[0] - 1;
+      const addressMetadataArray = await this.aptos.view({
+        payload: {
+          function: `${this.deployer.toString()}::slice_registry::get_slice_addresses`,
+          functionArguments: [locationName, 0, finalSliceIndex]
+        }
+      });
+      const metadata = addressMetadataArray[0];
+      return metadata.map((slice) => normalizeAddress(slice));
+    } 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("E_SLICE_NOT_FOUND"))) {
+        return [];
+      }
+      throw error;
+    }
+  }
+  /**
+   * Gets the placement group address for a slice.
+   *
+   * @param sliceAddress - The address of the slice account.
+   * @returns The placement group address as a string.
+   */
+  async getPlacementGroupAddressForSlice(sliceAddress) {
+    const sliceMetadata = await this.aptos.view({
+      payload: {
+        function: `${this.deployer.toString()}::slice::get_slice_info`,
+        functionArguments: [sliceAddress.toString()]
+      }
+    });
+    return sliceMetadata[0].placement_group_assignments[0].placement_group_address;
+  }
+  /**
+   * Retrieves the designated storage providers for a slice.
+   *
+   * Designated SPs are those appointed to store data for their slots:
+   * - Active: Currently serving data
+   * - Receiving: Receiving data during slot transfer
+   * - Repairing: Repairing data after crash or failed transfer
+   * - Reconstructing: Reconstructing data if the repair fails
+   *
+   * @param params.account - The address of the slice account.
+   * @returns An array where result[i] is the designated SP for slot i, or null if no SP is designated.
+   *
+   * @example
+   * ```typescript
+   * const providers = await client.getDesignatedStorageProvidersForSlice({ account: sliceAddress });
+   * ```
+   */
+  async getDesignatedStorageProvidersForSlice(params) {
+    const placementGroupAddress = await this.getPlacementGroupAddressForSlice(
+      params.account
+    );
+    const rawMetadata = await this.aptos.view({
+      payload: {
+        function: `${this.deployer.toString()}::placement_group::get_designated_storage_providers`,
+        functionArguments: [placementGroupAddress]
+      }
+    });
+    const providers = rawMetadata[0];
+    return providers.map(
+      (opt) => opt.vec.length > 0 ? normalizeAddress(opt.vec[0]) : null
+    );
+  }
+  /**
+   * Retrieves the active storage providers for a slice.
+   *
+   * Active SPs have a complete copy of the data for the slot, and are not in any data transfer/repair/reconstruction phase.
+   * Active SP can be audited for the data it contains.
+   * Each slot has at most one active SP.
+   *
+   * @param params.account - The address of the slice account.
+   * @returns An array where result[i] is the active SP for slot i, or null if no SP is active.
+   *
+   * @example
+   * ```typescript
+   * const providers = await client.getActiveStorageProvidersForSlice({ account: sliceAddress });
+   * ```
+   */
+  async getActiveStorageProvidersForSlice(params) {
+    const placementGroupAddress = await this.getPlacementGroupAddressForSlice(
+      params.account
+    );
+    const rawMetadata = await this.aptos.view({
+      payload: {
+        function: `${this.deployer.toString()}::placement_group::get_active_storage_providers`,
+        functionArguments: [placementGroupAddress]
+      }
+    });
+    const providers = rawMetadata[0];
+    return providers.map(
+      (opt) => opt.vec.length > 0 ? normalizeAddress(opt.vec[0]) : null
+    );
+  }
+  /**
+   * Retrieves the serving storage providers for a slice.
+   *
+   * Serving SPs are those that can respond to read requests. The serving logic is:
+   * - If an Active SP exists for a slot: Only the Active SP is serving
+   * - If no Active SP (transition in progress): Both Designated and Vacating SPs serve
+   *
+   * Each slot may have multiple serving SPs during transitions.
+   *
+   * @param params.account - The address of the slice account.
+   * @returns An array where result[i] contains the serving SPs for slot i.
+   *
+   * @example
+   * ```typescript
+   * const providers = await client.getServingStorageProvidersForSlice({ account: sliceAddress });
+   * ```
+   */
+  async getServingStorageProvidersForSlice(params) {
+    const placementGroupAddress = await this.getPlacementGroupAddressForSlice(
+      params.account
+    );
+    const rawMetadata = await this.aptos.view({
+      payload: {
+        function: `${this.deployer.toString()}::placement_group::get_serving_storage_providers`,
+        functionArguments: [placementGroupAddress]
+      }
+    });
+    const providers = rawMetadata[0];
+    return providers.map(
+      (slotProviders) => slotProviders.map((addr) => normalizeAddress(addr))
+    );
+  }
+};
+
+// src/core/clients/ShelbyRPCClient.ts
+import {
+  Hex as Hex6
+} from "@aptos-labs/ts-sdk";
+
+// src/core/layout.ts
+import { z as z2 } from "zod";
+var BlobNameSchema = z2.string().min(1, "Blob name path parameter cannot be empty.").max(
+  190,
+  "Blob name suffix cannot exceed 190 characters (on-chain full key limit is 256 bytes)."
+).refine((name) => !name.endsWith("/"), {
+  message: "Blob name cannot end with a slash"
+});
+
+// src/core/promises.ts
+function sleep(ms) {
+  return new Promise((resolve) => setTimeout(resolve, ms));
+}
+
+// src/core/rpc-responses.ts
+import { z as z3 } from "zod";
+var ChallengeResponseSchema = z3.object({
+  challenge: z3.string(),
+  expiresAt: z3.number()
+});
+var RPCErrorResponseSchema = z3.object({
+  error: z3.string()
+});
+var StaleMicropaymentErrorResponseSchema = z3.object({
+  error: z3.string().optional(),
+  storedMicropayment: z3.string().optional()
+});
+
+// src/core/types/payments.ts
+import {
+  AccountAddress as AccountAddress4,
+  Deserializer,
+  Hex as Hex5,
+  Serializer
+} from "@aptos-labs/ts-sdk";
+var MICROPAYMENTS_MODULE_NAME = "micropayments";
+var WITHDRAW_APPROVAL_STRUCT_NAME = "WithdrawApproval";
+function serializeTypeInfo(serializer, moduleAddress, moduleName, structName) {
+  moduleAddress.serialize(serializer);
+  const moduleNameBytes = new TextEncoder().encode(moduleName);
+  serializer.serializeBytes(moduleNameBytes);
+  const structNameBytes = new TextEncoder().encode(structName);
+  serializer.serializeBytes(structNameBytes);
+}
+var StaleChannelStateError = class _StaleChannelStateError extends Error {
+  /**
+   * The last valid micropayment stored by the server.
+   * Clients can use this to reset their local channel state.
+   */
+  storedMicropayment;
+  constructor(storedMicropayment, message) {
+    super(
+      message ?? "Client has stale channel state. Use the returned micropayment to reset local state."
+    );
+    this.name = "StaleChannelStateError";
+    this.storedMicropayment = storedMicropayment;
+  }
+  /**
+   * Returns the stored micropayment as a base64-encoded string.
+   */
+  toBase64() {
+    const bytes = this.storedMicropayment.bcsToBytes();
+    const binaryString = Array.from(
+      bytes,
+      (byte) => String.fromCharCode(byte)
+    ).join("");
+    return btoa(binaryString);
+  }
+  /**
+   * Creates a StaleChannelStateError from a base64-encoded micropayment string.
+   */
+  static fromBase64(base64, message) {
+    const binaryString = atob(base64);
+    const bytes = Uint8Array.from(binaryString, (char) => char.charCodeAt(0));
+    const micropayment = SenderBuiltMicropayment.deserialize(bytes);
+    return new _StaleChannelStateError(micropayment, message);
+  }
+};
+var SenderBuiltMicropayment = class _SenderBuiltMicropayment {
+  /**
+   * The sender's address (owner of the payment channel).
+   */
+  sender;
+  /**
+   * The receiver's address (beneficiary of the withdrawal).
+   */
+  receiver;
+  /**
+   * The unique ID of the payment channel.
+   */
+  paymentChannelId;
+  /**
+   * The cumulative amount the receiver is authorized to withdraw.
+   */
+  amount;
+  /**
+   * The fungible asset metadata address.
+   */
+  fungibleAssetAddress;
+  /**
+   * Monotonically increasing sequence number for replay protection.
+   */
+  sequenceNumber;
+  /**
+   * The sender's Ed25519 public key (32 bytes).
+   * Used by the receiver to verify the signature before submitting.
+   */
+  publicKey;
+  /**
+   * The Ed25519 signature of the SignedMessage<WithdrawApproval> struct.
+   * The SignedMessage includes TypeInfo for domain separation.
+   */
+  signature;
+  /**
+   * The deployer address of the micropayments module.
+   * This is needed to reconstruct the TypeInfo for signature verification.
+   */
+  deployer;
+  constructor(sender, receiver, paymentChannelId, amount, fungibleAssetAddress, sequenceNumber, publicKey, signature, deployer) {
+    this.sender = sender;
+    this.receiver = receiver;
+    this.paymentChannelId = paymentChannelId;
+    this.amount = amount;
+    this.fungibleAssetAddress = fungibleAssetAddress;
+    this.sequenceNumber = sequenceNumber;
+    this.publicKey = publicKey;
+    this.signature = signature;
+    this.deployer = deployer ?? AccountAddress4.fromString(MICROPAYMENTS_DEPLOYER);
+  }
+  /**
+   * Creates the BCS-serialized message that was signed.
+   * This is a SignedMessage<WithdrawApproval> which includes:
+   * 1. TypeInfo (module_address, module_name, struct_name)
+   * 2. WithdrawApproval struct fields
+   *
+   * This format is used with signature_verify_strict_t for domain separation.
+   */
+  getSignedMessage() {
+    return _SenderBuiltMicropayment.buildSignedMessage({
+      deployer: this.deployer,
+      sender: this.sender,
+      receiver: this.receiver,
+      fungibleAssetAddress: this.fungibleAssetAddress,
+      amount: this.amount,
+      paymentChannelId: this.paymentChannelId,
+      sequenceNumber: this.sequenceNumber
+    });
+  }
+  /**
+   * Static helper to build the SignedMessage<WithdrawApproval> bytes from raw parameters.
+   * This can be used to create the message for signing without constructing the full object.
+   *
+   * @param params - The withdrawal approval parameters.
+   * @returns The BCS-serialized SignedMessage<WithdrawApproval> bytes.
+   */
+  static buildSignedMessage(params) {
+    const serializer = new Serializer();
+    serializeTypeInfo(
+      serializer,
+      params.deployer,
+      MICROPAYMENTS_MODULE_NAME,
+      WITHDRAW_APPROVAL_STRUCT_NAME
+    );
+    params.sender.serialize(serializer);
+    params.receiver.serialize(serializer);
+    params.fungibleAssetAddress.serialize(serializer);
+    serializer.serializeU64(params.amount);
+    serializer.serializeU64(params.paymentChannelId);
+    serializer.serializeU64(params.sequenceNumber);
+    return serializer.toUint8Array();
+  }
+  serialize(serializer) {
+    this.sender.serialize(serializer);
+    this.receiver.serialize(serializer);
+    this.fungibleAssetAddress.serialize(serializer);
+    serializer.serializeU64(this.amount);
+    serializer.serializeU64(this.paymentChannelId);
+    serializer.serializeU64(this.sequenceNumber);
+    serializer.serializeBytes(this.publicKey);
+    serializer.serializeBytes(this.signature);
+    this.deployer.serialize(serializer);
+  }
+  bcsToBytes() {
+    const serializer = new Serializer();
+    this.serialize(serializer);
+    return serializer.toUint8Array();
+  }
+  bcsToHex() {
+    return Hex5.fromHexInput(this.bcsToBytes());
+  }
+  toStringWithoutPrefix() {
+    return this.bcsToHex().toStringWithoutPrefix();
+  }
+  toString() {
+    return this.bcsToHex().toString();
+  }
+  /**
+   * Deserializes a SenderBuiltMicropayment from BCS bytes.
+   * @param bytes - The bytes to deserialize from (Uint8Array or hex string).
+   * @returns A new SenderBuiltMicropayment instance.
+   */
+  static deserialize(bytes) {
+    const bytesArray = typeof bytes === "string" ? Hex5.fromHexInput(bytes).toUint8Array() : bytes;
+    const deserializer = new Deserializer(bytesArray);
+    const sender = AccountAddress4.deserialize(deserializer);
+    const receiver = AccountAddress4.deserialize(deserializer);
+    const fungibleAssetAddress = AccountAddress4.deserialize(deserializer);
+    const amount = deserializer.deserializeU64();
+    const paymentChannelId = deserializer.deserializeU64();
+    const sequenceNumber = deserializer.deserializeU64();
+    const publicKey = deserializer.deserializeBytes();
+    const signature = deserializer.deserializeBytes();
+    const deployer = AccountAddress4.deserialize(deserializer);
+    return new _SenderBuiltMicropayment(
+      sender,
+      receiver,
+      paymentChannelId,
+      amount,
+      fungibleAssetAddress,
+      sequenceNumber,
+      publicKey,
+      signature,
+      deployer
+    );
+  }
+};
+
+// src/core/clients/ShelbyRPCClient.ts
+var MICROPAYMENT_HEADER = "X-Shelby-Micropayment";
+var BLOB_OWNER_CHALLENGE_HEADER = "X-Shelby-Challenge";
+var BLOB_OWNER_SIGNATURE_HEADER = "X-Shelby-Signature";
+var BLOB_OWNER_PUBLIC_KEY_HEADER = "X-Shelby-Public-Key";
+var BLOB_OWNER_AUTH_SCHEME_HEADER = "X-Shelby-Auth-Scheme";
+var BLOB_OWNER_IDENTITY_HEADER = "X-Shelby-Identity";
+var BLOB_OWNER_DOMAIN_HEADER = "X-Shelby-Domain";
+var BLOB_OWNER_AUTH_FUNCTION_HEADER = "X-Shelby-Auth-Function";
+var INCLUSION_PROOF_HEADER = "X-Shelby-Inclusion-Proof";
+function buildAuthHeaders(auth) {
+  const signatureBase64 = btoa(
+    Array.from(auth.signature, (byte) => String.fromCharCode(byte)).join("")
+  );
+  const publicKeyHex = Hex6.fromHexInput(auth.publicKey).toString();
+  const headers = {
+    [BLOB_OWNER_CHALLENGE_HEADER]: auth.challenge,
+    [BLOB_OWNER_SIGNATURE_HEADER]: signatureBase64,
+    [BLOB_OWNER_PUBLIC_KEY_HEADER]: publicKeyHex
+  };
+  if (auth.authScheme === "derivable") {
+    headers[BLOB_OWNER_AUTH_SCHEME_HEADER] = auth.authScheme;
+    headers[BLOB_OWNER_IDENTITY_HEADER] = auth.identity;
+    headers[BLOB_OWNER_DOMAIN_HEADER] = auth.domain;
+    headers[BLOB_OWNER_AUTH_FUNCTION_HEADER] = auth.authFunction;
+  } else if (auth.authScheme) {
+    headers[BLOB_OWNER_AUTH_SCHEME_HEADER] = auth.authScheme;
+  }
+  return headers;
+}
+function encodeURIComponentKeepSlashes(str) {
+  return encodeURIComponent(str).replace(/%2F/g, "/");
+}
+async function generateChunksetInclusionProof(chunksetRoots, chunksetIndex) {
+  if (chunksetRoots.length === 0) {
+    throw new Error("Cannot generate inclusion proof for empty chunkset roots");
+  }
+  if (chunksetIndex < 0 || chunksetIndex >= chunksetRoots.length) {
+    throw new Error(
+      `Chunkset index ${chunksetIndex} out of range [0, ${chunksetRoots.length})`
+    );
+  }
+  if (chunksetRoots.length === 1) {
+    return [];
+  }
+  const zeroHash = new Uint8Array(32);
+  const siblings = [];
+  let currentLeaves = chunksetRoots.map((h) => h.toUint8Array());
+  let currentIdx = chunksetIndex;
+  while (currentLeaves.length > 1) {
+    if (currentLeaves.length % 2 !== 0) {
+      currentLeaves.push(zeroHash);
+    }
+    const siblingIdx = currentIdx % 2 === 0 ? currentIdx + 1 : currentIdx - 1;
+    siblings.push(currentLeaves[siblingIdx]);
+    const nextLeaves = [];
+    for (let i = 0; i < currentLeaves.length; i += 2) {
+      const combined = await concatHashes([
+        currentLeaves[i],
+        currentLeaves[i + 1]
+      ]);
+      nextLeaves.push(combined.toUint8Array());
+    }
+    currentLeaves = nextLeaves;
+    currentIdx = Math.floor(currentIdx / 2);
+  }
+  return siblings;
+}
+function encodeInclusionProof(siblings) {
+  if (siblings.length === 0) {
+    return "NONE";
+  }
+  const totalBytes = siblings.length * 32;
+  const combined = new Uint8Array(totalBytes);
+  let offset = 0;
+  for (const sibling of siblings) {
+    combined.set(sibling, offset);
+    offset += 32;
+  }
+  const binaryString = Array.from(
+    combined,
+    (byte) => String.fromCharCode(byte)
+  ).join("");
+  return btoa(binaryString);
+}
+function validateTotalBytes(totalBytes) {
+  if (!Number.isInteger(totalBytes) || totalBytes < 0) {
+    throw new Error("totalBytes must be a non-negative integer");
+  }
+}
+function isRetryableStatus(status) {
+  return status === 408 || status === 429 || status >= 500;
+}
+function getErrorCode(error) {
+  if (typeof error === "object" && error !== null && "code" in error && typeof error.code === "string") {
+    return error.code;
+  }
+  if (error instanceof Error) {
+    const match = error.message.match(/\bE[A-Z0-9_]+\b/);
+    return match?.[0];
+  }
+  return void 0;
+}
+var ShelbyRPCClient = class {
+  baseUrl;
+  apiKey;
+  rpcConfig;
+  indexer;
+  #signChallengeOverride;
+  /**
+   * Creates a new ShelbyRPCClient for interacting with Shelby RPC nodes.
+   * This client handles blob storage operations including upload and download.
+   *
+   * @param config - The client configuration object.
+   * @param config.network - The Shelby network to use.
+   * @param options.signChallengeHandler - Optional override for challenge
+   *   signing. When set, `putBlobChunksets` uses this instead of the built-in
+   *   `signChallenge`. Intended for kit-level overrides (e.g. Solana DAA).
+   *
+   * @example
+   * ```typescript
+   * const client = new ShelbyRPCClient({
+   *   network: Network.SHELBYNET,
+   *   apiKey: "AG-***",
+   * });
+   * ```
+   */
+  constructor(config, options) {
+    this.baseUrl = getShelbyRPCBaseUrl(config);
+    this.apiKey = config.apiKey ?? config.rpc?.apiKey;
+    this.rpcConfig = config.rpc ?? {};
+    this.indexer = getShelbyIndexerClient(config);
+    this.#signChallengeOverride = options?.signChallengeHandler;
+  }
+  /**
+   * Request an authentication challenge for the given account.
+   * The challenge must be signed and included in subsequent authenticated requests.
+   *
+   * @param account - The Aptos account address to authenticate as.
+   * @returns The challenge string and expiration timestamp.
+   *
+   * @example
+   * ```typescript
+   * const { challenge, expiresAt } = await client.getChallenge(account.accountAddress);
+   * const auth = client.signChallenge(account, challenge);
+   * ```
+   */
+  async getChallenge(account) {
+    const response = await fetch(
+      buildRequestUrl("/v1/auth/challenge", this.baseUrl),
+      {
+        method: "POST",
+        headers: {
+          "Content-Type": "application/json",
+          ...this.apiKey ? { Authorization: `Bearer ${this.apiKey}` } : {}
+        },
+        body: JSON.stringify({ account: account.toString() })
+      }
+    );
+    if (!response.ok) {
+      const errorBody = await response.text().catch(() => "");
+      throw new Error(
+        `Failed to get challenge: status ${response.status}, body: ${errorBody}`
+      );
+    }
+    return ChallengeResponseSchema.parse(await response.json());
+  }
+  /**
+   * Sign a challenge using the given account and return auth credentials.
+   *
+   * @param account - The Aptos account to sign with.
+   * @param challenge - The hex-encoded challenge string from getChallenge().
+   * @returns BlobOwnerAuth credentials for authenticated requests.
+   */
+  signChallenge(account, challenge) {
+    const challengeBytes = Hex6.fromHexInput(challenge).toUint8Array();
+    const signature = account.sign(challengeBytes);
+    return {
+      challenge,
+      signature: signature.toUint8Array(),
+      publicKey: account.publicKey.toUint8Array()
+    };
+  }
+  /**
+   * Upload a single chunkset via the v2 chunkset API.
+   */
+  async #uploadChunkset(params) {
+    const maxNonBusyRetries = 5;
+    let lastResponse;
+    let lastError;
+    let attempts = 0;
+    let consecutive429s = 0;
+    let nonBusyRetries = 0;
+    const chunksetUrl = buildRequestUrl(
+      `/v2/chunksets/${params.account}/${params.chunksetIndex}/${params.uid}`,
+      this.baseUrl
+    );
+    const authHeaders = buildAuthHeaders(params.auth);
+    while (true) {
+      if (params.signal?.aborted) {
+        throw new DOMException("Upload aborted", "AbortError");
+      }
+      attempts++;
+      try {
+        lastResponse = await fetch(chunksetUrl, {
+          method: "PUT",
+          headers: {
+            "Content-Type": "application/octet-stream",
+            ...this.apiKey ? { Authorization: `Bearer ${this.apiKey}` } : {},
+            ...authHeaders,
+            [INCLUSION_PROOF_HEADER]: params.inclusionProof
+          },
+          body: params.chunksetData,
+          signal: params.signal
+        });
+        lastError = void 0;
+      } catch (error) {
+        if (error instanceof DOMException && error.name === "AbortError") {
+          throw error;
+        }
+        lastError = error;
+        consecutive429s = 0;
+        nonBusyRetries++;
+        if (nonBusyRetries < maxNonBusyRetries) {
+          const delay2 = 2 ** nonBusyRetries * 100;
+          await sleep(delay2);
+          continue;
+        }
+        break;
+      }
+      if (lastResponse.ok) {
+        const json = await lastResponse.json();
+        const spAcks = json.spAcks?.map((ack) => ({
+          slot: ack.slot,
+          signature: Uint8Array.from(
+            atob(ack.signature),
+            (c) => c.charCodeAt(0)
+          )
+        }));
+        return {
+          success: json.success,
+          acksReceived: json.acksReceived,
+          spAcks
+        };
+      }
+      if (lastResponse.status === 429) {
+        consecutive429s++;
+        const baseDelay = 500;
+        const jitter = Math.random() * 200;
+        const delay2 = Math.min(
+          3e4,
+          2 ** consecutive429s * baseDelay + jitter
+        );
+        await sleep(delay2);
+        continue;
+      }
+      consecutive429s = 0;
+      if (!isRetryableStatus(lastResponse.status)) {
+        break;
+      }
+      nonBusyRetries++;
+      if (nonBusyRetries >= maxNonBusyRetries) {
+        break;
+      }
+      const delay = 2 ** nonBusyRetries * 100;
+      await sleep(delay);
+    }
+    if (lastError !== void 0) {
+      const errorCode = getErrorCode(lastError);
+      const errorMessage = lastError instanceof Error ? lastError.message : String(lastError);
+      throw new Error(
+        `Failed to upload chunkset ${params.chunksetIndex} after ${attempts} attempt${attempts === 1 ? "" : "s"}. ${errorCode ? `(${errorCode}) ` : ""}Last error: ${errorMessage}`,
+        { cause: lastError }
+      );
+    }
+    const errorBody = await lastResponse?.text().catch(() => "");
+    throw new Error(
+      `Failed to upload chunkset ${params.chunksetIndex} after ${attempts} attempt${attempts === 1 ? "" : "s"}. status: ${lastResponse?.status}, body: ${errorBody}`
+    );
+  }
+  /**
+   * Uploads blob data to the Shelby RPC node using the v2 chunkset API.
+   * This method authenticates using challenge-response and uploads chunksets
+   * directly to storage providers via the RPC's worker pool.
+   *
+   * This method:
+   * - Sends raw chunkset data directly to the RPC for erasure encoding
+   * - Requires pre-computed blob commitments to generate inclusion proofs
+   * - Does not support resume (each chunkset is idempotent on the SP side)
+   *
+   * @param params.account - The Aptos Account (with signing capability) that owns the blob.
+   * @param params.uid - The blob's on-chain UID (from `BlobRegisteredEvent` at registration).
+   * @param params.blobData - The raw blob data as a Uint8Array or ReadableStream.
+   * @param params.commitments - Pre-computed blob commitments (from generateCommitments).
+   * @param params.totalBytes - Total byte length. Required for streams; optional for Uint8Array.
+   * @param params.chunksetConcurrency - Number of chunksets to upload in parallel. Defaults to 4.
+   * @param params.onProgress - Optional callback for upload progress.
+   * @param params.signal - Optional AbortSignal for cancellation. When aborted, in-flight
+   *   HTTP requests are cancelled and an AbortError is thrown.
+   *
+   * @example
+   * ```typescript
+   * // First, generate commitments for the blob
+   * const commitments = await generateCommitments(provider, fileData);
+   *
+   * // Register the blob on chain, then read its UID from the register tx's
+   * // BlobRegisteredEvent (see ShelbyBlobClient.registeredBlobUids).
+   *
+   * // Upload using chunkset API
+   * await rpcClient.putBlobChunksets({
+   *   account: myAccount,
+   *   uid: blobUid,
+   *   blobData: fileData,
+   *   commitments,
+   *   chunksetConcurrency: 8,
+   * });
+   * ```
+   */
+  async putBlobChunksets(params) {
+    let totalBytes;
+    if (params.blobData instanceof Uint8Array) {
+      totalBytes = params.totalBytes ?? params.blobData.length;
+      if (totalBytes !== params.blobData.length) {
+        throw new Error(
+          "totalBytes must match blobData.length when blobData is a Uint8Array"
+        );
+      }
+    } else {
+      if (params.totalBytes === void 0) {
+        throw new Error(
+          "totalBytes is required when blobData is a ReadableStream"
+        );
+      }
+      totalBytes = params.totalBytes;
+    }
+    validateTotalBytes(totalBytes);
+    const chunksetConcurrency = params.chunksetConcurrency ?? 4;
+    const totalChunksets = params.commitments.chunkset_commitments.length;
+    const rawDataSizeFromCommitments = params.commitments.raw_data_size;
+    if (rawDataSizeFromCommitments !== totalBytes) {
+      throw new Error(
+        `Data size mismatch: commitments were generated for ${rawDataSizeFromCommitments} bytes, but totalBytes=${totalBytes}. This will cause inclusion proof verification to fail.`
+      );
+    }
+    const chunksetRoots = params.commitments.chunkset_commitments.map(
+      (c) => Hex6.fromHexString(c.chunkset_root)
+    );
+    const { challenge } = await this.getChallenge(
+      params.account.accountAddress
+    );
+    const signFn = this.#signChallengeOverride ?? this.signChallenge.bind(this);
+    const auth = signFn(params.account, challenge);
+    const firstChunkset = params.commitments.chunkset_commitments[0];
+    if (!firstChunkset) {
+      throw new Error("Commitments must have at least one chunkset");
+    }
+    const erasure_n = firstChunkset.chunk_commitments.length;
+    const matchingEntry = findErasureSchemeByErasureN(erasure_n);
+    if (!matchingEntry) {
+      throw new Error(
+        `Unknown erasure coding scheme with erasure_n=${erasure_n}`
+      );
+    }
+    const [schemeKey, matchingParams] = matchingEntry;
+    const erasure_k = matchingParams.erasure_k;
+    const { chunkSizeBytes } = ERASURE_CODE_AND_CHUNK_MAPPING[schemeKey];
+    const chunksetSize = erasure_k * chunkSizeBytes;
+    const expectedChunksetCount = totalBytes === 0 ? 1 : Math.ceil(totalBytes / chunksetSize);
+    if (expectedChunksetCount !== totalChunksets) {
+      throw new Error(
+        `Chunkset count mismatch: expected ${expectedChunksetCount} chunksets for ${totalBytes} bytes with chunksetSize=${chunksetSize}, but commitments have ${totalChunksets} chunksets. This suggests the commitments were generated with a different encoding scheme.`
+      );
+    }
+    let uploadedBytes = 0;
+    let bytesReadFromSource = 0;
+    const inFlight = /* @__PURE__ */ new Set();
+    async function* chunksetsFromBlob() {
+      if (totalBytes === 0) {
+        yield [0, new Uint8Array(chunksetSize)];
+        return;
+      }
+      yield* readInChunks(params.blobData, chunksetSize);
+    }
+    const chunksetIterator = chunksetsFromBlob();
+    const aggregatedAcks = /* @__PURE__ */ new Map();
+    const internalAbort = new AbortController();
+    if (params.signal?.aborted) {
+      internalAbort.abort();
+    } else if (params.signal) {
+      params.signal.addEventListener("abort", () => internalAbort.abort(), {
+        once: true
+      });
+    }
+    let iteratorDone = false;
+    let firstError = null;
+    while (!iteratorDone || inFlight.size > 0) {
+      if (internalAbort.signal.aborted) {
+        throw firstError ?? new DOMException("Upload aborted", "AbortError");
+      }
+      while (inFlight.size < chunksetConcurrency && !iteratorDone) {
+        const { value, done } = await chunksetIterator.next();
+        if (done) {
+          iteratorDone = true;
+          break;
+        }
+        const [chunksetIdx, chunksetData] = value;
+        bytesReadFromSource += totalBytes === 0 ? 0 : chunksetData.byteLength;
+        const expectedCommitment = params.commitments.chunkset_commitments[chunksetIdx];
+        if (!expectedCommitment) {
+          throw new Error(
+            `Chunkset index ${chunksetIdx} out of range. Commitments only have ${totalChunksets} chunksets. This suggests a chunkset size mismatch between commitment generation and upload.`
+          );
+        }
+        const proofSiblings = await generateChunksetInclusionProof(
+          chunksetRoots,
+          chunksetIdx
+        );
+        const inclusionProof = encodeInclusionProof(proofSiblings);
+        const chunksetDataCopy = new Uint8Array(chunksetData);
+        const chunksetBytes = chunksetDataCopy.length;
+        const uploadPromise = (async () => {
+          const result = await this.#uploadChunkset({
+            account: params.account.accountAddress.toString(),
+            uid: params.uid,
+            chunksetIndex: chunksetIdx,
+            inclusionProof,
+            chunksetData: chunksetDataCopy,
+            auth,
+            signal: internalAbort.signal
+          });
+          const chunksetSpAcks = result.spAcks?.map((ack) => ({
+            slot: ack.slot,
+            signature: ack.signature
+          }));
+          if (chunksetSpAcks) {
+            for (const ack of chunksetSpAcks) {
+              aggregatedAcks.set(ack.slot, ack.signature);
+            }
+          }
+          uploadedBytes += chunksetBytes;
+          params.onProgress?.({
+            phase: "uploading",
+            chunksetIdx,
+            totalChunksets,
+            chunksetBytes,
+            uploadedBytes,
+            totalBytes,
+            acksReceived: result.acksReceived,
+            spAcks: chunksetSpAcks
+          });
+        })().catch((err) => {
+          if (!firstError) {
+            firstError = err;
+            internalAbort.abort();
+          }
+        }).finally(() => {
+          inFlight.delete(uploadPromise);
+        });
+        inFlight.add(uploadPromise);
+      }
+      if (inFlight.size > 0) {
+        await Promise.race(inFlight);
+      }
+    }
+    if (firstError) {
+      throw firstError;
+    }
+    if (bytesReadFromSource !== totalBytes) {
+      throw new Error(
+        `Data source produced ${bytesReadFromSource} bytes, but expected ${totalBytes} bytes. The stream may have ended prematurely, resulting in an incomplete upload.`
+      );
+    }
+    const spAcks = Array.from(
+      aggregatedAcks.entries()
+    ).map(([slot, signature]) => ({ slot, signature }));
+    return { spAcks };
+  }
+  /**
+   * Downloads a blob from the Shelby RPC node.
+   * Returns a streaming response with validation to ensure data integrity.
+   *
+   * @param params.account - The account that owns the blob.
+   * @param params.blobName - The name/path of the blob (e.g. "folder/file.txt").
+   * @param params.range - Optional byte range for partial downloads.
+   * @param params.range.start - Starting byte position (inclusive).
+   * @param params.range.end - Ending byte position (inclusive, optional).
+   * @param params.micropayment - Optional micropayment to attach to the request.
+   *
+   * @returns A ShelbyBlob object containing the account, name, readable stream, and content length.
+   *
+   * @throws Error if the download fails or content length doesn't match.
+   * @throws StaleChannelStateError if the micropayment is stale (server has newer state).
+   *
+   * @example
+   * ```typescript
+   * // Download entire blob
+   * const blob = await client.getBlob({
+   *   account: AccountAddress.from("0x1"),
+   *   blobName: "documents/report.pdf"
+   * });
+   *
+   * // Download partial content (bytes 100-199)
+   * const partial = await client.getBlob({
+   *   account: AccountAddress.from("0x1"),
+   *   blobName: "large-file.bin",
+   *   range: { start: 100, end: 199 }
+   * });
+   *
+   * // Download with micropayment
+   * const blob = await client.getBlob({
+   *   account: AccountAddress.from("0x1"),
+   *   blobName: "documents/report.pdf",
+   *   micropayment: senderBuiltMicropayment
+   * });
+   * ```
+   */
+  async getBlob(params) {
+    BlobNameSchema.parse(params.blobName);
+    const url = buildRequestUrl(
+      `/v1/blobs/${params.account.toString()}/${encodeURIComponentKeepSlashes(
+        params.blobName
+      )}`,
+      this.baseUrl
+    );
+    const headers = new Headers();
+    if (params.range !== void 0) {
+      const { start, end } = params.range;
+      if (end === void 0) {
+        headers.set("Range", `bytes=${start}-`);
+      } else {
+        if (end < start) {
+          throw new Error("Range end cannot be less than start.");
+        }
+        headers.set("Range", `bytes=${start}-${end}`);
+      }
+    }
+    if (this.apiKey) {
+      headers.set("Authorization", `Bearer ${this.apiKey}`);
+    }
+    if (params.micropayment) {
+      const bytes = params.micropayment.bcsToBytes();
+      const binaryString = Array.from(
+        bytes,
+        (byte) => String.fromCharCode(byte)
+      ).join("");
+      headers.set(MICROPAYMENT_HEADER, btoa(binaryString));
+    }
+    const response = await fetch(url, { headers });
+    if (response.status === 409) {
+      let json;
+      try {
+        json = await response.json();
+      } catch {
+        throw new Error(
+          `Failed to download blob: ${response.status} ${response.statusText}`
+        );
+      }
+      const parseResult = StaleMicropaymentErrorResponseSchema.safeParse(json);
+      if (!parseResult.success) {
+        throw new Error(
+          `Failed to download blob: ${response.status} ${response.statusText}`
+        );
+      }
+      const errorBody = parseResult.data;
+      if (errorBody.storedMicropayment) {
+        throw StaleChannelStateError.fromBase64(
+          errorBody.storedMicropayment,
+          errorBody.error
+        );
+      }
+      throw new Error(
+        errorBody.error ?? `Failed to download blob: ${response.status} ${response.statusText}`
+      );
+    }
+    if (!response.ok) {
+      throw new Error(
+        `Failed to download blob: ${response.status} ${response.statusText}`
+      );
+    }
+    if (!response.body) {
+      throw new Error("Response body is null");
+    }
+    const contentLengthHeader = response.headers.get("content-length");
+    if (contentLengthHeader === null) {
+      throw new Error(
+        "Response did not have content-length header, which is required"
+      );
+    }
+    const expectedContentLength = Number.parseInt(contentLengthHeader, 10);
+    if (Number.isNaN(expectedContentLength)) {
+      throw new Error(
+        `Invalid content-length header received: ${contentLengthHeader}`
+      );
+    }
+    const validatingStream = new ReadableStream({
+      start(controller) {
+        const maybeReader = response.body?.getReader();
+        if (!maybeReader) {
+          controller.error(new Error("Response body reader is unavailable"));
+          return;
+        }
+        const reader = maybeReader;
+        let bytesReceived = 0;
+        function pump() {
+          return reader.read().then(({ done, value }) => {
+            if (done) {
+              if (bytesReceived !== expectedContentLength) {
+                controller.error(
+                  new Error(
+                    `Downloaded data size (${bytesReceived} bytes) does not match content-length header (${expectedContentLength} bytes). This might indicate a partial or corrupted download.`
+                  )
+                );
+                return;
+              }
+              controller.close();
+              return;
+            }
+            bytesReceived += value.byteLength;
+            controller.enqueue(value);
+            return pump();
+          }).catch((error) => {
+            controller.error(error);
+          });
+        }
+        return pump();
+      }
+    });
+    return {
+      account: normalizeAddress(params.account),
+      name: params.blobName,
+      readable: validatingStream,
+      contentLength: expectedContentLength
+    };
+  }
+};
+
+// src/core/clients/ShelbyClient.ts
+var ShelbyClient = class {
+  /**
+   * The coordination client is used to interact with the Aptos blockchain which handles the commitments
+   * and metadata for blobs.
+   */
+  coordination;
+  /**
+   * The metadata client is used for protocol-level metadata queries.
+   */
+  metadata;
+  /**
+   * The RPC client is used to interact with the Shelby RPC node which can be responsible for storing,
+   * confirming, and retrieving blobs from the storage layer.
+   *
+   * If not provided, the default RPC client will be created.
+   */
+  rpc;
+  /**
+   * The configuration for the Shelby client.
+   */
+  config;
+  /**
+   * The Aptos client.
+   *
+   * If not provided, a default Aptos client will be created.
+   */
+  aptos;
+  /**
+   * The erasure coding provider used for encoding/decoding operations.
+   * Lazily initialized on first use if not provided.
+   */
+  _provider;
+  /**
+   * Creates a new ShelbyClient instance for interacting with the Shelby Protocol.
+   * This client combines blockchain operations (via coordination) and storage operations (via RPC).
+   *
+   * @param config - The client configuration object.
+   * @param config.aptos.config - The Aptos network configuration.
+   * @param config.shelby.rpc.baseUrl - The base URL of the Shelby RPC node (optional, defaults to devnet).
+   * @param config.shelby.indexer - The indexer configuration for GraphQL queries.
+   * @param provider - Optional erasure coding provider for encoding/decoding operations.
+   *                   If not provided, a ClayErasureCodingProvider will be created on first use.
+   *                   Pass a shared provider to reuse across multiple clients.
+   *
+   * @example
+   * ```typescript
+   * // Basic usage (provider created automatically)
+   * const client = new ShelbyClient({
+   *   network: Network.SHELBYNET,
+   * });
+   *
+   * // Advanced: Share provider across multiple clients
+   * const provider = await ClayErasureCodingProvider.create();
+   * const mainnetClient = new ShelbyClient(mainnetConfig, provider);
+   * const devnetClient = new ShelbyClient(devnetConfig, provider);
+   * ```
+   */
+  constructor(config, provider) {
+    this.config = config;
+    this.aptos = new Aptos3(getAptosConfig(config));
+    this.coordination = new ShelbyBlobClient(config);
+    this.metadata = new ShelbyMetadataClient(config);
+    this.rpc = new ShelbyRPCClient(config, {
+      signChallengeHandler: (account, challenge) => this.signChallenge(account, challenge)
+    });
+    this._provider = provider;
+  }
+  /**
+   * Sign an authentication challenge for blob owner verification.
+   *
+   * The default implementation delegates to `ShelbyRPCClient.signChallenge`
+   * which works for standard Ed25519 accounts. Kits that use derived /
+   * abstracted accounts (Solana, Ethereum) should override this method to
+   * provide the correct public key bytes and derivation metadata.
+   */
+  signChallenge(account, challenge) {
+    return this.rpc.signChallenge(account, challenge);
+  }
+  /**
+   * Get the erasure coding provider, creating it if necessary.
+   * This allows lazy initialization for users who don't provide a provider.
+   */
+  async getProvider() {
+    if (!this._provider) {
+      this._provider = await ClayErasureCodingProvider.create(
+        defaultErasureCodingConfig()
+      );
+    }
+    return this._provider;
+  }
+  /**
+   * Build orderless transaction options (a random replay-protection nonce) for
+   * the per-blob commit transactions. batchUpload finalizes blobs
+   * concurrently, so without orderless replay protection the parallel
+   * same-account submissions collide on the sequence number ("transaction
+   * already in mempool with a different payload"). The nonce makes each commit
+   * independent regardless of the client's `orderless` config flag.
+   */
+  orderlessCommitOptions() {
+    return {
+      build: {
+        options: {
+          replayProtectionNonce: crypto.getRandomValues(new Uint32Array(1))[0]
+        }
+      }
+    };
+  }
+  /**
+   * Resolve the on-chain UID assigned to `blobName` from a committed register
+   * transaction. `register_blob` only publishes the uid -> name mapping via
+   * `BlobRegisteredEvent` (a pending blob is not yet in the `objects` map, so it
+   * cannot be read back by name), so the upload flow must parse it here before
+   * uploading bytes or committing.
+   */
+  uidFromRegisterTx(tx, account, blobName) {
+    const events = "events" in tx ? tx.events : [];
+    const objectName = createBlobKey({ account, blobName });
+    const match = ShelbyBlobClient.registeredBlobUids(
+      events,
+      this.coordination.deployer
+    ).find((registered) => registered.objectName === objectName);
+    if (match === void 0) {
+      throw new Error(
+        `No BlobRegisteredEvent for '${blobName}' in register transaction ${tx.hash}`
+      );
+    }
+    return match.uid;
+  }
+  /**
+   * Await a blob-registration transaction, rephrasing on-chain location
+   * failures into a human-readable message.
+   */
+  async waitForRegistration(transactionHash) {
+    try {
+      return await this.coordination.aptos.waitForTransaction({
+        transactionHash
+      });
+    } catch (error) {
+      const message = error instanceof Error ? error.message : String(error);
+      const described = describeLocationError(message);
+      throw described ? new Error(described, { cause: error }) : error;
+    }
+  }
+  /**
+   * The base URL for the Shelby RPC node.
+   */
+  get baseUrl() {
+    return getShelbyRPCBaseUrl(this.config);
+  }
+  /**
+   * Uploads a blob to the Shelby network.
+   * This method handles the complete upload flow including commitment generation,
+   * blockchain registration, and storage upload.
+   *
+   * Note: This method accepts only `Uint8Array` and buffers the entire blob in memory.
+   * For streaming uploads of large files (e.g. >2 GiB), orchestrate the steps manually
+   * using `generateCommitments()`, `coordination.registerBlob()`, `rpc.putBlobChunksets()`,
+   * and `coordination.commitObject()` with a `ReadableStream`.
+   *
+   * @param params.blobData - The raw data to upload as a Uint8Array.
+   * @param params.signer - The account that signs and pays for the transaction.
+   * @param params.blobName - The name/path of the blob (e.g. "folder/file.txt").
+   * @param params.expirationMicros - The expiration time in microseconds since Unix epoch.
+   * @param params.options - Optional upload configuration.
+   * @param params.options.chunksetSizeBytes - Custom chunkset size.
+   * @param params.options.build - Additional Aptos transaction options.
+   *
+   * @returns The transaction and generated blob commitments (when implemented).
+   *
+   * @example
+   * ```typescript
+   * await client.upload({
+   *   blobData: Buffer.from("Hello, World!"),
+   *   signer: account,
+   *   blobName: "hello.txt",
+   *   expirationMicros: Date.now() * 1000 + 86400_000_000 // 24 hours from now
+   * });
+   * ```
+   */
+  async upload(params) {
+    const provider = await this.getProvider();
+    const blobCommitments = await generateCommitments(
+      provider,
+      params.blobData
+    );
+    const { transaction: pendingRegisterBlobTransaction } = await this.coordination.registerBlob({
+      account: params.signer,
+      blobName: params.blobName,
+      blobMerkleRoot: blobCommitments.blob_merkle_root,
+      size: params.blobData.length,
+      expirationMicros: params.expirationMicros,
+      config: provider.config,
+      options: params.options
+    });
+    const registerTx = await this.waitForRegistration(
+      pendingRegisterBlobTransaction.hash
+    );
+    const uid = this.uidFromRegisterTx(
+      registerTx,
+      params.signer.accountAddress,
+      params.blobName
+    );
+    const { spAcks } = await this.rpc.putBlobChunksets({
+      account: params.signer,
+      uid,
+      blobData: params.blobData,
+      commitments: blobCommitments,
+      totalBytes: params.blobData.length
+    });
+    const requiredAcks = requiredAckCount(provider.config.erasure_n);
+    if (spAcks.length < requiredAcks) {
+      throw new Error(
+        `Insufficient storage provider acknowledgements for '${params.blobName}': got ${spAcks.length}, need ${requiredAcks} (erasure_d) to finalize on chain`
+      );
+    }
+    const { transaction: pendingCommitTransaction } = await this.coordination.commitObject({
+      account: params.signer,
+      uid,
+      blobName: params.blobName,
+      overwrite: true,
+      storageProviderAcks: spAcks,
+      options: this.orderlessCommitOptions()
+    });
+    const confirmedTx = await this.coordination.aptos.waitForTransaction({
+      transactionHash: pendingCommitTransaction.hash
+    });
+    if (!confirmedTx.success) {
+      throw new Error(
+        `commit_object tx failed for '${params.blobName}': ${confirmedTx.vm_status}`
+      );
+    }
+  }
+  /**
+   * Uploads a batch of blobs to the Shelby network.
+   * This method handles the complete upload flow including commitment generation,
+   * blockchain registration, and storage upload.
+   *
+   * Note: This method accepts only `Uint8Array` and buffers each blob in memory.
+   * For streaming uploads of large files, orchestrate the steps manually using
+   * `generateCommitments()`, `coordination.registerBlob()`, `rpc.putBlobChunksets()`,
+   * and `coordination.commitObject()` with a `ReadableStream`.
+   *
+   * @param params.blobs - The blobs to upload.
+   * @param params.blobs.blobData - The raw data to upload as a Uint8Array.
+   * @param params.blobs.blobName - The name/path of the blob (e.g. "folder/file.txt").
+   * @param params.expirationMicros - The expiration time in microseconds since Unix epoch.
+   * @param params.signer - The account that signs and pays for the transaction.
+   * @param params.options - Optional upload configuration.
+   * @param params.options.chunksetSizeBytes - Custom chunkset size.
+   * @param params.options.build - Additional Aptos transaction options.
+   *
+   * @returns The transaction and generated blob commitments (when implemented).
+   *
+   * @example
+   * ```typescript
+   * await client.batchUpload({
+   *   blobs: [
+   *     { blobData: Buffer.from("Hello, World!"), blobName: "hello.txt" },
+   *     { blobData: Buffer.from("Hello, World 2!"), blobName: "hello2.txt" },
+   *   ],
+   *   expirationMicros: Date.now() * 1000 + 86400_000_000 // 24 hours from now
+   * });
+   * ```
+   */
+  async batchUpload(params) {
+    const provider = await this.getProvider();
+    const prepared = await Promise.all(
+      params.blobs.map(async (blob) => ({
+        blob,
+        commitments: await generateCommitments(provider, blob.blobData)
+      }))
+    );
+    const { transaction: pendingRegisterBlobTransaction } = await this.coordination.batchRegisterBlobs({
+      account: params.signer,
+      expirationMicros: params.expirationMicros,
+      blobs: prepared.map((p) => ({
+        blobName: p.blob.blobName,
+        blobSize: p.blob.blobData.length,
+        blobMerkleRoot: p.commitments.blob_merkle_root
+      })),
+      config: provider.config,
+      options: params.options
+    });
+    const registerTx = await this.waitForRegistration(
+      pendingRegisterBlobTransaction.hash
+    );
+    const uidByObjectName = new Map(
+      ShelbyBlobClient.registeredBlobUids(
+        "events" in registerTx ? registerTx.events : [],
+        this.coordination.deployer
+      ).map((registered) => [registered.objectName, registered.uid])
+    );
+    const requiredAcks = requiredAckCount(provider.config.erasure_n);
+    const limit = pLimit(3);
+    await Promise.all(
+      prepared.map(
+        (p) => limit(async () => {
+          const objectName = createBlobKey({
+            account: params.signer.accountAddress,
+            blobName: p.blob.blobName
+          });
+          const uid = uidByObjectName.get(objectName);
+          if (uid === void 0) {
+            throw new Error(
+              `No BlobRegisteredEvent for '${p.blob.blobName}' in batch register transaction ${registerTx.hash}`
+            );
+          }
+          const { spAcks } = await this.rpc.putBlobChunksets({
+            account: params.signer,
+            uid,
+            blobData: p.blob.blobData,
+            commitments: p.commitments,
+            totalBytes: p.blob.blobData.length
+          });
+          if (spAcks.length < requiredAcks) {
+            throw new Error(
+              `Insufficient storage provider acknowledgements for '${p.blob.blobName}': got ${spAcks.length}, need ${requiredAcks} (erasure_d) to finalize on chain`
+            );
+          }
+          const { transaction: pendingCommitTransaction } = await this.coordination.commitObject({
+            account: params.signer,
+            uid,
+            blobName: p.blob.blobName,
+            overwrite: true,
+            storageProviderAcks: spAcks,
+            options: this.orderlessCommitOptions()
+          });
+          const confirmedTx = await this.coordination.aptos.waitForTransaction({
+            transactionHash: pendingCommitTransaction.hash
+          });
+          if (!confirmedTx.success) {
+            throw new Error(
+              `commit_object tx failed for '${p.blob.blobName}': ${confirmedTx.vm_status}`
+            );
+          }
+        })
+      )
+    );
+  }
+  /**
+   * Downloads a blob from the Shelby RPC node.
+   *
+   * @param params.account - The account namespace the blob is stored in (e.g. "0x1")
+   * @param params.blobName - The name of the blob (e.g. "foo/bar")
+   * @param params.range - The range of the blob to download.
+   *
+   * @returns A `ShelbyBlob` object containing the blob data.
+   *
+   * @example
+   * ```typescript
+   * const blob = await client.download({
+   *   account,
+   *   blobName: "foo/bar.txt",
+   * });
+   * ```
+   */
+  async download(params) {
+    return await this.rpc.getBlob(params);
+  }
+  /**
+   *
+   * Funds an account with ShelbyUSD tokens.
+   *
+   * @param params.address - The address to fund.
+   * @param params.amount - The amount to fund.
+   * @returns The transaction hash of the funded account.
+   *
+   * @example
+   * ```typescript
+   * const hash = await client.fundAccountWithShelbyUSD({
+   *   address: "0x1",
+   *   amount: 100000000,
+   * });
+   * ```
+   */
+  async fundAccountWithShelbyUSD(params) {
+    if (this.config.network === Network3.TESTNET) {
+      throw new Error(
+        `ShelbyUSD cannot be minted programmatically on ${Network3.TESTNET}. Please use the faucet at https://docs.shelby.xyz/apis/faucet/shelbyusd instead.`
+      );
+    }
+    const { address, amount } = params;
+    try {
+      const faucet = this.config.faucet?.baseUrl ?? "https://faucet.shelbynet.shelby.xyz/fund?asset=shelbyusd";
+      const authToken = this.config.faucet?.authToken;
+      const response = await fetch(`${faucet}`, {
+        method: "POST",
+        body: JSON.stringify({
+          address: normalizeAddress(address).toString(),
+          amount
+        }),
+        headers: {
+          "Content-Type": "application/json",
+          ...authToken ? { Authorization: `Bearer ${authToken}` } : {}
+        }
+      });
+      if (!response.ok) {
+        const errorBody = await response.text();
+        throw new Error(`Failed to fund account: ${errorBody}`);
+      }
+      const json = await response.json();
+      const res = await this.aptos.waitForTransaction({
+        transactionHash: json.txn_hashes[0],
+        options: {
+          timeoutSecs: DEFAULT_TXN_TIMEOUT_SEC,
+          checkSuccess: true
+        }
+      });
+      if (res.type === TransactionResponseType.User) {
+        return res.hash;
+      }
+      throw new Error(
+        `Unexpected transaction received for fund account: ${res.type}`
+      );
+    } catch (error) {
+      throw new Error(`Failed to fund account: ${error}`);
+    }
+  }
+  /**
+   * Fund an account with APT tokens
+   *
+   * @param params.address - The address to fund
+   * @param params.amount - The amount to fund
+   * @returns The transaction hash of the funded account
+   *
+   * @example
+   * ```typescript
+   * const hash = await client.fundAccountWithAPT({
+   *   address: "0x1",
+   *   amount: 100000000,
+   * });
+   * ```
+   */
+  async fundAccountWithAPT(params) {
+    const transaction = await this.aptos.fundAccount({
+      accountAddress: params.address,
+      amount: params.amount
+    });
+    return transaction.hash;
+  }
+};
+
+// src/node/clients/ShelbyNodeClient.ts
+var ShelbyNodeClient = class extends ShelbyClient {
+};
 export {
   ShelbyNodeClient
 };