@sip-protocol/sdk 0.9.0 → 0.11.0

package/src/chains/ethereum/stealth.ts

@@ -348,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
@@ -359,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!')
@@ -370,13 +373,13 @@ export function deriveEthereumStealthPrivateKey(
  */
 export function checkEthereumStealthAddress(
   stealthAddress: StealthAddress,
-  spendingPrivateKey: HexString,
-  viewingPrivateKey: HexString
+  viewingPrivateKey: HexString,
+  spendingPublicKey: HexString
 ): boolean {
   return checkSecp256k1StealthAddress(
     stealthAddress,
-    spendingPrivateKey,
-    viewingPrivateKey
+    viewingPrivateKey,
+    spendingPublicKey
   )
 }
 
@@ -419,10 +422,10 @@ export function checkEthereumStealthByEthAddress(
   const ephemeralPubBytes = hexToBytes(ephemeralPublicKey.slice(2))
 
   try {
-    // Compute shared secret: S = spendingPrivateKey * ephemeralPublicKey
-    // Mirrors generation: S = ephemeralPrivate * spendingPublic
+    // Compute shared secret: S = viewingPrivateKey * ephemeralPublicKey
+    // Canonical EIP-5564: ECDH on the viewing key (mirrors generation S = r * K_view)
     const sharedSecretPoint = secp256k1.getSharedSecret(
-      spendingPrivBytes,
+      viewingPrivBytes,
       ephemeralPubBytes,
     )
     const sharedSecretHash = sha256(sharedSecretPoint)
@@ -432,11 +435,11 @@ export function checkEthereumStealthByEthAddress(
       return null
     }
 
-    // Derive stealth private key: viewingPriv + hash(S) mod n
-    // Mirrors generation: stealth = viewingPub + hash(S)*G
-    const viewingScalar = BigInt('0x' + bytesToHex(viewingPrivBytes))
+    // 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 = (viewingScalar + hashScalar) % secp256k1.CURVE.n
+    const stealthPrivScalar = (spendingScalar + hashScalar) % secp256k1.CURVE.n
 
     // Compute expected public key from derived private key
     const stealthPrivHex = stealthPrivScalar.toString(16).padStart(64, '0')
@@ -457,6 +460,78 @@ export function checkEthereumStealthByEthAddress(
   }
 }
 
+/**
+ * View-only check of an Ethereum stealth announcement by ETH address.
+ *
+ * Detects whether a payment was intended for this recipient using only the viewing
+ * PRIVATE key and the spending PUBLIC key — never the spending private key (which is
+ * required to claim, not to detect). Recomputes the expected stealth public key as
+ * `A = K_spend + H(S)*G` (point arithmetic on the spending public key), converts it to an
+ * ETH address, and compares. Mirrors {@link checkEthereumStealthByEthAddress} but without
+ * the spending private key and returning a boolean rather than the derived key.
+ *
+ * @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 (meta-address spendingKey)
+ * @param viewingPrivateKey - Recipient's viewing private key
+ * @returns True if the address belongs to this recipient
+ */
+export function checkEthereumStealthByEthAddressViewOnly(
+  ethAddress: HexString,
+  ephemeralPublicKey: HexString,
+  viewTag: number,
+  spendingPublicKey: HexString,
+  viewingPrivateKey: HexString,
+): boolean {
+  if (!isValidPrivateKey(viewingPrivateKey)) {
+    throw new ValidationError(
+      'must be a valid 32-byte hex string',
+      'viewingPrivateKey'
+    )
+  }
+
+  const viewingPrivBytes = hexToBytes(viewingPrivateKey.slice(2))
+  const spendingPubBytes = hexToBytes(spendingPublicKey.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 false
+    }
+
+    // Expected stealth address: A = K_spend + hash(S)*G — point arithmetic on the spending
+    // PUBLIC key, so no spending private key is needed. Reduce hash(S) into [1, n-1] (a zero
+    // offset would be degenerate) before scaling the generator.
+    const hashScalar = BigInt('0x' + bytesToHex(sharedSecretHash)) % secp256k1.CURVE.n
+    if (hashScalar === 0n) {
+      return false
+    }
+    const spendingPubPoint = secp256k1.ProjectivePoint.fromHex(spendingPubBytes)
+    const expectedPoint = spendingPubPoint.add(
+      secp256k1.ProjectivePoint.BASE.multiply(hashScalar),
+    )
+    const expectedPubKey = expectedPoint.toRawBytes(true)
+
+    // Convert to ETH address and compare (case-insensitive)
+    const expectedPubKeyHex = ('0x' + bytesToHex(expectedPubKey)) as HexString
+    const expectedEthAddress = publicKeyToEthAddress(expectedPubKeyHex)
+
+    return expectedEthAddress.toLowerCase() === ethAddress.toLowerCase()
+  } catch {
+    return false
+  }
+}
+
 // ─── Address Conversion ─────────────────────────────────────────────────────
 
 /**

package/src/chains/ethereum/types.ts

@@ -441,8 +441,12 @@ export interface EthereumScanRecipient {
   viewingPrivateKey: HexString
   /** Spending public key */
   spendingPublicKey: HexString
-  /** Spending private key (required for scanning and key derivation) */
-  spendingPrivateKey: HexString
+  /**
+   * Spending private key — required to derive claimable keys during a full scan
+   * (`scanAnnouncements`). Optional for view-only registration: a recipient with only
+   * `viewingPrivateKey` + `spendingPublicKey` detects payments via `scanAnnouncementsViewOnly`.
+   */
+  spendingPrivateKey?: HexString
   /** Optional label */
   label?: string
 }
