iqdb-onchain-storage

name	iqdb-onchain-storage
description	On-chain immutable data storage using IQ Labs tech stack (IQDB, hanLock, x402). Use when building Solana-based persistent storage, on-chain databases, tamper-evident records, password-encoded data, or paid file inscription. Triggers on tasks involving on-chain CRUD, Solana PDA storage, rolling hash verification, Hangul encoding, or HTTP 402 payment-gated inscription.

IQDB On-Chain Storage (Code-In Tech)

Overview

Build on-chain relational databases on Solana using IQ Labs' tech stack. Three tools:

• IQDB — Full CRUD relational database on Solana via Anchor PDAs. Tables, rows, rolling keccak hash for tamper-evident history.
• hanLock — Password-based Hangul syllabic encoding (base-11172). Lightweight data encoding for on-chain privacy. Zero dependencies.
• x402 — HTTP 402 payment-gated file inscription to Solana. Quote → Pay (USDC/SOL) → Broadcast chunk transactions → Download.

Quick Start

Prerequisites

• Node.js 18+
• Solana CLI (solana --version)
• A Solana wallet with devnet SOL (solana airdrop 2)

Network Support

• Mainnet: Fully supported. Program ID: 9KLLchQVJpGkw4jPuUmnvqESdR7mtNCYr3qS4iQLabs (via @iqlabs-official/solana-sdk).
• Devnet: Supported via legacy SDK (@iqlabsteam/iqdb). Program: 7Vk5JJDxUBAaaAkpYQpWYCZNz4SVPm3mJFSxrBzTQuAX.

Install (New Official SDK — recommended)

npm install @iqlabs-official/solana-sdk @solana/web3.js

Install (Legacy SDK — devnet only)

npm install @iqlabsteam/iqdb @coral-xyz/anchor @solana/web3.js

Environment Variables (Legacy SDK)

ANCHOR_WALLET=/path/to/keypair.json    # Required — Solana keypair for signing
ANCHOR_PROVIDER_URL=https://api.devnet.solana.com  # Required — RPC for writes
NETWORK_URL=https://api.devnet.solana.com  # Required — RPC for reads (must match ANCHOR_PROVIDER_URL)

Legacy SDK note: Set NETWORK_URL to match ANCHOR_PROVIDER_URL. The SDK uses separate connections for reads and writes.

RPC Note: Public Solana RPCs rate-limit aggressively. Add 2-3 second delays between rapid transactions on mainnet. Use a dedicated RPC provider (Helius, Alchemy, QuickNode) for production.

Minimal Example — New SDK (Mainnet)

const { Connection, Keypair, SystemProgram, PublicKey } = require('@solana/web3.js');
const { writer, reader, setRpcUrl, contract } = require('@iqlabs-official/solana-sdk');

// Monkey-patch for Node v24 Buffer compatibility
const seedModule = require('@iqlabs-official/solana-sdk/dist/sdk/utils/seed');
const origFn = seedModule.toSeedBytes;
seedModule.toSeedBytes = (v) => Buffer.from(origFn(v));

setRpcUrl('https://api.mainnet-beta.solana.com');
const connection = new Connection('https://api.mainnet-beta.solana.com', 'confirmed');

// Write a row (requires root + table initialized first — see references/iqdb-core.md)
const sig = await writer.writeRow(
  connection, signer, 'my-db-root', 'players',
  JSON.stringify({ name: 'Alice', score: '1500', level: '12' })
);

// Read rows
const rows = await reader.readTableRows(tablePda);

Minimal Example — Legacy SDK (Devnet)

// Use CommonJS — the SDK bundles CJS internally
const { createIQDB } = require('@iqlabsteam/iqdb');

const iqdb = createIQDB();

// Ensure root PDA exists (idempotent)
await iqdb.ensureRoot();

// Create a table (idempotent — use ensureTable over createTable)
await iqdb.ensureTable('players', ['name', 'score', 'level'], 'name');

