proxmox/token-lists/README.md

# DBIS Chain 138 Token Lists

Production-ready token lists for ChainID 138 (DBIS Chain), following the [Uniswap Token Lists Specification](https://github.com/Uniswap/token-lists).

---

## Quick Start

### Validate Token List

```bash
node scripts/validate-token-list.js lists/dbis-138.tokenlist.json
```

### Verify On-Chain

```bash
node scripts/verify-on-chain.js lists/dbis-138.tokenlist.json
```

### Prepare Release

```bash
./scripts/release.sh patch  # or minor, major
```

### Sign Token List

```bash
./scripts/sign-list.sh sign
```

---

## Directory Structure

```
token-lists/
├── lists/
│   └── dbis-138.tokenlist.json      # Main token list
├── logos/                            # Token logos (future)
├── scripts/
│   ├── validate-token-list.js       # Schema & validation
│   ├── checksum-addresses.js        # EIP-55 checksum validation
│   ├── validate-logos.js            # Logo URL validation
│   ├── verify-on-chain.js           # On-chain verification
│   ├── release.sh                   # Release automation
│   └── sign-list.sh                 # minisign signing
├── docs/
│   ├── TOKEN_LIST_POLICY.md         # Inclusion/delisting policy
│   ├── INTEGRATION_GUIDE.md         # Integration instructions
│   ├── CHANGELOG.md                 # Version history
│   └── TOKEN_LIST_AUTHORING_GUIDE.md # Authoring guide
└── minisign.pub                     # Public key for verification
```

---

## Token List Contents

Current version: **1.2.0**

### Tokens

1. **ETH/USD Price Feed** (Oracle)
   - Address: `0x3304b747E565a97ec8AC220b0B6A1f6ffDB837e6`
   - Decimals: 8
   - Category: Oracle, Price Feed

2. **WETH** (Wrapped Ether)
   - Address: `0xC02aaA39b223FE8D0A0e5C4F27eAD9083C756Cc2`
   - Decimals: 18
   - Category: DeFi, Wrapped

3. **WETH10** (Wrapped Ether v10)
   - Address: `0xf4BB2e28688e89fCcE3c0580D37d36A7672E8A9F`
   - Decimals: 18
   - Category: DeFi, Wrapped

4. **LINK** (Chainlink Token)
   - Address: `0xb7721dD53A8c629d9f1Ba31a5819AFe250002b03`
   - Decimals: 18
   - Category: DeFi, Oracle, CCIP

5. **cUSDT** (Compliant Tether USD)
   - Address: `0x93E66202A11B1772E55407B32B44e5Cd8eda7f22`
   - Decimals: 6
   - Category: Stablecoin, DeFi, Compliant

6. **cUSDC** (Compliant USD Coin)
   - Address: `0xf22258f57794CC8E06237084b353Ab30fFfa640b`
   - Decimals: 6
   - Category: Stablecoin, DeFi, Compliant

---

## Validation

All token lists are validated against:

- Uniswap Token Lists JSON Schema
- EIP-55 address checksumming
- Chain ID strict validation (must be 138)
- Duplicate detection (addresses and symbols)
- Logo URL accessibility
- On-chain contract verification

### Running Validations

```bash
# Full validation
node scripts/validate-token-list.js lists/dbis-138.tokenlist.json

# Check address checksums
node scripts/checksum-addresses.js lists/dbis-138.tokenlist.json

# Fix checksummed addresses
node scripts/checksum-addresses.js lists/dbis-138.tokenlist.json --fix

# Validate logos
node scripts/validate-logos.js lists/dbis-138.tokenlist.json

# Verify on-chain
node scripts/verify-on-chain.js lists/dbis-138.tokenlist.json
```

---

## CI/CD

### PR Validation

GitHub Actions automatically validates token lists on pull requests:

- JSON schema validation
- Address checksum validation
- Duplicate detection
- Logo validation (non-blocking)
- On-chain verification (optional, non-blocking)

### Release Process

1. Update version using release script:
   ```bash
   ./scripts/release.sh patch  # or minor, major
   ```

2. Create git tag:
   ```bash
   git tag -a v1.2.0 -m "Release v1.2.0"
   git push --tags
   ```

3. GitHub Actions release workflow will:
   - Run all validations (required)
   - Perform on-chain verification (required)
   - Generate checksums
   - Sign token list
   - Create GitHub Release

---

## Hosting

Token lists are hosted at:

- **GitHub Pages**: `https://{user}.github.io/{repo}/token-lists/lists/dbis-138.tokenlist.json`
- **GitHub Raw**: `https://raw.githubusercontent.com/{user}/{repo}/main/token-lists/lists/dbis-138.tokenlist.json`
- **DBIS Domain** (if configured): `https://tokens.d-bis.org/lists/dbis-138.tokenlist.json`

---

## Integration

See [INTEGRATION_GUIDE.md](docs/INTEGRATION_GUIDE.md) for detailed integration instructions for:

- MetaMask
- Ledger
- dApps
- Explorers/Indexers
- Custom applications

---

## Policy

See [TOKEN_LIST_POLICY.md](docs/TOKEN_LIST_POLICY.md) for:

- Inclusion requirements
- Delisting criteria
- Governance process
- Versioning policy

---

## Security

### Signature Verification

Token lists are signed with minisign for integrity verification:

```bash
# Verify signature
minisign -V -p minisign.pub -m lists/dbis-138.tokenlist.json -x lists/dbis-138.tokenlist.json.sig
```

### Public Key

The public key is included in the repository: `minisign.pub`

Private key is stored securely in GitHub Secrets for CI/CD signing.

---

## Contributing

### Adding Tokens

1. Create issue or pull request with token details
2. Ensure token meets inclusion requirements
3. Code owners review and approve
4. Validations run automatically via CI/CD

### Updating Tokens

1. Update token metadata in `lists/dbis-138.tokenlist.json`
2. Run validations locally
3. Create pull request
4. CI/CD validates changes

### Removing Tokens

1. Create issue explaining removal reason
2. Code owners review and approve
3. Update token list (major version bump)
4. Update CHANGELOG.md

---

## Dependencies

- Node.js >= 16.0.0
- pnpm (package manager)
- `@uniswap/token-lists` (official Uniswap Token Lists package)
- ethers.js (for address validation and on-chain verification)
- ajv & ajv-formats (for JSON schema validation)
- minisign (for signing, optional for verification)

Install dependencies:

```bash
pnpm install
```

### Package Integration

This project uses the official `@uniswap/token-lists` package for:
- JSON Schema validation
- TypeScript type definitions
- Specification compliance

The validation scripts automatically use the package schema, with fallback to URL fetch if the package is unavailable.

---

## Chainlists Submission

Files for submitting to Chainlists.org are in the `chainlists/` directory:

- `chainlists/chain-138.json` - Chain configuration in Chainlists format
- `chainlists/SUBMISSION_GUIDE.md` - Submission instructions

### Validate Chain Configuration

```bash
node scripts/validate-chainlists.js chainlists/chain-138.json
```

### Submit to Chainlists

See `chainlists/SUBMISSION_GUIDE.md` for detailed submission instructions.

The chain configuration includes:
- Chain ID: 138
- RPC URLs (primary and fallback)
- Block explorer
- Native currency information
- Chain metadata

---

## Links

- [Uniswap Token Lists Specification](https://github.com/Uniswap/token-lists)
- [@uniswap/token-lists npm package](https://www.npmjs.com/package/@uniswap/token-lists)
- [JSON Schema](https://uniswap.org/tokenlist.schema.json)
- [Chainlists Repository](https://github.com/ethereum-lists/chains)
- [Chainlists Website](https://chainlist.org)
- [EIP-55: Mixed-case checksum address encoding](https://eips.ethereum.org/EIPS/eip-55)
- [EIP-155: Simple replay attack protection](https://eips.ethereum.org/EIPS/eip-155)
- [Semantic Versioning](https://semver.org/)

## Token Lists Available

### ChainID 138 (DBIS Chain)
- **File**: `lists/dbis-138.tokenlist.json`
- **Tokens**: 6 (WETH, WETH10, LINK, cUSDT, cUSDC, ETH/USD Oracle)
- **Version**: 1.3.0
- **Status**: ✅ Complete and validated

### Cronos (ChainID 25)
- **File**: `lists/cronos.tokenlist.json`
- **Tokens**: 10 (WETH9, WETH10, LINK, USDW, EURW, GBPW, AUDW, JPYW, CHFW, CADW)
- **Version**: 1.0.0
- **Status**: ✅ Complete (DBIS CCIP + ISO-4217W deployments)

### Avalanche C-Chain (ChainID 43114)
- **File**: `lists/avalanche.tokenlist.json`
- **Tokens**: 2 (WETH9, WETH10)
- **Version**: 1.0.0
- **Status**: ✅ Complete (DBIS CCIP deployments)

### Arbitrum One (ChainID 42161)
- **File**: `lists/arbitrum.tokenlist.json`
- **Tokens**: 2 (WETH9, WETH10)
- **Version**: 1.0.0
- **Status**: ✅ Complete (DBIS CCIP deployments)

### Ethereum Mainnet (ChainID 1)
- **File**: `lists/ethereum-mainnet.tokenlist.json`
- **Tokens**: 1 (USDT)
- **Version**: 1.0.0
- **Status**: ✅ Complete and validated

### ALL Mainnet (ChainID 651940)
- **File**: `lists/all-mainnet.tokenlist.json`
- **Tokens**: 9 (AUSDT, USDT, USDC, WETH, WALL, HYDX, HYBX, CHT, AUDA)
- **Version**: 1.0.0
- **Status**: ✅ Complete

## Documentation

- [Token List Authoring Guide](../docs/11-references/TOKEN_LIST_AUTHORING_GUIDE.md)
- [Integration Guide](docs/INTEGRATION_GUIDE.md)
- [Token List Policy](docs/TOKEN_LIST_POLICY.md)
- [Uniswap Comparison](docs/UNISWAP_COMPARISON.md)
- [DefiLlama Analysis](docs/DEFILLAMA_ANALYSIS.md)
- [ALL Mainnet Extraction Guide](ALL_MAINNET_TOKEN_EXTRACTION_GUIDE.md)
- [ALL Mainnet Submission Guide](ALL_MAINNET_COMPLETE_SUBMISSION.md)

---

**Last Updated**: 2025-12-22