Skip to main content
OnchainDB SDK provides familiar Prisma-style helper methods for common document operations.

Understanding Append-Only Storage

OnchainDB uses append-only storage on a Data Availability layer. This differs from traditional databases:
OperationTraditional DBOnchainDB
CreateInserts new rowAppends a new record with unique ID and timestamp
ReadReturns current dataReturns latest version by timestamp
UpdateModifies existing rowAppends NEW record with same ID and newer timestamp
DeleteRemoves rowAppends record with deleted: true (soft delete)

Benefits of Append-Only

  • Complete audit trail - All historical versions are preserved on-chain
  • Immutable history - Past states cannot be altered
  • Blockchain verifiability - Every change is recorded on-chain

Implications

  • Storage grows with each “update” (new record appended)
  • Historical versions can be queried if needed
  • Data is never physically removed from the blockchain

Available Methods

MethodDescription
createDocument()Create a new document with auto ID/timestamps
findUnique()Find a single document by field
findMany()Find multiple documents with filters
updateDocument()Update a document (appends new version)
upsertDocument()Create or update a document
deleteDocument()Soft delete a document
countDocuments()Count matching documents

Quick Example

import { createClient } from '@onchaindb/sdk';

const client = createClient({
  endpoint: 'https://api.onchaindb.io',
  appId: 'my-app',
  appKey: 'your-app-key'
});

// Create
const user = await client.createDocument(
  'users',
  { email: 'alice@example.com', name: 'Alice', active: true },
  paymentProof
);
console.log('Created:', user.id);

// Read
const found = await client.findUnique('users', { email: 'alice@example.com' });
console.log('Found:', found?.name);

// Update
const updated = await client.updateDocument(
  'users',
  { email: 'alice@example.com' },
  { name: 'Alice Smith' },
  paymentProof
);
console.log('Updated:', updated?.name);

// Delete
const deleted = await client.deleteDocument(
  'users',
  { email: 'alice@example.com' },
  paymentProof
);
console.log('Deleted:', deleted);

Payment Proof Structure

All write operations require a payment proof:
const paymentProof = {
  payment_tx_hash: 'ABC123...',
  user_address: 'celestia1...',
  broker_address: 'celestia1broker...',
  amount_utia: 100000
};

Next Steps