@shelby-protocol/react 0.0.4 → 1.0.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@shelby-protocol/react",
-  "version": "0.0.4",
+  "version": "1.0.0",
   "description": "React library for the Shelby Protocol",
   "private": false,
   "type": "module",
@@ -15,6 +15,11 @@
       "types": "./dist/index.d.ts",
       "import": "./dist/index.js",
       "require": "./dist/index.cjs"
+    },
+    "./core": {
+      "types": "./dist/core/index.d.ts",
+      "import": "./dist/core/index.js",
+      "require": "./dist/core/index.cjs"
     }
   },
   "files": [
@@ -36,7 +41,7 @@
     "react": "^18.0.0 || ^19.0.0",
     "react-dom": "^18.0.0 || ^19.0.0",
     "typescript": ">=5.0.4",
-    "@shelby-protocol/sdk": "0.0.9"
+    "@shelby-protocol/sdk": "0.1.0"
   },
   "peerDependenciesMeta": {
     "@aptos-labs/wallet-adapter-react": {
@@ -44,8 +49,9 @@
     }
   },
   "devDependencies": {
-    "@aptos-labs/ts-sdk": "^5.1.1",
+    "@aptos-labs/ts-sdk": "5.2.1",
     "@aptos-labs/wallet-adapter-react": "^6.0.0 || ^7.0.0",
+    "@tanstack/react-query": "^5.90.16",
     "@testing-library/dom": "^10.4.0",
     "@testing-library/react": "^16.3.0",
     "@types/react": "19.2.1",
@@ -54,9 +60,11 @@
     "@vitest/coverage-v8": "^3.2.4",
     "dotenv": "^16.5.0",
     "happy-dom": "^20.0.10",
+    "react": "19.2.1",
+    "react-dom": "19.2.1",
     "tsup": "^8.4.0",
     "vitest": "^3.1.2",
-    "@shelby-protocol/sdk": "0.0.9"
+    "@shelby-protocol/sdk": "0.1.0"
   },
   "keywords": [
     "aptos",
@@ -75,6 +83,7 @@
     "lint": "biome check .",
     "fmt": "biome check . --write",
     "test": "vitest dev --coverage",
-    "test:once": "vitest run --coverage"
+    "test:once": "echo 'React tests require RPC server - use test:integration instead' && exit 0",
+    "test:integration": "vitest run --coverage"
   }
 }

package/src/components/ShelbyClientProvider.tsx

@@ -0,0 +1,26 @@
+import type { ShelbyClient } from "@shelby-protocol/sdk/browser";
+import { createContext, type PropsWithChildren, useContext } from "react";
+
+export const ShelbyClientContext = createContext<ShelbyClient | null>(null);
+
+export function ShelbyClientProvider({
+  children,
+  client,
+}: PropsWithChildren & { client: ShelbyClient }) {
+  return (
+    <ShelbyClientContext.Provider value={client}>
+      {children}
+    </ShelbyClientContext.Provider>
+  );
+}
+
+export function useShelbyClient(client?: ShelbyClient | null) {
+  const contextClient = useContext(ShelbyClientContext);
+  const resolvedClient = client ?? contextClient;
+  if (!resolvedClient) {
+    throw new Error(
+      "`useShelbyClient` requires a client or `ShelbyClientProvider`",
+    );
+  }
+  return resolvedClient;
+}

package/src/components/index.ts

@@ -0,0 +1 @@
+export * from "./ShelbyClientProvider";

package/src/core/index.ts

@@ -0,0 +1,2 @@
+export * from "./queries";
+export type { UseQueryOptionsWithClient } from "./types";

package/src/core/queries/accountBlobs.ts

@@ -0,0 +1,23 @@
+import type { Network } from "@aptos-labs/ts-sdk";
+import type {
+  BlobMetadata,
+  ShelbyBlobClient,
+} from "@shelby-protocol/sdk/browser";
+import type { UseQueryOptionsWithClient } from "../types";
+
+export type UseAccountBlobsOptions = UseQueryOptionsWithClient<BlobMetadata[]> &
+  Parameters<ShelbyBlobClient["getAccountBlobs"]>[0];
+
+export const getUseAccountBlobsQueryKey = (
+  params: Parameters<ShelbyBlobClient["getAccountBlobs"]>[0] & {
+    network: Network;
+  },
+) => [
+  "account-blobs",
+  params.network,
+  params.account.toString(),
+  params.pagination?.limit,
+  params.pagination?.offset,
+  params.orderBy,
+  params.where,
+];

