@utxopia/sdk 0.1.0-alpha.1

package/packages/sdk/dist/auditor-ciphertext.d.ts

@@ -0,0 +1,72 @@
+/**
+ * Auditor ciphertext — ECDH encrypt-to-auditor for Method-Y permissioned pools.
+ *
+ * Lets a depositor encrypt note viewing data (tokenId, amount) TO a permissioned-pool
+ * auditor's Ed25519 viewing PUBLIC key. Only the auditor's private key can decrypt.
+ *
+ * Cipher: X25519 ECDH key-agreement + XChaCha20-Poly1305 AEAD.
+ *
+ * Wire format (112 bytes):
+ *   eph_pub        :: 32 bytes  (ephemeral X25519 public key)
+ *   nonce          :: 24 bytes  (random XChaCha20 nonce)
+ *   ciphertext_tag :: 56 bytes  (encrypted tokenId(32 BE) || amount(8 LE) + Poly1305 tag(16))
+ */
+export declare const AUDITOR_CIPHERTEXT_BYTES: number;
+export interface AuditorNotePlain {
+    tokenId: bigint;
+    amount: bigint;
+}
+/**
+ * Encrypt note viewing data to an auditor's Ed25519 viewing public key.
+ *
+ * @param auditorViewingPubKey - 32-byte Ed25519 public key of the auditor
+ * @param plain                - tokenId + amount to encrypt
+ * @param commitment           - 32-byte note commitment (AAD — binds blob to note)
+ * @param ephemeralPriv        - optional 32-byte X25519 private key (random if omitted)
+ * @returns 112-byte blob: eph_pub(32) || nonce(24) || ciphertextWithTag(56)
+ */
+export declare function encryptAuditorCiphertext(auditorViewingPubKey: Uint8Array, plain: AuditorNotePlain, commitment: Uint8Array, ephemeralPriv?: Uint8Array): Uint8Array;
+/**
+ * Convenience wrapper: build a 112-byte auditor ciphertext blob from note fields.
+ *
+ * Thin wrapper over {@link encryptAuditorCiphertext} for callers who have the raw
+ * note fields (tokenId, amount, commitment) rather than a pre-packed `AuditorNotePlain`.
+ *
+ * @param input.auditorViewingPubKey - 32-byte Ed25519 public key of the auditor
+ * @param input.tokenId              - token id (field element, fits in 256 bits)
+ * @param input.amount               - note amount (≤ 64 bits)
+ * @param input.commitment           - 32-byte note commitment (binds ciphertext to note)
+ * @returns 112-byte blob: eph_pub(32) || nonce(24) || ciphertextWithTag(56)
+ */
+export declare function buildAuditorCiphertextForNote(input: {
+    auditorViewingPubKey: Uint8Array;
+    tokenId: bigint;
+    amount: bigint;
+    commitment: Uint8Array;
+}): Uint8Array;
+/**
+ * Normalise the `auditorCiphertext` field accepted by permissioned builders.
+ *
+ * Builders accept either:
+ *   - a pre-computed `Uint8Array` blob (advanced / off-chain computed), OR
+ *   - a plain-fields object `{ auditorViewingPubKey, tokenId, amount, commitment }`
+ *     which will be encrypted on the fly via `buildAuditorCiphertextForNote`.
+ *
+ * If both forms are supplied the explicit `Uint8Array` wins.
+ */
+export type AuditorCiphertextInput = Uint8Array | {
+    auditorViewingPubKey: Uint8Array;
+    tokenId: bigint;
+    amount: bigint;
+    commitment: Uint8Array;
+};
+export declare function resolveAuditorCiphertext(input: AuditorCiphertextInput): Uint8Array;
+/**
+ * Decrypt an auditor ciphertext blob using the auditor's Ed25519 viewing private key.
+ *
+ * @param auditorViewingPrivKey - 32-byte Ed25519 private key of the auditor
+ * @param blob                  - 112-byte blob from `encryptAuditorCiphertext`
+ * @param commitment            - 32-byte note commitment (must match AAD used during encrypt)
+ * @returns decrypted plain, or null on any failure (wrong key, wrong commitment, corrupt)
+ */
+export declare function decryptAuditorCiphertext(auditorViewingPrivKey: Uint8Array, blob: Uint8Array, commitment: Uint8Array): AuditorNotePlain | null;

package/packages/sdk/dist/auditor-ciphertext.js

