snarkvm_synthesizer_program/finalize/
mod.rs

1// Copyright (c) 2019-2025 Provable Inc.
2// This file is part of the snarkVM library.
3
4// Licensed under the Apache License, Version 2.0 (the "License");
5// you may not use this file except in compliance with the License.
6// You may obtain a copy of the License at:
7
8// http://www.apache.org/licenses/LICENSE-2.0
9
10// Unless required by applicable law or agreed to in writing, software
11// distributed under the License is distributed on an "AS IS" BASIS,
12// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
13// See the License for the specific language governing permissions and
14// limitations under the License.
15
16use crate::Command;
17
18mod input;
19use input::*;
20
21mod bytes;
22mod parse;
23
24use console::{
25    network::prelude::*,
26    program::{FinalizeType, Identifier, Register},
27};
28
29use indexmap::IndexSet;
30use std::collections::HashMap;
31
32#[derive(Clone, PartialEq, Eq)]
33pub struct FinalizeCore<N: Network> {
34    /// The name of the associated function.
35    name: Identifier<N>,
36    /// The input statements, added in order of the input registers.
37    /// Input assignments are ensured to match the ordering of the input statements.
38    inputs: IndexSet<Input<N>>,
39    /// The commands, in order of execution.
40    commands: Vec<Command<N>>,
41    /// The number of write commands.
42    num_writes: u16,
43    /// A mapping from `Position`s to their index in `commands`.
44    positions: HashMap<Identifier<N>, usize>,
45}
46
47impl<N: Network> FinalizeCore<N> {
48    /// Initializes a new finalize with the given name.
49    pub fn new(name: Identifier<N>) -> Self {
50        Self { name, inputs: IndexSet::new(), commands: Vec::new(), num_writes: 0, positions: HashMap::new() }
51    }
52
53    /// Returns the name of the associated function.
54    pub const fn name(&self) -> &Identifier<N> {
55        &self.name
56    }
57
58    /// Returns the finalize inputs.
59    pub const fn inputs(&self) -> &IndexSet<Input<N>> {
60        &self.inputs
61    }
62
63    /// Returns the finalize input types.
64    pub fn input_types(&self) -> Vec<FinalizeType<N>> {
65        self.inputs.iter().map(|input| input.finalize_type()).cloned().collect()
66    }
67
68    /// Returns the finalize commands.
69    pub fn commands(&self) -> &[Command<N>] {
70        &self.commands
71    }
72
73    /// Returns the number of write commands.
74    pub const fn num_writes(&self) -> u16 {
75        self.num_writes
76    }
77
78    /// Returns the mapping of `Position`s to their index in `commands`.
79    pub const fn positions(&self) -> &HashMap<Identifier<N>, usize> {
80        &self.positions
81    }
82}
83
84impl<N: Network> FinalizeCore<N> {
85    /// Adds the input statement to finalize.
86    ///
87    /// # Errors
88    /// This method will halt if a command was previously added.
89    /// This method will halt if the maximum number of inputs has been reached.
90    /// This method will halt if the input statement was previously added.
91    #[inline]
92    fn add_input(&mut self, input: Input<N>) -> Result<()> {
93        // Ensure there are no commands in memory.
94        ensure!(self.commands.is_empty(), "Cannot add inputs after commands have been added");
95
96        // Ensure the maximum number of inputs has not been exceeded.
97        ensure!(self.inputs.len() < N::MAX_INPUTS, "Cannot add more than {} inputs", N::MAX_INPUTS);
98        // Ensure the input statement was not previously added.
99        ensure!(!self.inputs.contains(&input), "Cannot add duplicate input statement");
100
101        // Ensure the input register is a locator.
102        ensure!(matches!(input.register(), Register::Locator(..)), "Input register must be a locator");
103
104        // Insert the input statement.
105        self.inputs.insert(input);
106        Ok(())
107    }
108
109    /// Adds the given command to finalize.
110    ///
111    /// # Errors
112    /// This method will halt if the maximum number of commands has been reached.
113    #[inline]
114    pub fn add_command(&mut self, command: Command<N>) -> Result<()> {
115        // Ensure the maximum number of commands has not been exceeded.
116        ensure!(self.commands.len() < N::MAX_COMMANDS, "Cannot add more than {} commands", N::MAX_COMMANDS);
117        // Ensure the number of write commands has not been exceeded.
118        if command.is_write() {
119            ensure!(
120                self.num_writes < N::MAX_WRITES,
121                "Cannot add more than {} 'set' & 'remove' commands",
122                N::MAX_WRITES
123            );
124        }
125
126        // Ensure the command is not an async instruction.
127        ensure!(!command.is_async(), "Forbidden operation: Finalize cannot invoke an 'async' instruction");
128        // Ensure the command is not a call instruction.
129        ensure!(!command.is_call(), "Forbidden operation: Finalize cannot invoke a 'call'");
130        // Ensure the command is not a cast to record instruction.
131        ensure!(!command.is_cast_to_record(), "Forbidden operation: Finalize cannot cast to a record");
132
133        // Check the destination registers.
134        for register in command.destinations() {
135            // Ensure the destination register is a locator.
136            ensure!(matches!(register, Register::Locator(..)), "Destination register must be a locator");
137        }
138
139        // Check if the command is a branch command.
140        if let Some(position) = command.branch_to() {
141            // Ensure the branch target does not reference an earlier position.
142            ensure!(!self.positions.contains_key(position), "Cannot branch to an earlier position '{position}'");
143        }
144
145        // Check if the command is a position command.
146        if let Some(position) = command.position() {
147            // Ensure the position is not yet defined.
148            ensure!(!self.positions.contains_key(position), "Cannot redefine position '{position}'");
149            // Ensure that there are less than `u8::MAX` positions.
150            ensure!(self.positions.len() < N::MAX_POSITIONS, "Cannot add more than {} positions", N::MAX_POSITIONS);
151            // Insert the position.
152            self.positions.insert(*position, self.commands.len());
153        }
154
155        // Check if the command is a write command.
156        if command.is_write() {
157            // Increment the number of write commands.
158            self.num_writes += 1;
159        }
160
161        // Insert the command.
162        self.commands.push(command);
163        Ok(())
164    }
165}
166
167impl<N: Network> TypeName for FinalizeCore<N> {
168    /// Returns the type name as a string.
169    #[inline]
170    fn type_name() -> &'static str {
171        "finalize"
172    }
173}
174
175#[cfg(test)]
176mod tests {
177    use super::*;
178
179    use crate::{Command, Finalize};
180
181    type CurrentNetwork = console::network::MainnetV0;
182
183    #[test]
184    fn test_add_input() {
185        // Initialize a new finalize instance.
186        let name = Identifier::from_str("finalize_core_test").unwrap();
187        let mut finalize = Finalize::<CurrentNetwork>::new(name);
188
189        // Ensure that an input can be added.
190        let input = Input::<CurrentNetwork>::from_str("input r0 as field.public;").unwrap();
191        assert!(finalize.add_input(input.clone()).is_ok());
192
193        // Ensure that adding a duplicate input will fail.
194        assert!(finalize.add_input(input).is_err());
195
196        // Ensure that adding more than the maximum number of inputs will fail.
197        for i in 1..CurrentNetwork::MAX_INPUTS * 2 {
198            let input = Input::<CurrentNetwork>::from_str(&format!("input r{i} as field.public;")).unwrap();
199
200            match finalize.inputs.len() < CurrentNetwork::MAX_INPUTS {
201                true => assert!(finalize.add_input(input).is_ok()),
202                false => assert!(finalize.add_input(input).is_err()),
203            }
204        }
205    }
206
207    #[test]
208    fn test_add_command() {
209        // Initialize a new finalize instance.
210        let name = Identifier::from_str("finalize_core_test").unwrap();
211        let mut finalize = Finalize::<CurrentNetwork>::new(name);
212
213        // Ensure that a command can be added.
214        let command = Command::<CurrentNetwork>::from_str("add r0 r1 into r2;").unwrap();
215        assert!(finalize.add_command(command).is_ok());
216
217        // Ensure that adding more than the maximum number of commands will fail.
218        for i in 3..CurrentNetwork::MAX_COMMANDS * 2 {
219            let command = Command::<CurrentNetwork>::from_str(&format!("add r0 r1 into r{i};")).unwrap();
220
221            match finalize.commands.len() < CurrentNetwork::MAX_COMMANDS {
222                true => assert!(finalize.add_command(command).is_ok()),
223                false => assert!(finalize.add_command(command).is_err()),
224            }
225        }
226
227        // Ensure that adding more than the maximum number of writes will fail.
228
229        // Initialize a new finalize instance.
230        let name = Identifier::from_str("finalize_core_test").unwrap();
231        let mut finalize = Finalize::<CurrentNetwork>::new(name);
232
233        for _ in 0..CurrentNetwork::MAX_WRITES * 2 {
234            let command = Command::<CurrentNetwork>::from_str("remove object[r0];").unwrap();
235
236            match finalize.commands.len() < CurrentNetwork::MAX_WRITES as usize {
237                true => assert!(finalize.add_command(command).is_ok()),
238                false => assert!(finalize.add_command(command).is_err()),
239            }
240        }
241    }
242
243    #[test]
244    fn test_add_command_duplicate_positions() {
245        // Initialize a new finalize instance.
246        let name = Identifier::from_str("finalize_core_test").unwrap();
247        let mut finalize = Finalize::<CurrentNetwork>::new(name);
248
249        // Ensure that a command can be added.
250        let command = Command::<CurrentNetwork>::from_str("position start;").unwrap();
251        assert!(finalize.add_command(command.clone()).is_ok());
252
253        // Ensure that adding a duplicate position will fail.
254        assert!(finalize.add_command(command).is_err());
255
256        // Helper method to convert a number to a unique string.
257        #[allow(clippy::cast_possible_truncation)]
258        fn to_unique_string(mut n: usize) -> String {
259            let mut s = String::new();
260            while n > 0 {
261                s.push((b'A' + (n % 26) as u8) as char);
262                n /= 26;
263            }
264            s.chars().rev().collect::<String>()
265        }
266
267        // Ensure that adding more than the maximum number of positions will fail.
268        for i in 1..u8::MAX as usize * 2 {
269            let position = to_unique_string(i);
270            // println!("position: {position}");
271            let command = Command::<CurrentNetwork>::from_str(&format!("position {position};")).unwrap();
272
273            match finalize.commands.len() < u8::MAX as usize {
274                true => assert!(finalize.add_command(command).is_ok()),
275                false => assert!(finalize.add_command(command).is_err()),
276            }
277        }
278    }
279}
snarkvm_synthesizer_program/finalize/mod.rs

snarkvm_synthesizer_program/finalize/
mod.rs
