@onchaindb/sdk 0.4.0 → 0.4.2

package/src/client.ts

@@ -0,0 +1,1856 @@
+import axios, {AxiosError, AxiosInstance} from 'axios';
+import {EventEmitter} from 'eventemitter3';
+import {
+    BlobMetadata,
+    CreateCollectionResult,
+    IndexRequest,
+    IndexResponse,
+    OnChainDBConfig,
+    OnChainDBError,
+    PricingQuoteRequest,
+    PricingQuoteResponse,
+    RelationRequest,
+    RelationResponse,
+    RetrieveBlobRequest,
+    SimpleCollectionSchema,
+    SimpleFieldDefinition,
+    StoreRequest,
+    StoreResponse,
+    SyncCollectionResult,
+    TaskInfo,
+    TransactionError,
+    TransactionEvents,
+    UploadBlobRequest,
+    UploadBlobResponse,
+    ValidationError
+} from './types';
+
+// Import query builder components
+// Import database management
+import {createDatabaseManager, DatabaseManager} from './database';
+import {LogicalOperator, QueryBuilder, QueryResponse} from "./query-sdk";
+
+// Import x402 utilities
+import {
+    buildFacilitatorPaymentPayload,
+    buildPaymentPayload,
+    encodePaymentHeader,
+    isFacilitatorPaymentResult,
+    parseX402Response,
+    requirementToQuote,
+    selectPaymentOption,
+    X402FacilitatorPaymentResult,
+    X402PaymentCallbackResult,
+    X402PaymentResult,
+    X402Quote,
+} from './x402';
+
+/**
+ * OnChainDB TypeScript SDK
+ *
+ * Provides a complete interface for storing and querying data on OnChainDB,
+ * built on Celestia blockchain with automatic transaction management.
+ *
+ * @example
+ * ```typescript
+ * // Initialize with app key (for writes) and user key (for Auto-Pay)
+ * const db = new OnChainDBClient({
+ *   endpoint: 'http://localhost:9092',
+ *   appId: 'app_abc123',
+ *   appKey: 'app_xxx...', // Required for write operations
+ *   userKey: 'user_yyy...' // Optional: enables Auto-Pay for reads/writes
+ * });
+ *
+ * // Store data (requires appKey)
+ * const result = await db.store({
+ *   data: [{ message: 'Hello OnChainDB!', user: 'alice' }],
+ *   collection: 'messages'
+ * });
+ *
+ * // Query data (userKey enables Auto-Pay if authz granted)
+ * const messages = await db.query({ collection: 'messages' });
+ *
+ * // Backwards compatible: legacy apiKey maps to appKey
+ * const legacyDb = new OnChainDBClient({
+ *   endpoint: 'http://localhost:9092',
+ *   apiKey: 'app_xxx...' // Still works, maps to appKey
+ * });
+ * ```
+ */
+export class OnChainDBClient extends EventEmitter<TransactionEvents> {
+    /**
+     * Base fields that are automatically indexed when useBaseFields is true
+     */
+    private static readonly BASE_FIELDS: Record<string, SimpleFieldDefinition> = {
+        id: {type: 'string', index: true, unique: true},
+        createdAt: {type: 'date', index: true},
+        updatedAt: {type: 'date', index: true},
+        deletedAt: {type: 'date', index: true}
+    };
+    private http: AxiosInstance;
+    private config: Required<Omit<OnChainDBConfig, 'appId'>> & { appId?: string; appKey?: string; userKey?: string };
+    private _database?: DatabaseManager;
+
+    constructor(config: OnChainDBConfig) {
+        super();
+
+        // Support legacy apiKey for backwards compatibility (maps to appKey)
+        const appKey = config.appKey || '';
+        const userKey = config.userKey || '';
+
+        this.config = {
+            endpoint: config.endpoint,
+            apiKey: appKey, // Keep for backwards compat, but maps to appKey
+            appKey: appKey,
+            userKey: userKey,
+            appId: config.appId || undefined,
+            timeout: config.timeout || 30000,
+            retryCount: config.retryCount || 3,
+            retryDelay: config.retryDelay || 1000
+        };
+
+        // Build headers with both keys if provided
+        const headers: Record<string, string> = {
+            'Content-Type': 'application/json'
+        };
+
+        if (appKey) {
+            headers['X-App-Key'] = appKey;
+        }
+
+        if (config.apiKey) {
+            headers['X-Api-Key'] = config.apiKey;
+        }
+
+
+        if (userKey) {
+            headers['X-User-Key'] = userKey;
+        }
+
+        this.http = axios.create({
+            baseURL: this.config.endpoint,
+            timeout: this.config.timeout,
+            headers
+        });
+    }
+
+    /**
+     * Get database manager instance for collection and index management
+     *
+     * @param appId - Application ID for database operations
+     * @returns DatabaseManager instance
+     *
+     * @example
+     * ```typescript
+     * const db = client.database('app_12345');
+     *
+     * // Create collection with schema
+     * await db.createCollection('users', {
+     *   fields: {
+     *     name: { type: 'string', required: true },
+     *     email: { type: 'string', unique: true }
+     *   }
+     * });
+     *
+     * // Create index
+     * await db.createIndex({
+     *   name: 'users_email_index',
+     *   collection: 'users',
+     *   field_name: 'email',
+     *   index_type: 'btree',
+     *   options: { unique: true }
+     * });
+     * ```
+     */
+    database(appId: string): DatabaseManager {
+        if (!this._database || this._database['appId'] !== appId) {
+            this._database = createDatabaseManager(
+                this.http,
+                this.config.endpoint,
+                appId,
+                this.config.apiKey
+            );
+        }
+        return this._database;
+    }
+
+    /**
+     * Handle 402 Payment Required response (x402 protocol)
+     *
+     * Supports two payment flows:
+     * 1. Celestia native: User broadcasts tx, returns txHash
+     * 2. Facilitator (EVM/Solana): User signs authorization, server sends to facilitator
+     *
+     * @param response - The 402 response from the server
+     * @param paymentCallback - Callback to handle payment (user signs tx or authorization)
+     * @param finalRequest - The original request to retry after payment
+     * @param waitForConfirmation - Whether to wait for blockchain confirmation
+     * @returns Promise resolving to the operation result
+     */
+    async handleX402(
+        response: { data: any },
+        paymentCallback: ((quote: X402Quote) => Promise<X402PaymentCallbackResult>) | undefined,
+        finalRequest: any,
+        waitForConfirmation: boolean
+    ): Promise<any> {
+        console.log('[x402] Received 402 Payment Required');
+
+        // Parse x402 response
+        let x402Response;
+        try {
+            x402Response = parseX402Response(response.data);
+        } catch (e) {
+            throw new OnChainDBError(
+                `Invalid x402 response: ${e instanceof Error ? e.message : String(e)}`,
+                'PAYMENT_ERROR',
+                402
+            );
+        }
+
+        // Select payment option (default to first/native)
+        const requirement = selectPaymentOption(x402Response.accepts);
+
+        // Convert to quote format for callback
+        const quote = requirementToQuote(requirement, x402Response.accepts);
+
+        console.log('[x402] Quote:', {
+            quoteId: quote.quoteId,
+            amount: quote.amountRaw,
+            token: quote.tokenSymbol,
+            network: quote.network,
+            chainType: quote.chainType,
+            paymentMethod: quote.paymentMethod,
+        });
+
+        // Call payment callback if provided
+        if (!paymentCallback) {
+            throw new OnChainDBError(
+                'Payment required but no payment callback provided. Please provide a payment callback to handle x402.',
+                'PAYMENT_REQUIRED',
+                402,
+                quote
+            );
+        }
+
+        console.log('[x402] Calling payment callback...');
+        const payment = await paymentCallback(quote);
+
+        // Build x402 payment payload based on payment type
+        let x402Payload;
+        if (isFacilitatorPaymentResult(payment)) {
+            console.log('[x402] Facilitator payment - sending authorization to server');
+            const facilitatorPayment = payment as X402FacilitatorPaymentResult;
+
+            // IMPORTANT: Find the requirement that matches the payment result's network
+            // The payment callback may have selected a different network than the default
+            const selectedRequirement = x402Response.accepts.find(
+                (req) => req.network === facilitatorPayment.network
+            );
+
+            if (!selectedRequirement) {
+                throw new OnChainDBError(
+                    `Payment callback returned network '${facilitatorPayment.network}' but no matching payment option found`,
+                    'PAYMENT_ERROR'
+                );
+            }
+
+            console.log('[x402] Using payment option for network:', selectedRequirement.network);
+
+            if (facilitatorPayment.evmAuthorization) {
+                x402Payload = buildFacilitatorPaymentPayload(selectedRequirement, {
+                    type: 'evm',
+                    signature: facilitatorPayment.evmAuthorization.signature,
+                    authorization: facilitatorPayment.evmAuthorization.authorization,
+                });
+            } else if (facilitatorPayment.solanaAuthorization) {
+                x402Payload = buildFacilitatorPaymentPayload(selectedRequirement, {
+                    type: 'solana',
+                    transaction: facilitatorPayment.solanaAuthorization.transaction,
+                });
+            } else {
+                throw new OnChainDBError(
+                    'Facilitator payment missing authorization data',
+                    'PAYMENT_ERROR'
+                );
+            }
+        } else {
+            console.log('[x402] Native payment - tx hash:', payment.txHash);
+            x402Payload = buildPaymentPayload(requirement, payment);
+        }
+
+        const encodedPayment = encodePaymentHeader(x402Payload);
+
+        console.log('[x402] Retrying with X-PAYMENT header...');
+
+        const retryResponse = await this.http.post('/store', finalRequest, {
+            headers: {
+                'X-PAYMENT': encodedPayment
+            }
+        });
+
+        console.log('[x402] Server response after payment:', retryResponse.data);
+        const serverResult = retryResponse.data;
+
+        // Continue with ticket polling
+        if (serverResult.ticket_id) {
+            if (waitForConfirmation) {
+                const taskInfo = await this.waitForTaskCompletion(serverResult.ticket_id);
+                // Extract result from task
+                if (taskInfo.result && taskInfo.result.results && taskInfo.result.results.length > 0) {
+                    const firstResult = taskInfo.result.results[0];
+                    return {
+                        id: firstResult.id,
+                        block_height: firstResult.celestia_height || 0,
+                        transaction_hash: firstResult.blob_id || '',
+                        celestia_height: firstResult.celestia_height || 0,
+                        namespace: firstResult.namespace || '',
+                        confirmed: firstResult.celestia_height > 0
+                    };
+                }
+            } else {
+                // Return ticket without waiting
+                return {
+                    id: serverResult.ticket_id,
+                    block_height: 0,
+                    transaction_hash: '',
+                    celestia_height: 0,
+                    namespace: '',
+                    confirmed: false,
+                    ticket_id: serverResult.ticket_id
+                } as StoreResponse;
+            }
+        }
+
+        throw new OnChainDBError('No ticket_id in response after payment', 'STORE_ERROR');
+    }
+
+    /**
+     * Store data on OnChainDB using the new root-based API with broker payment
+     *
+     * @param request - Store request with root (app::collection) and data array
+     * @param paymentOptions - Payment configuration for broker fees
+     * @param waitForConfirmation - Whether to wait for blockchain confirmation (default: true)
+     * @returns Promise resolving to store response with transaction details
+     *
+     * @example
+     * ```typescript
+     * // With payment (user pays broker fees)
+     * const result = await db.store({
+     *   root: "twitter_app::tweets",
+     *   data: [{ content: 'Hello world!', author: 'alice' }]
+     * }, {
+     *   userWallet: keplrWallet,
+     *   brokerAddress: 'celestia1xyz...'
+     * });
+     *
+     * // Direct submission (broker pays - for backwards compatibility)
+     * const result = await db.store({
+     *   root: "system_logs",
+     *   data: [{ level: 'info', message: 'App started' }]
+     * });
+     * ```
+     */
+    async store(
+        request: StoreRequest,
+        paymentCallback?: (quote: X402Quote) => Promise<X402PaymentResult>,
+        waitForConfirmation: boolean = true
+    ): Promise<StoreResponse> {
+        this.validateStoreRequest(request);
+        const resolvedRequest = {
+            ...request,
+            root: this.resolveRoot(request)
+        };
+        try {
+            // Build the actual request with resolved root
+
+
+            // Remove collection from the request since we now have root
+            delete resolvedRequest.collection;
+
+
+            // Step 1: Try to store without payment (may get 402)
+            const response = await this.http.post('/store', resolvedRequest);
+
+            // Step 2: Handle 402 Payment Required (x402)
+            if (response.status === 402 && response.data) {
+                const v = await this.handleX402(response, paymentCallback, resolvedRequest, waitForConfirmation);
+
+                if (v) {
+                    return v;
+                }
+            }
+
+            // Step 5: No payment required or legacy flow
+            console.log('Server response:', response.data);
+            const serverResult = response.data;
+
+            // Check if we got an async response with ticket_id (new flow)
+            if (serverResult.ticket_id) {
+                console.log(`🎫 Got ticket ${serverResult.ticket_id}, polling for completion...`);
+
+                // Emit ticket received event
+                this.emit('transaction:queued', {
+                    ticket_id: serverResult.ticket_id,
+                    status: serverResult.status,
+                    message: serverResult.message
+                });
+
+                // Poll for task completion if requested
+                if (waitForConfirmation) {
+                    const taskInfo = await this.waitForTaskCompletion(serverResult.ticket_id);
+
+                    // Extract the actual storage result from the completed task
+                    if (taskInfo.result && taskInfo.result.results && taskInfo.result.results.length > 0) {
+                        const firstResult = taskInfo.result.results[0];
+
+                        // Transform to SDK format
+                        const result: StoreResponse = {
+                            id: firstResult.id,
+                            block_height: firstResult.celestia_height || 0,
+                            transaction_hash: firstResult.blob_id || '',
+                            celestia_height: firstResult.celestia_height || 0,
+                            namespace: firstResult.namespace || '',
+                            confirmed: firstResult.celestia_height > 0
+                        };
+
+                        // Emit completion event
+                        this.emit('transaction:confirmed', {
+                            id: result.id,
+                            status: 'confirmed',
+                            block_height: result.block_height,
+                            transaction_hash: result.transaction_hash,
+                            celestia_height: result.celestia_height
+                        });
+
+                        return result;
+                    } else {
+                        throw new OnChainDBError('Task completed but no storage results found', 'STORE_ERROR');
+                    }
+                } else {
+                    // Return ticket info without waiting
+                    return {
+                        id: serverResult.ticket_id,
+                        block_height: 0,
+                        transaction_hash: '',
+                        celestia_height: 0,
+                        namespace: '',
+                        confirmed: false,
+                        ticket_id: serverResult.ticket_id
+                    } as StoreResponse;
+                }
+            }
+
+            // Legacy response format (if server returns old format)
+            const firstResult = serverResult.results && serverResult.results[0];
+            if (!firstResult) {
+                throw new OnChainDBError('No results returned from server', 'STORE_ERROR');
+            }
+
+            // Transform server response to SDK format
+            const result: StoreResponse = {
+                id: firstResult.id,
+                block_height: firstResult.celestia_height || 0,
+                transaction_hash: firstResult.blob_id || '',
+                celestia_height: firstResult.celestia_height || 0,
+                namespace: firstResult.namespace || '',
+                confirmed: firstResult.celestia_height > 0
+            };
+
+            // Emit appropriate event based on height
+            if (result.block_height === 0) {
+                this.emit('transaction:pending', {
+                    id: result.id,
+                    status: 'pending',
+                    block_height: result.block_height,
+                    transaction_hash: result.transaction_hash
+                });
+            } else {
+                this.emit('transaction:confirmed', {
+                    id: result.id,
+                    status: 'confirmed',
+                    block_height: result.block_height,
+                    transaction_hash: result.transaction_hash,
+                    celestia_height: result.celestia_height
+                });
+            }
+
+            console.log('Transaction result:', result);
+            if (waitForConfirmation && result.block_height === 0) {
+                return await this.waitForConfirmation(result.transaction_hash);
+            }
+
+            return result;
+        } catch (error) {
+            if ((error as AxiosError)?.response) {
+                const err = error as AxiosError;
+                if (err.response?.status === 402 && err?.response?.data) {
+                    const v = await this.handleX402(err.response, paymentCallback, resolvedRequest, waitForConfirmation);
+
+                    if (v) {
+                        return v;
+                    }
+                }
+            }
+
+            const dbError = error instanceof OnChainDBError ? error :
+                new OnChainDBError('Failed to store data', 'STORE_ERROR');
+            this.emit('error', dbError);
+            throw dbError;
+        }
+    }
+
+    /**
+     * Store data and return a promise that resolves when transaction is confirmed
+     *
+     * @param request - Store request
+     * @param paymentOptions - Payment configuration for broker fees
+     * @returns Promise resolving when transaction is confirmed on blockchain
+     */
+    async storeAndConfirm(
+        request: StoreRequest
+    ): Promise<StoreResponse> {
+        return this.store(request, undefined, true);
+    }
+
+    /**
+     * Wait for transaction confirmation
+     *
+     * @param transactionHash - Transaction hash to monitor
+     * @param maxWaitTime - Maximum wait time in milliseconds (default: 5 minutes)
+     * @returns Promise resolving to confirmed transaction
+     */
+    async waitForConfirmation(transactionHash: string, maxWaitTime: number = 300000): Promise<StoreResponse> {
+        const startTime = Date.now();
+        const pollInterval = 3000; // Poll every 3 seconds (same as server)
+
+        console.log(`🔄 Waiting for transaction ${transactionHash} confirmation...`);
+
+        while (Date.now() - startTime < maxWaitTime) {
+            try {
+                // Query Celestia RPC directly to check transaction status
+                const rpcUrl = 'https://celestia-mocha-rpc.publicnode.com:443'; // Default testnet RPC
+                const txUrl = `${rpcUrl}/tx?hash=0x${transactionHash}`;
+
+                console.log(`🔍 Checking transaction status: attempt ${Math.floor((Date.now() - startTime) / pollInterval) + 1}`);
+
+                const response = await axios.get(txUrl);
+
+                if (response.data?.result && response.data.result !== null) {
+                    const txResult = response.data.result;
+                    const height = parseInt(txResult.height);
+
+                    if (height > 0) {
+                        console.log(`✅ Transaction ${transactionHash} confirmed at height ${height}`);
+
+                        const confirmedTx: StoreResponse = {
+                            id: transactionHash, // Use transaction hash as ID for confirmation
+                            namespace: '', // Will be filled by actual usage
+                            block_height: height,
+                            transaction_hash: transactionHash,
+                            celestia_height: height,
+                            confirmed: true
+                        };
+
+                        this.emit('transaction:confirmed', {
+                            id: transactionHash,
+                            status: 'confirmed',
+                            block_height: height,
+                            transaction_hash: transactionHash
+                        });
+                        return confirmedTx;
+                    }
+                }
+
+                // Still pending, wait and retry
+                console.log(`⏳ Transaction still pending, waiting ${pollInterval}ms...`);
+                this.emit('transaction:pending', {
+                    id: transactionHash,
+                    status: 'pending',
+                    block_height: 0,
+                    transaction_hash: transactionHash
+                });
+                await this.sleep(pollInterval);
+
+            } catch (error) {
+                // For 404 or other errors, the transaction might not be confirmed yet
+                if (Date.now() - startTime >= maxWaitTime) {
+                    throw new TransactionError(
+                        `Transaction confirmation timeout after ${maxWaitTime}ms`,
+                        transactionHash
+                    );
+                }
+
+                // Wait and retry for temporary errors
+                console.log(`⚠️ Error checking transaction (will retry): ${error}`);
+                await this.sleep(pollInterval);
+            }
+        }
+
+        throw new TransactionError(
+            `Transaction confirmation timeout after ${maxWaitTime}ms`,
+            transactionHash
+        );
+    }
+
+    /**
+     * Create an index on a collection field
+     *
+     * @param request - Index creation request
+     * @returns Index creation response
+     */
+    async createIndex(request: IndexRequest): Promise<IndexResponse> {
+        try {
+            // Use app-specific index creation endpoint
+            const appId = this.config.appId || 'default';
+            const response = await this.http.post<IndexResponse>(`/api/apps/${appId}/indexes`, request);
+            return response.data;
+        } catch (error) {
+            throw error instanceof OnChainDBError ? error :
+                new OnChainDBError('Failed to create index', 'INDEX_ERROR');
+        }
+    }
+
+    /**
+     * Create a collection with schema-defined indexes
+     *
+     * This is the recommended way to set up a new collection. It creates all
+     * necessary indexes in a single call, including base fields if enabled.
+     *
+     * @param schema - Collection schema definition
+     * @returns Result with created indexes and any warnings
+     *
+     * @example
+     * ```typescript
+     * // Create a users collection with indexes
+     * const result = await db.createCollection({
+     *   name: 'users',
+     *   fields: {
+     *     email: { type: 'string', index: true, unique: true },
+     *     username: { type: 'string', index: true },
+     *     age: { type: 'number' },
+     *     isActive: { type: 'boolean', index: true }
+     *   },
+     *   useBaseFields: true // adds id, createdAt, updatedAt, deletedAt indexes
+     * });
+     *
+     * console.log('Created indexes:', result.indexes);
+     * // Now you can store and query data efficiently
+     * ```
+     */
+    async createCollection(schema: SimpleCollectionSchema): Promise<CreateCollectionResult> {
+        const appId = this.config.appId;
+        if (!appId) {
+            throw new ValidationError('appId must be configured to create collections');
+        }
+
+        const result: CreateCollectionResult = {
+            collection: schema.name,
+            indexes: [],
+            success: true,
+            warnings: []
+        };
+
+        // Merge base fields if enabled (default: true)
+        const allFields: Record<string, SimpleFieldDefinition> = {};
+
+        if (schema.useBaseFields !== false) {
+            Object.assign(allFields, OnChainDBClient.BASE_FIELDS);
+        }
+
+        Object.assign(allFields, schema.fields);
+
+        // Create indexes only for fields marked with index: true
+        for (const [fieldName, fieldDef] of Object.entries(allFields)) {
+            // Skip fields not marked for indexing
+            if (!fieldDef.index) {
+                continue;
+            }
+
+            try {
+                // Map field type to index type
+                const indexType = fieldDef.indexType || this.getDefaultIndexType(fieldDef.type);
+
+                const indexRequest: any = {
+                    name: `${schema.name}_${fieldName}_idx`,
+                    collection: schema.name,
+                    field_name: fieldName,
+                    index_type: indexType,
+                    store_values: true,
+                };
+
+                // Add read pricing if specified
+                if (fieldDef.readPricing) {
+                    indexRequest.read_price_config = {
+                        pricing_model: fieldDef.readPricing.pricePerKb ? 'per_kb' : 'per_access',
+                        price_per_access_tia: fieldDef.readPricing.pricePerAccess,
+                        price_per_kb_tia: fieldDef.readPricing.pricePerKb
+                    };
+                }
+
+                const response = await this.http.post(`/api/apps/${appId}/indexes`, indexRequest);
+
+                // Check if it was an update vs create
+                const wasUpdated = response.data?.updated === true;
+                const hasWarning = response.data?._warning;
+
+                result.indexes.push({
+                    field: fieldName,
+                    type: indexType,
+                    status: wasUpdated ? 'updated' : 'created'
+                });
+
+                if (hasWarning) {
+                    result.warnings!.push(`${fieldName}: ${hasWarning}`);
+                }
+
+            } catch (error) {
+                const errorMsg = error instanceof Error ? error.message : String(error);
+                result.indexes.push({
+                    field: fieldName,
+                    type: fieldDef.indexType || 'btree',
+                    status: 'failed',
+                    error: errorMsg
+                });
+                result.success = false;
+            }
+        }
+
+        return result;
+    }
+
+    /**
+     * Sync collection schema - applies diff on indexes
+     *
+     * Compares the provided schema with existing indexes and:
+     * - Creates missing indexes for new fields with index: true
+     * - Removes indexes for fields no longer in schema or without index: true
+     * - Leaves unchanged indexes intact
+     *
+     * @param schema - Updated collection schema definition
+     * @returns Result with created, removed, and unchanged indexes
+     *
+     * @example
+     * ```typescript
+     * // Initial schema
+     * await db.createCollection({
+     *   name: 'users',
+     *   fields: {
+     *     email: { type: 'string', index: true },
+     *     username: { type: 'string', index: true }
+     *   }
+     * });
+     *
+     * // Later, sync with updated schema (add age index, remove username index)
+     * const result = await db.syncCollection({
+     *   name: 'users',
+     *   fields: {
+     *     email: { type: 'string', index: true },
+     *     username: { type: 'string' }, // index removed
+     *     age: { type: 'number', index: true } // new index
+     *   }
+     * });
+     *
+     * console.log('Created:', result.created);  // [{ field: 'age', type: 'number' }]
+     * console.log('Removed:', result.removed);  // [{ field: 'username', type: 'string' }]
+     * ```
+     */
+    async syncCollection(schema: SimpleCollectionSchema): Promise<SyncCollectionResult> {
+        const appId = this.config.appId;
+        if (!appId) {
+            throw new ValidationError('appId must be configured to sync collections');
+        }
+
+        const result: SyncCollectionResult = {
+            collection: schema.name,
+            created: [],
+            removed: [],
+            unchanged: [],
+            success: true,
+            errors: []
+        };
+
+        // Get existing indexes for this collection
+        let existingIndexes: Array<{ field_name: string; index_type: string; name: string }> = [];
+        try {
+            const response = await this.http.get(`/api/apps/${appId}/collections/${schema.name}/indexes`);
+            existingIndexes = response.data?.indexes || response.data || [];
+        } catch (error) {
+            // Collection might not exist yet, that's okay
+            existingIndexes = [];
+        }
+
+        // Build map of existing indexes by field name
+        const existingByField = new Map<string, { type: string; name: string }>();
+        for (const idx of existingIndexes) {
+            existingByField.set(idx.field_name, {type: idx.index_type, name: idx.name});
+        }
+
+        // Merge base fields if enabled (default: true)
+        const allFields: Record<string, SimpleFieldDefinition> = {};
+        if (schema.useBaseFields !== false) {
+            Object.assign(allFields, OnChainDBClient.BASE_FIELDS);
+        }
+        Object.assign(allFields, schema.fields);
+
+        // Build set of desired indexed fields
+        const desiredIndexedFields = new Set<string>();
+        for (const [fieldName, fieldDef] of Object.entries(allFields)) {
+            if (fieldDef.index) {
+                desiredIndexedFields.add(fieldName);
+            }
+        }
+
+        // Find indexes to create (in desired but not existing)
+        for (const fieldName of desiredIndexedFields) {
+            if (!existingByField.has(fieldName)) {
+                const fieldDef = allFields[fieldName];
+                const indexType = fieldDef.indexType || this.getDefaultIndexType(fieldDef.type);
+
+                try {
+                    const indexRequest: any = {
+                        name: `${schema.name}_${fieldName}_idx`,
+                        collection: schema.name,
+                        field_name: fieldName,
+                        index_type: indexType,
+                        store_values: true,
+                    };
+
+                    // Add unique constraint if specified
+                    if (fieldDef.unique) {
+                        indexRequest.unique_constraint = true;
+                    }
+
+                    if (fieldDef.readPricing) {
+                        indexRequest.read_price_config = {
+                            pricing_model: fieldDef.readPricing.pricePerKb ? 'per_kb' : 'per_access',
+                            price_per_access_tia: fieldDef.readPricing.pricePerAccess,
+                            price_per_kb_tia: fieldDef.readPricing.pricePerKb
+                        };
+                    }
+
+                    await this.http.post(`/api/apps/${appId}/indexes`, indexRequest);
+
+                    result.created.push({
+                        field: fieldName,
+                        type: indexType
+                    });
+                } catch (error) {
+                    const errorMsg = error instanceof Error ? error.message : String(error);
+                    result.errors!.push(`Failed to create index on ${fieldName}: ${errorMsg}`);
+                    result.success = false;
+                }
+            }
+        }
+
+        // Find indexes to remove (existing but not in desired)
+        for (const [fieldName, existing] of existingByField) {
+            if (!desiredIndexedFields.has(fieldName)) {
+                try {
+                    // Index ID format: {collection}_{field_name}_index
+                    const indexId = `${schema.name}_${fieldName}_index`;
+                    await this.http.delete(`/api/apps/${appId}/indexes/${indexId}`);
+                    result.removed.push({
+                        field: fieldName,
+                        type: existing.type
+                    });
+                } catch (error) {
+                    const errorMsg = error instanceof Error ? error.message : String(error);
+                    result.errors!.push(`Failed to remove index on ${fieldName}: ${errorMsg}`);
+                    result.success = false;
+                }
+            }
+        }
+
+        // Track unchanged indexes
+        for (const [fieldName, existing] of existingByField) {
+            if (desiredIndexedFields.has(fieldName)) {
+                result.unchanged.push({
+                    field: fieldName,
+                    type: existing.type
+                });
+            }
+        }
+
+        return result;
+    }
+
+    /**
+     * Get collection info including indexes
+     *
+     * @param collection - Collection name
+     * @returns Collection information
+     */
+    async getCollectionInfo(collection: string): Promise<{ indexes: string[]; recordCount?: number }> {
+        const appId = this.config.appId;
+        if (!appId) {
+            throw new ValidationError('appId must be configured');
+        }
+
+        try {
+            const response = await this.http.get(`/api/apps/${appId}/collections/${collection}`);
+            return response.data;
+        } catch (error) {
+            throw error instanceof OnChainDBError ? error :
+                new OnChainDBError('Failed to get collection info', 'COLLECTION_ERROR');
+        }
+    }
+
+    /**
+     * Create a relation between collections with automatic join optimization
+     *
+     * Creates a one-to-many relation and automatically:
+     * - Creates hash indexes on both parent and child fields for fast joins
+     * - Stores join information in index configs for query optimization
+     * - Enables efficient relationship queries using hash-based joins
+     *
+     * @param request - Relation creation request
+     * @returns Relation creation response with join information
+     *
+     * @example
+     * ```typescript
+     * // Create a user -> tweets relation (one user has many tweets)
+     * const userTweetsRelation = await db.createRelation({
+     *   parent_collection: 'users',
+     *   parent_field: 'address',      // User's unique field
+     *   child_collection: 'tweets',
+     *   child_field: 'author'         // Foreign key in tweets
+     * });
+     *
+     * // Create self-referential relations (tweets -> quote tweets)
+     * const quoteRelation = await db.createRelation({
+     *   parent_collection: 'tweets',
+     *   parent_field: 'id',
+     *   child_collection: 'tweets',
+     *   child_field: 'quote_tweet_id' // References parent tweet
+     * });
+     *
+     * // After creating relations, queries automatically benefit from:
+     * // - Hash indexes for O(1) lookups
+     * // - Join optimization in the query engine
+     * // - Efficient relationship traversal
+     * ```
+     */
+    async createRelation(request: RelationRequest): Promise<RelationResponse> {
+        try {
+            const appId = this.config.appId || 'default';
+            const response = await this.http.post<RelationResponse>(`/api/apps/${appId}/relations`, request);
+            return response.data;
+        } catch (error) {
+            throw error instanceof OnChainDBError ? error :
+                new OnChainDBError('Failed to create relation', 'RELATION_ERROR');
+        }
+    }
+
+    /**
+     * Get health status of OnChainDB service
+     *
+     * @returns Health check response
+     */
+    async health(): Promise<{ status: string; version?: string }> {
+        try {
+            const response = await this.http.get('/');
+            return response.data;
+        } catch (error) {
+            throw new OnChainDBError('Health check failed', 'HEALTH_ERROR');
+        }
+    }
+
+    /**
+     * Get pricing quote for an operation before executing it
+     *
+     * Use this to estimate costs before committing to a store operation,
+     * especially useful for large files or high-volume scenarios.
+     *
+     * @param request - Pricing quote request with app_id, operation type, size, and collection
+     * @returns Pricing quote with detailed cost breakdown
+     *
+     * @example
+     * ```typescript
+     * const quote = await db.getPricingQuote({
+     *   app_id: 'my_app',
+     *   operation_type: 'write',
+     *   size_kb: 50,
+     *   collection: 'users',
+     *   monthly_volume_kb: 1000
+     * });
+     *
+     * console.log(`Total cost: ${quote.total_cost_utia} utia`);
+     * console.log(`Indexing costs:`, quote.indexing_costs_utia);
+     * ```
+     */
+    async getPricingQuote(request: PricingQuoteRequest): Promise<PricingQuoteResponse> {
+        try {
+            const response = await this.http.post('/api/pricing/quote', request);
+            return response.data;
+        } catch (error) {
+            throw error instanceof OnChainDBError ? error :
+                new OnChainDBError('Failed to get pricing quote', 'PRICING_QUOTE_ERROR');
+        }
+    }
+
+    /**
+     * Execute a simple query with basic filtering
+     *
+     * @param request - Simple query request
+     * @returns Query response with records
+     *
+     * @example
+     * ```typescript
+     * const tweets = await db.query({
+     *   collection: 'tweets',
+     *   filters: { author: 'alice' },
+     *   limit: 10
+     * });
+     * ```
+     */
+    async query(request: {
+        collection: string;
+        filters?: Record<string, any>;
+        limit?: number;
+        offset?: number;
+        sort?: string[];
+    }): Promise<QueryResponse> {
+        try {
+            const queryBuilder = this.queryBuilder();
+
+            // Set collection using root building
+            const root = this.resolveRoot(request);
+
+            // Add filters if provided
+            if (request.filters) {
+                queryBuilder.find(builder => {
+                    const conditions = Object.entries(request.filters!).map(([field, value]) =>
+                        LogicalOperator.Condition(builder.field(field).equals(value))
+                    );
+                    return conditions.length === 1 ? conditions[0] : LogicalOperator.And(conditions);
+                });
+            }
+
+            // Set limit and offset
+            if (request.limit) {
+                queryBuilder.limit(request.limit);
+            }
+
+            if (request.offset) {
+                queryBuilder.offset(request.offset);
+            }
+
+            // Execute the query
+            return await queryBuilder.execute();
+
+        } catch (error) {
+            throw error instanceof OnChainDBError ? error :
+                new OnChainDBError('Failed to execute query', 'QUERY_ERROR');
+        }
+    }
+
+    /**
+     * Create a fluent query builder instance
+     *
+     * @returns OnChainQueryBuilder instance for building complex queries
+     *
+     * @example
+     * ```typescript
+     * const results = await db.queryBuilder()
+     *   .find(builder =>
+     *     LogicalOperator.And([
+     *       LogicalOperator.Condition(builder.field('status').equals('published')),
+     *       LogicalOperator.Condition(builder.field('author').equals('alice'))
+     *     ])
+     *   )
+     *   .select(selection =>
+     *     selection.field('title').field('content')
+     *   )
+     *   .limit(10)
+     *   .execute();
+     * ```
+     */
+    queryBuilder(): QueryBuilder {
+        // Wrap Axios instance in AxiosHttpClient for proper x402 support
+        const {AxiosHttpClient} = require('./query-sdk/adapters/HttpClientAdapter');
+        const httpClient = new AxiosHttpClient(this.http);
+        return new QueryBuilder(httpClient, this.config.endpoint, this.config.appId);
+    }
+
+    /**
+     * Create a batch operations instance for this client
+     *
+     * @returns BatchOperations instance
+     *
+     * @example
+     * ```typescript
+     * const batch = db.batch();
+     * const results = await batch.store([...], { concurrency: 5 });
+     * ```
+     */
+    batch() {
+        const {BatchOperations} = require('./batch');
+        return new BatchOperations(this);
+    }
+
+    /**
+     * Find a single document by query (Prisma-style findUnique)
+     * Returns the latest record by metadata (updatedAt or createdAt) if multiple matches.
+     *
+     * @param collection - Collection name to search in
+     * @param where - Query conditions as key-value pairs
+     * @returns Promise resolving to document or null if not found
+     *
+     * @example
+     * ```typescript
+     * const user = await client.findUnique('users', { email: 'alice@example.com' });
+     * if (user) {
+     *   console.log('Found user:', user);
+     * }
+     * ```
+     */
+    async findUnique<T extends Record<string, any>>(
+        collection: string,
+        where: Record<string, any>
+    ): Promise<T | null> {
+        try {
+            let queryBuilder = this.queryBuilder().collection(collection);
+
+            // Add each where condition
+            for (const [field, value] of Object.entries(where)) {
+                queryBuilder = queryBuilder.whereField(field).equals(value);
+            }
+
+            // Execute query and return the latest record by metadata
+            return await queryBuilder.selectAll().executeUnique<T>();
+        } catch (error) {
+            console.error(`findUnique error for ${collection}:`, error);
+            return null;
+        }
+    }
+
+    // ===== PRISMA-LIKE CRUD OPERATIONS =====
+
+    /**
+     * Find multiple documents by query (Prisma-style findMany)
+     *
+     * @param collection - Collection name to search in
+     * @param where - Query conditions as key-value pairs
+     * @param options - Query options (limit, offset, sort)
+     * @returns Promise resolving to array of documents
+     *
+     * @example
+     * ```typescript
+     * const users = await client.findMany('users',
+     *   { active: true },
+     *   { limit: 10, sort: { field: 'createdAt', order: 'desc' } }
+     * );
+     * ```
+     */
+    async findMany<T>(
+        collection: string,
+        where: Record<string, any> = {},
+        options: {
+            limit?: number;
+            offset?: number;
+            sort?: { field: string; order: 'asc' | 'desc' };
+        } = {}
+    ): Promise<T[]> {
+        try {
+            let queryBuilder = this.queryBuilder().collection(collection);
+
+            // Add where conditions
+            for (const [field, value] of Object.entries(where)) {
+                queryBuilder = queryBuilder.whereField(field).equals(value);
+            }
+
+            // Add limit
+            if (options.limit) {
+                queryBuilder = queryBuilder.limit(options.limit);
+            }
+
+            // Add offset
+            if (options.offset) {
+                queryBuilder = queryBuilder.offset(options.offset);
+            }
+
+            const result = await queryBuilder.selectAll().execute();
+
+            if (!result.records) {
+                return [];
+            }
+
+            // Apply sorting if specified (client-side for now)
+            let records = result.records as T[];
+            if (options.sort) {
+                records = records.sort((a: any, b: any) => {
+                    const aVal = a[options.sort!.field];
+                    const bVal = b[options.sort!.field];
+
+                    if (options.sort!.order === 'asc') {
+                        return aVal > bVal ? 1 : -1;
+                    } else {
+                        return aVal < bVal ? 1 : -1;
+                    }
+                });
+            }
+
+            return records;
+        } catch (error) {
+            console.error(`findMany error for ${collection}:`, error);
+            return [];
+        }
+    }
+
+    /**
+     * Create a new document (Prisma-style create)
+     *
+     * @param collection - Collection name
+     * @param data - Document data (without id, createdAt, updatedAt)
+     * @param paymentCallback - x402 payment callback for handling payment
+     * @param options - Optional settings (idGenerator)
+     * @returns Promise resolving to created document
+     *
+     * @example
+     * ```typescript
+     * const user = await client.createDocument('users',
+     *   { email: 'alice@example.com', name: 'Alice' },
+     *   async (quote) => {
+     *     const txHash = await signAndBroadcastPayment(quote);
+     *     return { txHash, network: quote.network, sender: userAddress, chainType: quote.chainType, paymentMethod: quote.paymentMethod };
+     *   }
+     * );
+     * ```
+     */
+    async createDocument<T extends Record<string, any>>(
+        collection: string,
+        data: Omit<T, 'id' | 'createdAt' | 'updatedAt'>,
+        paymentCallback?: (quote: X402Quote) => Promise<X402PaymentResult>,
+        options?: {
+            idGenerator?: () => string;
+        }
+    ): Promise<T> {
+        const document: any = {
+            id: options?.idGenerator ? options.idGenerator() : this.generateId(),
+            ...data,
+            createdAt: new Date().toISOString(),
+            updatedAt: new Date().toISOString(),
+        };
+
+        // Use the store method with x402 payment callback
+        await this.store({
+            collection,
+            data: [document],
+        }, paymentCallback);
+
+        return document as T;
+    }
+
+    /**
+     * Update an existing document (Prisma-style update)
+     *
+     * @param collection - Collection name
+     * @param where - Query conditions to find document
+     * @param data - Partial data to update
+     * @param paymentCallback - x402 payment callback for handling payment
+     * @returns Promise resolving to updated document or null if not found
+     *
+     * @example
+     * ```typescript
+     * const updated = await client.updateDocument('users',
+     *   { email: 'alice@example.com' },
+     *   { name: 'Alice Smith' },
+     *   async (quote) => {
+     *     const txHash = await signAndBroadcastPayment(quote);
+     *     return { txHash, network: quote.network, sender: userAddress, chainType: quote.chainType, paymentMethod: quote.paymentMethod };
+     *   }
+     * );
+     * ```
+     */
+    async updateDocument<T extends Record<string, any>>(
+        collection: string,
+        where: Record<string, any>,
+        data: Partial<T>,
+        paymentCallback?: (quote: X402Quote) => Promise<X402PaymentResult>
+    ): Promise<T | null> {
+        // Fetch current document
+        const current = await this.findUnique<T>(collection, where);
+
+        if (!current) {
+            return null;
+        }
+
+        // Create updated document
+        const updated: any = {
+            ...current,
+            ...data,
+            updatedAt: new Date().toISOString(),
+        };
+
+        // Store updated version with x402 payment callback
+        await this.store({
+            collection,
+            data: [updated],
+        }, paymentCallback);
+
+        return updated as T;
+    }
+
+    /**
+     * Upsert a document (Prisma-style upsert - create or update)
+     *
+     * @param collection - Collection name
+     * @param where - Query conditions to find document
+     * @param create - Data for creating new document
+     * @param update - Data for updating existing document
+     * @param paymentCallback - x402 payment callback for handling payment
+     * @param options - Optional settings (idGenerator)
+     * @returns Promise resolving to created/updated document
+     *
+     * @example
+     * ```typescript
+     * const user = await client.upsertDocument('users',
+     *   { email: 'alice@example.com' },
+     *   { email: 'alice@example.com', name: 'Alice', active: true },
+     *   { active: true },
+     *   async (quote) => {
+     *     const txHash = await signAndBroadcastPayment(quote);
+     *     return { txHash, network: quote.network, sender: userAddress, chainType: quote.chainType, paymentMethod: quote.paymentMethod };
+     *   }
+     * );
+     * ```
+     */
+    async upsertDocument<T extends Record<string, any>>(
+        collection: string,
+        where: Record<string, any>,
+        create: Omit<T, 'id' | 'createdAt' | 'updatedAt'>,
+        update: Partial<T>,
+        paymentCallback?: (quote: X402Quote) => Promise<X402PaymentResult>,
+        options?: {
+            idGenerator?: () => string;
+        }
+    ): Promise<T> {
+        const existing = await this.findUnique<T>(collection, where);
+
+        if (existing) {
+            return (await this.updateDocument<T>(collection, where, update, paymentCallback))!;
+        } else {
+            return await this.createDocument<T>(collection, create, paymentCallback, options);
+        }
+    }
+
+    /**
+     * Soft delete a document by marking it as deleted
+     *
+     * @param collection - Collection name
+     * @param where - Query conditions to find document
+     * @param paymentCallback - x402 payment callback for handling payment
+     * @returns Promise resolving to true if deleted, false if not found
+     *
+     * @example
+     * ```typescript
+     * const deleted = await client.deleteDocument('users',
+     *   { email: 'alice@example.com' },
+     *   async (quote) => {
+     *     const txHash = await signAndBroadcastPayment(quote);
+     *     return { txHash, network: quote.network, sender: userAddress, chainType: quote.chainType, paymentMethod: quote.paymentMethod };
+     *   }
+     * );
+     * ```
+     */
+    async deleteDocument<T extends Record<string, any>>(
+        collection: string,
+        where: Record<string, any>,
+        paymentCallback?: (quote: X402Quote) => Promise<X402PaymentResult>
+    ): Promise<boolean> {
+        const existing = await this.findUnique<T>(collection, where);
+
+        if (!existing) {
+            return false;
+        }
+
+        // Soft delete by marking
+        const deleted: any = {
+            ...existing,
+            deleted: true,
+            updatedAt: new Date().toISOString(),
+        };
+
+        // Store deleted version with x402 payment callback
+        await this.store({
+            collection,
+            data: [deleted],
+        }, paymentCallback);
+
+        return true;
+    }
+
+    /**
+     * Count documents matching criteria
+     * Uses server-side aggregation via QueryBuilder for efficiency.
+     *
+     * @param collection - Collection name
+     * @param where - Query conditions
+     * @returns Promise resolving to count
+     *
+     * @example
+     * ```typescript
+     * const activeUsers = await client.countDocuments('users', { active: true });
+     * console.log(`Active users: ${activeUsers}`);
+     * ```
+     */
+    async countDocuments(collection: string, where: Record<string, any> = {}): Promise<number> {
+        try {
+            let queryBuilder = this.queryBuilder().collection(collection);
+
+            // Add where conditions
+            for (const [field, value] of Object.entries(where)) {
+                queryBuilder = queryBuilder.whereField(field).equals(value);
+            }
+
+            return await queryBuilder.count();
+        } catch (error) {
+            console.error(`countDocuments error for ${collection}:`, error);
+            return 0;
+        }
+    }
+
+    /**
+     * Generate a unique ID for documents (simple base62 implementation)
+     * Override this if you want to use a different ID generation strategy
+     *
+     * @returns Unique ID string
+     */
+    generateId(): string {
+        const chars = '0123456789abcdefghijklmnopqrstuvwxyzABCDEFGHIJKLMNOPQRSTUVWXYZ';
+        let id = '';
+        for (let i = 0; i < 24; i++) {
+            id += chars[Math.floor(Math.random() * chars.length)];
+        }
+        return id;
+    }
+
+    /**
+     * Get task status by ticket ID
+     * @param ticketId - The ticket ID returned from async store operation
+     * @returns Promise resolving to task status information
+     */
+    async getTaskStatus(ticketId: string): Promise<TaskInfo> {
+        try {
+            const response = await this.http.get(`/task/${ticketId}`);
+            return response.data;
+        } catch (error) {
+            throw error instanceof OnChainDBError ? error :
+                new OnChainDBError('Failed to get task status', 'TASK_STATUS_ERROR');
+        }
+    }
+
+    /**
+     * Poll task status until completion
+     * @param ticketId - The ticket ID to monitor
+     * @param pollInterval - Polling interval in milliseconds (default: 2000ms)
+     * @param maxWaitTime - Maximum wait time in milliseconds (default: 10 minutes)
+     * @returns Promise resolving when task completes
+     */
+    async waitForTaskCompletion(ticketId: string, pollInterval: number = 2000, maxWaitTime: number = 600000): Promise<TaskInfo> {
+        const startTime = Date.now();
+
+        console.log(`🔄 Waiting for task ${ticketId} to complete...`);
+
+        while (Date.now() - startTime < maxWaitTime) {
+            try {
+                const taskInfo = await this.getTaskStatus(ticketId);
+
+                // Log task status with more detail
+                if (typeof taskInfo.status === 'object') {
+                    console.log(`📊 Task ${ticketId} status:`, JSON.stringify(taskInfo.status));
+                } else {
+                    console.log(`📊 Task ${ticketId} status: ${taskInfo.status}`);
+                }
+
+                // Check if task is completed
+                if (taskInfo.status === 'Completed') {
+                    console.log(`✅ Task ${ticketId} completed successfully`);
+                    return taskInfo;
+                }
+
+                // Check if task failed
+                if (typeof taskInfo.status === 'object' && 'Failed' in taskInfo.status) {
+                    const error = (taskInfo.status as { Failed: { error: string } }).Failed.error;
+                    console.error(`🚫 Task ${ticketId} failed: ${error}`);
+                    throw new OnChainDBError(`Task failed: ${error}`, 'TASK_FAILED');
+                }
+
+                // Check for any other error-like statuses
+                if (typeof taskInfo.status === 'string' && taskInfo.status.toLowerCase().includes('error')) {
+                    console.error(`🚫 Task ${ticketId} has error status: ${taskInfo.status}`);
+                    throw new OnChainDBError(`Task error: ${taskInfo.status}`, 'TASK_FAILED');
+                }
+
+                // Task still in progress, wait and check again
+                await this.sleep(pollInterval);
+
+            } catch (error) {
+                console.error(`❌ Error polling task ${ticketId}:`, error);
+
+                // Check if this is a permanent error (like 404, 400, etc.) that shouldn't be retried
+                if (error instanceof OnChainDBError) {
+                    // OnChainDB errors with specific codes should stop polling
+                    if (error.code === 'TASK_FAILED' || error.statusCode === 404 || error.statusCode === 400) {
+                        console.error(`🚫 Stopping polling due to permanent error: ${error.message}`);
+                        throw error;
+                    }
+                }
+
+                // For network/temporary errors, check if we've exceeded max wait time
+                if (Date.now() - startTime >= maxWaitTime) {
+                    throw new OnChainDBError(
+                        `Task completion timeout after ${maxWaitTime}ms. Last error: ${error instanceof Error ? error.message : String(error)}`,
+                        'TASK_TIMEOUT'
+                    );
+                }
+
+                // For temporary errors (network issues, 5xx), wait and retry
+                console.warn(`⚠️  Temporary error polling task ${ticketId}, retrying in ${pollInterval}ms...`);
+                await this.sleep(pollInterval);
+            }
+        }
+
+        throw new OnChainDBError(
+            `Task completion timeout after ${maxWaitTime}ms`,
+            'TASK_TIMEOUT'
+        );
+    }
+
+    /**
+     * Upload a blob (binary file) to OnChainDB with optional custom metadata fields
+     *
+     * Supports images, videos, documents, and any binary data up to 2MB.
+     * Automatically handles multipart/form-data upload and returns a ticket for tracking.
+     *
+     * @param request - Blob upload request with file, metadata, and payment details
+     * @returns Promise resolving to upload response with ticket_id and blob_id
+     *
+     * @example
+     * ```typescript
+     * // Browser upload with File object
+     * const file = document.querySelector('input[type="file"]').files[0];
+     *
+     * const uploadResult = await client.uploadBlob({
+     *   collection: 'avatars',
+     *   blob: file,
+     *   metadata: {
+     *     uploaded_by: 'alice',
+     *     is_primary: true
+     *   }
+     * }, async (quote) => {
+     *   const txHash = await signAndBroadcastPayment(quote);
+     *   return { txHash, network: quote.network, sender: userAddress, chainType: quote.chainType, paymentMethod: quote.paymentMethod };
+     * });
+     *
+     * console.log('Blob ID:', uploadResult.blob_id);
+     * console.log('Track upload:', uploadResult.ticket_id);
+     *
+     * // Wait for upload completion
+     * const task = await client.waitForTaskCompletion(uploadResult.ticket_id);
+     * console.log('Upload complete!', task);
+     * ```
+     */
+    async uploadBlob(
+        request: UploadBlobRequest,
+        paymentCallback?: (quote: X402Quote) => Promise<X402PaymentResult>
+    ): Promise<UploadBlobResponse> {
+        try {
+            const appId = this.config.appId;
+            if (!appId) {
+                throw new ValidationError('appId must be configured to upload blobs');
+            }
+
+            // Create FormData for multipart upload
+            const formData = new FormData();
+
+            // Append blob file
+            formData.append('blob', request.blob);
+
+            // Append metadata as JSON string
+            if (request.metadata) {
+                formData.append('metadata', JSON.stringify(request.metadata));
+            }
+
+            // First request without payment to get 402 if payment required
+            const uploadWithHeaders = async (headers: Record<string, string> = {}) => {
+                return await this.http.post<UploadBlobResponse>(
+                    `/api/apps/${appId}/blobs/${request.collection}`,
+                    formData,
+                    {
+                        headers: {
+                            'Content-Type': 'multipart/form-data',
+                            'X-App-Key': this.config.appKey,
+                            ...headers
+                        }
+                    }
+                );
+            };
+
+            try {
+                const response = await uploadWithHeaders();
+                return response.data;
+            } catch (error) {
+                const err = error as AxiosError;
+                if (err.response?.status === 402 && err.response?.data) {
+                    // Handle x402 payment required
+                    console.log('[x402] Blob upload requires payment');
+
+                    const x402Response = parseX402Response(err.response.data);
+                    const requirement = selectPaymentOption(x402Response.accepts);
+                    const quote = requirementToQuote(requirement, x402Response.accepts);
+
+                    if (!paymentCallback) {
+                        throw new OnChainDBError(
+                            'Payment required but no payment callback provided',
+                            'PAYMENT_REQUIRED',
+                            402,
+                            quote
+                        );
+                    }
+
+                    const payment = await paymentCallback(quote);
+                    const x402Payload = buildPaymentPayload(requirement, payment);
+                    const encodedPayment = encodePaymentHeader(x402Payload);
+
+                    // Retry with X-PAYMENT header
+                    const retryResponse = await uploadWithHeaders({
+                        'X-PAYMENT': encodedPayment
+                    });
+
+                    return retryResponse.data;
+                }
+                throw error;
+            }
+        } catch (error) {
+            throw error instanceof OnChainDBError ? error :
+                new OnChainDBError('Failed to upload blob', 'BLOB_UPLOAD_ERROR');
+        }
+    }
+
+    /**
+     * Retrieve a blob (binary file) from OnChainDB by blob_id
+     *
+     * Returns the raw blob data with proper Content-Type headers.
+     * Can be used to serve images, videos, documents, etc.
+     *
+     * @param request - Blob retrieval request with collection and blob_id
+     * @returns Promise resolving to Blob object (browser) or Buffer (Node.js)
+     *
+     * @example
+     * ```typescript
+     * // Retrieve and display image in browser
+     * const blob = await client.retrieveBlob({
+     *   collection: 'avatars',
+     *   blob_id: 'blob_abc123'
+     * });
+     *
+     * // Create object URL for displaying image
+     * const imageUrl = URL.createObjectURL(blob);
+     * document.querySelector('img').src = imageUrl;
+     *
+     * // Retrieve and save file in Node.js
+     * const buffer = await client.retrieveBlob({
+     *   collection: 'documents',
+     *   blob_id: 'blob_xyz789'
+     * });
+     *
+     * fs.writeFileSync('./downloaded-file.pdf', buffer);
+     * ```
+     */
+    async retrieveBlob(request: RetrieveBlobRequest): Promise<Blob | Buffer> {
+        try {
+            const appId = this.config.appId;
+            if (!appId) {
+                throw new ValidationError('appId must be configured to retrieve blobs');
+            }
+
+            // Retrieve blob via GET endpoint
+            const response = await this.http.get(
+                `/api/apps/${appId}/blobs/${request.collection}/${request.blob_id}`,
+                {
+                    responseType: 'arraybuffer',
+                    headers: {
+                        'X-App-Key': this.config.appKey
+                    }
+                }
+            );
+
+            // Return as Blob in browser, Buffer in Node.js
+            if (typeof (global as any).window !== 'undefined' && typeof Blob !== 'undefined') {
+                // Browser environment
+                const contentType = response.headers['content-type'] || 'application/octet-stream';
+                return new Blob([response.data], {type: contentType});
+            } else {
+                // Node.js environment
+                return Buffer.from(response.data);
+            }
+        } catch (error) {
+            throw error instanceof OnChainDBError ? error :
+                new OnChainDBError('Failed to retrieve blob', 'BLOB_RETRIEVAL_ERROR');
+        }
+    }
+
+    /**
+     * Query blob metadata using the standard query interface
+     *
+     * Returns metadata about blobs without downloading the actual binary data.
+     * Useful for listing, filtering, and searching blobs by their metadata.
+     *
+     * @param collection - Blob collection name
+     * @param where - Query conditions for filtering blobs
+     * @returns Promise resolving to array of blob metadata records
+     *
+     * @example
+     * ```typescript
+     * // Query all blobs by user
+     * const userBlobs = await client.queryBlobMetadata('avatars', {
+     *   user_address: 'celestia1abc...'
+     * });
+     *
+     * // Query blobs by content type
+     * const images = await client.queryBlobMetadata('uploads', {
+     *   content_type: { $regex: 'image/' }
+     * });
+     *
+     * // Query recent blobs
+     * const recentBlobs = await client.queryBlobMetadata('files', {
+     *   uploaded_at: { $gte: '2024-01-01T00:00:00Z' }
+     * });
+     *
+     * // Access blob metadata
+     * for (const blob of userBlobs) {
+     *   console.log('Blob ID:', blob.blob_id);
+     *   console.log('Size:', blob.size_bytes);
+     *   console.log('Type:', blob.content_type);
+     *   console.log('Custom fields:', blob);
+     * }
+     * ```
+     */
+    async queryBlobMetadata(
+        collection: string,
+        where: Record<string, any> = {}
+    ): Promise<BlobMetadata[]> {
+        return await this.findMany<BlobMetadata>(collection, where);
+    }
+
+    /**
+     * Get default index type based on field type
+     */
+    private getDefaultIndexType(fieldType: string): string {
+        switch (fieldType) {
+            case 'string':
+                return 'string';
+            case 'number':
+                return 'number';
+            case 'boolean':
+                return 'boolean';
+            case 'date':
+                return 'date';
+            default:
+                return 'string';
+        }
+    }
+
+    private validateStoreRequest(request: StoreRequest): void {
+        // Validate that either root or collection is provided
+        if (!request.root && !request.collection) {
+            throw new ValidationError('Either root or collection must be provided');
+        }
+
+        if (request.root && typeof request.root !== 'string') {
+            throw new ValidationError('Root must be a valid string in format "app::collection"');
+        }
+
+        if (request.collection && typeof request.collection !== 'string') {
+            throw new ValidationError('Collection must be a valid string');
+        }
+
+        if (!request.data || !Array.isArray(request.data)) {
+            throw new ValidationError('Data must be an array of objects');
+        }
+
+        if (request.data.length === 0) {
+            throw new ValidationError('Data array cannot be empty');
+        }
+
+        // Validate each data item
+        for (const item of request.data) {
+            if (!item || typeof item !== 'object') {
+                throw new ValidationError('Each data item must be a valid object');
+            }
+        }
+
+        // Validate total data size (reasonable limit)
+        const dataSize = JSON.stringify(request.data).length;
+        if (dataSize > 5 * 1024 * 1024) { // 5MB limit for batch
+            throw new ValidationError('Total data size exceeds 5MB limit');
+        }
+    }
+
+    private handleHttpError(error: AxiosError): OnChainDBError {
+        console.error(error);
+        if (error.response) {
+            const statusCode = error.response.status;
+            const message = (error.response.data as any)?.error || error.message;
+
+
+            if (statusCode >= 400 && statusCode < 500) {
+                return new ValidationError(message, error.response.data);
+            }
+
+            return new OnChainDBError(
+                message,
+                'HTTP_ERROR',
+                statusCode,
+                error.response.data
+            );
+        }
+
+        if (error.request) {
+            return new OnChainDBError(
+                'Network error - could not reach OnChainDB service',
+                'NETWORK_ERROR'
+            );
+        }
+
+        return new OnChainDBError(error.message, 'UNKNOWN_ERROR');
+    }
+
+    private sleep(ms: number): Promise<void> {
+        return new Promise(resolve => setTimeout(resolve, ms));
+    }
+
+    /**
+     * Build root string from collection name using configured appId
+     *
+     * @param collection - Collection name
+     * @returns Full root string in format "appId::collection" or just collection for system ops
+     */
+    private buildRoot(collection: string): string {
+        if (!this.config.appId) {
+            return collection; // System operation or no appId configured
+        }
+        return `${this.config.appId}::${collection}`;
+    }
+
+    /**
+     * Resolve root parameter from request, building it if needed
+     *
+     * @param request - Store or Query request
+     * @returns Resolved root string
+     */
+    private resolveRoot(request: { root?: string; collection?: string }): string {
+        if (request.root) {
+            return request.root; // Explicit root takes precedence
+        }
+
+        if (request.collection) {
+            return this.buildRoot(request.collection); // Build from collection + appId
+        }
+
+        throw new ValidationError('Either root or collection must be provided');
+    }
+
+
+}