PSBT API Reference

Psbt

Construction Examples:

• psbt[ "inputs": …, "outputs": … ]
• psbt(0x70736274ffff08a6da0…)
• psbt("cHNidP8BADMCAAAAAV3azg…") (base64)
• $psbt_a + $psbt_b (combine)

→ See the PSBT guide for more options.

Coerces from:

• Transaction – the unsigned_tx to initialize the PSBT from
• Bytes – encoded using the BIP 174 serialization format (as returned by bytes(Psbt))
• String – base64 encoded (as returned by base64(Psbt))
• Array – tagged array with PSBT fields (see psbt::create())

Underlying type: bitcoin::Psbt

psbt()

psbt(Transaction|Bytes|String|Array<Fields>) -> Psbt

When called with a single argument, an alias for psbt::create() to construct a new Psbt.

psbt(Psbt, Array<Fields>) -> Psbt

When called with two arguments, an alias for psbt::update() to update the Psbt with the given fields.

The Psbt may be specified as any Psbt-coercible type (Transaction|Bytes|String|Array), so for example psbt($tx, [ "inputs": … ]) works.

Rust source code: src/stdlib/psbt.rs:N/A

Psbt->unsigned_tx Transaction

Psbt->version Int

Psbt->inputs Array<PsbtInput>

Aliased as: Psbt->input

Psbt->outputs Array<PsbtOutput>

Aliased as: Psbt->output

Psbt->xpub Array<PsbtSourcedPubKey>

Psbt->unknown Array<PsbtRawKey:Bytes>

Psbt->proprietary Array<PsbtProprietaryKey:Bytes>

Psbt->txid Hash

The txid of the unsigned_tx.

⚠️ Should only be used when all inputs are segwit inputs. Otherwise, the txid depends on the scriptSig which is always empty in the unsigned_tx (even when populated in the PsbtInput->final_scriptsig) and is also malleable regardless.

Psbt->utxos Array<TxOut> opt

All UTXOs spent by the transaction's inputs, in order. Combines information from the witness_utxo and non_witness_utxo fields.

Only available when all UTXOs are known. If only some are, individual ones may be accessed directly via e.g. $psbt->inputs.0->witness_utxo.

Psbt->fee Int

Calculate the transaction fee. All inputs must have UTXO information associated to them.

Returns -1 if the fee cannot be calculated. See psbt::fee() for the reasons it may happen (and use it to get a more useful error message instead of a -1).

psbt::create()

psbt::create(Transaction|Bytes|String|Array<Fields>) -> Psbt

Construct a Psbt given one of:

• Transaction – the unsigned_tx to initialize the PSBT from
• Bytes – encoded using the BIP 174 serialization format (as returned by bytes(Psbt))
• String – base64 encoded (as returned by base64(Psbt))
• Array – tagged array with PSBT fields

Throws:

• If the given String/Bytes cannot be decoded into a valid PSBT
• If the given Transaction has witnesses/scriptSigs set for any of its inputs
• If the given Array<Fields> has invalid PSBT fields

Aliased as: psbt() (when called with a single argument)

Also see: BIP 174's Creator Role

Rust source code: src/stdlib/psbt.rs:N/A

psbt::update()

psbt::update(Psbt, Array<Fields>) -> Psbt

Aliased as: psbt() (when called with two arguments)

Also see: BIP 174's Updater Role

Rust source code: src/stdlib/psbt.rs:N/A

psbt::sign()

psbt::sign(Psbt, PsbtSigningKeys) -> Psbt

Sign all Psbt inputs using the PsbtSigningKeys (typically a SecKey or an array of them).

Keys will be matched to inputs based on their bip32_derivation/tap_key_origins fields.

Returns: The updated signed Psbt, with the signatures populated in the input's partial_sigs, tap_key_sig and tap_script_sigs fields.

Throws: On input signing failures. See psbt::try_sign(), which returns whatever was successfully signed and a list of signing errors instead.

Also see:

• BIP 174's Signer Role
• psbt::sign_extract(), which also finalizes the Psbt and extracts the Transaction

Rust source code: src/stdlib/psbt.rs:N/A

psbt::try_sign()

psbt::try_sign(Psbt, PsbtSigningKeys) -> [Psbt, Array<Int:Array<PubKey>>, Array<Int:String>]

Try signing whichever inputs can be signed, without raising an exception for signing failures.

Returns: an Array of 3 elements —

1. The updated Psbt with the successfully signed inputs
2. An array of input indexes and the pubkeys used to sign them (Int:Array<PubKey> tuples), if any
3. An array of input indexes and the error encountered while trying to sign them (Int:String tuples)

// XXX: inputs we don't have keys for are not considered failed

For example:

