Initial commit: Complete MetaMask integration for ChainID 138
This commit is contained in:
defiQUG
414
docs/METAMASK_TROUBLESHOOTING_GUIDE.md
Normal file
414
docs/METAMASK_TROUBLESHOOTING_GUIDE.md
Normal file
@@ -0,0 +1,414 @@
|
||||
# MetaMask Troubleshooting Guide - ChainID 138
|
||||
|
||||
**Date**: $(date)
|
||||
**Network**: SMOM-DBIS-138 (ChainID 138)
|
||||
|
||||
---
|
||||
|
||||
## 🔍 Common Issues & Solutions
|
||||
|
||||
### 1. Network Connection Issues
|
||||
|
||||
#### Issue: "Network Error" or "Failed to Connect"
|
||||
|
||||
**Symptoms**:
|
||||
- MetaMask shows "Network Error"
|
||||
- Can't fetch balance
|
||||
- Transactions fail immediately
|
||||
|
||||
**Solutions**:
|
||||
|
||||
1. **Verify RPC URL**
|
||||
```
|
||||
Correct: https://rpc-core.d-bis.org
|
||||
Incorrect: http://rpc-core.d-bis.org (missing 's')
|
||||
```
|
||||
|
||||
2. **Check Chain ID**
|
||||
- Must be exactly `138` (decimal)
|
||||
- Not `0x8a` (that's hex, but MetaMask expects decimal in manual entry)
|
||||
- Verify in network settings
|
||||
|
||||
3. **Remove and Re-add Network**
|
||||
- Settings → Networks → Remove "SMOM-DBIS-138"
|
||||
- Add network again with correct settings
|
||||
- See [Quick Start Guide](./METAMASK_QUICK_START_GUIDE.md)
|
||||
|
||||
4. **Clear MetaMask Cache**
|
||||
- Settings → Advanced → Reset Account (if needed)
|
||||
- Or clear browser cache and reload MetaMask
|
||||
|
||||
5. **Check RPC Endpoint Status**
|
||||
```bash
|
||||
curl -X POST https://rpc-core.d-bis.org \
|
||||
-H "Content-Type: application/json" \
|
||||
-d '{"jsonrpc":"2.0","method":"eth_blockNumber","params":[],"id":1}'
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### 2. Token Display Issues
|
||||
|
||||
#### Issue: "6,000,000,000.0T WETH" Instead of "6 WETH"
|
||||
|
||||
**Root Cause**: WETH9 contract's `decimals()` returns 0 instead of 18
|
||||
|
||||
**Solution**:
|
||||
|
||||
1. **Remove Token**
|
||||
- Find WETH9 in token list
|
||||
- Click token → "Hide token" or remove
|
||||
|
||||
2. **Re-import with Correct Decimals**
|
||||
- Import tokens → Custom token
|
||||
- Address: `0xC02aaA39b223FE8D0A0e5C4F27eAD9083C756Cc2`
|
||||
- Symbol: `WETH`
|
||||
- **Decimals: `18`** ⚠️ **Critical: Must be 18**
|
||||
|
||||
3. **Verify Display**
|
||||
- Should now show: "6 WETH" or "6.0 WETH"
|
||||
- Not: "6,000,000,000.0T WETH"
|
||||
|
||||
**See**: [WETH9 Display Fix Instructions](./METAMASK_WETH9_FIX_INSTRUCTIONS.md)
|
||||
|
||||
---
|
||||
|
||||
#### Issue: Token Not Showing Balance
|
||||
|
||||
**Symptoms**:
|
||||
- Token imported but shows 0 balance
|
||||
- Token doesn't appear in list
|
||||
|
||||
**Solutions**:
|
||||
|
||||
1. **Check Token Address**
|
||||
- WETH9: `0xC02aaA39b223FE8D0A0e5C4F27eAD9083C756Cc2`
|
||||
- WETH10: `0xf4BB2e28688e89fCcE3c0580D37d36A7672E8A9f`
|
||||
- Verify address is correct (case-sensitive)
|
||||
|
||||
2. **Verify You Have Tokens**
|
||||
```bash
|
||||
cast call 0xC02aaA39b223FE8D0A0e5C4F27eAD9083C756Cc2 \
|
||||
"balanceOf(address)" <YOUR_ADDRESS> \
|
||||
--rpc-url https://rpc-core.d-bis.org
|
||||
```
|
||||
|
||||
3. **Refresh Token List**
|
||||
- Click "Import tokens" → Refresh
|
||||
- Or remove and re-add token
|
||||
|
||||
4. **Check Network**
|
||||
- Ensure you're on ChainID 138
|
||||
- Tokens are chain-specific
|
||||
|
||||
---
|
||||
|
||||
### 3. Transaction Issues
|
||||
|
||||
#### Issue: Transaction Stuck or Pending Forever
|
||||
|
||||
**Symptoms**:
|
||||
- Transaction shows "Pending" for extended time
|
||||
- No confirmation after hours
|
||||
|
||||
**Solutions**:
|
||||
|
||||
1. **Check Network Status**
|
||||
- Verify RPC endpoint is responding
|
||||
- Check block explorer for recent blocks
|
||||
|
||||
2. **Check Gas Price**
|
||||
- May need to increase gas price
|
||||
- Network may be congested
|
||||
|
||||
3. **Replace Transaction** (Same Nonce)
|
||||
- Create new transaction with same nonce
|
||||
- Higher gas price
|
||||
- This cancels the old transaction
|
||||
|
||||
4. **Reset Nonce** (Last Resort)
|
||||
- Settings → Advanced → Reset Account
|
||||
- ⚠️ This clears transaction history
|
||||
|
||||
---
|
||||
|
||||
#### Issue: "Insufficient Funds for Gas"
|
||||
|
||||
**Symptoms**:
|
||||
- Transaction fails immediately
|
||||
- Error: "insufficient funds"
|
||||
|
||||
**Solutions**:
|
||||
|
||||
1. **Check ETH Balance**
|
||||
- Need ETH for gas fees
|
||||
- Gas costs vary (typically 0.001-0.01 ETH)
|
||||
|
||||
2. **Reduce Gas Limit** (If too high)
|
||||
- MetaMask may estimate too high
|
||||
- Try manual gas limit
|
||||
|
||||
3. **Get More ETH**
|
||||
- Request from network administrators
|
||||
- Bridge from another chain
|
||||
- Use faucet (if available)
|
||||
|
||||
---
|
||||
|
||||
#### Issue: Transaction Reverted
|
||||
|
||||
**Symptoms**:
|
||||
- Transaction confirmed but reverted
|
||||
- Error in transaction details
|
||||
|
||||
**Solutions**:
|
||||
|
||||
1. **Check Transaction Details**
|
||||
- View on block explorer
|
||||
- Look for revert reason
|
||||
|
||||
2. **Common Revert Reasons**:
|
||||
- Insufficient allowance (for token transfers)
|
||||
- Contract logic error
|
||||
- Invalid parameters
|
||||
- Out of gas (rare, usually fails before)
|
||||
|
||||
3. **Verify Contract State**
|
||||
- Check if contract is paused
|
||||
- Verify you have permissions
|
||||
- Check contract requirements
|
||||
|
||||
---
|
||||
|
||||
### 4. Price Feed Issues
|
||||
|
||||
#### Issue: Price Not Updating
|
||||
|
||||
**Symptoms**:
|
||||
- Oracle price seems stale
|
||||
- Price doesn't change
|
||||
|
||||
**Solutions**:
|
||||
|
||||
1. **Check Oracle Contract**
|
||||
```bash
|
||||
cast call 0x3304b747e565a97ec8ac220b0b6a1f6ffdb837e6 \
|
||||
"latestRoundData()" \
|
||||
--rpc-url https://rpc-core.d-bis.org
|
||||
```
|
||||
|
||||
2. **Verify `updatedAt` Timestamp**
|
||||
- Should update every 60 seconds
|
||||
- If > 5 minutes old, Oracle Publisher may be down
|
||||
|
||||
3. **Check Oracle Publisher Service**
|
||||
- Service should be running (VMID 3500)
|
||||
- Check service logs for errors
|
||||
|
||||
4. **Manual Price Query**
|
||||
- Use Web3.js or Ethers.js to query directly
|
||||
- See [Oracle Integration Guide](./METAMASK_ORACLE_INTEGRATION.md)
|
||||
|
||||
---
|
||||
|
||||
#### Issue: Price Returns Zero or Error
|
||||
|
||||
**Symptoms**:
|
||||
- `latestRoundData()` returns 0
|
||||
- Contract call fails
|
||||
|
||||
**Solutions**:
|
||||
|
||||
1. **Verify Contract Address**
|
||||
- Oracle Proxy: `0x3304b747e565a97ec8ac220b0b6a1f6ffdb837e6`
|
||||
- Ensure correct address
|
||||
|
||||
2. **Check Contract Deployment**
|
||||
- Verify contract exists on ChainID 138
|
||||
- Check block explorer
|
||||
|
||||
3. **Verify Network**
|
||||
- Must be on ChainID 138
|
||||
- Price feeds are chain-specific
|
||||
|
||||
---
|
||||
|
||||
### 5. Network Switching Issues
|
||||
|
||||
#### Issue: Can't Switch to ChainID 138
|
||||
|
||||
**Symptoms**:
|
||||
- Network doesn't appear in list
|
||||
- Switch fails
|
||||
|
||||
**Solutions**:
|
||||
|
||||
1. **Add Network Manually**
|
||||
- See [Quick Start Guide](./METAMASK_QUICK_START_GUIDE.md)
|
||||
- Ensure all fields are correct
|
||||
|
||||
2. **Programmatic Addition** (For dApps)
|
||||
```javascript
|
||||
try {
|
||||
await window.ethereum.request({
|
||||
method: 'wallet_switchEthereumChain',
|
||||
params: [{ chainId: '0x8a' }], // 138 in hex
|
||||
});
|
||||
} catch (switchError) {
|
||||
// Network doesn't exist, add it
|
||||
if (switchError.code === 4902) {
|
||||
await window.ethereum.request({
|
||||
method: 'wallet_addEthereumChain',
|
||||
params: [networkConfig],
|
||||
});
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
3. **Clear Network Cache**
|
||||
- Remove network
|
||||
- Re-add with correct settings
|
||||
|
||||
---
|
||||
|
||||
### 6. Account Issues
|
||||
|
||||
#### Issue: Wrong Account Connected
|
||||
|
||||
**Symptoms**:
|
||||
- Different address than expected
|
||||
- Can't see expected balance
|
||||
|
||||
**Solutions**:
|
||||
|
||||
1. **Switch Account in MetaMask**
|
||||
- Click account icon
|
||||
- Select correct account
|
||||
|
||||
2. **Import Account** (If needed)
|
||||
- Settings → Import Account
|
||||
- Use private key or seed phrase
|
||||
|
||||
3. **Verify Address**
|
||||
- Check address matches expected
|
||||
- Addresses are case-insensitive but verify format
|
||||
|
||||
---
|
||||
|
||||
#### Issue: Account Not Showing Balance
|
||||
|
||||
**Symptoms**:
|
||||
- Account connected but balance is 0
|
||||
- Expected to have ETH/tokens
|
||||
|
||||
**Solutions**:
|
||||
|
||||
1. **Verify Network**
|
||||
- Must be on ChainID 138
|
||||
- Balances are chain-specific
|
||||
|
||||
2. **Check Address**
|
||||
- Verify correct address
|
||||
- Check on block explorer
|
||||
|
||||
3. **Refresh Balance**
|
||||
- Click refresh icon in MetaMask
|
||||
- Or switch networks and switch back
|
||||
|
||||
---
|
||||
|
||||
## 🔧 Advanced Troubleshooting
|
||||
|
||||
### Enable Debug Mode
|
||||
|
||||
**MetaMask Settings**:
|
||||
1. Settings → Advanced
|
||||
2. Enable "Show Hex Data"
|
||||
3. Enable "Enhanced Gas Fee UI"
|
||||
4. Check browser console for errors
|
||||
|
||||
### Check Browser Console
|
||||
|
||||
**Open Console**:
|
||||
- Chrome/Edge: F12 → Console
|
||||
- Firefox: F12 → Console
|
||||
- Safari: Cmd+Option+I → Console
|
||||
|
||||
**Look For**:
|
||||
- RPC errors
|
||||
- Network errors
|
||||
- JavaScript errors
|
||||
- MetaMask-specific errors
|
||||
|
||||
### Verify RPC Response
|
||||
|
||||
**Test RPC Endpoint**:
|
||||
```bash
|
||||
curl -X POST https://rpc-core.d-bis.org \
|
||||
-H "Content-Type: application/json" \
|
||||
-d '{
|
||||
"jsonrpc": "2.0",
|
||||
"method": "eth_blockNumber",
|
||||
"params": [],
|
||||
"id": 1
|
||||
}'
|
||||
```
|
||||
|
||||
**Expected Response**:
|
||||
```json
|
||||
{
|
||||
"jsonrpc": "2.0",
|
||||
"id": 1,
|
||||
"result": "0x..."
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 📞 Getting Help
|
||||
|
||||
### Resources
|
||||
|
||||
1. **Documentation**:
|
||||
- [Quick Start Guide](./METAMASK_QUICK_START_GUIDE.md)
|
||||
- [Full Integration Requirements](./METAMASK_FULL_INTEGRATION_REQUIREMENTS.md)
|
||||
- [Oracle Integration](./METAMASK_ORACLE_INTEGRATION.md)
|
||||
|
||||
2. **Block Explorer**:
|
||||
- `https://explorer.d-bis.org`
|
||||
- Check transactions, contracts, addresses
|
||||
|
||||
3. **Network Status**:
|
||||
- RPC: `https://rpc-core.d-bis.org`
|
||||
- Verify endpoint is responding
|
||||
|
||||
### Information to Provide When Reporting Issues
|
||||
|
||||
1. **MetaMask Version**: Settings → About
|
||||
2. **Browser**: Chrome/Firefox/Safari + version
|
||||
3. **Network**: ChainID 138
|
||||
4. **Error Message**: Exact error text
|
||||
5. **Steps to Reproduce**: What you did before error
|
||||
6. **Console Errors**: Any JavaScript errors
|
||||
7. **Transaction Hash**: If transaction-related
|
||||
|
||||
---
|
||||
|
||||
## ✅ Quick Diagnostic Checklist
|
||||
|
||||
Run through this checklist when troubleshooting:
|
||||
|
||||
- [ ] Network is "SMOM-DBIS-138" (ChainID 138)
|
||||
- [ ] RPC URL is `https://rpc-core.d-bis.org`
|
||||
- [ ] Chain ID is `138` (decimal, not hex)
|
||||
- [ ] Account is connected and correct
|
||||
- [ ] Sufficient ETH for gas fees
|
||||
- [ ] Token decimals are correct (18 for WETH)
|
||||
- [ ] Browser console shows no errors
|
||||
- [ ] RPC endpoint is responding
|
||||
- [ ] Block explorer shows recent blocks
|
||||
|
||||
---
|
||||
|
||||
**Last Updated**: $(date)
|
||||
|
||||
Reference in New Issue
Block a user