DeFi Registry Manager

Manages expansion of tokens, pools, chains, networks, and DEXes across the codebase.

When to Use

• Adding new tokens to the registry
• Adding new protocols or DEXes
• Adding support for new chains
• Configuring network RPC endpoints
• Updating token addresses or decimals

Workflow

Step 1: Identify Registry Type

Determine if adding token, protocol, chain, or network.

Step 2: Follow Checklist

Use the appropriate checklist for the registry type.

Step 3: Update All Files

Ensure ALL required files are updated together.

Step 4: Validate Changes

Run validation commands to verify consistency.

---

Trigger Phrases

• "add token", "new token", "add coin"
• "add protocol", "new DEX", "add exchange"
• "add chain", "new network", "support chain"
• "add network", "new RPC", "configure network"
• "update address", "fix token address"

Registry Locations

Tokens - ALL must be updated together:

File	Purpose	Format
client/src/constants/protocols.ts	Frontend token list	TOKENS[chainId] array
rust-core/crates/core/src/tokens.rs	Rust core tokens	TOKENS LazyLock HashMap
server/src/services/wallet.ts	Wallet service tokens	COMMON_TOKENS + TOKEN_SYMBOLS
shared/schema.ts	Shared decimals map	TOKEN_DECIMALS record

Protocols/DEXes:

File	Purpose
client/src/constants/protocols.ts	PROTOCOLS array
server/src/services/arbitrage.ts	DEXES array for scanning
server/src/services/price-oracle.ts	Price oracle adapters

Chains:

File	Purpose
client/src/constants/protocols.ts	CHAINS array + ChainId type
rust-core/crates/core/src/lib.rs	ChainId enum
server/src/config/env.ts	RPC URLs per chain
shared/schema.ts	ChainId type
server/src/db/schema.ts	adminChains table (Admin UI)

Networks (RPC/Infrastructure):

File	Purpose
server/src/config/env.ts	Primary RPC URLs, WebSocket endpoints
server/src/db/schema.ts	adminChains table with rpcUrl, explorerUrl
rust-core/crates/core/src/lib.rs	Network constants, block times
server/src/services/trade-executor.ts	Chain-specific gas settings

Admin UI Database Tables:

Table	Purpose
adminTokens	Dynamic token registry via Admin UI
adminProtocols	Dynamic protocol/DEX registry via Admin UI
adminChains	Dynamic chain/network config via Admin UI
strategies	Trading strategy configurations

Adding a New Token - Checklist

[ ] 1. Verify token address on block explorer (checksum format)
[ ] 2. Confirm decimals (CRITICAL: USDC/USDT=6, WBTC=8, most=18)
[ ] 3. Update client/src/constants/protocols.ts - TOKENS[chainId]
[ ] 4. Update rust-core/crates/core/src/tokens.rs - chain_tokens.insert()
[ ] 5. Update server/src/services/wallet.ts - COMMON_TOKENS[chainId]
[ ] 6. Update server/src/services/wallet.ts - TOKEN_SYMBOLS (lowercase)
[ ] 7. Update shared/schema.ts - TOKEN_DECIMALS (if not standard 18)
[ ] 8. Run: grep -r "TOKEN_ADDRESS_HERE" to find any hardcoded refs

Token Template

// Frontend (protocols.ts)
{
  address: '0x...', // Checksum address
  symbol: 'TOKEN',
  name: 'Token Name',
  decimals: 18,
  chains: ['ethereum'],
}

// Rust (tokens.rs)
tokens.insert("TOKEN", Token::new(
    "0x...".parse().unwrap(),
    "TOKEN", "Token Name", 18, ChainId::Ethereum
));

// Wallet service (wallet.ts) - COMMON_TOKENS
'0x...', // TOKEN

// Wallet service (wallet.ts) - TOKEN_SYMBOLS
'0x...lowercase': 'TOKEN',

Adding a New Protocol/DEX - Checklist

[ ] 1. Add to client/src/constants/protocols.ts - PROTOCOLS array
[ ] 2. Add router address to shared/schema.ts - PROTOCOL_ADDRESSES
[ ] 3. Add to server/src/services/arbitrage.ts - DEXES (if scannable)
[ ] 4. Create adapter in server/src/services/price-oracle.ts (if needed)
[ ] 5. Update validation.ts if protocol needs specific validation

Adding a New Chain - Checklist

