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:58

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<PubKey:(FingerPrint:DerivationPath)>

Psbt->proprietary Array<PsbtPropKey:Bytes>

Psbt->unknown Array<PsbtRawKey:Bytes>

Psbt->txid Txid

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 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->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

Errors:

• 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:68

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:73

psbt::sign()

psbt::sign(Psbt, SecKey|Array<SecKey>) -> Psbt

Sign all Psbt inputs that can be signed using the given secret keys.

Keys will be matched to inputs based on their bip32_derivation/tap_key_origins fields, which must already be set.

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

Errors: If signing failed using any of the provided keys.
Does not error if keys were only given for some of the inputs.

Also see:

• BIP 174's Signer Role
• psbt::try_sign(), which doesn't raise an error for signing failures
• psbt::sign_finalize(), which also finalizes the Psbt and extracts the Transaction

Rust source code: src/stdlib/psbt.rs:119

psbt::try_sign()

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

Sign all Psbt inputs that can be signed using the given secret keys, without raising an error 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, with an empty array for unsigned inputs)
3. An array of input indexes and the error encountered while trying to sign them (Int:String tuples)

For example:

Code Result

[$psbt_, $signed, $failed] = psbt::try_sign($psbt, $sk);

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

// STDOUT: Input 0 signed by 1 keys
// STDOUT: Input 1 signed by 0 keys
$psbt_ = psbt[
  "unsigned_tx": tx[
    "version": 2,
    "inputs": [
      7e3bf1d75c773f5828d5020acf4c4c43abd655819ceddf204b92367c017bb2cd:0,
      bec105d8eecce01a4f71eab44f601e6a815689a3a2bbe2f4ceb2b0657b91beef:0
    ],
    "outputs": [
      `<0> <0x41d312a8e5d9a430699f5c3e5555571a9e951f29>`:0.1 BTC
    ]
  ],
  "version": 0,
  "inputs": [
    [
      "utxo": `<0> <0x3cc92f90833e9b7fb14716892fe2890e9ef1d773>`:0.1 BTC,
      "partial_sigs": [
        036771073c1e92792d05c5c4e739b7094817f9d94bb287e109298ae1936a88f3b2: 0x30450221008b648d6bfc36a633f2cd67b7b77d6323972282c762701ae2ba5afd05b877f5dc02203e19d99efdf79369c0ff1f75caa2db149000474c9b7f1638a2f4bca51e4ee7e801
      ],
      "bip32_derivation": [
        [3cc92f90]036771073c1e92792d05c5c4e739b7094817f9d94bb287e109298ae1936a88f3b2
      ]
    ],
    [
      "utxo": `<0> <0x703df49a4f910cf4bcaedc54698baf5d6e296b42>`:0.2 BTC,
      "bip32_derivation": [
        [703df49a]03b694b0ada1fc2889ee79b01860131a64f981c34199e339e614a8079f117df94e
      ]
    ]
  ],
  "outputs": [
    [ ]
  ]
] // psbt

$signed = [ 0: [ pubkey(036771073c1e92792d05c5c4e739b7094817f9d94bb287e109298ae1936a88f3b2) ], 1: [ ] ] // array

$failed = [ ] // array

Rust source code: src/stdlib/psbt.rs:135

psbt::sign_finalize()

psbt::sign_finalize(Psbt, SecKey|Array<SecKey>) -> Transaction

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

Shorthand for psbt::finalize(psbt::sign($psbt, $keys)).

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

Minsc source code: src/stdlib/btc.minsc:97

psbt::finalize()

psbt::finalize(psbt: Psbt, extract_tx: Bool = true) -> Transaction|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 using psbt::finalize_witness().

Returns:

• When extract_tx is true (the default), extracts and returns the Transaction
• When extract_tx is false, returns the updated Psbt populated with the final_script_witness/final_scriptsig input fields

Errors:

• If any inputs fail to finalize
• If any inputs fail the Miniscript sanity interpreter checks for signatures/preimages/timelocks

Also see:

• BIP 174's Input Finalizer Role
• [psbt::try_finalize()], which doesn't raise an error for finalization failures

Rust source code: src/stdlib/psbt.rs:93

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 error 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:

Code Result

[$psbt_, $failed] = psbt::try_finalize($psbt);

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

