web3ql-client 1.2.0

package/dist/src/query.js

@@ -0,0 +1,386 @@
+/**
+ * @file   query.ts
+ * @notice Web3QL v1.1 — client-side query engine.
+ *
+ * After decrypting records from the chain, this module provides:
+ *   • WHERE filtering   — eq, ne, gt, gte, lt, lte, in, notIn, like, between, isNull, isNotNull
+ *   • ORDER BY          — multi-column, ASC/DESC
+ *   • LIMIT / OFFSET    — pagination over decrypted records
+ *   • SELECT projection — pick only specific fields
+ *   • DISTINCT          — deduplicate on a column value
+ *   • COUNT / SUM / AVG / MIN / MAX / GROUP BY aggregations
+ *
+ * All operations run in-process on the decrypted plaintext — the chain
+ * sees only ciphertext. For large tables, use the relay-maintained index
+ * endpoint (v1.2) to avoid decrypting every record.
+ *
+ * Usage:
+ * ─────────────────────────────────────────────────────────────
+ *   const results = query(records)
+ *     .where('age', 'gt', 18n)
+ *     .where('name', 'like', 'Ali%')
+ *     .orderBy('age', 'asc')
+ *     .limit(10)
+ *     .select(['name', 'age'])
+ *     .execute();
+ *
+ *   const stats = query(records)
+ *     .where('active', 'eq', true)
+ *     .aggregate({ count: '*', avg: 'score', max: 'score' });
+ * ─────────────────────────────────────────────────────────────
+ */
+// ─────────────────────────────────────────────────────────────
+//  Time-bucket helper
+// ─────────────────────────────────────────────────────────────
+function truncateTimestamp(ms, unit) {
+    const d = new Date(ms);
+    switch (unit) {
+        case 'minute':
+            d.setUTCSeconds(0, 0);
+            break;
+        case 'hour':
+            d.setUTCMinutes(0, 0, 0);
+            break;
+        case 'day':
+            d.setUTCHours(0, 0, 0, 0);
+            break;
+        case 'week': {
+            const dow = d.getUTCDay(); // 0=Sun
+            d.setUTCDate(d.getUTCDate() - dow);
+            d.setUTCHours(0, 0, 0, 0);
+            break;
+        }
+        case 'month':
+            d.setUTCDate(1);
+            d.setUTCHours(0, 0, 0, 0);
+            break;
+        case 'year':
+            d.setUTCMonth(0, 1);
+            d.setUTCHours(0, 0, 0, 0);
+            break;
+    }
+    return d.getTime();
+}
+// ─────────────────────────────────────────────────────────────
+//  HAVING filter
+// ─────────────────────────────────────────────────────────────
+function applyHaving(result, having) {
+    for (const h of having) {
+        const val = result[h.aggregate] ?? 0;
+        switch (h.op) {
+            case 'eq':
+                if (val !== h.value)
+                    return false;
+                break;
+            case 'ne':
+                if (val === h.value)
+                    return false;
+                break;
+            case 'gt':
+                if (val <= h.value)
+                    return false;
+                break;
+            case 'gte':
+                if (val < h.value)
+                    return false;
+                break;
+            case 'lt':
+                if (val >= h.value)
+                    return false;
+                break;
+            case 'lte':
+                if (val > h.value)
+                    return false;
+                break;
+        }
+    }
+    return true;
+}
+// ─────────────────────────────────────────────────────────────
+//  Predicate evaluator
+// ─────────────────────────────────────────────────────────────
+function likeToRegex(pattern, caseInsensitive) {
+    const escaped = pattern
+        .replace(/[.*+?^${}()|[\]\\]/g, '\\$&')
+        .replace(/%/g, '.*')
+        .replace(/_/g, '.');
+    return new RegExp(`^${escaped}$`, caseInsensitive ? 'i' : '');
+}
+function compare(a, b) {
+    if (a instanceof Date && b instanceof Date)
+        return a.getTime() - b.getTime();
+    if (typeof a === 'bigint' && typeof b === 'bigint')
+        return a < b ? -1 : a > b ? 1 : 0;
+    if (typeof a === 'number' && typeof b === 'number')
+        return a - b;
+    return String(a).localeCompare(String(b));
+}
+function applyWhere(row, clause) {
+    const rawVal = row[clause.field];
+    switch (clause.op) {
+        case 'eq': return rawVal === clause.value;
+        case 'ne': return rawVal !== clause.value;
+        case 'gt': return compare(rawVal, clause.value) > 0;
+        case 'gte': return compare(rawVal, clause.value) >= 0;
+        case 'lt': return compare(rawVal, clause.value) < 0;
+        case 'lte': return compare(rawVal, clause.value) <= 0;
+        case 'in': return (clause.values ?? []).includes(rawVal);
+        case 'notIn': return !(clause.values ?? []).includes(rawVal);
+        case 'like': return likeToRegex(String(clause.value), false).test(String(rawVal));
+        case 'ilike': return likeToRegex(String(clause.value), true).test(String(rawVal));
+        case 'between': {
+            const [lo, hi] = clause.range;
+            return compare(rawVal, lo) >= 0 && compare(rawVal, hi) <= 0;
+        }
+        case 'isNull': return rawVal === null || rawVal === undefined;
+        case 'isNotNull': return rawVal !== null && rawVal !== undefined;
+        default: return true;
+    }
+}
+// ─────────────────────────────────────────────────────────────
+//  QueryBuilder
+// ─────────────────────────────────────────────────────────────
+export class QueryBuilder {
+    _rows;
+    _wheres = [];
+    _orders = [];
+    _limitN;
+    _offsetN;
+    _fields;
+    _distinct;
+    _joins = [];
+    constructor(rows) {
+        this._rows = rows;
+    }
+    where(field, op, valueOrArr, _unused2) {
+        if (op === 'isNull' || op === 'isNotNull') {
+            this._wheres.push({ field, op });
+        }
+        else if (op === 'in' || op === 'notIn') {
+            this._wheres.push({ field, op, values: valueOrArr });
+        }
+        else if (op === 'between') {
+            this._wheres.push({ field, op, range: valueOrArr });
+        }
+        else {
+            this._wheres.push({ field, op, value: valueOrArr });
+        }
+        return this;
+    }
+    // ── Sorting ─────────────────────────────────────────────────
+    /** Add an ORDER BY clause. Multiple calls are applied in sequence. */
+    orderBy(field, direction = 'asc') {
+        this._orders.push({ field, direction });
+        return this;
+    }
+    // ── Pagination ──────────────────────────────────────────────
+    limit(n) { this._limitN = n; return this; }
+    offset(n) { this._offsetN = n; return this; }
+    // ── Projection ──────────────────────────────────────────────
+    /** Return only the specified fields from each row. */
+    select(fields) { this._fields = fields; return this; }
+    /** Deduplicate rows where `field` has the same value. */
+    distinct(field) { this._distinct = field; return this; }
+    // ── JOIN ────────────────────────────────────────────────────
+    /**
+     * Join this table with a `right` array on matching key columns.
+     *
+     * @example
+     *   query(orders)
+     *     .join('inner', users, { left: 'userId', right: 'id' })
+     *     .execute()
+     *   // Each matched row = order fields + user fields prefixed with 'j_'
+     *
+     *   query(orders)
+     *     .join('left', users, { left: 'userId', right: 'id' }, 'user_')
+     *     .select(['id', 'user_name', 'amount'])
+     *     .execute()
+     */
+    join(type, right, on, prefix = 'j_') {
+        this._joins.push({ type, right, on, prefix });
+        return this;
+    }
+    // ── Terminal: execute ───────────────────────────────────────
+    execute() {
+        // 0. Apply JOINs
+        let rows = [...this._rows];
+        for (const j of this._joins) {
+            rows = applyJoin(rows, j);
+        }
+        // 1. Filter
+        rows = this._wheres.length
+            ? rows.filter((r) => this._wheres.every((w) => applyWhere(r, w)))
+            : rows;
+        // 2. Distinct
+        if (this._distinct) {
+            const seen = new Set();
+            const field = this._distinct;
+            rows = rows.filter((r) => {
+                const v = r[field];
+                if (seen.has(v))
+                    return false;
+                seen.add(v);
+                return true;
+            });
+        }
+        // 3. Sort
+        if (this._orders.length) {
+            rows.sort((a, b) => {
+                for (const ord of this._orders) {
+                    const cmp = compare(a[ord.field], b[ord.field]);
+                    if (cmp !== 0)
+                        return ord.direction === 'asc' ? cmp : -cmp;
+                }
+                return 0;
+            });
+        }
+        // 4. Offset + Limit
+        const start = this._offsetN ?? 0;
+        const end = this._limitN != null ? start + this._limitN : undefined;
+        rows = rows.slice(start, end);
+        // 5. Projection
+        if (this._fields) {
+            const fields = this._fields;
+            return rows.map((r) => {
+                const out = {};
+                for (const f of fields)
+                    out[f] = r[f];
+                return out;
+            });
+        }
+        return rows;
+    }
+    // ── Terminal: aggregate ─────────────────────────────────────
+    /**
+     * Run aggregation functions over filtered (but not sorted/limited) rows.
+     *
+     * @example
+     *   query(rows).where('active', 'eq', true).aggregate({ count: '*', avg: 'score' })
+     *   // => [{ count: 42, avg: 78.5 }]
+     *
+     *   query(rows).aggregate({ count: '*', groupBy: 'status' })
+     *   // => [{ group: 'active', count: 30 }, { group: 'inactive', count: 12 }]
+     */
+    aggregate(opts) {
+        // Apply JOINs first
+        let allRows = [...this._rows];
+        for (const j of this._joins)
+            allRows = applyJoin(allRows, j);
+        const filtered = this._wheres.length
+            ? allRows.filter((r) => this._wheres.every((w) => applyWhere(r, w)))
+            : allRows;
+        // Determine grouping key
+        const getGroupKey = (row) => {
+            if (opts.timeBucket) {
+                const rawMs = Number(row[opts.timeBucket.field]);
+                return truncateTimestamp(rawMs, opts.timeBucket.unit);
+            }
+            if (opts.groupBy)
+                return row[opts.groupBy];
+            return '__all__';
+        };
+        const groups = new Map();
+        for (const row of filtered) {
+            const gv = getGroupKey(row);
+            const bucket = groups.get(gv);
+            if (bucket)
+                bucket.push(row);
+            else
+                groups.set(gv, [row]);
+        }
+        const noGroupBy = !opts.groupBy && !opts.timeBucket;
+        if (noGroupBy) {
+            return [this._aggregateGroup('__all__', filtered, opts, noGroupBy)];
+        }
+        const results = Array.from(groups.entries()).map(([groupVal, rows]) => this._aggregateGroup(groupVal, rows, opts, false));
+        // Apply HAVING filter
+        if (opts.having?.length) {
+            return results.filter((r) => applyHaving(r, opts.having));
+        }
+        return results;
+    }
+    _aggregateGroup(groupVal, rows, opts, omitGroup) {
+        const result = {};
+        if (!omitGroup)
+            result.group = groupVal;
+        if (opts.count != null) {
+            result.count = rows.length;
+        }
+        if (opts.sum) {
+            result.sum = rows.reduce((acc, r) => acc + Number(r[opts.sum] ?? 0), 0);
+        }
+        if (opts.avg) {
+            result.avg = rows.length
+                ? rows.reduce((acc, r) => acc + Number(r[opts.avg] ?? 0), 0) / rows.length
+                : 0;
+        }
+        if (opts.min) {
+            const vals = rows.map((r) => r[opts.min]).filter((v) => v != null);
+            result.min = vals.reduce((a, b) => (compare(a, b) <= 0 ? a : b), vals[0]);
+        }
+        if (opts.max) {
+            const vals = rows.map((r) => r[opts.max]).filter((v) => v != null);
+            result.max = vals.reduce((a, b) => (compare(a, b) >= 0 ? a : b), vals[0]);
+        }
+        return result;
+    }
+}
+// ─────────────────────────────────────────────────────────────
+//  JOIN implementation
+// ─────────────────────────────────────────────────────────────
+function applyJoin(left, j) {
+    const prefix = j.prefix ?? 'j_';
+    const rightIndex = new Map();
+    for (const r of j.right) {
+        const k = r[j.on.right];
+        const bucket = rightIndex.get(k);
+        if (bucket)
+            bucket.push(r);
+        else
+            rightIndex.set(k, [r]);
+    }
+    const result = [];
+    for (const l of left) {
+        const k = l[j.on.left];
+        const matches = rightIndex.get(k);
+        if (matches && matches.length > 0) {
+            // INNER or LEFT: emit for each match
+            for (const r of matches) {
+                const merged = { ...l };
+                for (const [rk, rv] of Object.entries(r)) {
+                    merged[`${prefix}${rk}`] = rv;
+                }
+                result.push(merged);
+            }
+        }
+        else {
+            // LEFT JOIN: emit left row with nulled right fields
+            if (j.type === 'left') {
+                result.push({ ...l });
+            }
+            // INNER JOIN: no match → skip
+        }
+    }
+    // RIGHT JOIN: also emit right rows with no match on left
+    if (j.type === 'right') {
+        const leftKeys = new Set(left.map((l) => l[j.on.left]));
+        for (const r of j.right) {
+            if (!leftKeys.has(r[j.on.right])) {
+                const merged = {};
+                for (const [rk, rv] of Object.entries(r)) {
+                    merged[`${prefix}${rk}`] = rv;
+                }
+                result.push(merged);
+            }
+        }
+    }
+    return result;
+}
+// ─────────────────────────────────────────────────────────────
+//  Factory helper
+// ─────────────────────────────────────────────────────────────
+/** Fluent entry point: `query(records).where(...).orderBy(...).execute()` */
+export function query(rows) {
+    return new QueryBuilder(rows);
+}
+//# sourceMappingURL=query.js.map

