Overview

The Shelby Protocol Solana Kit SDK is built to bridge the gap between Solana and the Shelby Protocol, enabling Solana developers to use their existing keypairs or wallet connections for decentralized blob storage.

Architecture

The SDK provides two entry points for different environments:

┌─────────────────────────────────────────────────────────────────────────┐
│                         Your Solana Application                          │
├─────────────────────────────────────────────────────────────────────────┤
│                      @shelby-protocol/solana-kit                         │
│                                                                          │
│  ┌─────────────────────────────┐    ┌─────────────────────────────────┐ │
│  │         /node               │    │           /react                │ │
│  │  ┌───────────────────────┐  │    │  ┌───────────────────────────┐  │ │
│  │  │   Shelby Client       │  │    │  │   useStorageAccount       │  │ │
│  │  │   (extends SDK)       │  │    │  │   (React Hook)            │  │ │
│  │  └───────────────────────┘  │    │  └───────────────────────────┘  │ │
│  │  ┌───────────────────────┐  │    │                                 │ │
│  │  │ ShelbyStorageAccount  │  │    │  Uses connected wallet for:    │ │
│  │  │ (Keypair → 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 Solana keypairs:

Shelby Client: Extends the core SDK with Solana-specific initialization
ShelbyStorageAccount: Converts a Solana Keypair into a Shelby signer
Use cases: Backend services, scripts, CLIs, automated uploads

import { Shelby, Network } from "@shelby-protocol/solana-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 Phantom, Solflare, and other Solana wallets
Use cases: React dApps, Next.js applications, browser-based uploads

import { useStorageAccount } from "@shelby-protocol/solana-kit/react";

React Documentation

Complete guide for browser integration

Cross-Chain Flow

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

Node.js Flow

┌──────────────┐     ┌──────────────────────┐     ┌─────────────────┐
│   Solana     │────▶│ ShelbyStorageAccount │────▶│  Shelby Client  │
│   Keypair    │     │   (Signs with SIWS)  │     │  (Uploads blob) │
└──────────────┘     └──────────────────────┘     └─────────────────┘

Solana Keypair → Provided directly (from file, env, etc.)
ShelbyStorageAccount → Signs transactions with SIWS envelope
Shelby Client → Submits to the coordination layer

React Flow

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

Wallet → User connects via browser extension
useStorageAccount → Derives address, prompts user to sign
Shelby Client → Submits to the coordination layer

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

Transaction Data → Serialized Aptos transaction
SIWS Message → Human-readable message wrapping the transaction
Solana Signature → Ed25519 signature from Solana keypair/wallet
Authenticator → Wrapped signature compatible with Aptos

This enables Solana 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`)
`deriveStorageAccountAddress`	Derives Shelby address from Solana public key
`createSiwsMessage`	Creates the SIWS message for signing
`createAuthenticator`	Wraps signature in Aptos authenticator format

Choosing an Entry Point

Requirement	Use Node.js (`/node`)	Use React (`/react`)
Direct keypair 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