software-crypto-web3

ソフトウェア暗号資産／Web3 エンジニアリング

クイックリファレンス

タスク	デフォルト	使用する場面
EVM コントラクト	まず Foundry。プラグインを多用する TS ワークフローでは Hardhat	Solidity、DeFi、トークン標準、アップグレード可能なシステム
Solana プログラム	Anchor と最新の Solana SDK ガイダンス	Rust プログラム、SPL アセット、高スループットのアプリ
Cosmos コントラクト	CosmWasm	IBC ネイティブ、または Cosmos アプリチェーンのエコシステム
TON コントラクト	新規コントラクトには Tolk。対応ツールキットを TON ドキュメントで確認	Telegram での配布、TON ネイティブのウォレットとアセット
Bitcoin／Lightning	Bitcoin Core と BDK／LND のパターン	ウォレット、PSBT、決済、決済レール
アカウント抽象化	EOA には ERC-7702（委譲は持続するため、呼び出し元を保護する）、スマートアカウントには ERC-4337	トランザクションの一括処理、ガスのスポンサー提供、セッションキー、ソーシャルリカバリー
セキュリティレビュー	Slither、Echidna、Medusa、Halmos、Certora。監査ガイド	監査、デプロイ前レビュー、不変条件の適用
クロスチェーン	Chainlink CCIP、LayerZero、Wormhole、IBC	トークンブリッジ、クロスチェーンメッセージング、相互運用性
バックエンド統合	キューを利用する RPC クライアントと冪等なハンドラー	カストディ、入金、出金、Webhook／イベントの取り込み
調査	まず公式ドキュメント／仕様、その後にエコシステム分析	チェーンの選定、フレームワークの選択、最新のベストプラクティス

このスキルを使用する場面

• スマートコントラクトおよびブロックチェーンプログラムの開発
• DeFi、トークン、NFT、ガバナンス、ブリッジの統合
• バックエンドの暗号資産インフラ、カストディ、署名ワークフロー
• チェーンとフレームワークのトレードオフ分析
• セキュリティレビュー、監査準備、本番環境の強化

このスキルを使用しない場面

• ブロックチェーン要素のない一般的なバックエンド作業 → software-backend
• ウォレット／プロトコル統合のない、フロントエンド UI のみの作業 → software-frontend
• スマートコントラクトや暗号資産運用以外の一般的なアプリケーションセキュリティ → software-security-appsec
• Sui／Aptos での Move 実装は、このスキルのチェーン対応範囲外です。Sui Move または Aptos Move から始めてください。このスキルは共通のカストディおよび運用リスク管理に限って使用し、EVM／Anchor のコードを流用しないでください。

ワークフロー

1. ツールを推奨する前に、チェーン、製品の対象領域、カストディモデル、攻撃対象領域を特定します。
2. ブロックチェーンが付随的な要素である場合は、一般的なバックエンド、フロントエンド、または暗号資産以外の AppSec 作業を隣接するスキルに振り分けます。
3. 判断ツリーから、実用可能な最小限のプロトコルまたはフレームワークを選びます。
4. 実装の詳細を説明する前に、コントラクト、署名、決済、運用管理に関する実行時のデフォルトを適用します。
5. 最終的なガイダンスを提示する前に、該当する公式情報源でネットワークの対応状況とツールの成熟度を再確認します。Solana ではツールチェーンと拡張機能の確認事項を読み込み、TON では言語／ツールキットの選択を読み込んでください。

意思決定ツリー

製品の要件を満たす中で、最も小さな対応範囲を選んでください。

• エコシステムの充実度、監査実績、ツールの成熟度が最優先なら EVM
• スループットと低手数料が最優先で、チームが Rust を安全に運用できるなら Solana
• IBC ネイティブの相互運用性が必須要件なら CosmWasm
• Telegram ネイティブの配信が製品要件なら TON。言語を選ぶ前に Tolk とツールキットのガイダンスを確認してください
• コントラクトよりも決済の精算やウォレットが中心なら Bitcoin/Lightning

