연동 빠른 시작
완전한 연동은 다섯 부분으로 이루어집니다. 각 단계는 정확한 형식을 설명하는 페이지로 연결되며, 모든 형식에는 iPhone을 쓰기 전에 코드를 검증할 수 있는 테스트 벡터가 있습니다.
1. UR을 이해하는 QR 스캐너 추가
일반 주소를 제외한 BitTool Signer의 모든 QR 코드는 ur:<type>/로 시작하는 텍스트인 Uniform Resource(UR)입니다. 큰 페이로드는 애니메이션으로 표시되며, 여러 프레임이 모여 하나의 데이터를 전달합니다. 텍스트를 직접 파싱하지 말고 UR 디코더를 사용하세요.
| 플랫폼 | 라이브러리 |
|---|---|
| JavaScript / TypeScript | @ngraveio/bc-ur (BitTool Signer가 사용하는 라이브러리) |
| Swift | URKit |
| Kotlin / Java | Hummingbird |
| Rust | ur |
디코더가 완료를 알릴 때까지 스캔한 모든 프레임을 디코더에 넣으세요. 프레임은 순서와 상관없이 도착할 수 있고 반복될 수도 있습니다.
2. 페어링: 계정 가져오기
사용자에게 BitTool Signer에서 해당 지갑의 Connect(연결)를 열도록 안내하세요. 두 종류의 페어링 QR 코드를 제공합니다.
- Wallet level(지갑 레벨): Bitcoin(주소 유형 4개), EVM, TRON, Solana 주소 3개를 담은 애니메이션
ur:bytesQR 코드 하나입니다. 멀티체인 지갑에 가장 적합합니다. 지갑 레벨 QR을 참고하세요. - Coin level(코인 레벨): 체인마다 표준 QR 코드 하나(
ur:crypto-account,ur:crypto-hdkey,ur:crypto-multi-accounts또는 일반 주소)로, 다른 QR 서명 기기와 같은 형식입니다. 코인 레벨 QR을 참고하세요.
계정 xpub(또는 Solana 주소), 각 파생 경로, 그리고 마스터 지문(master fingerprint)을 저장하세요. 서명 요청을 만들려면 세 가지가 모두 필요합니다. 각 계정의 첫 번째 주소를 표시하고, 사용자가 BitTool Signer의 QR 코드 아래에 표시된 주소와 비교하도록 안내하세요.
3. 서명 요청 만들기
사용자가 송금하면 평소처럼 서명되지 않은 트랜잭션을 만든 다음, 체인별 요청 타입으로 감싸세요.
| 체인 | 요청 | 담기는 내용 |
|---|---|---|
| Bitcoin | ur:crypto-psbt | 모든 입력과 잔돈 출력에 bip32Derivation(지문 + 전체 경로)이 들어 있는 PSBT |
| EVM | ur:eth-sign-request | 서명되지 않은 RLP 트랜잭션, EIP-712 JSON 또는 메시지 바이트와 경로, 지문, 체인 ID, 주소 |
| TRON | ur:tron-sign-request | raw_data protobuf 바이트와 경로, 지문, 주소 |
| Solana | ur:sol-sign-request | 직렬화된 메시지(트랜잭션이 아님)와 경로, 지문, 공개 키 |
요청을 애니메이션 QR 코드로 표시하세요. 서명되지 않은 트랜잭션과 무작위 요청 ID는 대기 중인 레코드에 보관합니다. QR 서명을 참고하세요.
4. 서명 스캔
BitTool Signer는 모든 필드를 보여 주고 지갑 비밀번호를 요청한 뒤 결과를 QR 코드로 표시합니다. 이를 스캔하고 다음 순서로 확인하세요.
- UR 타입이 예상한 응답 타입인지 확인합니다.
- 요청 ID가 대기 중인 요청과 일치하는지 확인합니다(Bitcoin: PSBT 안의 서명되지 않은 트랜잭션이 바뀌지 않았는지 확인).
- 서명이 예상한 공개 키와 서명을 요청한 정확한 바이트에 대해 검증되는지 확인합니다.
5. 조립과 브로드캐스트
서명을 트랜잭션에 넣고(EVM: r, s, v, TRON: signature[]에 추가, Solana: 해당 서명자의 슬롯에 넣기, Bitcoin: PSBT 최종화) 브로드캐스트하세요. BitTool Signer는 브로드캐스트하지 않으며, 트랜잭션이 전송되었는지도 알 수 없습니다.
iPhone 없이 테스트하기
이 사이트의 모든 예제는 공개 테스트 문구를 사용해 BitTool Signer 엔진으로 생성했습니다.
abandon abandon abandon abandon abandon abandon abandon abandon abandon abandon abandon about
테스트 기기의 BitTool Signer(또는 자체 테스트 코드)에 이 문구를 가져오면 이 문서에 나온 주소, QR 코드, 서명이 그대로 나와야 합니다. 전체 데이터는 테스트 벡터에서 내려받을 수 있습니다.
- 애니메이션 QR 코드가 양방향 모두, 프레임을 놓친 뒤에도 스캔됩니다.
- 자금을 받기 전에 사용자가 모든 계정의 첫 번째 주소를 비교할 수 있습니다.
- 모든 응답을 브로드캐스트 전에 검증하며, 다른 요청에 대한 응답은 거부합니다.
- SegWit v0 및 Legacy Bitcoin 입력에는 이전 트랜잭션 전체(
nonWitnessUtxo)가 들어 있습니다. - Solana 트랜잭션은 정적 계정 키만 사용합니다(주소 조회 테이블 미사용).