> ## Documentation Index
> Fetch the complete documentation index at: https://docs.toju.network/llms.txt
> Use this file to discover all available pages before exploring further.

# Overview

> Getting started with the SDKs

We provide separate SDK packages per chain. Pick the one that matches your payment method.

## Installation

<Tabs>
  <Tab title="Solana (SOL)">
    <CodeGroup>
      ```bash pnpm theme={null}
      pnpm add @toju.network/sol
      ```

      ```bash npm theme={null}
      npm install @toju.network/sol
      ```

      ```bash yarn theme={null}
      yarn add @toju.network/sol
      ```
    </CodeGroup>

    **Peer dependencies:**

    ```bash theme={null}
    pnpm add @solana/wallet-adapter-react @solana/web3.js
    ```

    <Info>
      Works with any Solana wallet adapter (Phantom, Solflare, Ledger, etc.)
    </Info>
  </Tab>

  <Tab title="Filecoin (USDFC)">
    <CodeGroup>
      ```bash pnpm theme={null}
      pnpm add @toju.network/fil
      ```

      ```bash npm theme={null}
      npm install @toju.network/fil
      ```

      ```bash yarn theme={null}
      yarn add @toju.network/fil
      ```
    </CodeGroup>

    **Peer dependencies:**

    ```bash theme={null}
    pnpm add wagmi viem @tanstack/react-query
    ```

    <Info>
      Uses wagmi for EVM wallet connections (MetaMask, etc.) on the Filecoin network.
    </Info>
  </Tab>
</Tabs>

## Basic Usage

Import and use the SDK in your React component:

```typescript theme={null}
import { useUpload } from '@toju.network/sol';
import { useWallet } from '@solana/wallet-adapter-react';
import { Environment } from '@toju.network/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:

<CodeGroup>
  ```typescript Testnet theme={null}
  const client = useUpload(Environment.testnet);
  ```

  ```typescript Devnet theme={null}
  const client = useUpload(Environment.devnet);
  ```

  ```typescript Mainnet theme={null}
  const client = useUpload(Environment.mainnet);
  ```
</CodeGroup>

<Warning>
  Always use `testnet` or `devnet` for development. Only use `mainnet` for production with real tokens.
</Warning>

## Core Methods

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

<CardGroup cols={2}>
  <Card title="estimateStorageCost" icon="calculator" href="/sdk/deposit#estimate-cost">
    Calculate upload costs before committing
  </Card>

  <Card title="createDeposit" icon="upload" href="/sdk/deposit#create-deposit">
    Upload files and create onchain deposit
  </Card>

  <Card title="getSolPrice" icon="dollar-sign" href="/sdk/sol-price">
    Get real-time SOL/USD exchange rate
  </Card>

  <Card title="getUserUploadHistory" icon="clock-rotate-left" href="/sdk/upload-history">
    Fetch all uploads for a wallet address
  </Card>

  <Card title="renewStorageDuration" icon="rotate" href="/sdk/renewal">
    Extend storage duration for existing uploads
  </Card>
</CardGroup>

## Type Safety

The SDK is type-safe. Import types as needed:

```typescript theme={null}
import type {
  Environment,
  UploadResult,
  UploadHistoryResponse,
  DepositFile,
  RenewalResult,
} from '@toju.network/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

### Custom RPC URL (Optional)

By default, the SDK uses public Solana RPC endpoints. For production applications, you should use your own RPC provider (like [Helius](https://helius.dev) or [QuickNode](https://quicknode.com)) to avoid rate limits:

```typescript theme={null}
import { useUpload } from '@toju.network/sol';

// With custom RPC URL
const client = useUpload(
  Environment.mainnet,
  undefined, // API endpoint (optional)
  'https://mainnet.helius-rpc.com/?api-key=YOUR_API_KEY' // Custom RPC URL
);
```

<Warning>
  **Security Note:** If you're using a paid RPC provider, don't expose your API key in frontend code! Instead, create a proxy endpoint on your backend that forwards RPC requests to your provider.
</Warning>

For backend/server-side usage:

```typescript theme={null}
import { Client, Environment } from '@toju.network/sol';

const client = new Client({
  environment: Environment.mainnet,
  rpcUrl: process.env.SOLANA_RPC_URL, // From environment variable
});
```

## Common Patterns

### Checking Balance Before Upload

```typescript theme={null}
import { useUpload } from '@toju.network/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

```typescript theme={null}
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)

```typescript theme={null}
const result = await client.createDeposit({
  file,
  durationDays: 30,
  payer: publicKey,
  userEmail: 'user@example.com', // Optional: for expiration warnings
  signTransaction,
});
```

## Vite Configuration

If using Vite, you'll need Node.js polyfills for the browser:

```bash theme={null}
pnpm add -D vite-plugin-node-polyfills
```

Then update your `vite.config.ts`:

```typescript theme={null}
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'),
    },
  },
})
```

<Info>
  This prevents `ReferenceError: process is not defined` and provides necessary Node.js polyfills for Solana Web3.js to work in the browser.
</Info>

## Next Steps

<CardGroup cols={2}>
  <Card title="Upload Files" icon="cloud-arrow-up" href="/sdk/deposit">
    Learn how to upload files and create deposits
  </Card>

  <Card title="View History" icon="list" href="/sdk/upload-history">
    Fetch and display upload history
  </Card>

  <Card title="Renew Storage" icon="arrows-rotate" href="/sdk/renewal">
    Extend storage duration
  </Card>

  <Card title="Core Concepts" icon="book" href="/concepts/storage-payments">
    Understand how it works
  </Card>
</CardGroup>

## Support

<CardGroup cols={2}>
  <Card title="GitHub Issues" icon="github" href="https://github.com/tojunetwork/afara/issues">
    Report bugs or request features
  </Card>

  <Card title="SOL Package" icon="npm" href="https://www.npmjs.com/package/@toju.network/sol">
    View on npm
  </Card>

  <Card title="FIL Package" icon="npm" href="https://www.npmjs.com/package/@toju.network/fil">
    View on npm
  </Card>
</CardGroup>