次を推奨します。

• EVM のテスト、ファジング、不変条件、ガススナップショットには Foundry
• プラグインエコシステムや TypeScript 中心のワークフローが主な要件なら Hardhat 3（Solidity テストをネイティブに実行できます。現在のリリース状況は hardhat.org で確認してください）。Nomic Foundation は将来のハードフォークごとに Hardhat 2 をアップグレードするわけではないため、Hardhat 2 からの移行を計画してください
• 対象 EVM と互換性があり、レビュー済みの Solidity コンパイラー。選択したオプティマイザー／IR パイプライン（トランジェントストレージの処理を含む）について、リリース と 既知のバグ を確認してください。コンパイラーのバージョンを正確に固定し、すべての pragma との互換性を保ってください。
• EOA の移行には ERC-7702（既存アドレスの履歴を維持でき、Pectra アップグレード以降利用可能です。委任は再委任するか、ゼロアドレスに委任して解除するまで持続します。そのため、委任コードは実行前に msg.sender == address(this) または署名を確認する必要があり、ウォレットは委任リクエストを高リスクのフィッシング対象として扱う必要があります）。新しいスマートアカウントや、完全なバンドラー／ペイマスターインフラストラクチャが必要な場合は ERC-4337 を使用してください。この 2 つは相互補完的で、併用が増えています。どちらか一方を選ぶものではありません
• ブリッジのセキュリティ（独立したリスク管理ネットワーク）を最優先する場合は Chainlink CCIP、より幅広いチェーンへの対応を優先する場合は LayerZero または Wormhole を使用してください。多額の価値を扱うブリッジを信頼する前に、現在の DVN／ガーディアンセットと監査状況を確認してください
• 現在のネットワーク対応状況、ブリッジの前提条件、運用成熟度を確認したうえでのみ L2 を使用してください。記憶に頼った市場シェアの数値を信じず、現在の流動性を L2Beat または DefiLlama で確認してください
• 独自のブリッジや暗号処理を実装するより、既存の監査済みプロトコルコンポーネントを優先してください

実行時のデフォルト

• コントラクト、署名サービス、Webhook エンドポイントをパブリックな攻撃対象領域として扱ってください
• 入金、出金、決済処理のハンドラーには冪等性を必須としてください
• 読み取り処理とトランザクション送信処理を分離してください
• ホットウォレットの自動処理にはレート制限を設け、高リスクの送金には承認を必須としてください
• 影響範囲を抑えられる場合は、許可リスト、タイムロック、一時停止機能、ロールバック計画を優先してください
• エコシステムの人気に関する主張を、最新の情報で確認せずに信頼してはいけません

デプロイ前のセキュリティチェックリスト

コントラクトまたはカストディフローを本番環境にデプロイする前に、次を確認してください。

• すべての外部呼び出しパスにリエントランシー対策を実装する（CEI パターンまたは ReentrancyGuard）
• アクセス制御：特権関数すべてに明示的なオーナー／ロールチェックがある
• 整数オーバーフロー：Solidity 0.8 以降のチェック付き算術演算を使用する（SafeMath は不要）。すべての unchecked ブロックについて、レビューで妥当性を確認する
• リプレイ対策：ノンス／有効期限の消費とドメインへの紐付け（チェーン、検証コントラクト、アクション）を実装する。EIP-712 形式だけでは、同一ドメイン内のリプレイを防止できない
• 入金／出金ハンドラー：冪等性キー、確認しきい値、DLQ を定義する
• オラクル入力：鮮度チェック（最大経過時間）を行う。価格情報の唯一の情報源を設けない
• 緊急制御：一時停止機構またはタイムロックをリハーサルでテストする
• アップグレード経路：プロキシ管理者キーは EOA ではなくマルチシグで管理する。アップグレード手順を文書化する
• ファズテストと不変条件テスト（Foundry、Echidna、または Medusa）に合格する。実行回数／深さの予算はプロトコルのリスクに応じて設定し、価値を扱うコードではツールのデフォルトを上回る値にする

