@shelby-protocol/ethereum-kit 0.1.0

package/README.md

@@ -0,0 +1,115 @@
+# 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.SHELBYNET,
+  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.SHELBYNET, 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)

package/dist/node/index.cjs

@@ -0,0 +1,61 @@
+"use strict";Object.defineProperty(exports, "__esModule", {value: true}); function _createStarExport(obj) { Object.keys(obj) .filter((key) => key !== "default" && key !== "__esModule") .forEach((key) => { if (exports.hasOwnProperty(key)) { return; } Object.defineProperty(exports, key, {enumerable: true, configurable: true, get: () => obj[key]}); }); }// src/node/index.ts
+var _node = require('@shelby-protocol/sdk/node'); _createStarExport(_node);
+
+// src/common/constants.ts
+var _tssdk = require('@aptos-labs/ts-sdk');
+var Network = {
+  SHELBYNET: _tssdk.Network.SHELBYNET
+};
+
+// src/node/shelby.ts
+var _gasstationclient = require('@aptos-labs/gas-station-client');
+
+
+
+
+// src/node/storageAccount.ts
+var _derivedwalletethereum = require('@aptos-labs/derived-wallet-ethereum');
+var ShelbyStorageAccount = class extends _derivedwalletethereum.EIP1193DerivedAccount {
+};
+
+// src/node/shelby.ts
+var Shelby = class extends _node.ShelbyClient {
+  constructor(params) {
+    const shelbyClientConfig = {
+      network: params.network,
+      apiKey: params.apiKey
+    };
+    if (params.gasStationApiKey) {
+      shelbyClientConfig.aptos = {
+        pluginSettings: {
+          TRANSACTION_SUBMITTER: new (0, _gasstationclient.GasStationTransactionSubmitter)({
+            network: params.network,
+            apiKey: params.gasStationApiKey
+          })
+        }
+      };
+    }
+    super(shelbyClientConfig);
+  }
+  /**
+   * Create a Shelby storage account from an Ethereum wallet.
+   *
+   * @param ethereumWallet - The ethers Wallet instance (with private key)
+   * @param domain - The domain of the storage account
+   * @param scheme - The URI scheme (defaults to "https")
+   * @returns The Shelby storage account
+   *
+   * @example
+   * ```typescript
+   * const storageAccount = shelbyClient.createStorageAccount(ethereumWallet, "my-dapp.com");
+   * ```
+   */
+  createStorageAccount(ethereumWallet, domain, scheme) {
+    return new ShelbyStorageAccount({ ethereumWallet, domain, scheme });
+  }
+};
+
+
+
+
+exports.Network = Network; exports.Shelby = Shelby; exports.ShelbyStorageAccount = ShelbyStorageAccount;

package/dist/node/index.d.cts

