Web3 Frontend

判断ルール: 新規プロジェクトまたは wagmi 使用時は viem を推奨。既存 ethers.js プロジェクトの場合はユーザーに移行の意向を AskUserQuestion で確認する。

ワークフロー

Step 1: プロジェクト検出と技術スタック判定

1. package.json を読み込み、以下の依存関係を確認する:
   • viem / ethers → Ethereum クライアントの判定
   • wagmi / @wagmi/core → React hooks 使用有無
   • @rainbow-me/rainbowkit / connectkit → ウォレット UI の判定
   • @tanstack/react-query → 状態管理の確認
   • next / react → フレームワークの判定
2. tsconfig.json の存在で TypeScript プロジェクトか判定する。
3. 既存のウォレット接続コードを Grep で検出する:
   • createConfig, useAccount, useConnect → wagmi 使用中
   • ethers.providers, new ethers.Contract → ethers.js 使用中

検証ゲート: package.json が存在し、少なくとも 1 つの Web3 ライブラリが検出されること。Web3 ライブラリが未検出の場合は、AskUserQuestion で使用するスタックを確認する。

Step 2: スタック選択とリファレンス読み込み

Step 1 の結果に基づき、必要なリファレンスを選択して読み込む:

判断が不明な場合: 複数のアプローチが考えられる場合は AskUserQuestion で要件を確認してからリファレンスを選択する。

検証ゲート: 少なくとも 1 つのリファレンスファイルが正常に読み込めること。

Step 3: コード生成

1. Step 2 で選択したパターンに基づきコードを生成する。
2. 以下の共通原則を適用する:
   • TypeScript の型安全性を最大限活用する（ABI からの型推論を含む）
   • コントラクトアドレスはチェーン ID ごとに管理する
   • エラーハンドリングはユーザーフレンドリーなメッセージに変換する
   • ウォレット未接続状態を常に考慮する
3. ABI の取り扱い:
   • as const アサーションで ABI を定義し、viem の型推論を有効にする
   • ABI は abi/ ディレクトリに分離配置を推奨

検証ゲート: 生成コードが TypeScript コンパイルを通ること（npx tsc --noEmit で確認可能）。

Step 4: テスト・動作確認

1. ユニットテスト:
   • hooks のテストは @wagmi/test のモックプロバイダーを使用
   • コントラクト操作のテストは viem の createTestClient を使用
2. 統合テスト:
   • anvil（Foundry のローカルノード）でローカルチェーンを起動してテスト
   • cast でテストデータのセットアップ

検証ゲート: テストが全件パスすること。テストフレームワーク未導入の場合は AskUserQuestion でテスト方針を確認する。

使用例

例 1: ウォレット接続の実装

ユーザー入力: 「RainbowKit でウォレット接続を実装して」

アクション:

1. Step 1: package.json を確認 → wagmi + RainbowKit が依存に存在
2. Step 2: references/wallet-connection.md を読み込み → RainbowKit セクションを選択
3. Step 3: 以下を生成:
   • wagmi.config.ts — チェーン設定、トランスポート定義
   • providers.tsx — WagmiProvider + QueryClientProvider + RainbowKitProvider のラッピング
   • ConnectButton コンポーネントの配置
4. Step 4: ローカルで接続テスト

結果: RainbowKit のウォレット接続 UI が動作し、接続後にアドレスが表示される。

例 2: ERC20 トークン残高表示

ユーザー入力: 「ユーザーのウォレットにある USDC 残高を表示したい」

アクション:

1. Step 1: プロジェクト検出 → wagmi + viem を確認
2. Step 2: references/viem-patterns.md（コントラクト読取）+ references/wagmi-hooks.md（useReadContract）を読み込み
3. Step 3: 以下を生成:
   • ERC20 ABI（balanceOf, decimals, symbol のみ）を as const で定義
   • useReadContract で balanceOf を呼び出すカスタム hook
   • formatUnits でデシマル変換した表示コンポーネント
4. Step 4: テストクライアントでモック残高を設定してテスト

結果: 接続ウォレットの USDC 残高が正しいデシマルで表示される。

例 3: トランザクション送信 UX

ユーザー入力: 「NFT ミントのトランザクション送信画面を作って。進捗表示もほしい」

アクション:

