PriceIndex is a special index type that changes how payments work, enabling revenue-sharing business models for applications built on OnchainDB.
Traditional vs PriceIndex Payment
| Aspect | Traditional (BTree/Hash) | PriceIndex |
|---|
| Cost basis | Data size | Field value |
| Formula | cost = data_size_kb * rate | cost = field_value |
| Revenue sharing | None | Automatic |
| Example | 10 KB order costs ~0.001 TIA | $100 order costs 100 TIA |
How It Works
User Creates Order
totalPrice: 100000000 utia (100 TIA)
|
Payment Required: 100 TIA
|
Automatic Revenue Split (Server-Side)
|
+----+----+
| |
70 TIA 30 TIA
App Platform
Wallet (OnchainDB)
Creating a PriceIndex
const db = client.database('your-app-id');
// Create PriceIndex on totalPrice field
await db.createIndex({
name: 'idx_orders_totalPrice',
collection: 'orders',
field_name: 'totalPrice',
index_type: 'Price'
});
// Revenue split is configured server-side
// Typically: 70% to app wallet, 30% to platform
Using PriceIndex in Applications
// Calculate order total
const orderTotal = items.reduce((sum, item) =>
sum + (item.price * item.quantity), 0
);
// Create order with PriceIndex payment
await client.createDocument(
'orders',
{
customerAddress: userWallet,
items: orderItems,
totalPrice: orderTotal, // This field has PriceIndex!
status: 'confirmed'
},
{
payment_mode: 'pay_on_write',
payment_tx_hash: userPaymentTx,
user_address: userWallet,
broker_address: brokerAddress,
amount_utia: orderTotal // User pays order total, not storage cost
}
);
// Backend automatically:
// 1. Detects PriceIndex on totalPrice field
// 2. Uses totalPrice value as payment amount
// 3. Splits payment automatically (e.g., 70% app, 30% platform)
// 4. Credits app wallet balance
Use Cases
PriceIndex is perfect for:
| Use Case | PriceIndex Field |
|---|
| E-commerce | orderTotal |
| Ticketing | ticketPrice |
| Marketplace | transactionAmount |
| Subscriptions | planPrice |
| Service fees | feeAmount |
Not suitable for:
- Product catalogs (use BTree for filtering by price range)
- Free/public data storage
- Internal analytics data
- User-generated content without pricing
Complete E-commerce Example
import { createClient } from '@onchaindb/sdk';
const client = createClient({
endpoint: 'https://api.onchaindb.io',
appId: 'my-store',
appKey: process.env.ONCHAINDB_APP_KEY
});
// Setup: Create collections with indexes
async function setupStore() {
const db = client.database('my-store');
// Products - use btree for price range queries
await db.createIndex({
name: 'idx_products_category',
collection: 'products',
field_name: 'category',
index_type: 'hash'
});
await db.createIndex({
name: 'idx_products_price',
collection: 'products',
field_name: 'price',
index_type: 'btree'
});
// Orders - use PriceIndex for payment-based pricing!
await db.createIndex({
name: 'idx_orders_customerId',
collection: 'orders',
field_name: 'customerId',
index_type: 'hash'
});
await db.createIndex({
name: 'idx_orders_totalPrice',
collection: 'orders',
field_name: 'totalPrice',
index_type: 'Price' // <-- PriceIndex!
});
}
// Checkout: Create order with PriceIndex payment
async function checkout(cart, userWallet, paymentTxHash) {
const orderTotal = cart.items.reduce(
(sum, item) => sum + (item.price * item.quantity),
0
);
const order = await client.createDocument(
'orders',
{
customerId: userWallet,
items: cart.items,
totalPrice: orderTotal,
status: 'confirmed',
createdAt: new Date().toISOString()
},
{
payment_tx_hash: paymentTxHash,
user_address: userWallet,
broker_address: process.env.BROKER_ADDRESS,
amount_utia: orderTotal
}
);
return order;
}
Checking App Wallet Balance
Your application’s revenue share is credited to the app wallet balance:
// Check app wallet balance
const response = await fetch(
`${endpoint}/api/apps/${appId}/wallet/balance`
);
const balance = await response.json();
console.log('App balance:', balance.amount_utia, 'utia');
console.log('App balance:', balance.amount_utia / 1_000_000, 'TIA');
Revenue Split Configuration
The revenue split is configured server-side and is typically:
- 70% to the application wallet
- 30% to the platform (OnchainDB)
Revenue split percentages are not user-configurable. Contact OnchainDB support for custom arrangements.
Next Steps