@@ -0,0 +1,76 @@
+import { ShelbyNetwork, ShelbyClient } from '@shelby-protocol/sdk/node';
+export * from '@shelby-protocol/sdk/node';
+import { Network as Network$1 } from '@aptos-labs/ts-sdk';
+import { Wallet } from 'ethers';
+import { EIP1193DerivedAccount } from '@aptos-labs/derived-wallet-ethereum';
+
+declare const Network: {
+    readonly SHELBYNET: Network$1.SHELBYNET;
+};
+type Network = (typeof Network)[keyof typeof Network];
+
+/**
+ * A Shelby storage account that can be used as a signer for transactions on the Shelby network.
+ * Uses the standard Ethereum derivable account authentication function.
+ *
+ * Extends EIP1193DerivedAccount from @aptos-labs/derived-wallet-ethereum.
+ *
+ * @example
+ * ```typescript
+ * import { Wallet } from "ethers";
+ *
+ * const ethereumWallet = new Wallet("0x...");
+ * const storageAccount = new ShelbyStorageAccount({
+ *   ethereumWallet,
+ *   domain: "my-awesome-dapp.com",
+ * });
+ * ```
+ */
+declare class ShelbyStorageAccount extends EIP1193DerivedAccount {
+}
+
+interface ShelbyParams {
+    /** The Shelby network to connect with */
+    network: ShelbyNetwork;
+    /** The Shelby API key */
+    apiKey: string;
+    /** The Gas Station API key (optional, for sponsored transactions) */
+    gasStationApiKey?: string;
+}
+/**
+ * The Shelby client for the Ethereum ecosystem.
+ *
+ * @param params - The parameters for the Shelby client
+ *
+ * @example
+ * ```typescript
+ * import { Wallet } from "ethers";
+ *
+ * const shelbyClient = new Shelby({
+ *   network: Network.SHELBYNET,
+ *   apiKey: "AG-***",
+ * });
+ *
+ * const ethereumWallet = new Wallet("0x...");
+ * const storageAccount = shelbyClient.createStorageAccount(ethereumWallet, "my-dapp.com");
+ * ```
+ */
+declare class Shelby extends ShelbyClient {
+    constructor(params: ShelbyParams);
+    /**
+     * Create a Shelby storage account from an Ethereum wallet.
+     *
+     * @param ethereumWallet - The ethers Wallet instance (with private key)
+     * @param domain - The domain of the storage account
+     * @param scheme - The URI scheme (defaults to "https")
+     * @returns The Shelby storage account
+     *
+     * @example
+     * ```typescript
+     * const storageAccount = shelbyClient.createStorageAccount(ethereumWallet, "my-dapp.com");
+     * ```
+     */
+    createStorageAccount(ethereumWallet: Wallet, domain: string, scheme?: string): ShelbyStorageAccount;
+}
+
+export { Network, Shelby, type ShelbyParams, ShelbyStorageAccount };

package/dist/node/index.d.ts

@@ -0,0 +1,76 @@
+import { ShelbyNetwork, ShelbyClient } from '@shelby-protocol/sdk/node';
+export * from '@shelby-protocol/sdk/node';
+import { Network as Network$1 } from '@aptos-labs/ts-sdk';
+import { Wallet } from 'ethers';
+import { EIP1193DerivedAccount } from '@aptos-labs/derived-wallet-ethereum';
+
+declare const Network: {
+    readonly SHELBYNET: Network$1.SHELBYNET;
+};
+type Network = (typeof Network)[keyof typeof Network];
+
+/**
+ * A Shelby storage account that can be used as a signer for transactions on the Shelby network.
+ * Uses the standard Ethereum derivable account authentication function.
+ *
+ * Extends EIP1193DerivedAccount from @aptos-labs/derived-wallet-ethereum.
+ *
+ * @example
+ * ```typescript
+ * import { Wallet } from "ethers";
+ *
+ * const ethereumWallet = new Wallet("0x...");
+ * const storageAccount = new ShelbyStorageAccount({
+ *   ethereumWallet,
+ *   domain: "my-awesome-dapp.com",
+ * });
+ * ```
+ */
+declare class ShelbyStorageAccount extends EIP1193DerivedAccount {
+}
+
+interface ShelbyParams {
+    /** The Shelby network to connect with */
+    network: ShelbyNetwork;
+    /** The Shelby API key */
+    apiKey: string;
+    /** The Gas Station API key (optional, for sponsored transactions) */
+    gasStationApiKey?: string;
+}
+/**
+ * The Shelby client for the Ethereum ecosystem.
+ *
+ * @param params - The parameters for the Shelby client
+ *
+ * @example
+ * ```typescript
+ * import { Wallet } from "ethers";
+ *
+ * const shelbyClient = new Shelby({
+ *   network: Network.SHELBYNET,
+ *   apiKey: "AG-***",
+ * });
+ *
+ * const ethereumWallet = new Wallet("0x...");
+ * const storageAccount = shelbyClient.createStorageAccount(ethereumWallet, "my-dapp.com");
+ * ```
+ */
+declare class Shelby extends ShelbyClient {
+    constructor(params: ShelbyParams);
+    /**
+     * Create a Shelby storage account from an Ethereum wallet.
+     *
+     * @param ethereumWallet - The ethers Wallet instance (with private key)
+     * @param domain - The domain of the storage account
+     * @param scheme - The URI scheme (defaults to "https")
+     * @returns The Shelby storage account
+     *
+     * @example
+     * ```typescript
+     * const storageAccount = shelbyClient.createStorageAccount(ethereumWallet, "my-dapp.com");
+     * ```
+     */
+    createStorageAccount(ethereumWallet: Wallet, domain: string, scheme?: string): ShelbyStorageAccount;
+}
+
+export { Network, Shelby, type ShelbyParams, ShelbyStorageAccount };

