Merge branch '2024-08--docs'

Author: RCasatta

.github/workflows/rust.yml

@@ -69,15 +69,15 @@ jobs:
         run: ./contrib/test.sh
 
   Fuzz:
-    name: Fuzztests - 1.58.0 toolchain
+    name: Fuzztests - 1.63.0 toolchain
     runs-on: ubuntu-latest
     strategy:
       fail-fast: false
     steps:
       - name: Checkout Crate
         uses: actions/checkout@v3
       - name: Checkout Toolchain
-        uses: dtolnay/rust-toolchain@1.58.0
+        uses: dtolnay/rust-toolchain@1.63.0
       - name: Install test dependencies
         run: sudo apt-get update -y && sudo apt-get install -y binutils-dev libunwind8-dev libcurl4-openssl-dev libelf-dev libdw-dev cmake gcc libiberty-dev
       - name: Running test script

contrib/test.sh

@@ -9,6 +9,9 @@ if cargo --version | grep "1\.56"; then
     cargo update -p which --precise 4.4.0
     cargo update -p byteorder --precise 1.4.3
     cargo update -p cc --precise 1.0.94
+    cargo update -p serde_json --precise 1.0.98
+    cargo update -p serde --precise 1.0.156
+    cargo update -p ppv-lite86 --precise 0.2.8
 fi
 
 if [ "$DO_FEATURE_MATRIX" = true ]

src/blind.rs

@@ -262,7 +262,8 @@ impl TxOutSecrets {
         }
     }
 
-    /// Gets the surjection inputs from [`TxOutSecrets`]
+    /// Gets the surjection inputs from [`TxOutSecrets`].
+    ///
     /// Returns a tuple (assetid, blind_factor, generator) if the blinds are
     /// consistent with asset commitment
     /// Otherwise, returns an error
@@ -280,6 +281,7 @@ impl TxOutSecrets {
 }
 
 /// Data structure used to provide inputs to [`SurjectionProof`] methods.
+///
 /// Inputs for which we don't know the secrets can be [`SurjectionInput::Unknown`],
 /// while inputs from user's wallet should be [`SurjectionInput::Known`]
 ///

src/encode.rs

