168 lines
13 KiB
Markdown
168 lines
13 KiB
Markdown
# Chain 138 Snap — Troubleshooting (balance, swap, data)
|
||
|
||
If **installation fails** (“snap is not on the allowlist”), **main balance or USD value is not showing**, **swap is malfunctioning**, or **historical/data not loading** when using the Chain 138 Snap with MetaMask (including Flask), use this guide.
|
||
|
||
---
|
||
|
||
## 1. Installation fails: "The snap is not on the allowlist"
|
||
|
||
**What you see:** When adding the Snap in MetaMask you get:
|
||
|
||
- **"Connection failed — Fetching of chain138-snap failed, check your network and try again."**
|
||
- **"Cannot install version '0.1.2' of snap 'npm:chain138-snap': The snap is not on the allowlist."**
|
||
|
||
**Cause:** MetaMask only allows installing Snaps that use **protected permissions** (such as `endowment:rpc` and `endowment:network-access`) if the Snap is on their **allowlist**. The Chain 138 Snap uses those permissions, so it must be allowlisted. The Snap is published on npm and has been **submitted** for allowlisting; until MetaMask/Consensys approves it, standard MetaMask will block installation.
|
||
|
||
**What you can do:**
|
||
|
||
1. **Use MetaMask Flask (workaround now)**
|
||
[MetaMask Flask](https://metamask.io/flask/) is the development build and **does not enforce the allowlist**. Install Flask, then add the Snap using the same ID: `npm:chain138-snap`. The Snap works the same once installed.
|
||
|
||
2. **Wait for allowlist approval**
|
||
Once the Snap is approved, it will be installable in standard MetaMask. No code changes are required on your side.
|
||
|
||
3. **Operators:** If you submitted the allowlist form and it has been pending for a long time, you can follow up via the [MetaMask Snaps allowlist process](https://docs.metamask.io/snaps/how-to/get-allowlisted/#1-submit-your-snap). For new versions (e.g. 0.1.3), use the [Snaps Directory Information Update form](https://docs.metamask.io/snaps/how-to/get-allowlisted/#5-update-your-snap) to add the new version. Pre-filled fields for the submission are in [ALLOWLIST_FORM_FIELDS.md](../ALLOWLIST_FORM_FIELDS.md).
|
||
|
||
---
|
||
|
||
## 2. Main balance / USD not showing ($0.00, "No conversion rate available")
|
||
|
||
**What you see:** MetaMask shows **$0.00** or **"No conversion rate available"** for ETH (or other tokens) even when you hold a non‑zero balance (e.g. 1,000 ETH).
|
||
|
||
**Cause:** The **main wallet balance and USD value** are provided by **MetaMask (Consensys)**, not by the Snap. MetaMask gets conversion rates from its own providers (e.g. LavaPack). **Chain 138 (DeFi Oracle Meta Mainnet) is not in that list**, so MetaMask has no price feed for it and shows no USD value.
|
||
|
||
**This is expected** for custom chains until Consensys or price providers add support.
|
||
|
||
**What you can do:**
|
||
|
||
- **Trust the token quantity:** Your on‑chain balance (e.g. "1,000 ETH") is correct; only the USD conversion is missing in the wallet UI.
|
||
- **Use the Snap for prices:** Open the **Snap companion site** (e.g. https://explorer.d-bis.org/snap/) and use **"Show market data"** or **"Fetch market summary"**. Those use the token‑aggregation API (see §5) and can show USD prices for Chain 138 tokens.
|
||
- **Long‑term:** Submit Chain 138 and tokens to CoinGecko/CMC and/or Consensys so native MetaMask USD may be supported later (see project docs, e.g. `COINGECKO_SUBMISSION_GUIDE`, Consensys outreach).
|
||
|
||
---
|
||
|
||
## 3. "We could not fetch any historical data"
|
||
|
||
**What you see:** In the token/asset detail view, MetaMask shows a raccoon mascot and **"We could not fetch any historical data"** with time range buttons (1D, 1W, 1M, etc.).
|
||
|
||
**Cause:** Historical price/chart data is also supplied by **MetaMask’s portfolio/price providers**, which do not support Chain 138.
|
||
|
||
**What you can do:** This is a MetaMask UI limitation. Use the Snap’s market data (companion site) or external explorers/APIs for historical data on Chain 138.
|
||
|
||
---
|
||
|
||
## 4. Swap malfunctioning (in‑wallet Swap button)
|
||
|
||
**What you see:** Clicking **Swap** in MetaMask on Chain 138 fails or shows errors (e.g. "No XChain Swaps native asset found for chainId: eip155:138").
|
||
|
||
**Cause:** MetaMask’s **in‑wallet Swap** feature does **not** support Chain 138. It only supports chains in their native Swaps list.
|
||
|
||
**What you can do:**
|
||
|
||
- **Send ETH on Chain 138:** Use the dedicated **Send on Chain 138** page:
|
||
https://explorer.d-bis.org/snap/send
|
||
It uses `eth_sendTransaction` from the dApp context and works on Chain 138 (see `packages/site/src/pages/send.tsx`).
|
||
- **Swap quotes via Snap:** On the Snap companion site, use the **Swap quote** card: enter token In/Out and amount, then **"Get quote"** or **"Show quote in Snap"**. This uses the token‑aggregation API. Executing the actual swap must be done in your dApp or a DEX that supports Chain 138, not via MetaMask’s Swap button.
|
||
- **WETH display quirk:** If you see wrong WETH balance formatting (e.g. "6,000,000,000.0T WETH"), see [METAMASK_WETH9_DISPLAY_BUG.md](../../docs/METAMASK_WETH9_DISPLAY_BUG.md) (token list / decimals).
|
||
|
||
---
|
||
|
||
## 5. Snap market data / swap quote / bridge not loading
|
||
|
||
**What you see:** On the companion site (e.g. https://explorer.d-bis.org/snap/), **"Show market data"**, **"Fetch market summary"**, **"Get quote"** / **"Show quote in Snap"**, or **bridge routes** show an error or "Set GATSBY_SNAP_API_BASE_URL".
|
||
|
||
**Cause:** Those features need a **token‑aggregation–compatible API**. The Snap calls:
|
||
|
||
- `GET {apiBaseUrl}/api/v1/networks`
|
||
- `GET {apiBaseUrl}/api/v1/tokens?chainId=138&limit=...`
|
||
- `GET {apiBaseUrl}/api/v1/quote?chainId=138&tokenIn=...&tokenOut=...&amountIn=...`
|
||
- `GET {apiBaseUrl}/api/v1/bridge/routes`
|
||
- etc.
|
||
|
||
The companion site passes `apiBaseUrl` from **GATSBY_SNAP_API_BASE_URL** at **build time**. If that URL does not serve the token‑aggregation API (see `smom-dbis-138/services/token-aggregation` and [REST_API_REFERENCE.md](../../../smom-dbis-138/services/token-aggregation/docs/REST_API_REFERENCE.md)), those calls fail.
|
||
|
||
**What you can do:**
|
||
|
||
1. **If you build with `GATSBY_SNAP_API_BASE_URL=https://explorer.d-bis.org`**
|
||
Then **explorer.d-bis.org** must expose the token‑aggregation API. The explorer’s normal Blockscout/Go APIs do **not** implement `/api/v1/networks`, `/api/v1/tokens`, `/api/v1/quote`, etc. You must either:
|
||
- **Deploy the token‑aggregation service** (from `smom-dbis-138/services/token-aggregation`) and **proxy** its routes under `https://explorer.d-bis.org/api/v1/...`. On the explorer VM (VMID 5000), run **`explorer-monorepo/scripts/apply-nginx-token-aggregation-proxy.sh`** (or ensure the nginx config includes a `location /api/v1/` proxy to the token‑aggregation port, e.g. 3000). The script **`fix-nginx-conflicts-vmid5000.sh`** in the same repo already adds this proxy when applied.
|
||
- Or use a **separate API host** (see below).
|
||
|
||
2. **If the token‑aggregation service runs elsewhere** (e.g. `https://api.d-bis.org` or an internal URL):
|
||
Build the Snap site with that base URL:
|
||
|
||
```bash
|
||
export GATSBY_SNAP_API_BASE_URL=https://your-token-aggregation-host
|
||
bash scripts/build-snap-site-for-explorer.sh
|
||
```
|
||
|
||
Deploy the built `packages/site/public/` to `/var/www/html/snap/` (or your Snap host). Then the companion site will pass the correct `apiBaseUrl` to the Snap and market/swap/bridge can work.
|
||
|
||
3. **Local development:** Set `GATSBY_SNAP_API_BASE_URL` in `packages/site/.env` to your token‑aggregation base URL (e.g. `http://localhost:3001` if the service runs there). See [FAQ.md](FAQ.md) (“The companion site shows ‘Set GATSBY_SNAP_API_BASE_URL’”).
|
||
|
||
---
|
||
|
||
## 6. No icons or tokens showing in MetaMask Flask
|
||
|
||
**What you see:** MetaMask Flask shows no token icons, no chain icons, or no tokens from the token list when viewing Chain 138 or ALL Mainnet.
|
||
|
||
**Cause:** MetaMask does not auto-load tokens from the Snap. Chain 138 is not in MetaMask’s built-in token detection (which only covers Ethereum, Polygon, Arbitrum, etc.). You must add the token list URL manually. Icons come from `logoURI` (per token) and `iconUrls` (per network) in the API responses; if those URLs are missing or unreachable, MetaMask shows no icons.
|
||
|
||
**What you can do:**
|
||
|
||
1. **Get and add the token list URL**
|
||
- Open the Snap companion site (e.g. https://explorer.d-bis.org/snap/).
|
||
- Connect MetaMask Flask and install the Snap.
|
||
- Click **"Show dynamic info"** (requires `GATSBY_SNAP_API_BASE_URL` to be set at build time).
|
||
- The Snap dialog shows the **Token list URL** (e.g. `https://explorer.d-bis.org/api/v1/report/token-list`).
|
||
- Add that URL in MetaMask: **Settings → Security & Privacy → Token list** (or equivalent), if your MetaMask version supports custom token list URLs.
|
||
|
||
2. **If MetaMask does not support custom token list URLs**
|
||
- Add tokens manually: **Tokens** tab → **Import tokens** → **Custom token** → enter the token contract address for Chain 138 (e.g. cUSDC, cUSDT from the explorer or [CHAIN138_TOKEN_ADDRESSES](../../../docs/11-references/CHAIN138_TOKEN_ADDRESSES.md)).
|
||
|
||
3. **Ensure `apiBaseUrl` is set and reachable**
|
||
- The companion site must be built with `GATSBY_SNAP_API_BASE_URL` pointing at the token-aggregation API.
|
||
- Verify: `curl "https://explorer.d-bis.org/api/v1/report/token-list?chainId=138"` returns valid JSON with `tokens` and each token has `logoURI`.
|
||
|
||
4. **Icons not showing**
|
||
- Token icons: Each token in the token list must have a valid `logoURI`. The token-aggregation API provides these from `canonical-tokens.ts` (Trust Wallet assets).
|
||
- Network icons: `GET /api/v1/networks` must return `iconUrls` for each chain. Each network has a primary URL (e.g. `explorer.d-bis.org/favicon.ico`) and a fallback (Trust Wallet ETH logo). If the primary 404s, MetaMask uses the fallback. Operators: add `favicon.ico` to explorer and alltra sites if missing.
|
||
- If logo URLs (e.g. raw.githubusercontent.com) are blocked or return 404, operators can host logos locally and update `canonical-tokens.ts` or `networks.ts`.
|
||
|
||
**Operators:** See [PRE_PUBLISH_TESTING.md](../PRE_PUBLISH_TESTING.md) §4.3 (token list logoURI) and §4.4 (network iconUrls) for verification steps.
|
||
|
||
---
|
||
|
||
## 7. Permissions and connected site
|
||
|
||
The Snap needs:
|
||
|
||
- **Access the internet** — to call the token‑aggregation API.
|
||
- **Display dialog windows in MetaMask** — for market data, swap quote, bridge dialogs.
|
||
- **Allow websites to communicate directly with Chain 138** — so the companion site (e.g. explorer.d-bis.org) can invoke the Snap.
|
||
|
||
If market/swap work on the companion site but not from another origin, ensure that site is **connected** in MetaMask (Snap settings → Connected sites) and that you’re using the same Snap origin (e.g. `npm:chain138-snap`) and correct `apiBaseUrl`.
|
||
|
||
---
|
||
|
||
## 8. Quick reference
|
||
|
||
| Issue | Cause | Action |
|
||
| --------------------------------------------- | --------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------- |
|
||
| Installation: "snap is not on the allowlist" | Snap not yet approved on MetaMask allowlist | Use [MetaMask Flask](https://metamask.io/flask/) to install now; or wait for allowlist approval |
|
||
| No icons or tokens in MetaMask Flask | Token list not added; Chain 138 not in built-in detection | Use "Show dynamic info" to get token list URL; add in MetaMask Settings → Token list; or add tokens manually |
|
||
| Main balance USD = $0.00 / no conversion rate | MetaMask has no price feed for Chain 138 | Use Snap “Show market data” or accept quantity-only in wallet |
|
||
| Historical data not loading | MetaMask portfolio doesn’t support Chain 138 | Use Snap/explorer or external APIs |
|
||
| In‑wallet Swap fails | MetaMask Swap doesn’t support Chain 138 | Use [Send on Chain 138](https://explorer.d-bis.org/snap/send); get swap quotes from Snap companion site and execute swap in dApp/DEX |
|
||
| Snap market/swap/bridge errors | `apiBaseUrl` not set or not serving token‑aggregation API | Set GATSBY_SNAP_API_BASE_URL to token‑aggregation host; ensure `/api/v1/...` is available there (or proxy it under explorer.d-bis.org) |
|
||
|
||
---
|
||
|
||
**Related docs**
|
||
|
||
- [TOKEN_LIST_AND_ICONS_GUIDE.md](TOKEN_LIST_AND_ICONS_GUIDE.md) — how to add token list URL and fix icons
|
||
- [FAQ.md](FAQ.md) — apiBaseUrl, permissions, “Set GATSBY_SNAP_API_BASE_URL”
|
||
- [TESTING_INSTRUCTIONS.md](../TESTING_INSTRUCTIONS.md) — testing market summary, swap quote, bridge
|
||
- [METAMASK_WETH9_DISPLAY_BUG.md](../../docs/METAMASK_WETH9_DISPLAY_BUG.md) — WETH balance display
|
||
- Token‑aggregation API: `smom-dbis-138/services/token-aggregation/docs/REST_API_REFERENCE.md`
|