From d31158d3646f3c7e4832b9ca50f6ffe02800ff4c Mon Sep 17 00:00:00 2001
From: rkrux <rkrux.connect@gmail.com>
Date: Mon, 5 May 2025 17:04:27 +0530
Subject: [PATCH] psbt: clarify PSBT, PSBTInput, PSBTOutput unserialization
 flows

The unserialization flows of the PSBT types work based on few underlying
assumptions of functions from `serialize.h` & `stream.h` that takes some
to understand when read the first time.

Add few comments that highlight these assumptions hopefully making it easier
to grasp. Also, mention key/value format types as per BIP 174.
---
 src/psbt.h | 27 ++++++++++++++++++---------
 1 file changed, 18 insertions(+), 9 deletions(-)

diff --git a/src/psbt.h b/src/psbt.h
index dd7b02dc607..03b1462e606 100644
--- a/src/psbt.h
+++ b/src/psbt.h
@@ -465,7 +465,8 @@ struct PSBTInput
         // Read loop
         bool found_sep = false;
         while(!s.empty()) {
-            // Read
+            // Read the key of format "<keylen><keytype><keydata>" after which
+            // "key" will contain "<keytype><keydata>"
             std::vector<unsigned char> key;
             s >> key;
 
@@ -476,11 +477,13 @@ struct PSBTInput
                 break;
             }
 
-            // Type is compact size uint at beginning of key
+            // "skey" is used so that "key" is unchanged after reading keytype below
             SpanReader skey{key};
+            // keytype is of the format compact size uint at the beginning of "key"
             uint64_t type = ReadCompactSize(skey);
 
-            // Do stuff based on type
+            // Do stuff based on keytype "type", i.e., key checks, reading values of the
+            // format "<valuelen><valuedata>" from the stream "s", and value checks
             switch(type) {
                 case PSBT_IN_NON_WITNESS_UTXO:
                 {
@@ -949,7 +952,8 @@ struct PSBTOutput
         // Read loop
         bool found_sep = false;
         while(!s.empty()) {
-            // Read
+            // Read the key of format "<keylen><keytype><keydata>" after which
+            // "key" will contain "<keytype><keydata>"
             std::vector<unsigned char> key;
             s >> key;
 
@@ -960,11 +964,13 @@ struct PSBTOutput
                 break;
             }
 
-            // Type is compact size uint at beginning of key
+            // "skey" is used so that "key" is unchanged after reading keytype below
             SpanReader skey{key};
+            // keytype is of the format compact size uint at the beginning of "key"
             uint64_t type = ReadCompactSize(skey);
 
-            // Do stuff based on type
+            // Do stuff based on keytype "type", i.e., key checks, reading values of the
+            // format "<valuelen><valuedata>" from the stream "s", and value checks
             switch(type) {
                 case PSBT_OUT_REDEEMSCRIPT:
                 {
@@ -1212,7 +1218,8 @@ struct PartiallySignedTransaction
         // Read global data
         bool found_sep = false;
         while(!s.empty()) {
-            // Read
+            // Read the key of format "<keylen><keytype><keydata>" after which
+            // "key" will contain "<keytype><keydata>"
             std::vector<unsigned char> key;
             s >> key;
 
@@ -1223,11 +1230,13 @@ struct PartiallySignedTransaction
                 break;
             }
 
-            // Type is compact size uint at beginning of key
+            // "skey" is used so that "key" is unchanged after reading keytype below
             SpanReader skey{key};
+            // keytype is of the format compact size uint at the beginning of "key"
             uint64_t type = ReadCompactSize(skey);
 
-            // Do stuff based on type
+            // Do stuff based on keytype "type", i.e., key checks, reading values of the
+            // format "<valuelen><valuedata>" from the stream "s", and value checks
             switch(type) {
                 case PSBT_GLOBAL_UNSIGNED_TX:
                 {