From e79d47c2b9ccaab5c147314ce6ecb41ef698a6f9 Mon Sep 17 00:00:00 2001
From: Michael Zaikin <mz@bakingbad.dev>
Date: Tue, 6 Aug 2024 13:54:14 +0100
Subject: [PATCH] Introduce utreexo state, set, and abstract proofs

---
 src/state.cairo | 48 +++++++++++++++++++++++++++++++-----------------
 1 file changed, 31 insertions(+), 17 deletions(-)

diff --git a/src/state.cairo b/src/state.cairo
index 8928a518..4c598012 100644
--- a/src/state.cairo
+++ b/src/state.cairo
@@ -19,8 +19,28 @@ pub struct ChainState {
     pub epoch_start_time: u32,
     /// Previous timestamps.
     pub prev_timestamps: Span<u32>,
-    // Utreexo roots (for checking [TxIn] inclusion proofs)
-    pub utreexo_roots: Span<felt252>
+    /// Utreexo state
+    pub utreexo_state: @UtreexoState,
+}
+
+/// Accumulator representation of the state aka "Compact State Node"
+pub struct UtreexoState {
+    /// Roots of Merkle tree forest
+    pub roots: Span<felt252>,
+}
+
+/// Utreexo set is used to retrieve TXOs spent by particular inputs
+pub struct UtreexoSet {
+    /// A list of transaction outputs spent in a particular block(s).
+    pub outputs: Span<TxOut>,
+}
+
+/// Inclusion proof for multiple leaves
+pub struct UtreexoBatchProof {
+    /// Indices of tree leaves, one for each output in the utreexo set
+    pub targets: Span<u64>,
+    /// All the nodes required to calculate the root
+    pub proof: Span<felt252>,
 }
 
 /// Represents a block in the blockchain.
@@ -50,15 +70,15 @@ pub struct Header {
     pub nonce: u32,
 }
 
-/// Extended transaction.
+/// Transaction
 /// https://learnmeabitcoin.com/technical/transaction/
-///
-/// Contains additional "meta" fields required for validation.
 #[derive(Drop, Copy)]
 pub struct Transaction {
     /// The version of the transaction.
-    pub version: i32,
+    pub version: u32,
     /// Flag which indicates the presence of witness data.
+    /// It combines `marker` and `flag` fields for now but in the future
+    /// we might need to separate them if transaction structure changes.
     /// Segwit marker and flag do not contribute to TXID (transaction hash),
     /// but do contribute to wTXID.
     pub is_segwit: bool,
@@ -72,24 +92,20 @@ pub struct Transaction {
     pub witnesses: Span<Span<ByteArray>>,
     /// The lock time of the transaction.
     pub lock_time: u32,
-    /// Transaction fee which is diff between total input and output amounts (meta field)
-    pub fee: i64,
 }
 
 /// Output of a transaction.
 /// https://learnmeabitcoin.com/technical/transaction/output/
 #[derive(Drop, Copy)]
 pub struct TxOut {
-    /// The value of the output.
+    /// The value of the output in satoshis.
     pub value: i64,
-    /// The public key script of the output.
+    /// The spending script (aka locking code) for this output.
     pub pk_script: @ByteArray,
 }
 
 /// Extended input of a transaction.
 /// https://learnmeabitcoin.com/technical/transaction/input/
-///
-/// Contains additional "meta" fields required for validation.
 #[derive(Drop, Copy)]
 pub struct TxIn {
     /// The previous TXID this input spends.
@@ -99,10 +115,8 @@ pub struct TxIn {
     /// The signature script which satisfies the conditions placed in the txo pubkey script
     /// or coinbase script that contains block height (since 227,836) and miner nonce (optional).
     pub script: @ByteArray,
-    /// The sequence number of the input ().
+    /// The sequence number of the input.
     pub sequence: u32,
-    /// The previous transaction output this input spends (meta field)
-    pub txo: @TxOut,
-    /// Utreexo inclusion proof of the spent output (meta field)
-    pub txo_proof: Span<felt252>,
+    /// The index of output in the utreexo set (meta field).
+    pub txo_index: u64,
 }