Skip to content
This repository has been archived by the owner on May 22, 2023. It is now read-only.

Latest commit

 

History

History
179 lines (129 loc) · 6.37 KB

tbtc-liquidation-recovery.adoc

File metadata and controls

179 lines (129 loc) · 6.37 KB
Raw

tBTC Liquidation Recovery

1. Background

As described in RFC 2:

Keep ECDSA client implements the mechanism mentioned above to recover BTC after a tBTC Deposit got liquidated and split the amount among the Keep signers holding the BTC.

2. Configuration

To enable the tBTC Liquidation Recovery mechanism, update the TOML configuration file with a destination (BeneficiaryAddress) to which Bitcoin funds should be sent once liquidation happens.

BeneficiaryAddress in TOML Config File
[Extensions.TBTC.Bitcoin]
BeneficiaryAddress = "<your btc address or *pub key for a hierarchical deterministic wallet>"

The Beneficiary Address can be provided in one of two formats:

  1. A simple Bitcoin address, that will be used for all transactions.

  2. An extended public key (*pub), that will be used to derive unique addresses for each transaction, see Bitcoin Addresses Derivation section.

For examples see Example Beneficiary Addresses.

For all configuration parameters please see tBTC Extension configuration properties.

3. Bitcoin Addresses Derivation

BeneficiaryAddress can be provided as an extended public key described by BIP 32.

Type of Bitcoin address that will be calculated is resolved based on the *pub prefix, according to SLIP-0132.

Table 1. Addresses Encoding Based on *pub Prefix
Prefix Address Encoding Sample Address

xpub

P2PKH (Legacy)

1L3mGzLD9XLXKxkgLB5Gc6rW6s4ik4yd2r

ypub

P2WPKH nested in P2SH (Segwit)

3DMLhAwVrJxePftA8Q5emyoNFCj8Jn1q64

zpub

P2WPKH (Native Segwit)

bc1q6rczu6pcv2eq9gh9xvrwx6y9uhxk88f8xm020g

For more examples see Example Beneficiary Addresses.

If the extended public key is provided the client will resolve a unique and unused Bitcoin address for each Bitcoin transaction.

Addresses are resolved starting from 0 index. The index is incremented by 1 in case of the address being used already.

The highest used index for the extended public keys will be stored in the client’s local storage directory under bitcoin/derivation_indexes/<EXTENDED_PUBLIC_KEY_ID>/<INDEX> (e.g. bitcoin/derivation_indexes/xpub_b1wex5vq/3).

The client will additionally reach the Bitcoin API to check if there are any existing transactions for the given address.

If the Bitcoin connection is missing the client will check the address usage based on the local storage only.

3.1. Bitcoin Chain Connectivity

Connectivity to Bitcoin API is used for liquidation recovery handling but is not required for the process to complete.

The Keep ECDSA client uses Electrs API to obtain information and submit transactions.

By default the client reaches the Blockstream’s API (https://blockstream.info/api/), but it can be connected to any endpoint supporting the Electrs API. The address can be specified under ElectrsURL config property.

To disable Bitcoin connectivity set ElectrsURL property to empty value: ElectrsURL = "".

3.2. Configuration Verification

To verify configuration and Bitcoin address derivation use resolve-bitcoin-address command exposed by the Keep ECDSA client. Use --config <path> argument to point to the TOML configuration file.

❗
 Verify that you are in control of the Bitcoin beneficiary address resolved by the resolve-bitcoin-address command!
Sample execution of resolve-bitcoin-address command
$ ./keep-ecdsa --config <config file path> resolve-bitcoin-address
2021-08-19T11:23:03.946+0200	INFO	keep-cmd	resolved bitcoin beneficiary address: 2N89Sz5sDTrskGveo8jCVGofo46wnmPVwsR

4. Backward Compatibility

If the client version is updated but the configuration file doesn’t provide required details following warning message will be logged:

2021-08-19T11:11:46.339+0200	WARN	keep-cmd	missing bitcoin configuration for tbtc extension: [a bitcoin address or extended public key (*pub) is required; configure one at [Extensions.TBTC.Bitcoin.BeneficiaryAddress]]

If other peer members are not updated or configured correctly to handle liquidation recovery the client will log an error message.

5. Time Frames

There is a default timeout of 48 hours defined for the client to retry handling the liquidation recovery.

6. Limitations

The client starts liquidation recovery once an event is delivered from the Ethereum chain. If the client restarts during the event handling it won’t retry to recover the liquidation recovery process that started before the restart.

7. Get xpub Key from Ledger Live

Below you can find steps to create a dedicated Bitcoin account in the Ledger Live application.

ℹ️
 Ledger Live exports extended public keys in xpub format. It is recommended that you create an account of a LEGACY type to use its' xpub key in the Keep ECDSA client configuration. xpub keys exported from Ledger Live for other types of accounts (i.e. SEGWIT and NATIVE SEGWIT) require conversion to ypub or zpub before usage in the Keep ECDSA client configuration.

  1. Create a new account in Ledger Live application:

    1. Navigate to Accounts section.

    2. Press + Add Account button.

    3. In Crypto asset section select Bitcoin (BTC).

    4. Press Continue button and connect your Ledger device.

    5. In Accounts section press Show all address types and select LEGACY. Add account

    6. Press Add account button.

    7. In Confirmation section press Done button.

  2. Export xpub key for the account according to Ledger’s Documentation.

The xpub obtained from Ledger Live can be used in the Keep ECDSA client configuration file.

❗
 Please remember to verify your Keep ECDSA client configuration as described in Configuration Verification. Compare the address resolved by the Keep ECDSA client matches the address that you get for the account in Ledger Live Receive function.