Solana Kit for the Shelby Protocol

Note: The SDK is currently an alpha version; therefore, you can expect breaking changes.

Shelby is a high-performance decentralized blob storage system designed for demanding read-heavy workloads. Read more about Shelby, its capabilities, and components here.

The Solana Kit SDK was built to facilitate the development of Solana applications that use the Shelby Protocol.

Installation

Install with your favorite package manager such as npm, yarn, or pnpm:

pnpm install @shelby-protocol/solana-kit

Entry Points

The package provides two entry points for different use cases:

| Entry Point | Import Path | Use Case | |-------------|-------------|----------| | Node.js | @shelby-protocol/solana-kit/node | Server-side applications, scripts, CLIs | | React | @shelby-protocol/solana-kit/react | Browser applications with wallet connections |

Quick Start

Node.js / Server-side

import { Shelby, Network } from "@shelby-protocol/solana-kit/node";
import { Connection, Keypair } from "@solana/web3.js";

const shelbyClient = new Shelby({
  network: Network.TESTNET,
  connection: new Connection("https://api.devnet.solana.com"),
  apiKey: "AG-***",
});

const storageAccount = shelbyClient.createStorageAccount(
  Keypair.generate(),
  "my-dapp.com"
);

See Node.js README for detailed usage.

React / Browser

import { useStorageAccount, Network } from "@shelby-protocol/solana-kit/react";
import { ShelbyClient } from "@shelby-protocol/sdk/browser";
import { useWalletConnection } from "@solana/react-hooks";

function MyComponent() {
  const { wallet } = useWalletConnection();
  const shelbyClient = new ShelbyClient({ network: Network.TESTNET, apiKey: "AG-***" });

  const { storageAccountAddress, signAndSubmitTransaction } = useStorageAccount({
    client: shelbyClient,
    wallet,
  });

  // Storage account is automatically derived from the connected wallet
}

See React README for detailed usage.

Key Concepts

Shelby Storage Account

Shelby uses the Aptos blockchain as a coordination and settlement layer. To allow a Solana identity to own data in Shelby, the protocol leverages Aptos Derivable Account Abstraction to create a Shelby Storage Account.

This enables cross-chain signatures (SIWS - Sign-In with Solana) to be managed flexibly and securely on the Aptos network. Read more about it here.

Ownership hierarchy:

• Solana keypair/wallet controls the Storage Account
• Storage Account owns the blobs on Shelby

Address derivation:

The storage account address is deterministically derived from:

1. The Solana public key
2. The dApp domain (e.g., my-dapp.com)

This means the same Solana wallet will have different storage accounts on different dApps, providing application-level isolation.

Acquire a Shelby API Key

API keys authenticate your app and manage rate limits when using Shelby services. Without one, your client runs in "anonymous" mode with much lower limits.

Follow this guide to acquire an API Key.

Retrieving Files

Through Shelby Explorer

Once a blob has been uploaded to Shelby, it is viewable through the Shelby Explorer. Search for the storage account address to view the blobs owned by that account.

Via HTTP Request

Download files directly using a GET request to the Shelby RPC endpoint:

curl -X GET "https://api.shelbynet.shelby.xyz/shelby/v1/blobs/{account_address}/{blob_name}"

Documentation

• Node.js Usage - Server-side applications
• React Usage - Browser applications
• Full Documentation