@shelby-protocol/solana-kit 0.0.1

package/README.md

@@ -0,0 +1,159 @@
+# Solana 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 Solana Kit SDK was built to facilitate the development of Solana applications that use the Shelby Protocol.
+
+## Installation
+
+Install with your favorite package manager such as npm, yarn, or pnpm:
+
+```bash
+pnpm install @shelby-protocol/solana-kit
+```
+
+## 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.
+
+Follow [this guide](https://docs.shelby.xyz/sdks/typescript/acquire-api-keys#acquiring-api-keys) to acquire an API Key.
+
+## Usage
+
+Create a `Shelby` client in order to access the SDK's functionality.
+
+```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");
+
+// Create a shelby client
+const shelbyClient = new Shelby({
+  // The Shelby network to connect with
+  network: Network.SHELBYNET,
+  connection,
+  // The Shelby API Key
+  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,
+});
+```
+
+> 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";
+
+// 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
+});
+```
+
+## Retrieving a file
+
+### 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.
+
+### GET request
+
+Alternatively, you can directly download the file 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
+
+```bash
+curl -X GET `https://api.shelbynet.shelby.xyz/shelby/v1/blobs/${storageAccount.accountAddress.toString()}/${blobName}`;
+```

package/dist/node/index.cjs

@@ -0,0 +1,116 @@
+"use strict";Object.defineProperty(exports, "__esModule", {value: true}); function _interopRequireDefault(obj) { return obj && obj.__esModule ? obj : { default: obj }; }// src/node/index.ts
+var _tssdk = require('@aptos-labs/ts-sdk');
+
+// src/node/shelby.ts
+var _gasstationclient = require('@aptos-labs/gas-station-client');
+
+
+var _node = require('@shelby-protocol/sdk/node');
+
+// src/node/storageAccount.ts
+
+
+
+
+var _derivedwalletsolana = require('@aptos-labs/derived-wallet-solana');
+
+
+
+var _walletstandardutil = require('@solana/wallet-standard-util');
+var _tweetnacl = require('tweetnacl'); var _tweetnacl2 = _interopRequireDefault(_tweetnacl);
+var ShelbyStorageAccount = class extends _tssdk.AbstractedAccount {
+  constructor(params) {
+    const { solanaKeypair, domain, authenticationFunction } = params;
+    const derivedPublicKey = new (0, _derivedwalletsolana.SolanaDerivedPublicKey)({
+      domain,
+      solanaPublicKey: solanaKeypair.publicKey,
+      authenticationFunction
+    });
+    super({
+      accountAddress: derivedPublicKey.authKey().derivedAddress(),
+      authenticationFunction,
+      signer: (digest) => {
+        return _tweetnacl2.default.sign.detached(
+          digest,
+          solanaKeypair.secretKey
+        );
+      }
+    });
+    this.solanaKeypair = solanaKeypair;
+    this.domain = domain;
+    this.derivedPublicKey = derivedPublicKey;
+  }
+  /**
+   * Override the transaction signing to use SIWS envelope format
+   */
+  signTransactionWithAuthenticator(transaction) {
+    const { siwsInput, signingMessageDigest } = _derivedwalletsolana.createMessageForSolanaTransaction.call(void 0, {
+      rawTransaction: transaction,
+      authenticationFunction: this.authenticationFunction,
+      solanaPublicKey: this.solanaKeypair.publicKey,
+      domain: this.domain
+    });
+    const messageToSign = _walletstandardutil.createSignInMessage.call(void 0, siwsInput);
+    const signatureBytes = _tweetnacl2.default.sign.detached(
+      messageToSign,
+      this.solanaKeypair.secretKey
+    );
+    return _derivedwalletsolana.createAccountAuthenticatorForSolanaTransaction.call(void 0, 
+      signatureBytes,
+      this.solanaKeypair.publicKey,
+      this.domain,
+      this.authenticationFunction,
+      signingMessageDigest
+    );
+  }
+};
+
+// 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);
+    this.connection = params.connection;
+  }
+  /**
+   * Create a Shelby storage account
+   *
+   * @param solanaKeypair - The Solana keypair
+   * @param domain - The domain of the storage account
+   * @returns The Shelby storage account
+   *
+   * @example
+   * ```typescript
+   * const storageAccount = shelbyClient.createStorageAccount(solanaKeypair, domain);
+   * ```
+   */
+  createStorageAccount(solanaKeypair, domain) {
+    return new ShelbyStorageAccount({
+      solanaKeypair,
+      domain,
+      authenticationFunction: "0x1::solana_derivable_account::authenticate"
+    });
+  }
+};
+
+// src/node/index.ts
+var Network = {
+  SHELBYNET: _tssdk.Network.SHELBYNET
+};
+
+
+
+exports.Network = Network; exports.Shelby = Shelby;

package/dist/node/index.d.cts

@@ -0,0 +1,80 @@
+import { AbstractedAccount, AnyRawTransaction, AccountAuthenticatorAbstraction, Network as Network$1 } from '@aptos-labs/ts-sdk';
+import { ShelbyNetwork, ShelbyClient } from '@shelby-protocol/sdk/node';
+import { Keypair, Connection } from '@solana/web3.js';
+import { SolanaDerivedPublicKey } from '@aptos-labs/derived-wallet-solana';
+
+/**
+ * A Shelby storage account that can be used as a signer for transactions on the Shelby network
+ *
+ * @param params - The parameters for the Shelby storage account
+ * @param params.solanaKeypair - The Solana keypair
+ * @param params.domain - The domain of the storage account
+ * @param params.authenticationFunction - The authentication function
+ * @example
+ * ```typescript
+ * const storageAccount = new ShelbyStorageAccount({
+ *   solanaKeypair: solanaKeypair,
+ *   domain: "my-awesome-dapp.com",
+ *   authenticationFunction: "0x1::solana_derivable_account::authenticate",
+ * });
+ * ```
+ */
+declare class ShelbyStorageAccount extends AbstractedAccount {
+    readonly solanaKeypair: Keypair;
+    readonly domain: string;
+    readonly derivedPublicKey: SolanaDerivedPublicKey;
+    constructor(params: {
+        solanaKeypair: Keypair;
+        domain: string;
+        authenticationFunction: string;
+    });
+    /**
+     * Override the transaction signing to use SIWS envelope format
+     */
+    signTransactionWithAuthenticator(transaction: AnyRawTransaction): AccountAuthenticatorAbstraction;
+}
+
+interface ShelbyParams {
+    network: ShelbyNetwork;
+    connection: Connection;
+    apiKey: string;
+    gasStationApiKey?: string;
+}
+/**
+ * The Shelby client for the Solana network
+ *
+ * @param params - The parameters for the Shelby client
+ *
+ * @example
+ * ```typescript
+ * const shelbyClient = new Shelby({
+ *   network: Network.SHELBYNET,
+ *   connection: new Connection("https://api.devnet.solana.com"),
+ *   apiKey: "AG-***",
+ * });
+ * ```
+ */
+declare class Shelby extends ShelbyClient {
+    private readonly connection;
+    constructor(params: ShelbyParams);
+    /**
+     * Create a Shelby storage account
+     *
+     * @param solanaKeypair - The Solana keypair
+     * @param domain - The domain of the storage account
+     * @returns The Shelby storage account
+     *
+     * @example
+     * ```typescript
+     * const storageAccount = shelbyClient.createStorageAccount(solanaKeypair, domain);
+     * ```
+     */
+    createStorageAccount(solanaKeypair: Keypair, domain: string): ShelbyStorageAccount;
+}
+
+declare const Network: {
+    readonly SHELBYNET: Network$1.SHELBYNET;
+};
+type Network = (typeof Network)[keyof typeof Network];
+
+export { Network, Shelby, type ShelbyParams };

package/dist/node/index.d.ts

@@ -0,0 +1,80 @@
+import { AbstractedAccount, AnyRawTransaction, AccountAuthenticatorAbstraction, Network as Network$1 } from '@aptos-labs/ts-sdk';
+import { ShelbyNetwork, ShelbyClient } from '@shelby-protocol/sdk/node';
+import { Keypair, Connection } from '@solana/web3.js';
+import { SolanaDerivedPublicKey } from '@aptos-labs/derived-wallet-solana';
+
+/**
+ * A Shelby storage account that can be used as a signer for transactions on the Shelby network
+ *
+ * @param params - The parameters for the Shelby storage account
+ * @param params.solanaKeypair - The Solana keypair
+ * @param params.domain - The domain of the storage account
+ * @param params.authenticationFunction - The authentication function
+ * @example
+ * ```typescript
+ * const storageAccount = new ShelbyStorageAccount({
+ *   solanaKeypair: solanaKeypair,
+ *   domain: "my-awesome-dapp.com",
+ *   authenticationFunction: "0x1::solana_derivable_account::authenticate",
+ * });
+ * ```
+ */
+declare class ShelbyStorageAccount extends AbstractedAccount {
+    readonly solanaKeypair: Keypair;
+    readonly domain: string;
+    readonly derivedPublicKey: SolanaDerivedPublicKey;
+    constructor(params: {
+        solanaKeypair: Keypair;
+        domain: string;
+        authenticationFunction: string;
+    });
+    /**
+     * Override the transaction signing to use SIWS envelope format
+     */
+    signTransactionWithAuthenticator(transaction: AnyRawTransaction): AccountAuthenticatorAbstraction;
+}
+
+interface ShelbyParams {
+    network: ShelbyNetwork;
+    connection: Connection;
+    apiKey: string;
+    gasStationApiKey?: string;
+}
+/**
+ * The Shelby client for the Solana network
+ *
+ * @param params - The parameters for the Shelby client
+ *
+ * @example
+ * ```typescript
+ * const shelbyClient = new Shelby({
+ *   network: Network.SHELBYNET,
+ *   connection: new Connection("https://api.devnet.solana.com"),
+ *   apiKey: "AG-***",
+ * });
+ * ```
+ */
+declare class Shelby extends ShelbyClient {
+    private readonly connection;
+    constructor(params: ShelbyParams);
+    /**
+     * Create a Shelby storage account
+     *
+     * @param solanaKeypair - The Solana keypair
+     * @param domain - The domain of the storage account
+     * @returns The Shelby storage account
+     *
+     * @example
+     * ```typescript
+     * const storageAccount = shelbyClient.createStorageAccount(solanaKeypair, domain);
+     * ```
+     */
+    createStorageAccount(solanaKeypair: Keypair, domain: string): ShelbyStorageAccount;
+}
+
+declare const Network: {
+    readonly SHELBYNET: Network$1.SHELBYNET;
+};
+type Network = (typeof Network)[keyof typeof Network];
+
+export { Network, Shelby, type ShelbyParams };

package/dist/node/index.mjs

@@ -0,0 +1,116 @@
+// src/node/index.ts
+import { Network as AptosNetwork } from "@aptos-labs/ts-sdk";
+
+// src/node/shelby.ts
+import { GasStationTransactionSubmitter } from "@aptos-labs/gas-station-client";
+import {
+  ShelbyClient
+} from "@shelby-protocol/sdk/node";
+
+// src/node/storageAccount.ts
+import {
+  createAccountAuthenticatorForSolanaTransaction,
+  createMessageForSolanaTransaction,
+  SolanaDerivedPublicKey
+} from "@aptos-labs/derived-wallet-solana";
+import {
+  AbstractedAccount
+} from "@aptos-labs/ts-sdk";
+import { createSignInMessage } from "@solana/wallet-standard-util";
+import nacl from "tweetnacl";
+var ShelbyStorageAccount = class extends AbstractedAccount {
+  constructor(params) {
+    const { solanaKeypair, domain, authenticationFunction } = params;
+    const derivedPublicKey = new SolanaDerivedPublicKey({
+      domain,
+      solanaPublicKey: solanaKeypair.publicKey,
+      authenticationFunction
+    });
+    super({
+      accountAddress: derivedPublicKey.authKey().derivedAddress(),
+      authenticationFunction,
+      signer: (digest) => {
+        return nacl.sign.detached(
+          digest,
+          solanaKeypair.secretKey
+        );
+      }
+    });
+    this.solanaKeypair = solanaKeypair;
+    this.domain = domain;
+    this.derivedPublicKey = derivedPublicKey;
+  }
+  /**
+   * Override the transaction signing to use SIWS envelope format
+   */
+  signTransactionWithAuthenticator(transaction) {
+    const { siwsInput, signingMessageDigest } = createMessageForSolanaTransaction({
+      rawTransaction: transaction,
+      authenticationFunction: this.authenticationFunction,
+      solanaPublicKey: this.solanaKeypair.publicKey,
+      domain: this.domain
+    });
+    const messageToSign = createSignInMessage(siwsInput);
+    const signatureBytes = nacl.sign.detached(
+      messageToSign,
+      this.solanaKeypair.secretKey
+    );
+    return createAccountAuthenticatorForSolanaTransaction(
+      signatureBytes,
+      this.solanaKeypair.publicKey,
+      this.domain,
+      this.authenticationFunction,
+      signingMessageDigest
+    );
+  }
+};
+
+// 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);
+    this.connection = params.connection;
+  }
+  /**
+   * Create a Shelby storage account
+   *
+   * @param solanaKeypair - The Solana keypair
+   * @param domain - The domain of the storage account
+   * @returns The Shelby storage account
+   *
+   * @example
+   * ```typescript
+   * const storageAccount = shelbyClient.createStorageAccount(solanaKeypair, domain);
+   * ```
+   */
+  createStorageAccount(solanaKeypair, domain) {
+    return new ShelbyStorageAccount({
+      solanaKeypair,
+      domain,
+      authenticationFunction: "0x1::solana_derivable_account::authenticate"
+    });
+  }
+};
+
+// src/node/index.ts
+var Network = {
+  SHELBYNET: AptosNetwork.SHELBYNET
+};
+export {
+  Network,
+  Shelby
+};

package/package.json

@@ -0,0 +1,46 @@
+{
+  "name": "@shelby-protocol/solana-kit",
+  "version": "0.0.1",
+  "private": false,
+  "publishConfig": {
+    "access": "public"
+  },
+  "type": "module",
+  "files": [
+    "dist"
+  ],
+  "exports": {
+    "./node": {
+      "types": "./dist/node/index.d.ts",
+      "import": "./dist/node/index.mjs",
+      "require": "./dist/node/index.cjs"
+    }
+  },
+  "scripts": {
+    "lint": "biome check .",
+    "fmt": "biome check . --write",
+    "build": "tsc --noEmit && (rimraf dist; tsup)",
+    "test": "vitest dev",
+    "test:once": "vitest run"
+  },
+  "devDependencies": {
+    "@biomejs/biome": "2.0.6",
+    "@solana/web3.js": "^1.98.4",
+    "rimraf": "^6.0.1",
+    "tsup": "^8.4.0",
+    "typescript": "^5.8.3",
+    "vitest": "^3.1.2"
+  },
+  "peerDependencies": {
+    "@solana/web3.js": "^1.98.4"
+  },
+  "dependencies": {
+    "@aptos-labs/derived-wallet-base": "^0.10.0",
+    "@aptos-labs/derived-wallet-solana": "^0.9.1",
+    "@aptos-labs/gas-station-client": "^2.0.3",
+    "@aptos-labs/ts-sdk": "^5.1.1",
+    "@shelby-protocol/sdk": "workspace:*",
+    "@solana/wallet-standard-util": "^1.1.2",
+    "tweetnacl": "^1.0.3"
+  }
+}