UTXO Consolidation Helpers

[arboleya]

Problem

1. Users may have a lot of dust coins
2. A transaction can't have more than ^N inputs
3. When funding a transaction, it may require more than ^N coins
4. Users have no way to consolidate their coins
5. As a result, they might get stuck

Actionable Items

We need to think about two phases:

1. Exporting method utilities for UTXO split and consolidation
2. Provide an automated flow to consolidate coins on the fly during transaction funding/submission
   • This may be done later, expand the collapsible below for more info.

Automatic UTXO Consolidation

Because UTXO consolidation will use gas, it's tricky to enable it by default.

However, we could..

..offer an extra submission method or add parameters to the existing one.

The idea is to have the flow available, but it should be opt-in.

Here's a first sketch:

---
title: Automatic UTXO Consolidation
theme: dark
---

%%{
  init: {
    'theme': 'dark'
  }
}%%

flowchart TB
  Start(Start) --> GetCoins{GetCoins}
  GetCoins --> IsEnough[[Is it enough?]]
  IsEnough --> Yes(Yes)
  IsEnough --> No(No)
  Yes --> Submit{Submit}
  Submit --> End(End)

  No --> HasFreeInputs[[Max Inputs Reached?]]
  HasFreeInputs --> FreeYes(Yes)
  HasFreeInputs --> FreeNo(No)
  FreeNo --> Error(ERROR<br/>Insuf. Balance)

  FreeYes --> AutoConsolidate[[Auto consolidate?]]
  AutoConsolidate --> AutoNo(No)
  AutoConsolidate --> AutoYes(Yes)

  AutoYes --> Transfer{Transfer}
  Transfer --> GetCoins;
  AutoNo --> Error

style Error stroke:#570f43, fill:#570f43, color:#ffffff;

classDef StartEnd stroke:#333, fill:#fff, color:#000;
class Start StartEnd;
class End StartEnd;

classDef Actions stroke:#10375b, fill:#10375b, color:#ffffff;
class Consolidate Actions;
class Submit Actions;
class GetCoins Actions;
class Transfer Actions;

Loading

[Torres-ssf]

This is a great sketch. As mentioned, enabling this behavior by default can be tricky since it could result in multiple transactions being submitted upfront.

Providing this functionality through additional parameters is a good approach, as it allows users to control when and how consolidation occurs.

[arboleya]

@nedsalk Let's focus on the helper methods first - did you think about a simple API to get started?

const account = new Account(ADDRESS, provider);
account.consolidateCoins()
account.splitCoin()

[nedsalk]

@arboleya below is the full consolidation workflow for both base and non-base assets.

UTXO consolidation

flowchart TD
    Start["Consolidate coins"] --> 
    |Select asset id| get_all_coins("Get coins (all pages)") --> 
        more_coins_than_max_inputs(count >= max_inputs?) --> 
            |No| is_base_asset("Consolidating base asset?") -->
                    |No| get_resources_for_less("Call getResourcesToSpend to fund tx with one base input, all non-base inputs, and two outputs") -->
                        fill_up_all("Combine received base asset resources and as many non-base asset coins as possible") -->
                        at_least_two_non_base("There are at least two non-base inputs in the combination?") --> 
                            |Can't consolidate one coin, too many base asset dust coins, consider first consolidating them| throw
                        at_least_two_non_base -->
                            |Yes| verify_resources_can_fund("Verify resources can still fund tx after they have been added") -->
                                |No| refund_tx("Call getResourcesToSpend to fund this updated tx") -->
                                    fill_up_all
                            verify_resources_can_fund -->
                                |Yes| prepare_script_tx("Prepare tx with coins, check validity (amount > maxFee)")
                is_base_asset -->
                    |Yes| select_all_coins("Select all coins") -->
                    prepare_script_tx
        more_coins_than_max_inputs --> 
        |   Yes| is_base_asset_2("Consolidating base asset?") -->
                |No| get_resources_two_outputs("Call getResourcesToSpend to fund tx that has max fake inputs and two outputs") -->
                    fill_up_max("Combine funding resources and consolidation coins until max_inputs reached")
                is_base_asset_2 -->
                |Yes| get_resources_one_output("Call getResourcesToSpend to fund tx that has max fake inputs and one output") --> 
                    fill_up_max("Combine resources for funding and consolidation coins until max_inputs reached") --> 
                    prepare_script_tx
        prepare_script_tx --> 
            |Invalid| throw
        prepare_script_tx -->
            |Valid| send_tx("Send transaction and await")
        send_tx --> |Success| coins_remaining{"Remaining unconsolidated coins > 1?"}
        send_tx --> |Failure| throw("Throw, put results of previous transactions on error")
        send_tx --> |SqueezedOut| throw
        coins_remaining --> |Yes| more_coins_than_max_inputs
        coins_remaining --> |No| return_to_user(Return transactions and coins to user)

Loading