@yodlpay/tokenlists 0.9.7 → 1.0.0

package/README.md

@@ -1,29 +1,225 @@
-# Tokenlists
+# @yodlpay/tokenlists
 
-Lists of supported chains, tokens, routers for the Web3 Payment Network.
+Chains, tokens, and router ABIs for the Yodl Web3 Payment Network.
 
-# How to update pricefeeds and tokens
+## Installation
 
-Copy .env.sample to .env
+```bash
+npm install @yodlpay/tokenlists
+# or
+yarn add @yodlpay/tokenlists
+```
+
+## Usage
+
+### Chains
+
+```typescript
+import {
+  chains,
+  getChain,
+  getChainById,
+  getChains,
+  getShortNames,
+  getNativeToken,
+  getRouter,
+  getRouterByAddress,
+  type YodlChain
+} from '@yodlpay/tokenlists';
+
+// Get all supported chains
+const allChains = getChains();
+
+// Get chain by ID
+const ethereum = getChain(1);
+const arbitrum = getChainById(42161);
+
+// Get router config for a chain
+const router = getRouter(1);
+// { address: '0x...', version: '0.8', fee: '0.002' }
+
+// Get native token symbol
+const symbol = getNativeToken(1); // 'ETH'
+```
+
+### Tokens
+
+```typescript
+import {
+  tokenlist,
+  getTokens,
+  getTokenByAddress,
+  getTokenBySymbol,
+  getFeaturedTokenBySymbol,
+  getNativeWrappedToken,
+  type TokenInfo
+} from '@yodlpay/tokenlists';
+
+// Get all tokens
+const allTokens = tokenlist;
+
+// Get tokens for a specific chain
+const ethereumTokens = getTokens(1);
+
+// Find token by address
+const usdc = getTokenByAddress('0xa0b86991c6218b36c1d19d4a2e9eb0ce3606eb48', 1);
+
+// Find token by symbol
+const dai = getTokenBySymbol('DAI', 1);
+
+// Get wrapped native token
+const weth = getNativeWrappedToken(1);
+```
+
+### Router ABIs
+
+```typescript
+import {
+  getRouterAbi,
+  YODL_ROUTER_ABIS,
+  type AbiVersion
+} from '@yodlpay/tokenlists';
+
+// Get ABI for a specific version
+const abiV08 = getRouterAbi('0.8');
+
+// Use with viem
+import { getContract } from 'viem';
+
+const router = getContract({
+  address: '0x...',
+  abi: getRouterAbi('0.8'),
+  client,
+});
+```
+
+## Supported Chains
+
+- Ethereum (1)
+- Arbitrum (42161)
+- Optimism (10)
+- Base (8453)
+- Polygon (137)
+- Gnosis (100)
+- BSC (56)
+
+## Development
+
+```bash
+# Install dependencies
+yarn install
 
-Populate with the CoinMarketCap API key and run the following
+# Run tests
+yarn test
 
+# Build
+yarn build
+
+# Update token lists
+yarn update
+
+# Type check
+yarn typecheck
 ```
-yarn run update
+
+## Token List Update Process
+
+The package maintains two token lists:
+
+- **Featured** (`tokenlist-featured.json`) - Manually curated tokens with metadata updated from on-chain data
+- **Generated** (`tokenlist-generated.json`) - Auto-fetched tokens from external sources (cross-checked with other services as they are added)
+
+### How `yarn update` Works
+
+1. **Fetch tokens from Relay Link API** - Discovers tokens across all supported chains
+2. **Enrich with on-chain data** - Verifies name, symbol, and decimals directly from contracts
+3. **Match CoinGecko IDs** - Links tokens to CoinGecko for market data (tokens without a match are excluded)
+4. **Filter by market data** - Removes low-quality tokens based on:
+   - Market cap rank (must be ≤ 10,000)
+   - 24h volume (must be ≥ $10,000)
+   - Volume/market cap ratio (must be ≥ 0.1%)
+   - Circulating/max supply ratio (must be ≥ 0.1%)
+5. **Remove duplicates** - Tokens with duplicate symbols on the same chain are removed
+6. **Write to generated list** - Updates `tokenlist-generated.json`
+
+### Featured Token Overrides
+
+Some tokens intentionally have duplicates (e.g., native USDC + bridged USDC on the same chain). These are defined in `FEATURED_TOKEN_OVERRIDES` in `src/tokens/index.ts`:
+
+```typescript
+FEATURED_TOKEN_OVERRIDES: Array<{
+  symbol: string;    // Token symbol (e.g., 'USDC')
+  chainId: number;   // Chain ID where duplicates exist
+  primary: string;   // Default address returned by getTokenBySymbol()
+  addresses: string[]; // All valid addresses for this token
+}>
 ```
 
