snarkvm_synthesizer_program/constructor/
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
16mod bytes;
17mod parse;
18
19use crate::Command;
20
21use console::{
22    network::prelude::*,
23    program::{Identifier, Register},
24};
25
26use std::collections::HashMap;
27
28#[derive(Clone, PartialEq, Eq)]
29pub struct ConstructorCore<N: Network> {
30    /// The commands, in order of execution.
31    commands: Vec<Command<N>>,
32    /// The number of write commands.
33    num_writes: u16,
34    /// A mapping from `Position`s to their index in `commands`.
35    positions: HashMap<Identifier<N>, usize>,
36}
37
38impl<N: Network> ConstructorCore<N> {
39    /// Returns the constructor commands.
40    pub fn commands(&self) -> &[Command<N>] {
41        &self.commands
42    }
43
44    /// Returns the number of write commands.
45    pub const fn num_writes(&self) -> u16 {
46        self.num_writes
47    }
48
49    /// Returns the mapping of `Position`s to their index in `commands`.
50    pub const fn positions(&self) -> &HashMap<Identifier<N>, usize> {
51        &self.positions
52    }
53
54    /// Returns whether this constructor refers to an external struct.
55    pub fn contains_external_struct(&self) -> bool {
56        self.commands.iter().any(|command| command.contains_external_struct())
57    }
58
59    /// Returns `true` if the constructor commands contain a string type.
60    pub fn contains_string_type(&self) -> bool {
61        self.commands.iter().any(|command| command.contains_string_type())
62    }
63
64    /// Returns `true` if the constructor contains an array type with a size that exceeds the given maximum.
65    pub fn exceeds_max_array_size(&self, max_array_size: u32) -> bool {
66        self.commands.iter().any(|command| command.exceeds_max_array_size(max_array_size))
67    }
68}
69
70impl<N: Network> ConstructorCore<N> {
71    /// Adds the given command to constructor.
72    ///
73    /// # Errors
74    /// This method will halt if the maximum number of commands has been reached.
75    #[inline]
76    pub fn add_command(&mut self, command: Command<N>) -> Result<()> {
77        // Ensure the maximum number of commands has not been exceeded.
78        ensure!(self.commands.len() < N::MAX_COMMANDS, "Cannot add more than {} commands", N::MAX_COMMANDS);
79        // Ensure the number of write commands has not been exceeded.
80        if command.is_write() {
81            ensure!(
82                self.num_writes < N::MAX_WRITES,
83                "Cannot add more than {} 'set' & 'remove' commands",
84                N::MAX_WRITES
85            );
86        }
87
88        // Ensure the command is not an async instruction.
89        ensure!(!command.is_async(), "Forbidden operation: Constructor cannot invoke an 'async' instruction");
90        // Ensure the command is not a call instruction.
91        ensure!(!command.is_call(), "Forbidden operation: Constructor cannot invoke a 'call'");
92        // Ensure the command is not a cast to record instruction.
93        ensure!(!command.is_cast_to_record(), "Forbidden operation: Constructor cannot cast to a record");
94        // Ensure the command is not an await command.
95        ensure!(!command.is_await(), "Forbidden operation: Constructor cannot 'await'");
96
97        // Check the destination registers.
98        for register in command.destinations() {
99            // Ensure the destination register is a locator.
100            ensure!(matches!(register, Register::Locator(..)), "Destination register must be a locator");
101        }
102
103        // Check if the command is a branch command.
104        if let Some(position) = command.branch_to() {
105            // Ensure the branch target does not reference an earlier position.
106            ensure!(!self.positions.contains_key(position), "Cannot branch to an earlier position '{position}'");
107        }
108
109        // Check if the command is a position command.
110        if let Some(position) = command.position() {
111            // Ensure the position is not yet defined.
112            ensure!(!self.positions.contains_key(position), "Cannot redefine position '{position}'");
113            // Ensure that there are less than `u8::MAX` positions.
114            ensure!(self.positions.len() < N::MAX_POSITIONS, "Cannot add more than {} positions", N::MAX_POSITIONS);
115            // Insert the position.
116            self.positions.insert(*position, self.commands.len());
117        }
118
119        // Check if the command is a write command.
120        if command.is_write() {
121            // Increment the number of write commands.
122            self.num_writes += 1;
123        }
124
125        // Insert the command.
126        self.commands.push(command);
127        Ok(())
128    }
129}
130
131impl<N: Network> TypeName for ConstructorCore<N> {
132    /// Returns the type name as a string.
133    #[inline]
134    fn type_name() -> &'static str {
135        "constructor"
136    }
137}
138
139#[cfg(test)]
140mod tests {
141    use super::*;
142
143    use crate::{Command, Constructor};
144
145    type CurrentNetwork = console::network::MainnetV0;
146
147    #[test]
148    fn test_add_command() {
149        // Initialize a new constructor instance.
150        let mut constructor = Constructor::<CurrentNetwork> {
151            commands: Default::default(),
152            num_writes: 0,
153            positions: Default::default(),
154        };
155
156        // Ensure that a command can be added.
157        let command = Command::<CurrentNetwork>::from_str("add r0 r1 into r2;").unwrap();
158        assert!(constructor.add_command(command).is_ok());
159
160        // Ensure that adding more than the maximum number of commands will fail.
161        for i in 3..CurrentNetwork::MAX_COMMANDS * 2 {
162            let command = Command::<CurrentNetwork>::from_str(&format!("add r0 r1 into r{i};")).unwrap();
163
164            match constructor.commands.len() < CurrentNetwork::MAX_COMMANDS {
165                true => assert!(constructor.add_command(command).is_ok()),
166                false => assert!(constructor.add_command(command).is_err()),
167            }
168        }
169
170        // Ensure that adding more than the maximum number of writes will fail.
171
172        // Initialize a new constructor instance.
173        let mut constructor = Constructor::<CurrentNetwork> {
174            commands: Default::default(),
175            num_writes: 0,
176            positions: Default::default(),
177        };
178
179        for _ in 0..CurrentNetwork::MAX_WRITES * 2 {
180            let command = Command::<CurrentNetwork>::from_str("remove object[r0];").unwrap();
181
182            match constructor.commands.len() < CurrentNetwork::MAX_WRITES as usize {
183                true => assert!(constructor.add_command(command).is_ok()),
184                false => assert!(constructor.add_command(command).is_err()),
185            }
186        }
187    }
188
189    #[test]
190    fn test_add_command_duplicate_positions() {
191        // Initialize a new constructor instance.
192        let mut constructor =
193            Constructor { commands: Default::default(), num_writes: 0, positions: Default::default() };
194
195        // Ensure that a command can be added.
196        let command = Command::<CurrentNetwork>::from_str("position start;").unwrap();
197        assert!(constructor.add_command(command.clone()).is_ok());
198
199        // Ensure that adding a duplicate position will fail.
200        assert!(constructor.add_command(command).is_err());
201
202        // Helper method to convert a number to a unique string.
203        #[allow(clippy::cast_possible_truncation)]
204        fn to_unique_string(mut n: usize) -> String {
205            let mut s = String::new();
206            while n > 0 {
207                s.push((b'A' + (n % 26) as u8) as char);
208                n /= 26;
209            }
210            s.chars().rev().collect::<String>()
211        }
212
213        // Ensure that adding more than the maximum number of positions will fail.
214        for i in 1..u8::MAX as usize * 2 {
215            let position = to_unique_string(i);
216            println!("position: {position}");
217            let command = Command::<CurrentNetwork>::from_str(&format!("position {position};")).unwrap();
218
219            match constructor.commands.len() < u8::MAX as usize {
220                true => assert!(constructor.add_command(command).is_ok()),
221                false => assert!(constructor.add_command(command).is_err()),
222            }
223        }
224    }
225}
snarkvm_synthesizer_program/constructor/mod.rs

snarkvm_synthesizer_program/constructor/
mod.rs