カストディ、鍵管理、オンチェーンの判断

特権制御のゲート。 アップグレード、一時停止、ミント、凍結、オラクル、ブリッジ、手数料設定の各権限を、プロトコルのインターフェースの一部としてすべて洗い出してください。各権限について、署名者の構成、定足数、遅延時間、適用範囲、ローテーションの手順、障害発生時の影響を記録してください。フォークまたはローカルチェーンで、署名者が侵害された場合、署名者が利用できない場合、悪意のあるアップグレードが行われた場合のシナリオをテストしてください。マルチシグというラベルだけでは、特権操作が制約されていることや復旧可能であることの証明にはなりません。

• オンチェーンに記録しないもの：個人を特定できる情報、後から削除・訂正する必要があるもの（消去権との衝突）、定期的にオンチェーンでチェックポイント／ルートを記録すれば、オフチェーンのほうが安価で同等の信頼性を得られる高頻度の状態、そして公開検証可能性やトラストレスな決済ではなく、内部監査可能性のみを要件とするビジネスロジックです。オンチェーン化はコストと信頼性のトレードオフであり、デフォルトではありません。
• カストディの判断基準：
  • 単独／EOA 署名 — プロトタイプおよび非カストディアルの個人ウォレットに限ります。ユーザー資金をプールする用途には決して使わないでください。
  • マルチシグ（Safe または同等のもの） — トレジャリーおよび管理者／アップグレード用キーのデフォルトです。オンチェーンで承認に必要な署名数が透明になりますが、各署名者のデバイスとレビューの徹底度も信頼境界の一部になります（下記の署名基準を参照）。
  • MPC（閾値署名） — 大規模なホットウォレットの運用署名に適しています。プロトコルでは、完全なキーを再構成せずに、分散されたキーフラグメントを使って署名できます。閾値、独立したフラグメント／管理ドメイン、復旧方法、ポリシーのバイパス経路、ベンダーへの信頼を確認してください。フラグメントの更新と公開鍵の変更では、移行に伴う影響が異なります。
  • HSM — コールドキー／ルートキー、およびコンプライアンス制度で FIPS 検証済みハードウェアによる鍵管理が求められる場合に使用します。単独のオペレーターではなく、M-of-N のオペレーターアクセスと組み合わせてください。
  • 以下を基準に選択してください：リスクにさらされる価値、署名頻度、規制上のカストディ要件、そして防御対象となる障害モードがキーの窃取、内部関係者の共謀、ベンダーの侵害のどれかです。それぞれ必要な対策が異なります。
