From bbc0d3707245baf0fed4799ce39d11e06105410f Mon Sep 17 00:00:00 2001
From: Om Swami <reach.oms2004@gmail.com>
Date: Wed, 12 Nov 2025 21:30:20 +0530
Subject: [PATCH 01/14] feat: update examples

---
 examples/next-js/app/globals.css |  60 ++++
 examples/next-js/app/page.tsx    | 476 ++++++++++++++++++++++++++++++-
 examples/next-js/package.json    |   1 +
 examples/next-js/utils/wallet.ts |  26 +-
 examples/vite-core/src/App.tsx   |  55 +++-
 examples/vite-core/src/index.css |  60 ++++
 6 files changed, 661 insertions(+), 17 deletions(-)

diff --git a/examples/next-js/app/globals.css b/examples/next-js/app/globals.css
index f73f4812..e37c6bb4 100644
--- a/examples/next-js/app/globals.css
+++ b/examples/next-js/app/globals.css
@@ -172,3 +172,63 @@ button[type='submit'] {
   padding: 0.5rem;
   border-radius: 4px;
 }
+
+.button-group {
+  display: flex;
+  gap: 0.5rem;
+  margin-top: 0.5rem;
+}
+
+.preview-result {
+  margin-top: 1rem;
+  padding: 1rem;
+  background-color: #333;
+  border-radius: 8px;
+  border: 1px solid #444;
+}
+
+.preview-result h4 {
+  margin-top: 0;
+  margin-bottom: 0.75rem;
+  color: rgba(255, 255, 255, 0.87);
+}
+
+.preview-info {
+  display: flex;
+  flex-direction: column;
+  gap: 0.5rem;
+}
+
+.preview-info > div {
+  line-height: 1.6;
+}
+
+.preview-info strong {
+  color: #4a9eff;
+}
+
+.preview-result details {
+  margin-top: 0.75rem;
+  cursor: pointer;
+}
+
+.preview-result summary {
+  padding: 0.5rem;
+  background-color: #242424;
+  border-radius: 4px;
+  user-select: none;
+}
+
+.preview-result summary:hover {
+  background-color: #2a2a2a;
+}
+
+.preview-result pre {
+  margin-top: 0.5rem;
+  padding: 0.75rem;
+  background-color: #1a1a1a;
+  border-radius: 4px;
+  overflow-x: auto;
+  font-size: 0.85rem;
+  line-height: 1.4;
+}
diff --git a/examples/next-js/app/page.tsx b/examples/next-js/app/page.tsx
index 3c1e1632..a9c30737 100644
--- a/examples/next-js/app/page.tsx
+++ b/examples/next-js/app/page.tsx
@@ -1,10 +1,10 @@
 'use client'
 
 import { SetStateAction, useCallback, useEffect, useState } from 'react'
-import { wallet } from '@/utils/wallet'
+import { wallet, director } from '@/utils/wallet'
 
 const TESTNET_FEDERATION_CODE =
-  'fed11qgqzc2nhwden5te0vejkg6tdd9h8gepwvejkg6tdd9h8garhduhx6at5d9h8jmn9wshxxmmd9uqqzgxg6s3evnr6m9zdxr6hxkdkukexpcs3mn7mj3g5pc5dfh63l4tj6g9zk4er'
+  'fed11qgqrgvnhwden5te0v9k8q6rp9ekh2arfdeukuet595cr2ttpd3jhq6rzve6zuer9wchxvetyd938gcewvdhk6tcqqysptkuvknc7erjgf4em3zfh90kffqf9srujn6q53d6r056e4apze5cw27h75'
 
 // Expose the wallet to the global window object for testing
 // @ts-ignore