[ ] 1. Add ChainId to shared/schema.ts
[ ] 2. Add ChainId enum variant to rust-core/crates/core/src/lib.rs
[ ] 3. Add to client/src/constants/protocols.ts - CHAINS array
[ ] 4. Add RPC URL to server/src/config/env.ts
[ ] 5. Add chain config to server/src/services/trade-executor.ts
[ ] 6. Add tokens for new chain in all token files
[ ] 7. Add protocol addresses for new chain
[ ] 8. (Optional) Add to adminChains via Admin UI for dynamic config

Adding/Configuring a Network - Checklist

[ ] 1. Obtain reliable RPC endpoint (Alchemy, Infura, QuickNode, or self-hosted)
[ ] 2. Add environment variable to server/src/config/env.ts
     - HTTP RPC: {CHAIN}_RPC_URL
     - WebSocket: {CHAIN}_WS_URL (if needed for subscriptions)
[ ] 3. Configure rate limits and fallback RPCs if available
[ ] 4. Add network parameters to rust-core/crates/core/src/lib.rs:
     - Block time (for timing estimates)
     - Gas token decimals
     - EIP-1559 support flag
[ ] 5. Configure gas settings in server/src/services/trade-executor.ts:
     - Base fee multiplier
     - Priority fee defaults
     - Gas limit overrides
[ ] 6. Add explorer URL for transaction links
[ ] 7. Test connectivity: curl -X POST {RPC_URL} -d '{"jsonrpc":"2.0","method":"eth_blockNumber","params":[],"id":1}'
[ ] 8. Add to Admin UI via /admin -> Chains tab for dynamic updates

Network Configuration Template

// Environment (.env)
ETHEREUM_RPC_URL=https://eth-mainnet.g.alchemy.com/v2/YOUR_KEY
ETHEREUM_WS_URL=wss://eth-mainnet.g.alchemy.com/v2/YOUR_KEY
ARBITRUM_RPC_URL=https://arb-mainnet.g.alchemy.com/v2/YOUR_KEY

// server/src/config/env.ts
ethereum: {
  rpcUrl: process.env.ETHEREUM_RPC_URL,
  wsUrl: process.env.ETHEREUM_WS_URL,
  chainId: 1,
  blockTime: 12, // seconds
  supportsEip1559: true,
}

// Admin UI (adminChains table)
{
  id: 'ethereum',
  name: 'Ethereum Mainnet',
  chainIdNumeric: 1,
  rpcUrl: 'https://...',
  explorerUrl: 'https://etherscan.io',
  nativeToken: 'ETH',
  enabled: true,
}

Common Token Addresses (Ethereum Mainnet)

Token	Address	Decimals
WETH	0xC02aaA39b223FE8D0A0e5C4F27eAD9083C756Cc2	18
USDC	0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48	6
USDT	0xdAC17F958D2ee523a2206206994597C13D831ec7	6
DAI	0x6B175474E89094C44Da98b954EedeAC495271d0F	18
WBTC	0x2260FAC5E5542a773Aa44fBCfeDf7C193bc2C599	8

Validation Commands

After making changes, run these to verify consistency:

# Check all files have same token count for a chain
grep -c "ethereum" client/src/constants/protocols.ts
grep -c "Ethereum" rust-core/crates/core/src/tokens.rs

# Verify address consistency
grep -ri "0xA0b86991" --include="*.ts" --include="*.rs"

# Check for typos in addresses
grep -ri "0x6B175474E89094C44Da98b954" --include="*.ts" --include="*.rs"

Common Networks

Network	Chain ID	Block Time	Native Token	EIP-1559
Ethereum	1	12s	ETH	Yes
Arbitrum One	42161	0.25s	ETH	Yes
Base	8453	2s	ETH	Yes
Polygon	137	2s	MATIC	Yes
Optimism	10	2s	ETH	Yes
Avalanche	43114	2s	AVAX	Yes
BSC	56	3s	BNB	No

Critical Rules

1. ALWAYS verify decimals - Wrong decimals = catastrophic bugs
2. Use checksum addresses - Mixed case for EIP-55 compliance
3. Update ALL files - Partial updates cause runtime errors
4. Test after changes - Run build for both client and Rust core
5. Lowercase in TOKEN_SYMBOLS - Keys must be lowercase addresses
6. Test RPC connectivity - Verify endpoint before deploying
7. Use fallback RPCs - Primary + backup for reliability
8. Monitor rate limits - Stay within provider quotas