npm package: @shelby-protocol/ethereum-kit
Description: > Note: The SDK is currently an alpha version; therefore, you can expect breaking changes.
Latest version: 0.1.8

# 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](https://docs.shelby.xyz/protocol).

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:

```bash
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

```ts
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](./src/node/README.md) for detailed usage.

### React / Browser (with wagmi)

```tsx
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](./src/react/README.md) 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](https://github.com/aptos-foundation/AIPs/blob/main/aips/aip-113.md) 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](https://aptos.dev/build/sdks/wallet-adapter/x-chain-accounts).

**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](https://docs.shelby.xyz/sdks/typescript/acquire-api-keys#acquiring-api-keys) 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](https://explorer.shelby.xyz/shelbynet). 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:

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

## Documentation

- [Node.js Usage](./src/node/README.md) - Server-side applications
- [React Usage](./src/react/README.md) - Browser applications (wagmi)
- [Full Documentation](https://docs.shelby.xyz/sdks/ethereum-kit)