Create Deposit

Overview

The createDeposit method uploads files to decentralized storage and creates a payment record on the Solana blockchain.

Estimate Cost First

Before uploading, get a cost estimate:

const estimate = await client.estimateStorageCost(files, durationDays);

console.log(`Cost: ${estimate.costInSOL} SOL (~$${estimate.costInUSD})`);
console.log(`Total size: ${estimate.totalSizeInMB} MB`);

Response

{
  costInSOL: number;      // Cost in SOL
  costInUSD: number;      // Approximate USD value
  totalSizeInMB: number;  // Total file size
  durationDays: number;   // Storage duration
}

Always estimate costs before uploading to avoid transaction failures due to insufficient balance.

Create Deposit

Upload files and create a deposit on-chain:

const result = await client.createDeposit({
  file,                    // File or File[]
  durationDays: 30,        // Storage duration
  payer: publicKey,        // Wallet public key
  userEmail: '[email protected]', // Optional: for expiration warnings
  signTransaction: async (tx) => {
    return await signTransaction(tx);
  },
});

Parameters

File | File[]

required

Single file or array of files to upload

number

required

Storage duration in days (minimum: 7)

PublicKey

required

Solana wallet public key for payment

Function

required

Async function to sign the transaction

async (tx: Transaction) => Promise<Transaction>

string

Optional email for expiration reminders (sent 7 days before)

Response

boolean

Whether the upload succeeded

string

Content identifier for the uploaded file(s)

string

Solana transaction signature

string

IPFS gateway URL to access the file

string

Human-readable success message

string

Error message (only if success is false)

Complete Example

import { useDeposit } from '@toju.network/sol';
import { useWallet } from '@solana/wallet-adapter-react';
import { useState } from 'react';
import { toast } from 'sonner';

function UploadComponent() {
  const client = useDeposit('testnet');
  const { publicKey, signTransaction } = useWallet();
  const [files, setFiles] = useState<File[]>([]);
  const [duration, setDuration] = useState(30);
  const [email, setEmail] = useState('');

  const handleUpload = async () => {
    if (!publicKey || !signTransaction) {
      toast.error('Please connect your wallet');
      return;
    }

    // 1. Estimate cost
    const estimate = await client.estimateStorageCost(files, duration);
    console.log(`Estimated cost: ${estimate.costInSOL} SOL`);

    // 2. Check balance
    const balance = await connection.getBalance(publicKey);
    if (balance < estimate.costInSOL * LAMPORTS_PER_SOL) {
      toast.error('Insufficient balance');
      return;
    }

    // 3. Create deposit
    const toastId = toast.loading('Uploading to IPFS...');

    try {
      const result = await client.createDeposit({
        file: files.length === 1 ? files[0] : files,
        durationDays: duration,
        payer: publicKey,
        userEmail: email || undefined,
        signTransaction: async (tx) => {
          toast.loading('Please sign the transaction...', { id: toastId });
          return await signTransaction(tx);
        },
      });

      if (result.success) {
        toast.success(
          `Upload successful! CID: ${result.cid}`,
          { id: toastId, duration: 5000 }
        );
        
        console.log('View file:', result.url);
        console.log('Transaction:', result.signature);
      } else {
        toast.error(result.error, { id: toastId });
      }
    } catch (error) {
      toast.error('Upload failed', { id: toastId });
      console.error(error);
    }
  };

  return (
    <div>
      <input 
        type="file" 
        multiple 
        onChange={(e) => setFiles(Array.from(e.target.files || []))} 
      />
      <input
        type="number"
        value={duration}
        onChange={(e) => setDuration(Number(e.target.value))}
        min={7}
      />
      <input
        type="email"
        placeholder="Email (optional)"
        value={email}
        onChange={(e) => setEmail(e.target.value)}
      />
      <button onClick={handleUpload}>
        Upload
      </button>
    </div>
  );
}

Single vs Multiple Files

Single File

const file = new File(['content'], 'document.pdf');

const result = await client.createDeposit({
  file,  // Single File object
  durationDays: 30,
  payer: publicKey,
  signTransaction,
});

// Access at: result.url (direct file link)

Multiple Files

const files = [
  new File(['content1'], 'file1.txt'),
  new File(['content2'], 'file2.txt'),
];

const result = await client.createDeposit({
  file: files,  // File array
  durationDays: 30,
  payer: publicKey,
  signTransaction,
});

// Access at:
// result.url             → Directory listing
// result.url/file1.txt   → Individual file

Multiple files are packaged as a directory on IPFS. Pinata returns a single root CID for the directory. See Content Identifiers for details.

Error Handling

Common errors and solutions:

Insufficient Balance

Error: Transaction fails due to insufficient SOLSolution: Check balance before uploading using estimateStorageCost

const estimate = await client.estimateStorageCost(files, duration);
const balance = await connection.getBalance(publicKey);

if (balance / LAMPORTS_PER_SOL < estimate.costInSOL) {
  alert('You need more SOL');
}

User Rejected Transaction

Error: User cancels the wallet signature requestSolution: Catch the error and show appropriate message

try {
  const result = await client.createDeposit({...});
} catch (error) {
  if (error.message.includes('User rejected')) {
    toast.info('Transaction cancelled');
  }
}

Network Error

Error: Failed to upload to IPFS or confirm transactionSolution: Implement retry logic or ask user to try again

const maxRetries = 3;
let attempt = 0;

while (attempt < maxRetries) {
  try {
    const result = await client.createDeposit({...});
    if (result.success) break;
  } catch (error) {
    attempt++;
    if (attempt === maxRetries) throw error;
    await new Promise(r => setTimeout(r, 2000)); // Wait 2s
  }
}

File Too Large

Error: Browser runs out of memory processing large filesSolution: Limit file size or implement chunked uploads

const MAX_SIZE = 100 * 1024 * 1024; // 100 MB

if (file.size > MAX_SIZE) {
  toast.error('File too large. Max 100 MB');
  return;
}

Transaction Flow

What happens when you call createDeposit:

Pin to IPFS

Server receives your files and pins them to IPFS. The server returns the authoritative CID for your content.

Build Transaction

A Solana transaction is built using that CID along with the payment amount and duration

Sign Transaction

Your signTransaction callback is invoked

Submit to Network

Transaction is submitted to Solana blockchain

Wait for Confirmation

SDK waits for transaction confirmation

Confirm Upload

Server marks the upload active in the database, linking the transaction signature to the pinned CID

Return Result

CID, transaction signature, and gateway URL are returned to your app

Best Practices

Always Estimate First

Check costs before uploading to avoid failed transactions

Show Progress

Use loading states and toasts for better UX

Handle Errors Gracefully

Provide clear error messages to users

Verify Balance

Ensure sufficient SOL before initiating upload

Upload History

View past uploads

Storage Renewal

Extend storage duration

CID Computation

How CIDs are computed

Storage Payments

Payment mechanics

​Overview

​Estimate Cost First

​Response

​Create Deposit

​Parameters

​Response

​Complete Example

​Single vs Multiple Files

​Single File

​Multiple Files

​Error Handling

​Transaction Flow

​Best Practices

Always Estimate First

Show Progress

Handle Errors Gracefully

Verify Balance

​Related

Upload History

Storage Renewal

CID Computation

Storage Payments

Overview

Estimate Cost First

Response

Create Deposit

Parameters

Response

Complete Example

Single vs Multiple Files

Single File

Multiple Files

Error Handling

Transaction Flow

Best Practices

Related