feat: add chain integration skill#11260
Conversation
Add complete skill for integrating new blockchains as second-class citizens in ShapeShift Web and HDWallet. Features: - Deep research phase with automatic EVM detection - Interactive Claude UI for information gathering - Automatic RPC endpoint discovery (ChainList.org, GitHub, docs) - SLIP44 registry lookup - Split EVM (simple) vs non-EVM (complex) integration paths - Complete Verdaccio local testing workflow - 9 phases covering hdwallet → web integration - 40+ file checklist - 10 documented gotchas from recent integrations - Based on real examples: Monad (EVM), Tron (non-EVM), Sui (non-EVM) EVM chains: 2-4 hours, ~100 lines of code Non-EVM chains: 1-2 days, ~1000-2000 lines of code Includes patterns for: - HDWallet native wallet support - HDWallet Ledger support (optional) - Web poor man's chain adapter - Feature flags and config - Asset generation - Transaction status polling - Clean commit workflow with revertable verdaccio bumps 1343 lines of comprehensive documentation. 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude <[email protected]>
📝 WalkthroughWalkthroughAdds a comprehensive Chain Integration Skill document providing end-to-end guidance for integrating a new blockchain in ShapeShift Web and HDWallet. The document outlines activation conditions, architecture choices, phased development workflow, concrete implementation steps, code patterns, and multi-repo coordination procedures. Changes
Estimated code review effort🎯 2 (Simple) | ⏱️ ~12 minutes
Suggested reviewers
Poem
Pre-merge checks and finishing touches✅ Passed checks (3 passed)
✨ Finishing touches
🧪 Generate unit tests (beta)
Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out. Comment |
There was a problem hiding this comment.
Actionable comments posted: 0
🧹 Nitpick comments (4)
.claude/skills/chain-integration/SKILL.md (4)
70-71: Wrap bare URLs in markdown link syntax for consistent documentation formatting.Lines 70-71, 161, and 1008 contain bare URLs that should be formatted as markdown links for better rendering and consistency with documentation best practices.
- Look for ChainList entry: https://chainlist.org - Check: https://github.com/arddluma/awesome-list-rpc-nodes-providers + Look for ChainList entry: [ChainList](https://chainlist.org) + Check: [arddluma/awesome-list-rpc-nodes-providers](https://github.com/arddluma/awesome-list-rpc-nodes-providers) - Check: https://www.ledger.com/supported-crypto-assets + Check: [Ledger supported crypto assets](https://www.ledger.com/supported-crypto-assets) - 1. Visit https://www.ledger.com/supported-crypto-assets + 1. Visit [Ledger supported crypto assets](https://www.ledger.com/supported-crypto-assets)Also applies to: 161-161, 1008-1008
82-82: Specify language identifiers for fenced code blocks to enable syntax highlighting.Lines 82, 94, and 106 contain code blocks (triple backticks) without language specifications. These should include the language identifier for proper syntax highlighting in the Claude UI.
- **Question 1 - Chain Architecture** (MOST IMPORTANT): - ``` + **Question 1 - Chain Architecture** (MOST IMPORTANT): + ```text Does the user know if this is an EVM-compatible chain? - **Question 2 - RPC Endpoint**: - ``` + **Question 2 - RPC Endpoint**: + ```text Do you have a public RPC endpoint URL? - **Question 3 - SLIP44 Coin Type**: - ``` + **Question 3 - SLIP44 Coin Type**: + ```text Do you know the SLIP44 coin type (BIP44 derivation path)?Also applies to: 94-94, 106-106
1003-1004: Convert emphasized text to proper markdown structure.Line 1003-1004 uses emphasis (
**...**) to create what appears to be a section marker, violating markdown best practices. This should either be a proper markdown heading or regular paragraph text.- **Only if chain is supported by Ledger hardware** - - ### Step 6.1: Check Ledger Support + ### Step 6.1: Check Ledger Support (Optional) + + Only proceed with this step if chain is supported by Ledger hardware.
223-223: Remove or generalize personal absolute paths in working directory references.Lines 223 and 527-528 specify hardcoded personal filesystem paths (
/Users/alexandre.gomes/Sites/...) that won't work for other developers or in CI/CD contexts. These should either be documented as setup prerequisites or replaced with generic references.- **Working Directory**: `/Users/alexandre.gomes/Sites/shapeshiftHdWallet` + **Working Directory**: HDWallet repository root (typically `~/workspace/shapeshiftHdWallet` or equivalent) - cd /Users/alexandre.gomes/Sites/shapeshiftWeb + cd [shapeshiftWeb-repo-root]Alternatively, document the directory structure assumption in a setup section at the beginning of the skill.
Also applies to: 527-528
📜 Review details
Configuration used: CodeRabbit UI
Review profile: CHILL
Plan: Pro
Disabled knowledge base sources:
- Linear integration is disabled by default for public repositories
You can enable these sources in your CodeRabbit configuration.
📒 Files selected for processing (1)
.claude/skills/chain-integration/SKILL.md(1 hunks)
🧰 Additional context used
🧠 Learnings (17)
📓 Common learnings
Learnt from: gomesalexandre
Repo: shapeshift/web PR: 11170
File: patches/@shapeshiftoss+bitcoinjs-lib+7.0.0-shapeshift.0.patch:9-19
Timestamp: 2025-11-25T21:43:10.838Z
Learning: In shapeshift/web, gomesalexandre will not expand PR scope to fix latent bugs in unused API surface (like bitcoinjs-lib patch validation methods) when comprehensive testing proves the actual used code paths work correctly, preferring to avoid costly hdwallet/web verdaccio publish cycles and full regression testing for conceptual issues with zero runtime impact.
Learnt from: gomesalexandre
Repo: shapeshift/web PR: 10461
File: src/plugins/walletConnectToDapps/components/modals/EIP712MessageDisplay.tsx:133-137
Timestamp: 2025-09-12T10:15:10.389Z
Learning: gomesalexandre has identified that EIP-712 domain chainId should be preferred over request context chainId for accuracy in WalletConnect dApps structured signing flows. The domain chainId from the parsed message is more specific and accurate than the general request context, especially for asset resolution and network-specific operations.
Learnt from: gomesalexandre
Repo: shapeshift/web PR: 10458
File: src/plugins/walletConnectToDapps/components/modals/EIP712MessageDisplay.tsx:46-59
Timestamp: 2025-09-10T15:34:54.593Z
Learning: After extensive testing by gomesalexandre in PR #10458, dApps do not send EIP-712 domain.chainId as hex or bigint values in practice. The simple String(domain.chainId) conversion is sufficient for real-world usage in WalletConnect dApps structured signing.
Learnt from: gomesalexandre
Repo: shapeshift/web PR: 10206
File: src/config.ts:127-128
Timestamp: 2025-08-07T11:20:44.614Z
Learning: gomesalexandre prefers required environment variables without default values in the config file (src/config.ts). They want explicit configuration and fail-fast behavior when environment variables are missing, rather than having fallback defaults.
Learnt from: gomesalexandre
Repo: shapeshift/web PR: 10461
File: src/plugins/walletConnectToDapps/components/modals/ContractInteractionBreakdown.tsx:0-0
Timestamp: 2025-09-13T16:45:18.813Z
Learning: gomesalexandre prefers aggressively deleting unused/obsolete code files ("ramboing") rather than fixing technical issues in code that won't be used, demonstrating his preference for keeping codebases clean and PR scope focused.
Learnt from: gomesalexandre
Repo: shapeshift/web PR: 10458
File: src/plugins/walletConnectToDapps/types.ts:7-7
Timestamp: 2025-09-10T15:34:29.604Z
Learning: gomesalexandre is comfortable relying on transitive dependencies (like abitype through ethers/viem) rather than explicitly declaring them in package.json, preferring to avoid package.json bloat when the transitive dependency approach works reliably in practice.
Learnt from: gomesalexandre
Repo: shapeshift/web PR: 10503
File: .env:56-56
Timestamp: 2025-09-16T13:17:02.938Z
Learning: gomesalexandre prefers to enable feature flags globally in the base .env file when the intent is to activate features everywhere, even when there are known issues like crashes, demonstrating his preference for intentional global feature rollouts over cautious per-environment enablement.
Learnt from: gomesalexandre
Repo: shapeshift/web PR: 10249
File: src/pages/ThorChainLP/components/ReusableLpStatus/TransactionRow.tsx:447-503
Timestamp: 2025-08-13T17:07:10.763Z
Learning: gomesalexandre prefers relying on TypeScript's type system for validation rather than adding defensive runtime null checks when types are properly defined. They favor a TypeScript-first approach over defensive programming with runtime validations.
Learnt from: gomesalexandre
Repo: shapeshift/web PR: 10276
File: src/hooks/useActionCenterSubscribers/useThorchainLpDepositActionSubscriber.tsx:61-66
Timestamp: 2025-08-14T17:51:47.556Z
Learning: gomesalexandre is not concerned about structured logging and prefers to keep console.error usage as-is rather than implementing structured logging patterns, even when project guidelines suggest otherwise.
Learnt from: gomesalexandre
Repo: shapeshift/web PR: 10413
File: src/components/Modals/FiatRamps/fiatRampProviders/onramper/utils.ts:29-55
Timestamp: 2025-09-02T14:26:19.028Z
Learning: gomesalexandre prefers to keep preparatory/reference code simple until it's actively consumed, rather than implementing comprehensive error handling, validation, and robustness improvements upfront. They prefer to add these improvements when the code is actually being used in production.
Learnt from: gomesalexandre
Repo: shapeshift/web PR: 10276
File: src/pages/ThorChainLP/components/ReusableLpStatus/TransactionRow.tsx:396-402
Timestamp: 2025-08-14T17:55:57.490Z
Learning: gomesalexandre is comfortable with functions/variables that return undefined or true (tri-state) when only the truthy case matters, preferring to rely on JavaScript's truthy/falsy behavior rather than explicitly returning boolean values.
Learnt from: gomesalexandre
Repo: shapeshift/web PR: 10783
File: src/context/ModalStackProvider/useModalRegistration.ts:30-41
Timestamp: 2025-10-16T11:14:40.657Z
Learning: gomesalexandre prefers to add lint rules (like typescript-eslint/strict-boolean-expressions for truthiness checks on numbers) to catch common issues project-wide rather than relying on code review to catch them.
Learnt from: gomesalexandre
Repo: shapeshift/web PR: 10206
File: src/lib/moralis.ts:47-85
Timestamp: 2025-08-07T11:22:16.983Z
Learning: gomesalexandre prefers console.error over structured logging for Moralis API integration debugging, as they find it more conventional and prefer to examine XHR requests directly rather than rely on structured logs for troubleshooting.
📚 Learning: 2025-09-12T10:15:10.389Z
Learnt from: gomesalexandre
Repo: shapeshift/web PR: 10461
File: src/plugins/walletConnectToDapps/components/modals/EIP712MessageDisplay.tsx:133-137
Timestamp: 2025-09-12T10:15:10.389Z
Learning: gomesalexandre has identified that EIP-712 domain chainId should be preferred over request context chainId for accuracy in WalletConnect dApps structured signing flows. The domain chainId from the parsed message is more specific and accurate than the general request context, especially for asset resolution and network-specific operations.
Applied to files:
.claude/skills/chain-integration/SKILL.md
📚 Learning: 2025-11-19T16:59:50.569Z
Learnt from: gomesalexandre
Repo: shapeshift/web PR: 11012
File: src/context/WalletProvider/Vultisig/components/Connect.tsx:24-59
Timestamp: 2025-11-19T16:59:50.569Z
Learning: In src/context/WalletProvider/*/components/Connect.tsx files across the ShapeShift web codebase, the established pattern for handling null/undefined adapter from getAdapter() is to simply check `if (adapter) { ... }` without an else clause. All wallet Connect components (Coinbase, Keplr, Phantom, Ledger, MetaMask, WalletConnectV2, KeepKey, Vultisig) follow this pattern—they reset loading state after the if block but do not show error messages when adapter is null. This is an intentional design decision and should be maintained for consistency.
Applied to files:
.claude/skills/chain-integration/SKILL.md
📚 Learning: 2025-11-24T21:20:57.909Z
Learnt from: CR
Repo: shapeshift/web PR: 0
File: .cursor/rules/swapper.mdc:0-0
Timestamp: 2025-11-24T21:20:57.909Z
Learning: Applies to packages/swapper/src/swappers/*/*.ts : Implement filterBuyAssetsBySellAssetId method to filter assets by supported chain IDs in the buy property
Applied to files:
.claude/skills/chain-integration/SKILL.md
📚 Learning: 2025-10-23T14:27:19.073Z
Learnt from: gomesalexandre
Repo: shapeshift/web PR: 10857
File: src/plugins/walletConnectToDapps/eventsManager/useWalletConnectEventsHandler.ts:101-104
Timestamp: 2025-10-23T14:27:19.073Z
Learning: In WalletConnect wallet_switchEthereumChain and wallet_addEthereumChain requests, the chainId parameter is always present as per the protocol spec. Type guards checking for missing chainId in these handlers (like `if (!evmNetworkIdHex) return`) are solely for TypeScript compiler satisfaction, not real runtime edge cases.
Applied to files:
.claude/skills/chain-integration/SKILL.md
📚 Learning: 2025-11-24T21:20:57.909Z
Learnt from: CR
Repo: shapeshift/web PR: 0
File: .cursor/rules/swapper.mdc:0-0
Timestamp: 2025-11-24T21:20:57.909Z
Learning: Applies to packages/swapper/src/swappers/*/utils/constants.ts : Define supported chain IDs for each swapper in utils/constants.ts with both 'sell' and 'buy' properties following the pattern: SupportedChainIds type
Applied to files:
.claude/skills/chain-integration/SKILL.md
📚 Learning: 2025-09-18T23:47:14.810Z
Learnt from: gomesalexandre
Repo: shapeshift/web PR: 10566
File: src/hooks/useWalletSupportsChain/useWalletSupportsChain.ts:55-66
Timestamp: 2025-09-18T23:47:14.810Z
Learning: In the useWalletSupportsChain architecture, checkWalletHasRuntimeSupport() determines if the app has runtime capability to interact with a chain type (not actual signing capabilities), while walletSupportsChain() does the actual capabilities detection by checking account IDs. For Ledger read-only mode, checkWalletHasRuntimeSupport should return true since the app can display balances/addresses, with KeyManager being the source of truth rather than wallet instance.
Applied to files:
.claude/skills/chain-integration/SKILL.md
📚 Learning: 2025-11-24T21:20:57.909Z
Learnt from: CR
Repo: shapeshift/web PR: 0
File: .cursor/rules/swapper.mdc:0-0
Timestamp: 2025-11-24T21:20:57.909Z
Learning: Applies to packages/swapper/src/swappers/*/*.ts : Implement filterAssetIdsBySellable method to filter assets by supported chain IDs in the sell property
Applied to files:
.claude/skills/chain-integration/SKILL.md
📚 Learning: 2025-11-24T21:20:04.979Z
Learnt from: CR
Repo: shapeshift/web PR: 0
File: CLAUDE.md:0-0
Timestamp: 2025-11-24T21:20:04.979Z
Learning: Applies to **/*.{ts,tsx} : Import types from `shapeshiftoss/caip` for chain/account/asset IDs
Applied to files:
.claude/skills/chain-integration/SKILL.md
📚 Learning: 2025-10-01T07:42:40.195Z
Learnt from: gomesalexandre
Repo: shapeshift/web PR: 10596
File: src/components/Layout/Header/NavBar/WalletConnectedMenu.tsx:77-99
Timestamp: 2025-10-01T07:42:40.195Z
Learning: In WalletConnectedMenu.tsx's handleReconnectWallet handler, gomesalexandre prefers throwing an error for unsupported wallet types in the default case rather than gracefully handling with a fallback. His reasoning: "if we have a problem here, we have bigger problems" - only supported wallets (KeepKey, Ledger, MetaMask, Coinbase, Phantom) should reach the reconnect flow when disconnected/locked, so encountering an unsupported type indicates a larger architectural issue that should be surfaced explicitly rather than masked with graceful degradation.
Applied to files:
.claude/skills/chain-integration/SKILL.md
📚 Learning: 2025-11-12T12:49:17.895Z
Learnt from: gomesalexandre
Repo: shapeshift/web PR: 11016
File: packages/swapper/src/swappers/NearIntentsSwapper/swapperApi/getTradeQuote.ts:109-125
Timestamp: 2025-11-12T12:49:17.895Z
Learning: In packages/chain-adapters/src/evm/utils.ts, the getErc20Data function already includes a guard that returns an empty string when contractAddress is undefined (line 8: `if (!contractAddress) return ''`). This built-in handling means callers don't need to conditionally invoke getErc20Data—it safely handles both ERC20 tokens and native assets.
Applied to files:
.claude/skills/chain-integration/SKILL.md
📚 Learning: 2025-09-16T08:47:31.440Z
Learnt from: gomesalexandre
Repo: shapeshift/web PR: 10528
File: src/plugins/walletConnectToDapps/utils/createApprovalNamespaces.ts:39-47
Timestamp: 2025-09-16T08:47:31.440Z
Learning: In WalletConnect dApps createApprovalNamespaces logic, required namespaces have different semantics than optional namespaces. Required namespaces are validated upfront in the UI - users cannot proceed without accounts for all required chains, and required chains are always selected and unselectable. Therefore, additional filtering by selectedChainIds is unnecessary for required namespaces since the validation flow guarantees they will be supported and selected.
Applied to files:
.claude/skills/chain-integration/SKILL.md
📚 Learning: 2025-08-17T21:53:03.806Z
Learnt from: 0xApotheosis
Repo: shapeshift/web PR: 10290
File: scripts/generateAssetData/color-map.json:41-47
Timestamp: 2025-08-17T21:53:03.806Z
Learning: In the ShapeShift web codebase, native assets (using CAIP-19 slip44 namespace like eip155:1/slip44:60, bip122:.../slip44:..., cosmos:.../slip44:...) are manually hardcoded and not generated via the automated asset generation script. Only ERC20/BEP20 tokens go through the asset generation process. The validation scripts should only validate generated assets, not manually added native assets.
Applied to files:
.claude/skills/chain-integration/SKILL.md
📚 Learning: 2025-11-25T21:43:10.838Z
Learnt from: gomesalexandre
Repo: shapeshift/web PR: 11170
File: patches/@shapeshiftoss+bitcoinjs-lib+7.0.0-shapeshift.0.patch:9-19
Timestamp: 2025-11-25T21:43:10.838Z
Learning: In shapeshift/web, gomesalexandre will not expand PR scope to fix latent bugs in unused API surface (like bitcoinjs-lib patch validation methods) when comprehensive testing proves the actual used code paths work correctly, preferring to avoid costly hdwallet/web verdaccio publish cycles and full regression testing for conceptual issues with zero runtime impact.
Applied to files:
.claude/skills/chain-integration/SKILL.md
📚 Learning: 2025-10-22T22:11:22.918Z
Learnt from: gomesalexandre
Repo: shapeshift/web PR: 10879
File: src/context/WalletProvider/WalletConnectV2/components/WalletConnectDirectRow.tsx:64-81
Timestamp: 2025-10-22T22:11:22.918Z
Learning: In early WalletConnect POC/features behind a flag, gomesalexandre prioritizes connection correctness/stability over UX polish; minimal safety guards (like preventing concurrent connects) are preferred, while visuals will be wired later by reallybeard.
Applied to files:
.claude/skills/chain-integration/SKILL.md
📚 Learning: 2025-08-27T09:47:06.275Z
Learnt from: NeOMakinG
Repo: shapeshift/web PR: 10323
File: src/components/ButtonWalletPredicate/ButtonWalletPredicate.tsx:7-7
Timestamp: 2025-08-27T09:47:06.275Z
Learning: In shapeshift/web project, NeOMakinG consistently prefers to defer UI/UX improvements and refactoring work (like the Drawer.Close hack fix in ButtonWalletPredicate.tsx) to follow-up PRs rather than expanding the scope of feature PRs, even when the improvements would enhance robustness.
Applied to files:
.claude/skills/chain-integration/SKILL.md
📚 Learning: 2025-09-30T05:28:39.685Z
Learnt from: 0xApotheosis
Repo: shapeshift/web PR: 10691
File: src/components/AssetHeader/AssetHeader.tsx:98-106
Timestamp: 2025-09-30T05:28:39.685Z
Learning: In the ShapeShift web codebase, the "More" menu on the asset page (containing watch/unwatch, view on explorer, and mark as spam actions) should always be visible on both mobile and desktop, regardless of whether a wallet is connected or whether the wallet supports the asset's chain. Individual actions within the menu can handle their own disabled states, but the menu itself should not be gated behind wallet connection checks.
Applied to files:
.claude/skills/chain-integration/SKILL.md
🪛 markdownlint-cli2 (0.18.1)
.claude/skills/chain-integration/SKILL.md
70-70: Bare URL used
(MD034, no-bare-urls)
71-71: Bare URL used
(MD034, no-bare-urls)
82-82: Fenced code blocks should have a language specified
(MD040, fenced-code-language)
94-94: Fenced code blocks should have a language specified
(MD040, fenced-code-language)
106-106: Fenced code blocks should have a language specified
(MD040, fenced-code-language)
161-161: Bare URL used
(MD034, no-bare-urls)
1004-1004: Emphasis used instead of a heading
(MD036, no-emphasis-as-heading)
1008-1008: Bare URL used
(MD034, no-bare-urls)
⏰ Context from checks skipped due to timeout of 90000ms. You can increase the timeout in your CodeRabbit configuration to a maximum of 15 minutes (900000ms). (1)
- GitHub Check: Call / Static
🔇 Additional comments (1)
.claude/skills/chain-integration/SKILL.md (1)
1-1343: Comprehensive chain integration skill is well-structured, complete, and accurately reflects recent integration patterns.This documentation skill successfully consolidates integration experience from Monad, Tron, and Sui with clear phase-driven guidance, proper EVM/non-EVM split paths, 60+ file checklist, and 10 well-documented gotchas with concrete PR references. The technical examples follow established ShapeShift patterns and the Verdaccio workflow reflects best practices for local hdwallet testing.
Key strengths:
- Clear activation conditions and use cases (lines 11-17)
- Excellent critical understanding section distinguishing second-class vs first-class patterns (lines 19-46)
- Proper research/discovery phase (Phase 0) with interactive Claude UI guidance (lines 49-177)
- Clean EVM vs non-EVM decision tree with accurate complexity estimates (lines 181-218)
- Detailed phase-by-phase guidance with template code patterns
- Comprehensive file checklist organized by category and criticality
- Practical gotchas with specific PR references for verification
Minor observations:
- Markdown style issues (bare URLs, code block languages, emphasis-as-heading) noted in separate comments
- Personal filesystem paths should be generalized for broader reusability
- Consider adding a section on when to prefer working with maintainers vs independent integration
0xApotheosis
left a comment
There was a problem hiding this comment.
Dude this is wild. Untested, but reviewed - certainly looks like it'll do the do, get straight in 🫡
Description
Add comprehensive chain integration skill for integrating new blockchains as second-class citizens in ShapeShift Web and HDWallet.
The skill provides complete documentation covering the entire workflow from HDWallet native support through Web integration, based on recent successful integrations (Monad, Tron, Sui).
Key Features:
Integration Paths:
Covers:
1343 lines of production-ready documentation.
Issue (if applicable)
N/A - Improves chain integration reliability with documented gotchas from recent work
Risk
Low - Documentation only, no code changes
None - this is a skill/documentation file to guide future chain integrations
Testing
Engineering
N/A - Documentation/skill file only. Will be used for next chain integration.
Operations
N/A - Documentation only
Screenshots (if applicable)
N/A - Skill documentation
🤖 Generated with Claude Code
Co-Authored-By: Claude [email protected]
Summary by CodeRabbit
✏️ Tip: You can customize this high-level summary in your review settings.