React SDK

The Shelby Protocol React SDK provides a comprehensive set of React hooks built on top of @tanstack/react-query for interacting with the Shelby Protocol. This reference covers all available query and mutation hooks for blob storage operations.

Installation

npm install @shelby-protocol/react @shelby-protocol/sdk @aptos-labs/ts-sdk @tanstack/react-query

Prerequisites

The React SDK requires the following peer dependencies:

@shelby-protocol/sdk - Core SDK for Shelby Protocol
@aptos-labs/ts-sdk - Aptos TypeScript SDK
@tanstack/react-query - React Query for data fetching and state management
react and react-dom - React framework

Optional Dependencies

@aptos-labs/wallet-adapter-react - For wallet adapter integration (optional)

Quick Start

Setting up React Query

First, wrap your application with a QueryClientProvider and the ShelbyClientProvider. This is the recommended route so hooks can read the client from context without passing it into every call.

import { QueryClient, QueryClientProvider } from "@tanstack/react-query";
import { ShelbyClientProvider } from "@shelby-protocol/react";
import { ShelbyClient } from "@shelby-protocol/sdk/browser";
import { Network } from "@aptos-labs/ts-sdk";

const queryClient = new QueryClient();

// Create a Shelby client instance
const shelbyClient = new ShelbyClient({ network: Network.SHELBYNET });

function App() {
  return (
    <QueryClientProvider client={queryClient}>
      <ShelbyClientProvider client={shelbyClient}>
        {/* Your app components */}
      </ShelbyClientProvider>
    </QueryClientProvider>
  );
}

Basic Query Example

Query blob metadata for an account:

import { useAccountBlobs } from "@shelby-protocol/react";

function BlobList({ account }: { account: string }) {
  const { data: blobs, isLoading, error } = useAccountBlobs({
    account,
    pagination: { limit: 10, offset: 0 },
  });

  if (isLoading) return <div>Loading...</div>;
  if (error) return <div>Error: {error.message}</div>;

  return (
    <ul>
      {blobs?.map((blob) => (
        <li key={blob.name}>{blob.name}</li>
      ))}
    </ul>
  );
}

Basic Mutation Example

Upload blobs to the Shelby network:

import { useUploadBlobs } from "@shelby-protocol/react";
import { Account } from "@aptos-labs/ts-sdk";

function UploadBlob() {
  const uploadBlobs = useUploadBlobs({
    onSuccess: () => {
      console.log("Upload complete!");
    },
  });

  const handleUpload = async () => {
    const signer = Account.generate();
    const fileData = new Uint8Array([/* your file data */]);

    uploadBlobs.mutate({
      signer,
      blobs: [{ blobName: "example.txt", blobData: fileData }],
      expirationMicros: Date.now() * 1000 + 86400000000, // 1 day
    });
  };

  return (
    <button onClick={handleUpload} disabled={uploadBlobs.isPending}>
      {uploadBlobs.isPending ? "Uploading..." : "Upload Blob"}
    </button>
  );
}

Getting Started