package/dist/src/query.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"query.js","sourceRoot":"","sources":["../../src/query.ts"],"names":[],"mappings":"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"}

package/dist/src/registry.d.ts

@@ -0,0 +1,45 @@
+/**
+ * @file   registry.ts
+ * @notice Client for the on-chain PublicKeyRegistry contract.
+ *
+ * Why is a registry needed?
+ * ─────────────────────────────────────────────────────────────
+ *  When the owner wants to share a record with Alice, they need
+ *  Alice's X25519 public key to encrypt the symmetric key for her.
+ *  The registry is a simple on-chain mapping (address → bytes32)
+ *  where each user registers their own encryption public key once,
+ *  paying only ~40k gas.  After that anyone can look it up.
+ *
+ * Security note:
+ *  The public key stored here is the X25519 key DERIVED from the
+ *  Ethereum private key (sha256(ethPrivKey) → nacl keypair).
+ *  It does NOT expose the Ethereum private key in any way.
+ */
+import { ethers } from 'ethers';
+import type { EncryptionKeypair } from './crypto.js';
+export declare class PublicKeyRegistryClient {
+    private contract;
+    constructor(registryAddress: string, signerOrProvider: ethers.Signer | ethers.Provider);
+    /**
+     * Register the caller's encryption public key on-chain.
+     * Call this once per wallet — ~40k gas on Celo (~$0.001).
+     *
+     * @param keypair   Your EncryptionKeypair from deriveKeypairFromWallet(signer).
+     */
+    register(keypair: EncryptionKeypair): Promise<ethers.TransactionReceipt>;
+    /**
+     * Check whether an address has registered a public key.
+     */
+    hasKey(address: string): Promise<boolean>;
+    /**
+     * Get the X25519 public key for an address.
+     * Throws if the address has not registered.
+     */
+    getPublicKey(address: string): Promise<Uint8Array>;
+    /**
+     * Get public keys for multiple addresses in a single batch of calls.
+     * Returns `null` for any address that has not registered.
+     */
+    getPublicKeys(addresses: string[]): Promise<(Uint8Array | null)[]>;
+}
+//# sourceMappingURL=registry.d.ts.map

