@notrace/stealth-sdk 1.0.0

package/src/keys.ts

@@ -0,0 +1,62 @@
+/**
+ * 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.
+ */
+
+import { ed25519 } from "@noble/curves/ed25519";
+import { sha512 } from "@noble/hashes/sha2";
+import { randomBytes } from "@noble/hashes/utils";
+import { bytesToNumberLE } from "./bytes.js";
+
+const Point = ed25519.ExtendedPoint;
+const L = ed25519.CURVE.n;
+
+/** A meta-keypair. `seed` and `scalar` are *secret*; only `pub` is shareable. */
+export 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`. */
+export function generateMetaKey(): MetaKey {
+  return metaFromSeed(randomBytes(32));
+}
+
+/**
+ * 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.
+ */
+export function metaFromSeed(seed: Uint8Array): MetaKey {
+  if (seed.length !== 32) {
+    throw new Error(`metaFromSeed: seed must be 32 bytes (got ${seed.length})`);
+  }
+  const h = sha512(seed);
+  const sb = new Uint8Array(h.slice(0, 32));
+  // ed25519 clamping
+  sb[0]! &= 248;
+  sb[31]! &= 127;
+  sb[31]! |= 64;
+  const scalar = bytesToNumberLE(sb) % L;
+  const pub = Point.BASE.multiply(scalar).toRawBytes();
+  // Defensive copy of `seed` so callers can't mutate our state.
+  return { seed: new Uint8Array(seed), scalar, pub };
+}
+
+/** Recompute the public point for a given scalar. */
+export function pubFromScalar(scalar: bigint): Uint8Array {
+  return Point.BASE.multiply(scalar).toRawBytes();
+}

package/src/memo.ts

@@ -0,0 +1,47 @@
+/**
+ * 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.
+ */
+
+import { bs58decode, bs58encode } from "./base58.js";
+
+/** Current memo prefix. Bump when the on-chain wire format changes. */
+export const MEMO_PREFIX = "nt1:";
+
+/** Solana's official Memo Program address (v2). Useful for filtering RPC calls. */
+export 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).
+ */
+export function encodeMemo(ephPubBytes: Uint8Array): string {
+  if (ephPubBytes.length !== 32) {
+    throw new Error(`encodeMemo: eph_pub must be 32 bytes (got ${ephPubBytes.length})`);
+  }
+  return MEMO_PREFIX + bs58encode(ephPubBytes);
+}
+
+/**
+ * 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.
+ */
+export function parseMemo(memoString: unknown): Uint8Array | null {
+  if (typeof memoString !== "string") return null;
+  if (!memoString.startsWith(MEMO_PREFIX)) return null;
+  const body = memoString.slice(MEMO_PREFIX.length).trim();
+  try {
+    const bytes = bs58decode(body);
+    if (bytes.length !== 32) return null;
+    return bytes;
+  } catch {
+    return null;
+  }
+}

package/src/payLink.ts

@@ -0,0 +1,50 @@
+/**
+ * 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.
+ */
+
+import { bs58decode, bs58encode } from "./base58.js";
+
+const DEFAULT_ORIGIN = "https://notracesol.xyz";
+
+/** Build a `/pay` link for a given meta-pub. */
+export function makePayLink(metaPubBytes: Uint8Array, origin: string = DEFAULT_ORIGIN): string {
+  if (metaPubBytes.length !== 32) {
+    throw new Error(`makePayLink: meta_pub must be 32 bytes (got ${metaPubBytes.length})`);
+  }
+  const cleanOrigin = origin.replace(/\/+$/, "");
+  return `${cleanOrigin}/pay#m=${bs58encode(metaPubBytes)}`;
+}
+
+/**
+ * Parse a NoTrace pay-link and return the recipient meta-pub.
+ * Returns `null` for any input that isn't a parseable NoTrace pay-link.
+ */
+export function parsePayLink(url: string): Uint8Array | null {
+  let parsed: URL;
+  try {
+    parsed = new URL(url);
+  } catch {
+    return null;
+  }
+  // Accept both `#m=...` (fragment) and `?m=...` (query) for robustness.
+  const fragMatch = parsed.hash.match(/(?:^#|&)m=([1-9A-HJ-NP-Za-km-z]+)/);
+  const queryMatch = parsed.searchParams.get("m");
+  const encoded = fragMatch?.[1] ?? queryMatch;
+  if (!encoded) return null;
+  try {
+    const bytes = bs58decode(encoded);
+    return bytes.length === 32 ? bytes : null;
+  } catch {
+    return null;
+  }
+}

package/src/scan.ts

@@ -0,0 +1,212 @@
+/**
+ * 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.
+ */
+
+import { bs58decode, bs58encode } from "./base58.js";
+import type { MetaKey } from "./keys.js";
+import { MEMO_PROGRAM_ID, parseMemo } from "./memo.js";
+import { recoverStealth } from "./stealth.js";
+
+/** Minimal shape we need from an RPC client. */
+export 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. */
+export interface ParsedTransactionLike {
+  slot?: number;
+  blockTime?: number | null;
+  meta?: { err?: unknown } | null;
+  transaction: {
+    message: {
+      instructions: Array<ParsedInstructionLike>;
+    };
+  };
+}
+
+export 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. */
+export 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;
+}
+
+export 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.
+ */
+export async function scanForPayments(
+  meta: Pick<MetaKey, "scalar" | "pub">,
+  rpc: RpcLike,
+  opts: ScanOptions = {}
+): Promise<StealthPayment[]> {
+  const limit = opts.limit ?? 100;
+  const concurrency = Math.max(1, opts.concurrency ?? 5);
+  const seen = opts.alreadyScanned ?? new Set<string>();
+
+  const sigs = await rpc.getSignaturesForAddress(MEMO_PROGRAM_ID, {
+    limit,
+    ...(opts.before ? { before: opts.before } : {}),
+  });
+
+  const fresh = sigs.filter((s) => !seen.has(s.signature));
+  const matches: StealthPayment[] = [];
+
+  for (let i = 0; i < fresh.length; i += concurrency) {
+    const batch = fresh.slice(i, i + concurrency);
+    const results = await Promise.allSettled(
+      batch.map((s) => checkSignature(s.signature, meta, rpc))
+    );
+    for (let j = 0; j < results.length; j++) {
+      const r = results[j]!;
+      const sig = batch[j]!.signature;
+      seen.add(sig);
+      if (r.status === "fulfilled" && r.value) matches.push(r.value);
+    }
+  }
+
+  return matches;
+}
+
+/**
+ * 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).
+ */
+export async function checkSignature(
+  signature: string,
+  meta: Pick<MetaKey, "scalar" | "pub">,
+  rpc: RpcLike
+): Promise<StealthPayment | null> {
+  let tx: ParsedTransactionLike | null;
+  try {
+    tx = await rpc.getParsedTransaction(signature, {
+      maxSupportedTransactionVersion: 0,
+      commitment: "confirmed",
+    });
+  } catch {
+    return null;
+  }
+  if (!tx || tx.meta?.err) return null;
+
+  const instrs = tx.transaction.message.instructions || [];
+
+  // 1. Find the memo string.
+  let memoString: string | null = null;
+  for (const ix of instrs) {
+    const pid = typeof ix.programId === "string" ? ix.programId : ix.programId?.toString();
+    if (pid !== MEMO_PROGRAM_ID) continue;
+
+    if (typeof ix.parsed === "string") {
+      memoString = ix.parsed;
+    } else if (ix.parsed && typeof ix.parsed === "object" && typeof ix.parsed.info === "string") {
+      memoString = ix.parsed.info;
+    } else if (typeof ix.data === "string") {
+      try {
+        memoString = new TextDecoder().decode(bs58decode(ix.data));
+      } catch {
+        /* ignore unparseable memo */
+      }
+    }
+    if (memoString) break;
+  }
+  if (!memoString) return null;
+
+  const ephPub = parseMemo(memoString);
+  if (!ephPub) return null;
+
+  // 2. Recover the expected stealth address.
+  const { stealthScalar, stealthPub } = recoverStealth(meta.scalar, meta.pub, ephPub);
+  const expectedAddr = bs58encode(stealthPub);
+
+  // 3. Find a transfer to that address.
+  for (const ix of instrs) {
+    const parsed = ix.parsed;
+    if (!parsed || typeof parsed !== "object") continue;
+    if (parsed.type !== "transfer") continue;
+    const info = parsed.info;
+    if (!info || typeof info !== "object") continue;
+    if (info.destination !== expectedAddr) continue;
+
+    return {
+      signature,
+      slot: tx.slot,
+      blockTimeMs: tx.blockTime ? tx.blockTime * 1000 : null,
+      lamports: typeof info.lamports === "number" ? info.lamports : 0,
+      source: info.source ?? "",
+      stealthPub: expectedAddr,
+      stealthScalar,
+      ephPub: bs58encode(ephPub),
+    };
+  }
+
+  return null;
+}

package/src/sign.ts

@@ -0,0 +1,64 @@
+/**
+ * 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.
+ */
+
+import { ed25519 } from "@noble/curves/ed25519";
+import { sha512 } from "@noble/hashes/sha2";
+import { randomBytes } from "@noble/hashes/utils";
+import { bytesToNumberLE, concatBytes, numberToBytesLE } from "./bytes.js";
+
+const Point = ed25519.ExtendedPoint;
+const L = ed25519.CURVE.n;
+
+function modL(n: bigint): bigint {
+  let r = n % L;
+  if (r < 0n) r += L;
+  return r;
+}
+
+function hash512ModL(input: Uint8Array): bigint {
+  return modL(bytesToNumberLE(sha512(input)));
+}
+
+/**
+ * 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).
+ */
+export function signWithScalar(
+  scalar: bigint,
+  pubBytes: Uint8Array,
+  message: Uint8Array
+): Uint8Array {
+  const prefix = randomBytes(32);
+  const r = hash512ModL(concatBytes(prefix, pubBytes, message));
+  const R = Point.BASE.multiply(r).toRawBytes();
+  const k = hash512ModL(concatBytes(R, pubBytes, message));
+  const S = modL(r + k * scalar);
+  return concatBytes(R, numberToBytesLE(S, 32));
+}
+
+/** Re-export `ed25519.verify` for callers that don't want to import @noble directly. */
+export function verify(
+  sig: Uint8Array,
+  message: Uint8Array,
+  pubBytes: Uint8Array
+): boolean {
+  return ed25519.verify(sig, message, pubBytes);
+}

package/src/stealth.ts

@@ -0,0 +1,125 @@
+/**
+ * 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.
+ */
+
+import { ed25519 } from "@noble/curves/ed25519";
+import { sha512 } from "@noble/hashes/sha2";
+import { randomBytes } from "@noble/hashes/utils";
+import { bytesToNumberLE, concatBytes } from "./bytes.js";
+import { metaFromSeed } from "./keys.js";
+
+const Point = ed25519.ExtendedPoint;
+const L = ed25519.CURVE.n;
+
+const VERSION_TAG = new TextEncoder().encode("notrace.v1.stealth");
+
+function modL(n: bigint): bigint {
+  let r = n % L;
+  if (r < 0n) r += L;
+  return r;
+}
+
+function hash512ModL(input: Uint8Array): bigint {
+  return modL(bytesToNumberLE(sha512(input)));
+}
+
+/** Result of a sender-side derivation. */
+export 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.
+ */
+export function deriveStealthSender(metaPubBytes: Uint8Array): SenderDerivation {
+  if (metaPubBytes.length !== 32) {
+    throw new Error(`deriveStealthSender: meta_pub must be 32 bytes (got ${metaPubBytes.length})`);
+  }
+
+  // Fresh ephemeral keypair via the same clamping path as the meta-key.
+  const eph = metaFromSeed(randomBytes(32));
+
+  // DH on ed25519
+  const metaPt = Point.fromHex(metaPubBytes);
+  const sharedBytes = metaPt.multiply(eph.scalar).toRawBytes();
+
+  // Tweak. Include all four inputs so the tweak is bound to this exact pairing.
+  const tweak = hash512ModL(
+    concatBytes(VERSION_TAG, sharedBytes, eph.pub, metaPubBytes)
+  );
+
+  // stealth_pub = meta_pub + tweak * G
+  const stealthPt = metaPt.add(Point.BASE.multiply(tweak));
+  const stealthPub = stealthPt.toRawBytes();
+
+  return { stealthPub, ephPub: eph.pub };
+}
+
+/** Result of a recipient-side recovery — pub matches what the sender derived. */
+export 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.
+ */
+export function recoverStealth(
+  metaScalar: bigint,
+  metaPubBytes: Uint8Array,
+  ephPubBytes: Uint8Array
+): RecipientRecovery {
+  if (ephPubBytes.length !== 32) {
+    throw new Error(`recoverStealth: eph_pub must be 32 bytes (got ${ephPubBytes.length})`);
+  }
+  if (metaPubBytes.length !== 32) {
+    throw new Error(`recoverStealth: meta_pub must be 32 bytes (got ${metaPubBytes.length})`);
+  }
+
+  const ephPt = Point.fromHex(ephPubBytes);
+  const sharedBytes = ephPt.multiply(metaScalar).toRawBytes();
+
+  const tweak = hash512ModL(
+    concatBytes(VERSION_TAG, sharedBytes, ephPubBytes, metaPubBytes)
+  );
+  const stealthScalar = modL(metaScalar + tweak);
+  const stealthPub = Point.BASE.multiply(stealthScalar).toRawBytes();
+
+  return { stealthScalar, stealthPub };
+}