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.

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:

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 to acquire an API Key.

Usage

Create a Shelby client in order to access the SDK's functionality.

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 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.

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.

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.

// 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.

// 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 to sponsor the transaction fees.

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.

// 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. 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.

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

curl -X GET `https://api.shelbynet.shelby.xyz/shelby/v1/blobs/${storageAccount.accountAddress.toString()}/${blobName}`;