Ethereum Kit

Overview

Client-side Ethereum Kit for React and browser environments

React API

The React entry point provides client-side functionality for integrating Ethereum wallets with the Shelby Protocol. It's designed for browser applications where users connect their Ethereum wallets (MetaMask, Coinbase Wallet, etc.) via wagmi to interact with Shelby storage.

Installation

npm install @shelby-protocol/ethereum-kit

You'll also need wagmi and its dependencies for wallet connections:

npm install wagmi viem @tanstack/react-query

For simplicity, also install the Shelby react package for react hooks helpers:

npm install @shelby-protocol/react

Wallet Setup

The Ethereum Kit works with wagmi-based wallet libraries:

All of these use wagmi under the hood, so you can use useWalletClient() directly with the Ethereum Kit.

See your wallet library's documentation for setup instructions. Once configured, the useWalletClient() hook provides the wallet needed by Ethereum Kit.

Usage

Import from the @shelby-protocol/ethereum-kit/react entry point:

"use client";

import { useStorageAccount, Network } from "@shelby-protocol/ethereum-kit/react";
import { useUploadBlobs } from "@shelby-protocol/react";
import { ShelbyClient } from "@shelby-protocol/sdk/browser";
import { useWalletClient } from "wagmi";

function MyComponent() {
  // Use wagmi wallet hook
  const { data: wallet } = useWalletClient();

  // Initiate Shelby client
  const shelbyClient = new ShelbyClient({
    network: Network.SHELBYNET,
    apiKey: "AG-***",
  });

  // Use Shelby ethereum-kit hook
  const { storageAccountAddress, signAndSubmitTransaction } = useStorageAccount({
    client: shelbyClient,
    wallet,
  });

  // Use Shelby react package upload blob hook
  const { mutateAsync: uploadBlobs } = useUploadBlobs({
    client: shelbyClient,
  });

  const handleUpload = async () => {
    await uploadBlobs({
      signer: { account: storageAccountAddress, signAndSubmitTransaction },
      blobs: [
        {
          blobName: "example.txt",
          blobData: new Uint8Array([1, 2, 3]),
        },
      ],
      // 30 days from now in microseconds
      expirationMicros: (1000 * 60 * 60 * 24 * 30 + Date.now()) * 1000,
    });
  };

  return (
    <div>
      <p>Storage Account: {storageAccountAddress?.toString()}</p>
      <button onClick={handleUpload}>Upload</button>
    </div>
  );
}

When to Use React

Use the React entry point when you:

  • Building browser-based dApps
  • Users connect via Ethereum wallet extensions (MetaMask, Coinbase Wallet, etc.)
  • Need wallet-based signing (user approves each transaction)
  • Building React/Next.js applications

For server-side applications with direct wallet access, use the Node.js entry point instead.

Exports

The @shelby-protocol/ethereum-kit/react entry point exports:

ExportDescription
useStorageAccountReact hook for storage account operations
EthereumWalletType for viem WalletClient
UseStorageAccountParamsType for hook parameters
UseStorageAccountResultType for hook return value
SignAndSubmitTransactionInputType for transaction input
SignTransactionInputType for sign-only transaction input
SubmitTransactionInputType for submit-only transaction input
NetworkNetwork configuration constants

Key Differences from Node.js

FeatureNode.js (/node)React (/react)
SigningDirect wallet signingWallet popup for user approval
Storage AccountShelbyStorageAccount classDerived via hook
EnvironmentServer-sideBrowser
Wallet AccessFull wallet (with private key)Public address only (wallet holds key)

Next Steps