Merge pull request #161 from ChainSafe/fix/update-fix-NU6

fix: better error logging and prevent transactions over total balance

Author: irubido

PCZT_ERROR_TEST_PLAN.md

@@ -0,0 +1,149 @@
+# PCZT Creation Error - Reproduction Test Plan
+
+## Changes Made
+✅ **Error Handling Improvements Applied**
+- `error.rs`: Changed `PcztCreate` to include error details: `PcztCreate(String)`
+- `wallet.rs:569`: Updated `pczt_shield` to log and capture error details
+- `wallet.rs:657-660`: Updated `pczt_create` to log and capture error details
+- **Build Status**: ✅ Compiled successfully
+
+## Error Will Now Show Details
+Previously: `"Failed to create PCZT"` (no details)
+Now: `"Failed to create PCZT: <actual error from librustzcash>"` (includes root cause)
+
+## Testing Scenarios
+
+### Scenario 1: Transaction with Memo (PRIORITY - Never Tested)
+
+**Setup:**
+1. Open http://localhost:3000
+2. Connect MetaMask snap
+3. Ensure wallet is fully synced
+4. Attempt to send ZEC with a memo
+
+**Steps:**
+```
+To: <any_valid_zcash_address>
+Amount: 0.001 ZEC
+Memo: "Test memo for NU6.1"
+```
+
+**Expected Behaviors:**
+- ✅ **Success**: Transaction creates PCZT successfully
+- ❌ **Failure**: Console shows detailed error message
+
+**Check Console For:**
+- `pczt_create: create_pczt_from_proposal failed: <details>`
+- Look for: memo-related errors, encoding issues, or validation failures
+
+### Scenario 2: Shielding Operation
+
+**Setup:**
+1. Ensure wallet has transparent balance
+2. Attempt to shield funds to Sapling/Orchard
+
+**Steps:**
+```
+Shield Amount: <available_transparent_balance>
+Target Pool: Orchard
+```
+
+**Check Console For:**
+- `pczt_shield: create_pczt_from_proposal failed: <details>`
+- Look for: anchor mismatch, tree state issues
+
+### Scenario 3: Multiple Small Transactions (Note Fragmentation)
+
+**Hypothesis:** Wallet with many small notes might trigger input selection issues
+
+**Setup:**
+1. Create multiple small notes by receiving several small transactions
+2. Attempt to spend more than any single note
+3. Forces wallet to combine notes
+
+**Check For:**
+- Input selection failures
+- "insufficient balance" despite having enough total
+
+### Scenario 4: Transaction After Partial Sync
+
+**Hypothesis:** Wallet not fully synced might have stale anchor
+
+**Setup:**
+1. Stop sync before completion (close browser mid-sync)
+2. Reload and attempt transaction without re-syncing
+3. See if pre-sync validation catches it or if PCZT creation fails
+
+**Check For:**
+- "Wallet not fully synced" warning triggers auto-sync (line 598-605)
+- OR anchor mismatch in PCZT creation
+
+### Scenario 5: Pre-NU6.1 Notes (If Available)
+
+**Hypothesis:** Notes received before block 3,146,400 might have compatibility issues
+
+**Check:**
+- Look at transaction history for any notes from before Jan 2026
+- Try to spend these specific notes
+- Check if serialization format causes issues
+
+## What to Look For in Console
+
+With our improved error handling, you should now see:
+
+```javascript
+// Console output will show:
+ERROR pczt_create: create_pczt_from_proposal failed: <ACTUAL ERROR>
+
+// Examples of what might appear:
+// - "anchor not found in commitment tree"
+// - "insufficient balance after selecting inputs"
+// - "note value exceeds maximum"
+// - "invalid memo encoding"
+// - "transaction would create negative balance"
+```
+
+## Debugging Steps
+
+1. **Open Browser Console** (F12) before any transaction attempt
+2. **Enable verbose logging** if available
+3. **Copy full error message** including the new detailed part
+4. **Note wallet state**:
+   - Current block height
+   - Number of notes
+   - Total balance
+   - Last sync time
+
+## Expected Results
+
+If the forum user's error is reproducible:
+- You'll see the SAME detailed error message
+- Can then determine if it's:
+  - ✅ A memo-specific issue
+  - ✅ A tree/anchor sync issue
+  - ✅ A NU6.1 compatibility issue
+  - ✅ An input selection bug
+
+If NO error occurs:
+- The issue might be environment-specific
+- Or related to a specific wallet state we haven't replicated
+- Request more details from the forum user about their setup
+
+## Next Steps After Testing
+
+1. **If error reproduced**: Analyze the detailed error message to identify fix
+2. **If error NOT reproduced**: Deploy this improved error logging to production so users can report detailed errors
+3. **Check forum**: Ask user to update snap and provide new detailed error message
+
+## Quick Commands
+
+```bash
+# Start dev servers
+cd /home/skynet/ztest/WebZjs && yarn dev
+
+# Check build status
+cd /home/skynet/ztest/WebZjs && just build
+
+# View console logs in browser
+# F12 → Console tab → Look for "pczt_create" or "pczt_shield" errors
+```

