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.
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.
[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:
-
A simple Bitcoin address, that will be used for all transactions.
-
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.
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.
Prefix | Address Encoding | Sample Address |
---|---|---|
|
P2PKH (Legacy) |
|
|
P2WPKH nested in P2SH (Segwit) |
|
|
P2WPKH (Native Segwit) |
|
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.
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 = ""
.
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!
|
$ ./keep-ecdsa --config <config file path> resolve-bitcoin-address
2021-08-19T11:23:03.946+0200 INFO keep-cmd resolved bitcoin beneficiary address: 2N89Sz5sDTrskGveo8jCVGofo46wnmPVwsR
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.
There is a default timeout of 48 hours
defined for the client to retry handling
the liquidation recovery.
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.
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.
|
-
Create a new account in Ledger Live application:
-
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. |