@notrace/stealth-sdk 1.0.0

package/dist/index.d.cts

@@ -0,0 +1,325 @@
+/**
+ * Byte/scalar helpers shared across the SDK.
+ *
+ * Kept dependency-free — no `Buffer`, no `bigint-buffer`. Works in browser,
+ * Node 18+, Deno, and Bun without polyfills.
+ */
+/** Concatenate any number of byte arrays into a single Uint8Array. */
+declare function concatBytes(...arrs: Uint8Array[]): Uint8Array;
+/** Little-endian unsigned integer decode. */
+declare function bytesToNumberLE(bytes: Uint8Array): bigint;
+/** Little-endian unsigned integer encode to a fixed length. */
+declare function numberToBytesLE(n: bigint, len: number): Uint8Array;
+/** Compare two Uint8Arrays for byte equality. */
+declare function bytesEqual(a: Uint8Array, b: Uint8Array): boolean;
+
+/**
+ * Minimal base58 (Bitcoin/Solana alphabet) encoder/decoder.
+ *
+ * Zero-dep. Identical output to `bs58` and `@solana/web3.js` Address encoding.
+ */
+/** Encode a byte array to a base58 string. */
+declare function bs58encode(bytes: Uint8Array): string;
+/** Decode a base58 string back to bytes. Throws on invalid input. */
+declare function bs58decode(str: string): Uint8Array;
+
+/**
+ * Meta-keypair generation and seed derivation.
+ *
+ * A NoTrace identity is a single ed25519 keypair (the *meta-key*). Its public
+ * half is shared with payers — that's enough for them to derive a one-time
+ * stealth address. Its private half (the *view+spend scalar*) is what lets the
+ * recipient detect and claim incoming payments.
+ *
+ * Note: this is a non-hierarchical key. If you want separate view-only and
+ * spend keys, derive them upstream from your own master secret and pass the
+ * spend scalar in only when you need to sign.
+ */
+/** A meta-keypair. `seed` and `scalar` are *secret*; only `pub` is shareable. */
+interface MetaKey {
+    /** Original 32-byte random seed (kept for backup/export). */
+    seed: Uint8Array;
+    /** ed25519 scalar derived from the seed (in [0, L)). */
+    scalar: bigint;
+    /** 32-byte compressed ed25519 public point. Share this with payers. */
+    pub: Uint8Array;
+}
+/** Generate a fresh random meta-keypair using `crypto.getRandomValues`. */
+declare function generateMetaKey(): MetaKey;
+/**
+ * Deterministically derive a meta-keypair from a 32-byte seed.
+ *
+ * Performs the standard ed25519 clamping (RFC 8032 §5.1.5) so the scalar lands
+ * in a valid range. Same `seed` → same `pub` forever.
+ */
+declare function metaFromSeed(seed: Uint8Array): MetaKey;
+/** Recompute the public point for a given scalar. */
+declare function pubFromScalar(scalar: bigint): Uint8Array;
+
+/**
+ * Stealth-address derivation and recovery.
+ *
+ * The protocol is ECDH-on-ed25519 with a scalar-tweak — the same shape used by
+ * ERC-5564 and Umbra Cash, ported to Solana's native curve. Properties:
+ *
+ *   - Sender derives a stealth address from the recipient's published `meta_pub`.
+ *   - Sender CANNOT recover the stealth private key (would need `meta_scalar`).
+ *   - Recipient scans memos and applies their `meta_scalar` to detect payments.
+ *   - The stealth pub is a normal ed25519 point → a valid Solana address.
+ *
+ * The "version tag" included in the tweak makes the protocol forward-compatible:
+ * a future curve swap or hash change can ship a new tag without breaking
+ * existing wallets.
+ */
+/** Result of a sender-side derivation. */
+interface SenderDerivation {
+    /** The one-time stealth address (32-byte ed25519 pub) to send funds to. */
+    stealthPub: Uint8Array;
+    /** The ephemeral pub the sender must publish on-chain (e.g. in a memo). */
+    ephPub: Uint8Array;
+}
+/**
+ * SENDER side: derive a one-time stealth address from the recipient's meta-pub.
+ *
+ *     eph_scalar, eph_pub  = fresh ed25519 keypair
+ *     shared               = eph_scalar × meta_pub          (DH on ed25519)
+ *     tweak                = SHA512(ver ‖ shared ‖ eph_pub ‖ meta_pub) mod L
+ *     stealth_pub          = meta_pub + tweak × G            (point addition)
+ *
+ * The sender publishes `eph_pub`; only the holder of `meta_scalar` can both
+ * recover `stealth_scalar` and produce signatures over it.
+ *
+ * Safe to call from a hostile environment — no state is persisted.
+ */
+declare function deriveStealthSender(metaPubBytes: Uint8Array): SenderDerivation;
+/** Result of a recipient-side recovery — pub matches what the sender derived. */
+interface RecipientRecovery {
+    /** The recovered scalar — secret. Use this to sign sweeps. */
+    stealthScalar: bigint;
+    /** The recovered pub — compare against the on-chain destination. */
+    stealthPub: Uint8Array;
+}
+/**
+ * RECIPIENT side: given your meta-key and an ephemeral pub from a memo, recover
+ * the stealth keypair the sender derived.
+ *
+ *     shared        = meta_scalar × eph_pub                 (same point as sender's)
+ *     tweak         = SHA512(ver ‖ shared ‖ eph_pub ‖ meta_pub) mod L
+ *     stealth_scalar = (meta_scalar + tweak) mod L
+ *     stealth_pub   = stealth_scalar × G
+ *
+ * Compare the returned `stealthPub` against the SOL/SPL `destination` field of
+ * the transaction containing the memo. A match means the payment is yours.
+ */
+declare function recoverStealth(metaScalar: bigint, metaPubBytes: Uint8Array, ephPubBytes: Uint8Array): RecipientRecovery;
+
+/**
+ * ed25519 signing with a raw scalar (not a seed).
+ *
+ * Standard ed25519 sign-from-seed first hashes the seed and uses the upper half
+ * as a deterministic nonce. Our stealth scalars are *derived*, not seeded — so
+ * we use a Schnorr-style construction directly:
+ *
+ *     r = SHA512(prefix ‖ pub ‖ msg) mod L     where prefix is 32 fresh bytes
+ *     R = r × G
+ *     k = SHA512(R ‖ pub ‖ msg) mod L
+ *     S = (r + k × scalar) mod L
+ *     sig = R ‖ S                              (64 bytes, verifiable as ed25519)
+ *
+ * The random `prefix` is a hedge against bad randomness leaking the scalar via
+ * a colliding `r`. In normal NoTrace use each stealth scalar signs at most one
+ * sweep, so even non-hedged would be safe — we hedge anyway.
+ */
+/**
+ * Produce a 64-byte ed25519 signature using a raw scalar.
+ *
+ * The resulting signature verifies against `pub = scalar × G` under the
+ * standard ed25519 verify algorithm (e.g. `ed25519.verify` in @noble/curves,
+ * or Solana's runtime).
+ */
+declare function signWithScalar(scalar: bigint, pubBytes: Uint8Array, message: Uint8Array): Uint8Array;
+/** Re-export `ed25519.verify` for callers that don't want to import @noble directly. */
+declare function verify(sig: Uint8Array, message: Uint8Array, pubBytes: Uint8Array): boolean;
+
+/**
+ * Memo-program encoding for the ephemeral pub.
+ *
+ * Every NoTrace payment carries a memo of the form `nt1:<bs58_eph_pub>`. The
+ * recipient's scanner parses these out of memo-program instructions and feeds
+ * them to `recoverStealth` to test for matches.
+ *
+ * The `nt1:` prefix makes the protocol forward-compatible: a future scheme can
+ * use `nt2:` and old wallets will simply skip those memos.
+ */
+/** Current memo prefix. Bump when the on-chain wire format changes. */
+declare const MEMO_PREFIX = "nt1:";
+/** Solana's official Memo Program address (v2). Useful for filtering RPC calls. */
+declare const MEMO_PROGRAM_ID = "MemoSq4gqABAXKb96qnH8TysNcWxMyWCqXgDLGmfcHr";
+/**
+ * Encode an ephemeral public key into a memo string for on-chain publication.
+ * Output is ~48 chars (`nt1:` + 44-char base58).
+ */
+declare function encodeMemo(ephPubBytes: Uint8Array): string;
+/**
+ * Parse a memo string back into the ephemeral pub. Returns `null` for any
+ * memo that doesn't start with the current prefix or fails to decode to 32
+ * bytes — so the scanner can pipe every memo through this without try/catch.
+ */
+declare function parseMemo(memoString: unknown): Uint8Array | null;
+
+/**
+ * NoTrace pay-link helpers.
+ *
+ * A pay-link encodes a recipient's `meta_pub` in the URL fragment of a hosted
+ * `/pay` page (default: https://notracesol.xyz/pay). The recipient shares the
+ * link; the payer's browser derives a one-time address client-side and signs
+ * the transfer through Phantom.
+ *
+ * Format: `https://<origin>/pay#m=<bs58(meta_pub)>`
+ *
+ * Using the URL fragment (after `#`) means the meta-pub never reaches the
+ * NoTrace server — even the request log can't link payer to recipient.
+ */
+/** Build a `/pay` link for a given meta-pub. */
+declare function makePayLink(metaPubBytes: Uint8Array, origin?: string): string;
+/**
+ * Parse a NoTrace pay-link and return the recipient meta-pub.
+ * Returns `null` for any input that isn't a parseable NoTrace pay-link.
+ */
+declare function parsePayLink(url: string): Uint8Array | null;
+
+/**
+ * Memo-program scanner — find incoming stealth payments addressed to you.
+ *
+ * Standalone (no `@solana/web3.js` dependency at type-level): the scanner takes
+ * a small `RpcLike` interface so it composes with any RPC client — a real
+ * `Connection` from web3.js, a mock for tests, or a thin HTTP wrapper.
+ *
+ * Algorithm per scanned signature:
+ *
+ *   1. Fetch the parsed tx.
+ *   2. Find a Memo-program instruction; extract the memo string.
+ *   3. `parseMemo(...)` → 32-byte `eph_pub` (skip if not an `nt1:` memo).
+ *   4. `recoverStealth(meta_scalar, meta_pub, eph_pub)` → expected `stealth_pub`.
+ *   5. Look for a SystemProgram `transfer` whose `destination` matches; if so,
+ *      it's a payment to you.
+ */
+
+/** Minimal shape we need from an RPC client. */
+interface RpcLike {
+    /**
+     * Return signatures touching `address`, newest first. Slot/blockTime are
+     * optional but recommended for ordering and display.
+     */
+    getSignaturesForAddress(address: string, opts?: {
+        limit?: number;
+        before?: string;
+        until?: string;
+    }): Promise<Array<{
+        signature: string;
+        slot?: number;
+        blockTime?: number | null;
+    }>>;
+    /**
+     * Return a parsed transaction. The shape matches web3.js's
+     * `getParsedTransaction` for the fields the scanner actually reads.
+     */
+    getParsedTransaction(signature: string, opts?: {
+        maxSupportedTransactionVersion?: number;
+        commitment?: string;
+    }): Promise<ParsedTransactionLike | null>;
+}
+/** Minimal parsed-tx shape required by the scanner. */
+interface ParsedTransactionLike {
+    slot?: number;
+    blockTime?: number | null;
+    meta?: {
+        err?: unknown;
+    } | null;
+    transaction: {
+        message: {
+            instructions: Array<ParsedInstructionLike>;
+        };
+    };
+}
+interface ParsedInstructionLike {
+    programId?: {
+        toString(): string;
+    } | string;
+    /** Memo program may surface the memo here as a string. */
+    parsed?: string | {
+        type?: string;
+        info?: {
+            destination?: string;
+            source?: string;
+            lamports?: number;
+        } | string;
+    };
+    /** Raw memo bytes (base58-encoded) if the program is not parsed. */
+    data?: string;
+}
+/** A successfully-matched stealth payment. */
+interface StealthPayment {
+    /** Transaction signature on Solana. */
+    signature: string;
+    /** Slot the tx landed in (if the RPC returned it). */
+    slot?: number;
+    /** Block timestamp in **ms** since epoch (or `null` if RPC didn't supply). */
+    blockTimeMs?: number | null;
+    /** Lamports received at the stealth address. */
+    lamports: number;
+    /** Source wallet (the payer). */
+    source: string;
+    /** Stealth address (base58). */
+    stealthPub: string;
+    /** Secret stealth scalar — needed to sign sweeps. Treat as private key. */
+    stealthScalar: bigint;
+    /** Ephemeral pub from the memo (base58). */
+    ephPub: string;
+}
+interface ScanOptions {
+    /** How many signatures to pull from the memo program per batch. Default 100. */
+    limit?: number;
+    /** Concurrent `getParsedTransaction` calls. Default 5 (RPC-friendly). */
+    concurrency?: number;
+    /** Cursor for pagination — fetch sigs older than this signature. */
+    before?: string;
+    /** Already-scanned signatures to skip. */
+    alreadyScanned?: Set<string>;
+}
+/**
+ * Scan the memo program for new stealth payments addressed to `meta`.
+ *
+ * Returns *only the matches*. Updates `alreadyScanned` (if provided) in-place
+ * so subsequent calls can resume without re-checking.
+ */
+declare function scanForPayments(meta: Pick<MetaKey, "scalar" | "pub">, rpc: RpcLike, opts?: ScanOptions): Promise<StealthPayment[]>;
+/**
+ * Check a single signature for a stealth payment to `meta`. Returns the
+ * payment if matched, `null` otherwise. Exposed so callers can wire their own
+ * scanning loop (e.g. with subscribe/webhook flows instead of polling).
+ */
+declare function checkSignature(signature: string, meta: Pick<MetaKey, "scalar" | "pub">, rpc: RpcLike): Promise<StealthPayment | null>;
+
+/**
+ * @notrace/stealth-sdk
+ *
+ * Real stealth addresses on Solana. ECDH-derived one-time addresses on
+ * ed25519, view-key recoverable, with a Memo-program footprint.
+ *
+ * Extracted from the production NoTrace wallet (https://notracesol.xyz).
+ *
+ * Quick start:
+ *
+ *     import {
+ *       generateMetaKey, deriveStealthSender, recoverStealth,
+ *       encodeMemo, parseMemo, makePayLink, scanForPayments,
+ *     } from "@notrace/stealth-sdk";
+ *
+ * See README.md for end-to-end examples.
+ */
+
+/** Package version, kept in sync with `package.json`. */
+declare const VERSION = "1.0.0";
+
+export { MEMO_PREFIX, MEMO_PROGRAM_ID, type MetaKey, type ParsedInstructionLike, type ParsedTransactionLike, type RecipientRecovery, type RpcLike, type ScanOptions, type SenderDerivation, type StealthPayment, VERSION, bs58decode, bs58encode, bytesEqual, bytesToNumberLE, checkSignature, concatBytes, deriveStealthSender, encodeMemo, generateMetaKey, makePayLink, metaFromSeed, numberToBytesLE, parseMemo, parsePayLink, pubFromScalar, recoverStealth, scanForPayments, signWithScalar, verify };

