d-bis/metamask-integration
4
0
Fork 0
Code Issues Pull Requests 1 Actions Packages Projects Releases Wiki Activity

chore: sync submodule state (parent ref update)

Browse Source 
Made-with: Cursor
This commit is contained in:
defiQUG
2026-03-02 12:14:14 -08:00
parent b6a776e5d7
commit 25c96e210a
316 changed files with 29779 additions and 677 deletions
Download Patch File Download Diff File Expand all files Collapse all files

167
chain138-snap/docs/CHAIN138_SNAP_TROUBLESHOOTING.md Normal file
View File

@@ -0,0 +1,167 @@
# 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`

62
chain138-snap/docs/CONTRIBUTING.md Normal file
View File

@@ -0,0 +1,62 @@
# Contributing to Chain 138 Snap
Thank you for your interest in contributing. This guide covers setup, testing, and publishing.
## Prerequisites
- **Node.js** 18.6.0 or later (LTS recommended)
- **pnpm** (default) or **Yarn** — see [PACKAGE_MANAGER.md](../PACKAGE_MANAGER.md)
## Setup
```bash
# Clone the repo (or your fork)
git clone https://github.com/bis-innovations/chain138-snap.git
cd chain138-snap
# Install dependencies (pnpm default)
pnpm install
# Optional: enable scripts for packages that need postinstall (e.g. sharp)
pnpm run allow-scripts
```
## Development
- **Start dev server** (Snap + companion site): `pnpm run start` — serves at http://localhost:8000
- **Build:** `pnpm run build` — builds Snap and site
- **Lint:** `pnpm run lint` — ESLint + Prettier (JSON/MD/YAML)
- **Lint fix:** `pnpm run lint:fix`
## Testing
- **Unit tests (Snap):** `pnpm run test` — builds the Snap and runs Jest in packages/snap
- **E2E (Playwright):** `pnpm run test:e2e` — runs Playwright against the companion site (first time: `npx playwright install`)
For full manual E2E (MetaMask Flask, all RPC methods), see [TESTING_INSTRUCTIONS.md](../TESTING_INSTRUCTIONS.md) and [E2E_PREPARATION.md](../E2E_PREPARATION.md).
## Packages with scripts
Scripts are disabled by default (LavaMoat). If you need to run install scripts (e.g. for sharp or gatsby):
```bash
pnpm run allow-scripts
```
Then enable the package in the lavamoat.allowScripts section of the root package.json if required.
## Submitting changes
1. Create a branch, make your changes, and run `pnpm run lint` and `pnpm run test`.
2. Open a pull request against main.
3. Ensure CI passes (build, lint, tests, and any security workflows).
## Publishing (maintainers)
- **Push to GitHub:** See [PUSH_AND_PUBLISH.md](../PUSH_AND_PUBLISH.md) (subtree push from parent repo if applicable).
- **Publish to npm:** From this repo root, `pnpm run publish:snap` (requires NPM_ACCESS_TOKEN in .env for 2FA bypass; see .env.example).
- **Allowlist:** After publishing a new version, submit an update via the MetaMask Snaps Directory Information Update form if the Snap is already allowlisted.
## Code of conduct
Be respectful and constructive. Report security issues privately (see [SECURITY.md](../SECURITY.md)).

65
chain138-snap/docs/DEPLOY_COMPANION_SITE.md Normal file
View File

@@ -0,0 +1,65 @@
# Deploy the companion site
The companion site (`packages/site`) is a Gatsby app that lets users connect to and test the Snap. You can build it and deploy it to any static host (e.g. GitHub Pages, Netlify, or your own server).
## Build
From the repo root:
```bash
# Build with path prefix (e.g. /snap if served at https://yoursite.com/snap/)
GATSBY_PATH_PREFIX=/snap pnpm --filter site run build
# With production API URL (so Market data, Bridge, Swap cards work)
GATSBY_SNAP_API_BASE_URL=https://your-token-aggregation-api.com GATSBY_PATH_PREFIX=/snap pnpm --filter site run build
```
- Output is in `packages/site/public/`. Asset paths are prefixed by `GATSBY_PATH_PREFIX` (e.g. `/snap/`).
- Use `GATSBY_PATH_PREFIX=/` if the site is served at the root of your domain.
## Deploy to your host
1. **Upload** the contents of `packages/site/public/` to your web server (e.g. `/var/www/html/snap/` or your CDN).
2. **Web server:** Ensure the server serves the SPA correctly:
- For a path like `/snap/`, map `/snap` and `/snap/*` to the built files and use a fallback to `/snap/index.html` for client-side routing.
- Example (nginx):
```nginx
location /snap/ {
alias /var/www/html/snap/;
try_files $uri $uri/ /snap/index.html;
add_header Cache-Control "no-store, no-cache, must-revalidate";
}
```
3. **HTTPS:** Serve the site over HTTPS in production (see [SECURITY.md](../SECURITY.md)).
## Environment variables (build time)
| Variable | Description |
| -------------------------- | --------------------------------------------------------------------------------------------------- |
| `GATSBY_PATH_PREFIX` | Path prefix (e.g. `/snap`). Default: none (root). |
| `GATSBY_SNAP_API_BASE_URL` | Token-aggregation API base URL passed to the Snap for market data, bridge, swap. No trailing slash. |
| `GATSBY_SNAP_SITE_URL` | Public origin of the companion site (e.g. `https://explorer.d-bis.org`). When set, the "Send on Chain 138" link is absolute HTTPS so it never redirects to HTTP. |
| `GATSBY_BUILD_SHA` | Optional; written to `version.json` for display. |
Set these when running the build; they are baked into the static output.
## Verification
After deploy, open your site URL and confirm:
- The Snap Connect UI loads.
- Connecting with MetaMask (or MetaMask Flask) installs the Snap.
- If you set `GATSBY_SNAP_API_BASE_URL`, the Market data, Bridge, and Swap quote cards work when the API is reachable.
## Optional: validate token/list URLs
If you use external JSON URLs for networks, token list, or bridge list, you can validate them before deploy:
```bash
./scripts/validate-token-lists.sh [URL1] [URL2] ...
# Or set TOKEN_LIST_JSON_URL, BRIDGE_LIST_JSON_URL, NETWORKS_JSON_URL
```
See script help for details.

