proxmox/token-lists/docs/UNISWAP_COMPARISON.md

Comparison: DBIS Token Lists vs Uniswap Token Lists

Date: 2026-01-26
Status: Updated with @uniswap/token-lists integration

---

Overview

This document compares our DBIS Chain 138 Token List implementation with the official Uniswap Token Lists specification and package.

---

Implementation Comparison

Schema & Validation

Feature	Uniswap Package	DBIS Implementation	Status
JSON Schema	✅ Exported from package	✅ Fetched from URL (now uses package)	✅ Integrated
TypeScript Types	✅ TokenList, TokenInfo, Version	⚠️ Manual validation	✅ Available
Schema Validation	✅ Via AJV	✅ Via AJV with fallback	✅ Enhanced
EIP-55 Checksum	❌ Not included	✅ Custom validation	✅ Enhanced
Duplicate Detection	❌ Not included	✅ Address & symbol checks	✅ Enhanced
Chain ID Validation	❌ Not included	✅ Strict validation (138)	✅ Enhanced
On-Chain Verification	❌ Not included	✅ RPC verification	✅ Enhanced
Logo Validation	❌ Not included	✅ URL accessibility check	✅ Enhanced

Package Integration

Feature	Before	After	Status
Schema Source	URL fetch	@uniswap/token-lists package	✅ Integrated
Type Safety	Manual	TypeScript types available	✅ Available
Dependency	None	@uniswap/token-lists@^1.0.0-beta.34	✅ Added
Fallback	None	URL fetch fallback	✅ Maintained

---

Feature Comparison

✅ What We Have That Uniswap Doesn't

1. Enhanced Validation

   • EIP-55 checksum validation
   • Duplicate address detection
   • Duplicate symbol detection (per chainId)
   • Strict chain ID validation
   • Logo URL validation

2. On-Chain Verification

   • RPC-based contract verification
   • ERC-20 token verification
   • Oracle contract verification
   • Dual RPC endpoint support with fallback

3. CI/CD Integration

   • GitHub Actions PR validation
   • Release workflow with full validation
   • Automated version bumping
   • minisign signing integration

4. Security Features

   • minisign signing support
   • Checksum generation
   • Public key verification

5. Documentation

   • Comprehensive integration guide
   • Token list policy
   • Authoring guide
   • Changelog tracking

✅ What Uniswap Has That We Use

1. Official Schema

   • JSON Schema from @uniswap/token-lists
   • TypeScript type definitions
   • Standard specification compliance

2. Package Ecosystem

   • npm package for easy integration
   • Type definitions for TypeScript projects
   • Schema validation utilities

---

Code Comparison

Schema Access

Uniswap Approach:

import { schema } from '@uniswap/token-lists'
import { TokenList, TokenInfo } from '@uniswap/token-lists'

Our Approach (Before):

const SCHEMA_URL = 'https://uniswap.org/tokenlist.schema.json';
const schema = await fetch(SCHEMA_URL).then(r => r.json());

Our Approach (After):

import { schema } from '@uniswap/token-lists';
// Falls back to URL fetch if package unavailable

Validation

Uniswap Approach:

import Ajv from 'ajv';
import addFormats from 'ajv-formats';
import { schema } from '@uniswap/token-lists';

const ajv = new Ajv({ allErrors: true, verbose: true });
addFormats(ajv);
const validate = ajv.compile(schema);
const valid = validate(tokenList);

Our Approach:

// Uses @uniswap/token-lists schema + enhanced validation
const schema = await getSchema(); // From package or URL
const validate = ajv.compile(schema);
const valid = validate(tokenList);

// Plus additional checks:
// - EIP-55 checksum validation
// - Duplicate detection
// - Chain ID strict validation
// - Logo URL validation

---

Best Practices Alignment

✅ We Follow Uniswap Best Practices

1. Semantic Versioning

   • ✅ Major: token removals
   • ✅ Minor: token additions
   • ✅ Patch: metadata updates

2. File Naming

   • ✅ .tokenlist.json extension for schema validation

3. Schema Compliance

   • ✅ All required fields
   • ✅ Optional fields where appropriate
   • ✅ Proper tag definitions

4. Hosting

   • ✅ HTTPS endpoints
   • ✅ CORS headers configured
   • ✅ Public accessibility

✅ We Enhance Beyond Uniswap

1. Validation Rigor

   • Stricter validation than base spec
   • On-chain verification
   • Security checks

2. Automation

   • CI/CD integration
   • Automated releases
   • Signature generation

3. Documentation

   • Comprehensive guides
   • Policy documentation
   • Integration examples

---

Integration Status

✅ Completed

• Added @uniswap/token-lists package dependency
• Updated validation script to use package schema
• Maintained fallback to URL fetch
• Enhanced validation beyond base spec
• TypeScript types available for future use

🔄 Available But Not Required

• TypeScript migration (current scripts are JavaScript)
• Direct type imports in validation scripts
• Token list registry integration

---

Recommendations

✅ Implemented

1. Use Official Package ✅

   • Now using @uniswap/token-lists for schema
   • Maintains compatibility with specification

2. Enhanced Validation ✅

   • Kept our enhanced validation features
   • Adds value beyond base specification

3. Type Safety ✅

   • TypeScript types available from package
   • Can be used in TypeScript projects

💡 Future Enhancements

1. TypeScript Migration

   • Convert validation scripts to TypeScript
   • Use TokenList and TokenInfo types directly

2. Token List Registry

   • Consider creating a registry similar to Uniswap's
   • Enable discovery and aggregation

3. Automated Token Discovery

   • Explore DefiLlama adapter patterns
   • Auto-populate from on-chain data

---

Conclusion

Our implementation:

• ✅ Complies with Uniswap Token Lists specification
• ✅ Uses official @uniswap/token-lists package
• ✅ Enhances with additional validation and security
• ✅ Maintains backward compatibility
• ✅ Provides comprehensive tooling and documentation

Status: Fully aligned with Uniswap specification while providing enhanced features for production use.

---

Last Updated: 2026-01-26