crates/webzjs-wallet/src/error.rs

@@ -80,8 +80,8 @@ pub enum Error {
     SerdeWasmBindgen(#[from] serde_wasm_bindgen::Error),
     #[error("Fail to parse TxIds")]
     TxIdParse,
-    #[error("Failed to create Pczt")]
-    PcztCreate,
+    #[error("Failed to create Pczt: {0}")]
+    PcztCreate(String),
     #[error("Failed to prove Pczt: {0}")]
     PcztProve(String),
     #[error("Failed to send Pczt: {0}")]

crates/webzjs-wallet/src/wallet.rs

@@ -566,7 +566,7 @@ where
         )
         .map_err(|e| {
             tracing::error!("pczt_shield: create_pczt_from_proposal failed: {:?}", e);
-            Error::PcztCreate
+            Error::PcztCreate(format!("{:?}", e))
         })?;
         tracing::info!("pczt_shield: PCZT created from proposal successfully");
 
@@ -654,7 +654,10 @@ where
             OvkPolicy::Sender,
             &proposal,
         )
-        .map_err(|_| Error::PcztCreate)?;
+        .map_err(|e| {
+            tracing::error!("pczt_create: create_pczt_from_proposal failed: {:?}", e);
+            Error::PcztCreate(format!("{:?}", e))
+        })?;
         Ok(pczt)
     }
 

packages/snap/snap.manifest.json

