chain-integration

Chain Integration Skill

You are helping integrate a new blockchain as a second-class citizen into ShapeShift Web and HDWallet. This means basic support (native asset send/receive, account derivation, swaps to/from the chain) using the "poor man's" approach similar to Monad, Tron, and Sui - public RPC, no microservices, minimal features.

When This Skill Activates

Use this skill when the user wants to:

• "Add support for [ChainName]"
• "Integrate [ChainName] as second-class citizen"
• "Implement basic [ChainName] support"
• "Add [ChainName] with native wallet only"

Critical Understanding

Second-Class Citizen Pattern

Recent examples: Monad (EVM), Tron (UTXO-like), Sui (non-EVM)

What it includes:

• ✅ Native asset sends/receives
• ✅ Account derivation (Native wallet required, Ledger optional)
• ✅ Swap to/from the chain
• ✅ Poor man's balance updates (public RPC polling)
• ✅ Poor man's tx status (RPC polling with eth_getTransactionReceipt or equivalent)
• ✅ Feature flag gating

What it DOESN'T include:

• ❌ Full transaction history (no microservices)
• ❌ First-class Unchained API support
• ❌ Advanced features (staking, DeFi, etc.)
• ❌ All wallet support (usually just Native initially)

Development Flow

ALWAYS follow this order:

1. HDWallet Native Support (hdwallet repo)
2. Local Verdaccio Publishing (test hdwallet changes in web)
3. Web Basic Support (web repo - poor man's chain adapter)
4. Web Plugin & Integration (web repo - wire everything up)
5. Ledger Support (hdwallet repo - if chain is supported by Ledger)
6. Clean Commits (revert verdaccio bumps before PR)

Phase 0: Deep Research & Information Gathering

CRITICAL: This phase determines the entire integration strategy. Take time to research thoroughly.

Step 0.1: Initial Chain Discovery

First, search for basic chain information:

1. Search for official chain website and docs

   • Use WebSearch to find: "[ChainName] blockchain official website"
   • Look for: developer docs, whitepaper, GitHub repos

2. Determine chain architecture

   • CRITICAL QUESTION: Is this an EVM-compatible chain?
   • Search: "[ChainName] EVM compatible"
   • Look for keywords: "Ethereum Virtual Machine", "Solidity", "EVM-compatible", "Ethereum fork"
   • Check if they mention Metamask compatibility

3. Find RPC endpoints

   • Search: "[ChainName] public RPC endpoint"
   • Check official docs for RPC URLs
   • Look for ChainList entry: https://chainlist.org
   • Check: https://github.com/arddluma/awesome-list-rpc-nodes-providers

Why this matters:

• EVM chains (like Monad): 90% less code! Just add to EVM chains list. Auto-supported by all EVM wallets.
• Non-EVM chains (like Tron, Sui): Need full custom implementation with crypto adapters.

Step 0.2: Interactive Information Gathering

Use the AskUserQuestion tool with the Claude inquiry UI to gather information.

Question 1 - Chain Architecture (MOST IMPORTANT):

Does the user know if this is an EVM-compatible chain?

Options:
1. "Yes, it's EVM-compatible" → Proceed with EVM integration path (much simpler!)
2. "No, it's a custom blockchain" → Proceed with non-EVM integration path
3. "Not sure - can you research it?" → Perform web research (search for EVM compatibility indicators)

Context: EVM-compatible chains like Monad require minimal code changes (just add to supported chains list). Non-EVM chains like Tron/Sui require full custom crypto adapters.

Question 2 - RPC Endpoint:

Do you have a public RPC endpoint URL?

Options:
1. "Yes, here's the URL: [input]" → Use provided URL
2. "No, can you find one?" → Search ChainList.org, official docs, and GitHub for public RPC
3. "Need both HTTP and WebSocket" → Search for both endpoint types

Context: We need a reliable public RPC for the poor man's chain adapter. WebSocket is optional but nice for real-time updates.

Question 3 - SLIP44 Coin Type:

Do you know the SLIP44 coin type (BIP44 derivation path)?

Options:
1. "Yes, it's [number]" → Use provided coin type
2. "No, can you look it up?" → Search SLIP44 registry: https://github.com/satoshilabs/slips/blob/master/slip-0044.md
3. "Use the same as Ethereum (60)" → Common for EVM chains

Context: This determines the BIP44 derivation path: m/44'/[TYPE]'/0'/0/0

Step 0.3: Structured Information Collection

After determining chain type (EVM or non-EVM), collect remaining details:

Use AskUserQuestion to ask:

For ALL chains:

1. Chain Basic Info
   • Chain name (exact capitalizati