Chain Integration | Skills Pool

技能檔案

Chain Integration

Integrate a new blockchain as a second-class citizen in ShapeShift Web. HDWallet packages live in the monorepo under packages/hdwallet-*. Covers everything from HDWallet native/Ledger support to Web chain adapter, asset generation, and feature flags. Activates when user wants to add basic support for a new blockchain.

shapeshift201 星標2026年3月2日

職業
分類: Web3 工具

技能內容

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

相關技能

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.

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.

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

# 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

// 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)
]

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

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

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];
}

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] }];
}

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

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

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,
        };
      });
    }
  };
}

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

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

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

# Build hdwallet packages to verify
pnpm run hdwallet:build

# Run hdwallet tests
pnpm run hdwallet:test

// 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
}

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

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

// Add to feature-flag gated chains

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 }

// 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]'

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, /* ... */ }
}

// 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
}

Aspect	Native Asset	Tokens	Internal Transfers
Where to find	Transaction value field	Event logs / receipts	Nested calls / traces
Asset ID	`this.assetId`	`chainId/namespace:contractAddress`	Varies
pubkey comparison	Usually sender field	Event old_owner/new_owner	May be nested

// 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
  }
}

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

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

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

[chainLower]ChainId: [chainLower]AssetId,

// 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
}

case [chainLower]ChainId:
  return [chainLower]BaseAsset

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
}

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

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,
  }
}

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

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

// 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
  }
}

case hyperEvmChainId:
  return supportsHyperEvm(wallet)

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
                })
              },
            ],
          ],
        },
      },
    ],
  ]
}

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

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

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

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

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

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

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

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

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

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

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

export default [chainLower]

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

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

// 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
}

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

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

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

[[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' }

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

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

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])]
}

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

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

  ...[chainLower]Assets,

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

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

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,
  }

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)

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

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

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)
}

// 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,
  }

# 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

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"

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.

// 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
}

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

// 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)

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'

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

import { [chainLower]AssetId } from '@shapeshiftoss/caip'

export const availableLedgerAppAssetIds = [
  // ...
  [chainLower]AssetId,
]

// Add your chain's expected entry to the `expected` object in the test
'eip155:[CHAIN_ID]': {
  'eip155:[CHAIN_ID]/slip44:60': '[coingecko-native-id]',
},

const ethOn[ChainName] = toAssetId({
  chainNamespace,
  chainReference: CHAIN_REFERENCE.[ChainName]Mainnet,
  assetNamespace: 'slip44',
  assetReference: ASSET_REFERENCE.[ChainName],
})
expect(coingeckoToAssetIds('ethereum')).toEqual([
  ethOnEthereum,
  ethOnOptimism,
  ethOnArbitrum,
  ethOnBase,
  ethOnMegaEth,
  ethOn[ChainName],  // ADD THIS
])

error TS2339: Property 'eip155:XXX' does not exist on type...
error TS18048: 'targetNetwork' is possibly 'undefined'.

[KnownChainIds.[ChainName]Mainnet]: {
  name: '[ChainName]',
  symbol: '[SYMBOL]',
  explorer: 'https://[explorer-url]',
},

# 1. Build packages first (REQUIRED before type-check)
pnpm run build:packages

# 2. Run CAIP tests specifically
pnpm exec vitest run packages/caip/ --reporter=verbose

# 3. Type-check
pnpm run type-check

# 4. Lint
pnpm run lint --fix

Native Token	CoinGecko ID	Update index.test.ts?	Update utils.test.ts?
ETH (L2s like Base, Optimism, Ink)	`'ethereum'`	YES - add to `coingeckoToAssetIds('ethereum')`	YES - add chain entry
Own token (BERA, MON, MNT, CRO)	`'berachain-bera'`, `'monad'`, `'mantle'`, `'cronos'`	NO	YES - add chain entry

pnpm run type-check

# Fix any TypeScript errors

pnpm run lint --fix

pnpm run build