@@ -7,7 +7,7 @@
     "url": "https://github.com/ChainSafe/WebZjs.git"
   },
   "source": {
-    "shasum": "WOy/9JeJPJ346afb8ZQnvY0N6fX58ci737rwSSfjtLs=",
+    "shasum": "qzUODaU2KfdU1JVKRMUDL+wReKvUPUX4sx5Jx58D76k=",
     "location": {
       "npm": {
         "filePath": "dist/bundle.js",

packages/web-wallet/src/components/TransferCards/TransferInput.tsx

@@ -5,6 +5,8 @@ import {
 } from '../../pages/TransferBalance/useTransferBalanceForm';
 import Input from '../Input/Input';
 import Button from '../Button/Button';
+import useBalance from '../../hooks/useBalance';
+import { zecToZats, zatsToZec } from '../../utils/balance';
 
 interface TransferInputProps {
   formData: TransferBalanceFormData;
@@ -17,6 +19,7 @@ export function TransferInput({
   nextStep,
   handleChange,
 }: TransferInputProps): React.JSX.Element {
+  const { spendableBalance } = useBalance();
 
   const [errors, setErrors] = useState({
     recipient: '',
@@ -35,8 +38,28 @@ export function TransferInput({
       newErrors.recipient = 'Please enter a valid address';
     }
 
-    if (!amount || isNaN(Number(amount)) || Number(amount) <= 0) {
-      newErrors.amount = 'Please enter an valid amount to transfer';
+    // Amount validation
+    if (!amount) {
+      newErrors.amount = 'Amount is required';
+    } else if (isNaN(Number(amount))) {
+      newErrors.amount = 'Please enter a valid number';
+    } else if (Number(amount) <= 0) {
+      newErrors.amount = 'Amount must be greater than 0';
+    } else {
+      // Balance validation with fee buffer
+      try {
+        const amountInZats = zecToZats(amount);
+        const FEE_BUFFER = 10_000; // Conservative estimate: 0.0001 ZEC buffer for fees
+        const totalRequired = Number(amountInZats) + FEE_BUFFER;
+
+        if (totalRequired > spendableBalance) {
+          const availableZec = zatsToZec(Math.max(0, spendableBalance - FEE_BUFFER));
+          newErrors.amount = `Insufficient balance. Available (after fees): ${availableZec.toFixed(8)} ZEC`;
+        }
+      } catch (error) {
+        // If conversion fails, let it pass - the error will be caught later
+        // This handles edge cases like invalid decimal formats
+      }
     }
 
     setErrors(newErrors);

packages/web-wallet/src/hooks/usePCZT.ts

@@ -179,11 +179,40 @@ export const usePczt = (): IUsePczt => {
       await syncStateWithWallet();
     } catch (error) {
       const rawMessage = error instanceof Error ? error.message : String(error);
-      console.error('Transaction error:', rawMessage);
+
+      // Log full error details for debugging
+      console.error('=== Transaction Error Details ===');
+      console.error('Raw error:', error);
+      console.error('Error message:', rawMessage);
+      console.error('Error type:', error instanceof Error ? error.constructor.name : typeof error);
+      if (error instanceof Error && error.stack) {
+        console.error('Stack trace:', error.stack);
+      }
+      console.error('================================');
 
       let errorMessage = rawMessage;
+
+      // Parse InsufficientFunds error to extract amounts
       if (rawMessage.includes('InsufficientFunds')) {
-        errorMessage = 'Insufficient balance. Your wallet may still be syncing — please wait for sync to complete or try a Full Resync from the Account Summary page.';
+        const availableMatch = rawMessage.match(/available:\s*Zatoshis\((\d+)\)/);
+        const requiredMatch = rawMessage.match(/required:\s*Zatoshis\((\d+)\)/);
+
+        if (availableMatch && requiredMatch) {
+          const available = parseInt(availableMatch[1]);
+          const required = parseInt(requiredMatch[1]);
+          const availableZec = (available / 100_000_000).toFixed(8);
+          const requiredZec = (required / 100_000_000).toFixed(8);
+          const shortfallZec = ((required - available) / 100_000_000).toFixed(8);
+
+          console.error('Insufficient Funds Breakdown:');
+          console.error(`  Available: ${available} zatoshis (${availableZec} ZEC)`);
+          console.error(`  Required:  ${required} zatoshis (${requiredZec} ZEC)`);
+          console.error(`  Shortfall: ${required - available} zatoshis (${shortfallZec} ZEC)`);
+
+          errorMessage = `Insufficient balance. Available: ${availableZec} ZEC, Required: ${requiredZec} ZEC (includes fees). You need ${shortfallZec} ZEC more to complete this transaction.`;
+        } else {
+          errorMessage = 'Insufficient balance. Your wallet may still be syncing — please wait for sync to complete or try a Full Resync from the Account Summary page.';
+        }
       }
 
       setLastError(errorMessage);

packages/web-wallet/src/pages/ShieldBalance/ShieldBalance.tsx

@@ -46,7 +46,11 @@ export function ShieldBalance(): React.JSX.Element {
   }
 
   const isMinimalShieldAmount = useMemo(()=>{
-    return unshieldedBalance > 100000;
+    // Need at least 0.001 ZEC + fee buffer (0.0015 ZEC total minimum)
+    // This accounts for the transaction fee which is deducted from the balance
+    const MINIMUM_SHIELD_AMOUNT = 100000; // 0.001 ZEC
+    const FEE_BUFFER = 50000; // 0.0005 ZEC conservative fee estimate
+    return unshieldedBalance > (MINIMUM_SHIELD_AMOUNT + FEE_BUFFER);
   },[unshieldedBalance])
 
   return (
@@ -100,7 +104,7 @@ export function ShieldBalance(): React.JSX.Element {
                 />
                 {!isMinimalShieldAmount && (
                   <div className="text-red-500 text-sm mt-2">
-                    The minimum shielding balance required is 0.001 ZEC.
+                    Minimum balance required: 0.0015 ZEC (includes transaction fees). Your balance: {zatsToZec(unshieldedBalance)} ZEC
                   </div>
                 )}
               </div>