@@ -458,3 +462,15 @@ export interface EthereumDetectedPaymentResult {
   /** Derived stealth private key (for claiming) */
   stealthPrivateKey: HexString
 }
+
+/**
+ * View-only detected payment — carries no derived private key (detection used the
+ * spending PUBLIC key only). To claim, derive the stealth private key separately with
+ * both private keys at claim time.
+ */
+export interface EthereumViewOnlyDetectionResult {
+  /** The detected payment */
+  payment: EthereumDetectedPayment
+  /** The recipient that matched */
+  recipient: EthereumScanRecipient
+}

package/src/chains/near/constants.ts

@@ -77,11 +77,23 @@ export const NEAR_TOKEN_DECIMALS: Record<string, number> = {
 }
 
 /**
- * SIP announcement prefix for NEAR memos
+ * SIP announcement memo prefix (legacy SIP:1, swapped scheme — read-only back-compat)
  * Format: SIP:1:<ephemeral_pubkey_hex>:<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_hex>:<view_tag_hex>
+ */
+export const SIP_MEMO_PREFIX_V2 = 'SIP:2:'
+
+/**
+ * Version-agnostic announcement memo prefix for scanning.
+ * Matches both SIP:1 (legacy) and SIP:2 (canonical) announcements.
+ */
+export const SIP_MEMO_PREFIX_ANY = 'SIP:'
+
 /**
  * NEAR implicit account length (64 hex characters = 32 bytes)
  */

package/src/chains/near/index.ts

