WalletConnect가 작동하지 않나요? 일반적인 문제 및 수정 사항

연결 초기화 실패

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 엔드포인트는 세션 설정 중에 지갑에 전파되지 않습니다. 지갑은 기본 엔드포인트를 사용하므로 일치하지 않는 블록 높이 및 nonce 오류가 발생합니다.

지갑 측 호환성 격차

1. 이전 지갑 버전은 WalletConnect v2.0의 대칭 암호화 모델에 대한 지원이 부족하여 v1.0 프로토콜로 대체되지 않고 핸드셰이크 시도가 실패합니다.

2. 하드웨어 지갑 통합은 세션 제안 중에 필요한 증명 증명을 생략하여 보안 요소 지원 서명자에 대한 WalletConnect의 보안 요구 사항을 위반합니다.

3. 맞춤형 UI 흐름을 구현하는 지갑은 WalletConnect의 표준화된 모달 동작을 재정의하여 일관된 콜백 타이밍에 대한 dApp의 기대를 깨뜨립니다.

4. 16진수 문자열에 대한 지갑별 인코딩 방식은 이더리움의 표준 바이트 배열 직렬화에서 벗어나 주소 확인 중에 체크섬 불일치가 발생합니다.

5. 지갑은 이 정책을 dApp 개발자에게 노출하지 않고 세션 기간을 7일로 제한하므로 장기 실행 스테이킹 또는 거버넌스 인터페이스 중에 예기치 않은 세션 만료가 발생합니다.

디버깅 및 진단 도구

1. WalletConnect Explorer 대시보드는 실시간 릴레이 로그를 제공하지만 시스템 전체에 걸쳐 동기화되지 않은 시계로 인해 dApp 클라이언트 타임스탬프와의 수동 상관 관계가 필요합니다.

2. SDK 디버그 모드는 명시적인 활성화Logging: true 플래그로 초기화된 경우에만 자세한 콘솔 출력을 내보냅니다. 기본 구성은 모든 진단 추적을 억제합니다.

3. 릴레이 상태 엔드포인트는 부분적인 서비스 저하 중에도 HTTP 200을 반환하여 간헐적인 메시지 전달 실패를 마스킹합니다.

4. WalletConnect CLI 도구는 URI 구조를 검증하지만 플랫폼별 구문 분석 엣지 케이스가 누락되어 실제 모바일 딥 링크 확인을 시뮬레이션하지 않습니다.

5. 브라우저 확장 인젝터는 WalletConnect의 iframe 통신 계층을 방해하여 기본 SDK 핸들러와 경쟁하는 중복 이벤트 리스너를 주입합니다.

자주 묻는 질문

Q: 지갑이 QR 코드를 성공적으로 스캔했는데도 dApp에 "Connection timed out"이 표시되는 이유는 무엇입니까? A: 이는 릴레이 서버가 구성된 제한 시간 내에 지갑에서 dApp으로 승인 이벤트를 전달하지 못할 때 발생합니다. 이는 주로 네트워크 정체 또는 릴레이 로드 불균형으로 인해 발생합니다.

Q: 동일한 루트 도메인의 여러 하위 도메인에서 WalletConnect 세션을 재사용할 수 있습니까? A: 아니요. 각 하위 도메인은 브라우저에서 별도의 원본으로 처리되므로 별도의 세션 초기화 및 저장소 격리가 필요합니다.

Q: 내 dApp이 Content-Security-Policy 헤더를 사용할 때 WalletConnect가 실패하는 이유는 무엇입니까? 답변: 엄격한 CSP 지시문은 'unsafe-inline' 또는 특정 nonce 값이 허용되지 않는 한 WalletConnect의 iframe 기반 통신 계층에서 사용되는 동적 스크립트 삽입을 차단합니다.

Q: 지갑이 일괄 요청과 같은 WalletConnect v2.0의 선택적 기능을 지원하는지 어떻게 확인합니까? A: session.getNamespaces() 를 통해 지갑의 기능을 쿼리하고 eth_sendTransactionBatch 가 있는지 메서드 배열을 검사합니다.