@utxopia/sdk 0.1.0-alpha.1

package/packages/sdk/dist/sender-memo.d.ts

@@ -0,0 +1,149 @@
+/**
+ * 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.
+ */
+/** Bytes of the XChaCha20 24-byte nonce. */
+export declare const SENDER_MEMO_NONCE_BYTES = 24;
+/** Bytes of the encrypted ciphertext + Poly1305 tag (token(32) + amount(8) + tag(16)). */
+export declare const SENDER_MEMO_CIPHERTEXT_BYTES = 56;
+/** Plaintext token-id bytes inside the ciphertext. */
+export declare const SENDER_MEMO_TOKEN_BYTES = 32;
+/** Plaintext amount bytes inside the ciphertext. */
+export declare const SENDER_MEMO_AMOUNT_BYTES = 8;
+/** Bytes of the Poly1305 tag. */
+export declare const SENDER_MEMO_TAG_BYTES = 16;
+/** Bytes of the commitment field (plaintext, AAD). */
+export declare const SENDER_MEMO_COMMITMENT_BYTES = 32;
+/** Bytes of the leaf-index field (plaintext LE u32, AAD). */
+export declare const SENDER_MEMO_LEAF_INDEX_BYTES = 4;
+/** Total bytes of a packed sender memo. */
+export declare const SENDER_MEMO_PACKED_BYTES: number;
+/** 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 declare function deriveOutgoingViewingKey(viewingPrivKey: Uint8Array): Uint8Array;
+/**
+ * Generate a fresh 24-byte XChaCha20 nonce. Exposed so callers can
+ * pre-allocate nonces if they need deterministic ordering across outputs.
+ */
+export declare function generateSenderMemoNonce(): Uint8Array;
+/**
+ * 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 declare function encryptSenderMemo(viewingPrivKey: Uint8Array, plain: SenderMemoPlain, ctx: {
+    commitment: Uint8Array;
+    leafIndex: number;
+}, nonce?: Uint8Array): SenderMemoCiphertext;
+/**
+ * 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 declare function decryptSenderMemo(viewingPrivKey: Uint8Array, memo: SenderMemoCiphertext): SenderMemoPlain | null;
+/**
+ * Serialize a memo as its 116-byte on-chain payload.
+ *
+ * Layout: nonce(24) ‖ ciphertextWithTag(56) ‖ commitment(32) ‖ leafIndex(4)
+ */
+export declare function packSenderMemo(memo: SenderMemoCiphertext): Uint8Array;
+/**
+ * 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 declare function packSenderMemoForInstruction(memo: SenderMemoCiphertext): Uint8Array;
+/**
+ * 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 declare function buildSenderMemosForTransact(viewingPrivKey: Uint8Array, outputs: ReadonlyArray<SenderMemoOutput>): Uint8Array[];
+/** Deserialize a 116-byte packed memo. */
+export declare function unpackSenderMemo(bytes: Uint8Array): SenderMemoCiphertext;

package/packages/sdk/dist/sender-memo.js

@@ -0,0 +1,250 @@
+/**
+ * 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");
+/**
+ * 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) {
+    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() {
+    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, plain, ctx, nonce = generateSenderMemoNonce()) {
+    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, memo) {
+    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;
+    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) {
+    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) {
+    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;
+}
+/**
+ * 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, outputs) {
+    const out = 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) {
+    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, leafIndex) {
+    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) {
+    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) {
+    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/packages/sdk/dist/sns-resolver.d.ts

@@ -0,0 +1,121 @@
+/**
+ * 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 type { ConnectionAdapter } from "./stealth";
+/** Stealth data size: version(1) + viewingPubKey(32) + mpk(32) = 65 bytes */
+export declare const SNS_STEALTH_DATA_SIZE = 65;
+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 declare 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.
+     */
+    readonly AUDITOR_DISCLOSABLE: number;
+};
+/** Returns true if the recipient has set the AUDITOR_DISCLOSABLE bit. */
+export declare function isAuditorDisclosable(addr: SnsStealthAddress): boolean;
+/**
+ * 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 declare const SNS_COMPLIANCE_AUDITOR_OFFSET = 66;
+export declare const SNS_COMPLIANCE_AUDITOR_BYTES = 32;
+/**
+ * Derive the SNS key for a parent domain (e.g., "utxopia.sol")
+ */
+export declare function deriveParentDomainKey(parentDomain: string): Promise<string>;
+/**
+ * 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 declare function parseSnsStealthData(accountData: Uint8Array): {
+    viewingPubKey: Uint8Array;
+    mpk: Uint8Array;
+    version: number;
+    complianceFlags: number;
+    auditorPubkey?: Uint8Array;
+} | null;
+/**
+ * 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 declare function resolveSnsName(connection: ConnectionAdapter, name: string): Promise<SnsStealthAddress | 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 declare function resolveStealthName(connection: ConnectionAdapter, name: string): Promise<SnsStealthAddress | null>;
+/**
+ * Type guard to check if a resolved address is from SNS
+ */
+export declare function isSnsStealthAddress(addr: SnsStealthAddress | unknown): addr is SnsStealthAddress;