smom-dbis-138/docs/operations/integrations/METAMASK_PORTFOLIO.md

# MetaMask Portfolio Compatibility for ChainID 138

Guide for MetaMask Portfolio compatibility with ChainID 138.

## Current Status

ChainID 138 is **not** currently supported in MetaMask Portfolio's native features (Swaps, Bridge, Buy/Sell). However, read-only features (balances, token display) may work if token metadata is properly configured.

## Portfolio Read-Only Features

### Token Auto-Detection

MetaMask Portfolio can auto-detect tokens when they appear on **2+ reputable token lists**. To enable auto-detection:

1. **Official Token List**: Maintain an official token list for ChainID 138
2. **Token List Inclusion**: Submit token list to reputable aggregators:
   - CoinGecko Token Lists
   - Uniswap Token Lists
   - Other major DEX token lists
3. **Explorer Metadata**: Ensure Blockscout returns standard ERC-20 metadata endpoints

### Balance Visibility

Portfolio can display token balances if:

- Token metadata is available on token lists
- Explorer returns standard ERC-20 metadata
- Token contract implements standard ERC-20 interface
- Token balances are queryable via RPC

### Token Symbols and Logos

Portfolio displays token symbols and logos from:

- Token lists (primary source)
- Explorer metadata (fallback)
- Contract metadata (if available)

## CAIP-2 Identifier

ChainID 138 uses the CAIP-2 identifier: `eip155:138`

This identifier is used by:
- Portfolio for chain identification
- Token lists for chain-specific tokens
- Indexers for chain-specific data

## Blockscout Integration

### Required API Endpoints

Blockscout must provide these endpoints for Portfolio compatibility:

1. **Token Metadata**: `/api/v2/tokens/{address}`
   - Returns: name, symbol, decimals, total_supply
   
2. **Token Holders**: `/api/v2/tokens/{address}/holders`
   - Returns: list of token holders
   
3. **Token Transfers**: `/api/v2/tokens/{address}/transfers`
   - Returns: token transfer history

### CORS Configuration

Blockscout must allow CORS requests from Portfolio:

```
Access-Control-Allow-Origin: https://portfolio.metamask.io
Access-Control-Allow-Methods: GET, OPTIONS
Access-Control-Allow-Headers: Content-Type
```

### Token Logo Serving

Token logos should be served from Blockscout or CDN:

- URL format: `https://explorer.d-bis.org/images/tokens/{address}.png`
- Fallback: Token logo from token list
- Standard: 512x512 PNG format

## Token List Requirements

### Official Token List

The official token list for ChainID 138 must:

1. **Follow Token Lists Schema**: Use Uniswap Token Lists JSON schema
2. **Include All Tokens**: Include all ecosystem tokens
3. **Provide Logos**: Include logo URLs for all tokens
4. **Maintain Accuracy**: Keep token metadata up to date
5. **Host Publicly**: Host on public URL (HTTPS)

### Token List Submission

Submit token list to:

1. **CoinGecko**: For token discovery
2. **Uniswap**: For DEX integration
3. **Other Aggregators**: For wider reach

## Limitations

### Not Supported (Requires MetaMask Partnership)

- **Swaps**: In-wallet swap aggregator
- **Bridge**: Portfolio Bridge integration
- **Buy/Sell**: Fiat on/off-ramps
- **Advanced Charts**: Market data and charts
- **Full Portfolio Features**: Complete portfolio functionality

### Supported (Read-Only)

- **Token Balances**: Display token balances
- **Token Symbols**: Display token symbols
- **Token Logos**: Display token logos
- **Transaction History**: View transaction history (via explorer)
- **Account Overview**: Basic account information

## Testing Portfolio Compatibility

### Checklist

- [ ] Token list is publicly accessible
- [ ] Token list follows Token Lists schema
- [ ] Token logos are accessible
- [ ] Blockscout API endpoints work
- [ ] CORS headers are configured
- [ ] Token metadata is accurate
- [ ] Token balances are queryable
- [ ] CAIP-2 identifier is used correctly

### Test Steps

1. **Add Network**: Add ChainID 138 to MetaMask
2. **Add Tokens**: Add tokens to MetaMask
3. **Check Portfolio**: Open MetaMask Portfolio
4. **Verify Balances**: Check if token balances display
5. **Verify Symbols**: Check if token symbols display
6. **Verify Logos**: Check if token logos display
7. **Test Explorer**: Verify explorer links work

## Future Integration

### Path to Full Support

To enable full Portfolio features:

1. **Business Development**: Engage with Consensys for partnership
2. **Liquidity Requirements**: Ensure sufficient liquidity for swaps
3. **Bridge Integration**: Integrate with bridge providers
4. **On-Ramp Partners**: Partner with fiat on/ramp providers
5. **Regulatory Compliance**: Ensure regulatory compliance

### Tracking

- Monitor MetaMask Portfolio updates
- Track network support announcements
- Engage with Consensys for integration
- Submit feature requests

## References

- [MetaMask Portfolio](https://portfolio.metamask.io)
- [Token Lists](https://tokenlists.org)
- [CAIP-2](https://github.com/ChainAgnostic/CAIPs/blob/master/CAIPs/caip-2.md)
- [Blockscout API](https://docs.blockscout.com/for-developers/api)