@utxopia/sdk 0.1.0-alpha.2 → 0.1.0-alpha.3

package/src/auditor.ts

@@ -0,0 +1,409 @@
+/**
+ * Auditor toolkit (Phase 1)
+ *
+ * Given a {@link DelegatedViewKey}, produce a structured audit record for
+ * every announcement that decrypts cleanly to a positive amount. The scanner:
+ *
+ *   - enforces the delegation's `expiresAt` (wall-clock check)
+ *   - enforces the delegation's `[fromSlot, toSlot]` honor-system range
+ *   - honors `ViewPermissions.INCOMING_ONLY` once outgoing memos exist
+ *     (Phase 2). Today everything coming back is treated as IN since no
+ *     sender-memo channel has shipped yet.
+ *
+ * No on-chain enforcement is possible (the auditor already holds the secret);
+ * scope is enforced *inside this scanner* so a compliant tool obeys it and the
+ * issuer can prove what scope they handed over.
+ */
+
+import {
+  scanAnnouncementsViewOnly,
+  ANNOUNCEMENT_TYPE_DEPOSIT,
+  type OnChainStealthAnnouncement,
+  type ViewOnlyKeys,
+} from "./stealth";
+import { babyJubDecompress, bytesToHex } from "./crypto";
+import {
+  ViewPermissions,
+  hasPermission,
+  isDelegatedKeyValid,
+  isSlotInDelegatedRange,
+  type DelegatedViewKey,
+} from "./keys";
+import { decryptSenderMemo, type SenderMemoCiphertext } from "./sender-memo";
+import { decryptAuditorCiphertext } from "./auditor-ciphertext";
+export type { SenderMemoCiphertext };
+
+/** Direction of a record relative to the audited user. */
+export type AuditDirection = "IN" | "OUT" | "SELF" | "UNKNOWN" | "AUDITOR_VISIBLE";
+
+/** A single matched announcement, ready for report rendering. */
+export interface AuditRecord {
+  slot: number;
+  blockTime: number;
+  leafIndex: number;
+  direction: AuditDirection;
+  announcementType: number;
+  tokenId: bigint;
+  amount: bigint;
+  commitmentHex: string;
+  ephemeralPubHex: string;
+}
+
+export interface AuditScanOptions {
+  /** Token IDs to scan for. Required — auditor must know which token namespaces to look in. */
+  tokenIds: bigint[];
+  /** Override slot range (otherwise uses key's fromSlot/toSlot). */
+  fromSlot?: number;
+  toSlot?: number;
+  /** Clock for `expiresAt` check. Override for tests; defaults to `Date.now()`. */
+  now?: () => number;
+  /** Sender-memo events (Phase 2). When supplied, OUT records will be produced. */
+  senderMemos?: ReadonlyArray<OnChainSenderMemo>;
+  /** Auditor ciphertext events (Method-Y). When supplied, AUDITOR_VISIBLE records will be produced. */
+  auditorCiphertexts?: ReadonlyArray<{ commitment: Uint8Array; blob: Uint8Array; slot?: number; blockTime?: number }>;
+  /** Auditor viewing private key (32-byte Ed25519). Required to decrypt auditorCiphertexts. */
+  auditorViewingPrivKey?: Uint8Array;
+}
+
+/**
+ * Sender-memo event as observed on-chain. Emitted by `emit_sender_memo` in the
+ * UTXOpia program. The memo carries its own `commitment` and `leafIndex` so
+ * the auditor can join it back to the corresponding tree leaf, even though
+ * the memo itself isn't a leaf.
+ */
+export interface OnChainSenderMemo extends SenderMemoCiphertext {
+  blockTime?: number;
+  slot?: number;
+}
+
+export interface AuditScanSummary {
+  records: AuditRecord[];
+  /** How many announcements fell outside the slot range. */
+  outOfRangeSkipped: number;
+  /** How many announcements lacked a slot but the key required one. */
+  unscopedSkipped: number;
+  /** How many announcements decrypted to something invalid (wrong key, out of range amount). */
+  notForViewerSkipped: number;
+  /** Effective slot range that was actually enforced. */
+  effectiveFromSlot?: number;
+  effectiveToSlot?: number;
+}
+
+/**
+ * Annotated announcement input — carries the same shape as
+ * {@link OnChainStealthAnnouncement} but the `tokenId` is opt-in. When
+ * omitted, the caller will be matched against every `tokenIds` entry.
+ */
+export interface AuditScanAnnouncement extends OnChainStealthAnnouncement {
+  /** Optional — when present, scanner only tries the matching tokenId. */
+  tokenId?: bigint;
+}
+
+// Range intersection: undefined means unbounded on that side.
+function intersectLower(a?: number, b?: number): number | undefined {
+  if (a == null) return b;
+  if (b == null) return a;
+  return Math.max(a, b);
+}
+function intersectUpper(a?: number, b?: number): number | undefined {
+  if (a == null) return b;
+  if (b == null) return a;
+  return Math.min(a, b);
+}
+
+function buildAuditorVisibleRecord(
+  plain: { tokenId: bigint; amount: bigint },
+  commitment: Uint8Array,
+  slot: number,
+  blockTime: number,
+): AuditRecord {
+  return {
+    slot,
+    blockTime,
+    leafIndex: -1,
+    direction: "AUDITOR_VISIBLE",
+    announcementType: -1,
+    tokenId: plain.tokenId,
+    amount: plain.amount,
+    commitmentHex: bytesToHex(commitment),
+    ephemeralPubHex: "",
+  };
+}
+
+/**
+ * Scan announcements with a delegated viewing key and produce {@link AuditRecord}s.
+ *
+ * Throws if the key is expired or lacks `SCAN` permission, or if the key is
+ * missing the spending-pub/nullifying-key material required to verify deposits.
+ */
+export async function auditScan(
+  key: DelegatedViewKey,
+  announcements: ReadonlyArray<AuditScanAnnouncement>,
+  options: AuditScanOptions,
+): Promise<AuditScanSummary> {
+  if (!hasPermission(key, ViewPermissions.SCAN)) {
+    throw new Error("Delegated key missing SCAN permission");
+  }
+  if (!isDelegatedKeyValid(key)) {
+    throw new Error("Delegated key has expired");
+  }
+  if (!key.spendingPubKeyCompressed || key.nullifyingKey == null) {
+    throw new Error(
+      "Delegated key missing spendingPubKey/nullifyingKey — re-export with a v2 key",
+    );
+  }
+  if (options.tokenIds.length === 0) {
+    throw new Error("auditScan requires at least one tokenId");
+  }
+
+  // Intersect the CLI range with the key's grant — options may only narrow the
+  // delegated [fromSlot, toSlot], never widen it (undefined = unbounded that side).
+  const effectiveFromSlot = intersectLower(options.fromSlot, key.fromSlot);
+  const effectiveToSlot = intersectUpper(options.toSlot, key.toSlot);
+
+  const keyForRange: DelegatedViewKey = {
+    ...key,
+    fromSlot: effectiveFromSlot,
+    toSlot: effectiveToSlot,
+  };
+
+  let outOfRangeSkipped = 0;
+  let unscopedSkipped = 0;
+
+  const inScope: AuditScanAnnouncement[] = [];
+  for (const ann of announcements) {
+    if (effectiveFromSlot != null || effectiveToSlot != null) {
+      if (ann.slot == null) {
+        unscopedSkipped++;
+        continue;
+      }
+      if (!isSlotInDelegatedRange(keyForRange, ann.slot)) {
+        outOfRangeSkipped++;
+        continue;
+      }
+    }
+    inScope.push(ann);
+  }
+
+  const viewOnly: ViewOnlyKeys = {
+    viewingPrivKey: key.viewingPrivKey,
+    spendingPubKey: babyJubDecompress(key.spendingPubKeyCompressed),
+    nullifyingKey: key.nullifyingKey,
+  };
+
+  // Honor INCOMING_ONLY: when set, skip OUT records derived from sender memos.
+  // The auditor still scans incoming announcements; just doesn't produce
+  // outgoing-direction rows. Enforcement is honor-system (the key holder could
+  // run auditScan locally with this branch removed), but the issuance contract
+  // is that an INCOMING_ONLY delegation produces no OUT records under the
+  // canonical SDK path.
+  const incomingOnly = hasPermission(key, ViewPermissions.INCOMING_ONLY);
+
+  const records: AuditRecord[] = [];
+  const seenLeafIndex = new Set<number>();
+  // Index inScope by leafIndex so we can recover slot after the inner scan,
+  // which strips the slot field from its output.
+  const slotByLeafIndex = new Map<number, number | undefined>();
+  for (const ann of inScope) slotByLeafIndex.set(ann.leafIndex, ann.slot);
+
+  for (const tokenId of options.tokenIds) {
+    // Either the announcement explicitly targets this token, or its tokenId is
+    // unknown and we try every requested token id (commitment match disambiguates).
+    const subset = inScope.filter(
+      (a) => a.tokenId == null || a.tokenId === tokenId,
+    );
+    if (subset.length === 0) continue;
+
+    const matched = await scanAnnouncementsViewOnly(viewOnly, subset, tokenId);
+    for (const m of matched) {
+      if (seenLeafIndex.has(m.leafIndex)) continue;
+      seenLeafIndex.add(m.leafIndex);
+      records.push({
+        slot: slotByLeafIndex.get(m.leafIndex) ?? 0,
+        blockTime: m.blockTime ?? 0,
+        leafIndex: m.leafIndex,
+        direction: "IN",
+        announcementType:
+          subset.find((a) => a.leafIndex === m.leafIndex)?.announcementType ??
+          ANNOUNCEMENT_TYPE_DEPOSIT,
+        tokenId,
+        amount: m.amount,
+        commitmentHex: bytesToHex(m.commitment),
+        ephemeralPubHex: bytesToHex(m.ephemeralPub),
+      });
+    }
+  }
+
+  const notForViewerSkipped = inScope.length - seenLeafIndex.size;
+
+  // Sender memos (Phase 2): produce OUT records the user emitted.
+  // Skipped entirely when the delegation is INCOMING_ONLY.
+  if (!incomingOnly && options.senderMemos && options.senderMemos.length > 0) {
+    for (const memo of options.senderMemos) {
+      if (effectiveFromSlot != null || effectiveToSlot != null) {
+        if (memo.slot == null) {
+          unscopedSkipped++;
+          continue;
+        }
+        if (!isSlotInDelegatedRange(keyForRange, memo.slot)) {
+          outOfRangeSkipped++;
+          continue;
+        }
+      }
+      const plain = decryptSenderMemo(key.viewingPrivKey, memo);
+      if (!plain) continue;
+      // Sender memos are encrypted to the user's own viewing key, so the
+      // primary sanity check is non-zero. The 8-byte field already caps amount at u64::MAX.
+      if (plain.amount <= 0n) continue;
+      // Token filter: respect the requested tokenIds set.
+      if (!options.tokenIds.some((t) => t === plain.tokenId)) continue;
+
+      records.push({
+        slot: memo.slot ?? 0,
+        blockTime: memo.blockTime ?? 0,
+        leafIndex: memo.leafIndex,
+        direction: "OUT",
+        announcementType: -1, // distinct from deposit (0) / transfer (1)
+        tokenId: plain.tokenId,
+        amount: plain.amount,
+        commitmentHex: bytesToHex(memo.commitment),
+        ephemeralPubHex: "",
+      });
+    }
+  }
+
+  // Auditor ciphertexts (Method-Y): produce AUDITOR_VISIBLE records.
+  if (
+    options.auditorViewingPrivKey &&
+    options.auditorCiphertexts &&
+    options.auditorCiphertexts.length > 0
+  ) {
+    for (const entry of options.auditorCiphertexts) {
+      if (effectiveFromSlot != null || effectiveToSlot != null) {
+        if (entry.slot == null) {
+          unscopedSkipped++;
+          continue;
+        }
+        if (!isSlotInDelegatedRange(keyForRange, entry.slot)) {
+          outOfRangeSkipped++;
+          continue;
+        }
+      }
+      const plain = decryptAuditorCiphertext(
+        options.auditorViewingPrivKey,
+        entry.blob,
+        entry.commitment,
+      );
+      if (!plain) continue;
+      if (plain.amount <= 0n) continue;
+      if (!options.tokenIds.some((t) => t === plain.tokenId)) continue;
+
+      records.push(buildAuditorVisibleRecord(plain, entry.commitment, entry.slot ?? 0, entry.blockTime ?? 0));
+    }
+  }
+
+  return {
+    records,
+    outOfRangeSkipped,
+    unscopedSkipped,
+    notForViewerSkipped: Math.max(0, notForViewerSkipped),
+    effectiveFromSlot,
+    effectiveToSlot,
+  };
+}
+
+/**
+ * Scan auditor ciphertexts (Method-Y) using only an auditor viewing private key.
+ *
+ * Unlike {@link auditScan}, this function does NOT require a full {@link DelegatedViewKey}
+ * with spendingPubKey/nullifyingKey — it only needs the auditor's 32-byte Ed25519
+ * viewing private key. This is the primary entry point for Method-Y auditor use cases.
+ */
+export async function auditScanCiphertexts(
+  auditorViewingPrivKey: Uint8Array,
+  ciphertexts: ReadonlyArray<{ commitment: Uint8Array; blob: Uint8Array; slot?: number; blockTime?: number }>,
+  options?: { tokenIds?: bigint[]; fromSlot?: number; toSlot?: number },
+): Promise<AuditScanSummary> {
+  const records: AuditRecord[] = [];
+  let outOfRangeSkipped = 0;
+  let unscopedSkipped = 0;
+  let notForViewerSkipped = 0;
+
+  const effectiveFromSlot = options?.fromSlot;
+  const effectiveToSlot = options?.toSlot;
+
+  for (const entry of ciphertexts) {
+    if (effectiveFromSlot != null || effectiveToSlot != null) {
+      if (entry.slot == null) {
+        unscopedSkipped++;
+        continue;
+      }
+      if (effectiveFromSlot != null && entry.slot < effectiveFromSlot) {
+        outOfRangeSkipped++;
+        continue;
+      }
+      if (effectiveToSlot != null && entry.slot > effectiveToSlot) {
+        outOfRangeSkipped++;
+        continue;
+      }
+    }
+
+    const plain = decryptAuditorCiphertext(auditorViewingPrivKey, entry.blob, entry.commitment);
+    if (!plain) {
+      notForViewerSkipped++;
+      continue;
+    }
+    if (plain.amount <= 0n) {
+      notForViewerSkipped++;
+      continue;
+    }
+    if (options?.tokenIds && options.tokenIds.length > 0 && !options.tokenIds.some((t) => t === plain.tokenId)) {
+      notForViewerSkipped++;
+      continue;
+    }
+
+    records.push(buildAuditorVisibleRecord(plain, entry.commitment, entry.slot ?? 0, entry.blockTime ?? 0));
+  }
+
+  return {
+    records,
+    outOfRangeSkipped,
+    unscopedSkipped,
+    notForViewerSkipped,
+    effectiveFromSlot,
+    effectiveToSlot,
+  };
+}
+
+/**
+ * Render audit records as CSV. Always returns a single trailing newline.
+ *
+ * Columns: slot, block_time_iso, leaf_index, direction, type, token_id, amount, commitment, ephemeral_pub
+ */
+export function auditRecordsToCsv(records: ReadonlyArray<AuditRecord>): string {
+  const header =
+    "slot,block_time_iso,leaf_index,direction,type,token_id,amount,commitment,ephemeral_pub";
+  const lines = records.map((r) => {
+    const ts = r.blockTime > 0 ? new Date(r.blockTime * 1000).toISOString() : "";
+    const typeLabel =
+      r.direction === "OUT"
+        ? "sender-memo"
+        : r.direction === "AUDITOR_VISIBLE"
+          ? "auditor-ciphertext"
+          : r.announcementType === ANNOUNCEMENT_TYPE_DEPOSIT
+            ? "deposit"
+            : "transfer";
+    return [
+      r.slot,
+      ts,
+      r.leafIndex,
+      r.direction,
+      typeLabel,
+      r.tokenId.toString(),
+      r.amount.toString(),
+      r.commitmentHex,
+      r.ephemeralPubHex,
+    ].join(",");
+  });
+  return [header, ...lines].join("\n") + "\n";
+}