// STDOUT: Input 1 failed: Missing pubkey for a pkh/wpkh
$psbt_ = psbt[
  "unsigned_tx": tx[
    "version": 2,
    "inputs": [
      7e3bf1d75c773f5828d5020acf4c4c43abd655819ceddf204b92367c017bb2cd:0,
      bec105d8eecce01a4f71eab44f601e6a815689a3a2bbe2f4ceb2b0657b91beef:0
    ],
    "outputs": [
      `<0> <0x41d312a8e5d9a430699f5c3e5555571a9e951f29>`:0.1 BTC
    ]
  ],
  "version": 0,
  "inputs": [
    [
      "utxo": `<0> <0x3cc92f90833e9b7fb14716892fe2890e9ef1d773>`:0.1 BTC,
      "final_script_witness": [ 0x30450221008b648d6bfc36a633f2cd67b7b77d6323972282c762701ae2ba5afd05b877f5dc02203e19d99efdf79369c0ff1f75caa2db149000474c9b7f1638a2f4bca51e4ee7e801, 0x036771073c1e92792d05c5c4e739b7094817f9d94bb287e109298ae1936a88f3b2 ]
    ],
    [
      "utxo": `<0> <0x703df49a4f910cf4bcaedc54698baf5d6e296b42>`:0.2 BTC,
      "bip32_derivation": [
        [703df49a]03b694b0ada1fc2889ee79b01860131a64f981c34199e339e614a8079f117df94e
      ]
    ]
  ],
  "outputs": [
    [ ]
  ]
] // psbt

$failed = [ 1: "Missing pubkey for a pkh/wpkh" ] // array

Rust source code: src/stdlib/psbt.rs:107

psbt::finalize_witness()

psbt::finalize_witness(psbt: Psbt, witnesses: Array<Int:Array<Bytes>>, 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.

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.

For example:

Code Result

$tx = psbt::finalize_witness($psbt, [
  0: [ 0x0102, 0x0304 ], // set the witness for the first input
  2: [ 0xC0FFEE ], // and for the third
]);

$tx = tx[
  "version": 2,
  "inputs": [
    [
      "prevout": 7e3bf1d75c773f5828d5020acf4c4c43abd655819ceddf204b92367c017bb2cd:0,
      "witness": [ 0x0102, 0x0304 ]
    ],
    bec105d8eecce01a4f71eab44f601e6a815689a3a2bbe2f4ceb2b0657b91beef:0,
    [
      "prevout": 435e69fbc443be0a0da721b720d963d9db03c025e695881bb87e9833074c4d25:1,
      "witness": [ 0xc0ffee ]
    ]
  ],
  "outputs": [
    `<0> <0x41d312a8e5d9a430699f5c3e5555571a9e951f29>`:0.1 BTC
  ]
] // transaction

Also see: BIP 174's Input Finalizer Role

Minsc source code: src/stdlib/btc.minsc:88

psbt::extract()

psbt::extract(Psbt) -> Transaction

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

Errors:

• If any inputs are missing the final_script_witness/final_scriptsig fields
• If any inputs 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:145

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.

Errors: If any inputs are missing the final_script_witness/final_scriptsig fields

Rust source code: src/stdlib/psbt.rs:154

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.

Errors:

• If the PSBTs are not all for the same unsigned_tx
• If the PSBTs has the xpub field

Also see: BIP 174's Combiner Role

Rust source code: src/stdlib/psbt.rs:80

psbt::sighash()

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

Rust source code: src/stdlib/psbt.rs:163

psbt::fee()

psbt::fee(Psbt) -> Int

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

Errors:

• If any inputs are missing UTXO information (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:163

PsbtInput

Runtime Repr: Array<Fields>

Underlying Type: bitcoin::psbt::Input

PsbtInput->utxo TxOut opt

Also known as the witness_utxo

PsbtInput->non_witness_utxo Transaction opt

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

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>:KeySource)>

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:TapLeafVersion)>

Array mapping from serialized Taproot control blocks to a Script:TapLeafVersion 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<PsbtPropKey:Bytes>

PsbtInput->unknown Array<PsbtRawKey:Bytes>

PsbtOutput

Runtime Repr: Array<Fields>

Underlying Type: bitcoin::psbt::Output

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

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>:KeySource)>

PsbtOutput->tap_tree TapNode opt

PsbtOutput->proprietary Array<PsbtPropKey:Bytes>

PsbtOutput->unknown Array<PsbtRawKey:Bytes>

PsbtPropKey

PsbtRawKey