$psbt = psbt[
  "inputs": [ 7e3bf1d75c773f5828d5020acf4c4c43abd655819ceddf204b92367c017bb2cd:0, bec105d8eecce01a4f71eab44f601e6a815689a3a2bbe2f4ceb2b0657b91beef:0 ],
  "output": tb1qg8f39289mxjrq6vltsl9242hr20f28ef6wy7zu:0.1 BTC,
  "utxos": [ wpkh(dummy::pk(0)):0.1 BTC, wpkh(dummy::pk(1)):0.2 BTC, ]
], $sk = dummy::sk(1); ;;;
[$psbt_, $succeed, $failed] = psbt::try_sign($psbt, $sk);

each($succeed, |[$input_index, $pks]| print("Input "+$input_index+" signed by "+len($pks)+" keys"));
each($failed, |[$input_index, $error]| print("Input "+$input_index+" failed: "+$error));

Rust source code: src/stdlib/psbt.rs:N/A

psbt::finalize()

psbt::finalize(Psbt) -> Psbt

Use the Miniscript PSBT Finalizer to finalize all input witnesses/scriptSigs.

This is only supported for Miniscript-compatible PSBTs. For PSBTs using raw Script, manual finalization must be performed instead via psbt::finalize_witness().

Returns: The updated Psbt, populated with the final_script_witness/final_scriptsig input fields.

Throws: If any inputs fail to finalize, or fail the Miniscript sanity interpreter checks for signatures/preimages/timelocks.

Also see:

• BIP 174's Input Finalizer Role
• psbt::finalize_extract(), which also extracts the Transaction

Rust source code: src/stdlib/psbt.rs:N/A

psbt::try_finalize()

psbt::try_finalize(Psbt) -> [Psbt, Array<Int:String>]

Use the Miniscript PSBT finalizer to try finalizing whichever inputs can be finalized, without raising an exception for failures.

Returns: an Array of 2 elements —

1. The updated Psbt with the successfully finalized inputs

2. An array of errors encountered while trying to finalize

   When related to a specific input, each error is an Int:String tuple of the input index and error message. For other errors (WrongInputCount or InputIdxOutofBounds), the Int is -1.

For example:

$psbt = psbt[
  "inputs": [ 7e3bf1d75c773f5828d5020acf4c4c43abd655819ceddf204b92367c017bb2cd:0, bec105d8eecce01a4f71eab44f601e6a815689a3a2bbe2f4ceb2b0657b91beef:0 ],
  "output": tb1qg8f39289mxjrq6vltsl9242hr20f28ef6wy7zu:0.1 BTC,
  "utxos": [ wpkh(dummy::pk(0)):0.1 BTC, wpkh(dummy::pk(1)):0.2 BTC, ]
] | psbt::sign(dummy::sk(1)); ;;;
[$psbt_, $failed] = psbt::try_finalize($psbt);

each($failed, |[$input_index, $error]| print("Input "+$input_index+" failed: "+$error));
isEmpty($failed) && print("Finalized successfully");

Rust source code: src/stdlib/psbt.rs:N/A

psbt::finalize_witness()

psbt::finalize_witness(psbt: Psbt, witnesses: Array<Int:Witness>, extract_tx: Bool = true) -> Transaction|Psbt

Manually finalize the Psbt by explicitly setting the final input witnesses, provided as an array mapping from the input index to its witness stack array.

This is necessary for PSBTs using non-Miniscript-compatible raw Script, which cannot be finalized automatically. It is equivalent to using psbt::update() to set the input's final_script_witness field.

For example:

$psbt = psbt[
  "inputs": [ 7e3bf1d75c773f5828d5020acf4c4c43abd655819ceddf204b92367c017bb2cd:0, bec105d8eecce01a4f71eab44f601e6a815689a3a2bbe2f4ceb2b0657b91beef:0, 435e69fbc443be0a0da721b720d963d9db03c025e695881bb87e9833074c4d25:1 ],
  "output": tb1qg8f39289mxjrq6vltsl9242hr20f28ef6wy7zu:0.1 BTC,
]; ;;;
$tx = psbt::finalize_witness($psbt, [
  0: [ 0x0102, 0x0304 ], // set the witness for the first input
  2: [ 0xC0FFEE ], // and for the third
]);

By default, this also Extracts and returns the finalized Transaction. If you'd like to get the finalized Psbt back instead, set extract_tx to false.

Also see: BIP 174's Input Finalizer Role

Minsc source code: src/stdlib/btc.minsc:N/A

psbt::extract()

psbt::extract(Psbt) -> Transaction

Extract the finalized Transaction from the Psbt after running the Miniscript sanity interpreter checks.

Throws: If any inputs are missing the final_script_witness/final_scriptsig fields, or fail the Miniscript sanity interpreter checks for signatures/preimages/timelocks.

Also see: BIP 174's Transaction Extractor Role

Rust source code: src/stdlib/psbt.rs:N/A

psbt::extract_raw()

psbt::extract_raw(Psbt) -> Transaction

Extract the finalized Transaction from the Psbt, without running the Miniscript sanity interpreter checks.

This is necessary for PSBTs using non-Miniscript-compatible raw Script, which would not pass the sanity checks.

