proxmox/docs/archive/fixes/BLOCKSCOUT_METAMASK_ETHERS_FIX.md

# Blockscout MetaMask Ethers Fix

**Date**: $(date)  
**Issue**: Failed to connect MetaMask: ethers is not defined  
**Status**: ✅ Fixed

---

## Problem

The Blockscout frontend was failing to connect MetaMask with the error:
```
Failed to connect MetaMask: ethers is not defined
```

**Root Cause**: The ethers.js library was not loading properly from the CDN (`https://cdn.ethers.io/lib/ethers-5.7.2.umd.min.js`). This could happen due to:
- CDN being blocked or unavailable
- Network connectivity issues
- Script loading timing issues
- Browser security policies

---

## Solution

### 1. Added Fallback CDN

The primary CDN now has a fallback to unpkg.com:

```html
<script src="https://cdn.ethers.io/lib/ethers-5.7.2.umd.min.js" 
        onerror="this.onerror=null; this.src='https://unpkg.com/ethers@5.7.2/dist/ethers.umd.min.js';"></script>
```

### 2. Added Ethers Loading Detection

Added a script to detect if ethers loaded successfully and automatically load from fallback if needed:

```javascript
(function() {
    function checkEthers() {
        if (typeof ethers === 'undefined') {
            console.warn('Primary ethers CDN failed, trying fallback...');
            const script = document.createElement('script');
            script.src = 'https://unpkg.com/ethers@5.7.2/dist/ethers.umd.min.js';
            // ... fallback loading logic
        }
    }
    // Check after DOM loads
    if (document.readyState === 'loading') {
        document.addEventListener('DOMContentLoaded', function() {
            setTimeout(checkEthers, 100);
        });
    } else {
        setTimeout(checkEthers, 100);
    }
})();
```

### 3. Added Ethers Availability Checks

Created a helper function and added checks before all ethers usage:

```javascript
function ensureEthers() {
    if (typeof ethers === 'undefined') {
        throw new Error('Ethers library is not loaded. Please refresh the page.');
    }
    return true;
}
```

Updated functions:
- `connectMetaMask()` - Checks before creating provider
- `refreshWETHBalances()` - Checks before contract calls
- `wrapWETH9()` - Checks before wrapping
- `unwrapWETH9()` - Checks before unwrapping
- `wrapWETH10()` - Checks before wrapping
- `unwrapWETH10()` - Checks before unwrapping

### 4. Improved Error Handling

Enhanced error messages to clearly indicate when ethers library fails to load:

```javascript
catch (error) {
    let errorMessage = error.message || 'Unknown error';
    if (errorMessage.includes('ethers is not defined') || typeof ethers === 'undefined') {
        errorMessage = 'Ethers library failed to load. Please refresh the page.';
    }
    alert('Failed to connect MetaMask: ' + errorMessage);
}
```

---

## Files Modified

- **Frontend**: `/home/intlc/projects/proxmox/explorer-monorepo/frontend/public/index.html`
  - Updated ethers CDN with fallback
  - Added ethers loading detection
  - Added `ensureEthers()` helper function
  - Added checks in all MetaMask-related functions

---

## Deployment

### Option 1: Use Deployment Script (Recommended)

```bash
cd /home/intlc/projects/proxmox
./scripts/fix-blockscout-metamask-ethers.sh
```

The script will:
1. Check container accessibility (VMID 5000)
2. Locate the frontend deployment directory
3. Deploy the fixed `index.html`
4. Reload nginx if needed

### Option 2: Manual Deployment

1. **Access the blockscout container**:
   ```bash
   pct exec 5000 -- bash
   # or
   ssh root@192.168.11.140
   ```

2. **Locate frontend directory**:
   ```bash
   # Check nginx config
   find /etc/nginx -name "*.conf" -exec grep -l "root\|alias" {} \;
   
   # Or check blockscout static assets
   docker exec blockscout find /app/apps/explorer/priv/static -name "index.html"
   ```