// Write a row — data must be a JSON STRING, not an object
await iqdb.writeRow('players', JSON.stringify({
  name: 'Alice', score: '1500', level: '12'
}));

// Read all rows — requires userPubkey as string
const rows = await iqdb.readRowsByTable({
  userPubkey: 'YOUR_WALLET_PUBKEY',
  tableName: 'players'
});
console.log(rows);

Architecture

Root PDA (per wallet)
  └── Table PDA (per table name)
       └── Rows stored as transaction data
            └── hash: keccak(domain || prev_hash || tx_data)

• Root PDA — One per wallet. Initialized via ensureRoot().
• Table PDA — Created via ensureTable() or createTable(). Has column schema and ID column.
• Rows — Written as JSON strings via writeRow(). Append-only — each write is a new transaction.
• Rolling hash — Each write appends to an immutable hash chain. Enables tamper detection without full replication.

Core Operations

See references/iqdb-core.md for full API.

Operation	Method	Cost
Init root	contract.initializeDbRootInstruction() / ensureRoot()	~0.01 SOL rent
Create table	contract.createTableInstruction() / ensureTable()	~0.02 SOL rent
Write row	writer.writeRow() / iqdb.writeRow()	~0.005-0.01 SOL
Read rows	reader.readTableRows() / readRowsByTable()	Free (RPC read)
Update/Delete	pushInstruction(table, txSig, before, after)	TX fee only
Extension table	createExtTable(base, rowId, extKey, cols, idCol?)	~0.02 SOL rent

Cost reference (mainnet): Root + 3 tables + 5 data rows = ~0.09 SOL total.

Important Constraints

• Row data size limit: Keep row JSON under ~100 bytes. The on-chain program enforces a transaction size limit (TxTooLong error). For larger data, split across multiple rows or use hanLock sparingly (encoded output is larger than input).
• Append-only writes: writeRow always appends. Use pushInstruction for updates/deletes.
• pushInstruction writes to instruction log, not row data. readRowsByTable returns raw rows and does NOT reflect updates/deletes from pushInstruction. To see the full picture including corrections, use searchTableByName which returns both rows (raw) and instruRows/targetContent (instruction history). Your application must apply instruction corrections on top of raw rows.
• CommonJS required: The SDK uses dynamic require() internally. Use .cjs files or "type": "commonjs" in package.json. ESM imports will fail.

hanLock Encoding

See references/hanlock.md for full API.

Encode data with a password before writing on-chain for lightweight privacy:

const { encodeWithPassword, decodeWithPassword } = require('hanlock');

const encoded = encodeWithPassword('short secret', 'mypassword');
// → Korean syllable string like "깁닣뭡..."

// Write encoded data on-chain
await iqdb.writeRow('secrets', JSON.stringify({ owner: 'Alice', data: encoded }));

// Later — decode
const decoded = decodeWithPassword(encoded, 'mypassword');
// → 'short secret'

Note: hanLock encoding expands data size (~3x). Keep input short to stay within the on-chain row size limit.

x402 Payment Flow

See references/x402-payments.md for full API.

Payment-gated file inscription to Solana:

1. Quote — POST /quote with file metadata → get price in USDC/SOL
2. Pay — Send payment transaction to provided address
3. Inscribe — POST /inscribe with payment proof → file chunked into Solana transactions
4. Download — GET /download/:txId → reconstruct file from on-chain chunks

Use Cases

• Discord RPG Bot — On-chain character persistence, provable item ownership, immutable game state
• Governance — Tamper-evident proposal/vote storage with rolling hash audit trail
• Compliance logs — Verifiable edit history for call center records
• Paid storage — Monetize data inscription via x402

References

• IQ Labs SDK — Official Solana SDK (mainnet)
• @iqlabsteam/iqdb — Legacy SDK (devnet)
• hanLock — Hangul syllabic encoding
• Solana Web3.js — Solana client library