@shelby-protocol/solana-kit 0.1.2-alpha.8 → 0.2.0

package/README.md

@@ -11,209 +11,105 @@ The Solana Kit SDK was built to facilitate the development of Solana application
 Install with your favorite package manager such as npm, yarn, or pnpm:
 
 ```bash
-# Install the package
 pnpm install @shelby-protocol/solana-kit
-
-# For React applications (optional)
-pnpm install react react-dom
 ```
 
-## Acquire a Shelby API Key
+## Entry Points
 
-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.
+The package provides two entry points for different use cases:
 
-Follow [this guide](https://docs.shelby.xyz/sdks/typescript/acquire-api-keys#acquiring-api-keys) to acquire an API Key.
+| Entry Point | Import Path | Use Case |
+|-------------|-------------|----------|
+| **Node.js** | `@shelby-protocol/solana-kit/node` | Server-side applications, scripts, CLIs |
+| **React** | `@shelby-protocol/solana-kit/react` | Browser applications with wallet connections |
 
-## Usage
+## Quick Start
 
-Create a `Shelby` client in order to access the SDK's functionality.
+### Node.js / Server-side
 
 ```ts
 import { Shelby, Network } from "@shelby-protocol/solana-kit/node";
-import { Connection } from "@solana/web3.js";
-
-// Create a Solana network connection
-const connection = new Connection("https://api.devnet.solana.com");
+import { Connection, Keypair } from "@solana/web3.js";
 
-// Create a shelby client
 const shelbyClient = new Shelby({
-  // The Shelby network to connect with
   network: Network.SHELBYNET,
-  connection,
-  // The Shelby API Key
+  connection: new Connection("https://api.devnet.solana.com"),
   apiKey: "AG-***",
 });
-```
-
-## Shelby Storage Account
-
-Shelby uses the Aptos blockchain as a coordination and settlement layer. Aptos provides a high-performance, reliable foundation for managing system state and economic logic. As a result, uploading blobs to the Shelby Protocol requires communication with the Aptos network.
-
-To allow a Solana 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 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).
-
-The ownership hierarchy is:
-
-- Solana keypair controls the Storage Account
-- Storage Account owns the blobs on Shelby
-
-### Create a Storage Account
-
-The Shelby Storage Account is derived from:
-
-- An original keypair. This links the main keypair with the storage account and ensures full ownership.
-- A dApp domain. This maintains isolation at the application level. Since the storage account is based on the dApp domain, it is scoped to the dApp context. As a result, each storage account has a different address on different dApps.
-
-```ts
-import { Keypair } from "@solana/web3.js";
-
-// Generate a Solana account
-const solanaKeypair = Keypair.generate();
-
-// The dApp domain. Most likely it is the deployed dApp website domain.
-const domain = "my-awesome-dapp.com";
-
-// Create a storage account controlled by the solana keypair
-const storageAccount = shelbyClient.createStorageAccount(solanaKeypair, domain);
-```
-
-## Upload a Blob to Shelby
-
-### Funding your account
-
-To upload a file, the storage account needs to hold two assets:
-
-- ShelbyUSD tokens: Used to pay for uploading the file to the Shelby devnet network
-- APT tokens: Used to pay for gas fees when sending transactions
-
-To fund your account with ShelbyUSD tokens, you can use the `fundAccountWithShelbyUSD()` function that the SDK provides.
-
-```ts
-// Fund the storage account with shelbyUSD (upload fees)
-await shelbyClient.fundAccountWithShelbyUSD({
-  address: storageAccount.accountAddress,
-  amount: 1_000_000,
-});
-```
 
-To fund your account with APT tokens, you can use the `fundAccountWithAPT()` function that the SDK provides.
-
-```ts
-// Fund the storage account with APT (transaction fees)
-await shelbyClient.fundAccountWithAPT({
-  address: storageAccount.accountAddress,
-  amount: 1_000_000,
-});
+const storageAccount = shelbyClient.createStorageAccount(
+  Keypair.generate(),
+  "my-dapp.com"
+);
 ```
 
