docs(security): correct stealth scheme, NUMS, UltraHonk, constraint counts (audit 3/4)

[rz1989s]

Summary

Part 3 of 4 of the June 2026 docs audit (#96) — security/spec crypto accuracy + a design-doc banner. These pages feed the upcoming external audit, so accuracy matters most here.

⚠️ Stacked on #108 (PR2) → #107 (PR1). Merge order: #107 → #108 → this.

Headline: the stealth-address scheme was documented backwards

crypto-assumptions.md and audit-checklist.md described the stealth scheme with the spending and viewing key roles swapped relative to the implementation. Verified against packages/sdk/src/stealth/secp256k1.ts, the real scheme is:

• S = r·K_spend — ECDH uses the spending key (doc said r·K_view)
• P = K_view + H(S)·G — address built on the viewing key (doc said K_spend + s·G)
• p = k_view + H(S) — stealth private key (doc said k_spend + …)

This now matches both the code and security-properties.md (A = Q + H(r·P)·G, Q = viewing, P = spending).

⚑ Note for the auditor / team: SIP's key-role assignment differs from canonical EIP-5564 (which bases the stealth address on the spending key). Deriving the stealth private key here requires both recipient private keys. I've documented what the code actually does and flagged the divergence — no code change in this PR; please confirm it's intentional before the audit.

Other fixes (7 files)

• NUMS H generator — sha256("SIP_PEDERSEN_H_GENERATOR_V1") + hashToCurve → try-and-increment over "SIP-PEDERSEN-GENERATOR-H-v1:<counter>" (matches commitment.ts).
• Proof system — UltraPlonk → UltraHonk (crypto-assumptions + zk-architecture; removed the spurious Groth16 backend node).
• Constraint counts — proof-spec badges + the crypto-assumptions table corrected from "~20/50/80/150/200 constraints" to the real ACIR opcodes (funding 972, validity 1,113, fulfillment 1,691; 3,776 total) with an ACIR-vs-Barretenberg-gate-count clarification; fixed the bogus "64 bytes (mock)" proof-size claims.
• near-integration-design — added a "design proposal — not the shipped API" banner (it documents a proposed SIPClient/.swap() API that doesn't exist; the real client is SIP with getQuotes()/execute()).

Verification

• astro build green — 1277 pages.
• Stealth-scheme correction cross-checked against stealth/secp256k1.ts (generation + recovery) and security-properties.md.

Series

PR1 (#107) · PR2 (#108) · PR3 (this) · PR4 sipher SENTINEL → closes #96.

Refs #96

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Actions	Updated (UTC)
sip-docs	Ready	Preview, Comment	Jun 6, 2026 10:16am