snarkvm_synthesizer_program/logic/command/
get_or_use.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::{CallOperator, FinalizeStoreTrait, Opcode, Operand, RegistersTrait, StackTrait};
17use console::{
18    network::prelude::*,
19    program::{Register, Value},
20};
21
22/// A get command that uses the provided default in case of failure, e.g. `get.or_use accounts[r0] r1 into r2;`.
23/// Gets the value stored at `operand` in `mapping` and stores the result in `destination`.
24/// If the key is not present, `default` is stored in `destination`.
25#[derive(Clone, PartialEq, Eq, Hash)]
26pub struct GetOrUse<N: Network> {
27    /// The mapping.
28    mapping: CallOperator<N>,
29    /// The operands.
30    operands: [Operand<N>; 2],
31    /// The destination register.
32    destination: Register<N>,
33}
34
35impl<N: Network> GetOrUse<N> {
36    /// Returns the opcode.
37    #[inline]
38    pub const fn opcode() -> Opcode {
39        Opcode::Command("get.or_use")
40    }
41
42    /// Returns the operands in the operation.
43    #[inline]
44    pub fn operands(&self) -> &[Operand<N>] {
45        &self.operands
46    }
47
48    /// Returns the mapping.
49    #[inline]
50    pub const fn mapping(&self) -> &CallOperator<N> {
51        &self.mapping
52    }
53
54    /// Returns the operand containing the key.
55    #[inline]
56    pub const fn key(&self) -> &Operand<N> {
57        &self.operands[0]
58    }
59
60    /// Returns the default value.
61    #[inline]
62    pub const fn default(&self) -> &Operand<N> {
63        &self.operands[1]
64    }
65
66    /// Returns the destination register.
67    #[inline]
68    pub const fn destination(&self) -> &Register<N> {
69        &self.destination
70    }
71
72    /// Returns whether this command refers to an external struct.
73    #[inline]
74    pub fn contains_external_struct(&self) -> bool {
75        false
76    }
77}
78
79impl<N: Network> GetOrUse<N> {
80    /// Finalizes the command.
81    #[inline]
82    pub fn finalize(
83        &self,
84        stack: &impl StackTrait<N>,
85        store: &impl FinalizeStoreTrait<N>,
86        registers: &mut impl RegistersTrait<N>,
87    ) -> Result<()> {
88        // Determine the program ID and mapping name.
89        let (program_id, mapping_name) = match self.mapping {
90            CallOperator::Locator(locator) => (*locator.program_id(), *locator.resource()),
91            CallOperator::Resource(mapping_name) => (*stack.program_id(), mapping_name),
92        };
93
94        // Ensure the mapping exists.
95        if !store.contains_mapping_speculative(&program_id, &mapping_name)? {
96            bail!("Mapping '{program_id}/{mapping_name}' does not exist");
97        }
98
99        // Load the operand as a plaintext.
100        let key = registers.load_plaintext(stack, self.key())?;
101
102        // Retrieve the value from storage as a literal.
103        let value = match store.get_value_speculative(program_id, mapping_name, &key)? {
104            Some(Value::Plaintext(plaintext)) => Value::Plaintext(plaintext),
105            Some(Value::Record(..)) => bail!("Cannot 'get.or_use' a 'record'"),
106            Some(Value::Future(..)) => bail!("Cannot 'get.or_use' a 'future'"),
107            // If a key does not exist, then use the default value.
108            None => Value::Plaintext(registers.load_plaintext(stack, self.default())?),
109        };
110
111        // Assign the value to the destination register.
112        registers.store(stack, &self.destination, value)?;
113
114        // Return the finalize operation.
115        Ok(())
116    }
117}
118
119impl<N: Network> Parser for GetOrUse<N> {
120    /// Parses a string into an operation.
121    #[inline]
122    fn parse(string: &str) -> ParserResult<Self> {
123        // Parse the whitespace and comments from the string.
124        let (string, _) = Sanitizer::parse(string)?;
125        // Parse the opcode from the string.
126        let (string, _) = tag(*Self::opcode())(string)?;
127        // Parse the whitespace from the string.
128        let (string, _) = Sanitizer::parse_whitespaces(string)?;
129
130        // Parse the mapping name from the string.
131        let (string, mapping) = CallOperator::parse(string)?;
132        // Parse the "[" from the string.
133        let (string, _) = tag("[")(string)?;
134        // Parse the whitespace from the string.
135        let (string, _) = Sanitizer::parse_whitespaces(string)?;
136        // Parse the key operand from the string.
137        let (string, key) = Operand::parse(string)?;
138        // Parse the whitespace from the string.
139        let (string, _) = Sanitizer::parse_whitespaces(string)?;
140        // Parse the "]" from the string.
141        let (string, _) = tag("]")(string)?;
142        // Parse the whitespace from the string.
143        let (string, _) = Sanitizer::parse_whitespaces(string)?;
144        // Parse the default value from the string.
145        let (string, default) = Operand::parse(string)?;
146
147        // Parse the whitespace from the string.
148        let (string, _) = Sanitizer::parse_whitespaces(string)?;
149        // Parse the "into" keyword from the string.
150        let (string, _) = tag("into")(string)?;
151        // Parse the whitespace from the string.
152        let (string, _) = Sanitizer::parse_whitespaces(string)?;
153        // Parse the destination register from the string.
154        let (string, destination) = Register::parse(string)?;
155
156        // Parse the whitespace from the string.
157        let (string, _) = Sanitizer::parse_whitespaces(string)?;
158        // Parse the ";" from the string.
159        let (string, _) = tag(";")(string)?;
160
161        Ok((string, Self { mapping, operands: [key, default], destination }))
162    }
163}
164
165impl<N: Network> FromStr for GetOrUse<N> {
166    type Err = Error;
167
168    /// Parses a string into the command.
169    #[inline]
170    fn from_str(string: &str) -> Result<Self> {
171        match Self::parse(string) {
172            Ok((remainder, object)) => {
173                // Ensure the remainder is empty.
174                ensure!(remainder.is_empty(), "Failed to parse string. Found invalid character in: \"{remainder}\"");
175                // Return the object.
176                Ok(object)
177            }
178            Err(error) => bail!("Failed to parse string. {error}"),
179        }
180    }
181}
182
183impl<N: Network> Debug for GetOrUse<N> {
184    /// Prints the command as a string.
185    fn fmt(&self, f: &mut Formatter) -> fmt::Result {
186        Display::fmt(self, f)
187    }
188}
189
190impl<N: Network> Display for GetOrUse<N> {
191    /// Prints the command to a string.
192    fn fmt(&self, f: &mut Formatter) -> fmt::Result {
193        // Print the command.
194        write!(f, "{} ", Self::opcode())?;
195        // Print the mapping and key operand.
196        write!(f, "{}[{}] {} into ", self.mapping, self.key(), self.default())?;
197        // Print the destination register.
198        write!(f, "{};", self.destination)
199    }
200}
201
202impl<N: Network> FromBytes for GetOrUse<N> {
203    /// Reads the command from a buffer.
204    fn read_le<R: Read>(mut reader: R) -> IoResult<Self> {
205        // Read the mapping name.
206        let mapping = CallOperator::read_le(&mut reader)?;
207        // Read the key operand.
208        let key = Operand::read_le(&mut reader)?;
209        // Read the default value.
210        let default = Operand::read_le(&mut reader)?;
211        // Read the destination register.
212        let destination = Register::read_le(&mut reader)?;
213        // Return the command.
214        Ok(Self { mapping, operands: [key, default], destination })
215    }
216}
217
218impl<N: Network> ToBytes for GetOrUse<N> {
219    /// Writes the operation to a buffer.
220    fn write_le<W: Write>(&self, mut writer: W) -> IoResult<()> {
221        // Write the mapping name.
222        self.mapping.write_le(&mut writer)?;
223        // Write the key operand.
224        self.key().write_le(&mut writer)?;
225        // Write the default value.
226        self.default().write_le(&mut writer)?;
227        // Write the destination register.
228        self.destination.write_le(&mut writer)
229    }
230}
231
232#[cfg(test)]
233mod tests {
234    use super::*;
235    use console::{network::MainnetV0, program::Register};
236
237    type CurrentNetwork = MainnetV0;
238
239    #[test]
240    fn test_parse() {
241        let (string, get_or_use) = GetOrUse::<CurrentNetwork>::parse("get.or_use account[r0] r1 into r2;").unwrap();
242        assert!(string.is_empty(), "Parser did not consume all of the string: '{string}'");
243        assert_eq!(get_or_use.mapping, CallOperator::from_str("account").unwrap());
244        assert_eq!(get_or_use.operands().len(), 2, "The number of operands is incorrect");
245        assert_eq!(get_or_use.key(), &Operand::Register(Register::Locator(0)), "The first operand is incorrect");
246        assert_eq!(get_or_use.default(), &Operand::Register(Register::Locator(1)), "The second operand is incorrect");
247        assert_eq!(get_or_use.destination, Register::Locator(2), "The second operand is incorrect");
248
249        let (string, get_or_use) =
250            GetOrUse::<CurrentNetwork>::parse("get.or_use token.aleo/balances[r0] r1 into r2;").unwrap();
251        assert!(string.is_empty(), "Parser did not consume all of the string: '{string}'");
252        assert_eq!(get_or_use.mapping, CallOperator::from_str("token.aleo/balances").unwrap());
253        assert_eq!(get_or_use.operands().len(), 2, "The number of operands is incorrect");
254        assert_eq!(get_or_use.key(), &Operand::Register(Register::Locator(0)), "The first operand is incorrect");
255        assert_eq!(get_or_use.default(), &Operand::Register(Register::Locator(1)), "The second operand is incorrect");
256        assert_eq!(get_or_use.destination, Register::Locator(2), "The second operand is incorrect");
257    }
258
259    #[test]
260    fn test_from_bytes() {
261        let (string, get_or_use) = GetOrUse::<CurrentNetwork>::parse("get.or_use account[r0] r1 into r2;").unwrap();
262        assert!(string.is_empty());
263        let bytes_le = get_or_use.to_bytes_le().unwrap();
264        let result = GetOrUse::<CurrentNetwork>::from_bytes_le(&bytes_le[..]);
265        assert!(result.is_ok());
266    }
267}
snarkvm_synthesizer_program/logic/command/get_or_use.rs

snarkvm_synthesizer_program/logic/command/
get_or_use.rs