-> Note: Alternatively, instead of funding your storage account with APT, you can use [Geomi Gas Station](https://geomi.dev/docs/gas-stations) to sponsor the transaction fees.
-
-```ts
-import { Shelby, Network } from "@shelby-protocol/solana-kit/node";
-import { Connection } from "@solana/web3.js";
+See [Node.js README](./src/node/README.md) for detailed usage.
 
-// Create a Solana network connection
-const connection = new Connection("https://api.devnet.solana.com");
-
-// Create a shelby client
-const shelbyClient = new Shelby({
-  network: Network.SHELBYNET,
-  connection,
-  apiKey: "AG-***",
-  // The Gas Station API Key
-  gasStationApiKey: "AG-***",
-});
-```
-
-### Uploading a File
-
-To upload a file, you can use the `upload()` function that the SDK provides.
-
-```ts
-// Generate a random blob name
-const blobName = `example-${Math.floor(Math.random() * 900000 + 100000)}.txt`;
-
-// Upload a blob to Shelby
-await shelbyClient.upload({
-  blobData: new Uint8Array([1, 2, 3]),
-  signer: storageAccount,
-  blobName,
-  expirationMicros: Date.now() * 1000 + 86400000000, // 1 day
-});
-```
-
-## React Integration
-
-For React applications, use the `useStorageAccount` hook with `@solana/react-hooks`:
+### React / Browser
 
 ```tsx
-"use client";
-
 import { useStorageAccount, Network } from "@shelby-protocol/solana-kit/react";
 import { ShelbyClient } from "@shelby-protocol/sdk/browser";
 import { useWalletConnection } from "@solana/react-hooks";
 
 function MyComponent() {
   const { wallet } = useWalletConnection();
-  const shelbyClient = new ShelbyClient({
-    network: Network.SHELBYNET,
-    apiKey: "AG-***",
-  });
+  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>
-  );
+  // Storage account is automatically derived from the connected wallet
 }
 ```
 
-### Using with `@solana/wallet-adapter-react`
+See [React README](./src/react/README.md) for detailed usage.
 
-If you're using the `@solana/wallet-adapter-react` package, you can adapt the wallet to the expected shape:
+## Key Concepts
 
-```tsx
-import { useWallet } from "@solana/wallet-adapter-react";
+### Shelby Storage Account
 
-function MyComponent() {
-  const { publicKey, signMessage, signIn } = useWallet();
+Shelby uses the Aptos blockchain as a coordination and settlement layer. To allow a Solana 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**.
 
-  const { storageAccountAddress } = useStorageAccount({
-    client: shelbyClient,
-    wallet: publicKey
-      ? {
-          account: { address: publicKey },
-          signMessage,
-          signIn,
-        }
-      : null,
-  });
+This enables cross-chain signatures (SIWS - Sign-In with Solana) 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:**
+
+- Solana keypair/wallet controls the Storage Account
+- Storage Account owns the blobs on Shelby
+
+**Address derivation:**
 
-## Retrieving a file
+The storage account address is deterministically derived from:
+1. The Solana public key
+2. The dApp domain (e.g., `my-dapp.com`)
+
+This means the same Solana 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.
+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.
 
-### GET request
+### Via HTTP Request
 
-Alternatively, you can directly download the file using a GET request to the Shelby RPC endpoint.
+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}"
 ```
 
-With the previous example, the file should be available at
+## Documentation
 
-```bash
-curl -X GET `https://api.shelbynet.shelby.xyz/shelby/v1/blobs/${storageAccount.accountAddress.toString()}/${blobName}`;
-```
+- [Node.js Usage](./src/node/README.md) - Server-side applications
+- [React Usage](./src/react/README.md) - Browser applications
+- [Full Documentation](https://docs.shelby.xyz/sdks/solana-kit)

package/dist/node/index.cjs

@@ -21,8 +21,8 @@ var _gasstationclient = require('@aptos-labs/gas-station-client');
 
 
 // src/node/storageAccount.ts
-var _node3 = require('@aptos-labs/derived-wallet-solana/node');
-var ShelbyStorageAccount = class extends _node3.SolanaDerivedAccount {
+
+var ShelbyStorageAccount = class extends _derivedwalletsolana.SolanaDerivedAccount {
 };
 
 // src/node/shelby.ts

package/dist/node/index.d.cts

@@ -2,7 +2,7 @@ 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 { Connection, Keypair } from '@solana/web3.js';
-import { SolanaDerivedAccount } from '@aptos-labs/derived-wallet-solana/node';
+import { SolanaDerivedAccount } from '@aptos-labs/derived-wallet-solana';
 
 declare const Network: {
     readonly SHELBYNET: Network$1.SHELBYNET;

package/dist/node/index.d.ts

@@ -2,7 +2,7 @@ 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 { Connection, Keypair } from '@solana/web3.js';
-import { SolanaDerivedAccount } from '@aptos-labs/derived-wallet-solana/node';
+import { SolanaDerivedAccount } from '@aptos-labs/derived-wallet-solana';
 
 declare const Network: {
     readonly SHELBYNET: Network$1.SHELBYNET;

package/dist/node/index.mjs

@@ -2,7 +2,7 @@
 export * from "@shelby-protocol/sdk/node";
 
 // src/common/constants.ts
-import { defaultAuthenticationFunction } from "@aptos-labs/derived-wallet-solana";
+import { defaultSolanaAuthenticationFunction } from "@aptos-labs/derived-wallet-solana";
 import { Network as AptosNetwork } from "@aptos-labs/ts-sdk";
 var Network = {
   SHELBYNET: AptosNetwork.SHELBYNET
@@ -10,7 +10,7 @@ var Network = {
 
 // src/common/deriveAddress.ts
 import {
-  defaultAuthenticationFunction as defaultAuthenticationFunction2,
+  defaultSolanaAuthenticationFunction as defaultSolanaAuthenticationFunction2,
   SolanaDerivedPublicKey
 } from "@aptos-labs/derived-wallet-solana";
 
@@ -21,7 +21,7 @@ import {
 } from "@shelby-protocol/sdk/node";
 
 // src/node/storageAccount.ts
-import { SolanaDerivedAccount } from "@aptos-labs/derived-wallet-solana/node";
+import { SolanaDerivedAccount } from "@aptos-labs/derived-wallet-solana";
 var ShelbyStorageAccount = class extends SolanaDerivedAccount {
 };
 

package/dist/react/index.d.ts

@@ -49,4 +49,4 @@ interface UseStorageAccountResult {
 }
 declare function useStorageAccount(params: UseStorageAccountParams): UseStorageAccountResult;
 
-export { Network, type SignAndSubmitTransactionInput, type SignTransactionInput, type SubmitTransactionInput, type UseStorageAccountParams, type UseStorageAccountResult, useStorageAccount };
+export { Network, type SignAndSubmitTransactionInput, type SignTransactionInput, type SolanaWallet, type SubmitTransactionInput, type UseStorageAccountParams, type UseStorageAccountResult, useStorageAccount };

package/dist/react/index.mjs

@@ -1,5 +1,5 @@
 // src/common/constants.ts
-import { defaultAuthenticationFunction } from "@aptos-labs/derived-wallet-solana";
+import { defaultSolanaAuthenticationFunction } from "@aptos-labs/derived-wallet-solana";
 import { Network as AptosNetwork } from "@aptos-labs/ts-sdk";
 var Network = {
   SHELBYNET: AptosNetwork.SHELBYNET
@@ -7,13 +7,13 @@ var Network = {
 
 // src/common/deriveAddress.ts
 import {
-  defaultAuthenticationFunction as defaultAuthenticationFunction2,
+  defaultSolanaAuthenticationFunction as defaultSolanaAuthenticationFunction2,
   SolanaDerivedPublicKey
 } from "@aptos-labs/derived-wallet-solana";
 
 // src/react/useStorageAccount.tsx
 import {
-  defaultAuthenticationFunction as defaultAuthenticationFunction3,
+  defaultSolanaAuthenticationFunction as defaultSolanaAuthenticationFunction3,
   SolanaDerivedPublicKey as SolanaDerivedPublicKey2,
   signAptosTransactionWithSolana
 } from "@aptos-labs/derived-wallet-solana";
@@ -26,23 +26,30 @@ function useStorageAccount(params) {
   const publicKey = wallet?.account?.address?.toString() ?? null;
   const derivedPublicKey = useMemo(() => {
     if (!publicKey || !domain) return null;
-    return new SolanaDerivedPublicKey2({
-      domain,
-      solanaPublicKey: new PublicKey(publicKey),
-      authenticationFunction: defaultAuthenticationFunction3
-    });
+    try {
+      return new SolanaDerivedPublicKey2({
+        domain,
+        solanaPublicKey: new PublicKey(publicKey),
+        authenticationFunction: defaultSolanaAuthenticationFunction3
+      });
+    } catch {
+      return null;
+    }
   }, [publicKey, domain]);
   const storageAccountAddress = useMemo(
     () => derivedPublicKey?.authKey().derivedAddress() ?? null,
     [derivedPublicKey]
   );
   const signTransaction = async (params2) => {
-    if (!storageAccountAddress) {
-      throw new Error("Storage account address not found");
-    }
     if (!publicKey) {
       throw new Error("Wallet not connected");
     }
+    if (!derivedPublicKey) {
+      throw new Error("Invalid Solana public key");
+    }
+    if (!storageAccountAddress) {
+      throw new Error("Storage account address not found");
+    }
     const rawTransaction = await client.aptos.transaction.build.simple({
       sender: storageAccountAddress,
       data: params2.data
@@ -57,7 +64,7 @@ function useStorageAccount(params) {
         signIn: wallet?.signIn,
         name: "Solana Wallet"
       },
-      authenticationFunction: defaultAuthenticationFunction3,
+      authenticationFunction: defaultSolanaAuthenticationFunction3,
       rawTransaction,
       domain
     });

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@shelby-protocol/solana-kit",
-  "version": "0.1.2-alpha.8",
+  "version": "0.2.0",
   "private": false,
   "publishConfig": {
     "access": "public"
@@ -47,7 +47,7 @@
     }
   },
   "dependencies": {
-    "@aptos-labs/derived-wallet-solana": "0.11.0-alpha.4",
+    "@aptos-labs/derived-wallet-solana": "^0.12.0",
     "@aptos-labs/gas-station-client": "^2.0.3",
     "@aptos-labs/ts-sdk": "^5.1.1",
     "@aptos-labs/wallet-standard": "^0.5.2",