Chain Integration

Second-class EVM chain? If this is a second-class EVM chain integration, disregard the rest of this skill. Load and follow the contract at .claude/contracts/second-class-evm-chain.md instead - it contains the complete, authoritative checklist of every integration point required. Use the contract as your build todo list, checking off items as you go.

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 (workspace packages under packages/hdwallet-*)
2. Web Basic Support (poor man's chain adapter)
3. Web Plugin & Integration (wire everything up)
4. Ledger Support (packages/hdwallet-ledger - if chain is supported by Ledger)

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 capitalization, e.g., "Monad", "Tron", "Sui")
   • SLIP44 coin type (from Step 0.2 above)
   • Chain ID (numeric or string, e.g., "1" for Ethereum, "monad-1", etc.)

2. Documentation Links

   • Official website URL
   • Developer documentation URL
   • Block explorer URL
   • GitHub repository (if available)

3. Asset Information

   • Native asset symbol (e.g., MON, TRX, SUI)
   • Native asset name (e.g., "Monad", "Tron", "Sui")
   • Decimals/precision (usually 18 for EVM, varies for others)
   • CoinGecko ID (search: "coingecko [chainname]" or ask user)

For EVM chains only:

4. EVM-Specific Info
   • Network/Chain ID (numeric, e.g., 41454 for Monad)
   • Token standard: ERC20 (always)
   • Block explorer API (etherscan-like)?
   • Any non-standard behavior vs Ethereum?

For non-EVM chains only:

5. Chain Architecture Details

   • Transaction structure/format (link to docs)
   • Signing algorithm (secp256k1, ed25519, etc.)
   • Address format (base58, bech32, hex, etc.)
   • Official SDK (npm package name if available)
   • Token standard name (e.g., "TRC20", "SUI Coin", "SPL")

6. Ledger Hardware Wallet Support

   • Search: "Ledger [ChainName] support"
   • Check: https://www.ledger.com/supported-crypto-assets
   • Ask user: "Does Ledger support [ChainName]?"
   • If yes, note the Ledger app name

Action: Don't proceed until you have:

• ✅ Confirmed EVM vs non-EVM architecture
• ✅ At least one working RPC endpoint
• ✅ SLIP44 coin type
• ✅ Official documentation links
• ✅ Basic asset information (symbol, name, decimals)

Pro Tips:

• For EVM chains: Integration is 10x easier. You mostly just add constants.
• For non-EVM: Budget extra time for crypto adapter implementation.
• Missing RPC? Check ChainList.org, official Discord, or GitHub repos.
• Missing SLIP44? Check if it's in SLIP-0044 registry or propose one.
• Can't find CoinGecko ID? Search their API or website directly.

Integration Path Decision

Based on Phase 0 research, choose your path:

Path A: EVM Chain Integration (SIMPLE)

Examples: Monad, Base, Arbitrum, Optimism

Characteristics:

• ✅ Uses Ethereum Virtual Machine
• ✅ Solidity smart contracts
• ✅ ERC20 token standard
• ✅ Web3/ethers.js compatible
• ✅ Auto-supported by MetaMask, Ledger Ethereum app

What you'll do:

1. HDWallet: Just add chain ID to EVM chains list (~10 lines of code)
2. Web: Extend EvmBaseAdapter (~100 lines)
3. Everything else: Add constants and config

Time estimate: 2-4 hours for basic integration

Path B: Non-EVM Chain Integration (COMPLEX)

Examples: Tron, Sui, Cosmos, Solana

Characteristics:

• ❌ Custom virtual machine (not EVM)
• ❌ Custom smart contract language
• ❌ Custom token standard
• ❌ Custom transaction format
• ❌ Requires chain-specific crypto implementation

What you'll do:

1. HDWallet: Implement full chain module with crypto adapters (~500-1000 lines)
2. Web: Implement full IChainAdapter interface (~500-1000 lines)
3. Everything else: Add constants and config

Time estimate: 1-2 days for basic integration

Phase 1: HDWallet Native Support

Working Directory: Same monorepo — hdwallet packages are at packages/hdwallet-*

Step 1.0: Choose Implementation Strategy

If EVM chain: Continue with Step 1.2-EVM below (MINIMAL hdwallet work - ~30 minutes) If non-EVM chain: Continue with Step 1.1 below (COMPLEX - 1-2 days)

⚡ EVM Chains: Minimal HDWallet Work Required

For EVM-compatible chains (like Monad, HyperEVM, Base), you need MINIMAL changes to hdwallet:

What EVM chains DON'T need:

• ❌ No new core interfaces (TronWallet, SuiWallet, etc.)
• ❌ No crypto adapters (address derivation, signing)
• ❌ No wallet mixins
• ✅ Use existing Ethereum crypto (secp256k1, Keccak256)

What EVM chains DO need:

• ✅ Wallet support flags (_supportsChainName: boolean)
• ✅ Support function (supportsChainName())
• ✅ Set flags on all wallet implementations (~14 files)
• ✅ Build and verify with pnpm run hdwallet:build

Why? Each wallet type (Native, Ledger, MetaMask, etc.) needs to explicitly declare support for the chain, even though the crypto is identical. This enables wallet-specific gating in the UI.

Reference PRs:

• Monad hdwallet: https://github.com/shapeshift/hdwallet/pull/753
• HyperEVM hdwallet: https://github.com/shapeshift/hdwallet/pull/756

Time estimate: 30 minutes for hdwallet changes (vs 1-2 days for non-EVM)

Step 1.1: Research HDWallet Patterns (Non-EVM Only)

Examine existing implementations to understand patterns:

For non-EVM chains (like Tron, Sui):

# In the monorepo
cat packages/hdwallet-core/src/tron.ts
cat packages/hdwallet-native/src/tron.ts
cat packages/hdwallet-native/src/crypto/isolation/adapters/tron.ts

Key pattern: Need new core interfaces, native implementation, and crypto adapters for signing.

Step 1.2-EVM: EVM Chain Implementation (SIMPLE PATH)

For EVM chains only (like Monad):

File: packages/hdwallet-core/src/ethereum.ts Add your chain to supported EVM chains:

// Find the list of supported chain IDs and add yours
export const SUPPORTED_EVM_CHAINS = [
  1,      // Ethereum
  10,     // Optimism
  // ... other chains
  41454,  // Add your chain ID here (example: Monad)
]

File: packages/hdwallet-core/src/utils.ts Register SLIP44 if not using Ethereum's (60):

// If your chain uses a different SLIP44 than Ethereum
{ slip44: YOUR_SLIP44, symbol: 'SYMBOL', name: 'ChainName' }