package/dist/src/registry.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"registry.d.ts","sourceRoot":"","sources":["../../src/registry.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;GAgBG;AAEH,OAAO,EAAE,MAAM,EAAE,MAAoC,QAAQ,CAAC;AAE9D,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAoB,aAAa,CAAC;AAiBnE,qBAAa,uBAAuB;IAClC,OAAO,CAAC,QAAQ,CAAkB;gBAGhC,eAAe,EAAQ,MAAM,EAC7B,gBAAgB,EAAO,MAAM,CAAC,MAAM,GAAG,MAAM,CAAC,QAAQ;IASxD;;;;;OAKG;IACG,QAAQ,CAAC,OAAO,EAAE,iBAAiB,GAAG,OAAO,CAAC,MAAM,CAAC,kBAAkB,CAAC;IAO9E;;OAEG;IACG,MAAM,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC;IAK/C;;;OAGG;IACG,YAAY,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC,UAAU,CAAC;IAMxD;;;OAGG;IACG,aAAa,CACjB,SAAS,EAAE,MAAM,EAAE,GAClB,OAAO,CAAC,CAAC,UAAU,GAAG,IAAI,CAAC,EAAE,CAAC;CAWlC"}

package/dist/src/registry.js

@@ -0,0 +1,80 @@
+/**
+ * @file   registry.ts
+ * @notice Client for the on-chain PublicKeyRegistry contract.
+ *
+ * Why is a registry needed?
+ * ─────────────────────────────────────────────────────────────
+ *  When the owner wants to share a record with Alice, they need
+ *  Alice's X25519 public key to encrypt the symmetric key for her.
+ *  The registry is a simple on-chain mapping (address → bytes32)
+ *  where each user registers their own encryption public key once,
+ *  paying only ~40k gas.  After that anyone can look it up.
+ *
+ * Security note:
+ *  The public key stored here is the X25519 key DERIVED from the
+ *  Ethereum private key (sha256(ethPrivKey) → nacl keypair).
+ *  It does NOT expose the Ethereum private key in any way.
+ */
+import { ethers } from 'ethers';
+import { publicKeyToHex, hexToPublicKey } from './crypto.js';
+// ─────────────────────────────────────────────────────────────
+//  ABI — only what we need
+// ─────────────────────────────────────────────────────────────
+const REGISTRY_ABI = [
+    'function register(bytes32 pubKey) external',
+    'function getKey(address user) external view returns (bytes32)',
+    'function hasKey(address user) external view returns (bool)',
+    'event KeyRegistered(address indexed user, bytes32 publicKey)',
+];
+// ─────────────────────────────────────────────────────────────
+//  Client
+// ─────────────────────────────────────────────────────────────
+export class PublicKeyRegistryClient {
+    contract;
+    constructor(registryAddress, signerOrProvider) {
+        this.contract = new ethers.Contract(registryAddress, REGISTRY_ABI, signerOrProvider);
+    }
+    /**
+     * Register the caller's encryption public key on-chain.
+     * Call this once per wallet — ~40k gas on Celo (~$0.001).
+     *
+     * @param keypair   Your EncryptionKeypair from deriveKeypairFromWallet(signer).
+     */
+    async register(keypair) {
+        const hex = publicKeyToHex(keypair.publicKey);
+        // eslint-disable-next-line @typescript-eslint/no-explicit-any
+        const tx = await this.contract.register(hex);
+        return tx.wait();
+    }
+    /**
+     * Check whether an address has registered a public key.
+     */
+    async hasKey(address) {
+        // eslint-disable-next-line @typescript-eslint/no-explicit-any
+        return this.contract.hasKey(address);
+    }
+    /**
+     * Get the X25519 public key for an address.
+     * Throws if the address has not registered.
+     */
+    async getPublicKey(address) {
+        // eslint-disable-next-line @typescript-eslint/no-explicit-any
+        const hex = await this.contract.getKey(address);
+        return hexToPublicKey(hex);
+    }
+    /**
+     * Get public keys for multiple addresses in a single batch of calls.
+     * Returns `null` for any address that has not registered.
+     */
+    async getPublicKeys(addresses) {
+        return Promise.all(addresses.map(async (addr) => {
+            try {
+                return await this.getPublicKey(addr);
+            }
+            catch {
+                return null;
+            }
+        }));
+    }
+}
+//# sourceMappingURL=registry.js.map

