Merge bitcoin/bitcoin#28539: lib: add taproot support to libconsensus

ff8e2fc2e2416f6f3b84cdb40db8ac168596b579 fuzz: add coverage for `bitcoinconsensus_verify_script_with_spent_outputs` (brunoerg)
c5f2a757d736f14d27ac5256a9df887cd2f174f1 docs: add release notes for #28539 (brunoerg)
de54882348502d860cf1e504100aa8fb1e52aa88 docs: add docs for additional libconsensus functions (Jake Rawsthorne)
70106e0689546fee497814c63a6a4747e0937b36 docs: link to rust-bitcoinconsensus (Jake Rawsthorne)
fb0db07e414fec3318b3af683167ebef9c82fc84 lib: add Taproot support to libconsensus (Jake Rawsthorne)

Pull request description:

  Grabbed from #21158. Closes #21133.

ACKs for top commit:
  achow101:
    ACK ff8e2fc2e2416f6f3b84cdb40db8ac168596b579
  theStack:
    ACK ff8e2fc2e2416f6f3b84cdb40db8ac168596b579
  darosior:
    re-ACK ff8e2fc2e2416f6f3b84cdb40db8ac168596b579

Tree-SHA512: bf6f500c7e8c9ff6884137c2cd9b4522c586e52848dd639b774b94d998b0516b877498d24f3a6cc7425aedf81d18b0d30c1ccf19e2d527fdfdfa3955ca49b6e7

2 files changed, 34 insertions, 2 deletions

diff --git a/doc/release-notes-123.md b/doc/release-notes-123.md
new file mode 100644
index 0000000000..fffd211f37
--- /dev/null
+++ b/doc/release-notes-123.md
@@ -0,0 +1,5 @@
+Tools and Utilities
+---
+
+- A new `bitcoinconsensus_verify_script_with_spent_outputs` function is available in libconsensus which optionally accepts the spent outputs of the transaction being verified.
+- A new `bitcoinconsensus_SCRIPT_FLAGS_VERIFY_TAPROOT` flag is available in libconsensus that will verify scripts with the Taproot spending rules.
\ No newline at end of file
diff --git a/doc/shared-libraries.md b/doc/shared-libraries.md
index 147e223711..07aee46f0b 100644
--- a/doc/shared-libraries.md
+++ b/doc/shared-libraries.md
@@ -11,13 +11,14 @@ The interface is defined in the C header `bitcoinconsensus.h` located in `src/sc
 
 #### Version
 
-`bitcoinconsensus_version` returns an `unsigned int` with the API version *(currently `1`)*.
+`bitcoinconsensus_version` returns an `unsigned int` with the API version *(currently `2`)*.
 
 #### Script Validation
 
-`bitcoinconsensus_verify_script` returns an `int` with the status of the verification. It will be `1` if the input script correctly spends the previous output `scriptPubKey`.
+`bitcoinconsensus_verify_script`, `bitcoinconsensus_verify_script_with_amount` and `bitcoinconsensus_verify_script_with_spent_outputs` return an `int` with the status of the verification. It will be `1` if the input script correctly spends the previous output `scriptPubKey`.
 
 ##### Parameters
+###### bitcoinconsensus_verify_script
 - `const unsigned char *scriptPubKey` - The previous output script that encumbers spending.
 - `unsigned int scriptPubKeyLen` - The number of bytes for the `scriptPubKey`.
 - `const unsigned char *txTo` - The transaction with the input that is spending the previous output.
@@ -26,6 +27,28 @@ The interface is defined in the C header `bitcoinconsensus.h` located in `src/sc
 - `unsigned int flags` - The script validation flags *(see below)*.
 - `bitcoinconsensus_error* err` - Will have the error/success code for the operation *(see below)*.
 