That's it for hdwallet! EVM chains don't need crypto adapters. Skip to Step 1.6 (Version Bump).

Step 1.2-EVM: EVM Chain HDWallet Support (MINIMAL WORK - ~30 minutes)

For EVM chains only (like Monad, HyperEVM). Follow these PRs as reference:

• Monad hdwallet: https://github.com/shapeshift/hdwallet/pull/753
• HyperEVM hdwallet: https://github.com/shapeshift/hdwallet/pull/756

File: packages/hdwallet-core/src/ethereum.ts

Add your chain's support flag to the ETHWalletInfo interface:

export interface ETHWalletInfo extends HDWalletInfo {
  // ... existing flags
  readonly _supportsMonad: boolean;
  readonly _supportsHyperEvm: boolean;  // ADD THIS
  // ...
}

File: packages/hdwallet-core/src/wallet.ts

Add support function after supportsMonad:

export function supportsMonad(wallet: HDWallet): wallet is ETHWallet {
  return isObject(wallet) && (wallet as any)._supportsMonad;
}

export function supports[ChainName](wallet: HDWallet): wallet is ETHWallet {
  return isObject(wallet) && (wallet as any)._supports[ChainName];
}

Set flags on ALL wallet implementations (~12 files):

For second-class EVM chains (HyperEVM, Monad, Plasma):

Set readonly _supports[ChainName] = true on:

• packages/hdwallet-native/src/ethereum.ts
• packages/hdwallet-metamask-multichain/src/shapeshift-multichain.ts (uses standard EVM cryptography)
• packages/hdwallet-ledger/src/ledger.ts (uses Ethereum app, supports all EVM chains)
• packages/hdwallet-trezor/src/trezor.ts (uses Ethereum app, supports all EVM chains)
• packages/hdwallet-walletconnectv2/src/walletconnectv2.ts (chain-agnostic, supports all EVM chains)

Set readonly _supports[ChainName] = false on:

• packages/hdwallet-coinbase/src/coinbase.ts
• packages/hdwallet-gridplus/src/gridplus.ts
• packages/hdwallet-keepkey/src/keepkey.ts
• packages/hdwallet-keplr/src/keplr.ts
• packages/hdwallet-phantom/src/phantom.ts
• packages/hdwallet-vultisig/src/vultisig.ts

For non-EVM chains:

Set readonly _supports[ChainName] = true for Native only:

• packages/hdwallet-native/src/ethereum.ts (or appropriate chain file)

Set readonly _supports[ChainName] = false on all other wallet types listed above.

Then: Skip to Step 1.6 (Build & Verify)

Step 1.2-NonEVM: Non-EVM Core Interfaces (COMPLEX PATH)

File: packages/hdwallet-core/src/[chainname].ts

Create core TypeScript interfaces following the pattern:

import { addressNListToBIP32, slip44ByCoin } from "./utils";
import { BIP32Path, HDWallet, HDWalletInfo, PathDescription } from "./wallet";

export interface [Chain]GetAddress {
  addressNList: BIP32Path;
  showDisplay?: boolean;
  pubKey?: string;
}

export interface [Chain]SignTx {
  addressNList: BIP32Path;
  // Chain-specific tx data fields
  rawDataHex?: string; // or other fields
}

export interface [Chain]SignedTx {
  serialized: string;
  signature: string;
}

export interface [Chain]TxSignature {
  signature: string;
}

export interface [Chain]GetAccountPaths {
  accountIdx: number;
}

export interface [Chain]AccountPath {
  addressNList: BIP32Path;
}

export interface [Chain]WalletInfo extends HDWalletInfo {
  readonly _supports[Chain]Info: boolean;
  [chainLower]GetAccountPaths(msg: [Chain]GetAccountPaths): Array<[Chain]AccountPath>;
  [chainLower]NextAccountPath(msg: [Chain]AccountPath): [Chain]AccountPath | undefined;
}

export interface [Chain]Wallet extends [Chain]WalletInfo, HDWallet {
  readonly _supports[Chain]: boolean;
  [chainLower]GetAddress(msg: [Chain]GetAddress): Promise<string | null>;
  [chainLower]SignTx(msg: [Chain]SignTx): Promise<[Chain]SignedTx | null>;
}

export function [chainLower]DescribePath(path: BIP32Path): PathDescription {
  const pathStr = addressNListToBIP32(path);
  const unknown: PathDescription = {
    verbose: pathStr,
    coin: "[ChainName]",
    isKnown: false,
  };

  if (path.length != 5) return unknown;
  if (path[0] != 0x80000000 + 44) return unknown;
  if (path[1] != 0x80000000 + slip44ByCoin("[ChainName]")) return unknown;
  if ((path[2] & 0x80000000) >>> 0 !== 0x80000000) return unknown;
  if (path[3] !== 0) return unknown;
  if (path[4] !== 0) return unknown;

  const index = path[2] & 0x7fffffff;
  return {
    verbose: `[ChainName] Account #${index}`,
    accountIdx: index,
    wholeAccount: true,
    coin: "[ChainName]",
    isKnown: true,
  };
}

// Standard BIP44 derivation: m/44'/SLIP44'/<account>'/0/0
export function [chainLower]GetAccountPaths(msg: [Chain]GetAccountPaths): Array<[Chain]AccountPath> {
  const slip44 = slip44ByCoin("[ChainName]");
  return [{ addressNList: [0x80000000 + 44, 0x80000000 + slip44, 0x80000000 + msg.accountIdx, 0, 0] }];
}

Export from core:

// In packages/hdwallet-core/src/index.ts
export * from './[chainname]'

Register SLIP44:

// In packages/hdwallet-core/src/utils.ts
// Add to slip44Table
{ slip44: SLIP44, symbol: '[SYMBOL]', name: '[ChainName]' }

Step 1.3: Implement Native Wallet Support

File: packages/hdwallet-native/src/[chainname].ts

import * as core from "@shapeshiftoss/hdwallet-core";
import { Isolation } from "./crypto";
import { [Chain]Adapter } from "./crypto/isolation/adapters/[chainname]";
import { NativeHDWalletBase } from "./native";

export function MixinNative[Chain]WalletInfo<TBase extends core.Constructor<core.HDWalletInfo>>(Base: TBase) {
  return class MixinNative[Chain]WalletInfo extends Base implements core.[Chain]WalletInfo {
    readonly _supports[Chain]Info = true;

    [chainLower]GetAccountPaths(msg: core.[Chain]GetAccountPaths): Array<core.[Chain]AccountPath> {
      return core.[chainLower]GetAccountPaths(msg);
    }

    [chainLower]NextAccountPath(msg: core.[Chain]AccountPath): core.[Chain]AccountPath | undefined {
      throw new Error("Method not implemented");
    }
  };
}

