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

package/src/sender-memo.ts

@@ -0,0 +1,343 @@
+/**
+ * Sender memo channel (Phase 2 — regulator-grade tamper detection)
+ *
+ * Outputs of a `transact` call are encrypted to the *recipient's* viewing
+ * key, so the sender can't recover their own outgoing history from chain
+ * data alone. Sender memos close that gap: an opt-in second event per
+ * output, encrypted with a derived **outgoing viewing key** (`ovk`) so the
+ * sender (or an auditor holding the right key material) can later
+ * reconstruct what was sent.
+ *
+ * ## Cipher: XChaCha20-Poly1305 AEAD
+ *
+ * Chosen over plain XOR for **regulator-grade tamper detection**: the
+ * Poly1305 tag fails crisply on any bit flip in the ciphertext, the nonce,
+ * the key, or the AAD. With 24-byte random nonces collisions are
+ * astronomically unlikely, so callers don't have to coordinate uniqueness.
+ * Same family as Railgun / Zcash Sapling note encryption.
+ *
+ * `ovk = SHA-256(viewingPrivKey || "utxopia.ovk.v1")` — Sapling-style
+ * outgoing viewing key. Currently a one-way derivation from
+ * `viewingPrivKey`; a v2 refactor will derive both `ivk` and `ovk` from a
+ * master `mvk` so the two can be granted independently for true
+ * incoming/outgoing privilege separation.
+ *
+ * ## Wire format (matches `emit_sender_memo` in `events.rs`)
+ *
+ *   nonce              :: 24 bytes (random, fresh per memo — XChaCha extended)
+ *   ciphertext_and_tag :: 56 bytes (encrypted tokenId(32) || amount(8) + Poly1305 tag(16))
+ *   commitment         :: 32 bytes (plaintext — join key, also AAD)
+ *   leaf_index_le      ::  4 bytes (plaintext — same)
+ *   ─────────────────────────────────
+ *   total              :: 116 bytes
+ *
+ * The AAD `commitment || leafIndex_LE` binds the seal to the memo's tree
+ * leaf. An attacker who lifts a memo onto a different output → AAD
+ * mismatch → tag fails → decryption returns null. Crisp move-the-memo
+ * protection, unlike the probabilistic version we had with XOR.
+ */
+
+import { xchacha20poly1305 } from "@noble/ciphers/chacha.js";
+import { sha256 } from "@noble/hashes/sha2.js";
+
+/** Bytes of the XChaCha20 24-byte nonce. */
+export const SENDER_MEMO_NONCE_BYTES = 24;
+/** Bytes of the encrypted ciphertext + Poly1305 tag (token(32) + amount(8) + tag(16)). */
+export const SENDER_MEMO_CIPHERTEXT_BYTES = 56;
+/** Plaintext token-id bytes inside the ciphertext. */
+export const SENDER_MEMO_TOKEN_BYTES = 32;
+/** Plaintext amount bytes inside the ciphertext. */
+export const SENDER_MEMO_AMOUNT_BYTES = 8;
+/** Bytes of the Poly1305 tag. */
+export const SENDER_MEMO_TAG_BYTES = 16;
+/** Bytes of the commitment field (plaintext, AAD). */
+export const SENDER_MEMO_COMMITMENT_BYTES = 32;
+/** Bytes of the leaf-index field (plaintext LE u32, AAD). */
+export const SENDER_MEMO_LEAF_INDEX_BYTES = 4;
+/** Total bytes of a packed sender memo. */
+export const SENDER_MEMO_PACKED_BYTES =
+  SENDER_MEMO_NONCE_BYTES +
+  SENDER_MEMO_CIPHERTEXT_BYTES +
+  SENDER_MEMO_COMMITMENT_BYTES +
+  SENDER_MEMO_LEAF_INDEX_BYTES;
+
+/** Domain separator for ovk derivation. */
+const OVK_DOMAIN = new TextEncoder().encode("utxopia.ovk.v1");
+
+/** Plaintext memo. */
+export interface SenderMemoPlain {
+  tokenId: bigint;
+  amount: bigint;
+}
+
+/** Encrypted memo with associated chain context. */
+export interface SenderMemoCiphertext {
+  /** 24-byte XChaCha20 nonce. */
+  nonce: Uint8Array;
+  /** 56-byte ChaCha20-encrypted (tokenId(32) || amount(8)) + Poly1305 tag(16). */
+  ciphertextWithTag: Uint8Array;
+  /** 32-byte commitment of the output this memo covers (plaintext + AAD). */
+  commitment: Uint8Array;
+  /** Leaf index of the covered output (plaintext + AAD). */
+  leafIndex: number;
+}
+
+/**
+ * Derive the outgoing viewing key (`ovk`) from a viewing private key.
+ *
+ *   ovk = SHA-256(viewingPrivKey || "utxopia.ovk.v1")
+ *
+ * Currently derivable from `viewingPrivKey`, so possession of the viewing
+ * key implies possession of `ovk`. A future v2 refactor will derive `ivk`
+ * and `ovk` independently from a master `mvk`, allowing true incoming-only
+ * vs outgoing-only audit delegation.
+ */
+export function deriveOutgoingViewingKey(viewingPrivKey: Uint8Array): Uint8Array {
+  if (viewingPrivKey.length !== 32) {
+    throw new Error(`viewingPrivKey must be 32 bytes; got ${viewingPrivKey.length}`);
+  }
+  const buf = new Uint8Array(viewingPrivKey.length + OVK_DOMAIN.length);
+  buf.set(viewingPrivKey, 0);
+  buf.set(OVK_DOMAIN, viewingPrivKey.length);
+  return sha256(buf);
+}
+
+/**
+ * Generate a fresh 24-byte XChaCha20 nonce. Exposed so callers can
+ * pre-allocate nonces if they need deterministic ordering across outputs.
+ */
+export function generateSenderMemoNonce(): Uint8Array {
+  const nonce = new Uint8Array(SENDER_MEMO_NONCE_BYTES);
+  crypto.getRandomValues(nonce);
+  return nonce;
+}
+
+/**
+ * Encrypt a sender memo. The returned ciphertext is meant to be embedded
+ * in the program's instruction data alongside the recipient announcement,
+ * then emitted on-chain via `emit_sender_memo`.
+ */
+export function encryptSenderMemo(
+  viewingPrivKey: Uint8Array,
+  plain: SenderMemoPlain,
+  ctx: { commitment: Uint8Array; leafIndex: number },
+  nonce: Uint8Array = generateSenderMemoNonce(),
+): SenderMemoCiphertext {
+  if (nonce.length !== SENDER_MEMO_NONCE_BYTES) {
+    throw new Error(`nonce must be ${SENDER_MEMO_NONCE_BYTES} bytes`);
+  }
+  if (ctx.commitment.length !== SENDER_MEMO_COMMITMENT_BYTES) {
+    throw new Error(`commitment must be ${SENDER_MEMO_COMMITMENT_BYTES} bytes`);
+  }
+
+  const ovk = deriveOutgoingViewingKey(viewingPrivKey);
+  const aad = buildAAD(ctx.commitment, ctx.leafIndex);
+  const plaintext = packPlaintext(plain);
+
+  const aead = xchacha20poly1305(ovk, nonce, aad);
+  const ciphertextWithTag = aead.encrypt(plaintext);
+
+  if (ciphertextWithTag.length !== SENDER_MEMO_CIPHERTEXT_BYTES) {
+    throw new Error(
+      `internal error: AEAD produced ${ciphertextWithTag.length} bytes, expected ${SENDER_MEMO_CIPHERTEXT_BYTES}`,
+    );
+  }
+
+  return {
+    nonce: new Uint8Array(nonce),
+    ciphertextWithTag,
+    commitment: new Uint8Array(ctx.commitment),
+    leafIndex: ctx.leafIndex,
+  };
+}
+
+/**
+ * Decrypt a sender memo. Returns `null` when the Poly1305 tag fails
+ * (wrong key, tampered ciphertext, swapped AAD) or the ciphertext is
+ * structurally malformed. Callers should treat both as "not for me / corrupt"
+ * rather than fatal — this is the crisp tamper-detection signal AEAD provides.
+ */
+export function decryptSenderMemo(
+  viewingPrivKey: Uint8Array,
+  memo: SenderMemoCiphertext,
+): SenderMemoPlain | null {
+  if (
+    memo.nonce.length !== SENDER_MEMO_NONCE_BYTES ||
+    memo.ciphertextWithTag.length !== SENDER_MEMO_CIPHERTEXT_BYTES ||
+    memo.commitment.length !== SENDER_MEMO_COMMITMENT_BYTES
+  ) {
+    return null;
+  }
+
+  const ovk = deriveOutgoingViewingKey(viewingPrivKey);
+  const aad = buildAAD(memo.commitment, memo.leafIndex);
+
+  let plaintext: Uint8Array;
+  try {
+    const aead = xchacha20poly1305(ovk, memo.nonce, aad);
+    plaintext = aead.decrypt(memo.ciphertextWithTag);
+  } catch {
+    return null; // tag failure → wrong key, corrupted ciphertext, or AAD mismatch
+  }
+  return unpackPlaintext(plaintext);
+}
+
+/**
+ * Serialize a memo as its 116-byte on-chain payload.
+ *
+ * Layout: nonce(24) ‖ ciphertextWithTag(56) ‖ commitment(32) ‖ leafIndex(4)
+ */
+export function packSenderMemo(memo: SenderMemoCiphertext): Uint8Array {
+  const out = new Uint8Array(SENDER_MEMO_PACKED_BYTES);
+  let off = 0;
+  out.set(memo.nonce, off);
+  off += SENDER_MEMO_NONCE_BYTES;
+  out.set(memo.ciphertextWithTag, off);
+  off += SENDER_MEMO_CIPHERTEXT_BYTES;
+  out.set(memo.commitment, off);
+  off += SENDER_MEMO_COMMITMENT_BYTES;
+  new DataView(out.buffer, out.byteOffset + off, SENDER_MEMO_LEAF_INDEX_BYTES).setUint32(
+    0,
+    memo.leafIndex,
+    true,
+  );
+  return out;
+}
+
+/**
+ * Pack a memo into the 80-byte instruction-data layout that `transact` reads:
+ * `nonce(24) || ciphertext_and_tag(56)`. `commitment` and `leafIndex` are
+ * filled in by the program from the public commitments + tree insertion
+ * result, so they're omitted from the instruction-data form.
+ */
+export function packSenderMemoForInstruction(memo: SenderMemoCiphertext): Uint8Array {
+  const out = new Uint8Array(SENDER_MEMO_NONCE_BYTES + SENDER_MEMO_CIPHERTEXT_BYTES);
+  out.set(memo.nonce, 0);
+  out.set(memo.ciphertextWithTag, SENDER_MEMO_NONCE_BYTES);
+  return out;
+}
+
+/**
+ * Per-output input for {@link buildSenderMemosForTransact}.
+ *
+ * - `tokenId` / `amount` are the plaintext payload that lands in the memo.
+ * - `commitment` is the 32-byte output commitment for this leaf — must match
+ *   exactly what the program inserts (it's AAD).
+ * - `leafIndex` is the predicted on-chain leaf index for this output. Get it
+ *   by reading the commitment tree's `next_leaf_index` before signing and
+ *   incrementing for each output in order. If the tx races with another
+ *   `transact` that inserts first, decryption will fail (the AAD won't
+ *   match) — callers should be prepared to skip the failed memo on read
+ *   rather than treat it as fatal.
+ */
+export interface SenderMemoOutput {
+  tokenId: bigint;
+  amount: bigint;
+  commitment: Uint8Array;
+  leafIndex: number;
+}
+
+/**
+ * Build the per-output 80-byte sender-memo slices for a `transact` call.
+ *
+ * Returns one `Uint8Array` per output, each containing
+ * `nonce(24) || ciphertext_and_tag(56)`. Pass the result directly to
+ * {@link buildTransactInstructionData} as `senderMemos`.
+ *
+ * The program emits the commitment + leaf index back as part of
+ * `emit_sender_memo`, so they're omitted from the instruction-data form —
+ * but they remain bound via AAD, so a relayer can't lift a memo onto a
+ * different output.
+ */
+export function buildSenderMemosForTransact(
+  viewingPrivKey: Uint8Array,
+  outputs: ReadonlyArray<SenderMemoOutput>,
+): Uint8Array[] {
+  const out: Uint8Array[] = new Array(outputs.length);
+  for (let i = 0; i < outputs.length; i++) {
+    const o = outputs[i];
+    if (o.commitment.length !== SENDER_MEMO_COMMITMENT_BYTES) {
+      throw new Error(
+        `output ${i} commitment must be ${SENDER_MEMO_COMMITMENT_BYTES} bytes; got ${o.commitment.length}`,
+      );
+    }
+    if (!Number.isInteger(o.leafIndex) || o.leafIndex < 0 || o.leafIndex > 0xffffffff) {
+      throw new RangeError(`output ${i} leafIndex must be a u32; got ${o.leafIndex}`);
+    }
+    const memo = encryptSenderMemo(
+      viewingPrivKey,
+      { tokenId: o.tokenId, amount: o.amount },
+      { commitment: o.commitment, leafIndex: o.leafIndex },
+    );
+    out[i] = packSenderMemoForInstruction(memo);
+  }
+  return out;
+}
+
+/** Deserialize a 116-byte packed memo. */
+export function unpackSenderMemo(bytes: Uint8Array): SenderMemoCiphertext {
+  if (bytes.length !== SENDER_MEMO_PACKED_BYTES) {
+    throw new Error(
+      `packed sender memo must be ${SENDER_MEMO_PACKED_BYTES} bytes; got ${bytes.length}`,
+    );
+  }
+  let off = 0;
+  const nonce = bytes.slice(off, off + SENDER_MEMO_NONCE_BYTES);
+  off += SENDER_MEMO_NONCE_BYTES;
+  const ciphertextWithTag = bytes.slice(off, off + SENDER_MEMO_CIPHERTEXT_BYTES);
+  off += SENDER_MEMO_CIPHERTEXT_BYTES;
+  const commitment = bytes.slice(off, off + SENDER_MEMO_COMMITMENT_BYTES);
+  off += SENDER_MEMO_COMMITMENT_BYTES;
+  const leafIndex = new DataView(
+    bytes.buffer,
+    bytes.byteOffset + off,
+    SENDER_MEMO_LEAF_INDEX_BYTES,
+  ).getUint32(0, true);
+  return { nonce, ciphertextWithTag, commitment, leafIndex };
+}
+
+// ---------------------------------------------------------------------------
+// Internal helpers
+// ---------------------------------------------------------------------------
+
+function buildAAD(commitment: Uint8Array, leafIndex: number): Uint8Array {
+  const aad = new Uint8Array(
+    SENDER_MEMO_COMMITMENT_BYTES + SENDER_MEMO_LEAF_INDEX_BYTES,
+  );
+  aad.set(commitment, 0);
+  new DataView(
+    aad.buffer,
+    aad.byteOffset + SENDER_MEMO_COMMITMENT_BYTES,
+    SENDER_MEMO_LEAF_INDEX_BYTES,
+  ).setUint32(0, leafIndex, true);
+  return aad;
+}
+
+function packPlaintext(plain: SenderMemoPlain): Uint8Array {
+  const out = new Uint8Array(SENDER_MEMO_TOKEN_BYTES + SENDER_MEMO_AMOUNT_BYTES);
+  // tokenId big-endian in first 32 bytes
+  let t = plain.tokenId;
+  for (let i = SENDER_MEMO_TOKEN_BYTES - 1; i >= 0; i--) {
+    out[i] = Number(t & 0xffn);
+    t >>= 8n;
+  }
+  if (t !== 0n) throw new RangeError("tokenId exceeds 256 bits");
+  // amount little-endian u64 in last 8 bytes
+  let a = plain.amount;
+  for (let i = 0; i < SENDER_MEMO_AMOUNT_BYTES; i++) {
+    out[SENDER_MEMO_TOKEN_BYTES + i] = Number(a & 0xffn);
+    a >>= 8n;
+  }
+  if (a !== 0n) throw new RangeError("amount exceeds 64 bits");
+  return out;
+}
+
+function unpackPlaintext(bytes: Uint8Array): SenderMemoPlain {
+  let tokenId = 0n;
+  for (let i = 0; i < SENDER_MEMO_TOKEN_BYTES; i++) tokenId = (tokenId << 8n) | BigInt(bytes[i]);
+  let amount = 0n;
+  for (let i = SENDER_MEMO_AMOUNT_BYTES - 1; i >= 0; i--) {
+    amount = (amount << 8n) | BigInt(bytes[SENDER_MEMO_TOKEN_BYTES + i]);
+  }
+  return { tokenId, amount };
+}

