@sip-protocol/sdk 0.9.0 → 0.10.0

package/src/move/aptos.ts

@@ -269,9 +269,12 @@ export function deriveAptosStealthPrivateKey(
  * This is the same as the standard ed25519 check since Aptos stealth
  * addresses use ed25519 stealth public keys.
  *
+ * Canonical EIP-5564 view-only check: requires only the recipient's viewing
+ * private key plus their spending PUBLIC key (no spending private key needed).
+ *
  * @param stealthAddress - Stealth address to check
- * @param spendingPrivateKey - Recipient's spending private key
  * @param viewingPrivateKey - Recipient's viewing private key
+ * @param spendingPublicKey - Recipient's spending public key (meta-address spendingKey)
  * @returns true if this address belongs to the recipient
  * @throws {ValidationError} If any input is invalid
  *
@@ -279,21 +282,21 @@ export function deriveAptosStealthPrivateKey(
  * ```typescript
  * const isMine = checkAptosStealthAddress(
  *   stealthAddress,
- *   mySpendingPrivKey,
- *   myViewingPrivKey
+ *   myViewingPrivKey,
+ *   mySpendingPubKey
  * )
  * ```
  */
 export function checkAptosStealthAddress(
   stealthAddress: StealthAddress,
-  spendingPrivateKey: HexString,
   viewingPrivateKey: HexString,
+  spendingPublicKey: HexString,
 ): boolean {
   // Use standard ed25519 check
   return checkEd25519StealthAddress(
     stealthAddress,
-    spendingPrivateKey,
-    viewingPrivateKey
+    viewingPrivateKey,
+    spendingPublicKey
   )
 }
 
@@ -344,17 +347,20 @@ export class AptosStealthService {
   /**
    * Check if a stealth address belongs to this recipient
    *
+   * Canonical EIP-5564 view-only check: requires only the recipient's viewing
+   * private key plus their spending PUBLIC key (no spending private key needed).
+   *
    * @param stealthAddress - Stealth address to check
-   * @param spendingPrivateKey - Recipient's spending private key
    * @param viewingPrivateKey - Recipient's viewing private key
+   * @param spendingPublicKey - Recipient's spending public key (meta-address spendingKey)
    * @returns true if the address belongs to this recipient
    */
   checkStealthAddress(
     stealthAddress: StealthAddress,
-    spendingPrivateKey: HexString,
     viewingPrivateKey: HexString,
+    spendingPublicKey: HexString,
   ): boolean {
-    return checkAptosStealthAddress(stealthAddress, spendingPrivateKey, viewingPrivateKey)
+    return checkAptosStealthAddress(stealthAddress, viewingPrivateKey, spendingPublicKey)
   }
 
   /**

package/src/move/sui.ts

@@ -267,9 +267,12 @@ export function deriveSuiStealthPrivateKey(
  * This is the same as the standard ed25519 check since Sui stealth
  * addresses use ed25519 stealth public keys.
  *
+ * Canonical EIP-5564 view-only check: requires only the recipient's viewing
+ * private key plus their spending PUBLIC key (no spending private key needed).
+ *
  * @param stealthAddress - Stealth address to check
- * @param spendingPrivateKey - Recipient's spending private key
  * @param viewingPrivateKey - Recipient's viewing private key
+ * @param spendingPublicKey - Recipient's spending public key (meta-address spendingKey)
  * @returns true if this address belongs to the recipient
  * @throws {ValidationError} If any input is invalid
  *
@@ -277,21 +280,21 @@ export function deriveSuiStealthPrivateKey(
  * ```typescript
  * const isMine = checkSuiStealthAddress(
  *   stealthAddress,
- *   mySpendingPrivKey,
- *   myViewingPrivKey
+ *   myViewingPrivKey,
+ *   mySpendingPubKey
  * )
  * ```
  */
 export function checkSuiStealthAddress(
   stealthAddress: StealthAddress,
-  spendingPrivateKey: HexString,
   viewingPrivateKey: HexString,
+  spendingPublicKey: HexString,
 ): boolean {
   // Use standard ed25519 check
   return checkEd25519StealthAddress(
     stealthAddress,
-    spendingPrivateKey,
-    viewingPrivateKey
+    viewingPrivateKey,
+    spendingPublicKey
   )
 }
 
@@ -342,17 +345,20 @@ export class SuiStealthService {
   /**
    * Check if a stealth address belongs to this recipient
    *
+   * Canonical EIP-5564 view-only check: requires only the recipient's viewing
+   * private key plus their spending PUBLIC key (no spending private key needed).
+   *
    * @param stealthAddress - Stealth address to check
-   * @param spendingPrivateKey - Recipient's spending private key
    * @param viewingPrivateKey - Recipient's viewing private key
+   * @param spendingPublicKey - Recipient's spending public key (meta-address spendingKey)
    * @returns true if the address belongs to this recipient
    */
   checkStealthAddress(
     stealthAddress: StealthAddress,
-    spendingPrivateKey: HexString,
     viewingPrivateKey: HexString,
+    spendingPublicKey: HexString,
   ): boolean {
-    return checkSuiStealthAddress(stealthAddress, spendingPrivateKey, viewingPrivateKey)
+    return checkSuiStealthAddress(stealthAddress, viewingPrivateKey, spendingPublicKey)
   }
 
   /**

package/src/nft/private-nft.ts

@@ -19,6 +19,7 @@
  */
 
 import { sha256 } from '@noble/hashes/sha256'
+import { ed25519 } from '@noble/curves/ed25519'
 import { secp256k1 } from '@noble/curves/secp256k1'
 import { bytesToHex, hexToBytes } from '@noble/hashes/utils'
 import type {
@@ -490,9 +491,12 @@ export class PrivateNFT {
 
     const ownedNFTs: OwnedNFT[] = []
 
-    // Convert keys to hex for stealth checking
-    const scanKeyHex = `0x${bytesToHex(scanKey)}` as HexString
+    // Convert keys to hex for stealth checking.
+    // Canonical EIP-5564 view-only scanning needs the spending PUBLIC key, so
+    // derive it from the spending private (scan) key once for both curves.
     const viewingKeyHex = `0x${bytesToHex(viewingKey)}` as HexString
+    const ed25519SpendingPubHex = `0x${bytesToHex(ed25519.getPublicKey(scanKey))}` as HexString
+    const secp256k1SpendingPubHex = `0x${bytesToHex(secp256k1.getPublicKey(scanKey, true))}` as HexString
 
     // Scan each transfer
     for (const transfer of transfers) {
@@ -511,14 +515,14 @@ export class PrivateNFT {
         if (isEd25519Chain(transfer.chain)) {
           isOwned = checkEd25519StealthAddress(
             transfer.newOwnerStealth,
-            scanKeyHex,
-            viewingKeyHex
+            viewingKeyHex,
+            ed25519SpendingPubHex
           )
         } else {
           isOwned = checkStealthAddress(
             transfer.newOwnerStealth,
-            scanKeyHex,
-            viewingKeyHex
+            viewingKeyHex,
+            secp256k1SpendingPubHex
           )
         }
 

package/src/privacy-backends/shadowwire.ts

@@ -76,6 +76,12 @@ export const SHADOWWIRE_TOKEN_MINTS: Record<TokenSymbol, string> = {
   USD1: 'USD1exampleaddress1111111111111111111111111', // Placeholder - USD1 stablecoin
   AOL: 'AOLexampleaddress11111111111111111111111111', // Placeholder
   IQLABS: 'IQLABSexampleaddress111111111111111111111', // Placeholder - IQ Labs token
+  // Added in @radr/shadowwire@1.1.15 — real mints verified against the package's TOKEN_MINTS
+  SANA: '5dpN5wMH8j8au29Rp91qn4WfNq6t6xJfcjQNcFeDJ8Ct',
+  POKI: '6vK6cL9C66Bsqw7SC2hcCdkgm1UKBDUE6DCYJ4kubonk',
+  RAIN: '3iC63FgnB7EhcPaiSaC51UkVweeBDkqu17SaRyy2pump',
+  HOSICO: 'Dx2bQe2UPv4k3BmcW8G2KhaL5oKsxduM5XxLSV3Sbonk',
+  SKR: 'SKRbvo6Gf7GondiT3BbTfuRDPqLWei4j2Qy2NPGZhW3',
 }
 
 /**
@@ -370,6 +376,13 @@ export class ShadowWireBackend implements PrivacyBackend {
       amount,
       token_mint: tokenMint,
     })
+    // @radr/shadowwire@1.1.15 made WithdrawResponse.unsigned_tx_base64 optional
+    // (returned only in the unsigned-tx flow). Absence here is an error, not an empty tx.
+    if (!response.unsigned_tx_base64) {
+      throw new Error(
+        `ShadowWire withdraw returned no unsigned transaction${response.error ? `: ${response.error}` : ''}`
+      )
+    }
     return {
       unsignedTx: response.unsigned_tx_base64,
       amountWithdrawn: response.amount_withdrawn,

package/src/stealth/ed25519.ts

@@ -195,11 +195,11 @@ export function generateEd25519StealthMetaAddress(
 /**
  * Generate a one-time ed25519 stealth address for a recipient
  *
- * Algorithm (DKSAP for ed25519):
+ * Algorithm (DKSAP for ed25519, canonical EIP-5564):
  * 1. Generate ephemeral keypair (r, R = r*G)
- * 2. Compute shared secret: S = r * P_spend (ephemeral scalar * spending public)
+ * 2. Compute shared secret: S = r * P_view (ephemeral scalar * viewing public)
  * 3. Hash shared secret: h = SHA256(S)
- * 4. Derive stealth public key: P_stealth = P_view + h*G
+ * 4. Derive stealth public key: P_stealth = P_spend + h*G
  */
 export function generateEd25519StealthAddress(
   recipientMetaAddress: StealthMetaAddress,
@@ -226,14 +226,14 @@ export function generateEd25519StealthAddress(
       throw new Error('CRITICAL: Zero ephemeral scalar after reduction - investigate RNG')
     }
 
-    // S = ephemeral_scalar * P_spend
-    const spendingPoint = ed25519.ExtendedPoint.fromHex(spendingKeyBytes)
-    const sharedSecretPoint = spendingPoint.multiply(ephemeralScalar)
+    // S = ephemeral_scalar * P_view  (canonical EIP-5564: ECDH on the VIEWING key)
+    const viewingPoint = ed25519.ExtendedPoint.fromHex(viewingKeyBytes)
+    const sharedSecretPoint = viewingPoint.multiply(ephemeralScalar)
 
     // Hash the shared secret point
     const sharedSecretHash = sha256(sharedSecretPoint.toRawBytes())
 
-    // Derive stealth public key: P_stealth = P_view + hash(S)*G
+    // Derive stealth public key: P_stealth = P_spend + hash(S)*G
     const hashScalar = bytesToBigInt(sharedSecretHash) % ED25519_ORDER
     if (hashScalar === 0n) {
       throw new Error('CRITICAL: Zero hash scalar after reduction - investigate hash computation')
@@ -242,9 +242,9 @@ export function generateEd25519StealthAddress(
     // Compute hash(S) * G
     const hashTimesG = ed25519.ExtendedPoint.BASE.multiply(hashScalar)
 
-    // Add to viewing key: P_stealth = P_view + hash(S)*G
-    const viewingPoint = ed25519.ExtendedPoint.fromHex(viewingKeyBytes)
-    const stealthPoint = viewingPoint.add(hashTimesG)
+    // Add to spending key: P_stealth = P_spend + hash(S)*G
+    const spendingPoint = ed25519.ExtendedPoint.fromHex(spendingKeyBytes)
+    const stealthPoint = spendingPoint.add(hashTimesG)
     const stealthAddressBytes = stealthPoint.toRawBytes()
 
     // Compute view tag
@@ -266,7 +266,9 @@ export function generateEd25519StealthAddress(
 // ─── Private Key Derivation ─────────────────────────────────────────────────
 
 /**
- * Derive the private key for an ed25519 stealth address
+ * Derive the private key for an ed25519 stealth address (canonical EIP-5564)
+ *
+ * Requires BOTH the spending and viewing private keys (spending authority).
  *
  * **IMPORTANT: Derived Key Format**
  *
@@ -302,6 +304,86 @@ export function deriveEd25519StealthPrivateKey(
   const viewingPrivBytes = hexToBytes(viewingPrivateKey.slice(2))
   const ephemeralPubBytes = hexToBytes(stealthAddress.ephemeralPublicKey.slice(2))
 
+  try {
+    // Compute shared secret: S = viewing_scalar * R  (canonical: ECDH on the viewing key)
+    const rawViewingScalar = getEd25519Scalar(viewingPrivBytes)
+    const viewingScalar = rawViewingScalar % ED25519_ORDER
+    if (viewingScalar === 0n) {
+      throw new Error('CRITICAL: Zero viewing scalar after reduction - investigate key derivation')
+    }
+    const ephemeralPoint = ed25519.ExtendedPoint.fromHex(ephemeralPubBytes)
+    const sharedSecretPoint = ephemeralPoint.multiply(viewingScalar)
+
+    // Hash the shared secret
+    const sharedSecretHash = sha256(sharedSecretPoint.toRawBytes())
+
+    // Get spending scalar and reduce mod L
+    const rawSpendingScalar = getEd25519Scalar(spendingPrivBytes)
+    const spendingScalar = rawSpendingScalar % ED25519_ORDER
+    if (spendingScalar === 0n) {
+      throw new Error('CRITICAL: Zero spending scalar after reduction - investigate key derivation')
+    }
+
+    // Derive stealth private key: s_stealth = s_spend + hash(S) mod L  (canonical)
+    const hashScalar = bytesToBigInt(sharedSecretHash) % ED25519_ORDER
+    if (hashScalar === 0n) {
+      throw new Error('CRITICAL: Zero hash scalar after reduction - investigate hash computation')
+    }
+    const stealthPrivateScalar = (spendingScalar + hashScalar) % ED25519_ORDER
+    if (stealthPrivateScalar === 0n) {
+      throw new Error('CRITICAL: Zero stealth scalar after reduction - investigate key derivation')
+    }
+
+    // Convert to bytes (little-endian for ed25519)
+    const stealthPrivateKey = bigIntToBytesLE(stealthPrivateScalar, 32)
+
+    const result = {
+      stealthAddress: stealthAddress.address,
+      ephemeralPublicKey: stealthAddress.ephemeralPublicKey,
+      privateKey: `0x${bytesToHex(stealthPrivateKey)}` as HexString,
+    }
+
+    secureWipe(stealthPrivateKey)
+
+    return result
+  } finally {
+    secureWipeAll(spendingPrivBytes, viewingPrivBytes)
+  }
+}
+
+/**
+ * @deprecated Legacy SIP:1 swapped-scheme derivation — claim-side back-compat ONLY.
+ *
+ * Recovers funds sent to stealth addresses generated before the canonical
+ * EIP-5564 flip (legacy scheme: ECDH used the spending key, `S = s_spend * R`,
+ * and the private key was `p = s_view + H(S)`). Used only when claiming a
+ * `SIP:1` announcement. New (SIP:2) sends use {@link deriveEd25519StealthPrivateKey}.
+ */
+export function deriveEd25519StealthPrivateKeyV1(
+  stealthAddress: StealthAddress,
+  spendingPrivateKey: HexString,
+  viewingPrivateKey: HexString,
+): StealthAddressRecovery {
+  validateEd25519StealthAddress(stealthAddress)
+
+  if (!isValidPrivateKey(spendingPrivateKey)) {
+    throw new ValidationError(
+      'must be a valid 32-byte hex string',
+      'spendingPrivateKey'
+    )
+  }
+
+  if (!isValidPrivateKey(viewingPrivateKey)) {
+    throw new ValidationError(
+      'must be a valid 32-byte hex string',
+      'viewingPrivateKey'
+    )
+  }
+
+  const spendingPrivBytes = hexToBytes(spendingPrivateKey.slice(2))
+  const viewingPrivBytes = hexToBytes(viewingPrivateKey.slice(2))
+  const ephemeralPubBytes = hexToBytes(stealthAddress.ephemeralPublicKey.slice(2))
+
   try {
     // Get spending scalar and reduce mod L
     const rawSpendingScalar = getEd25519Scalar(spendingPrivBytes)
@@ -354,9 +436,88 @@ export function deriveEd25519StealthPrivateKey(
 // ─── Address Checking ───────────────────────────────────────────────────────
 
 /**
- * Check if an ed25519 stealth address was intended for this recipient
+ * Check if an ed25519 stealth address is ours — canonical EIP-5564 view-only.
+ *
+ * Requires only the viewing PRIVATE key + the spending PUBLIC key, so a viewing
+ * key can be delegated for scanning without granting spend authority. Never
+ * touches the spending private key.
+ *
+ * @param stealthAddress - Stealth address to check
+ * @param viewingPrivateKey - Recipient's viewing private key
+ * @param spendingPublicKey - Recipient's spending PUBLIC key (meta-address spendingKey)
+ * @returns true if this address belongs to the recipient
  */
 export function checkEd25519StealthAddress(
+  stealthAddress: StealthAddress,
+  viewingPrivateKey: HexString,
+  spendingPublicKey: HexString,
+): boolean {
+  validateEd25519StealthAddress(stealthAddress)
+
+  if (!isValidPrivateKey(viewingPrivateKey)) {
+    throw new ValidationError(
+      'must be a valid 32-byte hex string',
+      'viewingPrivateKey'
+    )
+  }
+
+  if (!isValidEd25519PublicKey(spendingPublicKey)) {
+    throw new ValidationError(
+      'must be a valid ed25519 public key (32 bytes)',
+      'spendingPublicKey'
+    )
+  }
+
+  const viewingPrivBytes = hexToBytes(viewingPrivateKey.slice(2))
+  const spendingPubBytes = hexToBytes(spendingPublicKey.slice(2))
+  const ephemeralPubBytes = hexToBytes(stealthAddress.ephemeralPublicKey.slice(2))
+
+  try {
+    // Compute shared secret: S = viewing_scalar * R  (canonical: ECDH on the viewing key)
+    const rawViewingScalar = getEd25519Scalar(viewingPrivBytes)
+    const viewingScalar = rawViewingScalar % ED25519_ORDER
+    if (viewingScalar === 0n) {
+      throw new Error('CRITICAL: Zero viewing scalar after reduction - investigate key derivation')
+    }
+    const ephemeralPoint = ed25519.ExtendedPoint.fromHex(ephemeralPubBytes)
+    const sharedSecretPoint = ephemeralPoint.multiply(viewingScalar)
+
+    // Hash the shared secret
+    const sharedSecretHash = sha256(sharedSecretPoint.toRawBytes())
+
+    // View tag check (fast reject)
+    if (sharedSecretHash[0] !== stealthAddress.viewTag) {
+      return false
+    }
+
+    const hashScalar = bytesToBigInt(sharedSecretHash) % ED25519_ORDER
+    if (hashScalar === 0n) {
+      throw new Error('CRITICAL: Zero hash scalar after reduction - investigate hash computation')
+    }
+
+    // Expected address: P_stealth = P_spend + hash(S)*G  (no spending private key needed)
+    const hashTimesG = ed25519.ExtendedPoint.BASE.multiply(hashScalar)
+    const spendingPoint = ed25519.ExtendedPoint.fromHex(spendingPubBytes)
+    const expectedPoint = spendingPoint.add(hashTimesG)
+    const expectedPubKeyBytes = expectedPoint.toRawBytes()
+
+    // Compare with provided stealth address
+    const providedAddress = hexToBytes(stealthAddress.address.slice(2))
+
+    return bytesToHex(expectedPubKeyBytes) === bytesToHex(providedAddress)
+  } finally {
+    secureWipe(viewingPrivBytes)
+  }
+}
+
+/**
+ * @deprecated Legacy SIP:1 full-wallet check — requires BOTH private keys.
+ *
+ * For detecting/claiming pre-flip (SIP:1) announcements only (legacy swapped
+ * scheme: `S = s_spend * R`, address built on the viewing key). New code should
+ * use the view-only {@link checkEd25519StealthAddress}.
+ */
+export function checkEd25519StealthAddressV1(
   stealthAddress: StealthAddress,
   spendingPrivateKey: HexString,
   viewingPrivateKey: HexString,

package/src/stealth/index.ts

@@ -30,14 +30,18 @@ import {
   generateEd25519StealthMetaAddress,
   generateEd25519StealthAddress,
   deriveEd25519StealthPrivateKey,
+  deriveEd25519StealthPrivateKeyV1,
   checkEd25519StealthAddress,
+  checkEd25519StealthAddressV1,
 } from './ed25519'
 
 import {
   generateSecp256k1StealthMetaAddress,
   generateSecp256k1StealthAddress,
   deriveSecp256k1StealthPrivateKey,
+  deriveSecp256k1StealthPrivateKeyV1,
   checkSecp256k1StealthAddress,
+  checkSecp256k1StealthAddressV1,
   publicKeyToEthAddress,
   validateSecp256k1StealthMetaAddress,
   validateSecp256k1StealthAddress,
@@ -166,32 +170,63 @@ export function deriveStealthPrivateKey(
   return deriveSecp256k1StealthPrivateKey(stealthAddress, spendingPrivateKey, viewingPrivateKey)
 }
 
+/**
+ * Derive the stealth private key for a LEGACY SIP:1 announcement (back-compat)
+ *
+ * Routes to the pre-flip swapped-scheme derivation. Use only when claiming funds
+ * announced before the canonical EIP-5564 flip; new (SIP:2) payments use
+ * {@link deriveStealthPrivateKey}.
+ *
+ * @param stealthAddress - The legacy stealth address to recover
+ * @param spendingPrivateKey - Recipient's spending private key
+ * @param viewingPrivateKey - Recipient's viewing private key
+ * @returns Recovery data including the derived private key
+ */
+export function deriveStealthPrivateKeyV1(
+  stealthAddress: StealthAddress,
+  spendingPrivateKey: HexString,
+  viewingPrivateKey: HexString,
+): StealthAddressRecovery {
+  const addressHex = stealthAddress.address.slice(2)
+
+  if (addressHex.length === 64) {
+    // 32 bytes = ed25519
+    return deriveEd25519StealthPrivateKeyV1(stealthAddress, spendingPrivateKey, viewingPrivateKey)
+  }
+
+  // Default to secp256k1
+  return deriveSecp256k1StealthPrivateKeyV1(stealthAddress, spendingPrivateKey, viewingPrivateKey)
+}
+
 /**
  * Check if a stealth address was intended for this recipient
  *
  * Automatically dispatches to the correct curve implementation.
  *
+ * Canonical EIP-5564 view-only check: requires only the recipient's viewing
+ * private key plus their spending PUBLIC key (no spending private key needed).
+ *
  * @param stealthAddress - Stealth address to check
- * @param spendingPrivateKey - Recipient's spending private key
  * @param viewingPrivateKey - Recipient's viewing private key
+ * @param spendingPublicKey - Recipient's spending public key (meta-address spendingKey)
  * @returns true if this address belongs to the recipient
  * @throws {ValidationError} If any input is invalid
  */
 export function checkStealthAddress(
   stealthAddress: StealthAddress,
-  spendingPrivateKey: HexString,
   viewingPrivateKey: HexString,
+  spendingPublicKey: HexString,
 ): boolean {
   // Try to detect curve from address length
   const addressHex = stealthAddress.address.slice(2)
 
   if (addressHex.length === 64) {
     // 32 bytes = ed25519
-    return checkEd25519StealthAddress(stealthAddress, spendingPrivateKey, viewingPrivateKey)
+    return checkEd25519StealthAddress(stealthAddress, viewingPrivateKey, spendingPublicKey)
   }
 
   // Default to secp256k1
-  return checkSecp256k1StealthAddress(stealthAddress, spendingPrivateKey, viewingPrivateKey)
+  return checkSecp256k1StealthAddress(stealthAddress, viewingPrivateKey, spendingPublicKey)
 }
 
 // ─── Re-exports ─────────────────────────────────────────────────────────────
@@ -207,6 +242,14 @@ export {
   checkEd25519StealthAddress,
 }
 
+// Legacy SIP:1 back-compat (claim/scan of pre-flip announcements)
+export {
+  deriveEd25519StealthPrivateKeyV1,
+  checkEd25519StealthAddressV1,
+  deriveSecp256k1StealthPrivateKeyV1,
+  checkSecp256k1StealthAddressV1,
+}
+
 // secp256k1 (Ethereum, Polygon, etc.)
 export { publicKeyToEthAddress }