Throws: If any inputs are missing the final_script_witness/final_scriptsig fields.

Rust source code: src/stdlib/psbt.rs:N/A

psbt::combine()

psbt::combine(Array<Psbt>) -> Psbt

Combine the given PSBTs.

In accordance with BIP 174 this function is commutative, i.e. psbt::combine[$psbt_a, $psbt_b] == psbt::combine[$psbt_b, $psbt_a].

Combining PSBTs is also possible using the + operator: $psbt_a + $psbt_b.

Also see: BIP 174's Combiner Role

Rust source code: src/stdlib/psbt.rs:N/A

psbt::sighash()

psbt::sighash(psbt: Psbt, input_index: Int, tap_leaf: TapLeafHash = None) -> Hash

Rust source code: src/stdlib/psbt.rs:N/A

psbt::fee()

psbt::fee(Psbt) -> Int

Calculate the transaction fee. All inputs must have UTXO information associated to them.

Throws:

• If any inputs are missing UTXO information (witness_utxo/non_witness_utxo)
• If output amount > input amount
• If integer overflow occurs when adding UTXO amounts (uses signed i64, can represent up to ~92 billion BTC)

Also see: Psbt->fee, tx::fee()

Rust source code: src/stdlib/psbt.rs:N/A

psbt::finalize_extract()

psbt::finalize_extract(Psbt) -> Transaction

Finalize the Psbt using the Miniscript Finalizer, then Extract the Transaction.

Short form for psbt::extract(psbt::finalize($psbt)).

Throws: If the Miniscript PSBT Finalizer fails or if Extraction fails

Minsc source code: src/stdlib/btc.minsc:N/A

psbt::sign_extract()

psbt::sign_extract(Psbt, PsbtSigningKeys) -> Transaction

Sign & Finalize the Psbt using the Miniscript Finalizer, then Extract the Transaction.

Short form for psbt::extract(psbt::finalize(psbt::sign($psbt))).

Throws: If signing fails, the Miniscript PSBT Finalizer fails, or if Extraction fails

Minsc source code: src/stdlib/btc.minsc:N/A

PsbtInput

Runtime Repr: Array<Fields>

Underlying Type: bitcoin::psbt::Input

PsbtInput->witness_utxo TxOut opt

Aliased as: utxo

PsbtInput->non_witness_utxo Transaction opt

PsbtInput->bip32_derivation Array<PubKey<SingleKey>:KeyOrigin>

PsbtInput->witness_script Script opt

PsbtInput->redeem_script Script opt

PsbtInput->sighash_type Int opt

PsbtInput->partial_sigs Array<PubKey<SingleKey>:Bytes>

PsbtInput->final_scriptsig Script opt

PsbtInput->final_script_witness Array<Bytes> opt

Taproot

PsbtInput->tap_internal_key PubKey<SingleKey> opt

PsbtInput->tap_merkle_root Hash opt

PsbtInput->tap_key_origins Array<PubKey<SingleKey>:(Array<TapLeafHash>:KeyOrigin)>

Array mapping from Taproot X-only PubKeys to their BIP32 origin and to the set of TapLeafHash containing that key

PsbtInput->tap_scripts Array<Bytes:(Script:LeafVersion)>

Array mapping from serialized Taproot Control Blocks to a Script:LeafVersion tuple

PsbtInput->tap_key_sig Bytes opt

Taproot signature with sighash type for key spend by the internal_key

PsbtInput->tap_script_sigs Array<(PubKey<SingleKey>:TapLeafHash):Bytes>

Array mapping from a PubKey<SingleKey>:TapLeafHash tuple to a Taproot signature by that key over that leaf hash

Hash Preimages

PsbtInput->sha256_preimages Array<Hash:Bytes<32>>

PsbtInput->hash256_preimages Array<Hash:Bytes<32>>

PsbtInput->ripemd160_preimages Array<Hash:Bytes<32>>

PsbtInput->hash160_preimages Array<Hash:Bytes<32>>

PsbtInput->proprietary Array<PsbtProprietaryKey:Bytes>

PsbtInput->unknown Array<PsbtRawKey:Bytes>

PsbtOutput

Runtime Repr: Array<Fields>

Underlying Type: bitcoin::psbt::Output

PsbtOutput->bip32_derivation Array<PubKey<SingleKey>:KeyOrigin>

PsbtOutput->witness_script Script opt

PsbtOutput->redeem_script Script opt

Taproot

PsbtOutput->tap_internal_key PubKey<SingleKey> opt

PsbtOutput->tap_key_origins Array<PubKey<SingleKey>:(Array<TapLeafHash>:KeyOrigin)>

PsbtOutput->tap_tree TapNode opt

PsbtOutput->proprietary Array<PsbtProprietaryKey:Bytes>

PsbtOutput->unknown Array<PsbtRawKey:Bytes>

PsbtSigningKeys

PsbtSourcedPubKey

PsbtRawKey

PsbtProprietaryKey