@@ -0,0 +1,135 @@
+/**
+ * Auditor ciphertext — ECDH encrypt-to-auditor for Method-Y permissioned pools.
+ *
+ * Lets a depositor encrypt note viewing data (tokenId, amount) TO a permissioned-pool
+ * auditor's Ed25519 viewing PUBLIC key. Only the auditor's private key can decrypt.
+ *
+ * Cipher: X25519 ECDH key-agreement + XChaCha20-Poly1305 AEAD.
+ *
+ * Wire format (112 bytes):
+ *   eph_pub        :: 32 bytes  (ephemeral X25519 public key)
+ *   nonce          :: 24 bytes  (random XChaCha20 nonce)
+ *   ciphertext_tag :: 56 bytes  (encrypted tokenId(32 BE) || amount(8 LE) + Poly1305 tag(16))
+ */
+import { xchacha20poly1305 } from "@noble/ciphers/chacha.js";
+import { sha256 } from "@noble/hashes/sha2.js";
+import { x25519 } from "@noble/curves/ed25519.js";
+import { ed25519PubToX25519, ed25519PrivToX25519, x25519PubFromPriv, } from "./crypto-ed25519";
+const DOMAIN = new TextEncoder().encode("utxopia.auditor-ciphertext.v1");
+const EPH_PUB_BYTES = 32;
+const NONCE_BYTES = 24;
+const PLAINTEXT_BYTES = 40; // tokenId(32) + amount(8)
+const TAG_BYTES = 16;
+const CT_WITH_TAG_BYTES = PLAINTEXT_BYTES + TAG_BYTES; // 56
+export const AUDITOR_CIPHERTEXT_BYTES = EPH_PUB_BYTES + NONCE_BYTES + CT_WITH_TAG_BYTES; // 112
+function deriveKey(shared) {
+    const buf = new Uint8Array(shared.length + DOMAIN.length);
+    buf.set(shared, 0);
+    buf.set(DOMAIN, shared.length);
+    return sha256(buf);
+}
+function packPlaintext(plain) {
+    const out = new Uint8Array(PLAINTEXT_BYTES);
+    // tokenId: 32 bytes big-endian
+    let t = plain.tokenId;
+    for (let i = 31; i >= 0; i--) {
+        out[i] = Number(t & 0xffn);
+        t >>= 8n;
+    }
+    if (t !== 0n)
+        throw new RangeError("tokenId exceeds 256 bits");
+    // amount: 8 bytes little-endian
+    let a = plain.amount;
+    for (let i = 0; i < 8; i++) {
+        out[32 + i] = Number(a & 0xffn);
+        a >>= 8n;
+    }
+    if (a !== 0n)
+        throw new RangeError("amount exceeds 64 bits");
+    return out;
+}
+function unpackPlaintext(bytes) {
+    let tokenId = 0n;
+    for (let i = 0; i < 32; i++)
+        tokenId = (tokenId << 8n) | BigInt(bytes[i]);
+    let amount = 0n;
+    for (let i = 7; i >= 0; i--)
+        amount = (amount << 8n) | BigInt(bytes[32 + i]);
+    return { tokenId, amount };
+}
+/**
+ * Encrypt note viewing data to an auditor's Ed25519 viewing public key.
+ *
+ * @param auditorViewingPubKey - 32-byte Ed25519 public key of the auditor
+ * @param plain                - tokenId + amount to encrypt
+ * @param commitment           - 32-byte note commitment (AAD — binds blob to note)
+ * @param ephemeralPriv        - optional 32-byte X25519 private key (random if omitted)
+ * @returns 112-byte blob: eph_pub(32) || nonce(24) || ciphertextWithTag(56)
+ */
+export function encryptAuditorCiphertext(auditorViewingPubKey, plain, commitment, ephemeralPriv) {
+    if (auditorViewingPubKey.length !== 32)
+        throw new Error("auditorViewingPubKey must be 32 bytes");
+    if (commitment.length !== 32)
+        throw new Error("commitment must be 32 bytes");
+    const ephPriv = ephemeralPriv ?? crypto.getRandomValues(new Uint8Array(32));
+    const ephPub = x25519PubFromPriv(ephPriv);
+    const auditorX = ed25519PubToX25519(auditorViewingPubKey);
+    const shared = x25519.getSharedSecret(ephPriv, auditorX);
+    const key = deriveKey(shared);
+    const nonce = crypto.getRandomValues(new Uint8Array(NONCE_BYTES));
+    const aead = xchacha20poly1305(key, nonce, commitment);
+    const ciphertextWithTag = aead.encrypt(packPlaintext(plain));
+    const blob = new Uint8Array(AUDITOR_CIPHERTEXT_BYTES);
+    blob.set(ephPub, 0);
+    blob.set(nonce, EPH_PUB_BYTES);
+    blob.set(ciphertextWithTag, EPH_PUB_BYTES + NONCE_BYTES);
+    return blob;
+}
+/**
+ * Convenience wrapper: build a 112-byte auditor ciphertext blob from note fields.
+ *
+ * Thin wrapper over {@link encryptAuditorCiphertext} for callers who have the raw
+ * note fields (tokenId, amount, commitment) rather than a pre-packed `AuditorNotePlain`.
+ *
+ * @param input.auditorViewingPubKey - 32-byte Ed25519 public key of the auditor
+ * @param input.tokenId              - token id (field element, fits in 256 bits)
+ * @param input.amount               - note amount (≤ 64 bits)
+ * @param input.commitment           - 32-byte note commitment (binds ciphertext to note)
+ * @returns 112-byte blob: eph_pub(32) || nonce(24) || ciphertextWithTag(56)
+ */
+export function buildAuditorCiphertextForNote(input) {
+    return encryptAuditorCiphertext(input.auditorViewingPubKey, { tokenId: input.tokenId, amount: input.amount }, input.commitment);
+}
+export function resolveAuditorCiphertext(input) {
+    if (input instanceof Uint8Array)
+        return input;
+    return buildAuditorCiphertextForNote(input);
+}
+/**
+ * Decrypt an auditor ciphertext blob using the auditor's Ed25519 viewing private key.
+ *
+ * @param auditorViewingPrivKey - 32-byte Ed25519 private key of the auditor
+ * @param blob                  - 112-byte blob from `encryptAuditorCiphertext`
+ * @param commitment            - 32-byte note commitment (must match AAD used during encrypt)
+ * @returns decrypted plain, or null on any failure (wrong key, wrong commitment, corrupt)
+ */
+export function decryptAuditorCiphertext(auditorViewingPrivKey, blob, commitment) {
+    if (blob.length !== AUDITOR_CIPHERTEXT_BYTES)
+        return null;
+    if (commitment.length !== 32)
+        return null;
+    const ephPub = blob.slice(0, EPH_PUB_BYTES);
+    const nonce = blob.slice(EPH_PUB_BYTES, EPH_PUB_BYTES + NONCE_BYTES);
+    const ciphertextWithTag = blob.slice(EPH_PUB_BYTES + NONCE_BYTES);
+    try {
+        const auditorXPriv = ed25519PrivToX25519(auditorViewingPrivKey);
+        const shared = x25519.getSharedSecret(auditorXPriv, ephPub);
+        const key = deriveKey(shared);
+        const aead = xchacha20poly1305(key, nonce, commitment);
+        const plaintext = aead.decrypt(ciphertextWithTag);
+        return unpackPlaintext(plaintext);
+    }
+    catch {
+        return null;
+    }
+}