@@ -403,6 +403,12 @@ impl Encodable for Vec<u8> {
 impl Decodable for Vec<u8> {
     fn consensus_decode<D: crate::ReadExt>(mut d: D) -> Result<Self, Error> {
         let s = VarInt::consensus_decode(&mut d)?.0 as usize;
+        if s > MAX_VEC_SIZE {
+            return Err(self::Error::OversizedVectorAllocation {
+                requested: s,
+                max: MAX_VEC_SIZE,
+            });
+        }
         let mut v = vec![0; s];
         d.read_slice(&mut v)?;
         Ok(v)

src/fast_merkle_root.rs

@@ -24,6 +24,7 @@ fn sha256midstate(left: &[u8], right: &[u8]) -> sha256::Midstate {
 }
 
 /// Compute the Merkle root of the give hashes using mid-state only.
+///
 /// The inputs must be byte slices of length 32.
 /// Note that the merkle root calculated with this method is not the same as the
 /// one computed by a normal SHA256(d) merkle root.

src/hash_types.rs

@@ -12,7 +12,9 @@
 // If not, see <http://creativecommons.org/publicdomain/zero/1.0/>.
 //
 
-//! File defines types for hashes used throughout the library. These types are needed in order
+//! File defines types for hashes used throughout the library.
+//!
+//! These types are needed in order
 //! to avoid mixing data of the same hash format (like SHA256d) but of different meaning
 //! (transaction id, block hash etc).
 

src/opcodes.rs

@@ -448,16 +448,20 @@ pub mod all {
     /// and completing the padding
     pub const OP_SHA256FINALIZE: All = All {code: 0xc6};
     /// Pop a CScriptNum input index idx and push the outpoint as a tuple.
+    ///
     /// First push the txid(32) of the prev_out, followed by a 4 byte push of
     /// vout followed by a push for the outpoint_flag(1)
     pub const OP_INSPECTINPUTOUTPOINT: All = All {code: 0xc7};
     /// Pop a CScriptNum input index idx and push the nAsset onto the stack as two elements.
+    ///
     /// The first push the assetID(32), followed by the prefix(1)
     pub const OP_INSPECTINPUTASSET: All = All {code: 0xc8};
     /// Pop a CScriptNum input index idx and push the nValue as a tuple,
+    ///
     /// value(8 byte LE, 32) followed by prefix(1),
     pub const OP_INSPECTINPUTVALUE: All = All {code: 0xc9};
     /// Pop a CScriptNum input index idx and push the following depending the type of scriptPubkey:
+    ///
     /// - If the scriptPubKey is not a native segwit program, push a single sha256
     ///   hash of the scriptPubKey on stack top. Next, push a CScriptNum(-1) to
     ///   indicate a non-native segwit scriptPubKey.
@@ -467,7 +471,9 @@ pub mod all {
     /// Pop a CScriptNum input index idx and push the nSequence(4) as little-endian number.
     pub const OP_INSPECTINPUTSEQUENCE: All = All {code: 0xcb};
     /// Pop a CScriptNum input index idx and push the assetIssuance information if the asset has issuance,
-    /// otherwise push an empty vector. Refer to the [spec](https://github.com/ElementsProject/elements/blob/master/doc/tapscript_opcodes.md)
+    /// otherwise push an empty vector.
+    ///
+    /// Refer to the [spec](https://github.com/ElementsProject/elements/blob/master/doc/tapscript_opcodes.md)
     /// for details
     pub const OP_INSPECTINPUTISSUANCE: All = All {code: 0xcc};
     /// Pushes the current input index as CScriptNum. This can be used in conjunction with
@@ -496,18 +502,22 @@ pub mod all {
     /// Push the transaction weight (8) as little-endian
     pub const OP_TXWEIGHT: All = All {code: 0xd6};
     /// Pop the first number(8 byte LE) as b followed another pop for a(8 byte LE).
+    ///
     /// Push a + b onto the stack. Push 1 CScriptNum if there is no overflow.
     /// Refer to the spec for details when dealing with overflow.
     pub const OP_ADD64: All = All {code: 0xd7};
-    /// pop the first number(8 byte LE) as b followed another pop for a(8 byte LE).
+    /// Pop the first number(8 byte LE) as b followed another pop for a(8 byte LE).
+    ///
     /// Push a - b onto the stack. Push 1 CScriptNum if there is no overflow.
     /// Refer to the spec for details when dealing with overflow.
     pub const OP_SUB64: All = All {code: 0xd8};
     /// Pop the first number(8 byte LE) as b followed another pop for a(8 byte LE).
+    ///
     /// Push a*b onto the stack. Push 1 CScriptNum if there is no overflow.
     /// Refer to the spec for details when dealing with overflow.
     pub const OP_MUL64: All = All {code: 0xd9};
-    /// pop the first number(8 byte LE) as b followed another pop for a(8 byte LE).
+    /// Pop the first number(8 byte LE) as b followed another pop for a(8 byte LE).
+    ///
     /// First push remainder a%b(must be non-negative and less than |b|) onto the
     /// stack followed by quotient(a//b) onto the stack.
     ///
@@ -516,44 +526,54 @@ pub mod all {
     /// Refer to the spec for details when dealing with overflow.
     pub const OP_DIV64: All = All {code: 0xda};
     /// Pop the first number(8 byte LE) as a and pushes -a on the stack top.
+    ///
     /// If the number is -2^63 treat as overflow, otherwise push CScriptNum 1 to indicate no overflow.
     /// Refer to the spec for details when dealing with overflow.
     pub const OP_NEG64: All = All {code: 0xdb};
-    /// pop the first number(8 byte LE) as b followed another pop for a(8 byte LE). Push a < b.
+    /// Pop the first number(8 byte LE) as b followed another pop for a(8 byte LE). Push a < b.
+    ///
     /// Note that this operation cannot fail
     pub const OP_LESSTHAN64: All = All {code: 0xdc};
-    /// pop the first number(8 byte LE) as b followed another pop for a(8 byte LE). Push a <= b.
+    /// Pop the first number(8 byte LE) as b followed another pop for a(8 byte LE). Push a <= b.
+    ///
     /// Note that this operation cannot fail
     pub const OP_LESSTHANOREQUAL64: All = All {code: 0xdd};
-    /// pop the first number(8 byte LE) as b followed another pop for a(8 byte LE). Push a > b
+    /// Pop the first number(8 byte LE) as b followed another pop for a(8 byte LE). Push a > b.
+    ///
     /// Note that this operation cannot fail
     pub const OP_GREATERTHAN64: All = All {code: 0xde};
-    /// pop the first number(8 byte LE) as b followed another pop for a(8 byte LE). Push a >= b.
+    /// Pop the first number(8 byte LE) as b followed another pop for a(8 byte LE). Push a >= b.
     /// Note that this operation cannot fail
     pub const OP_GREATERTHANOREQUAL64: All = All {code: 0xdf};
-    /// pop the stack as minimal CScriptNum, push 8 byte signed LE corresponding to that number.
+    /// Pop the stack as minimal CScriptNum, push 8 byte signed LE corresponding to that number.
     pub const OP_SCRIPTNUMTOLE64: All = All {code: 0xe0};
-    /// pop the stack as a 8 byte signed LE. Convert to CScriptNum and push it, abort on fail.
+    /// Pop the stack as a 8 byte signed LE. Convert to CScriptNum and push it, abort on fail.
+    ///
     /// Please check the range of the operand before calling the opcode.
     pub const OP_LE64TOSCRIPTNUM: All = All {code: 0xe1};
-    /// pop the stack as a 4 byte unsigned LE. Push the corresponding 8 byte signed LE number.
+    /// Pop the stack as a 4 byte unsigned LE. Push the corresponding 8 byte signed LE number.
+    ///
     /// Cannot fail, useful for operating of version, locktime, sequence, number of inputs,
     /// number of outputs, weight etc.
     pub const OP_LE32TOLE64: All = All {code: 0xe2};
-    ///  Pops three elements from stack as described below:
-    /// 1) a 32 byte big endian, unsigned scalar k.
-    /// 2) Compressed EC point P, and
-    /// 3) compressed EC point Q.
+    /// Pops three elements from stack as:
+    ///
+    /// 1. a 32 byte big endian, unsigned scalar k.
+    /// 2. Compressed EC point P, and
+    /// 3. compressed EC point Q.
     ///
     /// Abort if P, Q is invalid or k is not 32 bytes and outside of secp256k1 curve order.
+    ///
     /// Abort if Q != k*P.
     pub const OP_ECMULSCALARVERIFY: All = All {code: 0xe3};
     /// Pop the three elements as:
-    /// 1) 32 byte X-only internal key P,
-    /// 2) a 32 byte big endian, unsigned scalar k, and
-    /// 3) 33 byte compressed point Q.
+    ///
+    /// 1. 32 byte X-only internal key P,
+    /// 2. a 32 byte big endian, unsigned scalar k, and
+    /// 3. 33 byte compressed point Q.
     ///
     /// Abort if P, Q is invalid or k is not 32 bytes and outside of secp256k1 curve order.
+    ///
     /// Abort if Q != P + k*G where G is the generator for secp256k1.
     pub const OP_TWEAKVERIFY: All = All {code: 0xe4};
     /// Synonym for OP_RETURN

src/pset/map/input.rs

@@ -321,7 +321,9 @@ impl Default for Input {
     }
 }
 
-/// A Signature hash type for the corresponding input. As of taproot upgrade, the signature hash
+/// A Signature hash type for the corresponding input.
+///
+/// As of taproot upgrade, the signature hash
 /// type can be either [`EcdsaSighashType`] or [`SchnorrSighashType`] but it is not possible to know
 /// directly which signature hash type the user is dealing with. Therefore, the user is responsible
 /// for converting to/from [`PsbtSighashType`] from/to the desired signature hash type they need.

src/script.rs

@@ -178,12 +178,14 @@ fn build_scriptint(n: i64) -> Vec<u8> {
 }
 
 /// Helper to decode an integer in script format
+///
 /// Notice that this fails on overflow: the result is the same as in
 /// bitcoind, that only 4-byte signed-magnitude values may be read as
 /// numbers. They can be added or subtracted (and a long time ago,
 /// multiplied and divided), and this may result in numbers which
 /// can't be written out in 4 bytes or less. This is ok! The number
 /// just can't be read as a number again.
+///
 /// This is a bit crazy and subtle, but it makes sense: you can load
 /// 32-bit numbers and do anything with them, which back when mult/div
 /// was allowed, could result in up to a 64-bit number. We don't want

src/taproot.rs

@@ -103,6 +103,7 @@ pub const TAPROOT_CONTROL_MAX_SIZE: usize =
 // type alias for versioned tap script corresponding merkle proof
 type ScriptMerkleProofMap = BTreeMap<(Script, LeafVersion), BTreeSet<TaprootMerkleBranch>>;
 /// Data structure for representing Taproot spending information.
+///
 /// Taproot output corresponds to a combination of a
 /// single public key condition (known the internal key), and zero or more
 /// general conditions encoded in scripts organized in the form of a binary tree.