# MetaMask Multi-Chain Provider

Connect **MetaMask** and other Web3 providers to **ChainID 138** (DeFi Oracle Meta Mainnet), **Ethereum Mainnet** (1), and **ALL Mainnet** (651940). Includes chain configs, combined token list, and oracle helpers so tokens and price feeds work across chains.

## Features

- **Multi-chain**: Add and switch between Chain 138, Ethereum Mainnet, and ALL Mainnet in one flow.
- **Token list**: All tokens from all three chains (Chain 138: WETH, WETH10, cUSDT, cUSDC, ETH/USD oracle; Mainnet: WETH, USDT, USDC, DAI, ETH/USD oracle; ALL Mainnet: USDC).
- **Oracles**: Read ETH/USD from Chain 138 oracle and from Chainlink on Mainnet so dApps can display USD values.

## Installation

Use as a local module (no publish required):

```bash
# From your app (e.g. metamask-integration/examples/react-example)
npm install ethers   # peer dependency for getEthUsdPrice
```

Import from the provider path:

```javascript
import { addChainsToWallet, switchChain, getEthUsdPrice, getTokensByChain } from '../provider/index.js'
```

Or copy the `provider/` folder into your project and import from `./provider`.

## Quick Start

### 1. Add both chains to MetaMask

```javascript
import { addChainsToWallet } from './provider/index.js'

const ethereum = window.ethereum
if (ethereum) {
  const result = await addChainsToWallet(ethereum)
  console.log('Added:', result.added, 'Skipped:', result.skipped, 'Errors:', result.errors)
}
```

### 2. Switch chain

```javascript
import { switchChain, ensureChain } from './provider/index.js'

await switchChain(window.ethereum, 138)   // DeFi Oracle Meta Mainnet
await switchChain(window.ethereum, 1)     // Ethereum Mainnet

// Or ensure current chain (switch if needed, add if missing)
await ensureChain(window.ethereum, 138)
```

### 3. Add a token to the wallet

```javascript
import { addTokenToWallet, getToken, getTokensByChain } from './provider/index.js'

const tokens138 = getTokensByChain(138)
for (const token of tokens138) {
  if (token.tags?.includes('oracle')) continue
  await addTokenToWallet(window.ethereum, token)
}

// Or a single token by address
const weth = getToken(138, '0xC02aaA39b223FE8D0A0e5C4F27eAD9083C756Cc2')
if (weth) await addTokenToWallet(window.ethereum, weth)
```

### 4. Read oracle price (ETH/USD)

Requires `ethers` v6. Works on both Chain 138 and Mainnet.

```javascript
import { ethers } from 'ethers'
import { getEthUsdPrice } from './provider/index.js'

const provider = new ethers.BrowserProvider(window.ethereum)
const chainId = (await provider.getNetwork()).chainId

const result = await getEthUsdPrice(provider, Number(chainId))
if (result) {
  console.log('ETH/USD:', result.price, 'Updated:', result.updatedAt)
}
```

## API

| Export | Description |
|--------|-------------|
| `CHAINS`, `CHAIN_138`, `CHAIN_MAINNET` | Chain params for `wallet_addEthereumChain` |
| `getChainById(chainIdDecimal)`, `getChainByHex(chainIdHex)` | Look up chain config |
| `addChainsToWallet(ethereum, options?)` | Add Chain 138 and/or Mainnet |
| `switchChain(ethereum, chainIdDecimal)` | Switch to chain (adds if missing) |
| `ensureChain(ethereum, chainIdDecimal)` | Switch to chain if not already on it |
| `addTokenToWallet(ethereum, token)` | Add token via `wallet_watchAsset` |
| `TOKEN_LIST`, `getTokensByChain(chainId)`, `getToken(chainId, address)` | Token list for both chains |
| `TOKEN_LIST_URL` | URL/path to host the combined token list JSON |
| `getEthUsdPrice(provider, chainId)` | Read ETH/USD from oracle (needs ethers) |
| `ORACLES_CHAIN_138`, `ORACLES_MAINNET`, `getOracleConfig(chainId)` | Oracle addresses and config |

## Config files

- **Networks**: `docs/04-configuration/metamask/DUAL_CHAIN_NETWORKS.json` — both chain params.
- **Token list**: `docs/04-configuration/metamask/DUAL_CHAIN_TOKEN_LIST.tokenlist.json` — tokens for Chain 138 and Mainnet.

Host the token list at a public URL and set your app’s token list URL to it so MetaMask can fetch the list (or use the inline `TOKEN_LIST` / `getTokensByChain` in your UI).

## Downloads

| Asset | In-repo path | Use |
|-------|--------------|-----|
| **Multi-chain networks** | `docs/04-configuration/metamask/DUAL_CHAIN_NETWORKS.json` | `wallet_addEthereumChain` params for Chain 138, Ethereum Mainnet, and ALL Mainnet. If bundled: `config/DUAL_CHAIN_NETWORKS.json`. |
| **Dual-chain token list** | `docs/04-configuration/metamask/DUAL_CHAIN_TOKEN_LIST.tokenlist.json` | MetaMask token list URL; Uniswap token list format. If bundled: `config/DUAL_CHAIN_TOKEN_LIST.tokenlist.json`. **Hosted:** `https://explorer.d-bis.org/api/config/token-list` (explorer API). `TOKEN_LIST_URL` in code points to this by default. |
| **Feature parity and recommendations** | `docs/04-configuration/metamask/METAMASK_CHAIN138_FEATURE_PARITY_ANALYSIS.md` | Plugin/snap requirements, gaps, and build/integration options. |
| **Oracle and pricing** | `docs/04-configuration/metamask/ORACLE_PRICE_FEED_SETUP.md`, `WETH_ORACLE_QUICK_REFERENCE.md` | Oracle addresses and Oracle Publisher setup. |
| **Token-aggregation REST API** | `smom-dbis-138/services/token-aggregation/docs/REST_API_REFERENCE.md` | Tokens, pools, prices, volume, OHLCV for Chain 138 and ALL Mainnet (discovery without CMC/CoinGecko). |
| **Optional next steps** | `docs/04-configuration/metamask/METAMASK_CHAIN138_FEATURE_PARITY_ANALYSIS.md` §7, `SNAP_IMPLEMENTATION_ROADMAP.md` | Custom Snap roadmap, CoinGecko submission, Consensys outreach. |

## Oracles

- **Chain 138**: ETH/USD at `0x3304b747e565a97ec8ac220b0b6a1f6ffdb837e6` (8 decimals). Keep the Oracle Publisher service running so the feed stays updated.
- **Ethereum Mainnet**: Chainlink ETH/USD at `0x5f4eC3Df9cbd43714FE2740f5E3616155c5b8419`.

MetaMask does not read these oracles by default; use `getEthUsdPrice(provider, chainId)` in your dApp to show USD values.

## License

MIT