export function MixinNative[Chain]Wallet<TBase extends core.Constructor<NativeHDWalletBase>>(Base: TBase) {
  return class MixinNative[Chain]Wallet extends Base {
    readonly _supports[Chain] = true;

    [chainLower]Adapter: [Chain]Adapter | undefined;

    async [chainLower]InitializeWallet(masterKey: Isolation.Core.BIP32.Node): Promise<void> {
      const nodeAdapter = await Isolation.Adapters.BIP32.create(masterKey);
      this.[chainLower]Adapter = new [Chain]Adapter(nodeAdapter);
    }

    [chainLower]Wipe() {
      this.[chainLower]Adapter = undefined;
    }

    async [chainLower]GetAddress(msg: core.[Chain]GetAddress): Promise<string | null> {
      return this.needsMnemonic(!!this.[chainLower]Adapter, () => {
        return this.[chainLower]Adapter!.getAddress(msg.addressNList);
      });
    }

    async [chainLower]SignTx(msg: core.[Chain]SignTx): Promise<core.[Chain]SignedTx | null> {
      return this.needsMnemonic(!!this.[chainLower]Adapter, async () => {
        const address = await this.[chainLower]GetAddress({
          addressNList: msg.addressNList,
          showDisplay: false,
        });

        if (!address) throw new Error("Failed to get [ChainName] address");

        const signature = await this.[chainLower]Adapter!.signTransaction(
          msg.rawDataHex,
          msg.addressNList
        );

        return {
          serialized: msg.rawDataHex + signature,
          signature,
        };
      });
    }
  };
}

Integrate into NativeHDWallet:

// In packages/hdwallet-native/src/native.ts
// Add mixin to class hierarchy
// Add initialization in initialize() method
// Add wipe in wipe() method

Step 1.4: Create Crypto Adapter (Non-EVM only)

File: packages/hdwallet-native/src/crypto/isolation/adapters/[chainname].ts

Implement chain-specific cryptography:

• Address generation algorithm
• Transaction signing
• Any chain-specific encoding

Reference: See tron.ts adapter for a complete example

Export adapter:

// In packages/hdwallet-native/src/crypto/isolation/adapters/index.ts
export * from './[chainname]'

Step 1.5: Update Core Wallet Interface

File: packages/hdwallet-core/src/wallet.ts

Add support check function:

export function supports[Chain](wallet: HDWallet): wallet is [Chain]Wallet {
  return !!(wallet as any)._supports[Chain]
}

Step 1.6: Build & Verify

# Build hdwallet packages to verify
pnpm run hdwallet:build

# Run hdwallet tests
pnpm run hdwallet:test

No version bumps or publishing needed — hdwallet packages are workspace packages (workspace:^).

