feat(wasm-utxo-cli): add psbt create/add-input/add-output/sign subcommands

OttoAllmendinger · OttoAllmendinger · commit bbc43fab62f7 · 2026-07-06T13:46:45.000+02:00
Four composable subcommands under `psbt`, replacing the earlier
single-shot build-sign command: `psbt create`, `psbt add-input`,
`psbt add-output`, `psbt sign`. Each reads/writes a PSBT as hex via
stdin/stdout (or a file path), so they pipe together, e.g.:

  psbt create | psbt add-input - --network tzec --txid ... --descriptor pkh(&lt;pubkey&gt;) \
    | psbt add-output - --address ... --network tzec \
    | psbt sign - --network tzec --privkey ... --consensus-branch-id 0xc2d6d0b4

`add-input` and `sign` work for all networks, not just Zcash, using
the wasm-utxo library helpers added in the parent commit:

- `add-input` requires `--prev-tx` (a full previous transaction)
  unless `--network` is a value-committing network (Zcash/BCH-family)
  whose sighash already commits the input amount.
- `sign` dispatches the sighash algorithm on `--network`: plain,
  FORKID (BCH family), or Zcash ZIP-243. Manually verified end-to-end
  for all three sighash families.

This lets the indexer-utxo regtest fixture generator build+sign a
transparent Zcash transaction off-node for zebrad's sendrawtransaction.

Refs: T1-3672
diff --git a/packages/wasm-utxo/cli/README.md b/packages/wasm-utxo/cli/README.md
@@ -125,6 +125,54 @@ The output displays a hierarchical tree view of the PSBT structure, including:
 - Per-output fields (scripts, derivation paths)
 - Decoded transaction details
 
+#### Build and sign a transparent transaction
+
+Four composable subcommands — `create`, `add-input`, `add-output`, `sign` — each read a PSBT
+from a file or stdin (`-`) and print the result as hex, so they pipe together into a full
+build-and-sign flow for a single-key transparent (non-segwit) transaction. Works for any
+network; the sighash algorithm used by `sign` (plain, FORKID, or Zcash ZIP-243) is selected by
+`--network`.
+
+```bash
+wasm-utxo-cli psbt create [--version <VERSION>] [--lock-time <LOCK_TIME>]
+wasm-utxo-cli psbt add-input <PATH> --network <NETWORK> --txid <TXID> --vout <VOUT> \
+  --value <VALUE> --script <SCRIPT_HEX> --descriptor <DESCRIPTOR> [--prev-tx <PREV_TX_HEX>]
+wasm-utxo-cli psbt add-output <PATH> (--address <ADDRESS> --network <NETWORK> | --script <SCRIPT_HEX>) --value <VALUE>
+wasm-utxo-cli psbt sign <PATH> --network <NETWORK> --privkey <PRIVKEY> [--consensus-branch-id <ID>]
+```
+
+`add-input` requires `--prev-tx` (the full previous transaction, hex-encoded) unless
+`--network` is a value-committing network (Zcash, BCH family) whose sighash already commits the
+spent amount — see `Network::requires_prev_tx_for_legacy_input` in the `wasm-utxo` library.
+
+**Examples:**
+
+```bash
+# BTC: spend a P2PKH coinbase-style output, providing the full previous transaction
+wasm-utxo-cli psbt create \
+  | wasm-utxo-cli psbt add-input - --network btc \
+      --txid e6a6e7f5551af932bc3813d920c52d61ec39fbad2e5585a018cce7dcbdd4ec72 --vout 0 \
+      --value 50000000 --script 76a914aeee1e6ae364e64b1b36acd53df55bd8d750485888ac \
+      --descriptor "pkh(039ab0771c5f88913208a26f81ab8223e98d25176e4648a5a2bb8ff79cf1c5198b)" \
+      --prev-tx 010000000100000000000000000000000000000000000000000000000000000000000000000000000000ffffffff0180f0fa02000000001976a914aeee1e6ae364e64b1b36acd53df55bd8d750485888ac00000000 \
+  | wasm-utxo-cli psbt add-output - --script 76a914aeee1e6ae364e64b1b36acd53df55bd8d750485888ac --value 49990000 \
+  | wasm-utxo-cli psbt sign - --network btc --privkey KzEGYtKcbhYwUWcZygbsqmF31f3iV7HC3iUQug7MBecwCz9hm1Tv
+# Output: a plain-sighash signed BTC transaction, hex-encoded
+
+# Zcash: spend a transparent P2PKH coinbase output for regtest fixture generation
+# (e.g. for a zebrad-mined UTXO to broadcast via sendrawtransaction). No --prev-tx needed —
+# ZIP-243 sighash commits the input amount.
+wasm-utxo-cli psbt create --lock-time 0 \
+  | wasm-utxo-cli psbt add-input - --network tzec \
+      --txid a8c685478265f4c14dada651969c45a65e1aeb8cd6791f2f5bb6a1d9952104d9 --vout 0 \
+      --value 50000000 --script 76a914aeee1e6ae364e64b1b36acd53df55bd8d750485888ac \
+      --descriptor "pkh(039ab0771c5f88913208a26f81ab8223e98d25176e4648a5a2bb8ff79cf1c5198b)" \
+  | wasm-utxo-cli psbt add-output - --script 76a914aeee1e6ae364e64b1b36acd53df55bd8d750485888ac --value 49990000 \
+  | wasm-utxo-cli psbt sign - --network tzec --privkey KzEGYtKcbhYwUWcZygbsqmF31f3iV7HC3iUQug7MBecwCz9hm1Tv \
+      --consensus-branch-id 0xc2d6d0b4
+# Output: a signed Zcash overwintered (NU5) transaction, hex-encoded
+```
+
 ### Supported Networks
 
 The CLI supports the following networks (use with `--network` flag):
