chore(execution): sync comments between latest and v0

iota-execution/v0/iota-adapter/src/adapter.rs

@@ -36,6 +36,12 @@ mod checked {
     };
     use tracing::instrument;
 
+    /// Creates a new instance of `MoveVM` with the specified native functions
+    /// and protocol configuration. The VM is configured using a `VMConfig`
+    /// that sets limits for vector length, value depth, and other
+    /// runtime options based on the provided `ProtocolConfig`. If gas profiling
+    /// is enabled, the function configures the profiler with the provided
+    /// path.
     pub fn new_move_vm(
         natives: NativeFunctionTable,
         protocol_config: &ProtocolConfig,
@@ -71,6 +77,12 @@ mod checked {
         .map_err(|_| IotaError::ExecutionInvariantViolation)
     }
 
+    /// Creates a new set of `NativeContextExtensions` for the Move VM,
+    /// configuring extensions such as `ObjectRuntime` and
+    /// `NativesCostTable`. These extensions manage object resolution, input
+    /// objects, metering, protocol configuration, and metrics tracking.
+    /// They are available and mainly used in native function implementations
+    /// via `NativeContext` instance.
     pub fn new_native_extensions<'r>(
         child_resolver: &'r dyn ChildObjectResolver,
         input_objects: BTreeMap<ObjectID, object_runtime::InputObject>,
@@ -127,6 +139,7 @@ mod checked {
         Ok(())
     }
 
+    /// Returns an error message for a missing unwrapped object.
     pub fn missing_unwrapped_msg(id: &ObjectID) -> String {
         format!(
             "Unable to unwrap object {}. Was unable to retrieve last known version in the parent sync",

iota-execution/v0/iota-adapter/src/execution_engine.rs

@@ -74,6 +74,17 @@ mod checked {
         type_layout_resolver::TypeLayoutResolver,
     };
 
+    /// The main entry point to the adapter's transaction execution. It
+    /// prepares a transaction for execution, then executes it through an
+    /// inner execution method and finally produces an instance of
+    /// transaction effects. It also returns the inner temporary store, which
+    /// contains the objects resulting from the transction execution, the gas
+    /// status instance, which tracks the gas usage, and the execution result.
+    /// The function handles transaction execution based on the provided
+    /// `TransactionKind`. It checks for any expensive operations, manages
+    /// shared object references, and ensures transaction dependencies are
+    /// met. The returned objects are not committed to the store until the
+    /// resulting effects are applied by the caller.
     #[instrument(name = "tx_execute_to_effects", level = "debug", skip_all)]
     pub fn execute_transaction_to_effects<Mode: ExecutionMode>(
         store: &dyn BackingStore,
@@ -231,6 +242,12 @@ mod checked {
         )
     }
 
+    /// Function dedicated to the execution of a GenesisTransaction.
+    /// The function creates an `InnerTemporaryStore`, processes the input
+    /// objects, and executes the transaction in unmetered mode using the
+    /// `Genesis` execution mode. It returns an inner temporary store that
+    /// contains the objects found into the input `GenesisTransaction` by
+    /// adding the data for `previous_transaction` and `storage_rebate` fields.
     pub fn execute_genesis_state_update(
         store: &dyn BackingStore,
         protocol_config: &ProtocolConfig,
@@ -263,6 +280,14 @@ mod checked {
         Ok(temporary_store.into_inner())
     }
 
+    /// Executes a transaction by processing the specified `TransactionKind`,
+    /// applying the necessary gas charges and running the main execution logic.
+    /// The function handles certain error conditions such as denied
+    /// certificate, deleted input objects, exceeded execution meter limits,
+    /// failed conservation checks. It also accounts for unmetered storage
+    /// rebates and adjusts for special cases like epoch change
+    /// transactions. Gas costs are managed through the `GasCharger`
+    /// argument; gas is also charged in case of errors.
     #[instrument(name = "tx_execute", level = "debug", skip_all)]
     fn execute_transaction<Mode: ExecutionMode>(
         temporary_store: &mut TemporaryStore<'_>,
@@ -387,6 +412,14 @@ mod checked {
         (cost_summary, result)
     }
 
+    /// Performs IOTA conservation checks during transaction execution, ensuring
+    /// that the transaction does not create or destroy IOTA. If
+    /// conservation is violated, the function attempts to recover
+    /// by resetting the gas charger, recharging gas, and rechecking
+    /// conservation. If recovery fails, it panics to avoid IOTA creation or
+    /// destruction. These checks include both simple and expensive
+    /// checks based on the configuration and are skipped for genesis or epoch
+    /// change transactions.
     #[instrument(name = "run_conservation_checks", level = "debug", skip_all)]
     fn run_conservation_checks<Mode: ExecutionMode>(
         temporary_store: &mut TemporaryStore<'_>,
@@ -465,6 +498,10 @@ mod checked {
         result
     }
 
+    /// Checks if the estimated size of transaction effects exceeds predefined
+    /// limits based on the protocol configuration. For metered
+    /// transactions, it enforces hard limits, while for system transactions, it
+    /// allows soft limits with warnings.
     #[instrument(name = "check_meter_limit", level = "debug", skip_all)]
     fn check_meter_limit(
         temporary_store: &mut TemporaryStore<'_>,
@@ -504,6 +541,10 @@ mod checked {
         }
     }
 
+    /// Checks if the total size of written objects in the transaction exceeds
+    /// the limits defined in the protocol configuration. For metered
+    /// transactions, it enforces a hard limit, while for system transactions,
+    /// it allows a soft limit with warnings.
     #[instrument(name = "check_written_objects_limit", level = "debug", skip_all)]
     fn check_written_objects_limit<Mode: ExecutionMode>(
         temporary_store: &mut TemporaryStore<'_>,
@@ -547,6 +588,12 @@ mod checked {
         Ok(())
     }
 
+    /// Executes the given transaction based on its `TransactionKind` by
+    /// processing it through corresponding handlers such as epoch changes,
+    /// genesis transactions, consensus commit prologues, and programmable
+    /// transactions. For each type of transaction, the corresponding logic is
+    /// invoked, such as advancing the epoch, setting up consensus commits, or
+    /// executing a programmable transaction.
     #[instrument(level = "debug", skip_all)]
     fn execution_loop<Mode: ExecutionMode>(
         temporary_store: &mut TemporaryStore<'_>,
@@ -684,6 +731,14 @@ mod checked {
         Ok(result)
     }
 
+    /// Mints epoch rewards by creating both storage and computation rewards
+    /// using a `ProgrammableTransactionBuilder`. The function takes in the
+    /// `AdvanceEpochParams`, serializes the storage and computation
+    /// charges, and invokes the reward creation function within the Iota
+    /// Prepares invocations for creating both storage and computation rewards
+    /// with a `ProgrammableTransactionBuilder` using the `AdvanceEpochParams`.
+    /// The corresponding functions from the Iota framework can be invoked later
+    /// during execution of the programmable transaction.
     fn mint_epoch_rewards_in_pt(
         builder: &mut ProgrammableTransactionBuilder,
         params: &AdvanceEpochParams,
@@ -718,6 +773,13 @@ mod checked {
         (storage_charges, computation_rewards)
     }
 
+    /// Constructs a `ProgrammableTransaction` to advance the epoch. It creates
+    /// storage charges and computation rewards by invoking
+    /// `mint_epoch_rewards_in_pt`, advances the epoch by setting up the
+    /// necessary arguments, such as epoch number, protocol version, storage
+    /// rebate, and slashing rate, and executing the `advance_epoch` function
+    /// within the Iota system. Then, it destroys the storage rebates to
+    /// complete the transaction.
     pub fn construct_advance_epoch_pt(
         mut builder: ProgrammableTransactionBuilder,
         params: &AdvanceEpochParams,
@@ -774,6 +836,13 @@ mod checked {
         Ok(builder.finish())
     }
 
+    /// Advances the epoch by constructing a `ProgrammableTransaction` with
+    /// `construct_advance_epoch_pt` and executing it.
+    /// If the transaction fails, it switches to safe mode and retries the
+    /// epoch advancement in a more controlled environment. The function also
+    /// handles the publication and upgrade of system packages for the new
+    /// epoch. If any system package is added or upgraded, it ensures the
+    /// proper execution and storage of the changes.
     fn advance_epoch(
         builder: ProgrammableTransactionBuilder,
         change_epoch: ChangeEpoch,
@@ -949,6 +1018,9 @@ mod checked {
         )
     }
 
+    /// This function adds a Move call to the Iota framework's
+    /// `authenticator_state_create` function, preparing the transaction for
+    /// execution.
     fn setup_authenticator_state_create(
         mut builder: ProgrammableTransactionBuilder,
     ) -> ProgrammableTransactionBuilder {
@@ -964,6 +1036,7 @@ mod checked {
         builder
     }
 
+    /// Configures a `ProgrammableTransactionBuilder` to create a bridge.
     fn setup_bridge_create(
         mut builder: ProgrammableTransactionBuilder,
         chain_id: ChainIdentifier,
@@ -994,6 +1067,8 @@ mod checked {
         builder
     }
 
+    /// Configures a `ProgrammableTransactionBuilder` to update the bridge
+    /// committee.
     fn setup_bridge_committee_update(
         mut builder: ProgrammableTransactionBuilder,
         bridge_shared_version: SequenceNumber,
@@ -1035,6 +1110,12 @@ mod checked {
         builder
     }
 
+    /// Sets up and executes a `ProgrammableTransaction` to update the
+    /// authenticator state. This function constructs a transaction that
+    /// invokes the `authenticator_state_update` function from the Iota
+    /// framework, passing the authenticator state object and new active JWKS as
+    /// arguments. It then executes the transaction using the system
+    /// execution mode.
     fn setup_authenticator_state_update(
         update: AuthenticatorStateUpdateV1,
         temporary_store: &mut TemporaryStore<'_>,
@@ -1077,6 +1158,10 @@ mod checked {
         )
     }
 
+    /// Configures a `ProgrammableTransactionBuilder` to expire authenticator
+    /// state by invoking the `authenticator_state_expire_jwks` function
+    /// from the Iota framework. The function adds the necessary Move call
+    /// with the authenticator state object and the minimum epoch as arguments.
     fn setup_authenticator_state_expire(
         mut builder: ProgrammableTransactionBuilder,
         expire: AuthenticatorStateExpire,
@@ -1100,6 +1185,11 @@ mod checked {
         builder
     }
 
+    /// The function constructs a transaction that invokes
+    /// the `randomness_state_update` function from the Iota framework,
+    /// passing the randomness state object, the `randomness_round`,
+    /// and the `random_bytes` as arguments. It then executes the transaction
+    /// using the system execution mode.
     fn setup_randomness_state_update(
         update: RandomnessStateUpdate,
         temporary_store: &mut TemporaryStore<'_>,

iota-execution/v0/iota-adapter/src/programmable_transactions/context.rs

@@ -118,6 +118,12 @@ mod checked {
     }
 
     impl<'vm, 'state, 'a> ExecutionContext<'vm, 'state, 'a> {
+        /// Creates a new instance of the transaction execution context,
+        /// initializing the necessary components such as protocol
+        /// configuration, Move VM, gas management, inputs, and native
+        /// extensions. This function processes the input arguments, sets up gas
+        /// handling for the transaction, and prepares the state for
+        /// executing Move programs.
         #[instrument(name = "ExecutionContext::new", level = "trace", skip_all)]
         pub fn new(
             protocol_config: &'a ProtocolConfig,
@@ -381,6 +387,7 @@ mod checked {
             ) {
                 return Err(CommandArgumentError::InvalidObjectByValue);
             }
+
             // Any input object taken by value must be mutable
             if matches!(
                 input_metadata_opt,
@@ -940,6 +947,10 @@ mod checked {
             Ok((metadata, &mut result_value.value))
         }
 
+        /// Executes a Move function bypassing visibility checks, allowing the
+        /// execution of private or protected functions. This method
+        /// sets up the necessary gas status and data store, and then
+        /// delegates the execution to the Move VM runtime.
         pub(crate) fn execute_function_bypass_visibility(
             &mut self,
             module: &ModuleId,
@@ -960,6 +971,10 @@ mod checked {
             )
         }
 
+        /// Loads a Move function from the specified module with the given type
+        /// arguments without executing it. This function initializes
+        /// the data store and delegates the loading process to the Move
+        /// VM runtime.
         pub(crate) fn load_function(
             &mut self,
             module_id: &ModuleId,
@@ -975,6 +990,10 @@ mod checked {
             )
         }
 
+        /// Constructs an `ObjectValue` based on the provided Move object type,
+        /// transferability, usage context, and byte contents. This
+        /// function utilizes the protocol configuration, Move VM, and
+        /// linkage view to properly interpret and instantiate the object.
         pub(crate) fn make_object_value(
             &mut self,
             type_: MoveObjectType,
@@ -991,6 +1010,10 @@ mod checked {
             )
         }
 
+        /// Publishes a bundle of Move modules to the blockchain under the
+        /// specified sender's account address. The function initializes
+        /// a data store and delegates the publishing operation to the Move VM
+        /// runtime.
         pub fn publish_module_bundle(
             &mut self,
             modules: Vec<Vec<u8>>,
@@ -1009,6 +1032,8 @@ mod checked {
     }
 
     impl<'vm, 'state, 'a> TypeTagResolver for ExecutionContext<'vm, 'state, 'a> {
+        /// Retrieves the `TypeTag` corresponding to the provided `Type` by
+        /// querying the Move VM runtime.
         fn get_type_tag(&self, type_: &Type) -> Result<TypeTag, ExecutionError> {
             self.vm
                 .get_runtime()
@@ -1040,6 +1065,11 @@ mod checked {
         }
     }
 
+    /// Loads a `Type` from the given `StructTag`, retrieving the corresponding
+    /// struct from the package in storage. The function sets up the linkage
+    /// context to resolve the struct's module and verifies
+    /// any type parameter constraints. If the struct has type parameters, they
+    /// are recursively loaded and verified.
     pub fn load_type_from_struct(
         vm: &MoveVM,
         linkage_view: &mut LinkageView,
@@ -1135,6 +1165,12 @@ mod checked {
         })
     }
 
+    /// Constructs an `ObjectValue` based on the provided `MoveObjectType`,
+    /// contents, and additional flags such as transferability and usage
+    /// context. If the object is a coin, it deserializes the contents into
+    /// a `Coin` type; otherwise, it treats the contents as raw data. The
+    /// function then loads the corresponding struct type from the Move
+    /// package and verifies its abilities if needed.
     pub(crate) fn make_object_value(
         vm: &MoveVM,
         linkage_view: &mut LinkageView,
@@ -1168,6 +1204,10 @@ mod checked {
         })
     }
 
+    /// Converts a provided `Object` into an `ObjectValue`, extracting and
+    /// validating the `MoveObjectType` and contents. This function assumes
+    /// the object contains Move-specific data and passes the extracted data
+    /// through `make_object_value` to create the corresponding `ObjectValue`.
     pub(crate) fn value_from_object(
         vm: &MoveVM,
         linkage_view: &mut LinkageView,