# Verify no build errors
# Check bundle size didn't explode

# Commit everything together
git add -A
git commit -m "feat: implement [chainname]

- Add [ChainName] hdwallet core interfaces and native wallet support
- Add [ChainName] chain adapter with poor man's RPC
- Support native asset sends/receives
- Add account derivation
- Add feature flag VITE_FEATURE_[CHAIN]
- Add asset generation for [chain] from CoinGecko
- Wire transaction status polling
- Add [chain] plugin with feature flag gating

Behind feature flag for now."

git push origin HEAD

# Open PR to develop
gh pr create --title "feat: implement [chainname]" \
  --body "Adds basic [ChainName] support as second-class citizen..."

// 1. Import chain ID
import { [chainLower]ChainId } from '@shapeshiftoss/caip'

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

// 3. Add to switch statement (around line 186+)
case [chainLower]ChainId:
  return supports[ChainName](wallet)

case baseChainId:
case hyperEvmChainId:  // ← ADD THIS
case monadChainId:
case plasmaChainId:

Error: Chain namespace [chain] on mainnet not supported.
    at getNativeFeeAssetReference.ts:XX:XX

case CHAIN_NAMESPACE.[ChainName]:
  switch (chainReference) {
    case CHAIN_REFERENCE.[ChainName]Mainnet:
      return ASSET_REFERENCE.[ChainName]
    default:
      throw new Error(`Chain namespace ${chainNamespace} on ${chainReference} not supported.`)
  }

case CHAIN_NAMESPACE.[ChainName]: {
  const chainAccount = account as Account<KnownChainIds.[ChainName]Mainnet>
  const { chainId, assetId, pubkey } = account
  const accountId = toAccountId({ chainId, account: pubkey })

  portfolio.accounts.ids.push(accountId)
  portfolio.accounts.byId[accountId] = { assetIds: [assetId], hasActivity }
  portfolio.accountBalances.ids.push(accountId)
  portfolio.accountBalances.byId[accountId] = { [assetId]: account.balance }

  // Add token support if applicable
  chainAccount.chainSpecific.tokens?.forEach(token => {
    if (!assetIds.includes(token.assetId)) return
    if (bnOrZero(token.balance).gt(0)) portfolio.accounts.byId[accountId].hasActivity = true
    portfolio.accounts.byId[accountId].assetIds.push(token.assetId)
    portfolio.accountBalances.byId[accountId][token.assetId] = token.balance
  })

  break
}

async parseTx(txHash: string, pubkey: string): Promise<Transaction> {
  const result = await this.rpcCall('tx', [txHash, 'dontcare'])
  console.log('parseTx result:', JSON.stringify(result, null, 2))
  console.log('pubkey:', pubkey)
  // ... rest of implementation
}

// packages/utils/src/index.ts
export const isToken = (assetId: AssetId) => {
  switch (fromAssetId(assetId).assetNamespace) {
    case ASSET_NAMESPACE.erc20:
    case ASSET_NAMESPACE.erc721:
    case ASSET_NAMESPACE.erc1155:
    case ASSET_NAMESPACE.splToken:  // Solana
    case ASSET_NAMESPACE.trc20:     // Tron
    case ASSET_NAMESPACE.suiCoin:   // Sui
    case ASSET_NAMESPACE.nep141:    // NEAR <-- ADD YOUR NAMESPACE HERE
      return true
    default:
      return false
  }
}

console.log('[Send] assetId:', asset.assetId)
console.log('[Send] contractAddress:', contractAddressOrUndefined(asset.assetId))
// If contractAddress is undefined for a token, isToken() is missing the namespace

// 1. Add import at top
import Near from "@ledgerhq/hw-app-near";

// 2. Add case in translateCoinAndMethod switch
case "Near": {
  const near = new Near(transport as Transport);
  const methodInstance = near[method as LedgerTransportMethodName<"Near">].bind(near);
  return methodInstance as LedgerTransportMethod<T, U>;
}