feat(wasm-utxo): add getOutputsWithAddress method to PSBT

Adds a new method to PSBT that returns outputs with resolved address strings
derived from each output script. This allows getting proper addresses
formatted for specific coin networks without needing to call
address.fromOutputScript separately for each output.

Issue: BTC-2866

Co-authored-by: llm-git <llm-git@ttll.de>

Author: OttoAllmendinger

packages/wasm-utxo/js/index.ts

@@ -88,6 +88,11 @@ declare module "./wasm/wasm_utxo.js" {
     tapBip32Derivation: PsbtBip32Derivation[];
   }
 
+  /** PSBT output data with resolved address, returned by getOutputsWithAddress() */
+  interface PsbtOutputDataWithAddress extends PsbtOutputData {
+    address: string;
+  }
+
   interface WrapPsbt {
     // Signing methods (legacy - kept for backwards compatibility)
     signWithXprv(this: WrapPsbt, xprv: string): SignPsbtResult;
@@ -102,6 +107,7 @@ declare module "./wasm/wasm_utxo.js" {
     outputCount(): number;
     getInputs(): PsbtInputData[];
     getOutputs(): PsbtOutputData[];
+    getOutputsWithAddress(coin: import("./coinName.js").CoinName): PsbtOutputDataWithAddress[];
     getPartialSignatures(inputIndex: number): Array<{
       pubkey: Uint8Array;
       signature: Uint8Array;

packages/wasm-utxo/src/wasm/psbt.rs

@@ -1,3 +1,4 @@
+use crate::address::networks::{from_output_script_with_network_and_format, AddressFormat};
 use crate::error::WasmUtxoError;
 use crate::wasm::bip32::WasmBIP32;
 use crate::wasm::descriptor::WrapDescriptorEnum;
@@ -11,7 +12,7 @@ use miniscript::bitcoin::transaction::{Transaction, Version};
 use miniscript::bitcoin::{
     bip32, psbt, Amount, OutPoint, PublicKey, ScriptBuf, Sequence, XOnlyPublicKey,
 };
-use miniscript::bitcoin::{PrivateKey, Psbt, TxIn, TxOut, Txid};
+use miniscript::bitcoin::{PrivateKey, Psbt, Script, TxIn, TxOut, Txid};
 use miniscript::descriptor::{SinglePub, SinglePubKey};
 use miniscript::psbt::PsbtExt;
 use miniscript::{DescriptorPublicKey, ToPublicKey};
@@ -176,6 +177,32 @@ impl PsbtOutputData {
     }
 }
 
+/// PSBT output data with a resolved address string (requires a coin name for encoding).
+#[derive(Debug, Clone)]
+pub struct PsbtOutputDataWithAddress {
+    pub script: Vec<u8>,
+    pub value: u64,
+    pub address: String,
+    pub bip32_derivation: Vec<Bip32Derivation>,
+    pub tap_bip32_derivation: Vec<Bip32Derivation>,
+}
+
+impl PsbtOutputDataWithAddress {
+    pub fn from(base: PsbtOutputData, network: crate::Network) -> Result<Self, WasmUtxoError> {
+        let script_obj = Script::from_bytes(&base.script);
+        let address =
+            from_output_script_with_network_and_format(script_obj, network, AddressFormat::Default)
+                .map_err(|e| WasmUtxoError::new(&e.to_string()))?;
+        Ok(PsbtOutputDataWithAddress {
+            script: base.script,
+            value: base.value,
+            address,
+            bip32_derivation: base.bip32_derivation,
+            tap_bip32_derivation: base.tap_bip32_derivation,
+        })
+    }
+}
+
 #[wasm_bindgen]
 pub struct WrapPsbt(Psbt);
 
@@ -579,6 +606,28 @@ impl WrapPsbt {
         outputs.try_to_js_value()
     }
 
+    /// Get all PSBT outputs with resolved address strings.
+    ///
+    /// Like `getOutputs()` but each element also includes an `address` field
+    /// derived from the output script using the given coin name (e.g. "btc", "tbtc").
+    #[wasm_bindgen(js_name = getOutputsWithAddress)]
+    pub fn get_outputs_with_address(&self, coin: &str) -> Result<JsValue, WasmUtxoError> {
+        let network = crate::Network::from_coin_name(coin)
+            .ok_or_else(|| WasmUtxoError::new(&format!("Unknown coin: {}", coin)))?;
+        let outputs: Vec<PsbtOutputDataWithAddress> = self
+            .0
+            .unsigned_tx
+            .output
+            .iter()
+            .zip(self.0.outputs.iter())
+            .map(|(tx_out, psbt_out)| {
+                let base = PsbtOutputData::from(tx_out, psbt_out);
+                PsbtOutputDataWithAddress::from(base, network)
+            })
+            .collect::<Result<Vec<_>, _>>()?;
+        outputs.try_to_js_value()
+    }
+
     /// Get partial signatures for an input
     /// Returns array of { pubkey: Uint8Array, signature: Uint8Array }
     #[wasm_bindgen(js_name = getPartialSignatures)]

packages/wasm-utxo/src/wasm/try_into_js_value.rs

@@ -447,6 +447,18 @@ impl TryIntoJsValue for crate::wasm::psbt::PsbtOutputData {
     }
 }
 
+impl TryIntoJsValue for crate::wasm::psbt::PsbtOutputDataWithAddress {
+    fn try_to_js_value(&self) -> Result<JsValue, WasmUtxoError> {
+        js_obj!(
+            "script" => self.script.clone(),
+            "value" => self.value,
+            "address" => self.address.clone(),
+            "bip32Derivation" => self.bip32_derivation.clone(),
+            "tapBip32Derivation" => self.tap_bip32_derivation.clone()
+        )
+    }
+}
+
 /// A partial signature with its associated public key
 #[derive(Clone)]
 pub struct PartialSignature {

packages/wasm-utxo/test/testutilsDescriptor.ts

@@ -1,6 +1,8 @@
 import * as assert from "node:assert";
 
-import { Descriptor, Psbt, testutils } from "../js/index.js";
+import { Descriptor, Psbt, address } from "../js/index.js";
+import * as dt from "../js/testutils/descriptor/index.js";
+import * as testutils from "../js/testutils/index.js";
 
 describe("testutils.descriptor", () => {
   describe("getDefaultXPubs", () => {
@@ -95,6 +97,67 @@ describe("testutils.descriptor.mockPsbt", () => {
   });
 });
 
+describe("Psbt.getOutputsWithAddress", () => {
+  it("returns outputs with address strings for btc", () => {
+    const psbt = dt.mockPsbtDefault();
+    const outputs = psbt.getOutputsWithAddress("btc");
+    assert.strictEqual(outputs.length, 2);
+    for (const output of outputs) {
+      assert.ok(typeof output.address === "string", "address should be a string");
+      assert.ok(output.address.length > 0, "address should not be empty");
+      assert.ok(output.script instanceof Uint8Array, "script should be Uint8Array");
+      assert.ok(typeof output.value === "bigint", "value should be bigint");
+      assert.ok(Array.isArray(output.bip32Derivation), "bip32Derivation should be array");
+      assert.ok(Array.isArray(output.tapBip32Derivation), "tapBip32Derivation should be array");
+    }
+  });
+
+  it("returns consistent addresses with address.fromOutputScriptWithCoin", () => {
+    const psbt = dt.mockPsbtDefault();
+    const outputsWithAddr = psbt.getOutputsWithAddress("btc");
+    const rawOutputs = psbt.getOutputs();
+    for (let i = 0; i < rawOutputs.length; i++) {
+      const expected = address.fromOutputScriptWithCoin(rawOutputs[i].script, "btc");
+      assert.strictEqual(outputsWithAddr[i].address, expected);
+    }
+  });
+
+  it("returns btc mainnet addresses starting with expected prefixes", () => {
+    const psbt = dt.mockPsbtDefaultWithDescriptorTemplate("Wsh2Of3");
+    const outputs = psbt.getOutputsWithAddress("btc");
+    for (const output of outputs) {
+      // p2wsh addresses start with bc1
+      assert.ok(output.address.startsWith("bc1"), `expected bc1 prefix, got ${output.address}`);
+    }
+  });
+
+  it("returns tbtc testnet addresses starting with expected prefixes", () => {
+    const psbt = dt.mockPsbtDefaultWithDescriptorTemplate("Wsh2Of3");
+    const outputs = psbt.getOutputsWithAddress("tbtc");
+    for (const output of outputs) {
+      // p2wsh testnet addresses start with tb1
+      assert.ok(output.address.startsWith("tb1"), `expected tb1 prefix, got ${output.address}`);
+    }
+  });
+
+  it("works for all wsh/tr templates", () => {
+    for (const t of [
+      "Wsh2Of3",
+      "Wsh2Of2",
+      "Wsh2Of3CltvDrop",
+      "Tr2Of3-NoKeyPath",
+      "Tr1Of3-NoKeyPath-Tree",
+    ] as dt.DescriptorTemplate[]) {
+      const psbt = dt.mockPsbtDefaultWithDescriptorTemplate(t, dt.getPsbtParams(t));
+      const outputs = psbt.getOutputsWithAddress("btc");
+      assert.strictEqual(outputs.length, 2, `${t}: expected 2 outputs`);
+      for (const output of outputs) {
+        assert.ok(output.address.length > 0, `${t}: address should not be empty`);
+      }
+    }
+  });
+});
+
 describe("testutils.fixtures", () => {
   describe("jsonNormalize", () => {
     it("round-trips a simple object", () => {