defi-registry-manager

# 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

```typescript
// 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

```typescript
// 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:

```bash
# 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