package/src/core/queries/blobMetadata.ts

@@ -0,0 +1,16 @@
+import type { Network } from "@aptos-labs/ts-sdk";
+import type {
+  BlobMetadata,
+  ShelbyBlobClient,
+} from "@shelby-protocol/sdk/browser";
+import type { UseQueryOptionsWithClient } from "../types";
+
+export type UseBlobMetadataOptions =
+  UseQueryOptionsWithClient<BlobMetadata | null> &
+    Parameters<ShelbyBlobClient["getBlobMetadata"]>[0];
+
+export const getUseBlobMetadataQueryKey = (
+  params: Parameters<ShelbyBlobClient["getBlobMetadata"]>[0] & {
+    network: Network;
+  },
+) => ["blob-metadata", params.network, params.account.toString(), params.name];

package/src/core/queries/index.ts

@@ -0,0 +1,8 @@
+export {
+  getUseAccountBlobsQueryKey,
+  type UseAccountBlobsOptions,
+} from "./accountBlobs";
+export {
+  getUseBlobMetadataQueryKey,
+  type UseBlobMetadataOptions,
+} from "./blobMetadata";

package/src/core/types.ts

@@ -0,0 +1,16 @@
+import type { ShelbyClient } from "@shelby-protocol/sdk/browser";
+import type {
+  DefaultError,
+  QueryKey,
+  UseQueryOptions,
+} from "@tanstack/react-query";
+
+export type UseQueryOptionsWithClient<
+  TQueryFnData = unknown,
+  TError = DefaultError,
+  TData = TQueryFnData,
+  TQueryKey extends QueryKey = QueryKey,
+> = Omit<
+  UseQueryOptions<TQueryFnData, TError, TData, TQueryKey>,
+  "queryFn" | "queryKey"
+> & { client?: ShelbyClient | null };

package/src/index.ts

@@ -1,2 +1,4 @@
+export * from "./components/index";
 export * from "./mutations/index";
 export * from "./queries/index";
+export * from "./types/index";

package/src/mutations/index.ts

@@ -1,4 +1,6 @@
 export * from "./useCommitBlobs";
+export * from "./useDeleteBlob";
+export * from "./useDeleteBlobs";
 export * from "./useEncodeBlobs";
 export * from "./useRegisterCommitments";
 export * from "./useUploadBlobs";

package/src/mutations/useCommitBlobs.tsx

@@ -1,6 +1,7 @@
 import type { AccountAddressInput } from "@aptos-labs/ts-sdk";
 import { useMutation } from "@tanstack/react-query";
 import pLimit from "p-limit";