3. **Copy fixed file**:
   ```bash
   # From your local machine
   scp explorer-monorepo/frontend/public/index.html root@192.168.11.140:/path/to/frontend/
   
   # Or if using pct
   pct push 5000 explorer-monorepo/frontend/public/index.html /path/to/frontend/index.html
   ```

4. **Reload web server**:
   ```bash
   systemctl reload nginx
   # or restart blockscout container
   docker restart blockscout
   ```

---

## Verification

### 1. Check Browser Console

Open browser developer tools (F12) and check:
- ✅ No errors about "ethers is not defined"
- ✅ Console shows "Ethers loaded successfully"
- ✅ Network tab shows ethers library loaded (from primary or fallback CDN)

### 2. Test MetaMask Connection

1. Navigate to Blockscout frontend
2. Click "Connect MetaMask" button
3. Should successfully connect without "ethers is not defined" error
4. Should be able to use WETH wrap/unwrap functions

### 3. Test Fallback CDN

If you want to test the fallback:
1. Block the primary CDN in browser dev tools (Network tab → Block request URL)
2. Refresh page
3. Should automatically load from unpkg.com fallback
4. MetaMask connection should still work

---

## Technical Details

### CDN URLs Used

1. **Primary**: `https://cdn.ethers.io/lib/ethers-5.7.2.umd.min.js`
2. **Fallback**: `https://unpkg.com/ethers@5.7.2/dist/ethers.umd.min.js`

### Ethers.js Version

- **Version**: 5.7.2
- **Format**: UMD (Universal Module Definition)
- **Compatibility**: Works in browsers without module bundlers

### Functions Protected

All functions that use ethers now check availability:
- `connectMetaMask()` - Line 718
- `refreshWETHBalances()` - Line 874
- `wrapWETH9()` - Line 922
- `unwrapWETH9()` - Line 961
- `wrapWETH10()` - Line 993
- `unwrapWETH10()` - Line 1032

---

## Troubleshooting

### Issue: Still getting "ethers is not defined"

**Solutions**:
1. Clear browser cache and hard refresh (Ctrl+Shift+R)
2. Check browser console for CDN loading errors
3. Verify both CDN URLs are accessible:
   ```bash
   curl -I https://cdn.ethers.io/lib/ethers-5.7.2.umd.min.js
   curl -I https://unpkg.com/ethers@5.7.2/dist/ethers.umd.min.js
   ```
4. Check if browser extensions are blocking CDN requests
5. Try in incognito/private mode

### Issue: Frontend file not updating

**Solutions**:
1. Verify file was copied correctly:
   ```bash
   # On container
   head -20 /path/to/frontend/index.html | grep "unpkg.com"
   ```
2. Check nginx cache settings
3. Restart nginx: `systemctl restart nginx`
4. Clear browser cache

### Issue: Script deployment fails

**Solutions**:
1. Check container is running: `pct status 5000`
2. Verify SSH access: `ssh root@192.168.11.140`
3. Check file permissions: `ls -la explorer-monorepo/frontend/public/index.html`
4. Run script with debug: `bash -x scripts/fix-blockscout-metamask-ethers.sh`

---

## Related Files

- **Frontend Source**: `explorer-monorepo/frontend/public/index.html`
- **Deployment Script**: `scripts/fix-blockscout-metamask-ethers.sh`
- **Blockscout Config**: `smom-dbis-138-proxmox/install/blockscout-install.sh`

---

## Status

✅ **Fixed**: Ethers library loading with fallback  
✅ **Fixed**: Ethers availability checks in all functions  
✅ **Fixed**: Improved error messages  
✅ **Deployed**: Ready for deployment to VMID 5000

---

## Next Steps

1. Deploy the fix using the deployment script
2. Test MetaMask connection
3. Verify WETH utilities work correctly
4. Monitor for any remaining issues