Integration_guide.md

Cobo Vault Integration Guide

Cobo Vault is an air-gapped, QR Code based hardware wallet. Cobo Vault is a pure signer for your crypto transactions, Cobo Vault don't have external wireless connections like Bluetooth, WiFi, etc. The only way it can transmit data is via QR codes. This guide is for developers who would like to integrate their services with Cobo Vault.

Animated QR Codes

With Cobo Vault, we use QR Codes to transmit data, since each qr code image can only contain limited size of data, in order to send big chunks of data, we use animated QR codes to transmit big chunks of data. We are use the bc-ur to encode the data, for bc-ur please refer this doc we have implemented two libraries of bc-ur:

• javascript version: https://github.com/CoboVault/cobo-vault-blockchain-base/tree/master/packages/sdk

// Here is an sample:
yarn add @cvbb/sdk
const { CoboVaultSDK } = require("@cvbb/sdk")
const sdk = new CoboVaultSDK()
const data = sdk.encodeDataForQR('12334')
console.log(data)
// [ 'ur:bytes/1248938493496dfhjdh34' ]

Each item in the array should be put into the qr code image.

• java version: https://github.com/CoboVault/bc32-java

libraries

web

There are a lot of existing libraries which currently can be used to scan qr codes and here is some of it used by our friends :)

• qr-scaner
• vue-qr-code

React Native

• react-native-camera

Native App

For IOS and Android App we can use their native libraries to scan QR Codes.

BTC Only Firmware

We also provide a BTC-only Firmware for those who only use Bitcoin. You can get the latest firmware from here, For Bitcoin, we follow the BIP174, aka PSBT to encode transactions. For those who are not familiar with BIP174 and PSBT, those can find here are some good reference guides:

• https://github.com/bitcoin/bips/blob/master/bip-0174.mediawiki
• https://bitcointechweekly.com/front/bip-174-psbt-partially-signed-bitcoin-transactions/
• https://en.bitcoin.it/wiki/BIP_0174

And we strictly follow the slip-0132 to encode the extended public key.

Coin	Public Key	Address Encoding	BIP 32 Path
Bitcoin	0x0488b21e - xpub	P2PKH or P2SH	m/44'/0'
Bitcoin	0x049d7cb2 - ypub	P2WPKH in P2SH	m/49'/0'
Bitcoin	0x04b24746 - zpub	P2WPKH	m/84'/0'
Bitcoin	0x0295b43f - Ypub	Multi-signature P2WSH in P2SH	m/48'/0'/0'/1'
Bitcoin	0x02aa7ed3 - Zpub	Multi-signature P2WSH	m/48'/0'/0'/2'
Bitcoin Testnet	0x043587cf - tpub	P2PKH or P2SH	m/44'/1'
Bitcoin Testnet	0x044a5262 - upub	P2WPKH in P2SH	m/49'/1'
Bitcoin Testnet	0x045f1cf6 - vpub	P2WPKH	m/84'/1'
Bitcoin Testnet	0x024289ef - Upub	Multi-signature P2WSH in P2SH	m/48'/1'/0'/1'
Bitcoin Testnet	0x02575483 - Vpub	Multi-signature P2WSH	m/48'/1'/0'/2'

Single-Sig

Currently we have integrated with a lot of well-known wallets, like Electrum, Blue Wallet, Wasabi Wallet, BTCPay, Specter, Sparrow etc. and also we provide generic wallet models to other wallets or services who would like to integrate with us.

Setup the watch-only wallet

Watch-only wallet import of the extended public key from cobo vault, cobo vault support both file and qrcode, the xpub info defines as follow, here is an sample file for this info:

• ExPubKey [Required]: this is the extended public key of the master seed
• MasterFingerprint [Required]: this is the master fingerprint of master seed which is only used to identify the master seed
• AccountKeyPath [Required]: this is the derivation path of the extended public key
• CoboVaultFirmwareVersion [Required]: this is the firmware version in current hardware device.

file: p2wpkh-pubkey.txt

{
    "ExtPubKey":"vpub5Z3SXQwuvQWt5vBQiRYrqhbou6BB7u1TFcA4DTQxPirU4oqMwnWW5DcSmM31h7SzofmUM3xHHn8rEht38jyuX8tfXS2D1desPVRsvnD5Dtr",
    "MasterFingerprint":"5271C071",
    "AccountKeyPath":"84'/1'/0'",
    "CoboVaultFirmwareVersion":"1.8.2(BTC-Only)"
}

QR Code (json string):

Sign PSBT

We use psbt to encode the unsigned transaction and we provide two ways for that:

1. File:The unsigned PSBT file should be encoded as binary or base64 encoding and should use the .psbt file extension. reference bip174 here is the example unsigned psbt file example

2. QRCode: We use bc-ur to encode the psbt data. Here is a sample QRCode Image.

Export Signed PSBT

After signing, users can export the signed psbt, we provide two ways for that:

1. Signed psbt file: see the example signed psbt file example

2. QRCode: here is the sample qr code of signed PSBT.

Multi-Sig

We also support Multi-Sig for Bitcoin, currently we can use Cobo Vault and ColdCard to set up Multi-Sig Wallet and perform multi-Sig, we have integrated with Electurm, Spector-Desktop and you can check this guide about how to use Cobo Vault to perform multi-sig: https://btcguide.github.io/

