Evx Tokens

Evx Tokens is a library that provides default token lists for multiple blockchain networks, with an advanced indexing system using Fuse.js for fuzzy search and pagination.

Features

• Automatic Indexing: Automatically loads all tokens from all JSON files
• Fuzzy Search: Uses Fuse.js for intelligent search by name, symbol and address
• Pagination: Complete pagination support for results
• Filters: Filtering by network, chainId and other criteria
• Multiple Networks: Support for 18+ blockchain networks
• TypeScript: Fully typed with TypeScript

Installation

npm install evx-tokens

Development

Install Dependencies

npm install

Examples

The project includes comprehensive examples demonstrating different features:

Basic Statistics

Get system statistics and overview of indexed tokens, including total count, available networks, and chain IDs.

Basic Search

Search tokens by name, symbol, and address with various filtering options.

Pagination

Navigate through large result sets efficiently with proper pagination controls.

Network Filtering

Filter tokens by network and chain ID, compare tokens across different networks.

Fuzzy Search

Advanced search capabilities using Fuse.js for partial matches and typo tolerance.

Testing

The project includes comprehensive unit tests using Jest:

# Run all tests
npm test

# Run tests in watch mode
npm run test:watch

# Run tests with coverage report
npm run test:coverage

# Run tests with verbose output
npm run test:verbose

Build

npm run build

Project Structure

src/
├── types.ts              # Interfaces and types
├── config.ts             # System configurations
├── token-indexer.ts      # Main indexer logic
├── index.ts              # Main exports
└── tokens/               # Token JSON files

tests/
├── setup.ts              # Test setup and utilities
├── token-indexer.test.ts # TokenIndexer unit tests
└── config.test.ts        # ConfigManager unit tests

examples/
├── 01-basic-statistics.md    # Basic statistics example
├── 02-basic-search.md        # Basic search example
├── 03-pagination.md          # Pagination example
├── 04-network-filtering.md   # Network filtering example
└── 05-fuzzy-search.md        # Fuzzy search example

templates/
└── add-token-request-issue.md # Token request issue template

Data Structure

Each token has the following structure:

interface Token {
  name: string;           // Token name
  address: string;        // Contract address
  symbol: string;         // Token symbol
  decimals: number;       // Number of decimals
  chainId: number;        // Network ID
  logoURI?: string;       // Logo URL (optional)
  extensions?: any;       // Extensions (optional)
  network?: string;       // Network name (added automatically)
}

Example Token Entry:

{
  "name": "Wrapped Ether",
  "address": "0xC02aaA39b223FE8D0A0e5C4F27eAD9083C756Cc2",
  "symbol": "WETH",
  "decimals": 18,
  "chainId": 1,
  "logoURI": "https://raw.githubusercontent.com/trustwallet/assets/master/blockchains/ethereum/assets/0xC02aaA39b223FE8D0A0e5C4F27eAD9083C756Cc2/logo.png",
  "extensions": {
    "bridgeInfo": {
      "10": {
        "tokenAddress": "0x4200000000000000000000000000000000000006"
      }
    }
  }
}

Fuse.js Configuration

The system uses Fuse.js with the following optimized settings:

• Weights: Name (40%), Symbol (40%), Address (20%)
• Threshold: 0.3 (tolerance for fuzzy matches)
• MinMatchCharLength: 2 (minimum characters for match)
• IgnoreLocation: true (ignores text position)
• UseExtendedSearch: true (advanced search support)

Performance

• Indexing: Loads all tokens on initialization
• Search: O(1) for exact searches, O(n) for fuzzy searches
• Pagination: O(1) for pagination calculations
• Memory: ~2MB for all indexed tokens

License

This project is licensed under the MIT License - see the LICENSE file for details.

Adding New Tokens

To request the addition of a new token to the Evx token list, please follow these steps:

1. Create an Issue

Go to the Issues page and click on "New Issue".

2. Use the Token Request Template

Select the "Token Request" template from the issue templates. This will automatically populate the issue with the required format.

3. Fill in the Required Information

The template will ask for the following information:

• Token Address: The contract address of the token
• Token Name: The official name from the contract
• Token Decimals: Number of decimals from the contract
• Token Symbol: The symbol from the contract
• Official Homepage: Link to the token's official website
• Market Data: Link to CoinMarketCap or CoinGecko page

4. Important Notes

• Token listing is not required to use the Evx interface with a token
• Filing an issue does not guarantee addition to the default token list
• Please do not ping Discord about listing requests
• Ensure all information is accurate and from official sources

5. Review Process

All token requests will be reviewed based on:

• Token legitimacy and security
• Community demand
• Network coverage
• Compliance with listing criteria

Support

If you encounter any issues or have questions, open an issue on GitHub.