package/dist/src/registry.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"registry.js","sourceRoot":"","sources":["../../src/registry.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;GAgBG;AAEH,OAAO,EAAE,MAAM,EAAE,MAAoC,QAAQ,CAAC;AAC9D,OAAO,EAAE,cAAc,EAAE,cAAc,EAAE,MAAY,aAAa,CAAC;AAGnE,gEAAgE;AAChE,2BAA2B;AAC3B,gEAAgE;AAEhE,MAAM,YAAY,GAAG;IACnB,4CAA4C;IAC5C,+DAA+D;IAC/D,4DAA4D;IAC5D,8DAA8D;CACtD,CAAC;AAEX,gEAAgE;AAChE,UAAU;AACV,gEAAgE;AAEhE,MAAM,OAAO,uBAAuB;IAC1B,QAAQ,CAAkB;IAElC,YACE,eAA6B,EAC7B,gBAAsD;QAEtD,IAAI,CAAC,QAAQ,GAAG,IAAI,MAAM,CAAC,QAAQ,CACjC,eAAe,EACf,YAAY,EACZ,gBAAgB,CACjB,CAAC;IACJ,CAAC;IAED;;;;;OAKG;IACH,KAAK,CAAC,QAAQ,CAAC,OAA0B;QACvC,MAAM,GAAG,GAAG,cAAc,CAAC,OAAO,CAAC,SAAS,CAAC,CAAC;QAC9C,8DAA8D;QAC9D,MAAM,EAAE,GAAI,MAAO,IAAI,CAAC,QAAgB,CAAC,QAAQ,CAAC,GAAG,CAAmD,CAAC;QACzG,OAAO,EAAE,CAAC,IAAI,EAAE,CAAC;IACnB,CAAC;IAED;;OAEG;IACH,KAAK,CAAC,MAAM,CAAC,OAAe;QAC1B,8DAA8D;QAC9D,OAAQ,IAAI,CAAC,QAAgB,CAAC,MAAM,CAAC,OAAO,CAAqB,CAAC;IACpE,CAAC;IAED;;;OAGG;IACH,KAAK,CAAC,YAAY,CAAC,OAAe;QAChC,8DAA8D;QAC9D,MAAM,GAAG,GAAG,MAAO,IAAI,CAAC,QAAgB,CAAC,MAAM,CAAC,OAAO,CAAW,CAAC;QACnE,OAAO,cAAc,CAAC,GAAG,CAAC,CAAC;IAC7B,CAAC;IAED;;;OAGG;IACH,KAAK,CAAC,aAAa,CACjB,SAAmB;QAEnB,OAAO,OAAO,CAAC,GAAG,CAChB,SAAS,CAAC,GAAG,CAAC,KAAK,EAAE,IAAI,EAAE,EAAE;YAC3B,IAAI,CAAC;gBACH,OAAO,MAAM,IAAI,CAAC,YAAY,CAAC,IAAI,CAAC,CAAC;YACvC,CAAC;YAAC,MAAM,CAAC;gBACP,OAAO,IAAI,CAAC;YACd,CAAC;QACH,CAAC,CAAC,CACH,CAAC;IACJ,CAAC;CACF"}

