web3ql-client 1.2.0

package/src/schema-manager.ts

@@ -0,0 +1,301 @@
+/**
+ * @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';
+
+// ─────────────────────────────────────────────────────────────
+//  Schema introspection
+// ─────────────────────────────────────────────────────────────
+
+/**
+ * Minimal ABI type tags used in Web3QL schema encoding.
+ * Must stay in sync with protocol/compiler/generator.ts.
+ */
+const SOLIDITY_TO_FIELD_TYPE: Record<string, string> = {
+  'uint256': 'INT',
+  'int256' : 'INT',
+  'int64'  : 'INT',
+  'uint64' : 'UINT64',
+  'uint32' : 'UINT32',
+  'uint16' : 'UINT16',
+  'uint8'  : 'UINT8',
+  'string' : 'TEXT',
+  'bool'   : 'BOOL',
+  'address': 'ADDRESS',
+  'bytes32': 'BYTES32',
+  'bytes'  : 'BYTES32',
+};
+
+/**
+ * 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 function decodeSchemaBytes(schemaBytes: string | Uint8Array): FieldDescriptor[] {
+  try {
+    const bytes = typeof schemaBytes === 'string' ? ethers.getBytes(schemaBytes) : schemaBytes;
+    if (bytes.length === 0) return [];
+
+    const abiCoder = ethers.AbiCoder.defaultAbiCoder();
+    const decoded  = abiCoder.decode(
+      ['tuple(string name, string solidityType, bool primaryKey, bool notNull)[]'],
+      bytes,
+    );
+    const fields = decoded[0] as { name: string; solidityType: string; primaryKey: boolean; notNull: boolean }[];
+    return fields.map((f) => ({
+      name      : f.name,
+      type      : (SOLIDITY_TO_FIELD_TYPE[f.solidityType] ?? 'TEXT') as FieldDescriptor['type'],
+      primaryKey: f.primaryKey || undefined,
+      notNull   : f.notNull    || undefined,
+    }));
+  } catch {
+    return [];
+  }
+}
+
+// ─────────────────────────────────────────────────────────────
+//  Schema diff
+// ─────────────────────────────────────────────────────────────
+
+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 function diffSchema(
+  from: FieldDescriptor[],
+  to  : FieldDescriptor[],
+): SchemaChange[] {
+  const changes: SchemaChange[] = [];
+  const fromMap = new Map(from.map((f) => [f.name, f]));
+  const toMap   = new Map(to.map((f) => [f.name, f]));
+
+  // Added or changed
+  for (const [name, toField] of toMap) {
+    const fromField = fromMap.get(name);
+    if (!fromField) {
+      changes.push({ type: 'added', column: name, newValue: toField.type });
+    } else {
+      if (fromField.type !== toField.type) {
+        changes.push({ type: 'typeChanged', column: name, oldValue: fromField.type, newValue: toField.type });
+      }
+      if (Boolean(fromField.notNull) !== Boolean(toField.notNull)) {
+        changes.push({
+          type    : 'notNullChanged',
+          column  : name,
+          oldValue: fromField.notNull ? 'NOT NULL' : 'NULLABLE',
+          newValue: toField.notNull   ? 'NOT NULL' : 'NULLABLE',
+        });
+      }
+    }
+  }
+
+  // Dropped
+  for (const name of fromMap.keys()) {
+    if (!toMap.has(name)) {
+      changes.push({ type: 'dropped', column: name });
+    }
+  }
+
+  return changes;
+}
+
+// ─────────────────────────────────────────────────────────────
+//  SchemaManager
+// ─────────────────────────────────────────────────────────────
+
+const DATABASE_INTROSPECT_ABI = [
+  'function getTableSchema(string calldata name) external view returns (bytes memory)',
+  'function getTable(string calldata name) external view returns (address)',
+  'function listTables() external view returns (string[] memory)',
+] as const;
+
+export class SchemaManager {
+  private db          : DatabaseClient;
+  private tableAddress: string;
+  private tableClient : EncryptedTableClient;
+  private dbContract  : ethers.Contract;
+
+  constructor(
+    db          : DatabaseClient,
+    tableAddress: string,
+    tableClient : EncryptedTableClient,
+    signer      : ethers.Signer,
+  ) {
+    this.db           = db;
+    this.tableAddress = tableAddress;
+    this.tableClient  = tableClient;
+    this.dbContract   = new ethers.Contract(db.address, DATABASE_INTROSPECT_ABI, signer);
+  }
+
+  // ── Introspection ───────────────────────────────────────────
+
+  /**
+   * 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.
+   */
+  async introspect(tableName: string): Promise<FieldDescriptor[]> {
+    try {
+      // eslint-disable-next-line @typescript-eslint/no-explicit-any
+      const schemaBytes = await (this.dbContract as any).getTableSchema(tableName) as string;
+      return decodeSchemaBytes(schemaBytes);
+    } catch {
+      return [];
+    }
+  }
+
+  /**
+   * List all table names in this database.
+   */
+  async listTables(): Promise<string[]> {
+    return this.db.listTables();
+  }
+
+  // ── Schema version tracking ─────────────────────────────────
+
+  /**
+   * Read the schema version stored in a meta record on-chain.
+   * Returns 0 if no version record has been written yet.
+   */
+  async getSchemaVersion(tableName: string): Promise<number> {
+    const versionKey = this.tableClient.deriveKey(`__schema_version__${tableName}`, 0n);
+    try {
+      const exists = await this.tableClient.exists(versionKey);
+      if (!exists) return 0;
+      const json = await this.tableClient.readPlaintext(versionKey);
+      const { version } = JSON.parse(json) as { version: number };
+      return version;
+    } catch {
+      return 0;
+    }
+  }
+
+  /**
+   * Write (or update) the schema version meta record.
+   */
+  async setSchemaVersion(tableName: string, version: number): Promise<void> {
+    const versionKey = this.tableClient.deriveKey(`__schema_version__${tableName}`, 0n);
+    const payload    = JSON.stringify({ version, updatedAt: Date.now() });
+    const exists     = await this.tableClient.exists(versionKey);
+    if (exists) {
+      await this.tableClient.updateRaw(versionKey, payload);
+    } else {
+      await this.tableClient.writeRaw(versionKey, payload);
+    }
+  }
+
+  // ── Soft-rename ─────────────────────────────────────────────
+
+  /**
+   * 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.
+   */
+  async renameTable(oldName: string, newName: string): Promise<void> {
+    const renameKey = this.tableClient.deriveKey(`__rename__${oldName}`, 0n);
+    const payload   = JSON.stringify({ from: oldName, to: newName, renamedAt: Date.now() });
+    const exists    = await this.tableClient.exists(renameKey);
+    if (exists) {
+      await this.tableClient.updateRaw(renameKey, payload);
+    } else {
+      await this.tableClient.writeRaw(renameKey, payload);
+    }
+  }
+
+  /** Check if a table has been soft-renamed. Returns the new name or null. */
+  async getRenamedTo(tableName: string): Promise<string | null> {
+    const renameKey = this.tableClient.deriveKey(`__rename__${tableName}`, 0n);
+    try {
+      const exists = await this.tableClient.exists(renameKey);
+      if (!exists) return null;
+      const json = await this.tableClient.readPlaintext(renameKey);
+      const { to } = JSON.parse(json) as { to: string };
+      return to;
+    } catch {
+      return null;
+    }
+  }
+
+  // ── Soft-drop ───────────────────────────────────────────────
+
+  /**
+   * "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.
+   */
+  async dropTable(ownerAddress: string, maxRecords = 500): Promise<{ deleted: number }> {
+    const keys = await this.tableClient.listOwnerRecords(ownerAddress, 0n, BigInt(maxRecords));
+    let deleted = 0;
+    for (const key of keys) {
+      try {
+        await this.tableClient.deleteRecord(key);
+        deleted++;
+      } catch { /* already deleted or no access — skip */ }
+    }
+
+    // Write tombstone
+    const tombstoneKey = this.tableClient.deriveKey(`__dropped__${this.tableAddress}`, 0n);
+    const payload      = JSON.stringify({ droppedAt: Date.now(), ownerAddress });
+    await this.tableClient.writeRaw(tombstoneKey, payload);
+
+    return { deleted };
+  }
+
+  /** Check if a table has been soft-dropped. */
+  async isDropped(): Promise<boolean> {
+    const tombstoneKey = this.tableClient.deriveKey(`__dropped__${this.tableAddress}`, 0n);
+    return this.tableClient.exists(tombstoneKey);
+  }
+}

