Ethereum Kit

Getting Started

Getting Started with the Ethereum Kit SDK for Shelby Protocol

Ethereum Kit SDK

The Ethereum Kit SDK enables Ethereum developers to easily integrate with the Shelby Protocol and leverage decentralized blob storage in their applications.

Installation

npm install @shelby-protocol/ethereum-kit

Entry Points

The SDK provides two entry points optimized for different environments:

Entry PointEnvironmentUse Case
@shelby-protocol/ethereum-kit/nodeNode.jsBackend services, scripts, CLIs
@shelby-protocol/ethereum-kit/reactBrowserReact dApps with wagmi wallet adapters

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, which can affect performance.

Quick Start

Node.js (Server-Side)

For backend services with direct wallet access using ethers.js:

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

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

// Create a storage account from an Ethereum wallet
const ethereumWallet = new Wallet("0x...private_key...");
const storageAccount = shelbyClient.createStorageAccount(
  ethereumWallet,
  "my-app.com"
);

// Upload data
await shelbyClient.upload({
  blobData: new Uint8Array([1, 2, 3]),
  signer: storageAccount,
  blobName: "example.txt",
  expirationMicros: Date.now() * 1000 + 86400000000,
});

React (Browser)

For browser dApps with wagmi wallet connections:

"use client";

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.SHELBYNET,
    apiKey: "AG-***",
  });

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

  return (
    <div>
      <p>Storage Account: {storageAccountAddress?.toString()}</p>
    </div>
  );
}

Works with RainbowKit, Web3Modal, ConnectKit, and other wagmi-based wallet adapters. See the React guide for setup details.

Key Concepts

Cross-Chain Identity

Shelby uses the Aptos blockchain as a coordination and settlement layer. The Ethereum Kit leverages Aptos Derivable Account Abstraction to create a Shelby Storage Account from an Ethereum identity. This enables:

  • Ethereum wallets to control data on Shelby
  • Cross-chain signatures (SIWE) managed securely on the Aptos network
  • Application-level isolation through domain scoping

Ownership Hierarchy

The ownership structure is:

  1. Ethereum Wallet → Controls the Storage Account
  2. Storage Account → Owns blobs on Shelby

Each storage account has a different address on different dApps due to domain scoping. This maintains isolation at the application level.

Next Steps