@@ -49,6 +49,8 @@ export {
   NEAR_TOKEN_CONTRACTS,
   NEAR_TOKEN_DECIMALS,
   SIP_MEMO_PREFIX,
+  SIP_MEMO_PREFIX_V2,
+  SIP_MEMO_PREFIX_ANY,
   NEAR_IMPLICIT_ACCOUNT_LENGTH,
   NEAR_ACCOUNT_ID_MIN_LENGTH,
   NEAR_ACCOUNT_ID_MAX_LENGTH,

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'
@@ -37,13 +38,26 @@ import { isValidHex } from '../../validation'
 import { checkNEARStealthAddress, implicitAccountToEd25519PublicKey } from './stealth'
 import { parseAnnouncement, type NEARAnnouncement } from './types'
 import {
-  SIP_MEMO_PREFIX,
+  SIP_MEMO_PREFIX_ANY,
   VIEW_TAG_MIN,
   VIEW_TAG_MAX,
   isImplicitAccount,
 } 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) {
@@ -708,7 +722,7 @@ export class NEARStealthScanner {
     const announcements: NEARAnnouncement[] = []
 
     for (const log of logs) {
-      if (!log.includes(SIP_MEMO_PREFIX)) {
+      if (!log.includes(SIP_MEMO_PREFIX_ANY)) {
         continue
       }
 
@@ -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/near/types.ts

@@ -8,7 +8,7 @@
  */
 
 import type { HexString, StealthAddress } from '@sip-protocol/types'
-import { SIP_MEMO_PREFIX, VIEW_TAG_MIN, VIEW_TAG_MAX } from './constants'
+import { SIP_MEMO_PREFIX_V2, VIEW_TAG_MIN, VIEW_TAG_MAX } from './constants'
 
 // ─── Announcement Types ──────────────────────────────────────────────────────
 
@@ -18,6 +18,8 @@ import { SIP_MEMO_PREFIX, VIEW_TAG_MIN, VIEW_TAG_MAX } from './constants'
  * Contains the information needed for recipients to scan for payments.
  */
 export interface NEARAnnouncement {
+  /** Announcement scheme version: '1' = legacy swapped, '2' = canonical EIP-5564 */
+  version?: string
   /** Ephemeral public key (ed25519, 0x-prefixed hex) */
   ephemeralPublicKey: HexString
   /** View tag for efficient filtering (0-255) */
@@ -35,16 +37,21 @@ export interface NEARAnnouncement {
 /**
  * Parse an announcement from a NEAR memo string
  *
- * Format: SIP:1:<ephemeral_pubkey_hex>:<view_tag_hex>
+ * Accepts SIP:1 (legacy swapped scheme) and SIP:2 (canonical EIP-5564); the detected
+ * version is returned. NEAR derives canonically regardless, so the version is recorded
+ * for consistency rather than to route the claim.
+ *
+ * Format: SIP:<version>:<ephemeral_pubkey_hex>:<view_tag_hex>
  *
  * @param memo - The memo string to parse
  * @returns Parsed announcement or null if invalid
  *
  * @example
  * ```typescript
- * const memo = 'SIP:1:1234...abcd:0f'
+ * const memo = 'SIP:2:1234...abcd:0f'
  * const announcement = parseAnnouncement(memo)
  * if (announcement) {
+ *   console.log(announcement.version) // '2'
  *   console.log(announcement.ephemeralPublicKey)
  *   console.log(announcement.viewTag) // 15
  * }
@@ -55,13 +62,15 @@ export function parseAnnouncement(memo: string): Partial<NEARAnnouncement> | nul
     return null
   }
 
-  // Check prefix
-  if (!memo.startsWith(SIP_MEMO_PREFIX)) {
+  // Accept SIP:1 (legacy) and SIP:2 (canonical); capture the version.
+  const versionMatch = /^SIP:([12]):/.exec(memo)
+  if (!versionMatch) {
     return null
   }
+  const version = versionMatch[1]
 
-  // Parse parts: SIP:1:<ephemeral_pubkey>:<view_tag>
-  const content = memo.slice(SIP_MEMO_PREFIX.length)
+  // Parse parts: <ephemeral_pubkey_hex>:<view_tag_hex>
+  const content = memo.slice(versionMatch[0].length)
   const parts = content.split(':')
 
   if (parts.length < 2) {
@@ -86,6 +95,7 @@ export function parseAnnouncement(memo: string): Partial<NEARAnnouncement> | nul
   }
 
   return {
+    version,
     ephemeralPublicKey: `0x${ephemeralKeyHex.toLowerCase()}` as HexString,
     viewTag,
   }
@@ -104,7 +114,7 @@ export function parseAnnouncement(memo: string): Partial<NEARAnnouncement> | nul
  *   stealthAddress.ephemeralPublicKey,
  *   stealthAddress.viewTag
  * )
- * // => 'SIP:1:1234...abcd:0f'
+ * // => 'SIP:2:1234...abcd:0f'
  * ```
  */
 export function createAnnouncementMemo(
@@ -117,7 +127,8 @@ export function createAnnouncementMemo(
   // Convert view tag to 2-char hex
   const viewTagHex = viewTag.toString(16).padStart(2, '0')
 
-  return `${SIP_MEMO_PREFIX}${ephemeralKeyHex}:${viewTagHex}`
+  // Emit the canonical SIP:2 announcement (EIP-5564). Legacy SIP:1 remains parseable.
+  return `${SIP_MEMO_PREFIX_V2}${ephemeralKeyHex}:${viewTagHex}`
 }
 
 // ─── Transfer Types ──────────────────────────────────────────────────────────

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