Skill: emanz1/iqdb-onchain-storage (version 0.2.0)

--- 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: [REDACTED_SECRET] (via `@iqlabs-official/solana-sdk`). - **Devnet:** Supported via legacy SDK (`@iqlabsteam/iqdb`). Program: [REDACTED_SECRET]. ### Install (New Official SDK — recommended) ```bash npm install @iqlabs-official/solana-sdk @solana/web3.js ``` ### Install (Legacy SDK — devnet only) ```bash npm install @iqlabsteam/iqdb @coral-xyz/anchor @solana/web3.js ``` ### Environment Variables (Legacy SDK) ```bash 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) ```javascript 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) ```javascript // 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: ```javascript 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](https://www.npmjs.com/package/@iqlabs-official/solana-sdk) — Official Solana SDK (mainnet) - [@iqlabsteam/iqdb](https://www.npmjs.com/package/@iqlabsteam/iqdb) — Legacy SDK (devnet) - [hanLock](https://www.npmjs.com/package/hanlock) — Hangul syllabic encoding - [Solana Web3.js](https://www.npmjs.com/package/@solana/web3.js) — Solana client library


Security scan verdicts — ClawScan: clean | static analysis: clean | VirusTotal: clean | SkillSpector: clean (LOW)