Storage Account: {storageAccountAddress?.toString()}
Loading...
;
if (error) return Error: {error.message}
;
return (
-
{blobs?.map((blob) => (
- {blob.name} ))}
# Getting Started (/sdks/solana-kit) # Solana Kit SDK The Solana Kit SDK enables Solana developers to easily integrate with the Shelby Protocol and leverage decentralized blob storage in their applications. ## Installation
Storage Account: {storageAccountAddress?.toString()}
# Shelby Client (/sdks/ethereum-kit/node/shelby-client) The `Shelby` class is the main entry point for server-side Ethereum-Shelby integration. It extends the core `ShelbyClient` with Ethereum-specific functionality. ## Import ```typescript import { Shelby, Network } from "@shelby-protocol/ethereum-kit/node"; ``` ## Constructor ```typescript const shelbyClient = new Shelby({ network: Network.TESTNET, apiKey: "AG-***", gasStationApiKey: "GS-***", // Optional }); ``` ### Parameters | Parameter | Type | Required | Description | | ------------------ | --------------- | -------- | ---------------------------------------------- | | `network` | `ShelbyNetwork` | Yes | The Shelby network (e.g., `Network.TESTNET`) | | `apiKey` | `string` | Yes | Your Shelby API key | | `gasStationApiKey` | `string` | No | Gas Station API key for sponsored transactions | ## Methods ### `createStorageAccount` Creates a storage account from an ethers.js Wallet. ```typescript const storageAccount = shelbyClient.createStorageAccount( ethereumWallet, domain, scheme, ); ``` #### Parameters | Parameter | Type | Required | Description | | ---------------- | -------- | -------- | -------------------------------------- | | `ethereumWallet` | `Wallet` | Yes | An ethers.js Wallet instance | | `domain` | `string` | Yes | The dApp domain for address derivation | | `scheme` | `string` | No | URI scheme (default: `"https"`) | #### Returns Returns a `ShelbyStorageAccount` instance that can be used as a signer. ### Inherited Methods The `Shelby` class inherits all methods from `ShelbyClient`: | Method | Description | | ---------- | --------------------------- | | `upload` | Upload a blob to Shelby | | `download` | Download a blob from Shelby | ### Funding your account To upload files, you will need to fund your account with two assets: 1. **APT tokens**: Fund your account with testnet APT through the [Aptos Testnet Faucet](https://aptos.dev/network/faucet). 2. **ShelbyUSD tokens**: Sign up for early access through the [Shelby Discord](https://discord.gg/shelbyprotocol) to receive testnet ShelbyUSD tokens. ## Complete Example ```typescript import { Shelby, Network } from "@shelby-protocol/ethereum-kit/node"; import { Wallet } from "ethers"; async function main() { // Initialize client const shelbyClient = new Shelby({ network: Network.TESTNET, apiKey: process.env.SHELBY_API_KEY!, }); // Create storage account from private key const ethereumWallet = new Wallet(process.env.ETHEREUM_PRIVATE_KEY!); const storageAccount = shelbyClient.createStorageAccount( ethereumWallet, "my-dapp.com", ); console.log("Storage Account:", storageAccount.accountAddress.toString()); // Fund the storage account with APT through https://aptos.dev/network/faucet // Fund the storage account with ShelbyUSD through the Shelby Discord early access program // Upload a file const blobName = `hello-${Date.now()}.txt`; await shelbyClient.upload({ blobData: new TextEncoder().encode("Hello, Shelby!"), signer: storageAccount, blobName, expirationMicros: Date.now() * 1000 + 86400000000, }); console.log("Done! File available at:"); console.log( `https://api.testnet.shelby.xyz/shelby/v1/blobs/${storageAccount.accountAddress}/${blobName}`, ); } main().catch(console.error); ``` ## Gas Station (Sponsored Transactions) To sponsor gas fees for your users, provide a Gas Station API key: ```typescript const shelbyClient = new Shelby({ network: Network.TESTNET, apiKey: "AG-***", gasStationApiKey: "GS-***", }); ``` With a Gas Station key configured, users don't need APT in their accounts for transaction fees. # Storage Account (/sdks/ethereum-kit/node/storage-account) The `ShelbyStorageAccount` class represents a Shelby storage account derived from an Ethereum wallet. It extends `EIP1193DerivedAccount` from `@aptos-labs/derived-wallet-ethereum`. ## Overview A storage account: * Is derived deterministically from an Ethereum address and domain * Can sign transactions on behalf of the Ethereum wallet * Owns blobs stored on Shelby ## Import ```typescript import { ShelbyStorageAccount } from "@shelby-protocol/ethereum-kit/node"; ``` ## Creation The recommended way to create a storage account is via the `Shelby` client: ```typescript 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...private_key..."); const storageAccount = shelbyClient.createStorageAccount( ethereumWallet, "my-dapp.com", ); ``` Or directly: ```typescript import { ShelbyStorageAccount } from "@shelby-protocol/ethereum-kit/node"; import { Wallet } from "ethers"; const ethereumWallet = new Wallet("0x...private_key..."); const storageAccount = new ShelbyStorageAccount({ ethereumWallet, domain: "my-dapp.com", }); ``` ## Properties | Property | Type | Description | | ------------------------ | ------------------------- | -------------------------------------- | | `accountAddress` | `AccountAddress` | The derived Aptos account address | | `ethereumWallet` | `Wallet` | The underlying ethers.js Wallet | | `domain` | `string` | The domain used for derivation | | `scheme` | `string` | The URI scheme (default: `"https"`) | | `derivedPublicKey` | `EIP1193DerivedPublicKey` | The derived public key instance | | `authenticationFunction` | `string` | The authentication function identifier | ## Address Derivation The storage account address is deterministically derived from: 1. The Ethereum wallet's address 2. The domain string ```typescript // Same wallet + domain = same storage account address const account1 = shelbyClient.createStorageAccount(wallet, "app.com"); const account2 = shelbyClient.createStorageAccount(wallet, "app.com"); account1.accountAddress.toString() === account2.accountAddress.toString(); // true // Different domain = different storage account address const account3 = shelbyClient.createStorageAccount(wallet, "other.com"); account1.accountAddress.toString() !== account3.accountAddress.toString(); // true ```
Storage Account: {storageAccountAddress?.toString()}
# useStorageAccount (/sdks/ethereum-kit/react/use-storage-account) The `useStorageAccount` hook provides a convenient way to interact with Shelby storage from React applications using a connected Ethereum wallet. ## Overview This hook: * Derives a Shelby storage account address from the connected Ethereum wallet * Provides functions to sign and submit transactions to Shelby * Handles the SIWE (Sign-In With Ethereum) authentication flow automatically ## Import ```typescript import { useStorageAccount } from "@shelby-protocol/ethereum-kit/react"; ``` ## Parameters ```typescript interface UseStorageAccountParams { /** The Shelby client instance */ client: ShelbyClient; /** The connected Ethereum wallet from wagmi's useWalletClient() */ wallet: EthereumWallet | null | undefined; } ``` | Parameter | Type | Required | Description | | --------- | ------------------------ | -------- | ----------------------------- | | `client` | `ShelbyClient` | Yes | The Shelby client instance | | `wallet` | `EthereumWallet \| null` | Yes | The connected Ethereum wallet | ### EthereumWallet Type The `EthereumWallet` type is viem's `WalletClient`, which is what wagmi's `useWalletClient()` returns: ```typescript import type { WalletClient, Transport, Chain, Account } from "viem"; type EthereumWallet = WalletClient
Please connect your wallet
; } return (Ethereum Address: {wallet.account.address}
Shelby Storage: {storageAccountAddress?.toString()}
e.target.files?.[0] && handleUpload(e.target.files[0])}
disabled={!wallet || isPending}
/>
{isPending &&
);
}
```
## How It Works
1. **Automatic Address Derivation**: The hook automatically derives the storage account address from:
* The connected wallet's Ethereum address
* The current page's domain (`window.location.host`)
2. **SIWE Signing**: When signing transactions, the hook uses Sign-In with Ethereum (SIWE) to create signatures that the Aptos blockchain can verify.
3. **Domain Isolation**: Each dApp domain gets a unique storage account for the same wallet, providing application-level isolation.
## Type Safety with wagmi
The hook is designed for seamless integration with wagmi's `useWalletClient()`:
```tsx
import { useWalletClient } from "wagmi";
function MyComponent() {
// wallet is WalletClientUploading...
}Upload Files to Shelby
{!connected && (Please connect your wallet to upload files.
{selectedFiles.length > 0 && (
Selected Files:
-
{selectedFiles.map((file, index) => (
- {file.name} ({(file.size / 1024).toFixed(2)} KB) ))}
{uploadBlobs.isError && (
Error: {uploadBlobs.error?.message}
Connected
{account.address.slice(0, 6)}...{account.address.slice(-4)}
Connect your wallet
Shelby File Upload
# useCommitBlobs (/sdks/react/mutations/use-commit-blobs) This mutation uploads multiple blobs data to the RPC endpoint with configurable concurrency control. ## Example ```tsx import { useCommitBlobs } from "@shelby-protocol/react"; function CommitBlobs() { const commitBlobs = useCommitBlobs({ onSuccess: () => { console.log("Blobs committed successfully"); }, }); const handleCommit = () => { commitBlobs.mutate({ account: "0x123...", blobs: [ { blobName: "file1.txt", blobData: new Uint8Array([/* ... */]) }, { blobName: "file2.txt", blobData: new Uint8Array([/* ... */]) }, ], }); }; return ( ); } ``` ## Parameters
Loading...
;
if (error) return Error: {error.message}
;
return (
-
{blobs?.map((blob) => (
- {blob.name} ))}
Loading...
;
if (error) return Error: {error.message}
;
if (!metadata) return Blob not found
;
return (
{metadata.name}
Size: {metadata.size} bytes
Created: {new Date(metadata.created_at).toLocaleString()}
Updated: {new Date(metadata.updated_at).toLocaleString()}
-
{blobs.map((blob) => (
- {blob.blobNameSuffix} -{" "} ))}
{!wallet ? (
);
```
Please connect your wallet
) : ( <>Storage Account: {storageAccountAddress?.toString()}
{status}
)}# Overview (/sdks/solana-kit/node) # Node.js API The Node.js entry point provides server-side functionality for integrating Solana applications with the Shelby Protocol. It's designed for backend services, scripts, and CLI applications where you have direct access to Solana keypairs. ## Installation
# Shelby Client (/sdks/solana-kit/node/shelby-client) The `Shelby` class is the main entry point for interacting with the Shelby Protocol from a Solana application. It extends the core `ShelbyClient` with Solana-specific functionality. ## Constructor ```typescript import { Shelby, Network } from "@shelby-protocol/solana-kit/node"; import { Connection } from "@solana/web3.js"; const shelbyClient = new Shelby({ network: Network.TESTNET, connection: new Connection("https://api.devnet.solana.com"), apiKey: "AG-***", }); ``` ## Parameters | Parameter | Type | Required | Description | | ------------ | --------------- | -------- | ------------------------------------------------------------ | | `network` | `ShelbyNetwork` | Yes | The Shelby network to connect with (e.g., `Network.TESTNET`) | | `connection` | `Connection` | Yes | The Solana network connection | | `apiKey` | `string` | Yes | Your Shelby API key | ## Methods ### createStorageAccount Creates a Shelby storage account derived from a Solana keypair. ```typescript const storageAccount = shelbyClient.createStorageAccount(solanaKeypair, domain); ``` #### Parameters | Parameter | Type | Description | | --------------- | --------- | -------------------------------------------------------- | | `solanaKeypair` | `Keypair` | The Solana keypair that will control the storage account | | `domain` | `string` | The dApp domain for account isolation | #### Returns Returns a `ShelbyStorageAccount` instance that can be used as a signer for transactions. ## Inherited Methods The `Shelby` class extends `ShelbyClient` and inherits all its methods: ### upload Upload blobs to the Shelby network. ```typescript await shelbyClient.upload({ blobData: new Uint8Array([1, 2, 3]), signer: storageAccount, blobName: "example.txt", expirationMicros: Date.now() * 1000 + 86400000000, }); ``` ### Funding your account To upload files, you will need to fund your account with two assets: 1. **APT tokens**: Fund your storage account with testnet APT through the [Aptos Testnet Faucet](https://aptos.dev/network/faucet). 2. **ShelbyUSD tokens**: Sign up for early access through the [Shelby Discord](https://discord.gg/shelbyprotocol) to receive testnet ShelbyUSD tokens.
Storage Account: {storageAccountAddress?.toString()}
# useStorageAccount (/sdks/solana-kit/react/use-storage-account) The `useStorageAccount` hook provides a convenient way to interact with Shelby storage from React applications using a connected Solana wallet. ## Overview This hook: * Derives a Shelby storage account address from the connected Solana wallet * Provides functions to sign and submit transactions to Shelby * Handles the SIWS (Sign-In With Solana) authentication flow automatically ## Import ```typescript import { useStorageAccount } from "@shelby-protocol/solana-kit/react"; ``` ## Parameters ```typescript interface UseStorageAccountParams { /** The Shelby client instance */ client: ShelbyClient; /** The connected Solana wallet */ wallet: SolanaWallet | null; } ``` | Parameter | Type | Required | Description | | --------- | ---------------------- | -------- | --------------------------- | | `client` | `ShelbyClient` | Yes | The Shelby client instance | | `wallet` | `SolanaWallet \| null` | Yes | The connected Solana wallet | ### SolanaWallet Interface The `SolanaWallet` interface is compatible with `@solana/react-hooks`: ```typescript interface SolanaWallet { account: { address: { toString(): string }; }; signMessage?: (message: Uint8Array) => Promise
Please connect your wallet
; } return (Solana Address: {wallet.account.address.toString()}
Shelby Storage: {storageAccountAddress?.toString()}
# Specifications (/sdks/typescript/node/specifications) ## ShelbyNodeClient Node.js-specific implementation that extends the core ShelbyClient with server-side blob operations.
Upload Token-Gated File
Connect your wallet to upload encrypted files that can be purchased by others.
Wallet not connected
Upload Token-Gated File
Upload an encrypted file to Shelby and register it on Solana. Others can purchase access to decrypt it.
{selectedFile ? (
) : (
)}
{/* Price Input */}
{selectedFile.name}
{(selectedFile.size / 1024).toFixed(1)} KB
Click to select a file to sell
setPrice(e.target.value)}
disabled={isProcessing || isSending}
className="flex-1 rounded-lg border border-border-low bg-card px-4 py-2.5 text-sm outline-none transition placeholder:text-muted focus:border-foreground/30 disabled:cursor-not-allowed disabled:opacity-60"
/>
{/* Upload Button */}
{statusMessage}
)}
{/* Storage Account Info */}
Shelby Storage Account:{" "} {storageAccountAddress?.toString()}
Browse Files
No seller account configured. Set{" "}
NEXT_PUBLIC_SELLER_ACCOUNT
{" "}
in your .env file.
Browse Files
{isConnected ? "Select a file to purchase access and decrypt." : "Connect your wallet to purchase access to token-gated files."}
{isBlobsLoading && (
{/* Action Button - only show when a file is selected */}
{selectedBlob && (
)}
{/* Status Message - only show when a file is selected */}
{selectedBlob && statusMessage && (
Loading files...
)}
{isCheckingPurchases && !isBlobsLoading && (
Checking purchase status...
)}
{blobsError && (
Failed to load files: {blobsError.message}
)}
{blobs && blobs.length === 0 && (
No files found for this account.
)}
{blobs && blobs.length > 0 && (
{blobs.map((blob) => {
const isSelected =
selectedBlob?.blobNameSuffix === blob.blobNameSuffix;
const isPurchased =
isConnected && purchasedFiles.get(blob.blobNameSuffix) === true;
return (
);
})}
)}
{statusMessage}
)}
Token-Gated Files
Upload and buy encrypted files
Upload encrypted files to sell, or purchase access to existing files with SOL.
Files for sale
# Uploading a File (/sdks/typescript/node/guides/uploading-file) import { Step, Steps } from "fumadocs-ui/components/steps"; # Overview In this guide, we will walk you through the process of obtaining ShelbyUSD tokens and uploading a file to the Shelby network.