package/src/snarkjs.d.ts

@@ -0,0 +1,19 @@
+declare module "snarkjs" {
+  const groth16: {
+    fullProve(
+      input: Record<string, any>,
+      wasmFile: string | Uint8Array,
+      zkeyFile: string | Uint8Array
+    ): Promise<{ proof: any; publicSignals: string[] }>;
+    verify(
+      vkey: any,
+      publicSignals: string[],
+      proof: any
+    ): Promise<boolean>;
+    exportSolidityCallData(
+      proof: any,
+      publicSignals: string[]
+    ): Promise<string>;
+  };
+  export { groth16 };
+}

package/src/sns-resolver.ts

@@ -0,0 +1,333 @@
+/**
+ * SNS Subdomain Resolver for Stealth Addresses
+ *
+ * Resolves `<name>.utxopia.sol` (or configured parent domain) to stealth
+ * address keys stored in the SNS name record data field.
+ *
+ * On-chain data layout (after 96-byte SNS header):
+ *   version(1) + viewingPubKey(32) + mpk(32) = 65 bytes
+ *
+ * - viewingPubKey: Ed25519 public key (for X25519 ECDH)
+ * - mpk:          Master Public Key = Poseidon(spendingPub.x, spendingPub.y, nullifyingKey)
+ *
+ * These two keys are all a sender needs to create a stealth deposit.
+ * spendingPubKey is NOT stored — senders never use it.
+ *
+ * @module sns-resolver
+ */
+
+import { getConfig } from "./config";
+import type { ConnectionAdapter } from "./stealth";
+import { sha256Hash } from "./crypto";
+
+// ========== Constants ==========
+
+/** SNS name record header size (parent:32 + owner:32 + class:32) */
+const SNS_HEADER_SIZE = 96;
+
+/** Stealth data size: version(1) + viewingPubKey(32) + mpk(32) = 65 bytes */
+export const SNS_STEALTH_DATA_SIZE = 65;
+
+/** SNS hash prefix used for PDA derivation */
+const HASH_PREFIX = "SPL Name Service";
+
+// ========== Types ==========
+
+export interface SnsStealthAddress {
+  /** The subdomain name (e.g., "alice") */
+  name: string;
+
+  /** Full domain (e.g., "alice.utxopia.sol") */
+  fullDomain: string;
+
+  /** Ed25519 viewing public key (32 bytes) — for X25519 ECDH */
+  viewingPubKey: Uint8Array;
+
+  /** Master public key: Poseidon(spendingPub.x, spendingPub.y, nullifyingKey) (32 bytes) — for NPK derivation */
+  mpk: Uint8Array;
+
+  /** Data version read from the record */
+  version: number;
+
+  /**
+   * Compliance flag bits the recipient has self-published. Defaults to 0
+   * when the SNS record only carries the base 65-byte stealth payload.
+   * Check via {@link SnsComplianceFlags} / {@link isAuditorDisclosable}.
+   */
+  complianceFlags: number;
+
+  /**
+   * Optional 32-byte Solana pubkey of the recipient's designated auditor.
+   * Present only when the record carries the v2 compliance bytes
+   * (flag + 32-byte pubkey, 33 bytes total after the 65-byte stealth payload).
+   * Senders treat this as a hint about who the recipient discloses to —
+   * the actual DelegatedViewKey delivery is still out-of-band.
+   */
+  auditorPubkey?: Uint8Array;
+}
+
+/**
+ * Bit-flags a recipient can opt into on their SNS subdomain. The byte sits
+ * at offset 65 of the stealth payload (i.e. byte 161 of the on-chain
+ * account, after the 96-byte SNS header). Absent → all bits 0.
+ */
+export const SnsComplianceFlags = {
+  /**
+   * Recipient is "auditor-disclosable by default" — they've signalled to
+   * senders that they're OK receiving outgoing audit memos, and likely
+   * already share a `DelegatedViewKey` with a designated auditor
+   * out-of-band.
+   */
+  AUDITOR_DISCLOSABLE: 1 << 0,
+} as const;
+
+/** Returns true if the recipient has set the AUDITOR_DISCLOSABLE bit. */
+export function isAuditorDisclosable(addr: SnsStealthAddress): boolean {
+  return (addr.complianceFlags & SnsComplianceFlags.AUDITOR_DISCLOSABLE) !== 0;
+}
+
+/**
+ * Total bytes of the stealth payload's compliance extension when both
+ * pieces are present:
+ *   [byte 65]      complianceFlags (u8)
+ *   [bytes 66..97] auditorPubkey   (32-byte Solana pubkey)
+ *
+ * Records may carry only the base 65-byte payload, the payload plus
+ * `complianceFlags`, or the payload plus `complianceFlags` and `auditorPubkey`.
+ */
+export const SNS_COMPLIANCE_AUDITOR_OFFSET = 66;
+export const SNS_COMPLIANCE_AUDITOR_BYTES = 32;
+
+// ========== PDA Derivation ==========
+
+/**
+ * Hash a name for SNS PDA derivation (SHA256 of HASH_PREFIX + name)
+ */
+function hashSnsName(name: string): Uint8Array {
+  const input = HASH_PREFIX + name;
+  return sha256Hash(new TextEncoder().encode(input));
+}
+
+// ========== PDA Derivation (internal) ==========
+
+/**
+ * Derive the SNS key for a parent domain (e.g., "utxopia.sol")
+ */
+export async function deriveParentDomainKey(parentDomain: string): Promise<string> {
+  const { address, getProgramDerivedAddress, getAddressEncoder } = await import("@solana/kit");
+  const config = getConfig();
+
+  if (!config.snsRootDomain) {
+    throw new Error("SNS root domain not configured for this network");
+  }
+
+  const hashedParent = hashSnsName(parentDomain);
+  const encoder = getAddressEncoder();
+
+  const [pda] = await getProgramDerivedAddress({
+    seeds: [
+      hashedParent,
+      new Uint8Array(32), // no class
+      new Uint8Array(encoder.encode(address(config.snsRootDomain))),
+    ],
+    programAddress: address(config.snsNameServiceProgramId),
+  });
+
+  return pda;
+}
+
+/**
+ * Derive the SNS key for a subdomain (e.g., "alice" under "utxopia.sol")
+ *
+ * Seeds: [hash("SPL Name Service" + "\0" + name), zeros(32), parentKey]
+ */
+async function deriveSubdomainKey(
+  subdomain: string,
+  parentKey: string,
+): Promise<string> {
+  const { address, getProgramDerivedAddress, getAddressEncoder } = await import("@solana/kit");
+  const config = getConfig();
+
+  const hashedSub = hashSnsName("\0" + subdomain);
+  const encoder = getAddressEncoder();
+
+  const [pda] = await getProgramDerivedAddress({
+    seeds: [
+      hashedSub,
+      new Uint8Array(32), // no class
+      new Uint8Array(encoder.encode(address(parentKey))),
+    ],
+    programAddress: address(config.snsNameServiceProgramId),
+  });
+
+  return pda;
+}
+
+// ========== Parsing ==========
+
+/**
+ * Parse stealth address data from an SNS name record.
+ *
+ * Supports the current format:
+ * - Base (65 bytes, version 2): version(1) + viewingPubKey(32) + mpk(32)
+ *
+ * Optional trailing byte (offset 65 of the stealth payload, byte 161 of the
+ * account) carries `complianceFlags: u8` — see {@link SnsComplianceFlags}.
+ * When absent, the parsed result has `complianceFlags = 0`.
+ *
+ * @param accountData - Raw account data (including 96-byte header)
+ * @returns Parsed stealth keys + compliance flags, or null if invalid
+ */
+export function parseSnsStealthData(
+  accountData: Uint8Array,
+):
+  | {
+      viewingPubKey: Uint8Array;
+      mpk: Uint8Array;
+      version: number;
+      complianceFlags: number;
+      auditorPubkey?: Uint8Array;
+    }
+  | null {
+  // Need at least header + 65 bytes of stealth data
+  if (accountData.length < SNS_HEADER_SIZE + SNS_STEALTH_DATA_SIZE) {
+    return null;
+  }
+
+  const data = accountData.slice(SNS_HEADER_SIZE);
+  const version = data[0];
+  const allZero = (buf: Uint8Array) => buf.every((b) => b === 0);
+
+  if (version !== 2) {
+    return null;
+  }
+
+  const viewingPubKey = data.slice(1, 33);
+  const mpk = data.slice(33, 65);
+
+  if (allZero(viewingPubKey) || allZero(mpk)) {
+    return null;
+  }
+
+  const complianceFlags =
+    data.length > SNS_STEALTH_DATA_SIZE ? data[SNS_STEALTH_DATA_SIZE] : 0;
+
+  let auditorPubkey: Uint8Array | undefined;
+  if (
+    data.length >= SNS_COMPLIANCE_AUDITOR_OFFSET + SNS_COMPLIANCE_AUDITOR_BYTES
+  ) {
+    const buf = data.slice(
+      SNS_COMPLIANCE_AUDITOR_OFFSET,
+      SNS_COMPLIANCE_AUDITOR_OFFSET + SNS_COMPLIANCE_AUDITOR_BYTES,
+    );
+    // All-zero pubkey means "no auditor set" — distinguishes from the
+    // case where a recipient flips the flag bit but skips the pubkey.
+    if (!allZero(buf)) {
+      auditorPubkey = new Uint8Array(buf);
+    }
+  }
+
+  return {
+    viewingPubKey: new Uint8Array(viewingPubKey),
+    mpk: new Uint8Array(mpk),
+    version,
+    complianceFlags,
+    auditorPubkey,
+  };
+}
+
+// ========== Resolution ==========
+
+/**
+ * Resolve a name to a stealth address via SNS subdomain.
+ *
+ * Accepts multiple formats:
+ *   - "alice"              → resolves alice.<parentDomain>.sol
+ *   - "alice.utxopia"       → resolves alice.utxopia.sol
+ *   - "alice.utxopia.sol"   → resolves alice.utxopia.sol
+ *
+ * @param connection - RPC connection adapter
+ * @param name - Name to resolve
+ * @returns Stealth address or null if not found / no stealth data
+ */
+export async function resolveSnsName(
+  connection: ConnectionAdapter,
+  name: string,
+): Promise<SnsStealthAddress | null> {
+  const config = getConfig();
+
+  if (!config.snsNameServiceProgramId || !config.snsParentDomain) {
+    return null; // SNS not configured
+  }
+
+  // Normalize: strip .sol and parent domain suffix
+  const parentDomain = config.snsParentDomain;
+  let subdomain = name.trim().toLowerCase();
+  if (subdomain.endsWith(".sol")) {
+    subdomain = subdomain.slice(0, -4);
+  }
+  if (subdomain.endsWith("." + parentDomain)) {
+    subdomain = subdomain.slice(0, -(parentDomain.length + 1));
+  }
+
+  if (!subdomain || subdomain.includes(".")) {
+    return null; // Invalid: either empty or has extra dots
+  }
+
+  try {
+    // Derive parent domain key
+    const parentKey = await deriveParentDomainKey(parentDomain);
+
+    // Derive subdomain key
+    const subKey = await deriveSubdomainKey(subdomain, parentKey);
+
+    // Fetch account
+    const accountInfo = await connection.getAccountInfo(subKey as any);
+    if (!accountInfo) {
+      return null;
+    }
+
+    // Parse stealth data
+    const parsed = parseSnsStealthData(new Uint8Array(accountInfo.data));
+    if (!parsed) {
+      return null;
+    }
+
+    const fullDomain = `${subdomain}.${parentDomain}.sol`;
+
+    return {
+      name: subdomain,
+      fullDomain,
+      viewingPubKey: parsed.viewingPubKey,
+      mpk: parsed.mpk,
+      version: parsed.version,
+      complianceFlags: parsed.complianceFlags,
+      auditorPubkey: parsed.auditorPubkey,
+    };
+  } catch (err) {
+    console.error(`Failed to resolve SNS name "${name}":`, err);
+    return null;
+  }
+}
+
+/**
+ * Resolve a stealth name via SNS subdomain.
+ *
+ * This is the unified resolver that the frontend should use.
+ * All names are resolved as SNS subdomains under the configured parent domain.
+ */
+export async function resolveStealthName(
+  connection: ConnectionAdapter,
+  name: string,
+): Promise<SnsStealthAddress | null> {
+  return resolveSnsName(connection, name);
+}
+
+/**
+ * Type guard to check if a resolved address is from SNS
+ */
+export function isSnsStealthAddress(
+  addr: SnsStealthAddress | unknown,
+): addr is SnsStealthAddress {
+  return typeof addr === "object" && addr !== null && "fullDomain" in addr;
+}