• 明示的な署名内容の確認基準：特権署名を行う前に、独自に取得したコントラクト／ABI データと照合し、宛先、チェーン、値、メソッド、受取人、承認対象、ネストされた呼び出しをデコードしてください。ウォレットが対応している場合は ERC-7730 の記述子を使用し、対応スキーマを確認したうえで、記述子をチェーン／アドレス／署名タイプにひも付けてください。不明または不一致の記述子や、重要なフィールドが不透明な場合は、独自にデコードするまで特権署名をブロックしてください。表示が読みやすくても、安全な意図であることの証明にはなりません。記述子レジストリや外部メタデータも信頼境界です。
• ウォレットのフロントエンドのサプライチェーン：依存関係とビルド入力を固定してレビューし、変更可能なサードパーティ製スクリプトを制限し、リリース／CDN の認証情報を保護し、配信されるアセットの出所を検証し、UI が侵害された場合を想定した訓練を実施してください。トレジャリー／管理者向けのフローでは、独立した署名経路で実際のペイロードを照合してください。侵害された dApp は、無害な要約を表示しながら別の署名を要求する可能性があります。
• テストネットとメインネットのデプロイ規律：テストネットのガス、メンプール、MEV、またはリオーグの挙動が、メインネットの挙動を予測すると決して考えないでください。実際の価値に影響するメインネットへのデプロイ前には、必ずメインネットのフォークシミュレーション（Foundry/Anvil または Tenderly）を通過させてください。また、メインネットのデプロイキーとアップグレードキーはテストネットのキーから分離し、テストネットが侵害されても本番環境に到達できないようにしてください。
• オラクル操作による障害モード：単一ブロックのスポット価格（DEX の生リザーブ、単一ソースのフィード）は、フラッシュローンを使って1回のトランザクション内で操作できます。時間加重平均（TWAP）または、古さと乖離のチェックを備えた集約型のプッシュ／プルオラクル（Chainlink、Pyth）を優先してください。清算や借入可能額を左右するものについては、「価格の真実を示す単一のソースがないこと」（上記のチェックリストを参照）を、あると望ましい程度ではなく必須要件として扱ってください。
• 署名権限を持つ LLM またはエージェント（取引、スワップ、トレジャリーの移動）：オンチェーンのテキスト、トークン名、フィード、Webhook によって、モデルがいつか有害なトランザクションを実行するよう説得されることを前提とし、以下のすべての制御がモデルの出力にかかわらず機能するようにしてください。プロンプトインジェクションに対するキーワードフィルターは簡単に回避されるため、制御策として数えないでください。
  • モデルと署名者の間にコードで適用する、トランザクション単位およびローリングウィンドウの支出上限。上限はローカルポリシーで設定します。
  • 各トランザクションをシミュレートし（eth_call またはフォーク）、最低出力と期限が設定され、シミュレーション結果がそれらを満たさない限り署名を拒否します。
  • ドローダウンと連続損失を検知するブレーカーを設け、取引を停止して、人間による再開を必須にします。状態が無効な場合（基準値がゼロまたは欠落している場合）も停止します。
  • セッション用の資金のみを入れた専用のホットウォレットを用意し、トレジャリーは使用せず、シークレットマネージャーからキーを取得します。サンドイッチ攻撃のリスクがある場合は、保護されたルーティング（プライベートメンプール）を使用してください。
  • 送信したトランザクションだけでなく、拒否または失敗したものも含む、すべてのモデルの判断を監査ログに記録します。

既知の落とし穴

• ガス、メンプール、リオーグに関する前提が、対象ネットワークでは通用しないにもかかわらず、ローカル環境やテストネットでの挙動に依存すること。
• コントラクトの状態、ウォレット残高、または最終決済システムが信頼できる情報源であるにもかかわらず、インデックス化されたイベントを信頼できる情報源として扱うこと。
• リプレイ保護、確認しきい値、冪等な記帳処理を設けずに、入金と出金のハンドラーを構築すること。
• ブリッジ、リレイヤー、ペイマスターの信頼境界を、製品の中核的なリスクではなく、インフラの詳細事項だと見なすこと。
• リハーサル済みのロールバック手順や凍結状態の手順がないまま、プロキシ、アカウント抽象化フロー、署名者ポリシーをアップグレードすること。
• チェーンの選択間違い、古い承認状態、署名の混同によって資金が失われる可能性があるにもかかわらず、ウォレット UX の失敗を無害だと見なすこと。

ナビゲーション

リソース：

• references/blockchain-best-practices.md - 汎用的なブロックチェーンアーキテクチャとセキュリティパターン
• references/backend-integration-best-practices.md - バックエンドのカストディ、Webhook、キュー、CQRS、プロバイダー抽象化（.NET/C# の例。アーキテクチャパターンは言語に依存しません）
• references/solidity-best-practices.md - EVM と Solidity に関するガイダンス
• references/rust-solana-best-practices.md - Solana と Anchor のパターン
• references/cosmwasm-best-practices.md - CosmWasm と IBC に関するガイダンス
• references/ton-best-practices.md - TON コントラクトとウォレット統合のパターン
• references/defi-protocol-patterns.md - AMM、レンディング、ボールト、ステーキング、オラクル
• references/nft-token-standards.md - ERC-20/721/1155、SPL アセット、NFT メタデータ
• references/cross-chain-bridges.md - ブリッジモデル、信頼に関する前提、リスク管理策
• references/operational-playbook.md - トピック別の参考資料インデックスと、オンチェーンデータとオフチェーンデータの比較表
• data/sources.json - 厳選された外部参考資料と調査の出発点

