ウォレットコネクトが機能しない場合よくある問題と解決策

接続の初期化の失敗

1. dApp とウォレットの間のチェーン ID が一致しないため、WalletConnect セッションの開始に失敗します。 dApp は、接続リクエストでターゲットのブロックチェーン ネットワーク ID を明示的に宣言する必要があります。宣言しない場合、ウォレットはハンドシェイクを拒否します。

2. URI パラメータが欠落しているか不正な形式であると、モバイル デバイスで適切なディープリンクが妨げられます。 Android インテント フィルターと iOS ユニバーサル リンク構成は、WalletConnect に必要なスキーマ形式と正確に一致する必要があります。

3. ブラウザベースの dApp は、WalletConnect リレー サーバーへの WebSocket 接続を確立しようとすると CORS 制限に遭遇します。これにより、適切なプロキシ ヘッダーまたはリレー エンドポイントが設定されていない限り、ハンドシェイクの完了がブロックされます。

4. ユーザー エージェント検出ロジックがデスクトップ ブラウザをモバイルとして誤って識別し、直接ペアリングではなくサポートされていない QR コード フローをトリガーします。これにより、実行可能な UI 要素のない空のモーダル表示が発生します。

5. ネットワーク遅延が長い状態では、リレー サーバーのタイムアウトしきい値を超えます。デフォルトの15秒のタイムアウトでは、ウォレットの承認が登録される前にセッションが途中で中止されます。

セッション永続性の内訳

1. ユーザーが dApp タブから移動するか、ブラウザ ウィンドウを閉じると、セッション ストレージが意図せずクリアされます。ウォレットが再起動後もペアリングメタデータを保持しない場合、LocalStorage ベースのセッションリカバリは失敗します。

2. 同じオリジンから開始された複数の同時セッションは、互いのセッション状態を上書きします。これにより、ウォレットが古いトランザクション コンテキストに署名する、一貫性のない署名リクエストが発生します。

3. WalletConnect v2.0 のトピックベースの暗号化キーは、元のキー導出パスを保存せずに、アプリのリロード時に再生成されます。後続のメッセージの復号化はサイレントに失敗します。

4. Chromium ベースのブラウザでのバックグラウンド タブの調整により、WalletConnect イベント リスナーが一時停止され、セッション承認通知の遅延または欠落が発生します。

5. モバイル OS のメモリ管理は、セッション確認が完了する前にバックグラウンドのウォレット プロセスを強制終了し、dApp を無期限の保留状態のままにします。

署名およびトランザクション処理エラー

1. EIP-1559 トランザクションパラメータがペイロード内で省略されているか形式が間違っているため、ウォレットは従来のガス価格にフォールバックし、リクエストを完全に拒否します。

2. トランザクション ペイロードが、WalletConnect リレー インフラストラクチャによって課せられる 1MB のサイズ制限を超えます。大規模な契約のデプロイメントまたはバッチ操作では、サイレント切り捨てがトリガーされます。

3. ウォレットは、dApp オリジンで厳密なドメイン検証を強制しますが、拒否理由はエラー メッセージで明らかにされません。開発者には、有効な署名要求にもかかわらず、一般的な「ユーザーが拒否されました」と表示されます。

4. マルチチェーン dApp は、チェーン切り替え後にアクティブなセッションの名前空間を更新できません。ウォレットは以前のチェーンで署名を続け、無効な署名を生成します。

5. dApp で構成されたカスタム RPC エンドポイントは、セッションの確立中にウォレットに伝播されません。ウォレットはデフォルトのエンドポイントを使用するため、ブロックの高さの不一致とノンスエラーが発生します。

ウォレット側の互換性ギャップ

1. ウォレットの古いバージョンでは、WalletConnect v2.0 の対称暗号化モデルがサポートされていないため、ハンドシェイク試行が失敗し、v1.0 プロトコルへのフォールバックが行われません。

2. ハードウェアウォレットの統合により、セッション提案中に必要な認証証明が省略され、安全な要素に裏付けられた署名者に対する WalletConnect のセキュリティ要件に違反します。

3. カスタム UI フローを実装するウォレットは、WalletConnect の標準化されたモーダル動作をオーバーライドし、dApp が期待する一貫したコールバック タイミングを破ります。

4. 16 進文字列のウォレット固有のエンコード方式は、イーサリアムの正規のバイト配列シリアル化から逸脱しており、アドレス検証中にチェックサムの不一致が発生します。

5. ウォレットは、このポリシーを dApp 開発者に公開せずにセッション期間を 7 日間に制限するため、長時間実行されるステーキングまたはガバナンス インターフェイス中に予期しないセッション期限切れが発生します。

デバッグおよび診断ツール

1. WalletConnect Explorerダッシュボードはリアルタイムのリレーログを提供しますが、システム間でクロックが同期していないため、dAppクライアントのタイムスタンプと手動で相関させる必要があります。

2. SDK デバッグ モードは、明示的なenableLogging: trueフラグで初期化された場合にのみ、詳細なコンソール出力を出力します。デフォルト設定では、すべての診断トレースが抑制されます。

3. リレーの健全性ステータス エンドポイントは、部分的なサービス低下中でも HTTP 200 を返し、断続的なメッセージ配信の失敗を隠します。

4. WalletConnect CLI ツールは URI 構造を検証しますが、実際のモバイル ディープリンク解決をシミュレートせず、プラットフォーム固有の解析エッジ ケースが欠落しています。

5. ブラウザ拡張機能インジェクターは、WalletConnect の iframe 通信層に干渉し、ネイティブ SDK ハンドラーと競合する重複したイベント リスナーを挿入します。

よくある質問

Q: ウォレットが QR コードを正常にスキャンしたにもかかわらず、dApp に「接続がタイムアウトしました」と表示されるのはなぜですか? A: これは、リレーサーバーが、設定されたタイムアウトウィンドウ内にウォレットから dApp に承認イベントを転送できなかった場合に発生します。多くの場合、ネットワークの輻輳やリレーの負荷の不均衡が原因です。

Q: 同じルート ドメインの異なるサブドメイン間で WalletConnect セッションを再利用できますか? A: いいえ。各サブドメインはブラウザーによって個別のオリジンとして扱われるため、個別のセッション初期化とストレージ分離が必要になります。

Q: dApp が Content-Security-Policy ヘッダーを使用すると、WalletConnect が失敗するのはなぜですか? A: 厳密な CSP ディレクティブは、「unsafe-inline」または特定の nonce 値が許可されない限り、WalletConnect の iframe ベースの通信層で使用される動的スクリプト インジェクションをブロックします。

Q: ウォレットがバッチリクエストなどの WalletConnect v2.0 のオプション機能をサポートしているかどうかを確認するにはどうすればよいですか? A: session.getNamespaces()を介してウォレットの機能をクエリし、メソッド配列にeth_sendTransactionBatchが存在するか調べます。