package/dist/node/index.mjs

@@ -0,0 +1,61 @@
+// src/node/index.ts
+export * from "@shelby-protocol/sdk/node";
+
+// src/common/constants.ts
+import { Network as AptosNetwork } from "@aptos-labs/ts-sdk";
+var Network = {
+  SHELBYNET: AptosNetwork.SHELBYNET
+};
+
+// src/node/shelby.ts
+import { GasStationTransactionSubmitter } from "@aptos-labs/gas-station-client";
+import {
+  ShelbyClient
+} from "@shelby-protocol/sdk/node";
+
+// src/node/storageAccount.ts
+import { EIP1193DerivedAccount } from "@aptos-labs/derived-wallet-ethereum";
+var ShelbyStorageAccount = class extends EIP1193DerivedAccount {
+};
+
+// src/node/shelby.ts
+var Shelby = class extends ShelbyClient {
+  constructor(params) {
+    const shelbyClientConfig = {
+      network: params.network,
+      apiKey: params.apiKey
+    };
+    if (params.gasStationApiKey) {
+      shelbyClientConfig.aptos = {
+        pluginSettings: {
+          TRANSACTION_SUBMITTER: new GasStationTransactionSubmitter({
+            network: params.network,
+            apiKey: params.gasStationApiKey
+          })
+        }
+      };
+    }
+    super(shelbyClientConfig);
+  }
+  /**
+   * Create a Shelby storage account from an Ethereum wallet.
+   *
+   * @param ethereumWallet - The ethers Wallet instance (with private key)
+   * @param domain - The domain of the storage account
+   * @param scheme - The URI scheme (defaults to "https")
+   * @returns The Shelby storage account
+   *
+   * @example
+   * ```typescript
+   * const storageAccount = shelbyClient.createStorageAccount(ethereumWallet, "my-dapp.com");
+   * ```
+   */
+  createStorageAccount(ethereumWallet, domain, scheme) {
+    return new ShelbyStorageAccount({ ethereumWallet, domain, scheme });
+  }
+};
+export {
+  Network,
+  Shelby,
+  ShelbyStorageAccount
+};

package/dist/react/index.d.ts

