Covenants integration infrastructure

[lilbonekit]

No description provided.

[lilbonekit]

Covenant UTXO + Wallet UTXO Spending in lwk_web

Problem

For covenant spending we need a transaction that contains both:

1. Covenant UTXO (spent by Simplicity covenant logic)
2. Wallet UTXO (used for fees, change and wallet signing flow)

Current lwk_web transaction construction only exposes wallet inputs:

new TxBuilder(network)
  .setWalletUtxos(...)
  .addExplicitRecipient(...)
  .finish(wollet)

The important detail is that finish(wollet) adds wallet-specific metadata required for signing (ownership information, derivation paths, key origin data, etc.).

If a mixed transaction is assembled manually, covenant inputs can be added, but wallet inputs may miss metadata expected by LWK signers and Jade.

---

Investigation

Core support already exists in LWK.

Core implementation

https://github.com/Blockstream/lwk/blob/3a5407c27b63001aec7bdb6fd2f68bfe30a0f303/lwk_wollet/src/tx_builder.rs#L878

The core TxBuilder already supports:

add_external_utxos(...)

and finish_inner() already processes:

self.external_utxos

by adding them through:

add_external_input(...)

This means the core builder already supports:

wallet inputs
+ external inputs
+ recipients
+ fee calculation
+ blinding
+ finish()

WASM bindings

https://github.com/Blockstream/lwk/blob/3a5407c27b63001aec7bdb6fd2f68bfe30a0f303/lwk_wasm/src/tx_builder.rs

The investigation suggests that the core functionality is already implemented.

The only missing piece appears to be a WASM binding that exposes add_external_utxos() to JavaScript.

The missing API is effectively:

#[wasm_bindgen]
pub fn add_external_utxos(...)

on the wasm TxBuilder wrapper, alongside the existing set_wallet_utxos() binding.

---

Proposed API

new TxBuilder(network)
  .feeRate(100)
  .setWalletUtxos([walletInput])
  .addExternalUtxos([covenantInput])
  .addExplicitRecipient(receiver, amount, policyAsset)
  .finish(wollet)

Result:

• wallet inputs retain all metadata required for LWK/Jade signing
• covenant inputs are included as external inputs
• transaction construction remains inside the standard LWK builder flow
• no manual PSET assembly required

---

Why v1 Is Different

v1 uses manual signing:

manual PSET construction
→ manual sighash computation
→ manual witness insertion

v2 uses signer-based flows:

Signer.sign(pset)
Jade.sign(pset)

These signers must be able to recognize wallet-owned inputs and their derivation metadata.

While covenant inputs can be added manually, wallet inputs assembled outside the standard LWK transaction builder may not contain the metadata required by LWK/Jade signers.

Therefore the v1 approach does not directly solve the v2 production flow.