Skip to content

CONTRIBUTING.md

Latest commit

 

History

History
197 lines (140 loc) · 6.17 KB

CONTRIBUTING.md

File metadata and controls

197 lines (140 loc) · 6.17 KB

Contributing to Monad Token List

Thank you for your interest in contributing to the Monad Token List! This guide will walk you through the process of adding a new token to the repository.

Prerequisites

Before you begin, make sure you have:

  • Python 3.10 or higher installed on your system
  • uv (a Python package installer and resolver)
  • Access to a Monad RPC endpoint

Token Requirements

To be added to the Monad Token List, your token must meet the following requirements:

  • Deployed on Monad Mainnet
  • ERC20-compliant
  • Decimals (must be between 6 and 36)
  • Logo file (must provide a logo in SVG or PNG format)
  • Directory naming (the directory name must exactly match the token symbol)

Step-by-Step Guide

1. Fork and Clone the Repository

Fork this repository to your GitHub account, then clone it locally:

git clone https://github.com/YOUR_USERNAME/token-list.git
cd token-list

2. Install Dependencies

Install the required Python dependencies using uv:

uv sync

3. Configure Environment

Create a .env file in the root directory with your Monad RPC URL if you don't want to use the default RPC:

echo "MONAD_RPC_URL=https://your-monad-rpc-endpoint" > .env

Replace https://your-monad-rpc-endpoint with your actual RPC URL.

4. Run the Add Token Script

Use the add_token.py script to automatically fetch token information from the blockchain:

# With token address as argument
uv run python scripts/add_token.py 0xYourTokenAddress

# Or run interactively (you'll be prompted for the address)
uv run python scripts/add_token.py

# With token address as argument and custom RPC
uv run --env-file=.env python scripts/add_token.py 0xYourTokenAddress

The script will generate a data.json file with the token metadata.

5. Add a Logo File

After the script completes, you need to manually add a logo file to the token's directory:

# Navigate to the token directory (replace SYMBOL with your token's symbol)
cd mainnet/SYMBOL/

# Add your logo file (either SVG or PNG format)
# The file must be named exactly "logo.svg" or "logo.png"

Logo Requirements:

  • File name must be exactly logo.svg or logo.png
  • Preferably use SVG format for scalability
  • Image should be square (1:1 aspect ratio)
  • Minimum dimensions: min 200x200 pixels, preferably 256x256
  • Optimized for web display (keep file size reasonable)

6. Validate Your Token

Before submitting your changes, run the validation script to ensure everything is correct:

uv run python scripts/validate_tokens.py

7. Commit and Create Pull Request

Once validation passes, commit your changes and create a pull request on GitHub with:

  • A clear title (e.g., "Add SYMBOL token")
  • Description including the token contract address
  • Any additional relevant information about the token

Note: The token list file (tokenlist-mainnet.json) is automatically regenerated by a GitHub Action when your PR is merged. You don't need to run generate_token_list_file.py manually or include changes to this file in your PR.

Data Format

The data.json file contains the following fields:

{
  "chainId": 143,
  "address": "0xYourTokenAddress",
  "name": "Token Name",
  "symbol": "TKN",
  "decimals": 18,
  "extensions": {
    "coinGeckoId": "token-id",
    "bridgeInfo": {
      "protocol": "bridge-protocol",
      "bridgeAddress": "0xTokenBridgeAddress"
    }
  }
}

Required Fields

  • chainId: Always 143 for Monad Mainnet
  • address: The token's contract address (checksummed)
  • name: The full name of the token (must match the on-chain name() value)
  • symbol: The token symbol (must match the on-chain symbol() value and directory name)
  • decimals: The number of decimal places the token uses (must match the on-chain decimals() value)

Optional Fields

  • extensions: Additional metadata about the token
    • coinGeckoId: The CoinGecko API ID for the token (if listed on CoinGecko)
    • bridgeInfo: Bridge information for bridged tokens
    • crossChainAddresses: Token addresses on other chains (see below)

Cross-Chain Addresses

If your token exists on other chains, you can include those addresses to help with cross-chain token identification and bridging:

{
  "extensions": {
    "crossChainAddresses": {
      "1": {
        "address": "0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48"
      },
      "56": {
        "address": "0x8AC76a51cc950d9822D68b83fE1Ad97B32Cd580d",
        "decimals": 18
      },
      "8453": {
        "address": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913"
      }
    }
  }
}

Chain ID Reference:

Supported Chain ID Network
1 Ethereum Mainnet
10 Optimism
56 BNB Chain
137 Polygon
999 HyperEVM
8453 Base
9745 Plasma
42161 Arbitrum One
42220 Celo
43114 Avalanche C-Chain

Fields per chain entry:

  • address (required): The token contract address on that chain
  • symbol (optional): Expected symbol on this chain if it differs from the Monad token's symbol
  • decimals (optional): Expected decimals on this chain if they differ from the Monad token's decimals

Overrides: Some tokens have different metadata across chains. Use symbol or decimals overrides when the cross-chain token's on-chain values differ from the Monad token.

Important Notes

Disclaimer

This list serves as a resource for token issuers to submit token metadata for convenience and interoperability across ecosystem protocols, apps and interfaces. Inclusion of a token in this list does not imply endorsement, verification, or approval. No due diligence or verification is performed on token issuers or associated projects. It is imperative to conduct your own research before engaging with any token.

Questions?

If you encounter any issues or have questions about the contribution process, please open an issue on GitHub.