@@ -0,0 +1,95 @@
+import { Network as Network$1, InputEntryFunctionData, InputTransactionPluginData, AnyRawTransaction, AccountAuthenticatorAbstraction, AccountAddress } from '@aptos-labs/ts-sdk';
+import { ShelbyClient } from '@shelby-protocol/sdk/browser';
+
+declare const Network: {
+    readonly SHELBYNET: Network$1.SHELBYNET;
+};
+type Network = (typeof Network)[keyof typeof Network];
+
+/**
+ * Wallet interface compatible with wagmi's useWalletClient().
+ * Works with RainbowKit, Web3Modal, ConnectKit, etc.
+ */
+interface EthereumWallet {
+    account: {
+        address: `0x${string}`;
+    };
+    /** EIP-1193 request method - available on wagmi WalletClient */
+    request: (args: {
+        method: string;
+        params?: unknown[];
+    }) => Promise<unknown>;
+}
+/**
+ * Input type for signing transactions with the Ethereum wallet.
+ */
+type SignTransactionInput = {
+    data: InputEntryFunctionData;
+};
+/**
+ * Input type for submitting transactions with the Ethereum wallet.
+ */
+type SubmitTransactionInput = {
+    transaction: AnyRawTransaction;
+    senderAuthenticator: AccountAuthenticatorAbstraction;
+} & InputTransactionPluginData;
+/**
+ * Input type for signing and submitting transactions with the Ethereum wallet.
+ */
+type SignAndSubmitTransactionInput = {
+    data: InputEntryFunctionData;
+} & InputTransactionPluginData;
+/**
+ * Parameters type for the useStorageAccount hook.
+ */
+interface UseStorageAccountParams {
+    /** The Shelby client */
+    client: ShelbyClient;
+    /** The connected Ethereum wallet from wagmi's useWalletClient() */
+    wallet: EthereumWallet | null | undefined;
+}
+/**
+ * Result type for the useStorageAccount hook.
+ */
+interface UseStorageAccountResult {
+    /** The derived Shelby storage account address */
+    storageAccountAddress: AccountAddress | null;
+    /** Sign a transaction for Shelby using the connected Ethereum wallet */
+    signTransaction: (params: SignTransactionInput) => Promise<{
+        authenticator: AccountAuthenticatorAbstraction;
+        rawTransaction: AnyRawTransaction;
+    }>;
+    /** Submit a transaction to Shelby */
+    submitTransaction: (params: SubmitTransactionInput) => Promise<{
+        hash: string;
+    }>;
+    /** Sign and submit a transaction to Shelby */
+    signAndSubmitTransaction: (params: SignAndSubmitTransactionInput) => Promise<{
+        hash: string;
+    }>;
+}
+/**
+ * Hook to access Shelby storage functionality with Ethereum wallets.
+ *
+ * @param params - The Shelby client and connected wallet
+ * @returns Storage account address and transaction signing functions
+ *
+ * @example
+ * ```tsx
+ * import { useWalletClient } from "wagmi";
+ *
+ * function MyComponent() {
+ *   const { data: wallet } = useWalletClient();
+ *
+ *   const { storageAccountAddress, signAndSubmitTransaction } = useStorageAccount({
+ *     client: shelbyClient,
+ *     wallet,
+ *   });
+ *
+ *   // Use storageAccountAddress and signAndSubmitTransaction...
+ * }
+ * ```
+ */
+declare function useStorageAccount(params: UseStorageAccountParams): UseStorageAccountResult;
+
+export { type EthereumWallet, Network, type SignAndSubmitTransactionInput, type SignTransactionInput, type SubmitTransactionInput, type UseStorageAccountParams, type UseStorageAccountResult, useStorageAccount };

package/dist/react/index.mjs