1. Step 1: プロジェクト検出 → wagmi 確認
2. Step 2: references/transaction-ux.md（トランザクションライフサイクル）+ references/wagmi-hooks.md（useWriteContract）を読み込み
3. Step 3: 以下を生成:
   • useWriteContract + useWaitForTransactionReceipt を組み合わせたカスタム hook
   • 4 段階の進捗表示: idle → pending（署名待ち）→ confirming（ブロック確認待ち）→ success / error
   • ガス見積もりの事前表示（estimateContractGas）
   • エラー時のリトライボタンとユーザーフレンドリーなエラーメッセージ
4. Step 4: anvil でミントコントラクトをデプロイしてテスト

結果: NFT ミントの全ライフサイクルが視覚的にフィードバックされる UI が完成。

トラブルシューティング

1. ウォレット接続が失敗する

症状: ConnectButton を押してもウォレットが接続されない / エラーが出る

原因と対策:

• WalletConnect projectId 未設定: RainbowKit / ConnectKit は WalletConnect v2 の projectId が必須。cloud.walletconnect.com でプロジェクトを作成し、環境変数で設定する。
• チェーン設定の不一致: wagmi.config.ts のチェーン設定がウォレットの接続チェーンと一致しない。chains 配列を確認する。
• SSR 環境での window 未定義: Next.js の SSR で window.ethereum にアクセスしている。'use client' ディレクティブの付与と、動的インポートまたは mounted state ガードを確認する。

2. チェーン切り替えが動作しない

症状: useSwitchChain が失敗する / ユーザーにチェーン追加プロンプトが出ない

原因と対策:

• wagmi 設定にターゲットチェーン未追加: chains 配列にターゲットチェーンが含まれているか確認する。
• カスタムチェーンの RPC URL 不正: transports でチェーン ID ごとに正しい RPC URL が設定されているか確認する。
• ウォレット側の制限: 一部のウォレットはプログラマティックなチェーン追加をサポートしない。switchChain のエラーをキャッチし、手動切り替えの案内を表示する。

3. コントラクト呼び出しが reverted する

症状: useWriteContract が ContractFunctionRevertedError を返す

原因と対策:

• ABI の不一致: デプロイ済みコントラクトの ABI と定義した ABI が異なる。Etherscan / ブロックエクスプローラーから最新 ABI を取得する。
• 引数の型エラー: BigInt を期待する引数に Number を渡している。parseEther, parseUnits で正しく変換する。
• ガス不足: estimateContractGas で事前にガスを見積もり、十分な残高があるか確認する。
• 権限不足: コントラクトの onlyOwner 等の修飾子に引っかかっている。接続アドレスの権限を確認する。

4. RPC レート制限エラー

症状: 429 Too Many Requests または接続タイムアウト

原因と対策:

• 公開 RPC の制限: 本番では Alchemy / Infura 等の有料 RPC プロバイダーを使用する。
• リクエストの過剰発行: useReadContract の query.refetchInterval が短すぎる。適切な間隔（10-30秒）に設定する。
• フォールバック RPC: fallback トランスポートで複数の RPC エンドポイントを設定し、フェイルオーバーを実装する。

5. TypeScript の型エラー

症状: ABI から型が推論されない / unknown 型になる

原因と対策:

• ABI に as const がない: ABI 定義に as const アサーションを付与する。外部ファイルからインポートする場合も satisfies Abi + as const を使用する。
• wagmi / viem のバージョン不整合: wagmi と viem のメジャーバージョンが対応しているか確認する（wagmi v2 は viem v2 が必要）。

注意事項

• 秘密鍵をフロントエンドに含めない: 秘密鍵の管理はウォレット側の責務。フロントエンドでは writeContract でトランザクションを構築し、ウォレットに署名を委譲する。
• RPC エンドポイントの保護: 公開 RPC はレート制限あり。本番では API キー付きの RPC プロバイダーを使用し、サーバーサイドプロキシで API キーを隠蔽する。
• チェーン ID の型安全性: viem はチェーン ID を型レベルで管理する。mainnet, sepolia 等の定義済みチェーンオブジェクトを使用し、マジックナンバーを避ける。
• ethers.js v5 → v6 / viem への移行: 既存プロジェクトの移行は段階的に行う。viem は ethers.js と共存可能。
• 基盤的なスマートコントラクトの知識（Solidity 言語、セキュリティ、テスト）は solidity-core を参照する。
• DeFi / NFT / ガバナンス等のドメイン固有パターンは対応する Solidity スキルを参照する。