package/dist/src/schema-manager.d.ts

@@ -0,0 +1,109 @@
+/**
+ * @file   schema-manager.ts
+ * @notice Web3QL v1.2 — schema management: drop tables, rename, introspection.
+ *
+ * Schema is stored as ABI-encoded bytes in the database contract.
+ * This module provides:
+ *
+ *   1. SCHEMA INTROSPECTION  — decode raw schema bytes → FieldDescriptor[]
+ *   2. DROP TABLE            — bulk delete all owner records, then rename table to __dropped__
+ *   3. RENAME TABLE          — soft-rename via a meta record (contract doesn't support rename natively)
+ *   4. SCHEMA DIFF           — compare two schemas, produce a list of changes
+ *   5. SCHEMA VERSION        — read + write the schema version stored in a meta record
+ *
+ * Usage:
+ * ─────────────────────────────────────────────────────────────
+ *   const mgr = new SchemaManager(db, tableAddress, tableClient);
+ *
+ *   // Inspect a deployed table's schema
+ *   const fields = await mgr.introspect();
+ *
+ *   // Diff two versions
+ *   const changes = diffSchema(oldFields, newFields);
+ *
+ *   // Soft-drop: mark table as dropped + purge all owner records
+ *   await mgr.dropTable(ownerAddress);
+ *
+ *   // Soft-rename: store alias mapping in meta record
+ *   await mgr.renameTable('users', 'app_users');
+ * ─────────────────────────────────────────────────────────────
+ */
+import { ethers } from 'ethers';
+import type { DatabaseClient } from './factory-client.js';
+import type { EncryptedTableClient } from './table-client.js';
+import type { FieldDescriptor } from './types.js';
+/**
+ * Decode raw schema bytes from the contract into an array of FieldDescriptors.
+ *
+ * Web3QL encodes schema as ABI-encoded:
+ *   tuple(string name, string solidityType, bool primaryKey, bool notNull)[]
+ *
+ * This mirrors protocol/compiler/generator.ts compileSchema().
+ */
+export declare function decodeSchemaBytes(schemaBytes: string | Uint8Array): FieldDescriptor[];
+export type SchemaChangeType = 'added' | 'dropped' | 'typeChanged' | 'notNullChanged';
+export interface SchemaChange {
+    type: SchemaChangeType;
+    column: string;
+    oldValue?: string;
+    newValue?: string;
+}
+/**
+ * Compute the diff between two schema versions.
+ * Returns an ordered list of changes from `from` → `to`.
+ */
+export declare function diffSchema(from: FieldDescriptor[], to: FieldDescriptor[]): SchemaChange[];
+export declare class SchemaManager {
+    private db;
+    private tableAddress;
+    private tableClient;
+    private dbContract;
+    constructor(db: DatabaseClient, tableAddress: string, tableClient: EncryptedTableClient, signer: ethers.Signer);
+    /**
+     * Read the schema bytes from the database contract and decode them
+     * into a usable FieldDescriptor array.
+     *
+     * @param tableName  The name used when the table was created.
+     */
+    introspect(tableName: string): Promise<FieldDescriptor[]>;
+    /**
+     * List all table names in this database.
+     */
+    listTables(): Promise<string[]>;
+    /**
+     * Read the schema version stored in a meta record on-chain.
+     * Returns 0 if no version record has been written yet.
+     */
+    getSchemaVersion(tableName: string): Promise<number>;
+    /**
+     * Write (or update) the schema version meta record.
+     */
+    setSchemaVersion(tableName: string, version: number): Promise<void>;
+    /**
+     * Store a name alias mapping in a meta record.
+     * Future `introspect()` calls should use the new name.
+     *
+     * ⚠  The contract still uses the old name internally. This is a
+     *    client-side alias only. To hard-rename, re-create the table.
+     */
+    renameTable(oldName: string, newName: string): Promise<void>;
+    /** Check if a table has been soft-renamed. Returns the new name or null. */
+    getRenamedTo(tableName: string): Promise<string | null>;
+    /**
+     * "Drop" a table by:
+     *   1. Deleting all owner records (batch, up to `maxRecords`).
+     *   2. Writing a __dropped__ meta record so the SDK knows to ignore it.
+     *
+     * ⚠  This is irreversible. The on-chain key->ciphertext mapping for
+     *    deleted records is permanently unreadable (symmetric key scrubbed).
+     *
+     * @param ownerAddress  Address whose records to delete.
+     * @param maxRecords    Safety cap. Default: 500. Increase for large tables.
+     */
+    dropTable(ownerAddress: string, maxRecords?: number): Promise<{
+        deleted: number;
+    }>;
+    /** Check if a table has been soft-dropped. */
+    isDropped(): Promise<boolean>;
+}
+//# sourceMappingURL=schema-manager.d.ts.map