+import { useShelbyClient } from "../components/ShelbyClientProvider";
 import type { UseMutationOptionsWithClient } from "../types/mutations";
 
 export type UseCommitBlobsVariables = {
@@ -55,10 +56,8 @@ export type UseCommitBlobsOptions = UseMutationOptionsWithClient<
  * });
  * ```
  */
-export function useCommitBlobs({
-  client: shelbyClient,
-  ...options
-}: UseCommitBlobsOptions) {
+export function useCommitBlobs({ client, ...options }: UseCommitBlobsOptions) {
+  const shelbyClient = useShelbyClient(client);
   return useMutation({
     mutationFn: async ({
       account,

package/src/mutations/useDeleteBlob.tsx

@@ -0,0 +1,93 @@
+import type { InputGenerateTransactionOptions } from "@aptos-labs/ts-sdk";
+import { ShelbyBlobClient } from "@shelby-protocol/sdk/browser";
+import { useMutation } from "@tanstack/react-query";
+import { useShelbyClient } from "../components/ShelbyClientProvider";
+import type { UseMutationOptionsWithClient } from "../types/mutations";
+import type { AccountSigner, Signer } from "../types/signers";
+
+export type UseDeleteBlobVariables = {
+  /**
+   * The signer to use for the transaction.
+   *
+   * @see {@link Signer}
+   *
+   * @example
+   * ```tsx
+   * const signer = new Account.generate();
+   * deleteBlob.mutate({
+   *   signer,
+   *   blobName: "folder/file.txt",
+   * });
+   * ```
+   */
+  signer: Signer;
+  /**
+   * The name/path of the blob (e.g. "folder/file.txt").
+   */
+  blobName: string;
+  /**
+   * Optional transaction building options.
+   */
+  options?: InputGenerateTransactionOptions;
+};
+
+export type UseDeleteBlobOptions = UseMutationOptionsWithClient<
+  { hash: string },
+  Error,
+  UseDeleteBlobVariables
+>;
+
+/**
+ * Deletes a blob on-chain.
+ *
+ * @deprecated Use {@link useDeleteBlobs} instead, which supports both single
+ * and multiple blob deletion with automatic gas optimization.
+ *
+ * This mutation deletes blob metadata from the Shelby contract. It supports
+ * both account signers and wallet adapter signers.
+ *
+ * @example
+ * ```tsx
+ * import { ShelbyClient } from "@shelby-protocol/sdk/browser";
+ * import { Network } from "@aptos-labs/ts-sdk";
+ * import { useDeleteBlobs } from "@shelby-protocol/react";
+ *
+ * const shelbyClient = new ShelbyClient({ network: Network.SHELBYNET });
+ * const deleteBlobs = useDeleteBlobs({
+ *   client: shelbyClient,
+ *   onSuccess: ({ hash }) => console.log("Delete tx:", hash),
+ * });
+ *
+ * deleteBlobs.mutate({
+ *   signer,
+ *   blobNames: ["folder/file.txt"],
+ * });
+ * ```
+ */
+export function useDeleteBlob({ client, ...options }: UseDeleteBlobOptions) {
+  const shelbyClient = useShelbyClient(client);
+  return useMutation({
+    mutationFn: async ({ blobName, signer: signerOrFn, options }) => {
+      if (!("signAndSubmitTransaction" in signerOrFn)) {
+        const accountSigner: AccountSigner = signerOrFn;
+
+        const { transaction } = await shelbyClient.coordination.deleteBlob({
+          account: accountSigner,
+          blobName,
+          options,
+        });
+
+        return transaction;
+      }
+
+      const { signAndSubmitTransaction } = signerOrFn;
+      const transaction = await signAndSubmitTransaction({
+        data: ShelbyBlobClient.createDeleteBlobPayload({ blobName }),
+        options,
+      });
+
+      return transaction;
+    },
+    ...options,
+  });
+}

package/src/mutations/useDeleteBlobs.tsx

@@ -0,0 +1,139 @@
+import type { InputGenerateTransactionOptions } from "@aptos-labs/ts-sdk";
+import { ShelbyBlobClient } from "@shelby-protocol/sdk/browser";
+import { useMutation } from "@tanstack/react-query";
+import { useShelbyClient } from "../components/ShelbyClientProvider";
+import type { UseMutationOptionsWithClient } from "../types/mutations";
+import type { AccountSigner, Signer } from "../types/signers";
+
+export type UseDeleteBlobsVariables = {
+  /**
+   * The signer to use for the transaction.
+   *
+   * @see {@link Signer}
+   *
+   * @example
+   * ```tsx
+   * const signer = new Account.generate();
+   * deleteBlobs.mutate({
+   *   signer,
+   *   blobNames: ["folder/file1.txt", "folder/file2.txt"],
+   * });
+   * ```
+   */
+  signer: Signer;
+  /**
+   * The names/paths of the blobs to delete, without the account address prefix
+   * (e.g. ["folder/file1.txt", "folder/file2.txt"], NOT ["0x1/folder/file1.txt"]).
+   * The account address prefix is automatically derived from the signer.
+   */
+  blobNames: string[];
+  /**
+   * Optional transaction building options.
+   */
+  options?: InputGenerateTransactionOptions;
+};
+
+export type UseDeleteBlobsOptions = UseMutationOptionsWithClient<
+  { hash: string },
+  Error,
+  UseDeleteBlobsVariables
+>;
+
+/**
+ * Deletes one or more blobs on-chain.
+ *
+ * This hook automatically optimizes gas costs by using `delete_blob` for single
+ * blob deletion and `delete_multiple_blobs` for multiple blobs.
+ *
+ * **Note:** Deleting multiple blobs (more than one) requires the `delete_multiple_blobs`
+ * entry function which will be deployed to the smart contract on 2026-02-04.
+ * Using this hook with multiple blobs before that date will result in a transaction failure.
+ * Single blob deletion works immediately.
+ *
+ * This mutation deletes blob metadata from the Shelby contract. It supports
+ * both account signers and wallet adapter signers.
+ *
+ * When deleting multiple blobs, the operation is atomic: if any blob deletion
+ * fails (e.g., blob not found), the entire transaction fails and no blobs are deleted.
+ *
+ * @example
+ * ```tsx
+ * import { ShelbyClient } from "@shelby-protocol/sdk/browser";
+ * import { Network } from "@aptos-labs/ts-sdk";
+ * import { useDeleteBlobs } from "@shelby-protocol/react";
+ *
+ * const shelbyClient = new ShelbyClient({ network: Network.SHELBYNET });
+ * const deleteBlobs = useDeleteBlobs({
+ *   client: shelbyClient,
+ *   onSuccess: ({ hash }) => console.log("Delete tx:", hash),
+ * });
+ *
+ * // Delete a single blob
+ * deleteBlobs.mutate({
+ *   signer,
+ *   blobNames: ["folder/file.txt"],
+ * });
+ *
+ * // Delete multiple blobs in one transaction
+ * deleteBlobs.mutate({
+ *   signer,
+ *   blobNames: ["folder/file1.txt", "folder/file2.txt"],
+ * });
+ * ```
+ */
+export function useDeleteBlobs({ client, ...options }: UseDeleteBlobsOptions) {
+  const shelbyClient = useShelbyClient(client);
+  return useMutation({
+    mutationFn: async ({ blobNames, signer: signerOrFn, options }) => {
+      if (blobNames.length === 0) {
+        throw new Error("blobNames must contain at least one blob name");
+      }
+
+      const isSingleBlob = blobNames.length === 1;
+
+      if (!("signAndSubmitTransaction" in signerOrFn)) {
+        const accountSigner: AccountSigner = signerOrFn;
+
+        // Use single delete for gas optimization
+        if (isSingleBlob) {
+          const { transaction } = await shelbyClient.coordination.deleteBlob({
+            account: accountSigner,
+            blobName: blobNames[0],
+            options,
+          });
+          return transaction;
+        }
+
+        // Use batch delete for multiple blobs
+        const { transaction } =
+          await shelbyClient.coordination.deleteMultipleBlobs({
+            account: accountSigner,
+            blobNames,
+            options,
+          });
+        return transaction;
+      }
+
+      const { signAndSubmitTransaction } = signerOrFn;
+
+      if (isSingleBlob) {
+        // Use single delete for gas optimization
+        const transaction = await signAndSubmitTransaction({
+          data: ShelbyBlobClient.createDeleteBlobPayload({
+            blobName: blobNames[0],
+          }),
+          options,
+        });
+        return transaction;
+      }
+
+      // Use batch delete for multiple blobs
+      const transaction = await signAndSubmitTransaction({
+        data: ShelbyBlobClient.createDeleteMultipleBlobsPayload({ blobNames }),
+        options,
+      });
+      return transaction;
+    },
+    ...options,
+  });
+}

package/src/mutations/useEncodeBlobs.tsx

@@ -5,7 +5,7 @@ import {
   generateCommitments,
 } from "@shelby-protocol/sdk/browser";
 import { useMutation } from "@tanstack/react-query";
-import type { UseMutationOptionsWithClient } from "../types/mutations";
+import type { UseMutationOptions } from "../types/mutations";
 
 export type UseEncodeBlobsOnChunkEvent = {
   /**
@@ -25,7 +25,14 @@ export type UseEncodeBlobsOnChunkEvent = {
    */
   chunkData: Uint8Array;
   /**
-   * The progress of the encoding.
+   * The progress of the encoding in percentage.
+   *
+   * @example
+   * ```tsx
+   * onChunk: ({ progress }) => {
+   *   console.log(`Encoding progress: ${progress * 100}%`);
+   * },
+   * ```
    */
   progress: number;
 };
@@ -45,7 +52,7 @@ export type UseEncodeBlobsVariables = {
   onChunk?: (event: UseEncodeBlobsOnChunkEvent) => void;
 };
 
-export type UseEncodeBlobsOptions = UseMutationOptionsWithClient<
+export type UseEncodeBlobsOptions = UseMutationOptions<
   BlobCommitments[],
   Error,
   UseEncodeBlobsVariables
@@ -60,13 +67,9 @@ export type UseEncodeBlobsOptions = UseMutationOptionsWithClient<
  *
  * @example
  * ```tsx
