Shelby Protocol React SDK

A collection of React hooks and utilities built on top of the @shelby-protocol/sdk.

Installation

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

Documentation

Visit the Shelby React SDK Documentation for more information.

Basic Usage

1. Wrap your application with the QueryClientProvider component.

// src/App.tsx
import { QueryClient, QueryClientProvider } from "@tanstack/react-query";

const queryClient = new QueryClient();

function App({ children }: { children: React.ReactNode }) {
  return (
    <QueryClientProvider client={queryClient}>
      {children}
    </QueryClientProvider>
  );
}

2. Setup the Shelby Client.

// src/shelbyClient.ts
import { ShelbyClient } from "@shelby-protocol/sdk/browser";
import { Network } from "@aptos-labs/ts-sdk";

const shelbyClient = new ShelbyClient({ network: Network.SHELBYNET });

3. Use the queries to interact with the Shelby Protocol.

// src/AccountBlobs.tsx
import { useAccountBlobs } from "@shelby-protocol/react";
import { shelbyClient } from "./shelbyClient";

export function AccountBlobs() {
  const { data: accountBlobs } = useAccountBlobs({
    client: shelbyClient,
    account: "0x123...",
  });
  return (
    <div>
      {accountBlobs?.map((blob) =>
        <div key={blob.name}>
          <div>{blob.name}</div>
          <div>{blob.size}</div>
          <div>{blob.expirationMicros}</div>
        </div>
      )}
    </div>
  );
}

SSR / Server Components

The @shelby-protocol/react/core entry point exports query key factories and types that are safe to use in server-side environments (no createContext or React client APIs at runtime).

// app/account/[address]/page.tsx (Next.js Server Component)
import { ShelbyClient } from "@shelby-protocol/sdk/browser";
import { Network } from "@aptos-labs/ts-sdk";
import { getUseAccountBlobsQueryKey } from "@shelby-protocol/react/core";
import { QueryClient, dehydrate, HydrationBoundary } from "@tanstack/react-query";

export default async function AccountPage({ params }: { params: { address: string } }) {
  const queryClient = new QueryClient();
  const shelbyClient = new ShelbyClient({ network: Network.SHELBYNET });

  await queryClient.prefetchQuery({
    queryKey: getUseAccountBlobsQueryKey({
      network: Network.SHELBYNET,
      account: params.address,
    }),
    queryFn: () => shelbyClient.coordination.getAccountBlobs({ account: params.address }),
  });

  return (
    <HydrationBoundary state={dehydrate(queryClient)}>
      <AccountBlobs />
    </HydrationBoundary>
  );
}

4. Use the mutations to interact with the Shelby Protocol.

// src/UploadBlobs.tsx
import { useUploadBlobs } from "@shelby-protocol/react";

export function UploadBlobs() {
  const signer = new Ed25519Account({
    privateKey: new Ed25519PrivateKey("ed25519-priv-..."),
  })

  const { mutate: uploadBlobs, isPending } = useUploadBlobs({
    client: shelbyClient,
  });

  const handleUploadBlobs = () => 
    uploadBlobs({ 
        signer,
        blobs: [
            { blobName: "file1.txt", blobData: new Uint8Array([...]) },
            { blobName: "file2.txt", blobData: new Uint8Array([...]) },
        ], 
        expirationMicros: Date.now() * 1000 + 86400000000 
    });
  

  return (
    <div>
      <button onClick={handleUploadBlobs}>
        {isPending ? "Uploading..." : "Upload Blobs"}
      </button>
    </div>
  );
}