diff --git a/packages/wasm-utxo/cli/src/input.rs b/packages/wasm-utxo/cli/src/input.rs
@@ -16,6 +16,17 @@ pub fn parse_private_key(s: &str) -> Result<PrivateKey> {
     PrivateKey::from_slice(&bytes, BitcoinNetwork::Bitcoin).context("invalid private key bytes")
 }
 
+/// Parse a `u32` given as decimal or `0x`-prefixed hex.
+pub fn parse_u32_flexible(s: &str) -> Result<u32> {
+    let s = s.trim();
+    if let Some(hex) = s.strip_prefix("0x").or_else(|| s.strip_prefix("0X")) {
+        u32::from_str_radix(hex, 16).with_context(|| format!("invalid hex u32: {s}"))
+    } else {
+        s.parse::<u32>()
+            .with_context(|| format!("invalid u32: {s}"))
+    }
+}
+
 /// Decode input bytes, attempting to interpret as base64, hex, or raw bytes
 pub fn decode_input(raw_bytes: &[u8]) -> Result<Vec<u8>> {
     // Try to interpret as text first (for base64/hex encoded input)
diff --git a/packages/wasm-utxo/cli/src/psbt/add_input.rs b/packages/wasm-utxo/cli/src/psbt/add_input.rs
@@ -0,0 +1,69 @@
+use anyhow::{anyhow, bail, Context, Result};
+use std::path::PathBuf;
+use std::str::FromStr;
+use wasm_utxo::add_input_with_descriptor;
+use wasm_utxo::bitcoin::consensus::Decodable;
+use wasm_utxo::bitcoin::{ScriptBuf, Transaction, Txid};
+
+use super::common::{print_psbt, read_psbt};
+use crate::network::NetworkArg;
+
+#[allow(clippy::too_many_arguments)]
+pub fn handle_add_input_command(
+    path: PathBuf,
+    network: NetworkArg,
+    txid: String,
+    vout: u32,
+    value: u64,
+    script: String,
+    descriptor: String,
+    sequence: u32,
+    prev_tx: Option<String>,
+) -> Result<()> {
+    let network: wasm_utxo::Network = network.into();
+    let mut psbt = read_psbt(&path)?;
+
+    let txid = Txid::from_str(&txid).context("invalid --txid")?;
+    let script_pubkey = ScriptBuf::from(hex::decode(&script).context("invalid --script hex")?);
+
+    let non_witness_utxo = match prev_tx {
+        Some(hex_str) => {
+            let bytes = hex::decode(&hex_str).context("invalid --prev-tx hex")?;
+            let tx = Transaction::consensus_decode(&mut bytes.as_slice())
+                .context("invalid --prev-tx transaction")?;
+            if tx.compute_txid() != txid {
+                bail!(
+                    "--prev-tx txid {} does not match --txid {}",
+                    tx.compute_txid(),
+                    txid
+                );
+            }
+            Some(tx)
+        }
+        None if network.requires_prev_tx_for_legacy_input() => {
+            bail!(
+                "--prev-tx is required for network {network} (only value-committing networks \
+                 like Zcash/BCH-family can omit it)"
+            );
+        }
+        None => None,
+    };
+
+    let index = psbt.inputs.len();
+    add_input_with_descriptor(
+        &mut psbt,
+        index,
+        txid,
+        vout,
+        value,
+        script_pubkey,
+        &descriptor,
+        sequence,
+        non_witness_utxo,
+    )
+    .map_err(|e| anyhow!(e))
+    .with_context(|| format!("failed to add input {index}"))?;
+
+    print_psbt(&psbt);
+    Ok(())
+}
diff --git a/packages/wasm-utxo/cli/src/psbt/add_output.rs b/packages/wasm-utxo/cli/src/psbt/add_output.rs
@@ -0,0 +1,48 @@
+use anyhow::{anyhow, bail, Context, Result};
+use std::path::PathBuf;
+use wasm_utxo::bitcoin::psbt::Output as PsbtOutput;
+use wasm_utxo::bitcoin::{Amount, ScriptBuf, TxOut};
+use wasm_utxo::psbt_ops::insert_output;
+use wasm_utxo::to_output_script_with_network;
+
+use super::common::{print_psbt, read_psbt};
+use crate::network::NetworkArg;
+
+pub fn handle_add_output_command(
+    path: PathBuf,
+    network: Option<NetworkArg>,
+    address: Option<String>,
+    script: Option<String>,
+    value: u64,
+) -> Result<()> {
+    let mut psbt = read_psbt(&path)?;
+
+    let script_pubkey = match (address, script) {
+        (Some(address), None) => {
+            let network = network
+                .ok_or_else(|| anyhow!("--network is required when using --address"))?
+                .into();
+            to_output_script_with_network(&address, network).context("invalid --address")?
+        }
+        (None, Some(script)) => {
+            ScriptBuf::from(hex::decode(&script).context("invalid --script hex")?)
+        }
+        _ => bail!("expected exactly one of --address or --script"),
+    };
+
+    let index = psbt.outputs.len();
+    insert_output(
+        &mut psbt,
+        index,
+        TxOut {
+            value: Amount::from_sat(value),
+            script_pubkey,
+        },
+        PsbtOutput::default(),
+    )
+    .map_err(|e| anyhow!(e))
+    .with_context(|| format!("failed to add output {index}"))?;
+
+    print_psbt(&psbt);
+    Ok(())
+}
diff --git a/packages/wasm-utxo/cli/src/psbt/common.rs b/packages/wasm-utxo/cli/src/psbt/common.rs
@@ -0,0 +1,18 @@
+use anyhow::{Context, Result};
+use std::path::PathBuf;
+use wasm_utxo::bitcoin::psbt::Psbt;
+
+use crate::input::{decode_input, read_input_bytes};
+
+/// Read and deserialize a PSBT from a file path or stdin (`-`), auto-detecting
+/// hex/base64/raw encoding.
+pub fn read_psbt(path: &PathBuf) -> Result<Psbt> {
+    let raw_bytes = read_input_bytes(path, "PSBT")?;
+    let bytes = decode_input(&raw_bytes)?;
+    Psbt::deserialize(&bytes).context("Failed to parse PSBT")
+}
+
+/// Serialize a PSBT and print it as hex to stdout.
+pub fn print_psbt(psbt: &Psbt) {
+    println!("{}", hex::encode(psbt.serialize()));
+}
diff --git a/packages/wasm-utxo/cli/src/psbt/create.rs b/packages/wasm-utxo/cli/src/psbt/create.rs
@@ -0,0 +1,18 @@
+use anyhow::Result;
+use wasm_utxo::bitcoin::locktime::absolute::LockTime;
+use wasm_utxo::bitcoin::psbt::Psbt;
+use wasm_utxo::bitcoin::transaction::{Transaction, Version};
+
+use super::common::print_psbt;
+
+pub fn handle_create_command(version: i32, lock_time: u32) -> Result<()> {
+    let tx = Transaction {
+        version: Version(version),
+        lock_time: LockTime::from_consensus(lock_time),
+        input: vec![],
+        output: vec![],
+    };
+    let psbt = Psbt::from_unsigned_tx(tx).expect("empty transaction should be valid");
+    print_psbt(&psbt);
+    Ok(())
+}
diff --git a/packages/wasm-utxo/cli/src/psbt/mod.rs b/packages/wasm-utxo/cli/src/psbt/mod.rs
@@ -1,16 +1,22 @@
 use anyhow::Result;
-use clap::Subcommand;
+use clap::{ArgGroup, Subcommand};
+use std::path::PathBuf;
 
 use crate::network::NetworkArg;
 
+mod add_input;
+mod add_output;
+mod common;
+mod create;
 mod parse;
+mod sign;
 
 #[derive(Subcommand)]
 pub enum PsbtCommand {
     /// Parse a PSBT file and display its contents
     Parse {
         /// Path to the PSBT file (use '-' to read from stdin)
-        path: std::path::PathBuf,
+        path: PathBuf,
         /// Network for address formatting
         #[arg(long, short, value_enum)]
         network: NetworkArg,
@@ -21,6 +27,90 @@ pub enum PsbtCommand {
         #[arg(long)]
         raw: bool,
     },
+    /// Create an empty PSBT. Prints the PSBT as hex to stdout.
+    Create {
+        /// Transaction version (default: 4, required for Zcash overwintered txs)
+        #[arg(long, default_value_t = 4)]
+        version: i32,
+        /// Transaction lock time (default: 0)
+        #[arg(long, default_value_t = 0)]
+        lock_time: u32,
+    },
+    /// Add an input spending `{txid, vout, value, scriptPubKey}` to a PSBT, given a definite
+    /// descriptor for the output (e.g. `pkh(<pubkey>)`, `wpkh(<pubkey>)`). Prints the updated
+    /// PSBT as hex to stdout.
+    AddInput {
+        /// Path to the PSBT file (use '-' to read from stdin)
+        path: PathBuf,
+        /// Network (determines whether --prev-tx is required; e.g. tzec for Zcash regtest)
+        #[arg(long, short, value_enum)]
+        network: NetworkArg,
+        /// Transaction ID of the output being spent
+        #[arg(long)]
+        txid: String,
+        /// Output index being spent
+        #[arg(long)]
+        vout: u32,
+        /// Value in satoshis of the output being spent
+        #[arg(long)]
+        value: u64,
+        /// scriptPubKey of the output being spent, hex-encoded
+        #[arg(long)]
+        script: String,
+        /// Definite descriptor for the output being spent, with concrete keys
+        /// (e.g. `pkh(<pubkey>)`, `wpkh(<pubkey>)`); populates bip32_derivation/tap_key_origins
+        #[arg(long)]
+        descriptor: String,
+        /// Sequence number (default: 0xFFFFFFFE)
+        #[arg(long, default_value_t = 0xFFFFFFFE)]
+        sequence: u32,
+        /// Full previous transaction, hex-encoded (BIP174-safe path). Required unless --network
+        /// is a value-committing network (Zcash, BCH-family) whose sighash already commits the
+        /// input amount, making it safe to sign from --value/--script alone.
+        #[arg(long = "prev-tx")]
+        prev_tx: Option<String>,
+    },
+    /// Add an output to a PSBT. Prints the updated PSBT as hex to stdout.
+    #[command(group(ArgGroup::new("target").required(true).args(["address", "script"])))]
+    AddOutput {
+        /// Path to the PSBT file (use '-' to read from stdin)
+        path: PathBuf,
+        /// Output address (requires --network)
+        #[arg(long)]
+        address: Option<String>,
+        /// Output script, hex-encoded
+        #[arg(long)]
+        script: Option<String>,
+        /// Value in satoshis
+        #[arg(long)]
+        value: u64,
+        /// Network for --address (e.g. tzec for Zcash regtest, which reuses testnet prefixes)
+        #[arg(long, short, value_enum)]
+        network: Option<NetworkArg>,
+    },
+    /// Sign all inputs with a single private key, then finalize and extract. The sighash
+    /// algorithm is selected by --network: plain for BTC-like networks, FORKID for the
+    /// BCH family, or Zcash ZIP-243. Prints the signed wire hex to stdout (overwintered
+    /// format for Zcash).
+    Sign {
+        /// Path to the PSBT file (use '-' to read from stdin)
+        path: PathBuf,
+        /// Network (selects the sighash algorithm: plain, FORKID, or Zcash ZIP-243)
+        #[arg(long, short, value_enum)]
+        network: NetworkArg,
+        /// Controlling private key for all inputs (WIF or hex)
+        #[arg(long)]
+        privkey: String,
+        /// Zcash consensus branch ID, hex (0x...) or decimal (required for Zcash, unused otherwise)
+        #[arg(long)]
+        consensus_branch_id: Option<String>,
+        /// Zcash version group ID, hex or decimal (default: Sapling 0x892F2085; Zcash only)
+        #[arg(long)]
+        version_group_id: Option<String>,
+        /// Transaction expiry height (default: 0, no expiry; Zcash only)
+        #[arg(long, default_value_t = 0)]
+        expiry_height: u32,
+    },
 }
 
 pub fn handle_command(command: PsbtCommand) -> Result<()> {
@@ -31,5 +121,43 @@ pub fn handle_command(command: PsbtCommand) -> Result<()> {
             raw,
             network,
         } => parse::handle_parse_command(path, no_color, raw, network.into()),
+        PsbtCommand::Create { version, lock_time } => {
+            create::handle_create_command(version, lock_time)
+        }
+        PsbtCommand::AddInput {
+            path,
+            network,
+            txid,
+            vout,
+            value,
+            script,
+            descriptor,
+            sequence,
+            prev_tx,
+        } => add_input::handle_add_input_command(
+            path, network, txid, vout, value, script, descriptor, sequence, prev_tx,
+        ),
+        PsbtCommand::AddOutput {
+            path,
+            address,
+            script,
+            value,
+            network,
+        } => add_output::handle_add_output_command(path, network, address, script, value),
+        PsbtCommand::Sign {
+            path,
+            network,
+            privkey,
+            consensus_branch_id,
+            version_group_id,
+            expiry_height,
+        } => sign::handle_sign_command(
+            path,
+            network,
+            privkey,
+            consensus_branch_id,
+            version_group_id,
+            expiry_height,
+        ),
     }
 }
diff --git a/packages/wasm-utxo/cli/src/psbt/sign.rs b/packages/wasm-utxo/cli/src/psbt/sign.rs
