@sip-protocol/sdk 0.8.1 → 0.10.0

package/src/chains/ethereum/privacy-adapter.ts

@@ -8,6 +8,8 @@
  */
 
 import type { StealthMetaAddress, HexString, StealthAddress } from '@sip-protocol/types'
+import { secp256k1 } from '@noble/curves/secp256k1'
+import { hexToBytes, bytesToHex } from '@noble/hashes/utils'
 import {
   generateEthereumStealthMetaAddress,
   generateEthereumStealthAddress,
@@ -15,6 +17,8 @@ import {
   encodeEthereumStealthMetaAddress,
   deriveEthereumStealthPrivateKey,
   checkEthereumStealthAddress,
+  checkEthereumStealthByEthAddress,
+  stealthPublicKeyToEthAddress,
   type EthereumStealthMetaAddress,
   type EthereumStealthAddress,
 } from './stealth'
@@ -359,20 +363,23 @@ export class EthereumPrivacyAdapter {
   /**
    * Check if a stealth address belongs to a 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 object
-   * @param spendingPrivateKey - Spending private key (hex)
    * @param viewingPrivateKey - Viewing private key (hex)
+   * @param spendingPublicKey - Spending public key (hex, meta-address spendingKey)
    * @returns True if the address belongs to the recipient
    */
   checkStealthAddress(
     stealthAddress: StealthAddress,
-    spendingPrivateKey: HexString,
-    viewingPrivateKey: HexString
+    viewingPrivateKey: HexString,
+    spendingPublicKey: HexString
   ): boolean {
     return checkEthereumStealthAddress(
       stealthAddress,
-      spendingPrivateKey,
-      viewingPrivateKey
+      viewingPrivateKey,
+      spendingPublicKey
     )
   }
 
@@ -582,20 +589,17 @@ export class EthereumPrivacyAdapter {
 
       // Check each recipient
       for (const recipient of this.scanRecipients.values()) {
-        const isOwner = checkEthereumStealthAddress(
-          stealthAddress,
-          recipient.spendingPublicKey, // Note: need spending PRIVATE key for full check
-          recipient.viewingPrivateKey
+        // Use ETH address comparison since announcements store 20-byte addresses
+        // Returns the stealth private key if match found, null otherwise
+        const stealthPrivateKey = checkEthereumStealthByEthAddress(
+          announcement.stealthAddress,
+          announcement.ephemeralPublicKey,
+          announcement.viewTag,
+          recipient.spendingPrivateKey,
+          recipient.viewingPrivateKey,
         )
 
-        if (isOwner) {
-          // Derive stealth private key for claiming
-          const recovery = deriveEthereumStealthPrivateKey(
-            stealthAddress,
-            recipient.spendingPublicKey, // This should be spending PRIVATE key
-            recipient.viewingPrivateKey
-          )
-
+        if (stealthPrivateKey) {
           results.push({
             payment: {
               stealthAddress,
@@ -606,7 +610,7 @@ export class EthereumPrivacyAdapter {
               timestamp: announcement.timestamp,
             },
             recipient,
-            stealthPrivateKey: recovery.privateKey,
+            stealthPrivateKey,
           })
           break // Found owner, no need to check other recipients
         }
@@ -641,12 +645,26 @@ export class EthereumPrivacyAdapter {
    * @returns Built claim transaction
    */
   buildClaimTransaction(params: EthereumClaimParams): EthereumClaimBuild {
-    // Derive stealth private key
-    const recovery = deriveEthereumStealthPrivateKey(
-      params.stealthAddress,
-      params.spendingPrivateKey,
-      params.viewingPrivateKey
-    )
+    // Use pre-derived key if available (e.g. from scanning flow), otherwise derive
+    let stealthPrivateKey: HexString
+    let stealthEthAddress: HexString
+
+    if (params.stealthPrivateKey) {
+      stealthPrivateKey = params.stealthPrivateKey
+      stealthEthAddress = stealthPublicKeyToEthAddress(
+        ('0x' + bytesToHex(
+          secp256k1.getPublicKey(hexToBytes(params.stealthPrivateKey.slice(2)), true)
+        )) as HexString
+      )
+    } else {
+      const recovery = deriveEthereumStealthPrivateKey(
+        params.stealthAddress,
+        params.spendingPrivateKey,
+        params.viewingPrivateKey
+      )
+      stealthPrivateKey = recovery.privateKey
+      stealthEthAddress = recovery.ethAddress
+    }
 
     // Build transaction
     const amount = params.amount ?? 0n // Full balance if not specified
@@ -673,8 +691,8 @@ export class EthereumPrivacyAdapter {
     }
 
     return {
-      stealthEthAddress: recovery.ethAddress,
-      stealthPrivateKey: recovery.privateKey,
+      stealthEthAddress,
+      stealthPrivateKey,
       destinationAddress: params.destinationAddress,
       amount,
       tx,

package/src/chains/ethereum/stealth.ts

@@ -21,6 +21,7 @@ import type {
   StealthAddressRecovery,
   HexString,
 } from '@sip-protocol/types'
+import { secp256k1 } from '@noble/curves/secp256k1'
 import {
   generateSecp256k1StealthMetaAddress,
   generateSecp256k1StealthAddress,
@@ -28,6 +29,8 @@ import {
   checkSecp256k1StealthAddress,
   publicKeyToEthAddress,
 } from '../../stealth/secp256k1'
+import { sha256, hexToBytes, bytesToHex } from '../../stealth/utils'
+import { isValidPrivateKey } from '../../validation'
 import { ValidationError } from '../../errors'
 import { SECP256K1_SCHEME_ID } from './constants'
 
@@ -345,9 +348,12 @@ export function deriveEthereumStealthPrivateKey(
  *
  * Used during scanning to quickly filter announcements.
  *
+ * 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 - The 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
  *
  * @example
@@ -356,8 +362,8 @@ export function deriveEthereumStealthPrivateKey(
  * for (const announcement of announcements) {
  *   const isMine = checkEthereumStealthAddress(
  *     announcement.stealthAddress,
- *     mySpendingPrivateKey,
- *     myViewingPrivateKey
+ *     myViewingPrivateKey,
+ *     mySpendingPublicKey
  *   )
  *   if (isMine) {
  *     console.log('Found incoming payment!')
@@ -367,43 +373,91 @@ export function deriveEthereumStealthPrivateKey(
  */
 export function checkEthereumStealthAddress(
   stealthAddress: StealthAddress,
-  spendingPrivateKey: HexString,
-  viewingPrivateKey: HexString
+  viewingPrivateKey: HexString,
+  spendingPublicKey: HexString
 ): boolean {
   return checkSecp256k1StealthAddress(
     stealthAddress,
-    spendingPrivateKey,
-    viewingPrivateKey
+    viewingPrivateKey,
+    spendingPublicKey
   )
 }
 
 /**
- * Quick view tag check for efficient scanning
- *
- * Before doing the full elliptic curve check, verify the view tag matches.
- * This is ~256x faster for non-matching addresses.
+ * Check if an Ethereum stealth address matches by ETH address comparison
  *
- * @param _announcement - The announcement to check (unused, for API compatibility)
- * @param _viewingPrivateKey - Recipient's viewing private key (unused)
- * @param _spendingPublicKey - Sender's spending public key (unused)
- * @returns True if view tag matches (address *might* be ours)
+ * Used when the announcement only contains the 20-byte ETH address (not the
+ * full 33-byte compressed public key). Derives the expected stealth public key,
+ * converts it to an ETH address, and compares.
  *
- * @deprecated Use checkEthereumStealthAddress instead which handles everything
+ * @param ethAddress - The ETH address from the announcement (20 bytes)
+ * @param ephemeralPublicKey - Ephemeral public key from the announcement
+ * @param viewTag - View tag from the announcement
+ * @param spendingPublicKey - Recipient's spending public key
+ * @param viewingPrivateKey - Recipient's viewing private key
+ * @returns True if the address belongs to this recipient
  */
-export function checkViewTag(
-  _announcement: { ephemeralPublicKey: HexString; viewTag: number },
-  _viewingPrivateKey: HexString,
-  _spendingPublicKey: HexString
-): boolean {
-  // This is a simplified check - the full implementation would compute
-  // the shared secret and compare the first byte with the view tag.
-  // For efficiency, the secp256k1.checkSecp256k1StealthAddress already
-  // does the view tag check first, so we delegate to it with a minimal
-  // StealthAddress object.
-
-  // Note: This function is provided for API completeness but in practice,
-  // users should call checkEthereumStealthAddress which handles everything.
-  return true // Placeholder - actual implementation in checkEthereumStealthAddress
+export function checkEthereumStealthByEthAddress(
+  ethAddress: HexString,
+  ephemeralPublicKey: HexString,
+  viewTag: number,
+  spendingPrivateKey: HexString,
+  viewingPrivateKey: HexString,
+): HexString | null {
+  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(ephemeralPublicKey.slice(2))
+
+  try {
+    // Compute shared secret: S = viewingPrivateKey * ephemeralPublicKey
+    // Canonical EIP-5564: ECDH on the viewing key (mirrors generation S = r * K_view)
+    const sharedSecretPoint = secp256k1.getSharedSecret(
+      viewingPrivBytes,
+      ephemeralPubBytes,
+    )
+    const sharedSecretHash = sha256(sharedSecretPoint)
+
+    // Quick view tag check
+    if (sharedSecretHash[0] !== viewTag) {
+      return null
+    }
+
+    // Derive stealth private key: spendingPriv + hash(S) mod n
+    // Mirrors generation: stealth = spendingPub + hash(S)*G
+    const spendingScalar = BigInt('0x' + bytesToHex(spendingPrivBytes))
+    const hashScalar = BigInt('0x' + bytesToHex(sharedSecretHash))
+    const stealthPrivScalar = (spendingScalar + hashScalar) % secp256k1.CURVE.n
+
+    // Compute expected public key from derived private key
+    const stealthPrivHex = stealthPrivScalar.toString(16).padStart(64, '0')
+    const stealthPrivKeyBytes = hexToBytes(stealthPrivHex)
+    const expectedPubKey = secp256k1.getPublicKey(stealthPrivKeyBytes, true)
+
+    // Convert to ETH address
+    const expectedPubKeyHex = ('0x' + bytesToHex(expectedPubKey)) as HexString
+    const expectedEthAddress = publicKeyToEthAddress(expectedPubKeyHex)
+
+    // Compare addresses (case-insensitive)
+    if (expectedEthAddress.toLowerCase() === ethAddress.toLowerCase()) {
+      return ('0x' + stealthPrivHex) as HexString
+    }
+    return null
+  } catch {
+    return null
+  }
 }
 
 // ─── Address Conversion ─────────────────────────────────────────────────────

package/src/chains/ethereum/types.ts

@@ -224,6 +224,8 @@ export interface EthereumClaimParams {
   spendingPrivateKey: HexString
   /** Destination address to receive funds */
   destinationAddress: HexString
+  /** Pre-derived stealth private key (skips derivation if provided, e.g. from scanning) */
+  stealthPrivateKey?: HexString
   /** Network */
   network?: EthereumNetwork
   /** RPC URL (overrides default) */
@@ -439,6 +441,8 @@ export interface EthereumScanRecipient {
   viewingPrivateKey: HexString
   /** Spending public key */
   spendingPublicKey: HexString
+  /** Spending private key (required for scanning and key derivation) */
+  spendingPrivateKey: HexString
   /** Optional label */
   label?: string
 }

package/src/chains/near/privacy-adapter.ts

@@ -426,20 +426,23 @@ export class NEARPrivacyAdapter {
   /**
    * Check if a stealth address belongs to a 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 object
-   * @param spendingPrivateKey - Spending private key (hex)
    * @param viewingPrivateKey - Viewing private key (hex)
+   * @param spendingPublicKey - Spending public key (hex, meta-address spendingKey)
    * @returns True if the address belongs to the recipient
    */
   checkStealthAddress(
     stealthAddress: StealthAddress,
-    spendingPrivateKey: HexString,
-    viewingPrivateKey: HexString
+    viewingPrivateKey: HexString,
+    spendingPublicKey: HexString
   ): boolean {
     return checkNEARStealthAddress(
       stealthAddress,
-      spendingPrivateKey,
-      viewingPrivateKey
+      viewingPrivateKey,
+      spendingPublicKey
     )
   }
 

package/src/chains/near/resolver.ts

@@ -30,6 +30,7 @@
  * @module chains/near/resolver
  */
 
+import { ed25519 } from '@noble/curves/ed25519'
 import { bytesToHex, hexToBytes } from '@noble/hashes/utils'
 import type { HexString, StealthAddress } from '@sip-protocol/types'
 import { ValidationError } from '../../errors'
@@ -44,6 +45,19 @@ import {
 } from './constants'
 import type { NEARViewingKey } from './viewing-key'
 
+// ─── Helpers ──────────────────────────────────────────────────────────────────
+
+/**
+ * Derive the ed25519 spending PUBLIC key from a spending private key.
+ *
+ * Canonical EIP-5564 view-only scanning needs the spending public key, but
+ * scan recipients in this module hold the spending private key. This converts
+ * one to the other on the fly.
+ */
+function nearSpendingPublicFromPrivate(spendingPrivateKey: HexString): HexString {
+  return `0x${bytesToHex(ed25519.getPublicKey(hexToBytes(spendingPrivateKey.slice(2))))}` as HexString
+}
+
 // ─── Types ────────────────────────────────────────────────────────────────────
 
 /**
@@ -652,8 +666,8 @@ export class NEARStealthScanner {
         try {
           const isMatch = checkNEARStealthAddress(
             stealthAddressToCheck,
-            recipient.spendingPrivateKey,
-            recipient.viewingPrivateKey
+            recipient.viewingPrivateKey,
+            nearSpendingPublicFromPrivate(recipient.spendingPrivateKey)
           )
 
           if (isMatch) {
@@ -764,8 +778,8 @@ export class NEARStealthScanner {
     try {
       return checkNEARStealthAddress(
         stealthAddressToCheck,
-        spendingPrivateKey,
-        viewingPrivateKey
+        viewingPrivateKey,
+        nearSpendingPublicFromPrivate(spendingPrivateKey)
       )
     } catch {
       return false
@@ -814,8 +828,8 @@ export class NEARStealthScanner {
         try {
           const isMatch = checkNEARStealthAddress(
             stealthAddressToCheck,
-            recipient.spendingPrivateKey,
-            recipient.viewingPrivateKey
+            recipient.viewingPrivateKey,
+            nearSpendingPublicFromPrivate(recipient.spendingPrivateKey)
           )
 
           if (isMatch) {
@@ -954,8 +968,8 @@ export function hasNEARAnnouncementMatch(
       try {
         const isMatch = checkNEARStealthAddress(
           stealthAddressToCheck,
-          recipient.spendingPrivateKey,
-          recipient.viewingPrivateKey
+          recipient.viewingPrivateKey,
+          nearSpendingPublicFromPrivate(recipient.spendingPrivateKey)
         )
 
         if (isMatch) {

package/src/chains/near/stealth.ts

@@ -204,12 +204,12 @@ export function deriveNEARStealthPrivateKey(
 /**
  * Check if a NEAR stealth address was intended for this recipient
  *
- * Efficiently checks if a stealth address belongs to the owner of
- * the given spending/viewing 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 - The 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
  *
  * @example
@@ -217,8 +217,8 @@ export function deriveNEARStealthPrivateKey(
  * // Check if a detected address is for us
  * const isForMe = checkNEARStealthAddress(
  *   announcement.stealthAddress,
- *   mySpendingPrivateKey,
- *   myViewingPrivateKey
+ *   myViewingPrivateKey,
+ *   mySpendingPublicKey
  * )
  *
  * if (isForMe) {
@@ -228,13 +228,13 @@ export function deriveNEARStealthPrivateKey(
  */
 export function checkNEARStealthAddress(
   stealthAddress: StealthAddress,
-  spendingPrivateKey: HexString,
-  viewingPrivateKey: HexString
+  viewingPrivateKey: HexString,
+  spendingPublicKey: HexString
 ): boolean {
   return checkEd25519StealthAddress(
     stealthAddress,
-    spendingPrivateKey,
-    viewingPrivateKey
+    viewingPrivateKey,
+    spendingPublicKey
   )
 }
 

package/src/chains/solana/constants.ts

@@ -66,11 +66,23 @@ export const SOLANA_EXPLORER_URLS = {
 export const MEMO_PROGRAM_ID = 'MemoSq4gqABAXKb96qnH8TysNcWxMyWCqXgDLGmfcHr'
 
 /**
- * SIP announcement memo prefix
+ * SIP announcement memo prefix (legacy SIP:1, swapped scheme — read-only back-compat)
  * Format: SIP:1:<ephemeral_pubkey_base58>:<view_tag_hex>
  */
 export const SIP_MEMO_PREFIX = 'SIP:1:'
 
+/**
+ * Canonical EIP-5564 (SIP:2) announcement memo prefix — emitted by new sends.
+ * Format: SIP:2:<ephemeral_pubkey_base58>:<view_tag_hex>[:<stealth_address_base58>]
+ */
+export const SIP_MEMO_PREFIX_V2 = 'SIP:2:'
+
+/**
+ * Version-agnostic prefix for filtering announcement logs during scanning.
+ * Matches both SIP:1 (legacy) and SIP:2 (canonical) announcements.
+ */
+export const SIP_MEMO_PREFIX_ANY = 'SIP:'
+
 /**
  * Estimated transaction fee in lamports
  * Includes base fee + rent for ATA creation