テンプレート：

• Ethereum/EVM：assets/ethereum/template-solidity-hardhat.md、assets/ethereum/template-solidity-foundry.md
• Solana：assets/solana/template-rust-anchor.md
• Cosmos：assets/cosmos/template-cosmwasm.md
• TON：assets/ton/template-tact-blueprint.md、assets/ton/template-func-blueprint.md
• Bitcoin：assets/bitcoin/template-bitcoin-core.md

関連スキル：

• ../software-security-appsec/SKILL.md - 脅威モデリングとセキュリティ強化
• ../software-backend/SKILL.md - バックエンドサービス、API、キュー、永続化
• ../software-code-review/SKILL.md - レビュープロセスと正確性の確認
• ../ops-devops-platform/SKILL.md - インフラ、CI/CD、可観測性、ノード運用
• ../qa-resilience/SKILL.md - 障害モード、再試行、サーキットブレーカー
• ../dev-api-design/SKILL.md - カストディおよびブロックチェーン連携サービスの API 境界

エコシステムの調査

フレームワーク、ネットワーク、ブリッジ、ウォレット機能を推奨する前に、公式のリリース／サポート資料と、実際にデプロイされている正確な構成を確認してください。エコシステム分析は、現在の流動性や普及状況を比較する場合にのみ使用してください。記憶に基づく市場シェアやスループットの数値は引用しないでください。選択に影響する情報源と信頼に関する前提を明記してください。

規制上の落とし穴（エンジニアリング上の制御のみ）

法的な位置づけ、ライセンス、期限はリーガルスキルが扱うため、ここでは繰り返しません。管轄区域にかかわらず、以下の制御を実装してください。

• トラベルルールの仕組み：弁護士が承認した管轄区域および送金ルールに基づき、必要な送金人／受取人のフィールド、セルフホスト型ウォレットの証拠、例外処理を設定します。「取引相手がトラベルルールに対応していない」状態を明示的にモデル化します。
• カストディの分別管理と照合：顧客資産を自社資産と分別管理します。オンチェーンと台帳の日次照合を出金のゲートとします。
• ステーブルコイン発行システム：弁護士が承認した発行者／資産の適格性、償還ルール、通貨圏ごとの交換手段に関するテレメトリーを実装します。しきい値をパラメーター化し、「発行停止」スイッチのリハーサルを行います。
• マーケティングのゲート：一般公開される募集ページやプロモーションは、最新バージョンのホワイトペーパーに基づく場合にのみ公開します。認可されていない管轄区域をジオゲートし、その判断を記録します。
• 分類に関する証拠：管理者キー、アップグレード経路、手数料切り替え、トークンの一意性に関するメタデータを保持します。NFTや「完全な分散化」の適用範囲は法務上の判断事項です。

チェックリスト：references/mica-casp-checklist.md。ステータスと期限：EU の適格な規制関連弁護士（MiCA、TFR）、米国の適格な規制関連弁護士（GENIUS Act の規則策定、CLARITY Act）、英国の適格な規制関連弁護士（FCA の暗号資産制度）。

学びのループ

過去の判断や落とし穴が関係する場合は、learnings.consolidated.md があれば参照してください。必要な履歴を確認する場合、または利用可能な代替手段としては learnings.md のみを使用します。それ以外の場合は、どちらも参照しません。

内容を適用した後、記憶する価値のあるパターン、防止すべきミス、または意外だった分野の事実に遭遇した場合は、agents-skills-feedback-loop/scripts/append_learning.py を使って learnings.md に日付入りの箇条書きを 1 つ追加します。SKILL.md 自体は変更しないでください。