proxmox/docs/archive/historical/BLOCKSCOUT_METAMASK_QUICK_REFERENCE.md

Blockscout MetaMask Fix - Quick Reference

✅ Status: FIXED & DEPLOYED

Date: $(date)
VMID: 5000
Frontend Location: /var/www/html/index.html
Status: ✅ Live

---

🚀 Quick Commands

Deploy Fixed Frontend

cd /home/intlc/projects/proxmox
./scripts/deploy-blockscout-frontend.sh

Verify Deployment

ssh root@192.168.11.140 "grep -q 'unpkg.com' /var/www/html/index.html && echo '✅ Fallback CDN present' || echo '❌ Not found'"

Check Nginx Status

ssh root@192.168.11.140 "systemctl status nginx"

View Logs

ssh root@192.168.11.140 "tail -f /var/log/nginx/blockscout-access.log"

---

🔧 What Was Fixed

1. Ethers Library Loading

   • Primary CDN: https://cdn.ethers.io/lib/ethers-5.7.2.umd.min.js
   • Fallback CDN: https://unpkg.com/ethers@5.7.2/dist/ethers.umd.min.js
   • Automatic fallback detection

2. Error Handling

   • Added ensureEthers() helper function
   • Checks before all ethers usage
   • Clear error messages

3. Functions Protected

   • connectMetaMask()
   • refreshWETHBalances()
   • wrapWETH9() / unwrapWETH9()
   • wrapWETH10() / unwrapWETH10()

---

🧪 Testing

Test in Browser

1. Open: https://explorer.d-bis.org
2. Open Developer Console (F12)
3. Check for "Ethers loaded successfully" message
4. Click "Connect MetaMask"
5. Should connect without "ethers is not defined" error

Test Fallback CDN

1. Block primary CDN in browser (Network tab → Block request URL)
2. Refresh page
3. Should automatically load from unpkg.com
4. MetaMask should still work

---

📋 Next Steps (Recommended)

High Priority

1. Add Local Fallback

   ssh root@192.168.11.140
   cd /var/www/html
   mkdir -p js
   wget https://unpkg.com/ethers@5.7.2/dist/ethers.umd.min.js -O js/ethers.umd.min.js
   # Then update index.html to use /js/ethers.umd.min.js as final fallback
   

2. Add Connection State Persistence

   • Save connection state to localStorage
   • Restore on page load

3. Improve Error Messages

   • User-friendly error messages
   • Toast notifications

Medium Priority

4. Add network detection
5. Add SRI (Subresource Integrity) checks
6. Add CSP (Content Security Policy) headers
7. Add connection retry logic

Low Priority

8. Add service worker for offline support
9. Add comprehensive testing
10. Add analytics/monitoring

---

🐛 Troubleshooting

Issue: Still getting "ethers is not defined"

Solution:

1. Clear browser cache (Ctrl+Shift+R)
2. Check browser console for errors
3. Verify both CDNs are accessible
4. Check if browser extensions are blocking

Issue: Frontend not updating

Solution:

1. Verify file was deployed: ssh root@192.168.11.140 "head -20 /var/www/html/index.html | grep unpkg"
2. Clear nginx cache: ssh root@192.168.11.140 "systemctl reload nginx"
3. Clear browser cache

Issue: Deployment fails

Solution:

1. Check SSH access: ssh root@192.168.11.140 "echo 'OK'"
2. Check file exists: ls -la explorer-monorepo/frontend/public/index.html
3. Check permissions: chmod +x scripts/deploy-blockscout-frontend.sh

---

📚 Documentation

• Complete Recommendations: docs/BLOCKSCOUT_METAMASK_COMPLETE_RECOMMENDATIONS.md
• Fix Details: docs/BLOCKSCOUT_METAMASK_ETHERS_FIX.md
• Deployment Script: scripts/deploy-blockscout-frontend.sh

---

✅ Verification Checklist

• Ethers library loads from primary CDN
• Fallback CDN works
• MetaMask connection works
• Error messages are clear
• Local fallback available (recommended)
• Connection state persists (recommended)
• Network switching works (recommended)

---

Last Updated: $(date)
Status: ✅ Production Ready