planning-module.org

Planning module

• Right now BDK has a policy module: when creating a transaction I can specify which policy I want to use to spend my utxos
  • or(and(A,B), C): either A+B or C by themselves
  • when I create the transaction, I decide if I want to spend with the A+B path, or if I want to spend with the C path
  • UX is not great, specifying which policy to use can be difficult
• Replacing the policy module with this planning idea
• Instead of specifying the policy I want to use to spend, I specify the “assets” (keys, timelocks, hash preimages) I have/want to use, and the planning module will find out the cheapest way for me to spend my coins
  • or(and(A,B),C), I tell the planning module that I own the keys A, B, C
    • The planning module will tell me to spend using the key C -> it’s cheaper than using A+B
  • or(A, and(B, older(10))), I tell the planning module I only have B
    • The planning module will tell me I can’t spend
  • or(A, and(B, older(10))), I tell the planning module I have B and I’m ok waiting 10 blocks
    • The planning module will tell me that I can spend using the B + older(10) policy
• Witness template
  • Real witness looks like `OP_PUSH 03….`
  • Template will look like `[OP_PUSH, KEY_A]`
• Planning module is going to be used in three places:
  • Step 1: before creating the transaction, to figure out if I can spend certain coins
  • Step 2: during coin selection! What we do right now is, for each coin, we estimate its weight using `max_satisfaction_weight`, and that’s quite wasteful
    • or(A, and(B, C, D, E, F, G)) -> max_sat_weight of this policy is spending with B + C + … + G, and that’s really expensive. But sometimes I might want to spend just using A, but in the coin selection I’m still `max_sat_weight`, which means my estimate will be really overshoot
    • We want to use the planning module to precisely estimate the coin’s spending weight
  • Step 3: if I’m given a PSBT, and I know the Plan I want to use to spend it, I want to fill the PSBT with the metadata I need to spend

Useful PRs

• PR: add the planning module: rust-bitcoin/rust-miniscript#481
• PR: use the new planning module: LLFourn/bdk_core_staging#66

TxBuilder

• Used for building transactions in BDK
• Right now it does have a lot of methods for configuring how the builder behaves and how the transaction will be constructed

Useful issues

• Issue: Redesign TxBuilder: bitcoindevkit/bdk#899
• Issue: UTXO locking: bitcoindevkit/bdk#849

TxBuilder redesign

0. User options

• User will tell us how the transaction should be constructed
• add_recepients, etc.

1. Coin control

• Determine which coins can be candidates, and which coins to filter out.
  • User gives a function to specify which utxos can/can’t be used (add_utxo, add_utxos, add_foreign_utxo, do_not_spend_change, unspendable)
  • Wasabi-like idea: decide if I can spend based on a label
• Determine coin groups (which coins must be spent together, and which coins must NOT be spent together).
  • Default: same as Bitcoin Core, Coin group contains all the coins that send to the same spk (everyone knows those coins are linked)
  • User-customizable (closure or something)
• Add plan to each coin
  • Idea: (might complicate stuff way too much) instead of 1:1 plan/coin 1:N
  • TODO: What the default should be? Maybe I should have an Option<Plan> and if I don’t have a Plan for a coin just use max_sat_weight (!=creating a plan where I have all the assets)?
  • Can be user supplied

2. Coin selection

• Selecting coins: shiny new module for CS!
• Determine whether we need a drain output (TODO: is this done in the CS already?)

3. Transaction finalization (-> Transaction)

• Formulate the unsigned tx
• Reordering https://docs.rs/bdk/latest/bdk/wallet/tx_builder/enum.TxOrdering.html

4. PSBT preparation (Transaction -> PSBT)

• TODO: does the cs have a generic coin type? I don’t want to lose info about plan<->coin relationship
• uses the plan to create the PSBT input (see planning module step 3)

5. Signing

Ideas

• `TxBuilderContext`: can I redesign it to look less shitty?
  • create_tx, build_fee_bump, cancel_tx, build_cpfp or something ???, build_drain
• More generic structure that you can apply all the various steps on
• 0. User options: TxParams like structure, with some checks on it (`check_validity` method)
• 1. CoinControl: function for filtering, function for determing coin groups, function for creating the plan:coin relationship, “apply” method for applying the coin control
• 2. Coin Selection: see nursery/coin_select, you create a CoinSelect…Opt, you create the WeightedValues of the available coins, you give it to the coin selection and tada