- * import { ShelbyClient } from "@shelby-protocol/sdk/browser";
- * import { Network } from "@aptos-labs/ts-sdk";
  * import { useEncodeBlobs } from "@shelby-protocol/react";
  *
- * const shelbyClient = new ShelbyClient({ network: Network.SHELBYNET });
  * const encodeBlobs = useEncodeBlobs({
- *   client: shelbyClient,
  *   onSuccess: (commitments) => console.log('Encoded', commitments.length, 'blobs'),
  * });
  *
@@ -78,10 +81,7 @@ export type UseEncodeBlobsOptions = UseMutationOptionsWithClient<
  * });
  * ```
  */
-export function useEncodeBlobs({
-  client: shelbyClient,
-  ...options
-}: UseEncodeBlobsOptions) {
+export function useEncodeBlobs({ ...options }: UseEncodeBlobsOptions = {}) {
   return useMutation({
     mutationFn: async ({ blobs, provider, onChunk }) => {
       const activeProvider =

package/src/mutations/useRegisterCommitments.tsx

@@ -7,6 +7,7 @@ import {
   type UploadOptions,
 } from "@shelby-protocol/sdk/browser";
 import { useMutation } from "@tanstack/react-query";
+import { useShelbyClient } from "../components/ShelbyClientProvider";
 import type { UseMutationOptionsWithClient } from "../types/mutations";
 import type { AccountSigner, Signer } from "../types/signers";
 
@@ -76,9 +77,10 @@ export type UseRegisterCommitmentsOptions = UseMutationOptionsWithClient<
  * ```
  */
 export function useRegisterCommitments({
-  client: shelbyClient,
+  client,
   ...options
 }: UseRegisterCommitmentsOptions) {
+  const shelbyClient = useShelbyClient(client);
   return useMutation({
     mutationFn: async ({
       commitments,
@@ -86,7 +88,7 @@ export function useRegisterCommitments({
       options,
       signer: signerOrFn,
     }) => {
-      if (!("account" in signerOrFn)) {
+      if (!("signAndSubmitTransaction" in signerOrFn)) {
         const accountSigner: AccountSigner = signerOrFn;
 
         const { transaction } =
@@ -105,9 +107,21 @@ export function useRegisterCommitments({
       }
 
       const { account, signAndSubmitTransaction } = signerOrFn;
+
+      if (!account) {
+        throw new Error(
+          "'account' is required if using a wallet adapter signer with 'useRegisterCommitments'",
+        );
+      }
+
+      const accountAddress =
+        typeof account === "object" && "address" in account
+          ? account.address
+          : account;
+
       const transaction = await signAndSubmitTransaction({
         data: ShelbyBlobClient.createBatchRegisterBlobsPayload({
-          account: AccountAddress.from(account),
+          account: AccountAddress.from(accountAddress),
           expirationMicros,
           blobs: commitments.map((commitment) => ({
             blobName: commitment.blobName,

package/src/mutations/useUploadBlobs.tsx

@@ -10,6 +10,7 @@ import {
 } from "@shelby-protocol/sdk/browser";
 import { useMutation } from "@tanstack/react-query";
 import pLimit from "p-limit";
+import { useShelbyClient } from "../components/ShelbyClientProvider";
 import type { UseMutationOptionsWithClient } from "../types/mutations";
 import type { AccountSigner, Signer } from "../types/signers";
 
@@ -93,10 +94,8 @@ export type UseUploadBlobsOptions = UseMutationOptionsWithClient<
  * });
  * ```
  */
-export function useUploadBlobs({
-  client: shelbyClient,
-  ...options
-}: UseUploadBlobsOptions) {
+export function useUploadBlobs({ client, ...options }: UseUploadBlobsOptions) {
+  const shelbyClient = useShelbyClient(client);
   return useMutation({
     mutationFn: async ({
       blobs,
@@ -105,7 +104,7 @@ export function useUploadBlobs({
       signer: signerOrFn,
       maxConcurrentUploads = 3,
     }: UseUploadBlobsVariables) => {
-      if (!("account" in signerOrFn)) {
+      if (!("signAndSubmitTransaction" in signerOrFn)) {
         const accountSigner: AccountSigner = signerOrFn;
 
         await shelbyClient.batchUpload({
@@ -120,6 +119,17 @@ export function useUploadBlobs({
       } else {
         const { account, signAndSubmitTransaction } = signerOrFn;
 
+        if (!account) {
+          throw new Error(
+            "'account' is required if using a wallet adapter signer with 'useUploadBlobs'",
+          );
+        }
+
+        const accountAddress =
+          typeof account === "object" && "address" in account
+            ? account.address
+            : account;
+
         const chunksetSize =
           options?.chunksetSizeBytes ?? DEFAULT_CHUNKSET_SIZE_BYTES;
 
@@ -127,7 +137,10 @@ export function useUploadBlobs({
           where: {
             blob_name: {
               _in: blobs.map((blob) =>
-                createBlobKey({ account, blobName: blob.blobName }),
+                createBlobKey({
+                  account: accountAddress,
+                  blobName: blob.blobName,
+                }),
               ),
             },
           },
@@ -138,7 +151,10 @@ export function useUploadBlobs({
             !existingBlobs.some(
               (existingBlob) =>
                 existingBlob.name ===
-                createBlobKey({ account, blobName: blob.blobName }),
+                createBlobKey({
+                  account: accountAddress,
+                  blobName: blob.blobName,
+                }),
             ),
         );
 
@@ -154,7 +170,7 @@ export function useUploadBlobs({
           const pendingRegisterBlobTransaction = await signAndSubmitTransaction(
             {
               data: ShelbyBlobClient.createBatchRegisterBlobsPayload({
-                account: AccountAddress.from(account),
+                account: AccountAddress.from(accountAddress),
                 expirationMicros,
                 blobs: blobsToRegister.map((blob, index) => ({
                   blobName: blob.blobName,
@@ -179,7 +195,7 @@ export function useUploadBlobs({
         const uploadPromises = blobs.map((blob) =>
           limit(() =>
             shelbyClient.rpc.putBlob({
-              account,
+              account: accountAddress,
               blobName: blob.blobName,
               blobData: blob.blobData,
             }),

package/src/queries/useAccountBlobs.tsx

@@ -1,27 +1,15 @@
-import type { Network } from "@aptos-labs/ts-sdk";
-import type {
-  BlobMetadata,
-  ShelbyBlobClient,
-} from "@shelby-protocol/sdk/browser";
+import type { BlobMetadata } from "@shelby-protocol/sdk/browser";
 import { useQuery } from "@tanstack/react-query";
-import type { UseQueryOptionsWithClient } from "../types/queries";
+import { useShelbyClient } from "../components/ShelbyClientProvider";
+import {
+  getUseAccountBlobsQueryKey,
+  type UseAccountBlobsOptions,
+} from "../core/queries/accountBlobs";
 
-export const getUseAccountBlobsQueryKey = (
-  params: Parameters<ShelbyBlobClient["getAccountBlobs"]>[0] & {
-    network: Network;
-  },
-) => [
-  "account-blobs",
-  params.network,
-  params.account.toString(),
-  params.pagination?.limit,
-  params.pagination?.offset,
-  params.orderBy,
-  params.where,
-];
-
-export type UseAccountBlobsOptions = UseQueryOptionsWithClient<BlobMetadata[]> &
-  Parameters<ShelbyBlobClient["getAccountBlobs"]>[0];
+export {
+  getUseAccountBlobsQueryKey,
+  type UseAccountBlobsOptions,
+} from "../core/queries/accountBlobs";
 
 /**
  * Queries blobs associated with an account.
@@ -49,9 +37,10 @@ export function useAccountBlobs({
   pagination,
   orderBy,
   where,
-  client: shelbyClient,
+  client,
   ...options
 }: UseAccountBlobsOptions) {
+  const shelbyClient = useShelbyClient(client);
   return useQuery<BlobMetadata[]>({
     queryKey: getUseAccountBlobsQueryKey({
       network: shelbyClient.config.network,