package/src/bitcoin/ika.ts

@@ -0,0 +1,103 @@
+/**
+ * Ika dWallet → Bitcoin P2TR address derivation.
+ *
+ * UTXOpia v2 custody is held by an Ika dWallet on Solana. The dWallet's
+ * compressed secp256k1 public key (or its x-only form) identifies the Bitcoin
+ * key that Ika can sign for. Ika pre-alpha signs for the raw x-only key; it
+ * does not currently produce signatures for UTXOpia's per-deposit tweaked keys.
+ */
+
+import { taggedHash, hexToBytes, bytesToHex } from "../crypto";
+import { bech32m } from "bech32";
+import { secp256k1 } from "@noble/curves/secp256k1.js";
+
+/**
+ * Reference to an Ika dWallet for address derivation.
+ *
+ * `literal-pubkey` is the synchronous form — pass a 33-byte compressed or
+ * 32-byte x-only pubkey directly. The `id` form is async and must be resolved
+ * to a pubkey via the Ika SDK before reaching this helper.
+ */
+export type IkaDWalletRef =
+  | { type: "literal-xonly"; xonlyPubkey: Uint8Array } // 32 bytes
+  | { type: "literal-compressed"; compressedPubkey: Uint8Array } // 33 bytes (0x02/0x03 || x)
+  | { type: "id"; dwalletId: string };
+
+/**
+ * Derive the BIP-341 P2TR (key-path-only) address controlled by an Ika dWallet.
+ *
+ * BIP-341 (no script tree):
+ *   t = h_tapTweak(P)
+ *   Q = P + t*G
+ *   output_key = x(Q)
+ *   address = bech32m(hrp, [witness_version=1, ...words(output_key)])
+ *
+ * @param ref       The Ika dWallet reference (literal pubkey, or future async id).
+ * @param network   "mainnet" | "testnet" | "regtest"
+ * @returns         The P2TR address (`bc1p…` / `tb1p…` / `bcrt1p…`)
+ */
+export function deriveCustodyAddressFromIkaDWallet(
+  ref: IkaDWalletRef,
+  network: "mainnet" | "testnet" | "regtest"
+): string {
+  const xonly = extractXOnly(ref);
+  const tweak = taggedHash("TapTweak", xonly);
+  const tweakScalar = bytesToBigIntBe(tweak);
+
+  // Lift x-only to a full point with even y (BIP-340 convention).
+  const internalPoint = secp256k1.Point.fromHex("02" + bytesToHex(xonly));
+  const tweakPoint = secp256k1.Point.BASE.multiply(tweakScalar);
+  const outputPoint = internalPoint.add(tweakPoint);
+
+  // Drop the 1-byte parity prefix to get the x-only output key.
+  const outputKey = hexToBytes(outputPoint.toHex(true).slice(2));
+
+  const hrp =
+    network === "mainnet" ? "bc" : network === "regtest" ? "bcrt" : "tb";
+  const words = bech32m.toWords(outputKey);
+  return bech32m.encode(hrp, [1, ...words]);
+}
+
+/**
+ * Encode a raw x-only public key as a P2TR witness program.
+ *
+ * This intentionally does not apply BIP-341's no-script TapTweak. It is the
+ * direct-vault address used by the current Ika pre-alpha mock signer, because
+ * the signer returns Schnorr signatures for the dWallet's raw x-only key.
+ */
+export function deriveRawXOnlyP2TRAddress(
+  xonlyPubkey: Uint8Array,
+  network: "mainnet" | "testnet" | "regtest"
+): string {
+  if (xonlyPubkey.length !== 32) {
+    throw new Error("xonlyPubkey must be 32 bytes");
+  }
+  const hrp =
+    network === "mainnet" ? "bc" : network === "regtest" ? "bcrt" : "tb";
+  return bech32m.encode(hrp, [1, ...bech32m.toWords(xonlyPubkey)]);
+}
+
+function extractXOnly(ref: IkaDWalletRef): Uint8Array {
+  if (ref.type === "literal-xonly") {
+    if (ref.xonlyPubkey.length !== 32) {
+      throw new Error("xonlyPubkey must be 32 bytes");
+    }
+    return ref.xonlyPubkey;
+  }
+  if (ref.type === "literal-compressed") {
+    if (ref.compressedPubkey.length !== 33) {
+      throw new Error("compressedPubkey must be 33 bytes");
+    }
+    return ref.compressedPubkey.subarray(1);
+  }
+  throw new Error(
+    "deriveCustodyAddressFromIkaDWallet: 'id' resolution requires the Ika SDK; " +
+      "resolve dwalletId → pubkey first and pass via literal-xonly or literal-compressed"
+  );
+}
+
+function bytesToBigIntBe(bytes: Uint8Array): bigint {
+  let n = 0n;
+  for (const b of bytes) n = (n << 8n) | BigInt(b);
+  return n;
+}

package/src/bitcoin/index.ts

@@ -0,0 +1,5 @@
+export {
+  deriveCustodyAddressFromIkaDWallet,
+  deriveRawXOnlyP2TRAddress,
+} from "./ika";
+export type { IkaDWalletRef } from "./ika";