@shelby-protocol/react 0.0.2

package/dist/queries/useBlobMetadata.d.ts

@@ -0,0 +1,29 @@
+import type { Network } from "@aptos-labs/ts-sdk";
+import type { BlobMetadata, ShelbyBlobClient } from "@shelby-protocol/sdk/browser";
+import type { UseQueryOptionsWithClient } from "../types/queries";
+export declare const getUseBlobMetadataQueryKey: (params: Parameters<ShelbyBlobClient["getBlobMetadata"]>[0] & {
+    network: Network;
+}) => string[];
+export type UseBlobMetadataOptions = UseQueryOptionsWithClient<BlobMetadata | null> & Parameters<ShelbyBlobClient["getBlobMetadata"]>[0];
+/**
+ * Queries the metadata for a specific blob.
+ *
+ * This query fetches the metadata for a single blob identified by account and blob name.
+ * Returns `null` if the blob is not found.
+ *
+ * @example
+ * ```tsx
+ * import { ShelbyClient } from "@shelby-protocol/sdk/browser";
+ * import { Network } from "@aptos-labs/ts-sdk";
+ * import { useBlobMetadata } from "@shelby-protocol/react";
+ *
+ * const shelbyClient = new ShelbyClient({ network: Network.SHELBYNET });
+ * const { data: metadata } = useBlobMetadata({
+ *   client: shelbyClient,
+ *   account: '0x123...',
+ *   name: 'file1.txt',
+ * });
+ * ```
+ */
+export declare function useBlobMetadata({ account, name, client: shelbyClient, ...options }: UseBlobMetadataOptions): import("@tanstack/react-query").UseQueryResult<BlobMetadata | null, Error>;
+//# sourceMappingURL=useBlobMetadata.d.ts.map

package/dist/queries/useBlobMetadata.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"useBlobMetadata.d.ts","sourceRoot":"","sources":["../../src/queries/useBlobMetadata.tsx"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,oBAAoB,CAAC;AAClD,OAAO,KAAK,EACV,YAAY,EACZ,gBAAgB,EACjB,MAAM,8BAA8B,CAAC;AAEtC,OAAO,KAAK,EAAE,yBAAyB,EAAE,MAAM,kBAAkB,CAAC;AAElE,eAAO,MAAM,0BAA0B,GACrC,QAAQ,UAAU,CAAC,gBAAgB,CAAC,iBAAiB,CAAC,CAAC,CAAC,CAAC,CAAC,GAAG;IAC3D,OAAO,EAAE,OAAO,CAAC;CAClB,aAC2E,CAAC;AAE/E,MAAM,MAAM,sBAAsB,GAChC,yBAAyB,CAAC,YAAY,GAAG,IAAI,CAAC,GAC5C,UAAU,CAAC,gBAAgB,CAAC,iBAAiB,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC;AAEvD;;;;;;;;;;;;;;;;;;;GAmBG;AACH,wBAAgB,eAAe,CAAC,EAC9B,OAAO,EACP,IAAI,EACJ,MAAM,EAAE,YAAY,EACpB,GAAG,OAAO,EACX,EAAE,sBAAsB,8EAYxB"}

package/dist/types/mutations.d.ts

@@ -0,0 +1,6 @@
+import type { ShelbyClient } from "@shelby-protocol/sdk/browser";
+import type { DefaultError, MutationKey, UseMutationOptions } from "@tanstack/react-query";
+export type UseMutationOptionsWithClient<TMutationFnData = unknown, TError = DefaultError, TData = TMutationFnData, TMutationKey extends MutationKey = MutationKey> = Omit<UseMutationOptions<TMutationFnData, TError, TData, TMutationKey>, "mutationFn"> & {
+    client: ShelbyClient;
+};
+//# sourceMappingURL=mutations.d.ts.map

package/dist/types/mutations.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"mutations.d.ts","sourceRoot":"","sources":["../../src/types/mutations.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,8BAA8B,CAAC;AACjE,OAAO,KAAK,EACV,YAAY,EACZ,WAAW,EACX,kBAAkB,EACnB,MAAM,uBAAuB,CAAC;AAE/B,MAAM,MAAM,4BAA4B,CACtC,eAAe,GAAG,OAAO,EACzB,MAAM,GAAG,YAAY,EACrB,KAAK,GAAG,eAAe,EACvB,YAAY,SAAS,WAAW,GAAG,WAAW,IAC5C,IAAI,CACN,kBAAkB,CAAC,eAAe,EAAE,MAAM,EAAE,KAAK,EAAE,YAAY,CAAC,EAChE,YAAY,CACb,GAAG;IAAE,MAAM,EAAE,YAAY,CAAA;CAAE,CAAC"}

package/dist/types/queries.d.ts

@@ -0,0 +1,6 @@
+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;
+};
+//# sourceMappingURL=queries.d.ts.map