@@ -14,7 +14,7 @@ const useIsOpen = () => {
   const [open, setIsOpen] = useState(false)
 
   const checkIsOpen = useCallback(() => {
-    if (open !== wallet.isOpen()) {
+    if (wallet && open !== wallet?.isOpen()) {
       setIsOpen(wallet.isOpen())
     }
   }, [open])
@@ -30,7 +30,7 @@ const useBalance = (checkIsOpen: () => void) => {
   const [balance, setBalance] = useState(0)
 
   useEffect(() => {
-    const unsubscribe = wallet.balance.subscribeBalance(
+    const unsubscribe = wallet?.balance.subscribeBalance(
       (balance: SetStateAction<number>) => {
         checkIsOpen()
         setBalance(balance)
@@ -38,7 +38,7 @@ const useBalance = (checkIsOpen: () => void) => {
     )
 
     return () => {
-      unsubscribe()
+      unsubscribe?.()
     }
   }, [checkIsOpen])
 
@@ -78,15 +78,219 @@ const App = () => {
       </header>
       <main>
         <WalletStatus open={open} checkIsOpen={checkIsOpen} balance={balance} />
+        <MnemonicManager />
         <JoinFederation open={open} checkIsOpen={checkIsOpen} />
         <GenerateLightningInvoice />
         <RedeemEcash />
         <SendLightning />
+        <InviteCodeParser />
+        <ParseLightningInvoice />
+        <Deposit />
+        <SendOnchain />
       </main>
     </>
   )
 }
 
+const MnemonicManager = () => {
+  const [mnemonicState, setMnemonicState] = useState<string>('')
+  const [inputMnemonic, setInputMnemonic] = useState<string>('')
+  const [activeAction, setActiveAction] = useState<
+    'get' | 'set' | 'generate' | null
+  >(null)
+  const [isLoading, setIsLoading] = useState(false)
+  const [message, setMessage] = useState<{
+    text: string
+    type: 'success' | 'error'
+  }>()
+  const [showMnemonic, setShowMnemonic] = useState(false)
+
+  const clearMessage = () => setMessage(undefined)
+
+  // Helper function to extract user-friendly error messages
+  const extractErrorMessage = (error: any): string => {
+    let errorMsg = 'Operation failed'
+
+    if (error instanceof Error) {
+      errorMsg = error.message
+    } else if (typeof error === 'object' && error !== null) {
+      // Handle RPC error objects
+      const rpcError = error as any
+      if (rpcError.error) {
+        errorMsg = rpcError.error
+      } else if (rpcError.message) {
+        errorMsg = rpcError.message
+      }
+    }
+
+    return errorMsg
+  }
+
+  const handleAction = async (action: 'get' | 'set' | 'generate') => {
+    if (activeAction === action) {
+      setActiveAction(null)
+      return
+    }
+    setActiveAction(action)
+    clearMessage()
+
+    if (action === 'get') {
+      await handleGetMnemonic()
+    } else if (action === 'generate') {
+      await handleGenerateMnemonic()
+    }
+  }
+
+  const handleGenerateMnemonic = async () => {
+    setIsLoading(true)
+    try {
+      if (!director) throw new Error('Director unavailable')
+      const newMnemonic = await director.generateMnemonic()
+      setMnemonicState(newMnemonic.join(' '))
+      setMessage({ text: 'New mnemonic generated!', type: 'success' })
+      setShowMnemonic(true)
+    } catch (error) {
+      console.error('Error generating mnemonic:', error)
+      const errorMsg = extractErrorMessage(error)
+      setMessage({ text: errorMsg, type: 'error' })
+    } finally {
+      setIsLoading(false)
+    }
+  }
+
+  const handleGetMnemonic = async () => {
+    setIsLoading(true)
+    try {
+      if (!director) throw new Error('Director unavailable')
+      const mnemonic = await director.getMnemonic()
+      if (mnemonic && mnemonic.length > 0) {
+        setMnemonicState(mnemonic.join(' '))
+        setMessage({ text: 'Mnemonic retrieved!', type: 'success' })
+        setShowMnemonic(true)
+      } else {
+        setMessage({ text: 'No mnemonic found', type: 'error' })
+      }
+    } catch (error) {
+      console.error('Error getting mnemonic:', error)
+      const errorMsg = extractErrorMessage(error)
+      setMessage({ text: errorMsg, type: 'error' })
+    } finally {
+      setIsLoading(false)
+    }
+  }
+
+  const handleSetMnemonic = async (e: React.FormEvent) => {
+    e.preventDefault()
+    if (!inputMnemonic.trim()) return
+
+    setIsLoading(true)
+    try {
+      if (!director) throw new Error('Director unavailable')
+      const words = inputMnemonic.trim().split(/\s+/)
+      await director.setMnemonic(words)
+      setMessage({ text: 'Mnemonic set successfully!', type: 'success' })
+      setInputMnemonic('')
+      setMnemonicState(words.join(' '))
+      setActiveAction(null)
+    } catch (error) {
+      console.error('Error setting mnemonic:', error)
+      const errorMsg = extractErrorMessage(error)
+      setMessage({ text: errorMsg, type: 'error' })
+    } finally {
+      setIsLoading(false)
+    }
+  }
+
+  const copyToClipboard = async () => {
+    try {
+      await navigator.clipboard.writeText(mnemonicState)
+      setMessage({ text: 'Copied to clipboard!', type: 'success' })
+    } catch (error) {
+      setMessage({ text: 'Failed to copy', type: 'error' })
+    }
+  }
+
+  return (
+    <div className="section mnemonic-section">
+      <h3>🔑 Mnemonic Manager</h3>
+
+      <div className="mnemonic-buttons">
+        <button
+          onClick={() => handleAction('get')}
+          disabled={isLoading}
+          className={`btn ${activeAction === 'get' ? 'active' : ''}`}
+        >
+          Get
+        </button>
+        <button
+          onClick={() => handleAction('set')}
+          disabled={isLoading}
+          className={`btn ${activeAction === 'set' ? 'active' : ''}`}
+        >
+          Set
+        </button>
+        <button
+          onClick={() => handleAction('generate')}
+          disabled={isLoading}
+          className={`btn ${activeAction === 'generate' ? 'active' : ''}`}
+        >
+          Generate
+        </button>
+      </div>
+
+      {activeAction === 'set' && (
+        <form onSubmit={handleSetMnemonic} className="mnemonic-form">
+          <textarea
+            placeholder="Enter 12 or 24 words separated by spaces"
+            value={inputMnemonic}
+            onChange={(e) => setInputMnemonic(e.target.value)}
+            rows={2}
+            className="mnemonic-input"
+          />
+          <button
+            type="submit"
+            disabled={isLoading || !inputMnemonic.trim()}
+            className="btn btn-primary"
+          >
+            {isLoading ? 'Setting...' : 'Set Mnemonic'}
+          </button>
+        </form>
+      )}
+
+      {mnemonicState && (
+        <div className="mnemonic-display">
+          <div className="mnemonic-output">
+            <span className={showMnemonic ? '' : 'blurred'}>
+              {mnemonicState}
+            </span>
+            <div className="mnemonic-actions">
+              <button
+                onClick={() => setShowMnemonic(!showMnemonic)}
+                className="btn btn-small"
+                title={showMnemonic ? 'Hide mnemonic' : 'Show mnemonic'}
+              >
+                {showMnemonic ? '👁️' : '👁️‍🗨️'}
+              </button>
+              <button
+                onClick={copyToClipboard}
+                className="btn btn-small"
+                disabled={!showMnemonic}
+                title="Copy to clipboard"
+              >
+                📋
+              </button>
+            </div>
+          </div>
+        </div>
+      )}
+
+      {message && (
+        <div className={`message ${message.type}`}>{message.text}</div>
+      )}
+    </div>
+  )
+}
+
 const WalletStatus = ({
   open,
   checkIsOpen,
@@ -121,16 +325,39 @@ const JoinFederation = ({
   checkIsOpen: () => void
 }) => {
   const [inviteCode, setInviteCode] = useState(TESTNET_FEDERATION_CODE)
+  const [previewData, setPreviewData] = useState<any>(null)
+  const [previewing, setPreviewing] = useState(false)
   const [joinResult, setJoinResult] = useState<string | null>(null)
   const [joinError, setJoinError] = useState('')
   const [joining, setJoining] = useState(false)
 
+  const previewFederationHandler = async () => {
+    if (!inviteCode.trim()) return
+
+    setPreviewing(true)
+    setJoinError('')
+
+    try {
+      if (!director) throw new Error('Director unavailable')
+      const data = await director.previewFederation(inviteCode)
+      setPreviewData(data)
+      console.log('Preview federation:', data)
+    } catch (error) {
+      console.error('Error previewing federation:', error)
+      setJoinError(error instanceof Error ? error.message : String(error))
+      setPreviewData(null)
+    } finally {
+      setPreviewing(false)
+    }
+  }
+
   const joinFederation = async (e: React.FormEvent) => {
     e.preventDefault()
     checkIsOpen()
 
     console.log('Joining federation:', inviteCode)
     try {
+      if (!wallet) throw new Error('Wallet unavailable')
       setJoining(true)
       const res = await wallet.joinFederation(inviteCode)
       console.log('join federation res', res)
@@ -154,13 +381,43 @@ const JoinFederation = ({
           placeholder="Invite Code..."
           required
           value={inviteCode}
-          onChange={(e) => setInviteCode(e.target.value)}
+          onChange={(e) => {
+            setInviteCode(e.target.value)
+            setPreviewData(null)
+          }}
           disabled={open}
         />
+        <button
+          type="button"
+          onClick={previewFederationHandler}
+          disabled={previewing || !inviteCode.trim() || open}
+        >
+          {previewing ? 'Previewing...' : 'Preview'}
+        </button>
         <button type="submit" disabled={open || joining}>
-          Join
+          {joining ? 'Joining...' : 'Join'}
         </button>
       </form>
+
+      {previewData && (
+        <div className="preview-result">
+          <h4>Federation Preview:</h4>
+          <div className="preview-info">
+            <div>
+              <strong>Federation ID:</strong> {previewData.federation_id}
+            </div>
+            <div>
+              <strong>Config URL:</strong>{' '}
+              {previewData.config?.meta?.federation_name || 'N/A'}
+            </div>
+            <details>
+              <summary>Full Details</summary>
+              <pre>{JSON.stringify(previewData, null, 2)}</pre>
+            </details>
+          </div>
+        </div>
+      )}
+
       {!joinResult && open && <i>(You've already joined a federation)</i>}
       {joinResult && <div className="success">{joinResult}</div>}
       {joinError && <div className="error">{joinError}</div>}
@@ -316,4 +573,209 @@ const GenerateLightningInvoice = () => {
   )
 }
 
+const InviteCodeParser = () => {
+  const [inviteCode, setInviteCode] = useState('')
+  const [parseResult, setParseResult] = useState<any>(null)
+  const [parseError, setParseError] = useState('')
+  const [parsingStatus, setParsingStatus] = useState(false)
+
+  const handleParse = async (e: React.FormEvent) => {
+    e.preventDefault()
+    setParseResult(null)
+    setParseError('')
+    setParsingStatus(true)
+
+    try {
+      if (!director) throw new Error('Director unavailable')
+      const result = await director.parseInviteCode(inviteCode)
+      setParseResult(result)
+    } catch (e) {
+      console.error('Error parsing invite code', e)
+      setParseError(e instanceof Error ? e.message : String(e))
+    } finally {
+      setParsingStatus(false)
+    }
+  }
+
+  return (
+    <div className="section">
+      <h3>Parse Invite Code</h3>
+      <form onSubmit={handleParse} className="row">
+        <input
+          placeholder="Enter invite code..."
+          value={inviteCode}
+          onChange={(e) => setInviteCode(e.target.value)}
+          required
+        />
+        <button type="submit" disabled={parsingStatus}>
+          {parsingStatus ? 'Parsing...' : 'Parse'}
+        </button>
+      </form>
+      {parseResult && (
+        <div className="success">
+          <div className="row">
+            <strong>Fed Id:</strong>
+            <div className="id">{parseResult.federation_id}</div>
+          </div>
+          <div className="row">
+            <strong>Fed url:</strong>
+            <div className="url">{parseResult.url}</div>
+          </div>
+        </div>
+      )}
+      {parseError && <div className="error">{parseError}</div>}
+    </div>
+  )
+}
+
+const ParseLightningInvoice = () => {
+  const [invoiceStr, setInvoiceStr] = useState('')
+  const [parseResult, setParseResult] = useState<any>(null)
+  const [parseError, setParseError] = useState('')
+  const [parsingStatus, setParsingStatus] = useState(false)
+
+  const handleParse = async (e: React.FormEvent) => {
+    e.preventDefault()
+    setParseResult(null)
+    setParseError('')
+    setParsingStatus(true)
+
+    try {
+      if (!director) throw new Error('Director unavailable')
+      const result = await director.parseBolt11Invoice(invoiceStr)
+      console.log('result ', result)
+      setParseResult(result)
+    } catch (e) {
+      console.error('Error parsing invite code', e)
+      setParseError(e instanceof Error ? e.message : String(e))
+    } finally {
+      setParsingStatus(false)
+    }
+  }
+
+  return (
+    <div className="section">
+      <h3>Parse Lightning Invoice</h3>
+      <form onSubmit={handleParse} className="row">
+        <input
+          placeholder="Enter invoice..."
+          value={invoiceStr}
+          onChange={(e) => setInvoiceStr(e.target.value)}
+          required
+        />
+        <button type="submit" disabled={parsingStatus}>
+          {parsingStatus ? 'Parsing...' : 'Parse'}
+        </button>
+      </form>
+      {parseResult && (
+        <div className="success">
+          <div className="row">
+            <strong>Amount :</strong>
+            <div className="id">{parseResult.amount}</div>
+            sats
+          </div>
+          <div className="row">
+            <strong>Expiry :</strong>
+            <div className="url">{parseResult.expiry}</div>
+          </div>
+          <div className="row">
+            <strong>Memo :</strong>
+            <div className="url">{parseResult.memo}</div>
+          </div>
+        </div>
+      )}
+      {parseError && <div className="error">{parseError}</div>}
+    </div>
+  )
+}
+
+const Deposit = () => {
+  const [address, setAddress] = useState<string>('')
+  const [addressError, setAddressError] = useState('')
+  const [addressStatus, setAddressStatus] = useState(false)
+
+  const handleGenerateAddress = async (e: React.FormEvent) => {
+    e.preventDefault()
+    setAddressStatus(true)
+    try {
+      if (!wallet) throw new Error('Wallet unavailable')
+      const result = await wallet.wallet.generateAddress()
+      result && setAddress(result.deposit_address)
+    } catch (e) {
+      console.error('Error', e)
+      setAddressError(e instanceof Error ? e.message : String(e))
+    } finally {
+      setAddressStatus(false)
+    }
+  }
+  return (
+    <div className="section">
+      <h3>Generate Deposit Address</h3>
+      <form onSubmit={handleGenerateAddress} className="row">
+        <button type="submit" disabled={addressStatus}>
+          {addressStatus ? 'Generating...' : 'Generate'}
+        </button>
+      </form>
+      {address && (
+        <div className="success">
+          <p>{address}</p>
+        </div>
+      )}
+      {addressError && <div className="error">{addressError}</div>}
+    </div>
+  )
+}
+
+const SendOnchain = () => {
+  const [address, setAddress] = useState('')
+  const [amount, setAmount] = useState(0)
+  const [withdrawalResult, setWithdrawalResult] = useState('')
+  const [withdrawalError, setWithdrawalError] = useState('')
+  const [withdrawalStatus, setWithdrawalStatus] = useState(false)
+
+  const handleWithdraw = async (e: React.FormEvent) => {
+    e.preventDefault()
+    try {
+      setWithdrawalStatus(true)
+      if (!wallet) throw new Error('Wallet unavailable')
+      const result = await wallet.wallet.sendOnchain(amount, address)
+      result && setWithdrawalResult(result.operation_id)
+    } catch (e) {
+      console.error('Error ', e)
+      setWithdrawalError(e instanceof Error ? e.message : String(e))
+    } finally {
+      setWithdrawalStatus(false)
+    }
+  }
+  return (
+    <div className="section">
+      <h3>Send Onchain</h3>
+      <form onSubmit={handleWithdraw} className="row">
+        <input
+          placeholder="Enter amount"
+          type="number"
+          value={amount}
+          onChange={(e) => setAmount(Number(e.target.value))}
+          required
+        />
+        <input
+          placeholder="Enter onchain address"
+          value={address}
+          onChange={(e) => setAddress(e.target.value)}
+          required
+        />
+        <button type="submit" disabled={withdrawalStatus}>
+          {withdrawalStatus ? 'Sending' : 'Send'}
+        </button>
+      </form>
+      {withdrawalResult && (
+        <div className="success">
+          <p>Onchain Send Successful</p>
+        </div>
+      )}
+      {withdrawalError && <div className="error">{withdrawalError}</div>}
+    </div>
+  )
+}
+
 export default App
diff --git a/examples/next-js/package.json b/examples/next-js/package.json
index 2252da82..792f9f27 100644
--- a/examples/next-js/package.json
+++ b/examples/next-js/package.json
@@ -9,6 +9,7 @@
   },
   "dependencies": {
     "@fedimint/core": "latest",
+    "@fedimint/transport-web": "latest",
     "next": "15.2.4",
     "react": ">=19.2.0",
     "react-dom": ">=19.2.0"
diff --git a/examples/next-js/utils/wallet.ts b/examples/next-js/utils/wallet.ts
index 81cff9a2..7093e2f9 100644
--- a/examples/next-js/utils/wallet.ts
+++ b/examples/next-js/utils/wallet.ts
@@ -1,14 +1,24 @@
-import { FedimintWallet } from '@fedimint/core'
+import { type FedimintWallet, WalletDirector } from '@fedimint/core'
+import { WasmWorkerTransport } from '@fedimint/transport-web'
 
-let wallet: FedimintWallet
+let director: WalletDirector | undefined
+let wallet: FedimintWallet | undefined
 
 if (typeof window !== 'undefined') {
-  wallet = new FedimintWallet()
-  wallet.setLogLevel('debug')
-  wallet.open()
+  director = new WalletDirector(new WasmWorkerTransport())
+  director.createWallet().then((_wallet) => {
+    console.log('Creating wallet...')
+    _wallet.open()
+    wallet = _wallet
 
-  // Expose for testing
-  // globalThis.wallet = wallet
+    // Expose the wallet to the global window object for testing
+    // @ts-ignore
+    globalThis.wallet = wallet
+    // @ts-ignore
+    globalThis.director = director
+  })
+
+  director.setLogLevel('debug')
 }
 
-export { wallet }
+export { wallet, director }
diff --git a/examples/vite-core/src/App.tsx b/examples/vite-core/src/App.tsx
index edfa89be..a6fd0b82 100644
--- a/examples/vite-core/src/App.tsx
+++ b/examples/vite-core/src/App.tsx
@@ -317,10 +317,31 @@ const JoinFederation = ({
   checkIsOpen: () => void
 }) => {
   const [inviteCode, setInviteCode] = useState(TESTNET_FEDERATION_CODE)
+  const [previewData, setPreviewData] = useState<any>(null)
+  const [previewing, setPreviewing] = useState(false)
   const [joinResult, setJoinResult] = useState<string | null>(null)
   const [joinError, setJoinError] = useState('')
   const [joining, setJoining] = useState(false)
 
+  const previewFederationHandler = async () => {
+    if (!inviteCode.trim()) return
+
+    setPreviewing(true)
+    setJoinError('')
+
+    try {
+      const data = await director.previewFederation(inviteCode)
+      setPreviewData(data)
+      console.log('Preview federation:', data)
+    } catch (error) {
+      console.error('Error previewing federation:', error)
+      setJoinError(error instanceof Error ? error.message : String(error))
+      setPreviewData(null)
+    } finally {
+      setPreviewing(false)
+    }
+  }
+
   const joinFederation = async (e: React.FormEvent) => {
     e.preventDefault()
     checkIsOpen()
@@ -351,13 +372,43 @@ const JoinFederation = ({
           placeholder="Invite Code..."
           required
           value={inviteCode}
-          onChange={(e) => setInviteCode(e.target.value)}
+          onChange={(e) => {
+            setInviteCode(e.target.value)
+            setPreviewData(null)
+          }}
           disabled={open}
         />
+        <button
+          type="button"
+          onClick={previewFederationHandler}
+          disabled={previewing || !inviteCode.trim() || open}
+        >
+          {previewing ? 'Previewing...' : 'Preview'}
+        </button>
         <button type="submit" disabled={open || joining}>
-          Join
+          {joining ? 'Joining...' : 'Join'}
         </button>
       </form>
+
+      {previewData && (
+        <div className="preview-result">
+          <h4>Federation Preview:</h4>
+          <div className="preview-info">
+            <div>
+              <strong>Federation ID:</strong> {previewData.federation_id}
+            </div>
+            <div>
+              <strong>Config URL:</strong>{' '}
+              {previewData.config?.meta?.federation_name || 'N/A'}
+            </div>
+            <details>
+              <summary>Full Details</summary>
+              <pre>{JSON.stringify(previewData, null, 2)}</pre>
+            </details>
+          </div>
+        </div>
+      )}
+
       {!joinResult && open && <i>(You've already joined a federation)</i>}
       {joinResult && <div className="success">{joinResult}</div>}
       {joinError && <div className="error">{joinError}</div>}
diff --git a/examples/vite-core/src/index.css b/examples/vite-core/src/index.css
index f73f4812..e37c6bb4 100644
--- a/examples/vite-core/src/index.css
+++ b/examples/vite-core/src/index.css
@@ -172,3 +172,63 @@ button[type='submit'] {
   padding: 0.5rem;
   border-radius: 4px;
 }
+
+.button-group {
+  display: flex;
+  gap: 0.5rem;
+  margin-top: 0.5rem;
+}
+
+.preview-result {
+  margin-top: 1rem;
+  padding: 1rem;
+  background-color: #333;
+  border-radius: 8px;
+  border: 1px solid #444;
+}
+
+.preview-result h4 {
+  margin-top: 0;
+  margin-bottom: 0.75rem;
+  color: rgba(255, 255, 255, 0.87);
+}
+
+.preview-info {
+  display: flex;
+  flex-direction: column;
+  gap: 0.5rem;
+}
+
+.preview-info > div {
+  line-height: 1.6;
+}
+
+.preview-info strong {
+  color: #4a9eff;
+}
+
+.preview-result details {
+  margin-top: 0.75rem;
+  cursor: pointer;
+}
+
+.preview-result summary {
+  padding: 0.5rem;
+  background-color: #242424;
+  border-radius: 4px;
+  user-select: none;
+}
+
+.preview-result summary:hover {
+  background-color: #2a2a2a;
+}
+
+.preview-result pre {
+  margin-top: 0.5rem;
+  padding: 0.75rem;
+  background-color: #1a1a1a;
+  border-radius: 4px;
+  overflow-x: auto;
+  font-size: 0.85rem;
+  line-height: 1.4;
+}

From d4a2ead620ab6172ef2130075bbc39331b4e4d82 Mon Sep 17 00:00:00 2001
From: Om Swami <reach.oms2004@gmail.com>
Date: Wed, 12 Nov 2025 21:55:06 +0530
Subject: [PATCH 02/14] feat: add backup support through RecoveryService feat:
 add backup to federation in example

---
 examples/next-js/app/page.tsx                 | 52 +++++++++++++++++++
 examples/vite-core/src/App.tsx                | 52 +++++++++++++++++++
 packages/core/src/services/RecoveryService.ts |  9 ++++
 pnpm-lock.yaml                                |  3 ++
 4 files changed, 116 insertions(+)

diff --git a/examples/next-js/app/page.tsx b/examples/next-js/app/page.tsx
index a9c30737..04053313 100644
--- a/examples/next-js/app/page.tsx
+++ b/examples/next-js/app/page.tsx
@@ -87,6 +87,7 @@ const App = () => {
         <ParseLightningInvoice />
         <Deposit />
         <SendOnchain />
+        <BackupToFederation />
       </main>
     </>
   )
@@ -778,4 +779,55 @@ const SendOnchain = () => {
   )
 }
 
+const BackupToFederation = () => {
+  const [backupStatus, setBackupStatus] = useState(false)
+  const [backupResult, setBackupResult] = useState('')
+  const [backupError, setBackupError] = useState('')
+  const [metadata, setMetadata] = useState('')
+
+  const handleBackup = async (e: React.FormEvent) => {
+    e.preventDefault()
+    setBackupStatus(true)
+    setBackupResult('')
+    setBackupError('')
+
+    try {
+      if (!wallet) throw new Error('Wallet unavailable')
+
+      const metadataObj = metadata.trim() ? JSON.parse(metadata) : undefined
+      await wallet.recovery.backupToFederation(metadataObj)
+
+      console.log('Backup successful')
+      setBackupResult('Backup to federation successful!')
+    } catch (error: any) {
+      console.error('Error backing up to federation:', error)
+      setBackupError(error.message || 'Backup failed')
+    } finally {
+      setBackupStatus(false)
+    }
+  }
+
+  return (
+    <div className="section">
+      <h3>Backup to Federation</h3>
+      <form onSubmit={handleBackup} className="row">
+        <input
+          placeholder="Metadata (optional JSON)"
+          value={metadata}
+          onChange={(e) => setMetadata(e.target.value)}
+        />
+        <button type="submit" disabled={backupStatus}>
+          {backupStatus ? 'Backing up...' : 'Backup'}
+        </button>
+      </form>
+      {backupResult && (
+        <div className="success">
+          <p>{backupResult}</p>
+        </div>
+      )}
+      {backupError && <div className="error">{backupError}</div>}
+    </div>
+  )
+}
+
 export default App
diff --git a/examples/vite-core/src/App.tsx b/examples/vite-core/src/App.tsx
index a6fd0b82..dd9aaf36 100644
--- a/examples/vite-core/src/App.tsx
+++ b/examples/vite-core/src/App.tsx
@@ -82,6 +82,7 @@ const App = () => {
         <ParseLightningInvoice />
         <Deposit />
         <SendOnchain />
+        <BackupToFederation />
       </main>
     </>
   )
@@ -770,4 +771,55 @@ const SendOnchain = () => {
   )
 }
 
+const BackupToFederation = () => {
+  const [backupStatus, setBackupStatus] = useState(false)
+  const [backupResult, setBackupResult] = useState('')
+  const [backupError, setBackupError] = useState('')
+  const [metadata, setMetadata] = useState('')
+
+  const handleBackup = async (e: React.FormEvent) => {
+    e.preventDefault()
+    setBackupStatus(true)
+    setBackupResult('')
+    setBackupError('')
+
+    try {
+      if (!wallet) throw new Error('Wallet unavailable')
+
+      const metadataObj = metadata.trim() ? JSON.parse(metadata) : undefined
+      await wallet.recovery.backupToFederation(metadataObj)
+
+      console.log('Backup successful')
+      setBackupResult('Backup to federation successful!')
+    } catch (error: any) {
+      console.error('Error backing up to federation:', error)
+      setBackupError(error.message || 'Backup failed')
+    } finally {
+      setBackupStatus(false)
+    }
+  }
+
+  return (
+    <div className="section">
+      <h3>Backup to Federation</h3>
+      <form onSubmit={handleBackup} className="row">
+        <input
+          placeholder="Metadata (optional JSON)"
+          value={metadata}
+          onChange={(e) => setMetadata(e.target.value)}
+        />
+        <button type="submit" disabled={backupStatus}>
+          {backupStatus ? 'Backing up...' : 'Backup'}
+        </button>
+      </form>
+      {backupResult && (
+        <div className="success">
+          <p>{backupResult}</p>
+        </div>
+      )}
+      {backupError && <div className="error">{backupError}</div>}
+    </div>
+  )
+}
+
 export default App
diff --git a/packages/core/src/services/RecoveryService.ts b/packages/core/src/services/RecoveryService.ts
index 5f7eba34..ac0d1e22 100644
--- a/packages/core/src/services/RecoveryService.ts
+++ b/packages/core/src/services/RecoveryService.ts
@@ -41,4 +41,13 @@ export class RecoveryService {
       onError,
     )
   }
+
+  async backupToFederation(metadata?: JSONValue): Promise<void> {
+    await this.client.rpcSingle(
+      '',
+      'backup_to_federation',
+      { metadata: metadata ?? {} },
+      this.clientName,
+    )
+  }
 }
diff --git a/pnpm-lock.yaml b/pnpm-lock.yaml
index 9be7a9ed..a32ca138 100644
--- a/pnpm-lock.yaml
+++ b/pnpm-lock.yaml
@@ -95,6 +95,9 @@ importers:
       '@fedimint/core':
         specifier: latest
         version: 0.1.3
+      '@fedimint/transport-web':
+        specifier: latest
+        version: 0.1.2(@fedimint/core@0.1.3)
       next:
         specifier: 15.2.4
         version: 15.2.4(react-dom@19.2.0(react@19.2.0))(react@19.2.0)

From 4efb05b27ef64af13df5a6703bb352f5c16470f0 Mon Sep 17 00:00:00 2001
From: Om Swami <reach.oms2004@gmail.com>
Date: Wed, 12 Nov 2025 22:59:46 +0530
Subject: [PATCH 03/14] chore: update docs for recoveryService

---
 docs/.vitepress/sidebar.ts                    | 10 ++++-
 .../RecoveryService/backupToFederation.md     | 44 +++++++++++++++++++
 .../RecoveryService/hasPendingRecoveries.md   | 31 +++++++++++++
 .../subscribeToRecoveryProgress.md            | 44 +++++++++++++++++++
 .../RecoveryService/waitForAllRecoveries.md   | 28 ++++++++++++
 docs/core/FedimintWallet/joinFederation.md    |  4 ++
 6 files changed, 160 insertions(+), 1 deletion(-)
 create mode 100644 docs/core/FedimintWallet/RecoveryService/backupToFederation.md
 create mode 100644 docs/core/FedimintWallet/RecoveryService/hasPendingRecoveries.md
 create mode 100644 docs/core/FedimintWallet/RecoveryService/subscribeToRecoveryProgress.md
 create mode 100644 docs/core/FedimintWallet/RecoveryService/waitForAllRecoveries.md

diff --git a/docs/.vitepress/sidebar.ts b/docs/.vitepress/sidebar.ts
index 68aa09e3..096abc93 100644
--- a/docs/.vitepress/sidebar.ts
+++ b/docs/.vitepress/sidebar.ts
@@ -138,7 +138,15 @@ const FedimintWalletSidebar = [
       {
         text: 'RecoveryService',
         base: '/core/FedimintWallet/RecoveryService/',
-        items: [{ text: 'Docs TODO' }],
+        items: [
+          { text: 'backupToFederation()', link: 'backupToFederation' },
+          { text: 'hasPendingRecoveries()', link: 'hasPendingRecoveries' },
+          {
+            text: 'subscribeToRecoveryProgress()',
+            link: 'subscribeToRecoveryProgress',
+          },
+          { text: 'waitForAllRecoveries()', link: 'waitForAllRecoveries' },
+        ],
       },
     ],
   },
diff --git a/docs/core/FedimintWallet/RecoveryService/backupToFederation.md b/docs/core/FedimintWallet/RecoveryService/backupToFederation.md
new file mode 100644
index 00000000..0f59fada
--- /dev/null
+++ b/docs/core/FedimintWallet/RecoveryService/backupToFederation.md
@@ -0,0 +1,44 @@
+# Backup to Federation
+
+### `recovery.backupToFederation(metadata?: JSONValue)`
+
+Backup the wallet state to the federation with optional metadata.
+
+```ts twoslash
+// @esModuleInterop
+import { WalletDirector } from '@fedimint/core'
+import { WasmWorkerTransport } from '@fedimint/transport-web'
+
+const director = new WalletDirector(new WasmWorkerTransport())
+const wallet = await director.createWallet()
+
+await wallet.open()
+
+// Backup without metadata
+try {
+  await wallet.recovery.backupToFederation() // [!code focus]
+  console.log('Backup successful')
+} catch (error) {
+  console.error('Failed to backup', error)
+}
+
+// Backup with metadata
+try {
+  await wallet.recovery.backupToFederation({
+    // [!code focus]
+    timestamp: Date.now(), // [!code focus]
+    note: 'My backup', // [!code focus]
+  }) // [!code focus]
+  console.log('Backup with metadata successful')
+} catch (error) {
+  console.error('Failed to backup', error)
+}
+```
+
+## Parameters
+
+- `metadata` (optional): A JSON value containing custom metadata to store with the backup. Defaults to an empty object if not provided.
+
+## Returns
+
+Returns a `Promise<void>` that resolves when the backup is complete.
diff --git a/docs/core/FedimintWallet/RecoveryService/hasPendingRecoveries.md b/docs/core/FedimintWallet/RecoveryService/hasPendingRecoveries.md
new file mode 100644
index 00000000..7fc0bb7c
--- /dev/null
+++ b/docs/core/FedimintWallet/RecoveryService/hasPendingRecoveries.md
@@ -0,0 +1,31 @@
+# Has Pending Recoveries
+
+### `recovery.hasPendingRecoveries()`
+
+Check if there are any pending recovery operations.
+
+```ts twoslash
+// @esModuleInterop
+import { WalletDirector } from '@fedimint/core'
+import { WasmWorkerTransport } from '@fedimint/transport-web'
+
+const director = new WalletDirector(new WasmWorkerTransport())
+const wallet = await director.createWallet()
+
+await wallet.open()
+
+try {
+  const hasPending = await wallet.recovery.hasPendingRecoveries() // [!code focus]
+  if (hasPending) {
+    console.log('Recovery operations in progress')
+  } else {
+    console.log('No pending recoveries')
+  }
+} catch (error) {
+  console.error('Failed to check recovery status', error)
+}
+```
+
+## Returns
+
+Returns a `Promise<boolean>` that resolves to `true` if there are pending recoveries, `false` otherwise.
diff --git a/docs/core/FedimintWallet/RecoveryService/subscribeToRecoveryProgress.md b/docs/core/FedimintWallet/RecoveryService/subscribeToRecoveryProgress.md
new file mode 100644
index 00000000..53f2a71c
--- /dev/null
+++ b/docs/core/FedimintWallet/RecoveryService/subscribeToRecoveryProgress.md
@@ -0,0 +1,44 @@
+# Subscribe to Recovery Progress
+
+### `recovery.subscribeToRecoveryProgress(onSuccess, onError)`
+
+Subscribe to recovery progress updates for all modules.
+
+```ts twoslash
+// @esModuleInterop
+import { WalletDirector } from '@fedimint/core'
+import { WasmWorkerTransport } from '@fedimint/transport-web'
+
+const director = new WalletDirector(new WasmWorkerTransport())
+const wallet = await director.createWallet()
+
+await wallet.open()
+
+const unsubscribe = wallet.recovery.subscribeToRecoveryProgress(
+  // [!code focus]
+  (progress) => {
+    // [!code focus]
+    console.log('Module:', progress.module_id) // [!code focus]
+    console.log('Progress:', progress.progress) // [!code focus]
+  }, // [!code focus]
+  (error) => {
+    // [!code focus]
+    // [!code focus]
+    console.error('Recovery error:', error) // [!code focus]
+  }, // [!code focus]
+) // [!code focus]
+
+// Later, to stop listening for updates
+unsubscribe()
+```
+
+## Parameters
+
+- `onSuccess`: Callback function invoked with progress updates. Receives an object containing:
+  - `module_id`: The module identifier (number)
+  - `progress`: The progress data (JSONValue)
+- `onError`: Callback function invoked when an error occurs. Receives an error string.
+
+## Returns
+
+Returns a function that can be called to unsubscribe from progress updates.
diff --git a/docs/core/FedimintWallet/RecoveryService/waitForAllRecoveries.md b/docs/core/FedimintWallet/RecoveryService/waitForAllRecoveries.md
new file mode 100644
index 00000000..69672749
--- /dev/null
+++ b/docs/core/FedimintWallet/RecoveryService/waitForAllRecoveries.md
@@ -0,0 +1,28 @@
+# Wait for All Recoveries
+
+### `recovery.waitForAllRecoveries()`
+
+Wait for all pending recovery operations to complete.
+
+```ts twoslash
+// @esModuleInterop
+import { WalletDirector } from '@fedimint/core'
+import { WasmWorkerTransport } from '@fedimint/transport-web'
+
+const director = new WalletDirector(new WasmWorkerTransport())
+const wallet = await director.createWallet()
+
+await wallet.open()
+
+try {
+  console.log('Waiting for recoveries to complete...')
+  await wallet.recovery.waitForAllRecoveries() // [!code focus]
+  console.log('All recoveries completed')
+} catch (error) {
+  console.error('Recovery failed', error)
+}
+```
+
+## Returns
+
+Returns a `Promise<void>` that resolves when all recovery operations are complete.
diff --git a/docs/core/FedimintWallet/joinFederation.md b/docs/core/FedimintWallet/joinFederation.md
index ae9a1ddd..e25b7df5 100644
--- a/docs/core/FedimintWallet/joinFederation.md
+++ b/docs/core/FedimintWallet/joinFederation.md
@@ -4,6 +4,10 @@
 
 Attempts to join a federation.
 
+::: info Automatic Backup Recovery
+If you have a backup stored with the federation, it will be automatically fetched and restored when you join the federation.
+:::
+
 ```ts twoslash
 // @esModuleInterop
 import { WalletDirector } from '@fedimint/core'

From 9850c8777899fcc659eba4874d8d4a16d70c1ce7 Mon Sep 17 00:00:00 2001
From: Om Swami <reach.oms2004@gmail.com>
Date: Sun, 14 Dec 2025 19:46:40 +0530
Subject: [PATCH 04/14] chore: fix code focus

---
 docs/core/FedimintWallet/RecoveryService/backupToFederation.md | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/docs/core/FedimintWallet/RecoveryService/backupToFederation.md b/docs/core/FedimintWallet/RecoveryService/backupToFederation.md
index 0f59fada..7d1207f4 100644
--- a/docs/core/FedimintWallet/RecoveryService/backupToFederation.md
+++ b/docs/core/FedimintWallet/RecoveryService/backupToFederation.md
@@ -2,7 +2,7 @@
 
 ### `recovery.backupToFederation(metadata?: JSONValue)`
 
-Backup the wallet state to the federation with optional metadata.
+Backup the wallet state to the federation with optional metadata. You should call this function periodically to refresh the user's backups.
 
 ```ts twoslash
 // @esModuleInterop

From b737efe1c1957e20269bb5c27f6854cf3fbf4641 Mon Sep 17 00:00:00 2001
From: Om Swami <reach.oms2004@gmail.com>
Date: Sun, 14 Dec 2025 19:54:22 +0530
Subject: [PATCH 05/14] chore: change waitForAllRecoveries to waitForRecovery

---
 docs/.vitepress/sidebar.ts                                | 2 +-
 .../{waitForAllRecoveries.md => waitForRecovery.md}       | 8 ++++----
 packages/core/src/services/RecoveryService.ts             | 2 +-
 3 files changed, 6 insertions(+), 6 deletions(-)
 rename docs/core/FedimintWallet/RecoveryService/{waitForAllRecoveries.md => waitForRecovery.md} (74%)

diff --git a/docs/.vitepress/sidebar.ts b/docs/.vitepress/sidebar.ts
index bdff9979..6fbd20c8 100644
--- a/docs/.vitepress/sidebar.ts
+++ b/docs/.vitepress/sidebar.ts
@@ -149,7 +149,7 @@ const FedimintWalletSidebar = [
             text: 'subscribeToRecoveryProgress()',
             link: 'subscribeToRecoveryProgress',
           },
-          { text: 'waitForAllRecoveries()', link: 'waitForAllRecoveries' },
+          { text: 'waitForRecovery()', link: 'waitForRecovery' },
         ],
       },
     ],
diff --git a/docs/core/FedimintWallet/RecoveryService/waitForAllRecoveries.md b/docs/core/FedimintWallet/RecoveryService/waitForRecovery.md
similarity index 74%
rename from docs/core/FedimintWallet/RecoveryService/waitForAllRecoveries.md
rename to docs/core/FedimintWallet/RecoveryService/waitForRecovery.md
index 69672749..8f4e9f98 100644
--- a/docs/core/FedimintWallet/RecoveryService/waitForAllRecoveries.md
+++ b/docs/core/FedimintWallet/RecoveryService/waitForRecovery.md
@@ -1,8 +1,8 @@
-# Wait for All Recoveries
+# Wait for Recovery
 
-### `recovery.waitForAllRecoveries()`
+### `recovery.waitForRecovery()`
 
-Wait for all pending recovery operations to complete.
+Wait for all pending recovery operations of a particular wallet to complete.
 
 ```ts twoslash
 // @esModuleInterop
@@ -16,7 +16,7 @@ await wallet.open()
 
 try {
   console.log('Waiting for recoveries to complete...')
-  await wallet.recovery.waitForAllRecoveries() // [!code focus]
+  await wallet.recovery.waitForRecovery() // [!code focus]
   console.log('All recoveries completed')
 } catch (error) {
   console.error('Recovery failed', error)
diff --git a/packages/core/src/services/RecoveryService.ts b/packages/core/src/services/RecoveryService.ts
index ac0d1e22..0e3dc415 100644
--- a/packages/core/src/services/RecoveryService.ts
+++ b/packages/core/src/services/RecoveryService.ts
@@ -16,7 +16,7 @@ export class RecoveryService {
     )
   }
 
-  async waitForAllRecoveries() {
+  async waitForRecovery() {
     await this.client.rpcSingle(
       '',
       'wait_for_all_recoveries',

From 20f0a8a72cc031431b301bd8428014ab7950fece Mon Sep 17 00:00:00 2001
From: Om Swami <reach.oms2004@gmail.com>
Date: Sun, 14 Dec 2025 20:52:47 +0530
Subject: [PATCH 06/14] chore: update docs

---
 .../RecoveryService/subscribeToRecoveryProgress.md               | 1 -
 1 file changed, 1 deletion(-)

diff --git a/docs/core/FedimintWallet/RecoveryService/subscribeToRecoveryProgress.md b/docs/core/FedimintWallet/RecoveryService/subscribeToRecoveryProgress.md
index 53f2a71c..654f40e8 100644
--- a/docs/core/FedimintWallet/RecoveryService/subscribeToRecoveryProgress.md
+++ b/docs/core/FedimintWallet/RecoveryService/subscribeToRecoveryProgress.md
@@ -22,7 +22,6 @@ const unsubscribe = wallet.recovery.subscribeToRecoveryProgress(
     console.log('Progress:', progress.progress) // [!code focus]
   }, // [!code focus]
   (error) => {
-    // [!code focus]
     // [!code focus]
     console.error('Recovery error:', error) // [!code focus]
   }, // [!code focus]

From c163d0bc770a7ba5dafb3fcfa7a5f3da280933b7 Mon Sep 17 00:00:00 2001
From: Om Swami <reach.oms2004@gmail.com>
Date: Sun, 14 Dec 2025 21:03:40 +0530
Subject: [PATCH 07/14] chore: add docs

---
 docs/core/FedimintWallet/joinFederation.md | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)

diff --git a/docs/core/FedimintWallet/joinFederation.md b/docs/core/FedimintWallet/joinFederation.md
index e25b7df5..961b63c6 100644
--- a/docs/core/FedimintWallet/joinFederation.md
+++ b/docs/core/FedimintWallet/joinFederation.md
@@ -4,8 +4,8 @@
 
 Attempts to join a federation.
 
-::: info Automatic Backup Recovery
-If you have a backup stored with the federation, it will be automatically fetched and restored when you join the federation.
+::: info
+If there is an existing backup stored with the federation associated with the user's root mnemonic, it will be automatically fetched and restored when you join the federation.
 :::
 
 ```ts twoslash

From 3c334a9e9923c56a5ce1283adb305bbe165c20a4 Mon Sep 17 00:00:00 2001
From: Om Swami <reach.oms2004@gmail.com>
Date: Sun, 14 Dec 2025 21:17:18 +0530
Subject: [PATCH 08/14] chore: add warning to all the functions that are    
 are inaccessible during recovery of a wallet.

---
 docs/core/FedimintWallet/BalanceService/getBalance.md         | 2 ++
 docs/core/FedimintWallet/BalanceService/subscribeBalance.md   | 2 ++
 docs/core/FedimintWallet/FederationService/getConfig.md       | 2 ++
 docs/core/FedimintWallet/FederationService/getFederationId.md | 2 ++
 docs/core/FedimintWallet/FederationService/getInviteCode.md   | 2 ++
 docs/core/FedimintWallet/FederationService/getOperation.md    | 2 ++
 docs/core/FedimintWallet/FederationService/listOperations.md  | 2 ++
 .../core/FedimintWallet/FederationService/listTransactions.md | 2 ++
 docs/core/FedimintWallet/LightningService/createInvoice.md    | 2 ++
 docs/core/FedimintWallet/LightningService/payInvoice.md       | 4 ++++
 .../core/FedimintWallet/MintService/getNotesByDenomination.md | 2 ++
 docs/core/FedimintWallet/MintService/parseNotes.md            | 2 ++
 docs/core/FedimintWallet/MintService/redeemEcash.md           | 2 ++
 docs/core/FedimintWallet/MintService/spendNotes.md            | 2 ++
 .../core/FedimintWallet/RecoveryService/backupToFederation.md | 2 ++
 docs/core/FedimintWallet/WalletService/generateAddress.md     | 2 ++
 docs/core/FedimintWallet/WalletService/getWalletSummary.md    | 2 ++
 docs/core/FedimintWallet/WalletService/sendOnchain.md         | 2 ++
 18 files changed, 38 insertions(+)

diff --git a/docs/core/FedimintWallet/BalanceService/getBalance.md b/docs/core/FedimintWallet/BalanceService/getBalance.md
index 99820485..dc8900a8 100644
--- a/docs/core/FedimintWallet/BalanceService/getBalance.md
+++ b/docs/core/FedimintWallet/BalanceService/getBalance.md
@@ -4,6 +4,8 @@
 
 Get the current balance of the wallet in milli-satoshis (MSats).
 
+> **WARNING**: This function will throw an error if the wallet is currently recovering.
+
 ```ts twoslash
 // @esModuleInterop
 import { WalletDirector } from '@fedimint/core'
diff --git a/docs/core/FedimintWallet/BalanceService/subscribeBalance.md b/docs/core/FedimintWallet/BalanceService/subscribeBalance.md
index c9162d32..ed1678b2 100644
--- a/docs/core/FedimintWallet/BalanceService/subscribeBalance.md
+++ b/docs/core/FedimintWallet/BalanceService/subscribeBalance.md
@@ -4,6 +4,8 @@
 
 Subscribe to balance updates as they occur.
 
+> **WARNING**: This function will throw an error if the wallet is currently recovering.
+
 ```ts twoslash
 // @esModuleInterop
 import { WalletDirector } from '@fedimint/core'
diff --git a/docs/core/FedimintWallet/FederationService/getConfig.md b/docs/core/FedimintWallet/FederationService/getConfig.md
index e1e8eade..c82e7c63 100644
--- a/docs/core/FedimintWallet/FederationService/getConfig.md
+++ b/docs/core/FedimintWallet/FederationService/getConfig.md
@@ -4,6 +4,8 @@
 
 Access configuration details about a connected federation.
 
+> **WARNING**: This function will throw an error if the wallet is currently recovering.
+
 ```ts twoslash
 // @esModuleInterop
 import { WalletDirector } from '@fedimint/core'
diff --git a/docs/core/FedimintWallet/FederationService/getFederationId.md b/docs/core/FedimintWallet/FederationService/getFederationId.md
index b4164295..9c2f73d2 100644
--- a/docs/core/FedimintWallet/FederationService/getFederationId.md
+++ b/docs/core/FedimintWallet/FederationService/getFederationId.md
@@ -4,6 +4,8 @@
 
 Access the `federationId` of the connected Federation.
 
+> **WARNING**: This function will throw an error if the wallet is currently recovering.
+
 ```ts twoslash
 // @esModuleInterop
 import { WalletDirector } from '@fedimint/core'
diff --git a/docs/core/FedimintWallet/FederationService/getInviteCode.md b/docs/core/FedimintWallet/FederationService/getInviteCode.md
index c2952eef..bfa3cd99 100644
--- a/docs/core/FedimintWallet/FederationService/getInviteCode.md
+++ b/docs/core/FedimintWallet/FederationService/getInviteCode.md
@@ -4,6 +4,8 @@
 
 Access the invite code for the connected federation.
 
+> **WARNING**: This function will throw an error if the wallet is currently recovering.
+
 ```ts twoslash
 // @esModuleInterop
 import { WalletDirector } from '@fedimint/core'
diff --git a/docs/core/FedimintWallet/FederationService/getOperation.md b/docs/core/FedimintWallet/FederationService/getOperation.md
index 336fdf73..a8a9a5be 100644
--- a/docs/core/FedimintWallet/FederationService/getOperation.md
+++ b/docs/core/FedimintWallet/FederationService/getOperation.md
@@ -4,6 +4,8 @@
 
 Get the transaction data using the operation id.
 
+> **WARNING**: This function will throw an error if the wallet is currently recovering.
+
 ```ts twoslash
 // @esModuleInterop
 import { WalletDirector } from '@fedimint/core'
diff --git a/docs/core/FedimintWallet/FederationService/listOperations.md b/docs/core/FedimintWallet/FederationService/listOperations.md
index 5d5b643a..3fac6cea 100644
--- a/docs/core/FedimintWallet/FederationService/listOperations.md
+++ b/docs/core/FedimintWallet/FederationService/listOperations.md
@@ -4,6 +4,8 @@
 
 Returns a paginated list of operations (transactions) from the federation. In case limit and lastseen not given, returns all the available operations.
 
+> **WARNING**: This function will throw an error if the wallet is currently recovering.
+
 ```ts twoslash
 // @esModuleInterop
 import { WalletDirector } from '@fedimint/core'
diff --git a/docs/core/FedimintWallet/FederationService/listTransactions.md b/docs/core/FedimintWallet/FederationService/listTransactions.md
index 4dae4cf5..2473df43 100644
--- a/docs/core/FedimintWallet/FederationService/listTransactions.md
+++ b/docs/core/FedimintWallet/FederationService/listTransactions.md
@@ -4,6 +4,8 @@
 
 Returns a paginated list of transactions from the federation. In case limit and lastseen not given, returns all the available transactions.
 
+> **WARNING**: This function will throw an error if the wallet is currently recovering.
+
 ```ts twoslash
 /**
  * Represents wallet transaction record.
diff --git a/docs/core/FedimintWallet/LightningService/createInvoice.md b/docs/core/FedimintWallet/LightningService/createInvoice.md
index 51f47acd..65175881 100644
--- a/docs/core/FedimintWallet/LightningService/createInvoice.md
+++ b/docs/core/FedimintWallet/LightningService/createInvoice.md
@@ -8,6 +8,8 @@ You can use `subscribeLnReceive` to track the invoice status.
 
 `waitForReceive` returns a `Promise` that resolves when the invoice succeeds or `timeoutMs` is reached.
 
+> **WARNING**: This function will throw an error if the wallet is currently recovering.
+
 ```ts twoslash
 // @esModuleInterop
 import { WalletDirector } from '@fedimint/core'
diff --git a/docs/core/FedimintWallet/LightningService/payInvoice.md b/docs/core/FedimintWallet/LightningService/payInvoice.md
index 229db9f7..fee528db 100644
--- a/docs/core/FedimintWallet/LightningService/payInvoice.md
+++ b/docs/core/FedimintWallet/LightningService/payInvoice.md
@@ -4,6 +4,8 @@
 
 Attempts to pay an invoice. Returns a `Promise` that resolves when the payment succeeds or fails / times out.
 
+> **WARNING**: This function will throw an error if the wallet is currently recovering.
+
 ```ts twoslash
 // @esModuleInterop
 import { WalletDirector } from '@fedimint/core'
@@ -32,6 +34,8 @@ You can use `subscribeLnPay` and `subscribeInternalPay` to track the payment sta
 
 `subscribeInternalPay` can be used to track the internal payments status
 
+> **WARNING**: This function will throw an error if the wallet is currently recovering.
+
 ```ts twoslash
 // @esModuleInterop
 import { WalletDirector } from '@fedimint/core'
diff --git a/docs/core/FedimintWallet/MintService/getNotesByDenomination.md b/docs/core/FedimintWallet/MintService/getNotesByDenomination.md
index 3e652d6f..e6ab754a 100644
--- a/docs/core/FedimintWallet/MintService/getNotesByDenomination.md
+++ b/docs/core/FedimintWallet/MintService/getNotesByDenomination.md
@@ -4,6 +4,8 @@
 
 Gives count of ecash notes by denomination present in the wallet.
 
+> **WARNING**: This function will throw an error if the wallet is currently recovering.
+
 ```ts twoslash
 // @esModuleInterop
 import { WalletDirector } from '@fedimint/core'
diff --git a/docs/core/FedimintWallet/MintService/parseNotes.md b/docs/core/FedimintWallet/MintService/parseNotes.md
index 1c1f0246..857e5888 100644
--- a/docs/core/FedimintWallet/MintService/parseNotes.md
+++ b/docs/core/FedimintWallet/MintService/parseNotes.md
@@ -4,6 +4,8 @@
 
 Parses an ecash note string without redeeming it. Use [`redeemEcash()`](./redeemEcash) to redeem the notes.
 
+> **WARNING**: This function will throw an error if the wallet is currently recovering.
+
 ```ts twoslash
 // @esModuleInterop
 import { WalletDirector } from '@fedimint/core'
diff --git a/docs/core/FedimintWallet/MintService/redeemEcash.md b/docs/core/FedimintWallet/MintService/redeemEcash.md
index 17e85048..531154ca 100644
--- a/docs/core/FedimintWallet/MintService/redeemEcash.md
+++ b/docs/core/FedimintWallet/MintService/redeemEcash.md
@@ -4,6 +4,8 @@
 
 Redeem a set of ecash notes.
 
+> **WARNING**: This function will throw an error if the wallet is currently recovering.
+
 ```ts twoslash
 // @esModuleInterop
 import { WalletDirector } from '@fedimint/core'
diff --git a/docs/core/FedimintWallet/MintService/spendNotes.md b/docs/core/FedimintWallet/MintService/spendNotes.md
index 3a96e199..dbda49bb 100644
--- a/docs/core/FedimintWallet/MintService/spendNotes.md
+++ b/docs/core/FedimintWallet/MintService/spendNotes.md
@@ -4,6 +4,8 @@
 
 Generates ecash notes for spending.
 
+> **WARNING**: This function will throw an error if the wallet is currently recovering.
+
 ```ts twoslash
 // @esModuleInterop
 import { WalletDirector } from '@fedimint/core'
diff --git a/docs/core/FedimintWallet/RecoveryService/backupToFederation.md b/docs/core/FedimintWallet/RecoveryService/backupToFederation.md
index 7d1207f4..d5c3d4d2 100644
--- a/docs/core/FedimintWallet/RecoveryService/backupToFederation.md
+++ b/docs/core/FedimintWallet/RecoveryService/backupToFederation.md
@@ -4,6 +4,8 @@
 
 Backup the wallet state to the federation with optional metadata. You should call this function periodically to refresh the user's backups.
 
+> **WARNING**: This function will throw an error if the wallet is currently recovering.
+
 ```ts twoslash
 // @esModuleInterop
 import { WalletDirector } from '@fedimint/core'
diff --git a/docs/core/FedimintWallet/WalletService/generateAddress.md b/docs/core/FedimintWallet/WalletService/generateAddress.md
index 5c6bd835..a9d590c4 100644
--- a/docs/core/FedimintWallet/WalletService/generateAddress.md
+++ b/docs/core/FedimintWallet/WalletService/generateAddress.md
@@ -4,6 +4,8 @@
 
 Create an onchain address. Returns a `deposit_address` (string) and an `operation_id` (string).
 
+> **WARNING**: This function will throw an error if the wallet is currently recovering.
+
 ```ts twoslash
 // @esModuleInterop
 import { WalletDirector } from '@fedimint/core'
diff --git a/docs/core/FedimintWallet/WalletService/getWalletSummary.md b/docs/core/FedimintWallet/WalletService/getWalletSummary.md
index 4f68a563..044b161d 100644
--- a/docs/core/FedimintWallet/WalletService/getWalletSummary.md
+++ b/docs/core/FedimintWallet/WalletService/getWalletSummary.md
@@ -4,6 +4,8 @@
 
 Gives wallet UTXO set
 
+> **WARNING**: This function will throw an error if the wallet is currently recovering.
+
 ```ts twoslash
 // @esModuleInterop
 import { WalletDirector } from '@fedimint/core'
diff --git a/docs/core/FedimintWallet/WalletService/sendOnchain.md b/docs/core/FedimintWallet/WalletService/sendOnchain.md
index b72f171e..1c6dd7e6 100644
--- a/docs/core/FedimintWallet/WalletService/sendOnchain.md
+++ b/docs/core/FedimintWallet/WalletService/sendOnchain.md
@@ -4,6 +4,8 @@
 
 Attempts to send bitcoin to an onchain address.
 
+> **WARNING**: This function will throw an error if the wallet is currently recovering.
+
 ```ts twoslash
 // @esModuleInterop
 import { WalletDirector } from '@fedimint/core'

From 762b84977f308f0f1ede5d01ba69bc15eb8e53b2 Mon Sep 17 00:00:00 2001
From: Om Swami <reach.oms2004@gmail.com>
Date: Sun, 14 Dec 2025 21:32:54 +0530
Subject: [PATCH 09/14] chore: fix prettier formatting in backupToFederation

---
 .../core/FedimintWallet/RecoveryService/backupToFederation.md | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)

diff --git a/docs/core/FedimintWallet/RecoveryService/backupToFederation.md b/docs/core/FedimintWallet/RecoveryService/backupToFederation.md
index d5c3d4d2..e5fb7473 100644
--- a/docs/core/FedimintWallet/RecoveryService/backupToFederation.md
+++ b/docs/core/FedimintWallet/RecoveryService/backupToFederation.md
@@ -26,8 +26,8 @@ try {
 
 // Backup with metadata
 try {
-  await wallet.recovery.backupToFederation({
-    // [!code focus]
+  // prettier-ignore
+  await wallet.recovery.backupToFederation({ // [!code focus] 
     timestamp: Date.now(), // [!code focus]
     note: 'My backup', // [!code focus]
   }) // [!code focus]

From f401ac48d6af4dbac49e85bd1a5311952f58a5e9 Mon Sep 17 00:00:00 2001
From: Om Swami <reach.oms2004@gmail.com>
Date: Sun, 14 Dec 2025 21:35:47 +0530
Subject: [PATCH 10/14] chore: ignore prettier formatting in docs

---
 .prettierignore                                          | 2 ++
 .../FedimintWallet/RecoveryService/backupToFederation.md | 1 -
 .../RecoveryService/subscribeToRecoveryProgress.md       | 9 +++------
 3 files changed, 5 insertions(+), 7 deletions(-)

diff --git a/.prettierignore b/.prettierignore
index 1d207ae5..9617d39d 100644
--- a/.prettierignore
+++ b/.prettierignore
@@ -10,4 +10,6 @@ packages/*/dist/**
 docs/core/FedimintWallet/BalanceService/subscribeBalance.md
 docs/core/FedimintWallet/LightningService/createInvoice.md
 docs/core/FedimintWallet/LightningService/payInvoice.md
+docs/core/FedimintWallet/RecoveryService/subscribeToRecoveryProgress.md
+docs/core/FedimintWallet/RecoveryService/backupToFederation.md
 flake.lock
diff --git a/docs/core/FedimintWallet/RecoveryService/backupToFederation.md b/docs/core/FedimintWallet/RecoveryService/backupToFederation.md
index e5fb7473..08a5be3a 100644
--- a/docs/core/FedimintWallet/RecoveryService/backupToFederation.md
+++ b/docs/core/FedimintWallet/RecoveryService/backupToFederation.md
@@ -26,7 +26,6 @@ try {
 
 // Backup with metadata
 try {
-  // prettier-ignore
   await wallet.recovery.backupToFederation({ // [!code focus] 
     timestamp: Date.now(), // [!code focus]
     note: 'My backup', // [!code focus]
diff --git a/docs/core/FedimintWallet/RecoveryService/subscribeToRecoveryProgress.md b/docs/core/FedimintWallet/RecoveryService/subscribeToRecoveryProgress.md
index 654f40e8..accc566e 100644
--- a/docs/core/FedimintWallet/RecoveryService/subscribeToRecoveryProgress.md
+++ b/docs/core/FedimintWallet/RecoveryService/subscribeToRecoveryProgress.md
@@ -14,15 +14,12 @@ const wallet = await director.createWallet()
 
 await wallet.open()
 
-const unsubscribe = wallet.recovery.subscribeToRecoveryProgress(
-  // [!code focus]
-  (progress) => {
-    // [!code focus]
+const unsubscribe = wallet.recovery.subscribeToRecoveryProgress( // [!code focus]
+  (progress) => { // [!code focus]
     console.log('Module:', progress.module_id) // [!code focus]
     console.log('Progress:', progress.progress) // [!code focus]
   }, // [!code focus]
-  (error) => {
-    // [!code focus]
+  (error) => { // [!code focus]
     console.error('Recovery error:', error) // [!code focus]
   }, // [!code focus]
 ) // [!code focus]

From dd4b38e2a138dec521441b062b2e09ae23f773f4 Mon Sep 17 00:00:00 2001
From: Om Swami <reach.oms2004@gmail.com>
Date: Sun, 14 Dec 2025 21:40:10 +0530
Subject: [PATCH 11/14] chore: fix code focus in getNotesByDenomination

---
 docs/core/FedimintWallet/MintService/getNotesByDenomination.md | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/docs/core/FedimintWallet/MintService/getNotesByDenomination.md b/docs/core/FedimintWallet/MintService/getNotesByDenomination.md
index e6ab754a..8267c5e8 100644
--- a/docs/core/FedimintWallet/MintService/getNotesByDenomination.md
+++ b/docs/core/FedimintWallet/MintService/getNotesByDenomination.md
@@ -16,6 +16,6 @@ const wallet = await director.createWallet()
 
 await wallet.open()
 
-const notes = await wallet.mint.getNotesByDenomination()
+const notes = await wallet.mint.getNotesByDenomination() // [!code focus]
 console.log('Notes are: ', notes) // {1: 2, 2: 1, 8: 2}
 ```

From d207572cd8fa380a0248b156df2b63fd1c38200f Mon Sep 17 00:00:00 2001
From: Om Swami <reach.oms2004@gmail.com>
Date: Sun, 14 Dec 2025 21:42:40 +0530
Subject: [PATCH 12/14] chore: fix prettier formatting in sendOnChain

---
 .prettierignore                                       | 1 +
 docs/core/FedimintWallet/WalletService/sendOnchain.md | 2 +-
 2 files changed, 2 insertions(+), 1 deletion(-)

diff --git a/.prettierignore b/.prettierignore
index 9617d39d..4d412903 100644
--- a/.prettierignore
+++ b/.prettierignore
@@ -12,4 +12,5 @@ docs/core/FedimintWallet/LightningService/createInvoice.md
 docs/core/FedimintWallet/LightningService/payInvoice.md
 docs/core/FedimintWallet/RecoveryService/subscribeToRecoveryProgress.md
 docs/core/FedimintWallet/RecoveryService/backupToFederation.md
+docs/core/FedimintWallet/WalletService/sendOnchain.md
 flake.lock
diff --git a/docs/core/FedimintWallet/WalletService/sendOnchain.md b/docs/core/FedimintWallet/WalletService/sendOnchain.md
index 1c6dd7e6..69049c27 100644
--- a/docs/core/FedimintWallet/WalletService/sendOnchain.md
+++ b/docs/core/FedimintWallet/WalletService/sendOnchain.md
@@ -19,7 +19,7 @@ await wallet.open()
 const amount = 20 // amount in Sats // [!code focus]
 const address = 'bc1q...' // [!code focus]
 
-const { operation_id } = await wallet.wallet.sendOnchain(
+const { operation_id } = await wallet.wallet.sendOnchain( // [!code focus]
   amount, // [!code focus]
   address, // [!code focus]
 ) // [!code focus]

From a15e816927e2e322984c15e367841fba02b51872 Mon Sep 17 00:00:00 2001
From: Om Swami <reach.oms2004@gmail.com>
Date: Sun, 14 Dec 2025 22:00:10 +0530
Subject: [PATCH 13/14] chore: add code focus to getOperation

---
 docs/core/FedimintWallet/FederationService/getOperation.md | 6 +++---
 1 file changed, 3 insertions(+), 3 deletions(-)

diff --git a/docs/core/FedimintWallet/FederationService/getOperation.md b/docs/core/FedimintWallet/FederationService/getOperation.md
index a8a9a5be..9230249a 100644
--- a/docs/core/FedimintWallet/FederationService/getOperation.md
+++ b/docs/core/FedimintWallet/FederationService/getOperation.md
@@ -16,7 +16,7 @@ const wallet = await director.createWallet()
 
 await wallet.open()
 
-const operationId =
-  '3ff56b29cf014b9ff6c8b6b4aa78e02d3c429de7112bfaf42a876f6a797ddf8b'
-const config = await wallet.federation.getOperation(operationId)
+const operationId = // [!code focus]
+  '3ff56b29cf014b9ff6c8b6b4aa78e02d3c429de7112bfaf42a876f6a797ddf8b' // [!code focus]
+const config = await wallet.federation.getOperation(operationId) // [!code focus]
 ```

From d21e0eeaf85e85150e81cdcb17451fb6da8ef607 Mon Sep 17 00:00:00 2001
From: Om Swami <reach.oms2004@gmail.com>
Date: Sun, 14 Dec 2025 22:05:29 +0530
Subject: [PATCH 14/14] chore: add code focus to listOperation

---
 .prettierignore                                      |  1 +
 .../FederationService/listOperations.md              | 12 ++++++------
 2 files changed, 7 insertions(+), 6 deletions(-)

diff --git a/.prettierignore b/.prettierignore
index 4d412903..167e4b8f 100644
--- a/.prettierignore
+++ b/.prettierignore
@@ -13,4 +13,5 @@ docs/core/FedimintWallet/LightningService/payInvoice.md
 docs/core/FedimintWallet/RecoveryService/subscribeToRecoveryProgress.md
 docs/core/FedimintWallet/RecoveryService/backupToFederation.md
 docs/core/FedimintWallet/WalletService/sendOnchain.md
+docs/core/FedimintWallet/FederationService/listOperations.md
 flake.lock
diff --git a/docs/core/FedimintWallet/FederationService/listOperations.md b/docs/core/FedimintWallet/FederationService/listOperations.md
index 3fac6cea..0b1e295c 100644
--- a/docs/core/FedimintWallet/FederationService/listOperations.md
+++ b/docs/core/FedimintWallet/FederationService/listOperations.md
@@ -17,10 +17,10 @@ const wallet = await director.createWallet()
 await wallet.open()
 
 const limit = 10
-const lastseen = {
-  creation_time: { secs_since_epoch: 2323233, nanos_since_epoch: 93429234 },
-  operation_id:
-    '3ff56b29cf014b9ff6c8b6b4aa78e02d3c429de7112bfaf42a876f6a797ddf8b',
-}
-const operations = await wallet.federation.listOperations(limit, lastseen)
+const lastseen = { // [!code focus]
+  creation_time: { secs_since_epoch: 2323233, nanos_since_epoch: 93429234 }, // [!code focus]
+  operation_id: // [!code focus]
+    '3ff56b29cf014b9ff6c8b6b4aa78e02d3c429de7112bfaf42a876f6a797ddf8b', // [!code focus]
+} // [!code focus]
+const operations = await wallet.federation.listOperations(limit, lastseen) // [!code focus]
 ```