Skip to main content

​
Installation

Install the SDK in your React project: 
pnpm add storacha-sol

​
Peer Dependencies

The SDK requires Solana wallet adapters: 
pnpm add @solana/wallet-adapter-react @solana/web3.js
The SDK is designed to work with any Solana wallet adapter (Phantom, Solflare, Ledger, etc.)

​
Basic Usage

Import and use the SDK in your React component: 
import { useUpload } from 'storacha-sol';
import { useWallet } from '@solana/wallet-adapter-react';
import { Environment } from 'storacha-sol';

function MyComponent() {
  const client = useUpload(Environment.testnet);
  const { publicKey, signTransaction } = useWallet();
  
  // Use client methods
  const handleUpload = async (files: File[]) => {
    const result = await client.createDeposit({
      payer: publicKey,
      file: files,
      durationDays: 30,
      signTransaction,
    });
  };
}

​
Environment Types

The SDK supports three environments: 
const client = useUpload(Environment.testnet);
Always use testnet or devnet for development. Only use mainnet for production with real SOL.

​
Core Methods

The SDK provides a couple of methods (we’ll add more as we see fit, in the future):

estimateStorageCost

Calculate upload costs before committing

createDeposit

Upload files and create onchain deposit

getSolPrice

Get real-time SOL/USD exchange rate

getUserUploadHistory

Fetch all uploads for a wallet address

renewStorageDuration

Extend storage duration for existing uploads

​
Type Safety

The SDK is type-safe. Import types as needed: 
import type {
  Environment,
  UploadResult,
  UploadHistoryResponse,
  DepositFile,
  RenewalResult,
} from 'storacha-sol';

​
Configuration

​
Network Selection

The environment parameter determines which Solana network to use:
  • devnet: Local development
  • testnet: Public testing with test SOL
  • mainnet: Production with real SOL

​
Common Patterns

​
Checking Balance Before Upload

import { useUpload } from 'storacha-sol';
import { useWallet, useConnection } from '@solana/wallet-adapter-react';
import { LAMPORTS_PER_SOL } from '@solana/web3.js';

const client = useUpload(Environment.testnet);
const { publicKey } = useWallet();
const { connection } = useConnection();

// Get cost estimate
const estimate = client.estimateStorageCost(files, durationInSeconds);

// Get wallet balance
const balance = await connection.getBalance(publicKey);
const balanceInSOL = balance / LAMPORTS_PER_SOL;

// Check if user has enough SOL
if (balanceInSOL < estimate.sol) {
  alert('Insufficient balance!');
  return;
}

// Proceed with upload
const result = await client.createDeposit({...});

​
Toast Notifications

import { toast } from 'sonner';

const handleUpload = async () => {
  const toastId = toast.loading('Uploading files...');
  
  try {
    const result = await client.createDeposit({...});
    
    if (result.success) {
      toast.success('Upload successful!', { id: toastId });
    } else {
      toast.error(result.error, { id: toastId });
    }
  } catch (error) {
    toast.error('Upload failed', { id: toastId });
  }
};

​
Email Notifications (Optional)

const result = await client.createDeposit({
  file,
  durationDays: 30,
  payer: publicKey,
  userEmail: '[email protected]', // Optional: for expiration warnings
  signTransaction,
});

​
Vite Configuration

If using Vite, you’ll need Node.js polyfills for the browser: 
pnpm add -D vite-plugin-node-polyfills
Then update your vite.config.ts: 
import { nodePolyfills } from 'vite-plugin-node-polyfills';
import { defineConfig } from 'vite';

export default defineConfig({
  plugins: [
    nodePolyfills(),
    // ...other plugins
  ],
  define: {
    'process.env': {
      NODE_ENV: JSON.stringify(process.env.NODE_ENV || 'production'),
    },
  },
})
This prevents ReferenceError: process is not defined and provides necessary Node.js polyfills for Solana Web3.js to work in the browser.

​
Next Steps

Upload Files

Learn how to upload files and create deposits

View History

Fetch and display upload history

Renew Storage

Extend storage duration

Core Concepts

Understand how Keep works

​
Support

GitHub Issues

Report bugs or request features

NPM Package

View on npm