package/dist/types/queries.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"queries.d.ts","sourceRoot":"","sources":["../../src/types/queries.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,8BAA8B,CAAC;AACjE,OAAO,KAAK,EACV,YAAY,EACZ,QAAQ,EACR,eAAe,EAChB,MAAM,uBAAuB,CAAC;AAE/B,MAAM,MAAM,yBAAyB,CACnC,YAAY,GAAG,OAAO,EACtB,MAAM,GAAG,YAAY,EACrB,KAAK,GAAG,YAAY,EACpB,SAAS,SAAS,QAAQ,GAAG,QAAQ,IACnC,IAAI,CACN,eAAe,CAAC,YAAY,EAAE,MAAM,EAAE,KAAK,EAAE,SAAS,CAAC,EACvD,SAAS,GAAG,UAAU,CACvB,GAAG;IAAE,MAAM,EAAE,YAAY,CAAA;CAAE,CAAC"}

package/dist/types/signers.d.ts

@@ -0,0 +1,9 @@
+import type { Account, AccountAddressInput } from "@aptos-labs/ts-sdk";
+import type { SignAndSubmitTransactionFn } from "./walletAdapter";
+export type AccountSigner = Account;
+export type WalletAdapterSigner = {
+    account: AccountAddressInput;
+    signAndSubmitTransaction: SignAndSubmitTransactionFn;
+};
+export type Signer = AccountSigner | WalletAdapterSigner;
+//# sourceMappingURL=signers.d.ts.map

package/dist/types/signers.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"signers.d.ts","sourceRoot":"","sources":["../../src/types/signers.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,OAAO,EAAE,mBAAmB,EAAE,MAAM,oBAAoB,CAAC;AACvE,OAAO,KAAK,EAAE,0BAA0B,EAAE,MAAM,iBAAiB,CAAC;AAElE,MAAM,MAAM,aAAa,GAAG,OAAO,CAAC;AAEpC,MAAM,MAAM,mBAAmB,GAAG;IAChC,OAAO,EAAE,mBAAmB,CAAC;IAC7B,wBAAwB,EAAE,0BAA0B,CAAC;CACtD,CAAC;AAEF,MAAM,MAAM,MAAM,GAAG,aAAa,GAAG,mBAAmB,CAAC"}

package/dist/types/walletAdapter.d.ts

@@ -0,0 +1,3 @@
+import type { WalletContextState } from "@aptos-labs/wallet-adapter-react";
+export type SignAndSubmitTransactionFn = WalletContextState["signAndSubmitTransaction"];
+//# sourceMappingURL=walletAdapter.d.ts.map

package/dist/types/walletAdapter.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"walletAdapter.d.ts","sourceRoot":"","sources":["../../src/types/walletAdapter.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,kCAAkC,CAAC;AAE3E,MAAM,MAAM,0BAA0B,GACpC,kBAAkB,CAAC,0BAA0B,CAAC,CAAC"}

package/package.json