package/dist/index.d.ts

@@ -0,0 +1,325 @@
+/**
+ * Byte/scalar helpers shared across the SDK.
+ *
+ * Kept dependency-free — no `Buffer`, no `bigint-buffer`. Works in browser,
+ * Node 18+, Deno, and Bun without polyfills.
+ */
+/** Concatenate any number of byte arrays into a single Uint8Array. */
+declare function concatBytes(...arrs: Uint8Array[]): Uint8Array;
+/** Little-endian unsigned integer decode. */
+declare function bytesToNumberLE(bytes: Uint8Array): bigint;
+/** Little-endian unsigned integer encode to a fixed length. */
+declare function numberToBytesLE(n: bigint, len: number): Uint8Array;
+/** Compare two Uint8Arrays for byte equality. */
+declare function bytesEqual(a: Uint8Array, b: Uint8Array): boolean;
+
+/**
+ * Minimal base58 (Bitcoin/Solana alphabet) encoder/decoder.
+ *
+ * Zero-dep. Identical output to `bs58` and `@solana/web3.js` Address encoding.
+ */
+/** Encode a byte array to a base58 string. */
+declare function bs58encode(bytes: Uint8Array): string;
+/** Decode a base58 string back to bytes. Throws on invalid input. */
+declare function bs58decode(str: string): Uint8Array;
+
+/**
+ * Meta-keypair generation and seed derivation.
+ *
+ * A NoTrace identity is a single ed25519 keypair (the *meta-key*). Its public
+ * half is shared with payers — that's enough for them to derive a one-time
+ * stealth address. Its private half (the *view+spend scalar*) is what lets the
+ * recipient detect and claim incoming payments.
+ *
+ * Note: this is a non-hierarchical key. If you want separate view-only and
+ * spend keys, derive them upstream from your own master secret and pass the
+ * spend scalar in only when you need to sign.
+ */
+/** A meta-keypair. `seed` and `scalar` are *secret*; only `pub` is shareable. */
+interface MetaKey {
+    /** Original 32-byte random seed (kept for backup/export). */
+    seed: Uint8Array;
+    /** ed25519 scalar derived from the seed (in [0, L)). */
+    scalar: bigint;
+    /** 32-byte compressed ed25519 public point. Share this with payers. */
+    pub: Uint8Array;
+}
+/** Generate a fresh random meta-keypair using `crypto.getRandomValues`. */
+declare function generateMetaKey(): MetaKey;
+/**
+ * Deterministically derive a meta-keypair from a 32-byte seed.
+ *
+ * Performs the standard ed25519 clamping (RFC 8032 §5.1.5) so the scalar lands
+ * in a valid range. Same `seed` → same `pub` forever.
+ */
+declare function metaFromSeed(seed: Uint8Array): MetaKey;
+/** Recompute the public point for a given scalar. */
+declare function pubFromScalar(scalar: bigint): Uint8Array;
+
+/**
+ * Stealth-address derivation and recovery.
+ *
+ * The protocol is ECDH-on-ed25519 with a scalar-tweak — the same shape used by
+ * ERC-5564 and Umbra Cash, ported to Solana's native curve. Properties:
+ *
+ *   - Sender derives a stealth address from the recipient's published `meta_pub`.
+ *   - Sender CANNOT recover the stealth private key (would need `meta_scalar`).
+ *   - Recipient scans memos and applies their `meta_scalar` to detect payments.
+ *   - The stealth pub is a normal ed25519 point → a valid Solana address.
+ *
+ * The "version tag" included in the tweak makes the protocol forward-compatible:
+ * a future curve swap or hash change can ship a new tag without breaking
+ * existing wallets.
+ */
+/** Result of a sender-side derivation. */
+interface SenderDerivation {
+    /** The one-time stealth address (32-byte ed25519 pub) to send funds to. */
+    stealthPub: Uint8Array;
+    /** The ephemeral pub the sender must publish on-chain (e.g. in a memo). */
+    ephPub: Uint8Array;
+}
+/**
+ * SENDER side: derive a one-time stealth address from the recipient's meta-pub.
+ *
+ *     eph_scalar, eph_pub  = fresh ed25519 keypair
+ *     shared               = eph_scalar × meta_pub          (DH on ed25519)
+ *     tweak                = SHA512(ver ‖ shared ‖ eph_pub ‖ meta_pub) mod L
+ *     stealth_pub          = meta_pub + tweak × G            (point addition)
+ *
+ * The sender publishes `eph_pub`; only the holder of `meta_scalar` can both
+ * recover `stealth_scalar` and produce signatures over it.
+ *
+ * Safe to call from a hostile environment — no state is persisted.
+ */
+declare function deriveStealthSender(metaPubBytes: Uint8Array): SenderDerivation;
+/** Result of a recipient-side recovery — pub matches what the sender derived. */
+interface RecipientRecovery {
+    /** The recovered scalar — secret. Use this to sign sweeps. */
+    stealthScalar: bigint;
+    /** The recovered pub — compare against the on-chain destination. */
+    stealthPub: Uint8Array;
+}
+/**
+ * RECIPIENT side: given your meta-key and an ephemeral pub from a memo, recover
+ * the stealth keypair the sender derived.
+ *
+ *     shared        = meta_scalar × eph_pub                 (same point as sender's)
+ *     tweak         = SHA512(ver ‖ shared ‖ eph_pub ‖ meta_pub) mod L
+ *     stealth_scalar = (meta_scalar + tweak) mod L
+ *     stealth_pub   = stealth_scalar × G
+ *
+ * Compare the returned `stealthPub` against the SOL/SPL `destination` field of
+ * the transaction containing the memo. A match means the payment is yours.
+ */
+declare function recoverStealth(metaScalar: bigint, metaPubBytes: Uint8Array, ephPubBytes: Uint8Array): RecipientRecovery;
+
+/**
+ * ed25519 signing with a raw scalar (not a seed).
+ *
+ * Standard ed25519 sign-from-seed first hashes the seed and uses the upper half
+ * as a deterministic nonce. Our stealth scalars are *derived*, not seeded — so
+ * we use a Schnorr-style construction directly:
+ *
+ *     r = SHA512(prefix ‖ pub ‖ msg) mod L     where prefix is 32 fresh bytes
+ *     R = r × G
+ *     k = SHA512(R ‖ pub ‖ msg) mod L
+ *     S = (r + k × scalar) mod L
+ *     sig = R ‖ S                              (64 bytes, verifiable as ed25519)
+ *
+ * The random `prefix` is a hedge against bad randomness leaking the scalar via
+ * a colliding `r`. In normal NoTrace use each stealth scalar signs at most one
+ * sweep, so even non-hedged would be safe — we hedge anyway.
+ */
+/**
+ * Produce a 64-byte ed25519 signature using a raw scalar.
+ *
+ * The resulting signature verifies against `pub = scalar × G` under the
+ * standard ed25519 verify algorithm (e.g. `ed25519.verify` in @noble/curves,
+ * or Solana's runtime).
+ */
+declare function signWithScalar(scalar: bigint, pubBytes: Uint8Array, message: Uint8Array): Uint8Array;
+/** Re-export `ed25519.verify` for callers that don't want to import @noble directly. */
+declare function verify(sig: Uint8Array, message: Uint8Array, pubBytes: Uint8Array): boolean;
+
+/**
+ * Memo-program encoding for the ephemeral pub.
+ *
+ * Every NoTrace payment carries a memo of the form `nt1:<bs58_eph_pub>`. The
+ * recipient's scanner parses these out of memo-program instructions and feeds
+ * them to `recoverStealth` to test for matches.
+ *
+ * The `nt1:` prefix makes the protocol forward-compatible: a future scheme can
+ * use `nt2:` and old wallets will simply skip those memos.
+ */
+/** Current memo prefix. Bump when the on-chain wire format changes. */
+declare const MEMO_PREFIX = "nt1:";
+/** Solana's official Memo Program address (v2). Useful for filtering RPC calls. */
+declare const MEMO_PROGRAM_ID = "MemoSq4gqABAXKb96qnH8TysNcWxMyWCqXgDLGmfcHr";
+/**
+ * Encode an ephemeral public key into a memo string for on-chain publication.
+ * Output is ~48 chars (`nt1:` + 44-char base58).
+ */
+declare function encodeMemo(ephPubBytes: Uint8Array): string;
+/**
+ * Parse a memo string back into the ephemeral pub. Returns `null` for any
+ * memo that doesn't start with the current prefix or fails to decode to 32
+ * bytes — so the scanner can pipe every memo through this without try/catch.
+ */
+declare function parseMemo(memoString: unknown): Uint8Array | null;
+
+/**
+ * NoTrace pay-link helpers.
+ *
+ * A pay-link encodes a recipient's `meta_pub` in the URL fragment of a hosted
+ * `/pay` page (default: https://notracesol.xyz/pay). The recipient shares the
+ * link; the payer's browser derives a one-time address client-side and signs
+ * the transfer through Phantom.
+ *
+ * Format: `https://<origin>/pay#m=<bs58(meta_pub)>`
+ *
+ * Using the URL fragment (after `#`) means the meta-pub never reaches the
+ * NoTrace server — even the request log can't link payer to recipient.
+ */
+/** Build a `/pay` link for a given meta-pub. */
+declare function makePayLink(metaPubBytes: Uint8Array, origin?: string): string;
+/**
+ * Parse a NoTrace pay-link and return the recipient meta-pub.
+ * Returns `null` for any input that isn't a parseable NoTrace pay-link.
+ */
+declare function parsePayLink(url: string): Uint8Array | null;
+
+/**
+ * Memo-program scanner — find incoming stealth payments addressed to you.
+ *
+ * Standalone (no `@solana/web3.js` dependency at type-level): the scanner takes
+ * a small `RpcLike` interface so it composes with any RPC client — a real
+ * `Connection` from web3.js, a mock for tests, or a thin HTTP wrapper.
+ *
+ * Algorithm per scanned signature:
+ *
+ *   1. Fetch the parsed tx.
+ *   2. Find a Memo-program instruction; extract the memo string.
+ *   3. `parseMemo(...)` → 32-byte `eph_pub` (skip if not an `nt1:` memo).
+ *   4. `recoverStealth(meta_scalar, meta_pub, eph_pub)` → expected `stealth_pub`.
+ *   5. Look for a SystemProgram `transfer` whose `destination` matches; if so,
+ *      it's a payment to you.
+ */
+
+/** Minimal shape we need from an RPC client. */
+interface RpcLike {
+    /**
+     * Return signatures touching `address`, newest first. Slot/blockTime are
+     * optional but recommended for ordering and display.
+     */
+    getSignaturesForAddress(address: string, opts?: {
+        limit?: number;
+        before?: string;
+        until?: string;
+    }): Promise<Array<{
+        signature: string;
+        slot?: number;
+        blockTime?: number | null;
+    }>>;
+    /**
+     * Return a parsed transaction. The shape matches web3.js's
+     * `getParsedTransaction` for the fields the scanner actually reads.
+     */
+    getParsedTransaction(signature: string, opts?: {
+        maxSupportedTransactionVersion?: number;
+        commitment?: string;
+    }): Promise<ParsedTransactionLike | null>;
+}
+/** Minimal parsed-tx shape required by the scanner. */
+interface ParsedTransactionLike {
+    slot?: number;
+    blockTime?: number | null;
+    meta?: {
+        err?: unknown;
+    } | null;
+    transaction: {
+        message: {
+            instructions: Array<ParsedInstructionLike>;
+        };
+    };
+}
+interface ParsedInstructionLike {
+    programId?: {
+        toString(): string;
+    } | string;
+    /** Memo program may surface the memo here as a string. */
+    parsed?: string | {
+        type?: string;
+        info?: {
+            destination?: string;
+            source?: string;
+            lamports?: number;
+        } | string;
+    };
+    /** Raw memo bytes (base58-encoded) if the program is not parsed. */
+    data?: string;
+}
+/** A successfully-matched stealth payment. */
+interface StealthPayment {
+    /** Transaction signature on Solana. */
+    signature: string;
+    /** Slot the tx landed in (if the RPC returned it). */
+    slot?: number;
+    /** Block timestamp in **ms** since epoch (or `null` if RPC didn't supply). */
+    blockTimeMs?: number | null;
+    /** Lamports received at the stealth address. */
+    lamports: number;
+    /** Source wallet (the payer). */
+    source: string;
+    /** Stealth address (base58). */
+    stealthPub: string;
+    /** Secret stealth scalar — needed to sign sweeps. Treat as private key. */
+    stealthScalar: bigint;
+    /** Ephemeral pub from the memo (base58). */
+    ephPub: string;
+}
+interface ScanOptions {
+    /** How many signatures to pull from the memo program per batch. Default 100. */
+    limit?: number;
+    /** Concurrent `getParsedTransaction` calls. Default 5 (RPC-friendly). */
+    concurrency?: number;
+    /** Cursor for pagination — fetch sigs older than this signature. */
+    before?: string;
+    /** Already-scanned signatures to skip. */
+    alreadyScanned?: Set<string>;
+}
+/**
+ * Scan the memo program for new stealth payments addressed to `meta`.
+ *
+ * Returns *only the matches*. Updates `alreadyScanned` (if provided) in-place
+ * so subsequent calls can resume without re-checking.
+ */
+declare function scanForPayments(meta: Pick<MetaKey, "scalar" | "pub">, rpc: RpcLike, opts?: ScanOptions): Promise<StealthPayment[]>;
+/**
+ * Check a single signature for a stealth payment to `meta`. Returns the
+ * payment if matched, `null` otherwise. Exposed so callers can wire their own
+ * scanning loop (e.g. with subscribe/webhook flows instead of polling).
+ */
+declare function checkSignature(signature: string, meta: Pick<MetaKey, "scalar" | "pub">, rpc: RpcLike): Promise<StealthPayment | null>;
+
+/**
+ * @notrace/stealth-sdk
+ *
+ * Real stealth addresses on Solana. ECDH-derived one-time addresses on
+ * ed25519, view-key recoverable, with a Memo-program footprint.
+ *
+ * Extracted from the production NoTrace wallet (https://notracesol.xyz).
+ *
+ * Quick start:
+ *
+ *     import {
+ *       generateMetaKey, deriveStealthSender, recoverStealth,
+ *       encodeMemo, parseMemo, makePayLink, scanForPayments,
+ *     } from "@notrace/stealth-sdk";
+ *
+ * See README.md for end-to-end examples.
+ */
+
+/** Package version, kept in sync with `package.json`. */
+declare const VERSION = "1.0.0";
+
+export { MEMO_PREFIX, MEMO_PROGRAM_ID, type MetaKey, type ParsedInstructionLike, type ParsedTransactionLike, type RecipientRecovery, type RpcLike, type ScanOptions, type SenderDerivation, type StealthPayment, VERSION, bs58decode, bs58encode, bytesEqual, bytesToNumberLE, checkSignature, concatBytes, deriveStealthSender, encodeMemo, generateMetaKey, makePayLink, metaFromSeed, numberToBytesLE, parseMemo, parsePayLink, pubFromScalar, recoverStealth, scanForPayments, signWithScalar, verify };