Overview

The Shelby Protocol Ethereum Kit SDK is built to bridge the gap between Ethereum and the Shelby Protocol, enabling Ethereum developers to use their existing wallets for decentralized blob storage.

Architecture

The SDK provides two entry points for different environments:

┌─────────────────────────────────────────────────────────────────────────┐
│                       Your Ethereum Application                          │
├─────────────────────────────────────────────────────────────────────────┤
│                     @shelby-protocol/ethereum-kit                        │
│                                                                          │
│  ┌─────────────────────────────┐    ┌─────────────────────────────────┐ │
│  │         /node               │    │           /react                │ │
│  │  ┌───────────────────────┐  │    │  ┌───────────────────────────┐  │ │
│  │  │   Shelby Client       │  │    │  │   useStorageAccount       │  │ │
│  │  │   (extends SDK)       │  │    │  │   (React Hook)            │  │ │
│  │  └───────────────────────┘  │    │  └───────────────────────────┘  │ │
│  │  ┌───────────────────────┐  │    │                                 │ │
│  │  │ ShelbyStorageAccount  │  │    │  Uses viem WalletClient for:   │ │
│  │  │ (Wallet → Account)    │  │    │  - Address derivation          │ │
│  │  └───────────────────────┘  │    │  - Transaction signing         │ │
│  └─────────────────────────────┘    └─────────────────────────────────┘ │
├─────────────────────────────────────────────────────────────────────────┤
│                         @shelby-protocol/sdk                             │
│  ┌───────────────────────────┐    ┌───────────────────────────────────┐ │
│  │   Coordination Layer      │    │   RPC Operations                  │ │
│  │   (Aptos Chain)           │    │   (Blob Storage)                  │ │
│  └───────────────────────────┘    └───────────────────────────────────┘ │
└─────────────────────────────────────────────────────────────────────────┘

Entry Points

Node.js (`/node`)

For server-side applications with direct access to Ethereum wallets:

Shelby Client: Extends the core SDK with Ethereum-specific initialization
ShelbyStorageAccount: Converts an ethers.js Wallet into a Shelby signer
Use cases: Backend services, scripts, CLIs, automated uploads

import { Shelby, Network } from "@shelby-protocol/ethereum-kit/node";

Node.js Documentation

Complete guide for server-side integration

React (`/react`)

For browser applications with wallet connections:

useStorageAccount Hook: Derives storage account from connected wallet
Wallet Integration: Works with wagmi's useWalletClient() and viem types
Use cases: React dApps, Next.js applications, browser-based uploads

import { useStorageAccount } from "@shelby-protocol/ethereum-kit/react";
import { useWalletClient } from "wagmi";

React Documentation

Complete guide for browser integration

Cross-Chain Flow

Both entry points use the same underlying cross-chain mechanism:

Node.js Flow

┌──────────────┐     ┌──────────────────────┐     ┌─────────────────┐
│   ethers.js  │────▶│ ShelbyStorageAccount │────▶│  Shelby Client  │
│   Wallet     │     │   (Signs with SIWE)  │     │  (Uploads blob) │
└──────────────┘     └──────────────────────┘     └─────────────────┘

ethers.js Wallet → Provided directly (from private key, env, etc.)
ShelbyStorageAccount → Signs transactions with SIWE envelope
Shelby Client → Submits to the coordination layer

React Flow

┌──────────────┐     ┌──────────────────────┐     ┌─────────────────┐
│   Wallet     │────▶│  useStorageAccount   │────▶│  Shelby Client  │
│  (MetaMask)  │     │ (Prompts for sign)   │     │  (Uploads blob) │
└──────────────┘     └──────────────────────┘     └─────────────────┘

Wallet → User connects via wagmi (RainbowKit, Web3Modal, etc.)
useStorageAccount → Derives address, prompts user to sign
Shelby Client → Submits to the coordination layer

Both entry points use the SIWE envelope format for transaction signing:

Transaction Data → Serialized Aptos transaction
SIWE Message → Human-readable message wrapping the transaction
Ethereum Signature → ECDSA signature from Ethereum wallet
Authenticator → Wrapped signature compatible with Aptos

This enables Ethereum identities to control accounts on the Aptos-based Shelby network.

Common Module

Both entry points share common functionality:

Export	Description
`Network`	Network configuration (currently `SHELBYNET`)

Choosing an Entry Point

Requirement	Use Node.js (`/node`)	Use React (`/react`)
Direct wallet access	✅	❌
Wallet popup for signing	❌	✅
Server-side execution	✅	❌
Browser environment	❌	✅
Automated/batch operations	✅	❌
User-initiated transactions	✅	✅

Overview

Node.js Documentation

React Documentation

On this page