@@ -0,0 +1,80 @@
+{
+  "name": "@shelby-protocol/react",
+  "version": "0.0.2",
+  "description": "React library for the Shelby Protocol",
+  "private": false,
+  "type": "module",
+  "main": "./dist/index.js",
+  "module": "./dist/index.mjs",
+  "types": "./dist/index.d.ts",
+  "publishConfig": {
+    "access": "public"
+  },
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js",
+      "require": "./dist/index.cjs"
+    }
+  },
+  "files": [
+    "dist",
+    "src",
+    "!tests",
+    "!src/**/*.test.ts",
+    "!src/**/*.test.tsx",
+    "README.md",
+    "CHANGELOG.md"
+  ],
+  "dependencies": {
+    "p-limit": "^7.2.0"
+  },
+  "peerDependencies": {
+    "@aptos-labs/ts-sdk": ">=5.0.0",
+    "@aptos-labs/wallet-adapter-react": "^6.0.0 || ^7.0.0",
+    "@tanstack/react-query": ">=5.0.0",
+    "react": "^18.0.0 || ^19.0.0",
+    "react-dom": "^18.0.0 || ^19.0.0",
+    "typescript": ">=5.0.4",
+    "@shelby-protocol/sdk": "0.0.7"
+  },
+  "peerDependenciesMeta": {
+    "@aptos-labs/wallet-adapter-react": {
+      "optional": true
+    }
+  },
+  "devDependencies": {
+    "@aptos-labs/ts-sdk": "^5.1.1",
+    "@aptos-labs/wallet-adapter-react": "^6.0.0 || ^7.0.0",
+    "@testing-library/dom": "^10.4.0",
+    "@testing-library/react": "^16.3.0",
+    "@types/react": "^19.2.0",
+    "@types/react-dom": "^19.2.0",
+    "@vitest/browser": "^3.1.2",
+    "@vitest/coverage-v8": "^3.2.4",
+    "dotenv": "^16.5.0",
+    "happy-dom": "^20.0.10",
+    "tsup": "^8.4.0",
+    "vitest": "^3.1.2",
+    "@shelby-protocol/sdk": "0.0.7"
+  },
+  "keywords": [
+    "aptos",
+    "apt",
+    "web3",
+    "blockchain",
+    "dapps",
+    "wallet",
+    "shelby"
+  ],
+  "scripts": {
+    "build": "tsup",
+    "build:types": "tsc --project tsconfig.build.json",
+    "check:types": "tsc --noEmit",
+    "dev": "tsup --watch",
+    "lint": "biome check .",
+    "fmt": "biome check . --write",
+    "test": "vitest dev --coverage",
+    "test:once": "vitest run --coverage"
+  }
+}

package/src/index.ts

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

package/src/mutations/index.ts

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

package/src/mutations/useCommitBlobs.tsx

@@ -0,0 +1,83 @@
+import type { AccountAddressInput } from "@aptos-labs/ts-sdk";
+import { useMutation } from "@tanstack/react-query";
+import pLimit from "p-limit";
+import type { UseMutationOptionsWithClient } from "../types/mutations";
+
+export type UseCommitBlobsVariables = {
+  /**
+   * The account to commit the blobs to.
+   */
+  account: AccountAddressInput;
+  /**
+   * The blobs to commit.
+   */
+  blobs: {
+    blobName: string;
+    blobData: Uint8Array;
+  }[];
+  /**
+   * The maximum number of concurrent uploads.
+   * @default 3
+   */
+  maxConcurrentUploads?: number;
+};
+
+export type UseCommitBlobsOptions = UseMutationOptionsWithClient<
+  void,
+  Error,
+  UseCommitBlobsVariables
+>;
+
+/**
+ * Uploads blobs data to the Shelby RPCs.
+ *
+ * This mutation uploads multiple blobs data to the RPC endpoint with configurable
+ * concurrency control.
+ *
+ * @example
+ * ```tsx
+ * import { ShelbyClient } from "@shelby-protocol/sdk/browser";
+ * import { Network } from "@aptos-labs/ts-sdk";
+ * import { useCommitBlobs } from "@shelby-protocol/react";
+ *
+ * const shelbyClient = new ShelbyClient({ network: Network.SHELBYNET });
+ * const commitBlobs = useCommitBlobs({
+ *   client: shelbyClient,
+ *   onSuccess: () => console.log('Blobs committed successfully'),
+ * });
+ *
+ * commitBlobs.mutate({
+ *   account: '0x123...',
+ *   blobs: [
+ *     { blobName: 'file1.txt', blobData: new Uint8Array([...]) },
+ *     { blobName: 'file2.txt', blobData: new Uint8Array([...]) },
+ *   ],
+ * });
+ * ```
+ */
+export function useCommitBlobs({
+  client: shelbyClient,
+  ...options
+}: UseCommitBlobsOptions) {
+  return useMutation({
+    mutationFn: async ({
+      account,
+      blobs,
+      maxConcurrentUploads = 3,
+    }: UseCommitBlobsVariables) => {
+      const limit = pLimit(maxConcurrentUploads);
+      const uploadPromises = blobs.map((blob) =>
+        limit(() =>
+          shelbyClient.rpc.putBlob({
+            account,
+            blobName: blob.blobName,
+            blobData: blob.blobData,
+          }),
+        ),
+      );
+
+      await Promise.all(uploadPromises);
+    },
+    ...options,
+  });
+}