Phase 2: Web Chain Adapter (Poor Man's Approach)

Step 3.1: Add Chain Constants

File: packages/caip/src/constants.ts

// Add chain ID constant
export const [chainLower]ChainId = '[caip19-format]' as const // e.g., 'eip155:1', 'tron:0x2b6653dc', etc.

// Add asset ID constant
export const [chainLower]AssetId = '[caip19-format]' as AssetId

// Add asset reference constant
export const ASSET_REFERENCE = {
  // ...
  [ChainName]: 'slip44:COINTYPE',
}

// Add to KnownChainIds enum
export enum KnownChainIds {
  // ...
  [ChainName]Mainnet = '[caip2-chain-id]',
}

// Add to asset namespace if needed (non-EVM chains)
export const ASSET_NAMESPACE = {
  // ...
  [tokenStandard]: '[namespace]', // e.g., trc20, suiCoin
}

File: packages/types/src/base.ts

// Add to KnownChainIds enum (duplicate but required)
export enum KnownChainIds {
  // ...
  [ChainName]Mainnet = '[caip2-chain-id]',
}

File: src/constants/chains.ts

// Add to second-class chains array
export const SECOND_CLASS_CHAINS = [
  // ...
  KnownChainIds.[ChainName]Mainnet,
]

// Add to feature-flag gated chains

Step 3.2: Create Chain Adapter

Directory: packages/chain-adapters/src/[adaptertype]/[chainname]/

For EVM Chains (SIMPLE!)

Extend SecondClassEvmAdapter - you only need ~50 lines!

File: packages/chain-adapters/src/evm/[chainname]/[ChainName]ChainAdapter.ts

import { ASSET_REFERENCE, [chainLower]AssetId } from '@shapeshiftoss/caip'
import type { AssetId } from '@shapeshiftoss/caip'
import type { RootBip44Params } from '@shapeshiftoss/types'
import { KnownChainIds } from '@shapeshiftoss/types'

import { ChainAdapterDisplayName } from '../../types'
import { SecondClassEvmAdapter } from '../SecondClassEvmAdapter'
import type { TokenInfo } from '../SecondClassEvmAdapter'

const SUPPORTED_CHAIN_IDS = [KnownChainIds.[ChainName]Mainnet]
const DEFAULT_CHAIN_ID = KnownChainIds.[ChainName]Mainnet

export type ChainAdapterArgs = {
  rpcUrl: string
  knownTokens?: TokenInfo[]
}

export const is[ChainName]ChainAdapter = (adapter: unknown): adapter is ChainAdapter => {
  return (adapter as ChainAdapter).getType() === KnownChainIds.[ChainName]Mainnet
}

export class ChainAdapter extends SecondClassEvmAdapter<KnownChainIds.[ChainName]Mainnet> {
  public static readonly rootBip44Params: RootBip44Params = {
    purpose: 44,
    coinType: Number(ASSET_REFERENCE.[ChainName]),
    accountNumber: 0,
  }

  constructor(args: ChainAdapterArgs) {
    super({
      assetId: [chainLower]AssetId,
      chainId: DEFAULT_CHAIN_ID,
      rootBip44Params: ChainAdapter.rootBip44Params,
      supportedChainIds: SUPPORTED_CHAIN_IDS,
      rpcUrl: args.rpcUrl,
      knownTokens: args.knownTokens ?? [],
    })
  }

  getDisplayName() {
    return ChainAdapterDisplayName.[ChainName]
  }

  getName() {
    return '[ChainName]'
  }

  getType(): KnownChainIds.[ChainName]Mainnet {
    return KnownChainIds.[ChainName]Mainnet
  }

  getFeeAssetId(): AssetId {
    return this.assetId
  }
}

export type { TokenInfo }

That's it! SecondClassEvmAdapter automatically provides:

• ✅ Account balance fetching (native + ERC-20 tokens via multicall)
• ✅ Fee estimation
• ✅ Transaction broadcasting
• ✅ Transaction parsing with ERC-20 event decoding (for execution price)
• ✅ Rate limiting via PQueue
• ✅ Multicall batching for token balances

Just follow the pattern from HyperEVM, Monad, or Plasma adapters.

For Non-EVM Chains (COMPLEX)

Implement IChainAdapter interface - requires custom crypto adapters and ~500-1000 lines.

Key Methods to Implement:

• getAccount() - Get balances (native + tokens)
• getAddress() - Derive address from wallet
• getFeeData() - Estimate transaction fees
• broadcastTransaction() - Submit signed tx to network
• buildSendApiTransaction() - Build unsigned tx
• signTransaction() - Sign with wallet
• parseTx() - Parse transaction (can stub out)
• getTxHistory() - Get tx history (stub out - return empty)

Poor Man's Patterns:

1. No Unchained: Use public RPC directly (@mysten/sui, tronweb, etc.)
2. No TX History: Stub out getTxHistory() to return empty array
3. Direct RPC Polling: Use chain-specific RPC for tx status

File: packages/chain-adapters/src/[chainname]/[ChainName]ChainAdapter.ts

See SuiChainAdapter.ts or TronChainAdapter.ts for complete examples.

Export:

// In packages/chain-adapters/src/[adaptertype]/[chainname]/index.ts
export * from './[ChainName]ChainAdapter'
export * from './types'

// In packages/chain-adapters/src/[adaptertype]/index.ts
export * as [chainLower] from './[chainname]'

// In packages/chain-adapters/src/index.ts
export * from './[adaptertype]'

Step 3.2a: Implement parseTx (Iterative Approach)

CRITICAL: The parseTx() method parses transaction data after broadcast. This determines:

• Whether the transaction shows in history (if applicable)
• Execution price calculation for swaps
• Transfer display (from/to/value)

Reference Implementations (use these as patterns):

• EVM chains: SecondClassEvmAdapter.parseTx() - handles ERC-20 Transfer events automatically
• Sui: SuiChainAdapter.parseTx() - parses SUI native and coin transfers
• Tron: TronChainAdapter.parseTx() - parses TRC-20 transfers
• NEAR: NearChainAdapter.parseTx() + parseNep141Transfers() - parses NEP-141 token logs

Iterative Development Flow:

1. Start with naive implementation - Parse native asset transfers only:

async parseTx(txHash: string, pubkey: string): Promise<Transaction> {
  const result = await this.rpcCall('getTransaction', [txHash])

  // Basic structure
  const status = result.success ? TxStatus.Confirmed : TxStatus.Failed
  const fee = { assetId: this.assetId, value: result.fee.toString() }

  const transfers: Transfer[] = []

  // Parse native transfers (naive - just native asset)
  if (result.value) {
    transfers.push({
      assetId: this.assetId,
      from: [result.from],
      to: [result.to],
      type: result.from === pubkey ? TransferType.Send : TransferType.Receive,
      value: result.value.toString(),
    })
  }

  return { txid: txHash, status, fee, transfers, /* ... */ }
}

2. User testing reveals issues - User tests sends/swaps and reports:

   • "Native send works but tokens don't show"
   • "Swap execution price is wrong"
   • Provides RPC response from debugger

3. Refine with actual RPC response - User provides debugger scope:

// Example: User provides RPC response showing token events in logs
// You then add token parsing logic based on actual data structure

private parseTokenTransfers(result: RpcResult, pubkey: string): Transfer[] {
  const transfers: Transfer[] = []

  // Parse token events from logs/events
  for (const event of result.events || []) {
    if (event.type === 'token_transfer') {
      // Token-specific parsing based on actual RPC structure
    }
  }

  return transfers
}

Key considerations for parseTx:

Common patterns by chain type:

EVM Chains (SecondClassEvmAdapter handles automatically):

• Native: tx.value
• Tokens: ERC-20 Transfer events in logs
• Uses ethers.Interface.parseLog() to decode events

Non-EVM Chains (must implement manually):

// NEAR pattern - EVENT_JSON logs
for (const log of receipt.outcome.logs) {
  if (!log.startsWith('EVENT_JSON:')) continue
  const event = JSON.parse(log.slice('EVENT_JSON:'.length))
  if (event.standard === 'nep141' && event.event === 'ft_transfer') {
    // Parse transfer from event.data
  }
}

// Sui pattern - coin type from object changes
for (const change of result.objectChanges) {
  if (change.type === 'mutated' && change.objectType.includes('::coin::Coin<')) {
    // Extract coin type and amount
  }
}

// Tron pattern - TRC20 logs
for (const log of result.log || []) {
  if (log.topics[0] === TRC20_TRANSFER_TOPIC) {
    // Decode TRC20 transfer
  }
}

pubkey vs account ID gotcha:

• Some chains pass pubkey as hex public key
• But logs/events use account addresses (e.g., alice.near, base58, etc.)
• May need to convert: const accountId = pubKeyToAddress(pubkey)

When to ask user for debugger scope:

• Initial naive implementation doesn't catch tokens
• Swap execution prices are wrong
• Internal transfers missing

Example request to user:

"The parseTx implementation needs refinement for token transfers. Can you:

1. Make a token send/swap
2. Set a breakpoint in parseTx()
3. Share the result variable from the RPC response This will help me see the actual data structure for token events."

Step 3.3: Add Utility Functions

File: packages/utils/src/getAssetNamespaceFromChainId.ts

case [chainLower]ChainId:
  return ASSET_NAMESPACE.[tokenStandard]

File: packages/utils/src/getChainShortName.ts

case KnownChainIds.[ChainName]Mainnet:
  return '[SHORT]'

File: packages/utils/src/getNativeFeeAssetReference.ts

case KnownChainIds.[ChainName]Mainnet:
  return ASSET_REFERENCE.[ChainName]

File: packages/utils/src/chainIdToFeeAssetId.ts

[chainLower]ChainId: [chainLower]AssetId,

File: packages/utils/src/assetData/baseAssets.ts

// Add base asset
export const [chainLower]BaseAsset: Asset = {
  assetId: [chainLower]AssetId,
  chainId: [chainLower]ChainId,
  name: '[ChainName]',
  symbol: '[SYMBOL]',
  precision: [DECIMALS],
  icon: '[iconUrl]',
  explorer: '[explorerUrl]',
  // ... other fields
}

File: packages/utils/src/assetData/getBaseAsset.ts

case [chainLower]ChainId:
  return [chainLower]BaseAsset

Step 3.4: Create Chain Utils (Transaction Status)

File: src/lib/utils/[chainname].ts

import { [chainLower]ChainId } from '@shapeshiftoss/caip'
import type { ChainAdapter } from '@shapeshiftoss/chain-adapters'
import { assertUnreachable } from '@/lib/utils'
import type { TxStatus } from '@/state/slices/txHistorySlice/txHistorySlice'

export const is[Chain]ChainAdapter = (adapter: unknown): adapter is [ChainAdapter] => {
  return (adapter as ChainAdapter).getChainId() === [chainLower]ChainId
}

export const assertGet[Chain]ChainAdapter = (
  adapter: ChainAdapter,
): asserts adapter is [ChainAdapter] => {
  if (!is[Chain]ChainAdapter(adapter)) {
    throw new Error('[ChainName] adapter required')
  }
}

// Implement getTxStatus using chain-specific RPC calls
export const get[Chain]TransactionStatus = async (
  txHash: string,
  adapter: [ChainAdapter],
): Promise<TxStatus> => {
  // Use chain client to check transaction status
  // Return 'confirmed', 'failed', or 'unknown'
  // See monad.ts / sui.ts for examples
}

Step 3.5: Wire Up Transaction Status Polling

File: src/hooks/useActionCenterSubscribers/useSendActionSubscriber.tsx

Add case for your chain:

case KnownChainIds.[ChainName]Mainnet:
  txStatus = await get[Chain]TransactionStatus(txHash, adapter)
  break

Step 3.6: Add Account Derivation

File: src/lib/account/[chainname].ts

import { [chainLower]ChainId, toAccountId } from '@shapeshiftoss/caip'
import type { AccountMetadata, AccountMetadataByAccountId } from '@shapeshiftoss/types'
import { KnownChainIds } from '@shapeshiftoss/types'
import { assertGet[Chain]ChainAdapter, is[Chain]ChainAdapter } from '@/lib/utils/[chainname]'

export const derive[Chain]AccountIdsAndMetadata = async (
  args: // standard args
): Promise<AccountMetadataByAccountId> => {
  const { accountNumber, chainIds, wallet } = args

  const adapter = adapterManager.get([chainLower]ChainId)
  if (!adapter) throw new Error('[ChainName] adapter not available')
  assertGet[Chain]ChainAdapter(adapter)

  const address = await adapter.getAddress({
    wallet,
    accountNumber,
  })

  const accountId = toAccountId({ chainId: [chainLower]ChainId, account: address })
  const account = await adapter.getAccount(address)

  const metadata: AccountMetadata = {
    accountType: 'native',
    bip44Params: adapter.getBip44Params({ accountNumber }),
  }

  return {
    [accountId]: metadata,
  }
}

Wire into account dispatcher:

// In src/lib/account/account.ts
case KnownChainIds.[ChainName]Mainnet:
  return derive[Chain]AccountIdsAndMetadata(args)

Step 3.7: Add Wallet Support Detection

File: src/hooks/useWalletSupportsChain/useWalletSupportsChain.ts

// Add to switch statement
case KnownChainIds.[ChainName]Mainnet:
  return supports[Chain](wallet) // from hdwallet-core

Step 3.8: Add Asset Support Detection (CRITICAL!)

IMPORTANT: This was missing for recent chains (Tron, SUI, Monad, HyperEVM, Plasma) and caused assets not to show up properly!

File: src/state/slices/portfolioSlice/utils/index.ts

Add your chain to the isAssetSupportedByWallet function around line 367:

// 1. Import your chain ID at the top
import {
  // ... existing imports
  [chainLower]ChainId,
} from '@shapeshiftoss/caip'

// 2. Import the support function from hdwallet-core
import {
  // ... existing imports
  supports[ChainName],
} from '@shapeshiftoss/hdwallet-core'

// 3. Add case to the switch statement in isAssetSupportedByWallet
export const isAssetSupportedByWallet = (assetId: AssetId, wallet: HDWallet): boolean => {
  if (!assetId) return false
  const { chainId } = fromAssetId(assetId)
  switch (chainId) {
    // ... existing cases
    case [chainLower]ChainId:
      return supports[ChainName](wallet)
    // ... rest of cases
    default:
      return false
  }
}

Why this matters: This function determines if a wallet can use a particular asset. Without it, assets for your chain won't appear in wallet UIs even if everything else is configured correctly!

Example: For HyperEVM, add:

case hyperEvmChainId:
  return supportsHyperEvm(wallet)

Phase 4: Web Plugin & Feature Flags

Step 4.1: Create Plugin

File: src/plugins/[chainname]/index.tsx

import { [chainLower]ChainId } from '@shapeshiftoss/caip'
import { [chainLower] } from '@shapeshiftoss/chain-adapters'
import { KnownChainIds } from '@shapeshiftoss/types'
import { getConfig } from '@/config'
import type { Plugins } from '@/plugins/types'

export default function register(): Plugins {
  return [
    [
      '[chainLower]ChainAdapter',
      {
        name: '[chainLower]ChainAdapter',
        featureFlag: ['[ChainName]'],
        providers: {
          chainAdapters: [
            [
              KnownChainIds.[ChainName]Mainnet,
              () => {
                return new [chainLower].ChainAdapter({
                  rpcUrl: getConfig().VITE_[CHAIN]_NODE_URL,
                  // Add other config as needed
                })
              },
            ],
          ],
        },
      },
    ],
  ]
}

Register plugin:

// In src/plugins/activePlugins.ts
import [chainLower] from './[chainname]'

export const activePlugins = [
  // ...
  [chainLower],
]

Gate in provider:

// In src/context/PluginProvider/PluginProvider.tsx
// Add feature flag check for your chain

Step 4.2: Environment Variables

File: .env

VITE_[CHAIN]_NODE_URL=[default-public-rpc]
VITE_FEATURE_[CHAIN]=false

File: .env.development

VITE_[CHAIN]_NODE_URL=[dev-rpc]
VITE_FEATURE_[CHAIN]=true

File: .env.production

VITE_[CHAIN]_NODE_URL=[prod-rpc]
VITE_FEATURE_[CHAIN]=false

Step 4.3: Config Validation

File: src/config.ts

const validators = {
  // ...
  VITE_[CHAIN]_NODE_URL: url(),
  VITE_FEATURE_[CHAIN]: bool({ default: false }),
}

Step 4.4: Feature Flag State

File: src/state/slices/preferencesSlice/preferencesSlice.ts

export type FeatureFlags = {
  // ...
  [ChainName]: boolean
}

const initialState: PreferencesState = {
  featureFlags: {
    // ...
    [ChainName]: getConfig().VITE_FEATURE_[CHAIN],
  },
}

Add to test mocks:

// In src/test/mocks/store.ts
featureFlags: {
  // ...
  [ChainName]: false,
}

Step 4.5: CSP Headers

File: headers/csps/chains/[chainname].ts

const [chainLower]: Csp = {
  'connect-src': [env.VITE_[CHAIN]_NODE_URL],
}

export default [chainLower]

Register CSP:

// In headers/csps/index.ts
import [chainLower] from './chains/[chainname]'

export default [
  // ...
  [chainLower],
]

Phase 5: Asset Generation

Step 5.1: CoinGecko Adapter Integration

CRITICAL: This step is required for asset discovery and pricing! See PR #11257 for Monad example.

File: packages/caip/src/adapters/coingecko/index.ts

Add your chain to the CoingeckoAssetPlatform enum and import the chain ID:

// Add import at top
import {
  // ... existing imports
  [chainLower]ChainId,
} from '../../constants'

// Add platform constant
export enum CoingeckoAssetPlatform {
  // ... existing platforms
  [ChainName] = '[coingecko-platform-id]', // e.g., 'hyperevm' for HyperEVM
}

File: packages/caip/src/adapters/coingecko/index.ts (3 touchpoints — enum + 2 switch statements)

CRITICAL: This file has 3 separate places to update. Missing any causes runtime failures.

Touchpoint 1 — Already shown above: CoingeckoAssetPlatform enum entry.

Touchpoint 2 — chainIdToCoingeckoAssetPlatform() forward mapping (CHAIN_REFERENCE → platform):

// For EVM chains, add to the EVM switch (inside chainNamespace Evm case)
case CHAIN_REFERENCE.[ChainName]Mainnet:
  return CoingeckoAssetPlatform.[ChainName]

Touchpoint 3 — coingeckoAssetPlatformToChainId() reverse mapping (platform → chainId):

case CoingeckoAssetPlatform.[ChainName]:
  return [chainLower]ChainId

NOTE: This reverse mapping requires importing [chainLower]ChainId from ../../constants. Only import what is used — chainIdToCoingeckoAssetPlatform uses CHAIN_REFERENCE not chainId constants.

File: packages/caip/src/adapters/coingecko/utils.ts (2 touchpoints)

Touchpoint 4 — Add chainId to buildByChainId loop in COINGECKO_ASSET_PLATFORM_TO_CHAIN_ID_MAP (~line 280-310):

// Import chainId + assetId from constants at top of file
import { [chainLower]AssetId, [chainLower]ChainId, ... } from '../../constants'

// Add to the switch/if chain inside the buildByChainId loop
prev[[chainLower]ChainId][assetId] = id

Touchpoint 5 — Add native asset to COINGECKO_NATIVE_ASSET_PLATFORM_TO_CHAIN_ID_MAP (~line 370-390):

[[chainLower]ChainId]: { [[chainLower]AssetId]: '[coingecko-native-coin-id]' },
// e.g., for Cronos: [cronosChainId]: { [cronosAssetId]: 'crypto-com-chain' }
// e.g., for ETH-native chains: [scrollChainId]: { [scrollAssetId]: 'ethereum' }

File: packages/caip/src/adapters/coingecko/utils.test.ts

Add test case for your chain:

it('returns correct platform for [ChainName]', () => {
  expect(chainIdToCoingeckoAssetPlatform([chainLower]ChainId)).toEqual(
    CoingeckoAssetPlatform.[ChainName]
  )
})

File: packages/caip/src/adapters/coingecko/index.test.ts

Add test asset for your chain:

// Add example asset from your chain to test fixtures
const [chainLower]UsdcAssetId: AssetId = 'eip155:[CHAIN_ID]/erc20:[USDC_ADDRESS]'

// Update test expectations to include your chain's asset

Step 5.2: Create Asset Generator

File: scripts/generateAssetData/[chainname]/index.ts

Follow the pattern from monad/tron/sui:

import { [chainLower]ChainId } from '@shapeshiftoss/caip'
import type { Asset } from '@shapeshiftoss/types'
import { [chainLower], unfreeze } from '@shapeshiftoss/utils'

import * as coingecko from '../coingecko'

export const getAssets = async (): Promise<Asset[]> => {
  const assets = await coingecko.getAssets([chainLower]ChainId)

  return [...assets, unfreeze([chainLower])]
}

Wire into generator:

1. Import in scripts/generateAssetData/generateAssetData.ts:

import * as [chainLower] from './[chainname]'

2. Fetch assets in the generateAssetData() function:

const [chainLower]Assets = await [chainLower].getAssets()

3. Add to unfilteredAssetData array:

  ...[chainLower]Assets,

Add chain to CoinGecko script:

File: scripts/generateAssetData/coingecko.ts

Import your chain:

import {
  // ... existing imports
  [chainLower]ChainId,
} from '@shapeshiftoss/caip'

import {
  // ... existing imports
  [chainLower],
} from '@shapeshiftoss/utils'

Add case in the switch statement (around line 133+):

case [chainLower]ChainId:
  return {
    assetNamespace: ASSET_NAMESPACE.erc20, // or trc20, suiCoin, etc.
    category: adapters.chainIdToCoingeckoAssetPlatform(chainId),
    explorer: [chainLower].explorer,
    explorerAddressLink: [chainLower].explorerAddressLink,
    explorerTxLink: [chainLower].explorerTxLink,
  }

Step 5.3: Swapper Support Discovery & Integration

CRITICAL: Add your chain to supported swappers so users can actually trade!

Step 5.3a: Research Which Swappers Support Your Chain

Use AskUserQuestion to ask:

Question: Which swappers support [ChainName]?

Options:

1. "I know which swappers" → User provides list
2. "Can you research it?" → Search swapper docs and supported chains lists
3. "Just add Relay for now" → Start with Relay, add others later

Context: Different swappers support different chains. We need to add your chain to each swapper that supports it.

Search for swapper support:

1. Relay: Check https://docs.relay.link/resources/supported-chains
2. 0x/Matcha: Check https://0x.org/docs/introduction/0x-cheat-sheet
3. OneInch: Check https://docs.1inch.io/docs/aggregation-protocol/introduction
4. CowSwap: Check https://docs.cow.fi/cow-protocol/reference/contracts/deployments
5. Jupiter: Solana-only
6. THORChain: Check https://docs.thorchain.org/chain-clients/overview

Common patterns:

• Most EVM chains: Relay, 0x, possibly OneInch
• Ethereum L2s: Relay, 0x, CowSwap, OneInch
• Non-EVM: Relay (if supported), chain-specific DEXes

Step 5.3b: Relay Swapper Integration (Most Common)

For Relay Swapper (supports most chains):

IMPORTANT - Check viem chain definitions first:

1. Search viem's chain definitions: Check if your chain exists in viem:

   • Browse: https://github.com/wevm/viem/tree/main/src/chains/definitions
   • Look for [chainname].ts file (e.g., hyperEvm.ts for HyperEVM)
   • Note the exact export name (may differ from chain name, e.g., hyperEvm not hyperliquid)

2. Update viem if needed: For new/recent chains, update viem to latest version first:

   # Check current version
   pnpm why viem
   
   # Update to latest pinned version
   pnpm update viem@latest
   
   # Rebuild packages
   pnpm run build:packages

3. Only define manually if unavailable: If the chain doesn't exist in viem, use defineChain() pattern (see viem docs)

File: packages/swapper/src/swappers/RelaySwapper/constant.ts

Add your chain to the Relay chain ID mapping:

import {
  // ... existing imports
  [chainLower]ChainId,
} from '@shapeshiftoss/caip'

// Add to viem chain imports if EVM (check viem/chains for exact export name!)
import {
  // ... existing chains
  [chainLower], // e.g., hyperEvm from viem/chains (note: hyperEvm not hyperliquid!)
} from 'viem/chains'

export const chainIdToRelayChainId = {
  // ... existing mappings
  [[chainLower]ChainId]: [chainLower].id, // For EVM chains using viem
  // OR
  [[chainLower]ChainId]: [RELAY_CHAIN_ID], // For non-EVM (get from Relay docs)
}

File: packages/swapper/src/swappers/RelaySwapper/utils/relayTokenToAssetId.ts

Add native asset case in the relayTokenToAssetId function:

// Add to the switch statement for native assets (around line 100+)
case CHAIN_REFERENCE.[ChainName]Mainnet:
  return {
    assetReference: ASSET_REFERENCE.[ChainName],
    assetNamespace: ASSET_NAMESPACE.slip44,
  }

IMPORTANT: Make sure ALL chains that are in the chainIdToRelayChainId mapping in constant.ts have a corresponding case in the switch statement in relayTokenToAssetId.ts. Missing cases will cause runtime errors like chainId 'XX' not supported.

Check Relay docs for your chain:

• https://docs.relay.link/resources/supported-chains
• Verify chain ID and native token address

Step 5.4: Generate Assets (Step-by-Step Approach)

IMPORTANT: Asset generation requires a Zerion API key for related asset indexing.

Ask user for Zerion API key using AskUserQuestion:

Question: Do you have a Zerion API key to run asset generation?

Options:

1. "Yes, here it is" → User provides key (NEVER store in VCS!)
2. "No, skip for now" → Skip asset generation, user can run manually later

Context: Asset generation fetches token metadata and requires a Zerion API key. The key is passed via environment variable and should NEVER be committed to VCS.

Ask user how they want to run generation using AskUserQuestion:

Question: How do you want to run the asset generation pipeline?

Options:

1. "I'll run it myself" → Copy command to clipboard (echo | pbcopy), user runs it, better visibility of progress
2. "Claude runs it" → Claude runs all steps in background. ⚠️ WARNING: May take 5-10 minutes with limited visibility. You'll see less progress output.

Context: Asset generation has 5 steps (caip-adapters, color-map, asset-data, tradable-asset-map, thor-longtail). Running manually gives full visibility of progress (you'll see "chain_id: hyperevm" tokens being processed). Claude running it is hands-off but you won't see detailed progress, and it may appear stuck for several minutes while processing thousands of tokens.

Run generation scripts ONE AT A TIME (better visibility than generate:all):

# Step 1: Generate CoinGecko CAIP adapters (JSON mappings from our code)
pnpm run generate:caip-adapters
# ✓ Generates packages/caip/src/adapters/coingecko/generated/eip155_999/adapter.json
# ✓ Takes ~10 seconds

# Step 2: Generate color map (picks up new assets)
pnpm run generate:color-map
# ✓ Updates scripts/generateAssetData/color-map.json
# ✓ Takes ~5 seconds

# Step 3: Generate asset data (fetches tokens from CoinGecko)
ZERION_API_KEY=<user-provided-key> pnpm run generate:asset-data
# ✓ Fetches all HyperEVM ERC20 tokens from CoinGecko platform 'hyperevm'
# ✓ Updates src/assets/generated/
# ✓ Takes 2-5 minutes - YOU SHOULD SEE:
#   - "Total Portals tokens fetched for ethereum: XXXX"
#   - "Total Portals tokens fetched for base: XXXX"
#   - "chain_id": "hyperevm" appearing in output (means HyperEVM tokens found!)
#   - "Generated CoinGecko AssetId adapter data."
#   - "Asset data generated successfully"

# Step 4: Generate tradable asset map (for swapper support)
pnpm run generate:tradable-asset-map
# ✓ Generates src/lib/swapper/constants.ts mappings
# ✓ Takes ~10 seconds

# Step 5: Generate Thor longtail tokens (Thor-specific, optional for most chains)
pnpm run generate:thor-longtail-tokens
# ✓ Updates Thor longtail token list
# ✓ Takes ~5 seconds

Why step-by-step is better than generate:all:

• ✅ See exactly which step is running
• ✅ Catch errors immediately
• ✅ See progress output (like "chain_id": "hyperevm" tokens being processed)
• ✅ Can skip irrelevant steps (e.g., thor-longtail for non-Thor chains)

Commit generated assets:

git add src/assets/generated/ packages/caip/src/adapters/coingecko/generated/ scripts/generateAssetData/color-map.json
git commit -m "feat: generate [chainname] assets and mappings"

⚠️ CRITICAL: NEVER commit the Zerion API key. Only use it in the command line.

Step 5.4: Research & Add Swapper Support

IMPORTANT: After assets are generated, check which swappers support your new chain!

Step 5.4a: Ask User About Swapper Support

Use AskUserQuestion to determine swapper support:

Which swappers support [ChainName]?

Options:
1. "I know which swappers support it" → User provides list
2. "Research it for me" → AI will search swapper docs
3. "Skip for now" → Can add swapper support later

Context: Different DEX aggregators support different chains. We need to add your chain to each swapper that supports it so users can trade.

Step 5.4b: Research Common Swapper Support (if needed)

If user chooses "Research it for me", check these sources:

Relay (most common, supports most chains):

• Docs: https://docs.relay.link/resources/supported-chains
• Usually supports: Ethereum, Base, Arbitrum, Optimism, Polygon, Avalanche, BSC, Gnosis, and many new EVM chains
• Check if your chain's viem chain definition exists (e.g., plasma from 'viem/chains')

Other swappers to check:

• 0x/Matcha: https://0x.org/docs/introduction/0x-cheat-sheet
• CowSwap: https://docs.cow.fi/cow-protocol/reference/contracts/deployments
• Jupiter: Solana-only
• THORChain: Check https://docs.thorchain.org/chain-clients/overview
• ChainFlip: Check supported chains in their docs

Step 5.4c: Add Relay Swapper Support (Most Common)

If Relay supports your chain:

File: packages/swapper/src/swappers/RelaySwapper/constant.ts

// 1. Add imports
import {
  // ... existing imports
  plasmaChainId,
} from '@shapeshiftoss/caip'

import {
  // ... existing chains
  plasma,  // Check if viem/chains exports your chain
} from 'viem/chains'

// 2. Add to chainIdToRelayChainId mapping
export const chainIdToRelayChainId = {
  // ... existing mappings
  [plasmaChainId]: plasma.id,  // Uses viem chain ID
}

File: packages/swapper/src/swappers/RelaySwapper/utils/relayTokenToAssetId.ts

// Add native asset case in switch statement (around line 124):
case CHAIN_REFERENCE.PlasmaMainnet:
  return {
    assetReference: ASSET_REFERENCE.Plasma,
    assetNamespace: ASSET_NAMESPACE.slip44,
  }

Step 5.4d: Add Other Swapper Support (As Needed)

Follow similar patterns for other swappers (CowSwap, 0x, etc.) - see swapper-integration skill for detailed guidance.

Reference: Plasma added to Relay swapper for swap support

Step 5.5: Add Native Asset to Popular Assets

CRITICAL: Second-class citizen chains are not in CoinGecko's top 100 by market cap, so they won't appear in the popular assets list by default. This causes the native asset to be missing when users filter by that chain.

File: src/components/TradeAssetSearch/hooks/useGetPopularAssetsQuery.tsx

// Add import at the top
import {
  hyperEvmAssetId,
  mayachainAssetId,
  monadAssetId,
  plasmaAssetId,  // example for Plasma
  [chainLower]AssetId,  // Add your chain's asset ID
  thorchainAssetId,
  tronAssetId,
  suiAssetId,
} from '@shapeshiftoss/caip'

// Add to the queryFn, after the mayachain check (around line 37)
// add second-class citizen chains to popular assets for discoverability
if (enabledFlags.HyperEvm) assetIds.push(hyperEvmAssetId)
if (enabledFlags.Monad) assetIds.push(monadAssetId)
if (enabledFlags.Plasma) assetIds.push(plasmaAssetId)
if (enabledFlags.[ChainName]) assetIds.push([chainLower]AssetId)  // Add your chain
if (enabledFlags.Tron) assetIds.push(tronAssetId)
if (enabledFlags.Sui) assetIds.push(suiAssetId)

Why this is needed:

• Popular assets are fetched from CoinGecko's top 100 by market cap
• New/small chains aren't in the top 100
• Without this, when filtering by your chain, only tokens appear (via relatedAssetIds)
• The native asset won't show up, which is confusing for users
• Example: Searching "monad" in MetaMask (doesn't support Monad) shows Monad tokens but not MON itself

Reference PRs:

• See how Monad, Tron, Sui, Plasma, and HyperEVM were added in the same PR

Step 5.6: Add ETH Related Asset to Related Asset Index (CONDITIONAL - ETH-native chains only!)

ONLY for chains where ETH is the native gas token (e.g., Optimism, Arbitrum, Base, Katana, MegaETH). SKIP for chains with their own native token (e.g., Berachain/BERA, Monad/MON, Tron/TRX, Sui/SUI).

Why this matters: The related asset index groups the same asset across different chains (e.g., ETH on Ethereum, ETH on Optimism, ETH on Arbitrum). When a user views ETH, they can see all the chain variants. If your chain uses ETH as its native gas token and you don't add it here, the chain's ETH won't appear as a related asset in the UI.

File: scripts/generateAssetData/generateRelatedAssetIndex/generateRelatedAssetIndex.ts

1. Import your chain's asset ID at the top:

import {
  adapters,
  arbitrumAssetId,
  baseAssetId,
  ethAssetId,
  FEE_ASSET_IDS,
  foxAssetId,
  foxOnArbitrumOneAssetId,
  fromAssetId,
  katanaAssetId,
  megaethAssetId,
  [chainLower]AssetId,  // ADD THIS - only if native token IS ETH
  optimismAssetId,
  starknetAssetId,
} from '@shapeshiftoss/caip'

2. Add to the manualRelatedAssetIndex under ethAssetId:

const manualRelatedAssetIndex: Record<AssetId, AssetId[]> = {
  [ethAssetId]: [optimismAssetId, arbitrumAssetId, baseAssetId, katanaAssetId, megaethAssetId, [chainLower]AssetId],
  //                                                                                           ^^^^^^^^^^^^^^^^ ADD
  [foxAssetId]: [foxOnArbitrumOneAssetId],
  // ...
}

How to determine if this step applies:

• ✅ ADD if: Chain uses ETH as native gas (user pays gas in ETH, like Optimism, Base, Arbitrum)
• ❌ SKIP if: Chain has its own native gas token (like BERA for Berachain, MON for Monad, TRX for Tron)

Reference: Look at which assetIds are already in the array - they're all L2s/chains where the native token is ETH.

Phase 6: Ledger Support (Optional)

Only if chain is supported by Ledger hardware

Step 6.1: Check Ledger Support

1. Visit https://www.ledger.com/supported-crypto-assets
2. Search for your chain
3. Note the Ledger app name

For EVM chains: Automatically supported via Ethereum app For non-EVM: Needs chain-specific Ledger app

Step 6.2: Add Ledger Support in HDWallet

File: packages/hdwallet-ledger/src/ledger.ts

Add chain support following existing patterns.

For EVM: Just add to supported chains list For non-EVM: Implement chain-specific Ledger transport