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-kitEntry Points
The SDK provides two entry points optimized for different environments:
Node.js
Server-side applications with direct wallet access
React
Browser applications with wallet connections (wagmi)
| Entry Point | Environment | Use Case |
|---|---|---|
@shelby-protocol/ethereum-kit/node | Node.js | Backend services, scripts, CLIs |
@shelby-protocol/ethereum-kit/react | Browser | React 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:
- Ethereum Wallet → Controls the Storage Account
- 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.