-# Publish new version
+When querying by symbol, the `primary` address is returned. Use `getTokenByAddress()` to get a specific variant.
+
+### Token Logo Management
 
+Token logos are stored in Vercel Blob storage and managed with two scripts:
+
+**Download logos locally:**
+```bash
+yarn download-logos
 ```
-yarn run test
-yarn run build
-yarn run publish
+- Downloads logos from external URLs in token lists
+- Converts all images to optimized WebP format (512px max, 85% quality)
+- Upscales small images with [Real-ESRGAN](https://github.com/xinntao/Real-ESRGAN) if available
+- Saves to `logos/tokens/` directory
+- Updates token lists to point to Vercel Blob URLs
+
+**Upload logos to Vercel Blob:**
+```bash
+# Upload new logos (skip existing)
+yarn upload-logos
+
+# Force re-upload all logos
+yarn upload-logos --force
+
+# Preview without uploading
+yarn upload-logos --dry-run
+```
+
+Requires `BLOB_READ_WRITE_TOKEN` environment variable (set in `.env` or export).
+
+## Version Management
+
+This package uses [semantic-release](https://github.com/semantic-release/semantic-release) for automated versioning. Version bumps are determined automatically from commit messages using [Conventional Commits](https://www.conventionalcommits.org/).
+
+### Commit Message Format
+
 ```
+<type>(<scope>): <description>
+
+[optional body]
+
+[optional footer]
+```
+
+### Version Bump Rules
+
+| Commit Type | Example | Release |
+|-------------|---------|---------|
+| `fix:` | `fix: correct token decimals` | Patch (0.9.7 → 0.9.8) |
+| `feat:` | `feat: add Sonic chain support` | Minor (0.9.7 → 0.10.0) |
+| `feat!:` or `BREAKING CHANGE:` | `feat!: change API signature` | Major (0.9.7 → 1.0.0) |
+
+Other commit types (`chore:`, `docs:`, `style:`, `refactor:`, `test:`) do not trigger a release.
 
-# Useful CMC categories
+### Release Process
 
-- Fiat Stablecoin - 6634dccba7b6f0637eec196a
-- EUR Stablecoin - 625d057257c0560770d004e2
-- USD Stablecoin - 625d04fa57c0560770d004e1
+1. Commit your changes using conventional commit messages
+2. Push to `main`
+3. GitHub Actions automatically:
+   - Runs tests and builds
+   - Determines the version bump from commits
+   - Updates `package.json` and `CHANGELOG.md`
+   - Creates a GitHub release with release notes
+   - Publishes to npm
 
+## License
 
+MIT

package/dist/ccip-CTW8a_vN.js

@@ -0,0 +1,184 @@
+var index = require('./index-Cso5F8p5.js');
+
+class OffchainLookupError extends index.BaseError {
+    constructor({ callbackSelector, cause, data, extraData, sender, urls }){
+        super(cause.shortMessage || 'An error occurred while fetching for an offchain result.', {
+            cause,
+            metaMessages: [
+                ...cause.metaMessages || [],
+                cause.metaMessages?.length ? '' : [],
+                'Offchain Gateway Call:',
+                urls && [
+                    '  Gateway URL(s):',
+                    ...urls.map((url)=>`    ${index.getUrl(url)}`)
+                ],
+                `  Sender: ${sender}`,
+                `  Data: ${data}`,
+                `  Callback selector: ${callbackSelector}`,
+                `  Extra data: ${extraData}`
+            ].flat(),
+            name: 'OffchainLookupError'
+        });
+    }
+}
+class OffchainLookupResponseMalformedError extends index.BaseError {
+    constructor({ result, url }){
+        super('Offchain gateway response is malformed. Response data must be a hex value.', {
+            metaMessages: [
+                `Gateway URL: ${index.getUrl(url)}`,
+                `Response: ${index.stringify(result)}`
+            ],
+            name: 'OffchainLookupResponseMalformedError'
+        });
+    }
+}
+class OffchainLookupSenderMismatchError extends index.BaseError {
+    constructor({ sender, to }){
+        super('Reverted sender address does not match target contract address (`to`).', {
+            metaMessages: [
+                `Contract address: ${to}`,
+                `OffchainLookup sender address: ${sender}`
+            ],
+            name: 'OffchainLookupSenderMismatchError'
+        });
+    }
+}
+
+const offchainLookupSignature = '0x556f1830';
+const offchainLookupAbiItem = {
+    name: 'OffchainLookup',
+    type: 'error',
+    inputs: [
+        {
+            name: 'sender',
+            type: 'address'
+        },
+        {
+            name: 'urls',
+            type: 'string[]'
+        },
+        {
+            name: 'callData',
+            type: 'bytes'
+        },
+        {
+            name: 'callbackFunction',
+            type: 'bytes4'
+        },
+        {
+            name: 'extraData',
+            type: 'bytes'
+        }
+    ]
+};
+async function offchainLookup(client, { blockNumber, blockTag, data, to }) {
+    const { args } = index.decodeErrorResult({
+        data,
+        abi: [
+            offchainLookupAbiItem
+        ]
+    });
+    const [sender, urls, callData, callbackSelector, extraData] = args;
+    const { ccipRead } = client;
+    const ccipRequest_ = ccipRead && typeof ccipRead?.request === 'function' ? ccipRead.request : ccipRequest;
+    try {
+        if (!index.isAddressEqual(to, sender)) throw new OffchainLookupSenderMismatchError({
+            sender,
+            to
+        });
+        const result = urls.includes(index.localBatchGatewayUrl) ? await index.localBatchGatewayRequest({
+            data: callData,
+            ccipRequest: ccipRequest_
+        }) : await ccipRequest_({
+            data: callData,
+            sender,
+            urls
+        });
+        const { data: data_ } = await index.call(client, {
+            blockNumber,
+            blockTag,
+            data: index.concat([
+                callbackSelector,
+                index.encodeAbiParameters([
+                    {
+                        type: 'bytes'
+                    },
+                    {
+                        type: 'bytes'
+                    }
+                ], [
+                    result,
+                    extraData
+                ])
+            ]),
+            to
+        });
+        return data_;
+    } catch (err) {
+        throw new OffchainLookupError({
+            callbackSelector,
+            cause: err,
+            data,
+            extraData,
+            sender,
+            urls
+        });
+    }
+}
+async function ccipRequest({ data, sender, urls }) {
+    let error = new Error('An unknown error occurred.');
+    for(let i = 0; i < urls.length; i++){
+        const url = urls[i];
+        const method = url.includes('{data}') ? 'GET' : 'POST';
+        const body = method === 'POST' ? {
+            data,
+            sender
+        } : undefined;
+        const headers = method === 'POST' ? {
+            'Content-Type': 'application/json'
+        } : {};
+        try {
+            const response = await fetch(url.replace('{sender}', sender.toLowerCase()).replace('{data}', data), {
+                body: JSON.stringify(body),
+                headers,
+                method
+            });
+            let result;
+            if (response.headers.get('Content-Type')?.startsWith('application/json')) {
+                result = (await response.json()).data;
+            } else {
+                result = await response.text();
+            }
+            if (!response.ok) {
+                error = new index.HttpRequestError({
+                    body,
+                    details: result?.error ? index.stringify(result.error) : response.statusText,
+                    headers: response.headers,
+                    status: response.status,
+                    url
+                });
+                continue;
+            }
+            if (!index.isHex(result)) {
+                error = new OffchainLookupResponseMalformedError({
+                    result,
+                    url
+                });
+                continue;
+            }
+            return result;
+        } catch (err) {
+            error = new index.HttpRequestError({
+                body,
+                details: err.message,
+                url
+            });
+        }
+    }
+    throw error;
+}
+
+exports.ccipRequest = ccipRequest;
+exports.offchainLookup = offchainLookup;
+exports.offchainLookupAbiItem = offchainLookupAbiItem;
+exports.offchainLookupSignature = offchainLookupSignature;