@@ -0,0 +1,87 @@
+// src/common/constants.ts
+import { Network as AptosNetwork } from "@aptos-labs/ts-sdk";
+var Network = {
+  SHELBYNET: AptosNetwork.SHELBYNET
+};
+
+// src/react/useStorageAccount.tsx
+import {
+  defaultEthereumAuthenticationFunction,
+  EIP1193DerivedPublicKey,
+  signAptosTransactionWithEthereum
+} from "@aptos-labs/derived-wallet-ethereum";
+import { UserResponseStatus } from "@aptos-labs/wallet-standard";
+import { useMemo } from "react";
+function useStorageAccount(params) {
+  const { client, wallet } = params;
+  const domain = typeof window !== "undefined" ? window.location.host : void 0;
+  const ethereumAddress = wallet?.account?.address ?? null;
+  const derivedPublicKey = useMemo(() => {
+    if (!ethereumAddress || !domain) return null;
+    return new EIP1193DerivedPublicKey({
+      domain,
+      ethereumAddress,
+      authenticationFunction: defaultEthereumAuthenticationFunction
+    });
+  }, [ethereumAddress, domain]);
+  const storageAccountAddress = useMemo(
+    () => derivedPublicKey?.authKey().derivedAddress() ?? null,
+    [derivedPublicKey]
+  );
+  const signTransaction = async (params2) => {
+    if (!storageAccountAddress) {
+      throw new Error("Storage account address not found");
+    }
+    if (!ethereumAddress) {
+      throw new Error("Wallet not connected");
+    }
+    const rawTransaction = await client.aptos.transaction.build.simple({
+      sender: storageAccountAddress,
+      data: params2.data
+    });
+    const response = await signAptosTransactionWithEthereum({
+      eip1193Provider: wallet,
+      ethereumAddress,
+      authenticationFunction: defaultEthereumAuthenticationFunction,
+      rawTransaction
+    });
+    if (response.status !== UserResponseStatus.APPROVED || !("args" in response)) {
+      throw new Error("User rejected the request.");
+    }
+    return {
+      authenticator: response.args,
+      rawTransaction
+    };
+  };
+  const submitTransaction = async (params2) => {
+    const { transaction, senderAuthenticator, transactionSubmitter } = params2;
+    const submitted = await client.aptos.transaction.submit.simple({
+      transaction,
+      senderAuthenticator,
+      transactionSubmitter: transactionSubmitter ?? null
+    });
+    const committed = await client.aptos.waitForTransaction({
+      transactionHash: submitted.hash
+    });
+    return { hash: committed.hash };
+  };
+  const signAndSubmitTransaction = async (params2) => {
+    const { data, transactionSubmitter } = params2;
+    const { authenticator, rawTransaction } = await signTransaction({ data });
+    return submitTransaction({
+      transaction: rawTransaction,
+      senderAuthenticator: authenticator,
+      transactionSubmitter
+    });
+  };
+  return {
+    storageAccountAddress,
+    signTransaction,
+    submitTransaction,
+    signAndSubmitTransaction
+  };
+}
+export {
+  Network,
+  useStorageAccount
+};

package/package.json

@@ -0,0 +1,64 @@
+{
+  "name": "@shelby-protocol/ethereum-kit",
+  "version": "0.1.0",
+  "private": false,
+  "publishConfig": {
+    "access": "public"
+  },
+  "type": "module",
+  "files": [
+    "dist"
+  ],
+  "exports": {
+    "./node": {
+      "types": "./dist/node/index.d.ts",
+      "require": "./dist/node/index.cjs",
+      "import": "./dist/node/index.mjs"
+    },
+    "./react": {
+      "types": "./dist/react/index.d.ts",
+      "import": "./dist/react/index.mjs"
+    }
+  },
+  "devDependencies": {
+    "@biomejs/biome": "2.0.6",
+    "@testing-library/dom": "^10.4.0",
+    "@testing-library/react": "^16.3.0",
+    "@types/react": "19.2.1",
+    "@types/react-dom": "19.2.1",
+    "happy-dom": "^20.0.10",
+    "react": "19.2.1",
+    "react-dom": "19.2.1",
+    "rimraf": "^6.0.1",
+    "tsup": "^8.4.0",
+    "typescript": "^5.8.3",
+    "vitest": "^3.1.2"
+  },
+  "peerDependencies": {
+    "react": "^18.0.0 || ^19.0.0",
+    "react-dom": "^18.0.0 || ^19.0.0"
+  },
+  "peerDependenciesMeta": {
+    "react": {
+      "optional": true
+    },
+    "react-dom": {
+      "optional": true
+    }
+  },
+  "dependencies": {
+    "@aptos-labs/derived-wallet-ethereum": "^0.9.0",
+    "@aptos-labs/gas-station-client": "^2.0.3",
+    "@aptos-labs/ts-sdk": "^5.1.1",
+    "@aptos-labs/wallet-standard": "^0.5.2",
+    "ethers": "^6.13.5",
+    "@shelby-protocol/sdk": "0.0.9"
+  },
+  "scripts": {
+    "lint": "biome check .",
+    "fmt": "biome check . --write",
+    "build": "tsc --noEmit && (rimraf dist; tsup)",
+    "test": "vitest dev",
+    "test:once": "vitest run"
+  }
+}