fix(monero): harden address, purge, and unlocked balance

.changeset/monero-client-hardening.md

@@ -0,0 +1,5 @@
+---
+'@xchainjs/xchain-monero': patch
+---
+
+Harden Monero client: sync getAddress/setPhrase, clear wallet state on purge, return unlocked balance from wallet-rpc getBalance, add getWalletBalanceDetail, and refuse transfers above unlocked

packages/xchain-monero/README.md

@@ -8,9 +8,9 @@ This package is experimental. Treat it as a local-node adapter, not a general-pu
 
 | Capability | How |
 |---|---|
-| Address from BIP-39 | Pure JS (SLIP-10). Not a 25-word `monero-wallet-cli` seed. |
-| Balance / history | `walletRpcUrls` → `lwsUrls` → bounded daemon scan (≤ 5,000 blocks) |
-| Transfer | **`walletRpcUrls` only.** The in-process RingCT builder is not used. |
+| Address from BIP-39 | Pure JS (SLIP-10). Not a 25-word `monero-wallet-cli` seed. Sync `getAddress` / `setPhrase` supported. |
+| Balance / history | `walletRpcUrls` → `lwsUrls` → bounded daemon scan (≤ 5,000 blocks). Wallet-rpc `getBalance` returns **unlocked** (spendable); use `getWalletBalanceDetail` for total + unlocked. |
+| Transfer | **`walletRpcUrls` only.** Refuses amounts above unlocked balance. The in-process RingCT builder is not used. |
 | Fees | Daemon fee-per-byte × a typical 2-in/2-out weight. Wallet-rpc sets the real fee. |
 
 A public `monerod` cannot answer “what is my balance?” or build a spend. Point the client at your own node plus `monero-wallet-rpc`.

packages/xchain-monero/__tests__/client.test.ts

@@ -111,11 +111,27 @@ describe('Monero client (pure JS)', () => {
     })
 
     it('Should not get address without phrase', async () => {
+      expect(() => client.getAddress()).toThrow(/Phrase must be provided/)
       await expect(async () => client.getAddressAsync()).rejects.toThrow(/Phrase must be provided/)
     })
 
