Subintent hash at device side

sbor/src/bech32/address.rs

@@ -4,6 +4,8 @@ use crate::bech32::network::NetworkId;
 use crate::math::StaticVec;
 use crate::type_info::ADDRESS_STATIC_LEN;
 
+/// Reusable storage for various types of addresses. All addresses share same length.
+/// For convenience in use with stream decoders, additional boolean flag is maintained. 
 #[derive(Copy, Clone, Debug)]
 pub struct Address {
     address: [u8; ADDRESS_STATIC_LEN as usize],

sbor/src/decoder_error.rs

@@ -1,8 +1,10 @@
-// Errors which could appear during decoding
+/// Errors which could appear during decoding.
+/// First parameter is the position in the stream where error was encountered.
+/// Second parameter (where available) is the byte which caused the error.
 #[derive(Copy, Clone, Debug)]
 pub enum DecoderError {
     UnknownType(usize, u8),          // Unknown main type id
-    UnknownSubType(usize, u8),       // Unknown sub type id (element, key, value)
+    UnknownSubType(usize, u8),       // Unknown subtype id (element, key, value)
     UnknownDiscriminator(usize, u8), // Unknown discriminator for OWN or NFL ID
     InvalidLen(usize, u8),           // Incorrectly encoded element length
     InvalidState(usize),             // Input caused decoder to reach invalid state

sbor/src/digest/digest.rs

@@ -10,6 +10,8 @@ const COPY_SIZE: usize = ADDRESS_STATIC_LEN as usize;
 const COPY_FROM: usize = BLAKE2B_DIGEST_SIZE - COPY_SIZE;
 const COPY_TO: usize = BLAKE2B_DIGEST_SIZE;
 
+/// Value Object to represent a Blake2b digest.
+/// Serves two purposes: 1 - preserves context and 2 - ensures automatic cleanup after use.
 #[repr(C, packed)]
 #[derive(Clone, Debug)]
 pub struct Digest(pub [u8; BLAKE2B_DIGEST_SIZE]);

sbor/src/digest/hash_calculator.rs

@@ -1,15 +1,28 @@
+/// Babylon uses quite non-traditional approach to hash calculation. Instead of hashing the whole transaction or subintent SBOR-encoded blob,
+/// it hashes individual components of the transaction/subintent. Then final hash is calculated as a hash of hashes.
+/// This approach introduces substantial complexity in case of the stream decoding and requires a state machine to handle the decoding process.
+///
+/// The general idea is to have two independent digesters - one for current element and one for final hash. Unfortunately, BLOBS require one more digester
+/// because hash of the BLOB field is calculated as hash of hashes of individual BLOBs.
+///
+/// The subintent introduces additional complexity, as hashes for fields are calculated with initial (type) byte skipped
+/// (see `radix-transactions/src/model/versioned.rs` in `radix-scrypto` repository for details of hash calculation)
+///
+/// Implementation basically consists of two decoders which share the same digesters for memory efficiency.
 use core::result::Result;
 
 use crate::digest::digest::Digest;
 use crate::digest::digester::Digester;
 use crate::sbor_decoder::SborEvent;
 
+/// Working modes for the hash calculator
 #[repr(u8)]
 pub enum HashCalculatorMode {
     Transaction,
     PreAuth,
 }
 
+/// State machine phases for the transaction hash calculator
 #[derive(Copy, Clone, PartialEq)]
 #[repr(u8)]
 enum TxHashPhase {
@@ -25,6 +38,7 @@ enum TxHashPhase {
     HashingError,
 }
 
+/// State machine phases for the subintent hash calculator
 #[derive(Copy, Clone, PartialEq, Debug)]
 #[repr(u8)]
 enum SiHashPhase {
@@ -43,6 +57,7 @@ enum SiHashPhase {
     HashingError,
 }
 
+/// Internal state machine which controls the process of finalizing/merging hashes
 #[derive(Copy, Clone, Debug)]
 #[repr(u8)]
 enum HashCommitPhase {
@@ -85,7 +100,7 @@ pub struct HashCalculator<T: Digester> {
     mode: HashCalculatorMode,
 }
 
-// Transaction intent hash calculator
+/// Transaction intent hash calculator implementation
 impl<T: Digester> HashCalculator<T> {
     fn tx_handle(&mut self, event: SborEvent) {
         match event {
@@ -229,6 +244,7 @@ impl<T: Digester> HashCalculator<T> {
     }
 }
 
+/// Subintent hash calculator implementation
 impl<T: Digester> HashCalculator<T> {
     fn si_handle(&mut self, event: SborEvent) {
         match event {
@@ -367,6 +383,10 @@ impl<T: Digester> HashCalculator<T> {
         match self.work_digester.finalize() {
             Ok(digest) => match self.output_digester.update(digest.as_bytes()) {
                 Ok(_) => {
+                    // Use it for debugging hash calculator: it prints the hash of each
+                    // processed element. Note that si_test_data.rs contains these hashes as well,
+                    // so you can compare (sorry, only visually for now) calculated hash with
+                    // expected one and find which element is calculated incorrectly.
                     #[cfg(test)]
                     {
                         let blob = digest.as_bytes();
@@ -426,7 +446,7 @@ impl<T: Digester> HashCalculator<T> {
     }
 }
 
-// Common part + externally visible API for both transaction and subintent hash calculators
+/// Common part + externally visible API for both transaction and subintent hash calculators
 impl<T: Digester> HashCalculator<T> {
     const PAYLOAD_PREFIX: u8 = 0x54;
     const V1_INTENT: u8 = 1;

sbor/src/instruction.rs

@@ -1,4 +1,4 @@
-// Instructions recognized by instruction extractor
+/// Instructions recognized by instruction extractor
 // Keep in sync with
 // https://raw.githubusercontent.com/radixdlt/radixdlt-scrypto/develop/transaction/src/model/instruction.rs
 

sbor/src/instruction_extractor.rs

@@ -1,5 +1,7 @@
-// Process events received from decoder and extract data related to instructions
-
+/// Process events received from SBOR decoder and extract data related to each instruction
+/// and its parameters.
+/// Implemented as a state machine which "walks" through the transaction intent and when it reaches
+/// the instructions it starts emitting relevant events.
 use crate::instruction::{to_instruction, InstructionInfo};
 use crate::sbor_decoder::SborEvent;
 use crate::type_info::{to_type_info, TypeInfo, TYPE_ENUM, TYPE_NONE, TYPE_TUPLE};

sbor/src/math/decimal.rs

@@ -6,6 +6,7 @@ use crate::static_vec::StaticVec;
 #[derive(Copy, Clone, Debug)]
 pub struct Decimal(BigInt<192>);
 
+/// Ledger app-specific counterpart of the Scrypto Decimal type
 impl Decimal {
     pub const SIZE_IN_BYTES: usize = BigInt::<192>::NUM_BYTES;
     pub const ZERO: Decimal = Decimal(BigInt::from_limbs([0, 0, 0, 0, 0, 0]));

sbor/src/math/mod.rs

@@ -8,6 +8,9 @@ pub use simple_bigint::bcd::BCD;
 pub use simple_bigint::bigint::{BigInt, BigIntError};
 pub use simple_bigint::ceil_div;
 
+/// String formatting routine for Decimal and PreciseDecimal types.
+/// It converts the underlying BigInt to BCD and then formats it by putting decimal dot where necessary
+/// and stripping/adding leading/trailing zeros where necessary to achieve necessary output.
 pub fn format_big_int<const N: usize, const SCALE: usize, const DISPLAY_WIDTH: usize>(
     input: &BigInt<N>,
     output: &mut StaticVec<u8, DISPLAY_WIDTH>,

sbor/src/math/precise_decimal.rs

@@ -6,6 +6,7 @@ use crate::static_vec::StaticVec;
 #[derive(Copy, Clone)]
 pub struct PreciseDecimal(BigInt<256>);
 
+/// Ledger app-specific counterpart of the Scrypto PreciseDecimal type
 impl PreciseDecimal {
     pub const SIZE_IN_BYTES: usize = BigInt::<256>::NUM_BYTES;
     pub const SCALE: usize = 36;

sbor/src/print/array.rs

@@ -30,11 +30,11 @@ impl<T: Copy> ParameterPrinter<T> for ArrayParameterPrinter {
         }
     }
 
-    fn subcomponent_end(&self, state: &mut ParameterPrinterState<T>) {
-        state.print_text(b", ");
-    }
-
     fn end(&self, state: &mut ParameterPrinterState<T>) {
         state.print_byte(b')');
     }
+
+    fn subcomponent_end(&self, state: &mut ParameterPrinterState<T>) {
+        state.print_text(b", ");
+    }
 }

sbor/src/print/decimals.rs

@@ -2,7 +2,6 @@ use crate::math::{Decimal, PreciseDecimal};
 use crate::print::parameter_printer::ParameterPrinter;
 use crate::print::state::ParameterPrinterState;
 
-// Decimal parameter printer
 pub struct DecimalParameterPrinter {}
 
 pub const DECIMAL_PARAMETER_PRINTER: DecimalParameterPrinter = DecimalParameterPrinter {};
@@ -22,7 +21,6 @@ impl<T: Copy> ParameterPrinter<T> for DecimalParameterPrinter {
     }
 }
 
-// PreciseDecimal parameter printer
 pub struct PreciseDecimalParameterPrinter {}
 
 pub const PRECISE_DECIMAL_PARAMETER_PRINTER: PreciseDecimalParameterPrinter =

sbor/src/print/fanout.rs

@@ -2,6 +2,7 @@ use crate::instruction_extractor::{ExtractorEvent, InstructionHandler};
 use crate::print::instruction_printer::InstructionPrinter;
 use crate::print::tx_summary_detector::TxSummaryDetector;
 
+/// Small adapter used to distribute events to multiple handlers.
 pub struct Fanout<'a, T: Copy> {
     printer: &'a mut InstructionPrinter<T>,
     detector: &'a mut TxSummaryDetector,

sbor/src/print/instruction_printer.rs

@@ -163,6 +163,8 @@ impl<T: Copy> InstructionPrinter<T> {
     }
 }
 
+/// This structure and its implementation are a workaround for Rust compiler for STM32 not
+/// supporting dynamic traits (i.e. virtual methods).
 struct Dispatcher;
 
 // Workaround for not working vtables

sbor/src/print/state.rs

@@ -7,6 +7,7 @@ use crate::print::tty::TTY;
 use crate::sbor_decoder::STACK_DEPTH;
 use crate::static_vec::StaticVec;
 
+/// Element of the parameter printer nesting stack.
 #[repr(C, packed)]
 #[derive(Copy, Clone, Debug)]
 pub struct ValueState {
@@ -38,13 +39,15 @@ impl Default for ValueState {
     }
 }
 
+/// The intermediate buffer size for the individual parameters.
 #[cfg(target_os = "nanos")]
 pub const PARAMETER_AREA_SIZE: usize = 96;
 #[cfg(any(target_os = "nanox", target_os = "nanosplus"))]
 pub const PARAMETER_AREA_SIZE: usize = 256;
 #[cfg(not(any(target_os = "nanos", target_os = "nanox", target_os = "nanosplus")))]
 pub const PARAMETER_AREA_SIZE: usize = 256;
 
+/// The buffer size of the entire message to be displayed.
 #[cfg(target_os = "nanos")]
 pub const DISPLAY_SIZE: usize = 256; // Use smaller buffer for Nano S
 #[cfg(any(target_os = "nanox", target_os = "nanosplus"))]
@@ -57,11 +60,11 @@ pub const TITLE_SIZE: usize = 32;
 pub struct ParameterPrinterState<T: Copy> {
     pub display: StaticVec<u8, { DISPLAY_SIZE }>,
     pub data: StaticVec<u8, { PARAMETER_AREA_SIZE }>,
-    pub title: StaticVec<u8, { TITLE_SIZE }>,
+    pub title: StaticVec<u8, { TITLE_SIZE }>, // Intermediate buffer for formatting instruction titles (instruction number)
     pub stack: StaticVec<ValueState, { STACK_DEPTH as usize }>,
-    pub nesting_level: u8,
+    pub nesting_level: u8,          // Active nesting level in the stack
     pub network_id: NetworkId,
-    pub show_instructions: bool,
+    pub show_instructions: bool,    // Whether to show instructions or not
     tty: TTY<T>,
 }
 
@@ -87,7 +90,7 @@ impl<T: Copy> ParameterPrinterState<T> {
             nesting_level: 0,
             network_id,
             show_instructions: true,
-            tty: tty,
+            tty,
         }
     }
 

sbor/src/print/tx_intent_type.rs

@@ -1,3 +1,5 @@
+/// Transaction intent type as detected by the transaction summary detector.
+/// So far only two types are recognized - Simple Transfer and others.
 #[derive(Copy, Clone, PartialEq)]
 #[repr(u8)]
 pub enum TxIntentType {

sbor/src/print/tx_summary_detector.rs

@@ -1,3 +1,8 @@
+/// Transaction summary detector is used to determine the type of the transaction intent and collect
+/// information about fees.
+/// Implementation consists of two independent state machines - one for detecting the intent type and
+/// other to collect fee information. Both of them use information about decoded instructions
+/// received from `InstructionExtractor`.
 use crate::bech32::address::Address;
 use crate::instruction::{Instruction, InstructionInfo};
 use crate::instruction_extractor::ExtractorEvent;
@@ -7,7 +12,7 @@ use crate::sbor_decoder::SborEvent;
 use crate::static_vec::StaticVec;
 use crate::type_info::*;
 
-// Lock_fee: CallMethod -> Address -> Name ("lock_fee") -> TupleLockFee -> (ValueLockFee) -> DoneLockFee
+/// Transaction fee collector state machine phases.
 #[derive(Copy, Clone, PartialEq)]
 #[repr(u8)]
 pub enum FeePhase {
@@ -20,6 +25,7 @@ pub enum FeePhase {
     ValueStart,
 }
 
+/// Transaction type detector state machine phases.
 #[derive(Copy, Clone, PartialEq)]
 #[repr(u8)]
 pub enum DecodingPhase {
@@ -46,10 +52,10 @@ pub enum DecodingPhase {
 #[derive(Copy, Clone, Debug)]
 pub struct TransferDetails {
     pub fee: Option<Decimal>,
-    pub src_address: Address,
-    pub dst_address: Address,
-    pub res_address: Address,
-    pub amount: Decimal,
+    pub src_address: Address,   // From ...
+    pub dst_address: Address,   // To ...
+    pub res_address: Address,   // Resource ...
+    pub amount: Decimal,        // Amount ...
 }
 
 #[derive(Copy, Clone, Debug)]
@@ -132,14 +138,16 @@ impl DetectedTxType {
     }
 }
 
-//Max of address length and decimal length
+/// Size of temporary buffer for parameter data. It should be enough to store any parameter data
+/// which we're going to use. So far we're operating with addresses, decimal numbers and fixed
+/// method names. None of them exceeds 40 bytes.
 const MAX_TX_DATA_SIZE: usize = 40;
 
 pub struct TxSummaryDetector {
     intent_type: TxIntentType,
     decoding_phase: DecodingPhase,
     fee_phase: FeePhase,
-    data: StaticVec<u8, { MAX_TX_DATA_SIZE }>,
+    data: StaticVec<u8, { MAX_TX_DATA_SIZE }>, // Temporary buffer for parameter data
     fee: Decimal,
     amount: Decimal,
     src_address: Address,