123
chain138-snap/docs/FAQ.md Normal file
View File

@@ -0,0 +1,123 @@
# Chain 138 Snap — FAQ
Frequently asked questions about the Chain 138 Snap (MetaMask).
---
## General
### What is the Chain 138 Snap?
A MetaMask Snap that adds **Chain 138** (DeFi Oracle Meta Mainnet) and **ALL Mainnet** (651940) support inside MetaMask: network parameters, token list, market data (USD prices), swap quotes, and bridge routes (CCIP and Trustless). It uses a token-aggregation (or compatible) API that you configure.
### Why use this Snap?
MetaMask supports Chain 138 as a custom EVM network, but native **Swaps**, **Portfolio Bridge**, and **USD pricing** do not include Chain 138. This Snap provides in-wallet swap quotes, bridge routes, and market data by calling your API, so users get feature parity without waiting for upstream support.
### What is the Snap ID?
**Production:** `npm:chain138-snap` (after installing from npm or the MetaMask Snaps Directory).
**Development:** `local:http://localhost:8000` when running the dev server.
---
## Installation and usage
### How do I install the Snap?
1. Install [MetaMask](https://metamask.io/) (or [MetaMask Flask](https://metamask.io/flask/) for development).
2. From a dApp or the companion site, connect and add the Snap using the ID `npm:chain138-snap`.
### Do I need MetaMask Flask?
- **Production:** No. Once the Snap is allowlisted, it installs in standard MetaMask.
- **Development:** Yes, for testing before allowlisting. Use [MetaMask Flask](https://metamask.io/flask/).
### Why do market data, swap quote, and bridge routes not work?
Those features require the dApp to pass **`apiBaseUrl`** (your token-aggregation service base URL) when invoking the Snap. Without it, the Snap cannot fetch data. See [INTEGRATORS.md](../INTEGRATORS.md).
### Can I use my own API or JSON URLs?
Yes. You can pass:
- **`apiBaseUrl`** — base URL of a token-aggregation–compatible API (networks, token list, bridge, quote endpoints).
- **`networksUrl`** — direct URL to a networks JSON (overrides API for networks).
- **`tokenListUrl`** — direct URL to a token list JSON.
- **`bridgeListUrl`** — direct URL to a bridge routes JSON.
See [INTEGRATORS.md](../INTEGRATORS.md) and [TESTING_INSTRUCTIONS.md](../TESTING_INSTRUCTIONS.md).
---
## Development
### How do I run the Snap locally?
From the repo root: `pnpm run start`. The companion site and Snap are served at http://localhost:8000. Use MetaMask Flask and connect to that URL.
### How do I run tests?
- **Unit (Jest):** `pnpm run test`
- **E2E (Playwright):** `pnpm run test:e2e` (run `npx playwright install` once)
See [TESTING_INSTRUCTIONS.md](../TESTING_INSTRUCTIONS.md) for full manual E2E.
### The companion site shows "Set GATSBY_SNAP_API_BASE_URL"
Set `GATSBY_SNAP_API_BASE_URL` in `packages/site/.env` (copy from `.env.production.dist`) to your token-aggregation API base URL so the site can pass `apiBaseUrl` to the Snap. Restart the dev server after changing env.
### How do I publish a new version?
1. Bump version in `packages/snap/package.json`.
2. From repo root: `pnpm run build` then `pnpm run publish:snap` (see [PUSH_AND_PUBLISH.md](../PUSH_AND_PUBLISH.md)).
3. Push to GitHub. If the Snap is allowlisted, submit a version update via the [MetaMask update form](https://docs.metamask.io/snaps/how-to/get-allowlisted/#5-update-your-snap).
---
## Permissions and security
### What permissions does the Snap use?
- **snap_dialog** — show dialogs (e.g. bridge routes, market data).
- **endowment:rpc** (dapps: true) — handle RPC from dApps.
- **endowment:network-access** — fetch data from the configured API/URLs.
No key-management or account APIs are used. See [SECURITY.md](../SECURITY.md) and `packages/snap/snap.manifest.json`.
### Is an audit required for allowlisting?
No. The Snap does not use key-management APIs, so a third-party audit is not required for the MetaMask Snaps Directory. See [ALLOWLIST_SOURCE_AND_COMPLIANCE_CHECKLIST.md](../ALLOWLIST_SOURCE_AND_COMPLIANCE_CHECKLIST.md).
---
## RPC methods
### What RPC methods are available?
See the table in [packages/snap/README.md](../packages/snap/README.md) or [TESTING_INSTRUCTIONS.md](../TESTING_INSTRUCTIONS.md). Summary: `hello`, `get_networks`, `get_chain138_config`, `get_chain138_market_chains`, `get_token_list`, `get_token_list_url`, `get_oracles`, `show_dynamic_info`, `get_market_summary`, `show_market_data`, `get_bridge_routes`, `show_bridge_routes`, `get_swap_quote`, `show_swap_quote`.
### How do I call the Snap from my dApp?
Use `wallet_requestSnaps` to install and `wallet_invokeSnap` to call methods. Example in [INTEGRATORS.md](../INTEGRATORS.md) and [packages/snap/README.md](../packages/snap/README.md).
---
## Troubleshooting
### Snap not appearing in MetaMask Flask
- Ensure the dev server is running on port 8000 and you opened http://localhost:8000.
- Check the browser console for errors and refresh the page.
### API calls failing (CORS, 404)
- Ensure your token-aggregation API allows the Snap/site origin in CORS.
- Verify `apiBaseUrl` is correct (no trailing slash) and the endpoints (e.g. `/api/v1/networks`, `/api/v1/report/token-list`) exist and return valid JSON.
### Permission errors
- Confirm `snap.manifest.json` includes `endowment:network-access` if you call APIs. Reinstall the Snap after changing the manifest.
For more, see the **Troubleshooting** section in [TESTING_INSTRUCTIONS.md](../TESTING_INSTRUCTIONS.md).

186
chain138-snap/docs/FEATURES.md Normal file
View File

@@ -0,0 +1,186 @@
# Chain 138 Snap — Features and RPC methods
This document lists every function and feature of the Snap, with parameters and response shapes. The Snap supports **both** blockchains: **Chain 138** (DeFi Oracle Meta Mainnet) and **ALL Mainnet** (651940).
---
## Blockchains supported
| Chain | Chain ID | Name | Use in Snap |
| --------------- | -------- | ------------------------ | ----------------------------------------------------- |
| **Chain 138** | 138 | DeFi Oracle Meta Mainnet | Primary; networks, config, market, swap, bridge |
| **ALL Mainnet** | 651940 | ALL Mainnet | Supported in networks, token list, optional `chainId` |
All methods that accept an optional `chainId` default to **138** when omitted.
---
## Feature overview (visual)
```
┌─────────────────────────────────────────────────────────────────────────┐
│ Chain 138 Snap (npm:chain138-snap) │
├─────────────────────────────────────────────────────────────────────────┤
│ Networks & config │ get_networks, get_chain138_config, │
│ (Chain 138 + ALL) │ get_chain138_market_chains │
├─────────────────────────────────────────────────────────────────────────┤
│ Token list │ get_token_list, get_token_list_url │
│ (optional chainId) │ (chainId: 138 or 651940) │
├─────────────────────────────────────────────────────────────────────────┤
│ Market data │ get_market_summary, show_market_data │
│ (USD prices) │ (dialog: token symbols + prices) │
├─────────────────────────────────────────────────────────────────────────┤
│ Bridge routes │ get_bridge_routes, show_bridge_routes │
│ (CCIP + Trustless) │ (dialog: CCIP WETH9/WETH10 + Trustless Lockbox)│
├─────────────────────────────────────────────────────────────────────────┤
│ Swap quote │ get_swap_quote, show_swap_quote │
│ (Chain 138) │ (tokenIn, tokenOut, amountIn → amountOut) │
├─────────────────────────────────────────────────────────────────────────┤
│ Oracles & dynamic │ get_oracles, show_dynamic_info │
│ (API config) │ (dialog: networks + token list URL) │
├─────────────────────────────────────────────────────────────────────────┤
│ Test │ hello (returns greeting) │
└─────────────────────────────────────────────────────────────────────────┘
```
---
## RPC method matrix
| Method | Chain 138 | ALL (651940) | Requires apiBaseUrl / URL param | Shows dialog (UI) |
| ---------------------------- | --------- | ------------ | ---------------------------------------- | ------------------ |
| `hello` | — | — | No | Yes (confirmation) |
| `get_networks` | ✅ | ✅ | apiBaseUrl or networksUrl | No |
| `get_chain138_config` | ✅ | — | apiBaseUrl or networksUrl | No |
| `get_chain138_market_chains` | ✅ | — | apiBaseUrl | No |
| `get_token_list` | ✅ | ✅ | apiBaseUrl or tokenListUrl | No |
| `get_token_list_url` | ✅ | ✅ | apiBaseUrl or tokenListUrl | No |
| `get_oracles` | ✅ | — | apiBaseUrl | No |
| `show_dynamic_info` | ✅ | ✅ | apiBaseUrl or networksUrl/tokenListUrl | **Yes** |
| `get_market_summary` | ✅ | ✅ | apiBaseUrl | No |
| `show_market_data` | ✅ | ✅ | apiBaseUrl | **Yes** |
| `get_bridge_routes` | ✅ | — | apiBaseUrl or bridgeListUrl | No |
| `show_bridge_routes` | ✅ | — | apiBaseUrl or bridgeListUrl | **Yes** |
| `get_swap_quote` | ✅ | — | apiBaseUrl + tokenIn, tokenOut, amountIn | No |
| `show_swap_quote` | ✅ | — | apiBaseUrl + tokenIn, tokenOut, amountIn | **Yes** |
---
## Method reference by category
### Test
| Method | Params | Response | UI |
| ------- | ------ | ------------------------------ | ------------------- |
| `hello` | — | `"Hello from Chain 138 Snap!"` | Confirmation dialog |
---
### Networks and chain config
| Method | Params | Response shape |
| ---------------------------- | ----------------------------- | ------------------------------------------------------------------------------------------ |
| `get_networks` | `apiBaseUrl` or `networksUrl` | `{ version?, networks: EIP-3085[] }` |
| `get_chain138_config` | `apiBaseUrl` or `networksUrl` | Chain 138 params (chainId, chainName, rpcUrls, nativeCurrency, blockExplorerUrls, oracles) |
| `get_chain138_market_chains` | `apiBaseUrl` | `[{ chainId, name, nativeToken, rpcUrl, explorerUrl }]` |
**Visual (dialog):** None for get\_\*; use `show_dynamic_info` for an in-Snap dialog with networks and token list URL.
---
### Token list
| Method | Params | Response shape |
| -------------------- | ------------------------------------------------------------------ | ----------------------------------------------------------- |
| `get_token_list` | `apiBaseUrl` or `tokenListUrl`, optional `chainId` (138 \| 651940) | `{ tokens: [{ symbol, name, address, ... }] }` or API shape |
| `get_token_list_url` | Same | URL string or object with token list URL |
---
### Oracles and dynamic info
| Method | Params | Response / UI |
| ------------------- | ---------------------------------------------- | ----------------------------------------------- |
| `get_oracles` | `apiBaseUrl` | Oracles config from API |
| `show_dynamic_info` | `apiBaseUrl` or `networksUrl` / `tokenListUrl` | **Dialog:** networks summary and token list URL |
---
### Market data (USD prices)
| Method | Params | Response shape | UI |
| -------------------- | ---------------------------------------------- | --------------------------------------------------------------------------- | ----------------------------------------------------------------------- |
| `get_market_summary` | `apiBaseUrl`, optional `chainId` (default 138) | `{ tokens: [{ symbol, name, address, market?: { priceUsd, volume24h } }] }` | No |
| `show_market_data` | Same | — | **Dialog:** "Market data (Chain 138)" with token symbols and USD prices |
---
### Bridge routes (CCIP + Trustless)
| Method | Params | Response shape | UI |
| -------------------- | ------------------------------- | ----------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------- |
| `get_bridge_routes` | `apiBaseUrl` or `bridgeListUrl` | `{ routes: { weth9?, weth10?, trustless? }, chain138Bridges: { weth9?, weth10?, trustless? } }` | No |
| `show_bridge_routes` | Same | — | **Dialog:** CCIP (WETH9/WETH10) and Trustless (Lockbox on 138) routes to Ethereum Mainnet |
The API or `bridgeListUrl` JSON may include:
- **CCIP:** `routes.weth9`, `routes.weth10`, `chain138Bridges.weth9`, `chain138Bridges.weth10`.
- **Trustless:** `chain138Bridges.trustless` (Lockbox on Chain 138), optional `routes.trustless['Ethereum Mainnet (1)']` (Ethereum-side contract).
---
### Swap quote
| Method | Params | Response shape | UI |
| ----------------- | ---------------------------------------------------------------------------------------------- | -------------------------------------- | -------------------------------- |
| `get_swap_quote` | `apiBaseUrl`, `tokenIn`, `tokenOut`, `amountIn` (raw string), optional `chainId` (default 138) | `{ amountOut?, error?, poolAddress? }` | No |
| `show_swap_quote` | Same | — | **Dialog:** In/Out amounts (raw) |
---
## Request flow (high level)
```mermaid
flowchart LR
subgraph dApp
A[dApp / Companion site]
end
subgraph Snap
B[Chain 138 Snap]
end
subgraph API
C[Token-aggregation API]
end
A -->|wallet_invokeSnap + apiBaseUrl / URL params| B
B -->|GET /api/v1/networks etc.| C
C -->|JSON| B
B -->|result or snap_dialog| A
```
---
## Optional URL overrides
Instead of (or in addition to) `apiBaseUrl`, you can pass:
| Param | Used by methods |
| --------------- | ----------------------------------------- |
| `networksUrl` | `get_networks`, `get_chain138_config` |
| `tokenListUrl` | `get_token_list`, `get_token_list_url` |
| `bridgeListUrl` | `get_bridge_routes`, `show_bridge_routes` |
---
## Screenshots and visuals (for maintainers)
To make the docs more visual, add screenshots under **`docs/images/`** and link them here and in the README. Suggested captures:
| Screenshot | Description |
| -------------------------- | ---------------------------------------------------------------- |
| `connect.png` | Companion site Connect button and MetaMask install prompt |
| `market-data-dialog.png` | Snap dialog from `show_market_data` (Chain 138 tokens + prices) |
| `bridge-routes-dialog.png` | Snap dialog from `show_bridge_routes` (CCIP + Trustless routes) |
| `swap-quote-dialog.png` | Snap dialog from `show_swap_quote` |
| `dynamic-info-dialog.png` | Snap dialog from `show_dynamic_info` (networks + token list URL) |
After adding images, link them in this section and in [README.md](../README.md).

253
chain138-snap/docs/PRE_PUBLISH_TESTING.md Normal file
View File

@@ -0,0 +1,253 @@
# Thorough Pre-Publish Testing Guide — Chain 138 Snap
Use this guide to **thoroughly test the Snap before every npm publish** and before submitting or updating the Snap in the MetaMask directory. It covers build, assets (logos/images), every RPC method, companion site, Send page, production-like flows, and recommendations. No details (including chain/token logos) are left out.
---
## 1. Overview and when to use
- **Purpose:** Ensure the Snap and companion site work end-to-end, all assets (icons, logos) are present and reachable, and the package is ready for npm and (optionally) the MetaMask directory.
- **When:** Before each `pnpm run publish:snap` and before submitting or updating the Snap via the [MetaMask Snaps Directory Information form](https://docs.metamask.io/snaps/how-to/get-allowlisted/#5-update-your-snap).
- **Scope:** Build, unit tests, Snap package contents, **all logos and images**, every RPC method, companion site cards, Send page, production-like test, allowlist checklist, and recommendations.
---
## 2. Prerequisites
### 2.1 MetaMask Flask (for full manual E2E)
- Install: https://metamask.io/flask/
- Use a **separate** browser profile or the Flask build as a separate extension so it does not conflict with regular MetaMask.
- Ensure Flask is unlocked and (optionally) create or import a test wallet you can use on Chain 138.
### 2.2 Token-aggregation API (for market data, swap quote, bridge, token list)
- **Local:** See [E2E_PREPARATION.md](../E2E_PREPARATION.md). Run from `smom-dbis-138/services/token-aggregation` (Node 20+, PostgreSQL if required). Default port **3000**. Verify: `curl http://localhost:3000/api/v1/networks` and `curl http://localhost:3000/api/v1/report/token-list?chainId=138`.
- **Staging/production:** Use a deployed base URL. Ensure CORS allows the Snap/site origin and all required endpoints respond (see E2E_PREPARATION.md §1). Run **`scripts/verify-snap-api-and-icons.sh [API_BASE_URL]`** to verify token list, networks, logoURIs, and iconUrls.
### 2.3 Companion site environment
- In `packages/site`: copy `.env.production.dist` to `.env` (dev) or `.env.production` (production build).
- Set **`GATSBY_SNAP_API_BASE_URL`** to the token-aggregation base URL (e.g. `http://localhost:3000` or `https://explorer.d-bis.org`). No trailing slash.
- For **production-like** test: set **`GATSBY_SNAP_ORIGIN=npm:chain138-snap`** so the site uses the published Snap (after it is on npm).
- Restart the dev server after changing env so Gatsby picks up the variables.
### 2.4 Optional but recommended
- A **real wallet** with a small balance on **Chain 138** (e.g. testnet ETH) to verify Send page and in-wallet display.
- **Deployed companion site** (e.g. https://explorer.d-bis.org/snap/) so you can test from a production URL and from a different origin (MetaMask “Connected sites”).
---
## 3. Build and unit tests
| Step | Command | What to verify |
| ------------------------ | ------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------- |
| Install deps | `pnpm install` | No peer/version errors. |
| Build | `pnpm run build` | Both `packages/snap` and `packages/site` build successfully. Snap manifest shasum is updated (mm-snap may report “fixed”). |
| Unit tests | `pnpm run test` | All Jest tests pass (Snap package). |
| Automated E2E (optional) | `npx playwright install` once, then `pnpm run test:e2e` | Playwright tests pass (site loads, Connect/Reconnect/Install visible). Does not drive MetaMask. |
| Lint | `pnpm run lint` | No ESLint/Prettier errors. |
**Snap package contents (must be present for publish):**
- [ ] `packages/snap/dist/bundle.js` — exists and non-empty.
- [ ] `packages/snap/images/icon.svg` — exists (referenced in `snap.manifest.json` as `iconPath`).
- [ ] `packages/snap/snap.manifest.json` — `version` matches `packages/snap/package.json`, `source.location.npm.packageName` is `chain138-snap`, `iconPath` is `images/icon.svg`.
- [ ] `packages/snap/package.json` — `files` includes `dist/`, `images/`, `snap.manifest.json`; `publishConfig.access` is `public` if publishing as public.
---
## 4. Logos and images — complete checklist
Nothing should be missing or broken. Verify each of the following.
### 4.1 Snap icon (MetaMask Snap list and detail)
| Item | Location | Check |
| ----------- | ------------------------------- | ------------------------------------------------------------------------------------------------------------- |
| Snap icon | `packages/snap/images/icon.svg` | File exists; referenced in `snap.manifest.json` → `source.location.npm.iconPath`. |
| In MetaMask | After installing the Snap | In Settings → Snaps, “Chain 138” shows the purple “138” icon (or your icon). Icon is clear and not pixelated. |
If you use a different format (e.g. PNG), ensure `iconPath` and `files` in package.json include it and the manifest points to the correct path.
### 4.2 Companion site assets
| Item | Location | Check |
| ------------------- | ---------------------------------------------------------------- | -------------------------------------------------------- |
| Site favicon / icon | `packages/site/gatsby-config.ts` → `icon: 'src/assets/logo.svg'` | File exists; build succeeds; browser tab shows the icon. |
| Header logo | `packages/site/src/components/Header.tsx` → `<SnapLogo />` | Logo renders in the header; no broken image. |
Ensure `src/assets/logo.svg` (or the path you use) exists. Add a favicon or apple-touch icon in Gatsby config if required for directory/submission.
### 4.3 Token list — logoURI (token-aggregation API)
The Snap and MetaMask token list depend on **`GET /api/v1/report/token-list`** returning Uniswap-style tokens with **`logoURI`** per token and a **list-level `logoURI`**.
| Check | How to verify |
| ----------------------- | --------------------------------------------------------------------------------------------------------------------------------------------- |
| List-level logoURI | `curl -s "${API_BASE}/api/v1/report/token-list?chainId=138" \| jq '.logoURI'` — present and URL is reachable (e.g. ETH or list logo). |
| Every token has logoURI | `curl -s "${API_BASE}/api/v1/report/token-list?chainId=138" \| jq '.tokens[] \| {symbol, logoURI}'` — no token has null or missing `logoURI`. |
| URLs resolve | For each distinct `logoURI` in the response, open in browser or `curl -sI <url>` — expect 200 (or 301/302 to a valid asset). |
**Token-aggregation source:** In `smom-dbis-138/services/token-aggregation`, `src/config/canonical-tokens.ts` defines `LOGO_BY_SYMBOL` and `getLogoUriForSpec()`. Defaults use Trust Wallet assets and ethereum.org ETH diamond. For Chain 138–specific tokens, set `logoUrl` on the spec or ensure they fall back to a sensible default (e.g. ETH_LOGO). Add any new token symbols to `LOGO_BY_SYMBOL` or give them a `logoUrl` so no token is missing a logo.
### 4.4 Network icons (iconUrls) — token-aggregation API
**`GET /api/v1/networks`** must return each network with **`iconUrls`** (array of URLs) so wallets can show chain icons.
| Chain | Expected iconUrls (examples) | Verify |
| ---------------------- | ----------------------------------------------------------------------------------- | -------------------------------------------------- |
| Chain 138 (0x8a) | `https://explorer.d-bis.org/favicon.ico`, ETH diamond or similar | Each URL returns 200 (or redirect to valid image). |
| Ethereum Mainnet (0x1) | `https://raw.githubusercontent.com/ethereum/ethereum.org/.../eth-diamond-black.png` | URL reachable. |
| ALL Mainnet (651940) | `https://alltra.global/favicon.ico`, ETH diamond or similar | URL reachable. |
**Token-aggregation source:** `smom-dbis-138/services/token-aggregation/src/config/networks.ts` — each entry in `NETWORKS` has `iconUrls`. Ensure:
- [ ] `explorer.d-bis.org/favicon.ico` exists (explorer site serves a favicon).
- [ ] `alltra.global/favicon.ico` exists (or update to a valid URL).
- [ ] Any raw GitHub or CDN URLs (ethereum.org, Trust Wallet assets) are still valid and not 404.
### 4.5 Suggested screenshot list (for allowlist and docs)
Capture and keep for submission and `docs/images/`:
| File | Content |
| -------------------------- | ----------------------------------------------------------------- |
| `connect.png` | Companion site with Connect / Install Flask / Reconnect visible. |
| `market-data-dialog.png` | Snap dialog from “Show market data” (tokens + prices). |
| `bridge-routes-dialog.png` | Snap dialog from “Show bridge routes” (CCIP + Trustless). |
| `swap-quote-dialog.png` | Snap dialog from “Show quote in Snap”. |
| `dynamic-info-dialog.png` | Snap dialog from `show_dynamic_info` (networks + token list URL). |
| `send-page.png` | Send on Chain 138 page (network switch + send form). |
See [FEATURES.md](FEATURES.md) “Screenshots and visuals” and [ALLOWLIST_FORM_FIELDS.md](../ALLOWLIST_FORM_FIELDS.md) “Images”.
---
## 5. RPC methods — full verification table
Test each method (e.g. via browser console `wallet_invokeSnap` from the companion site origin). Use **local** Snap ID for dev (`local:http://localhost:8000` or the URL your dev server uses) or **npm** for production-like (`npm:chain138-snap`).
| Method | Params (required / optional) | Expected | Verify |
| ---------------------------- | ------------------------------------------------------------------- | ----------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------- |
| `hello` | — | `{ message: "Hello, …" }` | No error; message contains “Chain 138” or similar. |
| `get_networks` | `apiBaseUrl` or `networksUrl` | `{ version, networks: [ … ] }` with EIP-3085 entries for 138, 1, 651940 | Each network has `chainId`, `rpcUrls`, `nativeCurrency`, `blockExplorerUrls`; **iconUrls** present and URLs reachable. |
| `get_chain138_config` | `apiBaseUrl` or `networksUrl` | Single Chain 138 config object | Matches your chain (e.g. DeFi Oracle Meta Mainnet, RPCs, explorer). |
| `get_chain138_market_chains` | `apiBaseUrl` | `{ chains: [ … ] }` | At least Chain 138; names and explorer URLs correct. |
| `get_token_list_url` | `apiBaseUrl` or `tokenListUrl` | `{ tokenListUrl, description }` | URL is your API’s token-list endpoint (e.g. `…/api/v1/report/token-list`). |
| `get_token_list` | `apiBaseUrl` or `tokenListUrl`; optional `chainId` | `{ tokens: [ … ] }` (Uniswap-style) | Each token has **logoURI**; list usable as MetaMask token list. |
| `get_oracles` | `apiBaseUrl`; optional `chainId` | `{ version, chains: [ … oracles ] }` | Oracles for 138 (and others) if configured. |
| `show_dynamic_info` | `apiBaseUrl` or `networksUrl` / `tokenListUrl` | MetaMask dialog | Dialog shows networks and token list URL; no “pass apiBaseUrl” error. |
| `get_market_summary` | `apiBaseUrl`; optional `chainId` | `{ tokens: [ { symbol, name, address, market?: { priceUsd, volume24h } } ] }` | Tokens and optional prices; no error or empty when API is up. |
| `show_market_data` | `apiBaseUrl`; optional `chainId` | MetaMask dialog | “Market data (Chain 138)” (or chosen chain) with token symbols and prices. |
| `get_bridge_routes` | `apiBaseUrl` or `bridgeListUrl` | `{ routes, chain138Bridges?, … }` | CCIP (WETH9/WETH10) and, if configured, Trustless routes. |
| `show_bridge_routes` | `apiBaseUrl` or `bridgeListUrl` | MetaMask dialog | Dialog lists bridge routes. |
| `get_swap_quote` | `apiBaseUrl`, `tokenIn`, `tokenOut`, `amountIn`; optional `chainId` | `{ amountOut?, error?, poolAddress? }` | When pool exists: `amountOut` present; when not: `error` or null amountOut. |
| `show_swap_quote` | Same as `get_swap_quote` | MetaMask dialog | Dialog shows quote or “no quote” message. |
**Error cases to test:**
- [ ] `get_networks` without `apiBaseUrl` and without `networksUrl`: returns error message asking for params.
- [ ] `get_market_summary` with invalid or down API: returns `{ error, tokens: [] }` or similar; no uncaught exception.
- [ ] `show_*` methods without `apiBaseUrl` (when required): dialog or alert asks user to pass `apiBaseUrl`.
---
## 6. Companion site — every card and page
### 6.1 Home page (index)
| Element | Check |
| ----------------------------------- | -------------------------------------------------------------------------------------------------------------------------------- |
| Connect / Install Flask / Reconnect | Correct button or link visible; clicking triggers MetaMask. |
| “Add Chain 138” / network card | If present, invoking Snap to add network works. |
| **Market data** card | “Show market data” opens Snap dialog; “Fetch market summary” shows tokens/prices below (when `GATSBY_SNAP_API_BASE_URL` is set). |
| **Bridge** card | “Show bridge routes” opens Snap dialog with routes. |
| **Swap quote** card | Enter token In/Out (addresses) and amount; “Get quote” shows amountOut (or error); “Show quote in Snap” opens dialog. |
| Notice / Send link | Link to “Send on Chain 138” is present and correct (e.g. `./send` or `/send`). |
| Footer | Version or build info if configured; no broken links. |
If `GATSBY_SNAP_API_BASE_URL` is not set, Market/Bridge/Swap cards should show a clear message (e.g. “Set GATSBY_SNAP_API_BASE_URL”) instead of failing silently.
### 6.2 Send page (`/send`)
| Step | Check |
| --------------------- | ------------------------------------------------------------------------------------------------------------------------- |
| Navigate | Open `/send` (or path under your pathPrefix, e.g. `/snap/send`). Page loads. |
| “Switch to Chain 138” | Click; MetaMask prompts to add/switch network; after approval, message confirms “Switched to Chain 138.” |
| Send form | Enter recipient address and amount. |
| Send transaction | Submit; MetaMask shows tx confirmation; after approval, tx is sent on Chain 138 and message or link to explorer is shown. |
| Back link | “Back to Chain 138 Snap” (or similar) returns to home. |
Use a test wallet with a small balance on Chain 138 to avoid real funds at risk.
---
## 7. Production-like test
Before publishing (or after publishing a version you intend to allowlist):
1. **Publish to npm** (or use the latest published version): `pnpm run publish:snap` (see [PUSH_AND_PUBLISH.md](../PUSH_AND_PUBLISH.md)).
2. **Build companion site with npm Snap:** Set `GATSBY_SNAP_ORIGIN=npm:chain138-snap` and `GATSBY_SNAP_API_BASE_URL` to your **production** token-aggregation URL (e.g. `https://explorer.d-bis.org` if API is proxied there). Build and serve (or deploy).
3. **Clean MetaMask Flask:** Remove the Snap if it was installed from local; optionally use a fresh profile.
4. **Install from production site:** Open the deployed companion site (e.g. https://explorer.d-bis.org/snap/). Connect and install the Snap — it should install from **npm** (no localhost). Verify Snap appears in Settings → Snaps as “Chain 138” with correct icon.
5. **Run through:** Repeat the RPC checks and companion site cards using the **production** API. Confirm market data, bridge, and swap quote work when the production API is up.
6. **Connected site:** In Snap settings, confirm the companion site origin is listed under “Connected sites” and can invoke the Snap.
---
## 8. Allowlist and directory submission
If you are submitting or updating the Snap in the MetaMask directory:
- [ ] Use [ALLOWLIST_FORM_FIELDS.md](../ALLOWLIST_FORM_FIELDS.md) for exact field values (Snap name, repo, npm, **version**).
- [ ] **Version:** Must match `packages/snap/package.json` and `snap.manifest.json` (e.g. 0.1.2).
- [ ] **Images:** Upload screenshots as required (companion site, Snap dialogs — see §4.5).
- [ ] **Demo video (optional):** Short walkthrough of install and use (Connect, add network, market data, bridge, swap quote, Send page).
- [ ] **Compliance:** [ALLOWLIST_SOURCE_AND_COMPLIANCE_CHECKLIST.md](../ALLOWLIST_SOURCE_AND_COMPLIANCE_CHECKLIST.md) — repo public, no key-management APIs, etc.
---
## 9. Recommendations and suggestions
- **Snapper / security:** If available, run [Snapper](https://docs.metamask.io/snaps/how-to/get-allowlisted/) (or the MetaMask security scanner) locally before publish.
- **Real wallet on Chain 138:** Test with a wallet that has a small balance on Chain 138 so in-wallet balance and the Send page reflect real behavior (and so you can verify token list and network icons in MetaMask).
- **Deployed companion site:** Test the full flow from the **deployed** companion site (e.g. https://explorer.d-bis.org/snap/) and from a different origin to confirm CORS and “Connected sites” behavior.
- **API health:** Before a release, confirm token-aggregation (or your API) is up and that `/api/v1/networks`, `/api/v1/report/token-list`, `/api/v1/bridge/routes`, `/api/v1/quote`, and `/api/v1/tokens` respond as expected. Document any env (e.g. `NETWORKS_JSON_URL`, `TOKEN_LIST_JSON_URL`) so operators can run the same checks.
- **Changelog / version:** Keep a short changelog (e.g. in README or CHANGELOG.md) and bump version deliberately; note any breaking changes for integrators (e.g. `apiBaseUrl` requirement).
- **Token list and logos:** When adding new tokens to the token-aggregation canonical list, always set **logoURI** (or `logoUrl` in spec) so MetaMask and the Snap never show a token without a logo.
- **Network icons:** When adding or changing chains in token-aggregation `networks.ts`, always set **iconUrls** and ensure URLs are stable and reachable (favicon or official chain logo).
---
## 10. Final sign-off checklist (before publish)
Use this as a single pass/fail before `pnpm run publish:snap`.
**Automatable (run `bash scripts/verify-pre-publish.sh`):** Build, unit tests, package contents, manifest/package version, Prettier check. Optional: `pnpm run test:e2e` (set `SKIP_E2E=1` to skip).
- [ ] **Build:** `pnpm run build` succeeds; manifest shasum is correct.
- [ ] **Tests:** `pnpm run test` passes; `pnpm run lint:misc --check` (Prettier) passes. *(Full `pnpm run lint` includes ESLint; repo may have existing ESLint rule warnings.)*
- [ ] **Snap package:** `dist/bundle.js`, `images/icon.svg`, `snap.manifest.json` present; `package.json` version and `files` correct.
- [ ] **Snap icon:** Icon displays correctly in MetaMask Snap list/detail.
- [ ] **Token list:** Every token from `/api/v1/report/token-list` has a valid **logoURI**; list-level logoURI set.
- [ ] **Networks:** Each network from `/api/v1/networks` has **iconUrls**; all URLs reachable.
- [ ] **RPC methods:** All methods in §5 tested; success and error paths as expected.
- [ ] **Companion site:** All cards (Market, Bridge, Swap) and Send page tested; links and messages correct.
- [ ] **Production-like:** Installed from npm and tested with production API (if applicable).
- [ ] **Allowlist:** If submitting/updating directory, form fields and screenshots ready (§8).
When all items are checked, the Snap is ready for publish and (optionally) directory submission.
---
**Related docs**
- **Script:** `scripts/verify-pre-publish.sh` — runs build, test, package contents, version check, Prettier. Use before publish.
- [TESTING_INSTRUCTIONS.md](../TESTING_INSTRUCTIONS.md) — RPC examples and E2E checklist.
- [E2E_PREPARATION.md](../E2E_PREPARATION.md) — Token-aggregation and env setup.
- [MANUAL_E2E_CHECKLIST.md](../MANUAL_E2E_CHECKLIST.md) — Short manual checklist.
- [CHAIN138_SNAP_TROUBLESHOOTING.md](CHAIN138_SNAP_TROUBLESHOOTING.md) — Balance, swap, and API issues.
- [PUSH_AND_PUBLISH.md](../PUSH_AND_PUBLISH.md) — Version bump and npm publish.
- [ALLOWLIST_FORM_FIELDS.md](../ALLOWLIST_FORM_FIELDS.md) — Directory form and images.

38
chain138-snap/docs/README.md Normal file
View File

@@ -0,0 +1,38 @@
# Chain 138 Snap — Documentation index
Documentation for the **Chain 138 Snap** (MetaMask): network params, token list, market data, swap quotes, and CCIP and Trustless bridge routes for Chain 138 and ALL Mainnet.
## Quick links
| Doc | Description |
| ---------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------- |
| [FEATURES.md](FEATURES.md) | **All RPC methods and features** — method matrix, params, response shapes, blockchains (138 + 651940), flow diagram |
| [CONTRIBUTING.md](CONTRIBUTING.md) | How to contribute: setup, testing, linting, publishing |
| [FAQ.md](FAQ.md) | Frequently asked questions about the Snap |
| [DEPLOY_COMPANION_SITE.md](DEPLOY_COMPANION_SITE.md) | Build and deploy the companion site to your own host |
| [RUNBOOK.md](RUNBOOK.md) | Build, test, publish quick reference |
## Root-level docs (repo root)
| Doc | Description |
| -------------------------------------------------------------------------------------------- | ----------------------------------------------------------- |
| [README](../README.md) | Project overview, getting started |
| [INTEGRATORS](../INTEGRATORS.md) | Integrator guide: Snap ID, apiBaseUrl, RPC methods |
| [TESTING_INSTRUCTIONS](../TESTING_INSTRUCTIONS.md) | Full testing guide: dev server, RPC examples, E2E checklist |
| [E2E_PREPARATION](../E2E_PREPARATION.md) | Token-aggregation and companion site setup for E2E |
| [MANUAL_E2E_CHECKLIST](../MANUAL_E2E_CHECKLIST.md) | Short manual E2E checklist |
| [PUSH_AND_PUBLISH](../PUSH_AND_PUBLISH.md) | Push to GitHub, publish to npm, allowlist |
| [PACKAGE_MANAGER](../PACKAGE_MANAGER.md) | pnpm vs Yarn |
| [SECURITY](../SECURITY.md) | Security notes: HTTPS, API, permissions |
| [ALLOWLIST_FORM_FIELDS](../ALLOWLIST_FORM_FIELDS.md) | MetaMask allowlist form fields |
| [ALLOWLIST_SOURCE_AND_COMPLIANCE_CHECKLIST](../ALLOWLIST_SOURCE_AND_COMPLIANCE_CHECKLIST.md) | Allowlist compliance checklist |
| [NEXT_STEPS](../NEXT_STEPS.md) | Completed items and future releases |
## Visual elements
- **Feature overview and method matrix:** [FEATURES.md](FEATURES.md) includes ASCII feature overview, RPC method matrix (all methods × Chain 138 / ALL Mainnet × params × UI), and a Mermaid request-flow diagram.
- **Screenshots:** Optional screenshots (Connect UI, market data dialog, bridge dialog, swap quote dialog) can be added under [docs/images/](images/). See the "Screenshots and visuals" section in [FEATURES.md](FEATURES.md) for suggested filenames.
## Snap package (npm)
The published Snap package has its own README on npm; a copy lives in [packages/snap/README.md](../packages/snap/README.md).

45
chain138-snap/docs/RUNBOOK.md Normal file
View File

@@ -0,0 +1,45 @@
# Chain 138 Snap — Runbook
Quick reference for building, testing, and publishing the Snap and companion site.
## Build
```bash
# Snap + site
pnpm run build
# Companion site only (e.g. for deploy)
GATSBY_PATH_PREFIX=/snap pnpm --filter site run build
# With production API:
# GATSBY_SNAP_API_BASE_URL=https://your-token-aggregation-api.com
```
## Test
```bash
pnpm run test # Snap unit tests (Jest)
pnpm run test:e2e # Playwright E2E (companion site)
pnpm run lint # ESLint + Prettier
```
## Publish Snap to npm
From repo root:
```bash
pnpm run build
pnpm run publish:snap # uses NPM_ACCESS_TOKEN from .env if set
```
See [PUSH_AND_PUBLISH.md](../PUSH_AND_PUBLISH.md).
## Deploy companion site
Build with path prefix and API URL, then upload `packages/site/public/` to your static host. See [DEPLOY_COMPANION_SITE.md](DEPLOY_COMPANION_SITE.md).
## Validate token/list URLs
```bash
./scripts/validate-token-lists.sh [URL1] [URL2] ...
# Or set TOKEN_LIST_JSON_URL, BRIDGE_LIST_JSON_URL, NETWORKS_JSON_URL
```

67
chain138-snap/docs/TOKEN_LIST_AND_ICONS_GUIDE.md Normal file
View File

@@ -0,0 +1,67 @@
# Chain 138 Snap — Token List and Icons Guide
How to display tokens and icons in MetaMask when using the Chain 138 Snap.
---
## Why tokens and icons may not show
- **Chain 138 is not in MetaMask’s built-in token detection.** MetaMask only auto-detects tokens on Ethereum, Polygon, Arbitrum, Optimism, Base, zkSync, etc. Chain 138 and ALL Mainnet (651940) are custom chains, so you must add the token list or import tokens manually.
- **Icons come from the token list.** Each token needs a `logoURI` and each network needs `iconUrls`. If those URLs are missing or unreachable, MetaMask shows no icons.
---
## Step 1: Get the token list URL
1. Open the Snap companion site (e.g. https://explorer.d-bis.org/snap/).
2. Connect MetaMask (or MetaMask Flask) and install the Chain 138 Snap.
3. Click **"Show dynamic info"**.
4. The Snap dialog shows the **Token list URL** (e.g. `https://explorer.d-bis.org/api/v1/report/token-list`).
---
## Step 2: Add the token list in MetaMask
### If MetaMask supports custom token list URLs
- Go to **Settings → Security & Privacy** (or equivalent).
- Find **Token list** and add the URL from Step 1.
- MetaMask will fetch the list and display tokens with icons when you switch to Chain 138 or ALL Mainnet.
### If MetaMask does not support custom token list URLs
Add tokens manually:
1. Switch to Chain 138 in MetaMask.
2. Go to **Tokens** tab → **Import tokens** (or the plus button).
3. Select **Custom token**.
4. Enter the token contract address (see [CHAIN138_TOKEN_ADDRESSES](../../../docs/11-references/CHAIN138_TOKEN_ADDRESSES.md) for cUSDC, cUSDT, etc.).
5. MetaMask will fill symbol and decimals. Click **Import**.
---
## Step 3: Verify icons
If tokens show but icons are missing:
- **Token icons:** The token-aggregation API (`GET /api/v1/report/token-list`) must return a `logoURI` for each token. Operators: see [PRE_PUBLISH_TESTING.md](PRE_PUBLISH_TESTING.md) §4.3.
- **Network icons:** The networks API (`GET /api/v1/networks`) must return `iconUrls` for each chain. Operators: see [PRE_PUBLISH_TESTING.md](PRE_PUBLISH_TESTING.md) §4.4.
- **Logo URLs:** If logo URLs (e.g. raw.githubusercontent.com) are blocked or return 404, operators can host logos locally and update the token-aggregation config.
---
## Operators: verify API and icons
Run the verification script to check token list, networks, logoURIs, and iconUrls:
```bash
./scripts/verify-snap-api-and-icons.sh [API_BASE_URL]
# Example: ./scripts/verify-snap-api-and-icons.sh https://explorer.d-bis.org
```
---
## Related docs
- [CHAIN138_SNAP_TROUBLESHOOTING.md](CHAIN138_SNAP_TROUBLESHOOTING.md) — §6 No icons or tokens showing
- [PRE_PUBLISH_TESTING.md](PRE_PUBLISH_TESTING.md) — §4.3 Token list logoURI, §4.4 Network iconUrls

1
chain138-snap/docs/images/.gitkeep Normal file
View File

@@ -0,0 +1 @@
# Add screenshots here: connect.png, market-data-dialog.png, bridge-routes-dialog.png, swap-quote-dialog.png, dynamic-info-dialog.png (see docs/FEATURES.md)