package/dist/src/schema-manager.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"schema-manager.d.ts","sourceRoot":"","sources":["../../src/schema-manager.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6BG;AAEH,OAAO,EAAE,MAAM,EAAE,MAAyB,QAAQ,CAAC;AACnD,OAAO,KAAK,EAAE,cAAc,EAAE,MAAY,qBAAqB,CAAC;AAChE,OAAO,KAAK,EAAE,oBAAoB,EAAE,MAAM,mBAAmB,CAAC;AAC9D,OAAO,KAAK,EAAE,eAAe,EAAE,MAAW,YAAY,CAAC;AAyBvD;;;;;;;GAOG;AACH,wBAAgB,iBAAiB,CAAC,WAAW,EAAE,MAAM,GAAG,UAAU,GAAG,eAAe,EAAE,CAoBrF;AAMD,MAAM,MAAM,gBAAgB,GAAG,OAAO,GAAG,SAAS,GAAG,aAAa,GAAG,gBAAgB,CAAC;AAEtF,MAAM,WAAW,YAAY;IAC3B,IAAI,EAAO,gBAAgB,CAAC;IAC5B,MAAM,EAAK,MAAM,CAAC;IAClB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,QAAQ,CAAC,EAAE,MAAM,CAAC;CACnB;AAED;;;GAGG;AACH,wBAAgB,UAAU,CACxB,IAAI,EAAE,eAAe,EAAE,EACvB,EAAE,EAAI,eAAe,EAAE,GACtB,YAAY,EAAE,CAiChB;AAYD,qBAAa,aAAa;IACxB,OAAO,CAAC,EAAE,CAA2B;IACrC,OAAO,CAAC,YAAY,CAAS;IAC7B,OAAO,CAAC,WAAW,CAAwB;IAC3C,OAAO,CAAC,UAAU,CAAoB;gBAGpC,EAAE,EAAY,cAAc,EAC5B,YAAY,EAAE,MAAM,EACpB,WAAW,EAAG,oBAAoB,EAClC,MAAM,EAAQ,MAAM,CAAC,MAAM;IAU7B;;;;;OAKG;IACG,UAAU,CAAC,SAAS,EAAE,MAAM,GAAG,OAAO,CAAC,eAAe,EAAE,CAAC;IAU/D;;OAEG;IACG,UAAU,IAAI,OAAO,CAAC,MAAM,EAAE,CAAC;IAMrC;;;OAGG;IACG,gBAAgB,CAAC,SAAS,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC;IAa1D;;OAEG;IACG,gBAAgB,CAAC,SAAS,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAazE;;;;;;OAMG;IACG,WAAW,CAAC,OAAO,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAWlE,4EAA4E;IACtE,YAAY,CAAC,SAAS,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC;IAe7D;;;;;;;;;;OAUG;IACG,SAAS,CAAC,YAAY,EAAE,MAAM,EAAE,UAAU,SAAM,GAAG,OAAO,CAAC;QAAE,OAAO,EAAE,MAAM,CAAA;KAAE,CAAC;IAkBrF,8CAA8C;IACxC,SAAS,IAAI,OAAO,CAAC,OAAO,CAAC;CAIpC"}