Setup Multi-sig wallet

Users can create a Multi-sig wallet by collecting all co-signers extended public key or import a multi-sig wallet file export from another Cobo vault co-signer.

Users can get the xpub by following this guide: https://btcguide.github.io/setup-wallets/cobo

1. Export the xpub of co-signer, it can be export via file or QR Code：

   file: 5271C071_P2WSH.json (export from cobo vault)

   {
    "xfp":"5271C071",
    "xpub":"Vpub5mpRVCzdkDTtCwH9LrfiiPonePjP4CZSakA4wynC4zVBVAooaykiCzjUniYbLpWxoRotGiXwoKGcHC5kSxiJGX1Ybjf2ioNommVmCJg7AV2",
    "path":"m/48'/1'/0'/2'"
   }
   

   • "xfp" is the master fingerprint
   • "xpub" is the extended public key
   • "path" is the derivation path of the extended public key

QR Code(json string):

2. Import Multi-sig wallet, Multi-sig wallet data format

These data can be exported via fil or QR Code, here is a sample file:

```
# CoboVault Multisig setup file (created on C2202A77)
#
Name: CV_85C39000_2-3
Policy: 2 of 3
Derivation: m/48'/1'/0'/2'
Format: P2WSH

C2202A77: Vpub5nbpJQxCxQu9Nv5Effa1F8gdQsijrgk7KrMkioLs5DoRwb7MCjC3t1P2y9mXbnBgu29yL8EYexZqzniFdX7Xo3q8TuwkVAqbQpgxfAfrRiW
5271C071: Vpub5mpRVCzdkDTtCwH9LrfiiPonePjP4CZSakA4wynC4zVBVAooaykiCzjUniYbLpWxoRotGiXwoKGcHC5kSxiJGX1Ybjf2ioNommVmCJg7AV2
748CC6AA: Vpub5mcrJpVp9X8ZKsjyxwNu36SLRAWTMbqUtbmtcapahAtqVa66JtXhT4Uc9SVLN1nF782sPRRT2jbUbe7XzT8eue6vXsyDJKBvexGJHewyPxQ
```

• Name: the multi-sig wallet name
• Policy: multi-sig policy like 2 of 2 , 2 of 3
• Derivation: the Derivation path of all the extend public key for multi-sig
• Format: your script format, current we support P2WSH, P2WSH-P2SH, P2SH (P2SH-P2MS)

the following items are master fingerprint and its extended public key

• {master fingerprint:extended public key}

The data format should be consistent with the file and all the fields should be filled.

QrCode (bc-ur):

We use bc-ur to encode this sample file and here is an sample data:

```
UR:BYTES/TYQL2GEQGDHKYM6KV96KCAPQF46KCARFWD5KWGRNV4682UPQVE5KCEFQ9P3HYETPW3JKGGR0DCSR2V3HX9PNQDE39Y9ZXZJWV9KK2W3QGDT97WP4GVENJVPSXP0NYTFNPFGX7MRFVDUN5GPJYPHKVGPNPFZX2UNFWESHG6T0DCAZQMF0XSUZWTE3YUHNQFE0XGNS53N0WFKKZAP6YPGRY46NFQ9Q5SEJXGCRYSFHXUAZQ4NSW43R2MNZWP99Z7ZR0PGH2W2WWC652ENXVYC5VWR8V3GHX6T2WFNKKD6TWFXKK6T0F3EN23R02FMKYD6DGD4YXVM5X9GRY7FED4VXYMJZVA6NYWTEFSUY2KT90PD8Z7NWD9RXGKPHTPHNXUFC236HW66KG9CKY5TSVAUXVSTXWFFXJ4C2X5ERWV2RXQMNZW3Q2EC82C34D4C9Y4JR0FJXK3Z5W3PHWJPEF3EXV6TF2PHKUE2SDFGRGS662DSKKSF5WAUKUSE50FTYY4JPDAHKZ7TTD9PH56J4DE54JCJVWPTHSM6JDA6YW62CWAH5K3MRFPPN266N0P55536CX9VKY6NXXF5K7NN0D4K4VM2RFFNNWS2KXG9RWDPCGDPNVS2P8GS9VUR4VG6K6CMJFFC9VUPETQU95JMNDFUHSA6WW5ENV56V2FQ4W4ZDVFC42ARZD46XXCTSV95YZAR32ESNVDJ2W3VXS4P5243NJ56KF38RZMJXXUURYU6S2FF9GVN2VF2KYEFHTPA9GWR9W4JNVAJCWDU5GJJTGFMX27Z8FFYX2AME2PU9ZZSDGUVWA
```

And here is the sample image:

Sign PSBT

For multi-sig, unsigned and signed PSBT are consistent with single-sig and we also provide two ways for it.

Unsigned psbt file:

See the example unsigned multisig psbt file example

Unsigned psbt Qrcode(encoded in bc-ur):

Export Signed PSBT

Signed multisig psbt file:

See the example partially signed multisig psbt file example

Signed multisig psbt qrcode(encoded in bc-ur):

FAQ

TODO