package/src/mutations/useEncodeBlobs.tsx

@@ -0,0 +1,122 @@
+import {
+  type BlobCommitments,
+  createDefaultErasureCodingProvider,
+  type ErasureCodingProvider,
+  generateCommitments,
+} from "@shelby-protocol/sdk/browser";
+import { useMutation } from "@tanstack/react-query";
+import type { UseMutationOptionsWithClient } from "../types/mutations";
+
+export type UseEncodeBlobsOnChunkEvent = {
+  /**
+   * The index of the blob being encoded.
+   */
+  blobIndex: number;
+  /**
+   * The index of the chunkset being encoded.
+   */
+  chunksetIndex: number;
+  /**
+   * The index of the chunk being encoded.
+   */
+  chunkIndex: number;
+  /**
+   * The data of the chunk being encoded.
+   */
+  chunkData: Uint8Array;
+  /**
+   * The progress of the encoding.
+   */
+  progress: number;
+};
+
+export type UseEncodeBlobsVariables = {
+  /**
+   * The blobs to encode.
+   */
+  blobs: { blobData: Uint8Array }[];
+  /**
+   * The erasure coding provider to use.
+   */
+  provider?: ErasureCodingProvider;
+  /**
+   * The callback to call when a chunk is encoded.
+   */
+  onChunk?: (event: UseEncodeBlobsOnChunkEvent) => void;
+};
+
+export type UseEncodeBlobsOptions = UseMutationOptionsWithClient<
+  BlobCommitments[],
+  Error,
+  UseEncodeBlobsVariables
+>;
+
+/**
+ * Encodes blobs using erasure coding.
+ *
+ * This mutation generates blob commitments (merkle roots and erasure coding chunks)
+ * from raw blob data. It supports custom erasure coding providers and progress callbacks
+ * for tracking encoding progress.
+ *
+ * @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'),
+ * });
+ *
+ * encodeBlobs.mutate({
+ *   blobs: [{ blobData: new Uint8Array([...]) }],
+ *   onChunk: ({ blobIndex, progress }) => {
+ *     console.log(`Blob ${blobIndex}: ${(progress * 100).toFixed(1)}%`);
+ *   },
+ * });
+ * ```
+ */
+export function useEncodeBlobs({
+  client: shelbyClient,
+  ...options
+}: UseEncodeBlobsOptions) {
+  return useMutation({
+    mutationFn: async ({ blobs, provider, onChunk }) => {
+      const activeProvider =
+        provider ?? (await createDefaultErasureCodingProvider());
+
+      const results: BlobCommitments[] = new Array(blobs.length);
+      await Promise.all(
+        blobs.map(async ({ blobData }, blobIndex) => {
+          const chunksetCount = Math.ceil(
+            blobData.length / activeProvider.config.chunkSizeBytes,
+          );
+
+          const blobCommitments = await generateCommitments(
+            activeProvider,
+            blobData,
+            (
+              chunksetIndex: number,
+              chunkIndex: number,
+              chunkData: Uint8Array,
+            ) =>
+              onChunk?.({
+                blobIndex,
+                chunksetIndex,
+                chunkIndex,
+                chunkData,
+                progress: chunksetIndex / chunksetCount,
+              }),
+          );
+
+          results[blobIndex] = blobCommitments;
+        }),
+      );
+
+      return results;
+    },
+    ...options,
+  });
+}

package/src/mutations/useRegisterCommitments.tsx

