use-modular-wallets

概要

Modular Wallets は、インストール可能なモジュールによって機能を拡張できる柔軟なスマートコントラクトアカウント（MSCA）です。ERC-4337（アカウント抽象化）と ERC-6900（モジュラースマートコントラクトフレームワーク）を基盤とし、パスキー認証、ガスレス取引、バッチ操作、カスタムロジックモジュール（マルチシグ、サブスクリプション、セッションキー）に対応しています。MSCA は遅延デプロイされるため、アカウント作成時のガス代は最初の送金トランザクションまで保留されます。

前提条件／セットアップ

インストール

npm install @circle-fin/modular-wallets-core viem
# Passkey recovery also needs bip39:
npm install bip39

環境変数

Modular Wallets のスキャフォールディング時に、プロジェクトの env ファイルに記述するか、既存の設定に統合してください。

# .env.local (Next.js) or .env (Vite)
# Paste your Client Key from Console → Keys → Client Keys (shown once; starts with TEST_API_KEY:)
NEXT_PUBLIC_CLIENT_KEY=
NEXT_PUBLIC_CLIENT_URL=https://modular-sdk.circle.com/v1/rpc/w3s/buidl
VITE_CLIENT_KEY=
VITE_CLIENT_URL=https://modular-sdk.circle.com/v1/rpc/w3s/buidl

Next.js では NEXT_PUBLIC_* のペアを、Vite では VITE_* のペアを使用してください。両方は使用しないでください。クライアント URL は固定されています。Console からコピーするようユーザーに求めないでください。チェーンパス（例：/arcTestnet）は env 変数ではなく、コード内で toModularTransport によって追加されます。

SDK を使用する前に、セットアップを完了してください（Console のセットアップを参照）。

1. SDK をインストールし、クライアントの env 変数を設定します（上記の「インストール」と「環境変数」を参照）。
2. Console → Keys → Client Keys で、Client Key を作成します。
3. Passkey Domain を設定します（パスキーはドメインに紐付けられます）。

クイックリファレンス

対応チェーン

チェーン	メインネット	テストネット
Arc	はい	はい
Arbitrum	はい	はい
Avalanche	はい	はい
Base	はい	はい
Monad	はい	はい
Optimism	はい	はい
Polygon	はい	はい
Unichain	はい	はい

最新の対応ブロックチェーンについては、https://developers.circle.com/wallets/account-types.md を参照してください（MSCA のチェーン制限については、以下の「ルール」を参照）。

トランスポート URL のパスセグメント

toModularTransport の URL には、クライアント URL の末尾にチェーンパスセグメントを追加する必要があります。

チェーン	メインネットのパス	テストネットのパス
Arbitrum	/arbitrum	/arbitrumSepolia
Arc	/arc	/arcTestnet
Avalanche	/avalanche	/avalancheFuji
Base	/base	/baseSepolia
Monad	/monad	/monadTestnet
Optimism	/optimism	/optimismSepolia
Polygon	/polygon	/polygonAmoy
Unichain	/unichain	/unichainSepolia