package/src/table-client.ts

@@ -0,0 +1,393 @@
+/**
+ * @file   table-client.ts
+ * @notice Base encrypted table client.
+ *
+ * This class wraps a Web3QL table contract proxy and handles ALL
+ * encryption/decryption client-side.  The chain only ever sees:
+ *   • ciphertext blobs (AES-equivalent via NaCl secretbox)
+ *   • per-user encrypted key blobs   (NaCl box)
+ *
+ * Plaintext and symmetric keys never leave this class.
+ *
+ * Usage pattern:
+ * ─────────────────────────────────────────────────────────────
+ *   const client = new EncryptedTableClient(tableAddress, signer, keypair);
+ *
+ *   // Write — encrypts automatically
+ *   await client.write(1n, JSON.stringify({ name: 'Alice' }));
+ *
+ *   // Read — decrypts automatically
+ *   const data = await client.read(1n);         // '{"name":"Alice"}'
+ *
+ *   // Share with Bob (needs Bob registered in registry)
+ *   await client.share(1n, bobAddress, Role.VIEWER, registry);
+ *
+ *   // Revoke
+ *   await client.revoke(1n, bobAddress);
+ */
+
+import { ethers }                               from 'ethers';
+import {
+  EncryptionKeypair,
+  generateSymmetricKey,
+  encryptData,
+  decryptData,
+  encryptKeyForSelf,
+  encryptKeyForRecipient,
+  decryptKeyForSelf,
+  decryptKeyFromSender,
+}                                               from './crypto.js';
+import type { PublicKeyRegistryClient }         from './registry.js';
+
+// ─────────────────────────────────────────────────────────────
+//  Types
+// ─────────────────────────────────────────────────────────────
+
+export enum Role {
+  VIEWER = 1,
+  EDITOR = 2,
+}
+
+export interface RawRecord {
+  ciphertext : Uint8Array;
+  deleted    : boolean;
+  version    : bigint;
+  updatedAt  : bigint;
+  owner      : string;
+}
+
+// ─────────────────────────────────────────────────────────────
+//  Minimal ABI — functions shared by all Web3QL table contracts
+// ─────────────────────────────────────────────────────────────
+
+const TABLE_ABI = [
+  // core
+  'function write(bytes32 key, bytes calldata ciphertext, bytes calldata encryptedKey) external',
+  'function read(bytes32 key) external view returns (bytes memory ciphertext, bool deleted, uint256 version, uint256 updatedAt, address owner)',
+  'function update(bytes32 key, bytes calldata ciphertext, bytes calldata encryptedKey) external',
+  'function deleteRecord(bytes32 key) external',
+  // key management
+  'function getMyEncryptedKey(bytes32 key) external view returns (bytes memory)',
+  // access control
+  'function grantAccess(bytes32 key, address user, uint8 role, bytes calldata encryptedKeyForUser) external',
+  'function revokeAccess(bytes32 key, address user) external',
+  // views
+  'function recordExists(bytes32 key) external view returns (bool)',
+  'function recordOwner(bytes32 key) external view returns (address)',
+  'function collaboratorCount(bytes32 key) external view returns (uint8)',
+  'function getCollaborators(bytes32 key) external view returns (address[] memory)',
+  'function getRole(bytes32 resource, address user) external view returns (uint8)',
+  // owner record enumeration
+  'function ownerRecordCount(address addr) external view returns (uint256)',
+  'function getOwnerRecords(address addr, uint256 start, uint256 limit) external view returns (bytes32[] memory)',
+  'function getActiveOwnerRecords(address addr, uint256 start, uint256 limit) external view returns (bytes32[] memory)',
+  // table metadata
+  'function tableName() external view returns (string memory)',
+] as const;
+
+// ─────────────────────────────────────────────────────────────
+//  EncryptedTableClient
+// ─────────────────────────────────────────────────────────────
+
+export class EncryptedTableClient {
+  readonly tableAddress : string;
+  protected contract   : ethers.Contract;
+  protected signer     : ethers.Signer;
+
+  /** The caller's X25519 keypair — private key STAYS in memory only. */
+  private keypair      : EncryptionKeypair;
+  /** Shorthand for casting contract to any so strict index checks don't block calls. */
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any
+  private get c(): any { return this.contract; }
+
+  constructor(
+    tableAddress : string,
+    signer       : ethers.Signer,
+    keypair      : EncryptionKeypair,
+    abi          : readonly string[] = TABLE_ABI,
+  ) {
+    this.tableAddress = tableAddress;
+    this.signer       = signer;
+    this.keypair      = keypair;
+    this.contract     = new ethers.Contract(tableAddress, abi, signer);
+  }
+
+  // ── Key derivation ─────────────────────────────────────────
+
+  /**
+   * Derive the bytes32 on-chain record key from a table name + primary key.
+   * Canonical scheme: keccak256(abi.encodePacked(tableName, id))
+   * Matches the Solidity generator and connector — all three layers are aligned.
+   */
+  deriveKey(tableName: string, id: bigint): string {
+    return ethers.solidityPackedKeccak256(
+      ['string', 'uint256'],
+      [tableName, id],
+    );
+  }
+
+  // ── Write ──────────────────────────────────────────────────
+
+  /**
+   * Encrypt `plaintext` and store it as a new record.
+   * The symmetric key is encrypted for the caller (owner).
+   *
+   * @param key        bytes32 record key (use deriveKey or pass directly).
+   * @param plaintext  Any data you want to store — string or raw bytes.
+   */
+  async writeRaw(
+    key       : string,
+    plaintext : string | Uint8Array,
+  ): Promise<ethers.TransactionReceipt> {
+    const data         = toBytes(plaintext);
+    const symKey       = generateSymmetricKey();
+    const ciphertext   = encryptData(data, symKey);
+    const encryptedKey = encryptKeyForSelf(symKey, this.keypair);
+
+    const tx = await this.c.write(key, ciphertext, encryptedKey);
+    return tx.wait();
+  }
+
+  /**
+   * Encrypt `plaintext` for self — returns the raw ciphertext and
+   * encrypted symmetric key bytes WITHOUT submitting any transaction.
+   *
+   * Used by Model.relatedCreate() to hand the encrypted bytes to a
+   * RelationWire contract that will call table.write() on behalf of
+   * the user within an atomic transaction.
+   */
+  async encryptForSelf(
+    plaintext : string | Uint8Array,
+  ): Promise<{ ciphertext: Uint8Array; encryptedKey: Uint8Array }> {
+    const data         = toBytes(plaintext);
+    const symKey       = generateSymmetricKey();
+    const ciphertext   = encryptData(data, symKey);
+    const encryptedKey = encryptKeyForSelf(symKey, this.keypair);
+    return { ciphertext, encryptedKey };
+  }
+
+  // ── Read ───────────────────────────────────────────────────
+
+  /**
+   * Read and decrypt a record.
+   * Returns the plaintext as a UTF-8 string.
+   * Throws if the record is deleted, doesn't exist, or you lack access.
+   */
+  async readPlaintext(key: string): Promise<string> {
+    return new TextDecoder().decode(await this.readBytes(key));
+  }
+
+  /**
+   * Read and decrypt a record — returns raw bytes.
+   */
+  async readBytes(key: string): Promise<Uint8Array> {
+    const raw         = await this.readRaw(key);
+    const encKey      = await this.getMyEncryptedKey(key);
+    const symKey      = decryptKeyForSelf(encKey, this.keypair);
+    return decryptData(raw.ciphertext, symKey);
+  }
+
+  /**
+   * Get the raw (still-encrypted) record from chain.
+   */
+  async readRaw(key: string): Promise<RawRecord> {
+    const [ciphertext, deleted, version, updatedAt, owner] =
+      await this.c.read(key);
+    if (deleted) throw new Error(`EncryptedTableClient: record ${key} is deleted`);
+    return {
+      ciphertext: toUint8Array(ciphertext),
+      deleted,
+      version,
+      updatedAt,
+      owner,
+    };
+  }
+
+  // ── Update ─────────────────────────────────────────────────
+
+  /**
+   * Update an existing record with new plaintext.
+   * Re-encrypts with a FRESH symmetric key — old key copies are NOT
+   * automatically re-shared.  Call reshareAfterUpdate() afterwards
+   * if collaborators need access to the updated version.
+   */
+  async updateRaw(
+    key       : string,
+    plaintext : string | Uint8Array,
+  ): Promise<ethers.TransactionReceipt> {
+    const data         = toBytes(plaintext);
+    const symKey       = generateSymmetricKey();
+    const ciphertext   = encryptData(data, symKey);
+    const encryptedKey = encryptKeyForSelf(symKey, this.keypair);
+    const tx = await this.c.update(key, ciphertext, encryptedKey);
+    return tx.wait();
+  }
+
+  // ── Delete ─────────────────────────────────────────────────
+
+  /**
+   * Delete a record.  The contract scrubs ALL collaborator key copies
+   * on-chain.  Ciphertext remains but is permanently unreadable by
+   * anyone (the symmetric key is gone).
+   */
+  async deleteRecord(key: string): Promise<ethers.TransactionReceipt> {
+    const tx = await this.c.deleteRecord(key);
+    return tx.wait();
+  }
+
+  // ── Sharing ────────────────────────────────────────────────
+
+  /**
+   * Share a record with another user.
+   *
+   * Flow:
+   *   1. Fetch caller's encrypted key from chain
+   *   2. Decrypt to recover the symmetric key (requires caller's privkey)
+   *   3. Fetch recipient's X25519 public key from the registry
+   *   4. Re-encrypt the symmetric key for the recipient
+   *   5. Call grantAccess on-chain with the new encrypted key copy
+   *
+   * @param key       bytes32 record key
+   * @param recipient Address to share with
+   * @param role      Role.VIEWER or Role.EDITOR
+   * @param registry  PublicKeyRegistryClient to look up recipient's pubkey
+   */
+  async share(
+    key       : string,
+    recipient : string,
+    role      : Role,
+    registry  : PublicKeyRegistryClient,
+  ): Promise<ethers.TransactionReceipt> {
+    // 1. Get our own encrypted key copy from chain
+    const myEncKey = await this.getMyEncryptedKey(key);
+
+    // 2. Decrypt to get the plain symmetric key
+    const symKey = decryptKeyForSelf(myEncKey, this.keypair);
+
+    // 3. Look up recipient's public key from registry
+    const recipientPubKey = await registry.getPublicKey(recipient);
+
+    // 4. Re-encrypt the symmetric key for the recipient
+    const recipientEncKey = encryptKeyForRecipient(
+      symKey,
+      recipientPubKey,
+      this.keypair.privateKey,
+    );
+
+    // 5. Grant access on-chain
+    const tx = await this.c.grantAccess(
+      key,
+      recipient,
+      role,
+      recipientEncKey,
+    );
+    return tx.wait();
+  }
+
+  /**
+   * Revoke a user's access.  Their encrypted key copy is scrubbed
+   * on-chain — they can no longer decrypt the record.
+   * (They may have decrypted and cached it locally — that is a
+   *  client-side concern, not something the chain can prevent.)
+   */
+  async revoke(
+    key  : string,
+    user : string,
+  ): Promise<ethers.TransactionReceipt> {
+    const tx = await this.c.revokeAccess(key, user);
+    return tx.wait();
+  }
+
+  /**
+   * After updating a record (which rotates the key), re-share with
+   * all current collaborators so they can decrypt the new ciphertext.
+   *
+   * @param key            bytes32 record key
+   * @param collaborators  List of addresses to re-share with
+   * @param roles          Role for each address (parallel array)
+   * @param registry       PublicKeyRegistryClient
+   */
+  async reshareAfterUpdate(
+    key           : string,
+    collaborators : string[],
+    roles         : Role[],
+    registry      : PublicKeyRegistryClient,
+  ): Promise<void> {
+    if (collaborators.length !== roles.length) {
+      throw new Error('reshareAfterUpdate: collaborators and roles arrays must be same length');
+    }
+    for (let i = 0; i < collaborators.length; i++) {
+      await this.share(key, collaborators[i]!, roles[i]!, registry);
+    }
+  }
+
+  // ── Key helpers ────────────────────────────────────────────
+
+  /** Fetch this caller's encrypted key blob from chain (still encrypted). */
+  async getMyEncryptedKey(key: string): Promise<Uint8Array> {
+    const hex = await this.c.getMyEncryptedKey(key) as string;
+    return ethers.getBytes(hex);
+  }
+
+  /**
+   * Decrypt a symmetric key blob that was encrypted by a known sender
+   * (use when you are a collaborator, not the owner — the sender's
+   *  public key must be passed explicitly).
+   */
+  decryptSharedKey(
+    encryptedKey    : Uint8Array,
+    senderPublicKey : Uint8Array,
+  ): Uint8Array {
+    return decryptKeyFromSender(encryptedKey, senderPublicKey, this.keypair.privateKey);
+  }
+
+  // ── Views ──────────────────────────────────────────────────
+
+  async exists(key: string): Promise<boolean> {
+    return this.c.recordExists(key) as Promise<boolean>;
+  }
+
+  async owner(key: string): Promise<string> {
+    return this.c.recordOwner(key) as Promise<string>;
+  }
+
+  async collaboratorCount(key: string): Promise<number> {
+    return Number(await this.c.collaboratorCount(key));
+  }
+
+  /** List bytes32 record keys owned by `addr` (paginated).
+   *  Prefers getActiveOwnerRecords (skips deleted) when available;
+   *  falls back to getOwnerRecords for older contract versions.
+   */
+  async listOwnerRecords(
+    addr  : string,
+    start : bigint = 0n,
+    limit : bigint = 50n,
+  ): Promise<string[]> {
+    try {
+      return await this.c.getActiveOwnerRecords(addr, start, limit) as Promise<string[]>;
+    } catch {
+      // Older contract without getActiveOwnerRecords — fall back
+      return this.c.getOwnerRecords(addr, start, limit) as Promise<string[]>;
+    }
+  }
+
+  /** Total number of records written by `addr` (including deleted). */
+  async ownerRecordCount(addr: string): Promise<bigint> {
+    return this.c.ownerRecordCount(addr) as Promise<bigint>;
+  }
+}
+
+// ─────────────────────────────────────────────────────────────
+//  Helpers
+// ─────────────────────────────────────────────────────────────
+
+function toBytes(data: string | Uint8Array): Uint8Array {
+  if (typeof data === 'string') return new TextEncoder().encode(data);
+  return data;
+}
+
+function toUint8Array(value: string | Uint8Array): Uint8Array {
+  if (value instanceof Uint8Array) return value;
+  return ethers.getBytes(value); // hex string
+}