Skip to main content
OnchainDB supports uploading and retrieving binary files like images, videos, and documents.

Upload Blob

// Browser upload with File object
const fileInput = document.querySelector('input[type="file"]');
const file = fileInput.files[0];

const uploadResult = await client.uploadBlob({
  collection: 'avatars',
  blob: file,
  metadata: {
    user_address: 'celestia1abc...',
    uploaded_by: 'alice',
    is_primary: true
  },
  payment_tx_hash: 'ABC123...',
  user_address: 'celestia1abc...',
  broker_address: 'celestia1broker...',
  amount_utia: 100000
});

console.log('Blob ID:', uploadResult.blob_id);

// Wait for upload completion
const task = await client.waitForTaskCompletion(uploadResult.ticket_id);

Retrieve Blob

// Browser: Display image
const blob = await client.retrieveBlob({
  collection: 'avatars',
  blob_id: 'blob_abc123'
});

const imageUrl = URL.createObjectURL(blob);
document.querySelector('img').src = imageUrl;

// Node.js: Save file
const buffer = await client.retrieveBlob({
  collection: 'documents',
  blob_id: 'blob_xyz789'
});
fs.writeFileSync('./downloaded-file.pdf', buffer);

Query Blob Metadata

Query metadata without downloading the actual blob:
const userBlobs = await client.queryBlobMetadata('avatars', {
  user_address: 'celestia1abc...'
});

for (const blob of userBlobs) {
  console.log('Blob ID:', blob.blob_id);
  console.log('Size:', blob.size_bytes);
  console.log('Type:', blob.content_type);
}

Complete Example: Avatar Upload

async function uploadAvatar(file: File, userAddress: string) {
  // Get cost estimate
  const sizeKb = Math.ceil(file.size / 1024);
  const quote = await client.getPricingQuote({
    app_id: 'my_app',
    operation_type: 'write',
    size_kb: sizeKb,
    collection: 'avatars'
  });

  console.log(`Upload will cost ${quote.total_cost} TIA`);

  // Execute payment
  const paymentTx = await wallet.sendTokens(
    quote.brokerAddress,
    quote.total_cost
  );

  // Upload blob
  const uploadResult = await client.uploadBlob({
    collection: 'avatars',
    blob: file,
    metadata: {
      user_address: userAddress,
      is_primary: true,
      uploaded_at: new Date().toISOString()
    },
    payment_tx_hash: paymentTx.transactionHash,
    user_address: userAddress,
    broker_address: quote.brokerAddress,
    amount_utia: quote.total_cost_utia
  });

  // Wait for confirmation
  await client.waitForTaskCompletion(uploadResult.ticket_id);

  return uploadResult.blob_id;
}

Supported File Types

OnchainDB blob storage supports any binary file type including:
  • Images (PNG, JPG, GIF, WebP, SVG)
  • Videos (MP4, WebM)
  • Documents (PDF, DOCX)
  • Audio (MP3, WAV)
  • Archives (ZIP, TAR)

Size Limits

Maximum blob size is 2MB per file. For larger files, consider:
  • Compressing images before upload
  • Splitting large files into chunks
  • Using external storage with OnchainDB for metadata

Next Steps