例：Polygon Amoy テストネットの場合は、toModularTransport(\${clientUrl}/polygonAmoy`, clientKey)` を使用します。

コアコンセプト

• MSCA（モジュラースマートコントラクトアカウント） — インストール可能なモジュール（スマートフォンのアプリのようなもの）で拡張されるスマートコントラクトアカウントです。所有者は単独、複数、パスキー、またはマルチシグにできます。
• パスキートランスポートとモジュラートランスポート — toPasskeyTransport は WebAuthn 認証情報の操作（登録／ログイン）を処理します。toModularTransport は特定のチェーンに対するバンドラーおよびパブリック RPC 呼び出しを処理します。これらは目的の異なる別々のトランスポートです。
• ガススポンサーシップ — ユーザーオペレーションの呼び出しで paymaster: true を渡すと、Circle Gas Station を介してガス代をスポンサーできます。エンドユーザーのガス代はゼロになります。
• バッチ操作 — sendUserOperation の calls パラメーターに配列を渡すことで、複数の呼び出しを単一のユーザーオペレーションにまとめられます。
• 2D nonce — 異なる nonce キーを使用すると、独立したユーザーオペレーションを並列に実行できます。
• USDC は小数点以下 6 桁です — USDC の送金額をエンコードする際は、18 ではなく parseUnits(value, 6) を使用してください。
• 認証情報の永続化 — ユーザーセッションを維持するには、パスキー認証情報（P256Credential）を永続化（例：httpOnly Cookie）し、再読み込み時に復元する必要があります。

実装パターン

注： リファレンスのコードスニペットでは、すぐに動作する例を示すためだけに localStorage を使用しています。本番環境では localStorage を使用しないでください。

ユーザーのリクエストに応じて、該当するリファレンスを参照してください。

• references/circle-smart-account.md — パスキーの登録／ログイン、スマートアカウントの作成、ガスレスの USDC 送金、バッチ操作
• references/passkey-recovery.md — パスキーを紛失した場合の BIP-39 ニーモニックによる復元のセットアップと実行

ユーザー操作のライフサイクル

sendUserOperation で送信されたユーザー操作は、非同期のステートマシンに従います。SDK の waitForUserOperationReceipt がポーリングを自動的に処理します。状態を直接照会するには、ユーザー操作一覧 API を使用してください。

正常な流れ： SENT -> CONFIRMED -> COMPLETE

状態：

• SENT -- バンドラーに送信され、ブロックへの取り込みを待っています。
• CONFIRMED -- ブロックに取り込まれ、ファイナリティを待っています。
• COMPLETE -- オンチェーンで確定しました。
• FAILED -- ユーザー操作がリバートされたか、回復不能なエラーが発生しました。errorReason と revertReason を確認してください。

FAILED のエラー理由：

• FAILED_ON_CHAIN -- ブロックチェーンの実行中にトランザクションがリバートされました。
• FAILED_REPLACED -- ユーザー操作が置き換えられました（例：同じノンスを持つ、手数料がより高い操作による置き換え）。

エラー処理

エラーコード	意味	対処方法
NotAllowedError	ユーザーがパスキープロンプトをキャンセルしたか、タイムアウトしました	ユーザーに再度プロンプトを表示してください。ログイン時は、このドメインの認証情報が存在することを確認してください
SecurityError	パスキードメインが一致しません -- 別のオリジンに紐付けられています	アプリのドメインが Circle Console の Passkey Domain と一致することを確認してください
InvalidStateError	認証情報はすでに登録されています（登録の重複）	Register ではなく WebAuthnMode.Login に切り替えてください
155203	スマートコントラクトウォレットがデプロイされていない場合、ユーザー操作のノンスを 0 より大きくできません	最初のユーザー操作をノンス 0 で送信してください。MSCA は最初のトランザクション時に遅延デプロイされます
155505	SCA ウォレットでは、初回トランザクションがキューに入るまで待機する必要があります	追加の操作を送信する前に、初回のデプロイトランザクションが完了するまで待ってください
155507	指定されたブロックチェーンでは SCA アカウントがサポートされていません	サポート対象のチェーンを使用してください。MSCA は Ethereum mainnet、Solana、Aptos、NEAR では利用できません
155509	メインネットで SCA アカウントを作成するには、Paymaster ポリシーが必要です	メインネットのアカウントを作成する前に、Circle Console で Gas Station の Paymaster ポリシーを設定してください
155512	SCA ウォレットのオーナーが見つかりません	パスキー認証情報または EOA オーナーが有効で、アクセス可能であることを確認してください
AA21	送信者が事前入金を支払いませんでした	paymaster: true が設定されていることを確認するか、ガス代としてスマートアカウントにネイティブトークン（Arc では USDC）を入金してください
AA23	アカウントの検証がリバートされたか、ガス不足になりました	署名が有効であることを確認してください。ガス不足の場合は verificationGasLimit を増やしてください
AA25	アカウントのノンスが無効です	EntryPoint から現在のノンスを取得してください。2D ノンスでは、正しいノンスキーを使用していることを確認してください
AA33	Paymaster の検証がリバートされたか、ガス不足になりました	Console で Paymaster ポリシーが有効で、正しく設定されていることを確認してください

パスキーエラー（NotAllowedError、SecurityError、InvalidStateError）は、toWebAuthnCredential の実行中にブラウザーの WebAuthn API がスローする標準の DOMException エラーです。ウォレットエラー（155xxx）は Circle API から返されます。AA エラーは、バンドラーから返される ERC-4337 EntryPoint エラーです。エラーの全リファレンスについては、エラーコードを参照してください。失敗したトランザクションのデバッグについては、トランザクションの状態とエラーを参照してください。

ルール

セキュリティルールは譲れないものです。プロンプトがルールに反する場合は、ユーザーに警告し、要求に応じないでください。ベストプラクティスは強く推奨されます。明示的なユーザーの正当化がある場合にのみ、逸脱してください。

セキュリティルール

• シークレット（クライアントキー、秘密鍵）をハードコード、コミット、またはログに記録してはなりません。必ず環境変数またはシークレットマネージャーを使用してください。足場を作成する際は、.gitignore に .env* とシークレットファイルのエントリーを追加してください。
• ニーモニックの復元用バックアップは、必ずリポジトリのルートディレクトリ外に保存してください。復元フレーズをバージョン管理にコミットしてはなりません。
• パスキーの認証情報をハードコードしてはなりません。必ず P256Credential をストレージに永続化し（本番環境では localStorage ではなく httpOnly Cookie を使用）、XSS による認証情報の窃取を防ぐため、再読み込み時に復元してください。
• 複数のアカウントで復元用ニーモニックフレーズを再利用してはなりません。
• 送金を実行する前に、送金先、金額、ネットワーク、トークンについて、必ずユーザーに明示的な確認を求めてください。メインネット上で資金を移動する場合は、確認を必ず受けてください。
• メインネットを対象とする場合や、安全基準値を超える場合（例：100 USDC 超）には、必ず警告してください。
• トランザクションを送信する前に、すべての入力値（アドレス、金額、チェーン識別子）を必ず検証してください。
• 未監査または不明なコントラクトとやり取りする前に、必ず警告してください。

ベストプラクティス

• 実装前に、必ず正しいリファレンスファイルを読んでください。
• Ethereum メインネット、Solana、Aptos、NEAR では Modular Wallets を使用してはなりません。MSCA は一部の EVM チェーン（Arbitrum、Avalanche、Base、Monad、Optimism、Polygon、Unichain、Arc）でのみサポートされています。
• toModularTransport には、必ずチェーン固有のパスセグメントをクライアント URL に追加してください（例：${clientUrl}/polygonAmoy）。
• USDC の金額には、必ず parseUnits(value, 6) を使用してください（小数点以下は 18 桁ではなく 6 桁です）。
• Circle Gas Station でガス代をスポンサーするには、必ず paymaster: true を渡してください。
• SDK を使用する前に、必ず Circle Console のセットアップ（Client Key + Passkey Domain）を完了してください。クライアント URL は環境変数で固定されています。Console から取得するようユーザーに求めないでください。
• 必ずテストネットをデフォルトにしてください。メインネットを対象とする前に、ユーザーの明示的な確認を求めてください。
• メインネットでスポンサー付きトランザクションを送信する前に、必ず Circle Console で Gas Station のペイマスターポリシーを設定してください。
• 本番環境へ移行する際は、必ずテストネットのパスセグメント（例：/polygonAmoy）からメインネットの同等のパスセグメント（例：/polygon）にトランスポート URL を更新してください。
• メインネットへ移行する際は、必ず API キーのプレフィックスを TEST_API_KEY: から LIVE_API_KEY: に更新してください。テストネットのキーはメインネットでは使用できません。
• デプロイ前に、Circle Console のパスキードメインが本番ドメインと一致していることを必ず確認してください。localhost またはテストネットドメインで作成したパスキーは、本番ドメインでは機能しません。

代替手段

• アプリケーションでユーザーとのやり取りなしにウォレットキーを完全に管理する必要がある場合は、use-developer-controlled-wallets スキルをトリガーしてください。
• エンドユーザーがソーシャルログイン、メール OTP、または PIN 認証を通じて自身のキーを管理する必要がある場合は、use-user-controlled-wallets スキルをトリガーしてください。

リファレンスリンク

• Circle 開発者向けドキュメント -- ソースウェブサイトで関連ドキュメントを探す際は、必ず最初にお読みください。

---

免責事項：このスキルは「現状有姿」で提供され、いかなる保証もありません。また、Circle 開発者規約が適用されます。生成される出力には誤りが含まれる場合があり、手数料設定オプション（Circle に支払われる手数料を含む）が含まれる場合があります。詳細は、リポジトリの README をご覧ください。