package/packages/sdk/dist/auditor.d.ts

@@ -0,0 +1,115 @@
+/**
+ * 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 { type OnChainStealthAnnouncement } from "./stealth";
+import { type DelegatedViewKey } from "./keys";
+import { type SenderMemoCiphertext } from "./sender-memo";
+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;
+}
+/**
+ * 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 declare function auditScan(key: DelegatedViewKey, announcements: ReadonlyArray<AuditScanAnnouncement>, options: AuditScanOptions): Promise<AuditScanSummary>;
+/**
+ * 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 declare function auditScanCiphertexts(auditorViewingPrivKey: Uint8Array, ciphertexts: ReadonlyArray<{
+    commitment: Uint8Array;
+    blob: Uint8Array;
+    slot?: number;
+    blockTime?: number;
+}>, options?: {
+    tokenIds?: bigint[];
+    fromSlot?: number;
+    toSlot?: number;
+}): Promise<AuditScanSummary>;
+/**
+ * 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 declare function auditRecordsToCsv(records: ReadonlyArray<AuditRecord>): string;

package/packages/sdk/dist/auditor.js

@@ -0,0 +1,292 @@
+/**
+ * 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, } from "./stealth";
+import { babyJubDecompress, bytesToHex } from "./crypto";
+import { ViewPermissions, hasPermission, isDelegatedKeyValid, isSlotInDelegatedRange, } from "./keys";
+import { decryptSenderMemo } from "./sender-memo";
+import { decryptAuditorCiphertext } from "./auditor-ciphertext";
+// Range intersection: undefined means unbounded on that side.
+function intersectLower(a, b) {
+    if (a == null)
+        return b;
+    if (b == null)
+        return a;
+    return Math.max(a, b);
+}
+function intersectUpper(a, b) {
+    if (a == null)
+        return b;
+    if (b == null)
+        return a;
+    return Math.min(a, b);
+}
+function buildAuditorVisibleRecord(plain, commitment, slot, blockTime) {
+    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, announcements, options) {
+    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 = {
+        ...key,
+        fromSlot: effectiveFromSlot,
+        toSlot: effectiveToSlot,
+    };
+    let outOfRangeSkipped = 0;
+    let unscopedSkipped = 0;
+    const inScope = [];
+    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 = {
+        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 = [];
+    const seenLeafIndex = new Set();
+    // 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();
+    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, ciphertexts, options) {
+    const records = [];
+    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) {
+    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/packages/sdk/dist/bitcoin/ika.d.ts

@@ -0,0 +1,47 @@
+/**
+ * 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.
+ */
+/**
+ * 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;
+} | {
+    type: "literal-compressed";
+    compressedPubkey: Uint8Array;
+} | {
+    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 declare function deriveCustodyAddressFromIkaDWallet(ref: IkaDWalletRef, network: "mainnet" | "testnet" | "regtest"): string;
+/**
+ * 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 declare function deriveRawXOnlyP2TRAddress(xonlyPubkey: Uint8Array, network: "mainnet" | "testnet" | "regtest"): string;