@@ -0,0 +1,129 @@
+import { AccountAddress } from "@aptos-labs/ts-sdk";
+import {
+  type BlobCommitments,
+  DEFAULT_CHUNKSET_SIZE_BYTES,
+  expectedTotalChunksets,
+  ShelbyBlobClient,
+  type UploadOptions,
+} from "@shelby-protocol/sdk/browser";
+import { useMutation } from "@tanstack/react-query";
+import type { UseMutationOptionsWithClient } from "../types/mutations";
+import type { AccountSigner, Signer } from "../types/signers";
+
+export type UseRegisterCommitmentsVariables = {
+  /**
+   * The signer to use for the transaction.
+   * @see {@link Signer}
+   *
+   * @example
+   * ```tsx
+   * const signer = new Account.generate();
+   * registerCommitments.mutate({
+   *   signer,
+   *   commitments: [
+   *     { blobName: 'file1.txt', commitment: blobCommitments[0] },
+   *   ],
+   * });
+   * ```
+   */
+  signer: Signer;
+  /**
+   * The commitments to register.
+   */
+  commitments: { blobName: string; commitment: BlobCommitments }[];
+  /**
+   * The expiration time of the commitments in microseconds.
+   */
+  expirationMicros: number;
+  /**
+   * Optional transaction building options.
+   */
+  options?: UploadOptions;
+};
+
+export type UseRegisterCommitmentsOptions = UseMutationOptionsWithClient<
+  { hash: string },
+  Error,
+  UseRegisterCommitmentsVariables
+>;
+
+/**
+ * Registers blob commitments on-chain.
+ *
+ * This mutation registers blob commitments (merkle roots) on the Aptos blockchain
+ * as part of the blob upload process. It supports both account signers and wallet adapter
+ * signers, and handles batch registration of multiple blobs.
+ *
+ * @example
+ * ```tsx
+ * import { ShelbyClient } from "@shelby-protocol/sdk/browser";
+ * import { Network } from "@aptos-labs/ts-sdk";
+ * import { useRegisterCommitments } from "@shelby-protocol/react";
+ *
+ * const shelbyClient = new ShelbyClient({ network: Network.SHELBYNET });
+ * const registerCommitments = useRegisterCommitments({
+ *   client: shelbyClient,
+ *   onSuccess: ({ hash }) => console.log('Transaction hash:', hash),
+ * });
+ *
+ * registerCommitments.mutate({
+ *   signer: accountSigner,
+ *   commitments: [
+ *     { blobName: 'file1.txt', commitment: blobCommitments[0] },
+ *   ],
+ *   expirationMicros: Date.now() * 1000 + 86400000000, // 1 day
+ * });
+ * ```
+ */
+export function useRegisterCommitments({
+  client: shelbyClient,
+  ...options
+}: UseRegisterCommitmentsOptions) {
+  return useMutation({
+    mutationFn: async ({
+      commitments,
+      expirationMicros,
+      options,
+      signer: signerOrFn,
+    }) => {
+      if (!("account" in signerOrFn)) {
+        const accountSigner: AccountSigner = signerOrFn;
+
+        const { transaction } =
+          await shelbyClient.coordination.batchRegisterBlobs({
+            account: accountSigner,
+            expirationMicros,
+            options,
+            blobs: commitments.map((commitment) => ({
+              blobName: commitment.blobName,
+              blobSize: commitment.commitment.raw_data_size,
+              blobMerkleRoot: commitment.commitment.blob_merkle_root,
+            })),
+          });
+
+        return transaction;
+      }
+
+      const { account, signAndSubmitTransaction } = signerOrFn;
+      const transaction = await signAndSubmitTransaction({
+        data: ShelbyBlobClient.createBatchRegisterBlobsPayload({
+          account: AccountAddress.from(account),
+          expirationMicros,
+          blobs: commitments.map((commitment) => ({
+            blobName: commitment.blobName,
+            blobSize: commitment.commitment.raw_data_size,
+            blobMerkleRoot: commitment.commitment.blob_merkle_root,
+            numChunksets: expectedTotalChunksets(
+              commitment.commitment.raw_data_size,
+              options?.chunksetSizeBytes ?? DEFAULT_CHUNKSET_SIZE_BYTES,
+            ),
+          })),
+        }),
+        options: options?.build?.options,
+      });
+
+      return transaction;
+    },
+    ...options,
+  });
+}