-    it('Should not get address sync method not be implemented', () => {
-      expect(() => client.getAddress()).toThrow('Sync method not supported')
+    it('Should derive the same address sync and async', async () => {
+      const withPhrase = new Client({ ...defaultXMRParams, phrase: TEST_PHRASE })
+      expect(withPhrase.getAddress()).toBe(await withPhrase.getAddressAsync())
+    })
+
+    it('Should setPhrase and return the derived address', () => {
+      const c = new Client()
+      const address = c.setPhrase(TEST_PHRASE)
+      expect(address).toBe(c.getAddress())
+      expect(address.startsWith('4')).toBe(true)
+    })
+
+    it('Should clear wallet state on purgeClient', async () => {
+      const c = new Client({ ...defaultXMRParams, phrase: TEST_PHRASE })
+      expect(c.getAddress()).toBeTruthy()
+      c.purgeClient()
+      expect(() => c.getAddress()).toThrow(/Phrase must be provided/)
     })
 
     it('Should get full derivation path with account 0', () => {
@@ -298,7 +314,8 @@ describe('Monero client (pure JS)', () => {
           case 'get_balance':
             return {
               ok: true,
-              json: async () => ({ result: { balance: 1500000000000, unlocked_balance: 1500000000000 } }),
+              // total > unlocked: getBalance must return unlocked (spendable)
+              json: async () => ({ result: { balance: 2000000000000, unlocked_balance: 1500000000000 } }),
             }
           default:
             return { ok: false, status: 500, statusText: `unexpected ${body.method}` }
@@ -309,6 +326,9 @@ describe('Monero client (pure JS)', () => {
 
       expect(balances).toHaveLength(1)
       expect(balances[0].amount.amount().toString()).toBe('1500000000000')
+      const detail = await client.getWalletBalanceDetail(address)
+      expect(detail.total.amount().toString()).toBe('2000000000000')
+      expect(detail.unlocked.amount().toString()).toBe('1500000000000')
       const walletCalls = mockFetch.mock.calls.filter((call) => String(call[0]).includes('wallet.test'))
       expect(walletCalls.length).toBeGreaterThan(0)
     })
@@ -739,6 +759,11 @@ describe('Monero client (pure JS)', () => {
             return { ok: true, json: async () => ({ result: { blocks_fetched: 0, received_money: false } }) }
           case 'get_height':
             return { ok: true, json: async () => ({ result: { height: 3626705 } }) }
+          case 'get_balance':
+            return {
+              ok: true,
+              json: async () => ({ result: { balance: 5000000000000, unlocked_balance: 5000000000000 } }),
+            }
           case 'transfer':
             return { ok: true, json: async () => ({ result: { tx_hash: 'ef12'.repeat(16) } }) }
           default:
@@ -760,6 +785,49 @@ describe('Monero client (pure JS)', () => {
       expect(payload.params.destinations[0]).toEqual({ amount: 1000000000000, address: dest })
     })
 
+    it('Should refuse transfer when amount exceeds unlocked balance', async () => {
+      const client = new Client({
+        ...defaultXMRParams,
+        phrase: TEST_PHRASE,
+        walletRpcUrls: { [Network.Mainnet]: ['https://wallet.test'], [Network.Testnet]: [], [Network.Stagenet]: [] },
+        daemonUrls: { [Network.Mainnet]: ['https://daemon.test'], [Network.Testnet]: [], [Network.Stagenet]: [] },
+        lwsUrls: { [Network.Mainnet]: [], [Network.Testnet]: [], [Network.Stagenet]: [] },
+        restoreHeight: 3626700,
+      })
+
+      const ownAddress = await client.getAddressAsync()
+
+      mockFetch.mockImplementation(async (input: RequestInfo | URL, init?: RequestInit) => {
+        const url = typeof input === 'string' ? input : input instanceof URL ? input.toString() : input.url
+        const rawBody = typeof init?.body === 'string' ? init.body : '{}'
+        const body = JSON.parse(rawBody) as { method?: string }
+        if (url.includes('daemon.test')) {
+          return { ok: true, json: async () => ({ result: { count: 3626705, status: 'OK' } }) }
+        }
+        switch (body.method) {
+          case 'get_version':
+            return { ok: true, json: async () => ({ result: { version: 65536 } }) }
+          case 'get_address':
+            return { ok: true, json: async () => ({ result: { address: ownAddress } }) }
+          case 'refresh':
+            return { ok: true, json: async () => ({ result: { blocks_fetched: 0, received_money: false } }) }
+          case 'get_height':
+            return { ok: true, json: async () => ({ result: { height: 3626705 } }) }
+          case 'get_balance':
+            return {
+              ok: true,
+              json: async () => ({ result: { balance: 5000000000000, unlocked_balance: 100000000000 } }),
+            }
+          default:
+            return { ok: false, status: 500, statusText: `unexpected ${body.method}` }
+        }
+      })
+
+      await expect(client.transfer({ recipient: dest, amount: baseAmount(1000000000000, 12) })).rejects.toThrow(
+        /Insufficient unlocked balance/,
+      )
+    })
+
     it('Should reject an invalid recipient before calling wallet RPC', async () => {
       const client = new Client({
         ...defaultXMRParams,

packages/xchain-monero/src/client.ts

@@ -11,8 +11,8 @@ import {
   TxHistoryParams,
   TxType,
 } from '@xchainjs/xchain-client'
-import { getSeed } from '@xchainjs/xchain-crypto'
-import { Address, baseAmount } from '@xchainjs/xchain-util'
+import { getSeed, validatePhrase } from '@xchainjs/xchain-crypto'
+import { Address, BaseAmount, baseAmount } from '@xchainjs/xchain-util'
 import { keccak_256 } from '@noble/hashes/sha3'
 import slip10 from 'micro-key-producer/slip10.js'
 
@@ -81,48 +81,55 @@ export class Client extends BaseXChainClient {
   }
 
   /**
-   * Get the current address asynchronously.
-   * Derives keys from mnemonic and encodes as Monero address (pure JS, no WASM).
+   * Derive the Monero address for a wallet index (pure JS, sync).
    */
-  public async getAddressAsync(index?: number): Promise<string> {
+  public getAddress(index?: number): string {
     const spendKey = this.getPrivateSpendKey(index ?? 0)
     const keys = deriveKeyPairs(spendKey)
     const networkType = getMoneroNetworkType(this.getNetwork())
     return encodeAddress(keys.publicSpendKey, keys.publicViewKey, networkType)
   }
 
+  public async getAddressAsync(index?: number): Promise<string> {
+    return this.getAddress(index)
+  }
+
   /**
-   * @deprecated Use getAddressAsync instead
+   * Set or update the mnemonic. Clears cached scan / LWS / wallet-rpc session state
+   * when the phrase changes so a new wallet cannot reuse another wallet's cache.
    */
-  public getAddress(): string {
-    throw Error('Sync method not supported')
+  public setPhrase(phrase: string, walletIndex = 0): Address {
+    if (this.phrase !== phrase) {
+      if (!validatePhrase(phrase)) {
+        throw new Error('Invalid phrase')
+      }
+      this.phrase = phrase
+      this.resetWalletState()
+    }
+    return this.getAddress(walletIndex)
+  }
+
+  /**
+   * Clear phrase and all wallet session state (scan cache, LWS login, rpc lock).
+   */
+  public purgeClient(): void {
+    super.purgeClient()
+    this.resetWalletState()
   }
 
   public validateAddress(address: Address): boolean {
     return validateMoneroAddress(address)
   }
 
   /**
-   * Get balance via wallet-rpc (local monerod), then LWS, then a bounded daemon scan.
+   * Get spendable balance via wallet-rpc (unlocked), then LWS, then a bounded daemon scan.
+   * For wallet-rpc, prefer {@link getWalletBalanceDetail} when both total and unlocked are needed.
    */
   public async getBalance(address: Address): Promise<Balance[]> {
     const walletRpcUrls = this.walletRpcUrls[this.getNetwork()]
     if (walletRpcUrls && walletRpcUrls.length > 0) {
-      const ownAddress = await this.getAddressAsync(0)
-      if (address !== ownAddress) {
-        throw new Error('Monero wallet RPC can only return the balance for the unlocked wallet address')
-      }
-      let lastError: unknown
-      for (const url of walletRpcUrls) {
-        try {
-          const amount = await this.getBalanceFromWalletRpc(url)
-          return [{ asset: AssetXMR, amount: baseAmount(amount.toString(), XMR_DECIMALS) }]
-        } catch (error) {
-          lastError = error
-          console.warn(`Wallet RPC ${url} failed for getBalance:`, (error as Error).message)
-        }
-      }
-      throw lastError instanceof Error ? lastError : new Error('All Monero wallet RPC endpoints failed for getBalance')
+      const detail = await this.getWalletBalanceDetail(address)
+      return [{ asset: AssetXMR, amount: detail.unlocked }]
     }
 
     // Try LWS next
@@ -305,6 +312,37 @@ export class Client extends BaseXChainClient {
     return { total: allOutputs.length, txs }
   }
 
+  /**
+   * Total and unlocked balances from monero-wallet-rpc (own address only).
+   * Unlocked is what can be spent immediately; total includes locked outputs.
+   */
+  public async getWalletBalanceDetail(address: Address): Promise<{ total: BaseAmount; unlocked: BaseAmount }> {
+    const walletRpcUrls = this.walletRpcUrls[this.getNetwork()]
+    if (!walletRpcUrls || walletRpcUrls.length === 0) {
+      throw new Error('getWalletBalanceDetail requires walletRpcUrls')
+    }
+    const ownAddress = this.getAddress(0)
+    if (address !== ownAddress) {
+      throw new Error('Monero wallet RPC can only return the balance for the unlocked wallet address')
+    }
+    let lastError: unknown
+    for (const url of walletRpcUrls) {
+      try {
+        const result = await this.getBalanceFromWalletRpc(url)
+        return {
+          total: baseAmount(result.total.toString(), XMR_DECIMALS),
+          unlocked: baseAmount(result.unlocked.toString(), XMR_DECIMALS),
+        }
+      } catch (error) {
+        lastError = error
+        console.warn(`Wallet RPC ${url} failed for getWalletBalanceDetail:`, (error as Error).message)
+      }
+    }
+    throw lastError instanceof Error
+      ? lastError
+      : new Error('All Monero wallet RPC endpoints failed for getWalletBalanceDetail')
+  }
+
   /**
    * Transfer XMR to a recipient address via monero-wallet-rpc.
    * The in-process RingCT builder is not used: it is not consensus-compatible.
@@ -484,21 +522,38 @@ export class Client extends BaseXChainClient {
     return address
   }
 
-  private async getBalanceFromWalletRpc(url: string): Promise<bigint> {
+  private resetWalletState(): void {
+    this.scanCache = null
+    this.lwsLoggedIn = false
+    this.walletRpcLock = Promise.resolve()
+  }
+
+  private async getBalanceFromWalletRpc(url: string): Promise<{ total: bigint; unlocked: bigint }> {
     return this.withWalletRpcLock(async () => {
       await this.prepareWalletRpc(url)
       const result = await walletRpc.callWithBusyRetry(() => walletRpc.getBalance(url))
-      return BigInt(result.balance)
+      return {
+        total: BigInt(result.balance),
+        unlocked: BigInt(result.unlockedBalance),
+      }
     })
   }
 
   private async transferViaWalletRpc(url: string, params: TxParams): Promise<string> {
     return this.withWalletRpcLock(async () => {
       await this.prepareWalletRpc(url, params.walletIndex ?? 0)
+      const balances = await walletRpc.callWithBusyRetry(() => walletRpc.getBalance(url))
+      const unlocked = BigInt(balances.unlockedBalance)
+      const amountPiconero = BigInt(params.amount.amount().toFixed(0))
+      if (amountPiconero > unlocked) {
+        throw new Error(
+          `Insufficient unlocked balance: need ${amountPiconero.toString()} piconero, unlocked ${unlocked.toString()}`,
+        )
+      }
       return walletRpc.callWithBusyRetry(() =>
         walletRpc.transfer(url, {
           address: params.recipient,
-          amountPiconero: params.amount.amount().toFixed(0).toString(),
+          amountPiconero: amountPiconero.toString(),
         }),
       )
     })