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

snarkvm_synthesizer_program/logic/command/
get_or_use.rs