+###### bitcoinconsensus_verify_script_with_amount
+- `const unsigned char *scriptPubKey` - The previous output script that encumbers spending.
+- `unsigned int scriptPubKeyLen` - The number of bytes for the `scriptPubKey`.
+- `int64_t amount` - The amount spent in the input
+- `const unsigned char *txTo` - The transaction with the input that is spending the previous output.
+- `unsigned int txToLen` - The number of bytes for the `txTo`.
+- `unsigned int nIn` - The index of the input in `txTo` that spends the `scriptPubKey`.
+- `unsigned int flags` - The script validation flags *(see below)*.
+- `bitcoinconsensus_error* err` - Will have the error/success code for the operation *(see below)*.
+
+###### bitcoinconsensus_verify_script_with_spent_outputs
+- `const unsigned char *scriptPubKey` - The previous output script that encumbers spending.
+- `unsigned int scriptPubKeyLen` - The number of bytes for the `scriptPubKey`.
+- `int64_t amount` - The amount spent in the input
+- `const unsigned char *txTo` - The transaction with the input that is spending the previous output.
+- `unsigned int txToLen` - The number of bytes for the `txTo`.
+- `UTXO *spentOutputs` - Previous outputs spent in the transaction. `UTXO` is a struct composed by `const unsigned char *scriptPubKey`, `unsigned int scriptPubKeySize` (the number of bytes for the `scriptPubKey`) and `unsigned int value`.
+- `unsigned int spentOutputsLen` - The number of bytes for the `spentOutputs`.
+- `unsigned int nIn` - The index of the input in `txTo` that spends the `scriptPubKey`.
+- `unsigned int flags` - The script validation flags *(see below)*.
+- `bitcoinconsensus_error* err` - Will have the error/success code for the operation *(see below)*.
+
 ##### Script Flags
 - `bitcoinconsensus_SCRIPT_FLAGS_VERIFY_NONE`
 - `bitcoinconsensus_SCRIPT_FLAGS_VERIFY_P2SH` - Evaluate P2SH ([BIP16](https://github.com/bitcoin/bips/blob/master/bip-0016.mediawiki)) subscripts
@@ -34,6 +57,7 @@ The interface is defined in the C header `bitcoinconsensus.h` located in `src/sc
 - `bitcoinconsensus_SCRIPT_FLAGS_VERIFY_CHECKLOCKTIMEVERIFY` - Enable CHECKLOCKTIMEVERIFY ([BIP65](https://github.com/bitcoin/bips/blob/master/bip-0065.mediawiki))
 - `bitcoinconsensus_SCRIPT_FLAGS_VERIFY_CHECKSEQUENCEVERIFY` - Enable CHECKSEQUENCEVERIFY ([BIP112](https://github.com/bitcoin/bips/blob/master/bip-0112.mediawiki))
 - `bitcoinconsensus_SCRIPT_FLAGS_VERIFY_WITNESS` - Enable WITNESS ([BIP141](https://github.com/bitcoin/bips/blob/master/bip-0141.mediawiki))
+- `bitcoinconsensus_SCRIPT_FLAGS_VERIFY_TAPROOT` - Enable TAPROOT ([BIP340](https://github.com/bitcoin/bips/blob/master/bip-0340.mediawiki), [BIP341](https://github.com/bitcoin/bips/blob/master/bip-0341.mediawiki), [BIP342](https://github.com/bitcoin/bips/blob/master/bip-0342.mediawiki))
 
 ##### Errors
 - `bitcoinconsensus_ERR_OK` - No errors with input parameters *(see the return value of `bitcoinconsensus_verify_script` for the verification status)*
@@ -42,9 +66,12 @@ The interface is defined in the C header `bitcoinconsensus.h` located in `src/sc
 - `bitcoinconsensus_ERR_DESERIALIZE` - An error deserializing `txTo`
 - `bitcoinconsensus_ERR_AMOUNT_REQUIRED` - Input amount is required if WITNESS is used
 - `bitcoinconsensus_ERR_INVALID_FLAGS` - Script verification `flags` are invalid (i.e. not part of the libconsensus interface)
+- `bitcoinconsensus_ERR_SPENT_OUTPUTS_REQUIRED` - Spent outputs are required if TAPROOT is used
+- `bitcoinconsensus_ERR_SPENT_OUTPUTS_MISMATCH` - Spent outputs size doesn't match tx inputs size
 
 ### Example Implementations
 - [NBitcoin](https://github.com/MetacoSA/NBitcoin/blob/5e1055cd7c4186dee4227c344af8892aea54faec/NBitcoin/Script.cs#L979-#L1031) (.NET Bindings)
 - [node-libbitcoinconsensus](https://github.com/bitpay/node-libbitcoinconsensus) (Node.js Bindings)
 - [java-libbitcoinconsensus](https://github.com/dexX7/java-libbitcoinconsensus) (Java Bindings)
 - [bitcoinconsensus-php](https://github.com/Bit-Wasp/bitcoinconsensus-php) (PHP Bindings)
+- [rust-bitcoinconsensus](https://github.com/rust-bitcoin/rust-bitcoinconsensus) (Rust Bindings)
\ No newline at end of file