Ethereum 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 Ethereum Kit SDK was built to facilitate the development of Ethereum applications that use the Shelby Protocol.

Installation

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

pnpm install @shelby-protocol/ethereum-kit

Entry Points

The package provides two entry points for different use cases:

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

Quick Start

Node.js / Server-side

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

const shelbyClient = new Shelby({
  network: Network.TESTNET,
  apiKey: "AG-***",
});

const ethereumWallet = new Wallet("0x...");
const storageAccount = shelbyClient.createStorageAccount(
  ethereumWallet,
  "my-dapp.com"
);

See Node.js README for detailed usage.

React / Browser (with wagmi)

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

function MyComponent() {
  const { data: wallet } = useWalletClient();
  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 an Ethereum identity to own data in Shelby, the protocol leverages Aptos Derivable Account Abstraction to create a Shelby Storage Account.

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

Ownership hierarchy:

• Ethereum wallet controls the Storage Account
• Storage Account owns the blobs on Shelby

Address derivation:

The storage account address is deterministically derived from:

1. The Ethereum address
2. The dApp domain (e.g., my-dapp.com)

This means the same Ethereum 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 (wagmi)
• Full Documentation