doc: exemplify error handling

Also, fix broken, redundant, and ambiguous links.

triton-vm/src/error.rs

@@ -15,9 +15,13 @@ use crate::stark::StarkHasher;
 use crate::vm::VMState;
 use crate::BFieldElement;
 
+/// Indicates a runtime error that resulted in a crash of Triton VM.
 #[derive(Debug, Clone, PartialEq, Eq, Error)]
 pub struct VMError {
+    /// The reason Triton VM crashed.
     pub source: InstructionError,
+
+    /// The state of Triton VM at the time of the crash.
     pub vm_state: Box<VMState>,
 }
 

triton-vm/src/instruction.rs

@@ -548,7 +548,7 @@ const fn all_instruction_names() -> [&'static str; Instruction::COUNT] {
     names
 }
 
-/// Indicators for all the possible bits in an [`Instruction`](Instruction).
+/// Indicators for all the possible bits in an [`Instruction`].
 #[derive(Debug, Clone, Copy, PartialEq, Eq, Default, EnumCount, EnumIter)]
 pub enum InstructionBit {
     #[default]

triton-vm/src/lib.rs

@@ -121,6 +121,26 @@
 //! assert!(verdict);
 //! ```
 //!
+//! ## Crashing Triton VM
+//!
+//! Successful termination of a program is not guaranteed. For example, a program must execute
+//! `halt` as its last instruction. Certain instructions, such as `assert`, `invert`, or the u32
+//! instructions, can also cause the VM to crash. Upon crashing Triton VM, methods like
+//! [`run`](Program::run) and [`trace_execution`][trace_execution] will return a
+//! [`VMError`][vm_error]. This can be helpful for debugging.
+//!
+//! ```
+//! # use triton_vm::*;
+//! # use triton_vm::error::InstructionError;
+//! let crashing_program = triton_program!(push 2 assert halt);
+//! let vm_error = crashing_program.run([].into(), [].into()).unwrap_err();
+//! assert!(matches!(vm_error.source, InstructionError::AssertionFailed));
+//! // inspect the VM state
+//! eprintln!("{vm_error}");
+//! ```
+//!
+//! [vm_error]: error::VMError
+//! [trace_execution]: Program::trace_execution
 
 #![recursion_limit = "4096"]
 

triton-vm/src/program.rs

@@ -395,8 +395,12 @@ impl Program {
     /// If an error is encountered, the returned [`VMError`] contains the [`VMState`] at the point
     /// of execution failure.
     ///
-    /// See also [`trace_execution`](Self::trace_execution) and
-    /// [`terminal_state`](Self::terminal_state).
+    /// See also [`trace_execution`][trace_execution], [`terminal_state`][terminal_state], and
+    /// [`profile`][profile].
+    ///
+    /// [trace_execution]: Self::trace_execution
+    /// [terminal_state]: Self::terminal_state
+    /// [profile]: Self::profile
     pub fn run(
         &self,
         public_input: PublicInput,
@@ -406,10 +410,14 @@ impl Program {
         Ok(terminal_state.public_output)
     }
 
-    /// Similar to [`run`](Self::run), but returns the entire [`VMState`] instead of just
-    /// the public output.
+    /// Similar to [`run`][run], but returns the entire [`VMState`] instead of just the public
+    /// output.
+    ///
+    /// See also [`trace_execution`][trace_execution] and [`profile`][profile].
     ///
-    /// See also [`trace_execution`](Self::trace_execution) and [`profile`](Self::profile).
+    /// [run]: Self::run
+    /// [trace_execution]: Self::trace_execution
+    /// [profile]: Self::profile
     pub fn terminal_state(
         &self,
         public_input: PublicInput,
@@ -430,8 +438,12 @@ impl Program {
     /// 1. an [`AlgebraicExecutionTrace`], and
     /// 1. the output of the program.
     ///
-    /// See also [`run`][Self::run], [`terminal_state`](Self::terminal_state), and
-    /// [`profile`](Self::profile).
+    /// See also [`run`][run], [`terminal_state`][terminal_state], and
+    /// [`profile`][profile].
+    ///
+    /// [run]: Self::run
+    /// [terminal_state]: Self::terminal_state
+    /// [profile]: Self::profile
     pub fn trace_execution(
         &self,
         public_input: PublicInput,
@@ -458,8 +470,12 @@ impl Program {
     /// in each callable block of instructions. This function returns a Result wrapping a program
     /// profiler report, which is a Vec of [`ProfileLine`]s.
     ///
-    /// See also [`run`](Self::run), [`trace_execution`](Self::trace_execution), and
-    /// [`terminal_state`](Self::terminal_state).
+    /// See also [`run`][run], [`trace_execution`][trace_execution], and
+    /// [`terminal_state`][terminal_state].
+    ///
+    /// [run]: Self::run
+    /// [trace_execution]: Self::trace_execution
+    /// [terminal_state]: Self::terminal_state
     pub fn profile(
         &self,
         public_input: PublicInput,

triton-vm/src/table/hash_table.rs

@@ -70,7 +70,7 @@ pub struct ExtHashTable {}
 /// 1. Processing the `hash` instruction.
 /// 1. Padding mode.
 ///
-/// Changing the mode is only possible when the current [`RoundNumber`][round_no] is [`NUM_ROUNDS`].
+/// Changing the mode is only possible when the current [`RoundNumber`] is [`NUM_ROUNDS`].
 /// The mode evolves as
 /// [`ProgramHashing`][prog_hash] → [`Sponge`][sponge] → [`Hash`][hash] → [`Pad`][pad].
 /// Once mode [`Pad`][pad] is reached, it is not possible to change the mode anymore.
@@ -86,11 +86,10 @@ pub struct ExtHashTable {}
 /// instruction `halt`.
 ///
 /// [program]: crate::program::Program
-/// [round_no]: HashBaseTableColumn::RoundNumber
-/// [prog_hash]: Self::ProgramHashing
-/// [sponge]: Self::Sponge
-/// [hash]: Self::Hash
-/// [pad]: Self::Pad
+/// [prog_hash]: HashTableMode::ProgramHashing
+/// [sponge]: HashTableMode::Sponge
+/// [hash]: type@HashTableMode::Hash
+/// [pad]: HashTableMode::Pad
 #[derive(Display, Debug, Clone, Copy, PartialEq, Eq, EnumIter, EnumCount, Hash)]
 pub enum HashTableMode {
     /// The mode in which the [`Program`][program] is hashed. This is part of program attestation.

triton-vm/src/table/processor_table.rs

@@ -3380,7 +3380,8 @@ impl<'a> Display for ProcessorTraceRow<'a> {
         let register_width = 20;
 
         let register = |reg: ProcessorBaseTableColumn| {
-            format!("{:>register_width$}", self.row[reg.base_table_index()])
+            let reg_string = format!("{}", self.row[reg.base_table_index()]);
+            format!("{reg_string:>register_width$}")
         };
         let multi_register = |regs: [_; 4]| regs.map(register).join(" | ");
 

triton-vm/src/table/ram_table.rs

@@ -34,9 +34,9 @@ pub const BASE_WIDTH: usize = RamBaseTableColumn::COUNT;
 pub const EXT_WIDTH: usize = RamExtTableColumn::COUNT;
 pub const FULL_WIDTH: usize = BASE_WIDTH + EXT_WIDTH;
 
-pub(crate) const INSTRUCTION_TYPE_WRITE: BFieldElement = BFIELD_ZERO;
-pub(crate) const INSTRUCTION_TYPE_READ: BFieldElement = BFIELD_ONE;
-pub(crate) const PADDING_INDICATOR: BFieldElement = BFieldElement::new(2);
+pub const INSTRUCTION_TYPE_WRITE: BFieldElement = BFIELD_ZERO;
+pub const INSTRUCTION_TYPE_READ: BFieldElement = BFIELD_ONE;
+pub const PADDING_INDICATOR: BFieldElement = BFieldElement::new(2);
 
 #[derive(Debug, Clone, PartialEq, Eq, Hash, Arbitrary)]
 pub struct RamTableCall {

triton-vm/src/table/table_column.rs

@@ -258,18 +258,19 @@ pub enum HashBaseTableColumn {
     /// The current instruction. Only relevant for [`Mode`][mode] [`Sponge`][mode_sponge]
     /// in order to distinguish between the different Sponge instructions.
     ///
-    /// [mode]: Self::Mode
+    /// [mode]: HashBaseTableColumn::Mode
     /// [mode_sponge]: crate::table::hash_table::HashTableMode::Sponge
     CI,
 
     /// The number of the current round in the permutation. The round number evolves as
     /// - 0 → 1 → 2 → 3 → 4 → 5 (→ 0) in [`Mode`][mode]s
     /// [`ProgramHashing`][mode_prog_hash], [`Sponge`][mode_sponge] and [`Hash`][mode_hash],
-    /// - 0 → 0 in [`Mode`][mode] [`Sponge`][mode_sponge] if the current instruction [`CI`] is
+    /// - 0 → 0 in [`Mode`][mode] [`Sponge`][mode_sponge] if the current instruction [`CI`][ci] is
     /// `sponge_init`, as an exception to above rule, and
     /// - 0 → 0 in [`Mode`][mode] [`Pad`][mode_pad].
     ///
-    /// [mode]: Self::Mode
+    /// [ci]: HashBaseTableColumn::CI
+    /// [mode]: HashBaseTableColumn::Mode
     /// [mode_prog_hash]: crate::table::hash_table::HashTableMode::ProgramHashing
     /// [mode_sponge]: crate::table::hash_table::HashTableMode::Sponge
     /// [mode_hash]: crate::table::hash_table::HashTableMode::Hash