Skip to content

UNSIGNED_SWEEP.md

Latest commit

 

History

History
137 lines (83 loc) · 7.15 KB

UNSIGNED_SWEEP.md

File metadata and controls

137 lines (83 loc) · 7.15 KB

Unsigned Sweep Recovery Instructions

Build an unsigned transaction from a cold wallet using the user and backup public keys, independent of any BitGo services.

What happens in an unsigned sweep recovery?

  1. You are asked to provide the Coin Name that you want to recover.

  2. You are asked to provide the User Public Key as found on your recovery KeyCard.

  3. If you have a Key ID set to your User Key, it will be displayed on your KeyCard. You are supposed to provide the Key ID only if you have it on your KeyCard.

  4. You are asked to provide the Backup Public Key as found on your recovery KeyCard.

  5. If you have a Key ID set to your Backup Key, it will be displayed on your KeyCard. You are supposed to provide the Key ID only if you have it on your KeyCard.

  6. The next field will be different based on coin type

    1. For UTXO based coins, you are asked to provide the BitGo Public Key as found on your recovery KeyCard.

    2. For Coins like Stellar, Ripple, and EOS, Root Address of the wallet needs to be provided.

    3. For Ethereum, Ethereum Proof of Work, ERC20 Token, and Avalanche C-Chain, Wallet Contract Address needs to be provided. This is the ETH or AVAXC address of the wallet contract. This is also the wallet's base address. For ERC20 Token, Token Contract Address needs to be provided. This is the address of the smart contract of the token to recover. This is unique to each token and is NOT your wallet address

  7. You are asked to provide the Destination Address (The address where you want to receive your recovered funds).

  8. For UTXO based coins like Bitcoin, Litecoin, Dash, Zcash, Bitcoin Gold, Tron, and Bitcoin Cash, Address Scanning Factor needs to be provided. By default, it's value is 20 and can be changed if needed. The tool scans the addresses of the wallet to find the unspents. If it doesn't find unspents in 20 consecutive addresses, then it will stop scanning and generate a recovery transaction. For eg: If your funds are stuck in addresses with indices 10, 25 and 50 and you keep scanning factor as 20. Then the tool will stop after scanning till 46th index, because it didn't find unspents for 20 consecutive addresses from 26th address onwards. So in order to recover the funds in the address with 50th index, you will have to increase the scanning factor to a higher value.

  9. For Ethereum, Ethereum Proof of Work, and ERC20 Token, Max Fee Per Gas Price and Max Priority Fee Per Gas in Gwei needs to be provided. The value should be between 1 Gwei and 2500 Gwei. The default is 20 Gwei for Max Fee Per Gas and 10 Gwei for Max Priority Fee Per Gas. If there is not enough Gwei in the backup key address gas tank, you will need to fund your backup key address. WRW will report the backup key address if there is not enough Gwei in it.

  10. For Ethereum, Ethereum Proof of Work, ERC20 Token, and Avalanche C-Chain, Gas Limit needs to be provided. The value should be between 30,000 and 20,000,000. The default is 500,000 units of gas.

  11. For Avalanche C-Chain, Gas Price needs to be provided. The value should be between 1 Gwei and 2500 Gwei. The default is 30 Gwei.

  12. An API Key token from etherscan.com needs to be provided for certain recoveries.

  13. For UTXO based coins like Bitcoin, Litecoin, Dash, Zcash, Bitcoin Gold, and Bitcoin Cash, the key is from https://blockchair.com/.

  14. For Ethereum and ERC20 token, the key is from https://etherscan.io/.

  15. For Avalanche C-Chain, the key is from https://snowtrace.io/.

  16. For Algorand, you must use your own node to broadcast recovery transactions.

  17. The SDK determines the amount of an asset that you can recover, and then builds a unsigned transaction to a destination address.

  18. Using the OVC (Offline Vault Console), you must sign the unsigned transaction with your private user key, resulting in a half-signed transaction.

  19. Using the OVC again, you must sign the half-signed transaction with your private backup key, resulting in a fully-signed transaction.

  20. To finish the recovery, broadcast the fully-signed transaction on the network using a blockchain explorer. Some blockchain explorers to broadcast the transaction are as follows:

    Avalanche C-Chain transactions: https://snowtrace.io/pushTx

    Blockchair (Supports multiple coins): https://blockchair.com/broadcast

    Bitcoin Gold transactions: https://btgexplorer.com/sendtx

    Cardano transactions: See Cardano (ADA / TADA) section below.

    EOS transactions: EOS.md

    Ethereum and ERC20 Token transactions: https://etherscan.io/pushTx

    Ethereum Proof of Work transactions: ETHW.md

    Near transactions: NEAR.md

    Ripple transactions: https://bithomp.com/submit/

    Stellar transactions: https://laboratory.stellar.org/#txsubmitter?network=public

    Tron transactions: https://www.btcschools.net/tron/tron_broadcast_tx.php

Cardano (ADA / TADA)

Cardano uses EdDSA (Ed25519) signing, so the OVC signing process takes 6 steps instead of the standard 2.

Supported assets

  • ADA (mainnet) and TADA (Preprod testnet)
  • Native tokens (e.g. fungible tokens on the Cardano blockchain)

When the wallet holds both ADA and native tokens, WRW produces two outputs in the unsigned sweep:

  • Token output: destination address + tokens + 1.5 ADA (Cardano minimum UTXO requirement)
  • ADA remainder: destination address + remaining ADA after fee

Step 1 — Build the unsigned sweep file in WRW

  1. Select coin ADA or TADA.
  2. Enter your User Public Key, Backup Public Key, and BitGo Public Key from your KeyCard.
  3. Enter the destination address.
  4. Click Recover Funds. WRW saves e.g. ada-unsigned-sweep-<timestamp>.json.

Step 2 — Sign offline using OVC (6-step EdDSA)

Important: Select Sign TSS Recoveries in OVC — not "Sign Transactions" or "Sign TSS Transactions". Recovery files have no server-backed txRequestId; the standard signing flow will fail.

Step OVC role Action
1 User OVC Upload unsigned sweep file → download share file
2 Backup OVC Upload user share → download backup share
3 User OVC Upload backup share → download user signature share
4 Backup OVC Upload user signature share → download backup signature share
5 User OVC Upload backup signature share → download final signed file
6 — Broadcast the final signed file

Step 3 — Broadcast using broadcast_ada.py

broadcast_ada.py (included in this repository) assembles the signed CBOR from the OVC output and submits it to the Cardano network via Koios.

Requirements:

pip install cbor2

Broadcast to testnet (TADA / Preprod):

python3 broadcast_ada.py path/to/SIGNED-ovc-signed-part-6-of-6-<timestamp>.json

Broadcast to mainnet (ADA):

python3 broadcast_ada.py path/to/SIGNED-ovc-signed-part-6-of-6-<timestamp>.json --network mainnet

Dry run (assemble CBOR without broadcasting):

python3 broadcast_ada.py path/to/SIGNED-ovc-signed-part-6-of-6-<timestamp>.json --dry-run

On success, the script prints the transaction hash and a Cardanoscan explorer link.