Skip to main content
OnchainDB supports async operations with ticket-based status tracking for long-running operations.

Task Status Flow

Getting Task Tickets

When waitForConfirmation is false, operations return immediately with a task ticket:
const response = await client.store(
  { collection: 'large_dataset', data: largeData },
  paymentCallback,
  false // Don't wait for confirmation
);

console.log('Task ticket:', response.ticket_id);

Check Task Status

const status = await client.getTaskStatus(ticketId);
console.log('Current status:', status.status);

Wait for Task Completion

// Wait for task to complete
const task = await client.waitForTaskCompletion(ticketId);
console.log('Task completed:', task.status);

// With custom poll interval and max wait time
const task = await client.waitForTaskCompletion(
  ticketId,
  2000,    // Poll every 2 seconds
  300000   // Max wait 5 minutes
);

Task Status Types

StatusDescription
PendingTask queued, waiting to start
PaymentBroadcastPayment transaction sent
PaymentConfirmingWaiting for payment confirmation
PaymentConfirmedPayment confirmed on-chain
StoringDataWriting data to blockchain
CompletedTask finished successfully
FailedTask failed with error

Get User Tasks

Retrieve all tasks for a specific user:
const userTasks = await client.getUserTasks('celestia1...');
console.log(`User has ${userTasks.total_tasks} tasks`);

userTasks.tasks.forEach(task => {
  console.log(`Task ${task.ticket_id}: ${task.status}`);
});

Polling Pattern

async function pollTaskStatus(ticketId: string) {
  const maxAttempts = 30;
  const pollInterval = 2000;

  for (let attempt = 0; attempt < maxAttempts; attempt++) {
    const status = await client.getTaskStatus(ticketId);

    if (status.status === 'Completed') {
      return { success: true, data: status };
    }

    if (typeof status.status === 'object' && 'Failed' in status.status) {
      return { success: false, error: status.status.Failed.error };
    }

    console.log(`Attempt ${attempt + 1}: ${status.status}`);
    await new Promise(resolve => setTimeout(resolve, pollInterval));
  }

  return { success: false, error: 'Timeout waiting for task completion' };
}

Wait for Transaction Confirmation

For direct transaction tracking:
await client.waitForConfirmation(
  'TXHASH123...',
  60000 // Max wait 60 seconds
);

Next Steps