snarkvm_synthesizer_program/logic/instruction/operation/
serialize.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::{Opcode, Operand, RegistersCircuit, RegistersTrait, StackTrait};
17use console::{
18    network::prelude::*,
19    program::{ArrayType, Identifier, LiteralType, Locator, Plaintext, PlaintextType, Register, RegisterType, Value},
20};
21
22/// Serializes the bits of the input.
23pub type SerializeBits<N> = SerializeInstruction<N, { SerializeVariant::ToBits as u8 }>;
24/// Serializes the raw bits of the input.
25pub type SerializeBitsRaw<N> = SerializeInstruction<N, { SerializeVariant::ToBitsRaw as u8 }>;
26
27/// The serialize variant.
28#[derive(Debug, Clone, Eq, PartialEq)]
29pub enum SerializeVariant {
30    ToBits,
31    ToBitsRaw,
32}
33
34impl SerializeVariant {
35    // Returns the opcode associated with the variant.
36    pub const fn opcode(variant: u8) -> &'static str {
37        match variant {
38            0 => "serialize.bits",
39            1 => "serialize.bits.raw",
40            _ => panic!("Invalid 'serialize' instruction opcode"),
41        }
42    }
43}
44
45/// Checks that the number of operands is correct.
46fn check_number_of_operands(variant: u8, num_operands: usize) -> Result<()> {
47    if num_operands != 1 {
48        bail!("Instruction '{}' expects 1 operand, found {num_operands} operands", SerializeVariant::opcode(variant))
49    }
50    Ok(())
51}
52
53/// Checks that the operand type is valid.
54fn check_operand_type_is_valid(variant: u8, operand_type: &PlaintextType<impl Network>) -> Result<()> {
55    // A helper function to check a literal type.
56    fn check_literal_type(literal_type: &LiteralType) -> Result<()> {
57        match literal_type {
58            LiteralType::Address
59            | LiteralType::Boolean
60            | LiteralType::Field
61            | LiteralType::Group
62            | LiteralType::I8
63            | LiteralType::I16
64            | LiteralType::I32
65            | LiteralType::I64
66            | LiteralType::I128
67            | LiteralType::U8
68            | LiteralType::U16
69            | LiteralType::U32
70            | LiteralType::U64
71            | LiteralType::U128
72            | LiteralType::Scalar => Ok(()),
73            _ => bail!("Invalid literal type '{literal_type}' for 'serialize' instruction"),
74        }
75    }
76
77    match operand_type {
78        PlaintextType::Literal(literal_type) => check_literal_type(literal_type),
79        PlaintextType::Array(array_type) => match array_type.base_element_type() {
80            PlaintextType::Literal(literal_type) => check_literal_type(literal_type),
81            _ => bail!("Invalid element type '{array_type}' for 'serialize' instruction"),
82        },
83        _ => bail!("Instruction '{}' cannot take type '{operand_type}' as input", SerializeVariant::opcode(variant)),
84    }
85}
86
87/// Check that the destination type is valid.
88fn check_destination_type_is_valid(variant: u8, destination_type: &ArrayType<impl Network>) -> Result<()> {
89    match (variant, destination_type) {
90        (0 | 1, array_type) if array_type.is_bit_array() => Ok(()),
91        _ => {
92            bail!("Instruction '{}' cannot output type '{destination_type}'", SerializeVariant::opcode(variant))
93        }
94    }
95}
96
97/// Serialize the operand into the declared type.
98#[derive(Clone, PartialEq, Eq, Hash)]
99pub struct SerializeInstruction<N: Network, const VARIANT: u8> {
100    /// The operand as `input`.
101    operands: Vec<Operand<N>>,
102    /// The operand type.
103    operand_type: PlaintextType<N>,
104    /// The destination register.
105    destination: Register<N>,
106    /// The destination register type.
107    destination_type: ArrayType<N>,
108}
109
110impl<N: Network, const VARIANT: u8> SerializeInstruction<N, VARIANT> {
111    /// Initializes a new `serialize` instruction.
112    pub fn new(
113        operands: Vec<Operand<N>>,
114        operand_type: PlaintextType<N>,
115        destination: Register<N>,
116        destination_type: ArrayType<N>,
117    ) -> Result<Self> {
118        // Sanity check the number of operands.
119        check_number_of_operands(VARIANT, operands.len())?;
120        // Ensure that the operand type is valid.
121        check_operand_type_is_valid(VARIANT, &operand_type)?;
122        // Sanity check the destination type.
123        check_destination_type_is_valid(VARIANT, &destination_type)?;
124        // Return the instruction.
125        Ok(Self { operands, operand_type, destination, destination_type })
126    }
127
128    /// Returns the opcode.
129    pub const fn opcode() -> Opcode {
130        Opcode::Serialize(SerializeVariant::opcode(VARIANT))
131    }
132
133    /// Returns the operands in the operation.
134    pub fn operands(&self) -> &[Operand<N>] {
135        // Sanity check that the operands is the correct length.
136        if cfg!(debug_assertions) {
137            check_number_of_operands(VARIANT, self.operands.len()).unwrap();
138            check_operand_type_is_valid(VARIANT, &self.operand_type).unwrap();
139            check_destination_type_is_valid(VARIANT, &self.destination_type).unwrap();
140        }
141        // Return the operand.
142        &self.operands
143    }
144
145    /// Returns the operand type.
146    pub const fn operand_type(&self) -> &PlaintextType<N> {
147        &self.operand_type
148    }
149
150    /// Returns the destination register.
151    #[inline]
152    pub fn destinations(&self) -> Vec<Register<N>> {
153        vec![self.destination.clone()]
154    }
155
156    /// Returns the destination register type.
157    #[inline]
158    pub const fn destination_type(&self) -> &ArrayType<N> {
159        &self.destination_type
160    }
161
162    /// Returns whether this instruction refers to an external struct.
163    #[inline]
164    pub fn contains_external_struct(&self) -> bool {
165        self.operand_type.contains_external_struct()
166    }
167}
168
169/// Evaluate a `serialize` operation.
170///
171/// This allows running `serialize` without the machinery of stacks and registers.
172/// This is necessary for the Leo interpreter.
173pub fn evaluate_serialize<N: Network>(
174    variant: SerializeVariant,
175    input: &Value<N>,
176    destination_type: &ArrayType<N>,
177) -> Result<Value<N>> {
178    evaluate_serialize_internal(variant as u8, input, destination_type)
179}
180
181fn evaluate_serialize_internal<N: Network>(
182    variant: u8,
183    input: &Value<N>,
184    destination_type: &ArrayType<N>,
185) -> Result<Value<N>> {
186    match (variant, destination_type) {
187        (0, array_type) if array_type.is_bit_array() => {
188            // Get the desired length of the array.
189            let length = **array_type.length();
190            // Serialize the input to bits.
191            let bits = input.to_bits_le();
192            // Return the bits as a plaintext array.
193            Ok(Value::Plaintext(Plaintext::from_bit_array(bits, length)?))
194        }
195        (1, array_type) if array_type.is_bit_array() => {
196            // Get the desired length of the array.
197            let length = **array_type.length();
198            // Serialize the input to raw bits.
199            let bits = input.to_bits_raw_le();
200            // Return the bits as a plaintext array.
201            Ok(Value::Plaintext(Plaintext::from_bit_array(bits, length)?))
202        }
203        _ => bail!(
204            "Invalid destination type '{}' for instruction '{}'",
205            destination_type,
206            SerializeVariant::opcode(variant)
207        ),
208    }
209}
210
211impl<N: Network, const VARIANT: u8> SerializeInstruction<N, VARIANT> {
212    /// Evaluates the instruction.
213    pub fn evaluate(&self, stack: &impl StackTrait<N>, registers: &mut impl RegistersTrait<N>) -> Result<()> {
214        // Ensure the number of operands is correct.
215        check_number_of_operands(VARIANT, self.operands.len())?;
216        // Ensure that the operand type is valid.
217        check_operand_type_is_valid(VARIANT, &self.operand_type)?;
218        // Ensure the destination type is valid.
219        check_destination_type_is_valid(VARIANT, &self.destination_type)?;
220
221        // Load the operand.
222        let input = registers.load(stack, &self.operands[0])?;
223
224        let output = evaluate_serialize_internal(VARIANT, &input, &self.destination_type)?;
225
226        // Store the output.
227        registers.store(stack, &self.destination, output)
228    }
229
230    /// Executes the instruction.
231    pub fn execute<A: circuit::Aleo<Network = N>>(
232        &self,
233        stack: &impl StackTrait<N>,
234        registers: &mut impl RegistersCircuit<N, A>,
235    ) -> Result<()> {
236        use crate::circuit::traits::{ToBits, ToBitsRaw};
237
238        // Ensure the number of operands is correct.
239        check_number_of_operands(VARIANT, self.operands.len())?;
240        // Ensure that the operand type is valid.
241        check_operand_type_is_valid(VARIANT, &self.operand_type)?;
242        // Ensure the destination type is valid.
243        check_destination_type_is_valid(VARIANT, &self.destination_type)?;
244
245        // Load the operand.
246        let input = registers.load_circuit(stack, &self.operands[0])?;
247
248        let output = match (VARIANT, &self.destination_type) {
249            (0, array_type) if array_type.is_bit_array() => {
250                // Get the desired length of the array.
251                let length = **array_type.length();
252                // Serialize the input to bits.
253                let bits = input.to_bits_le();
254                // Return the bits as a plaintext array.
255                circuit::Value::Plaintext(circuit::Plaintext::from_bit_array(bits, length)?)
256            }
257            (1, array_type) if array_type.is_bit_array() => {
258                // Get the desired length of the array.
259                let length = **array_type.length();
260                // Serialize the input to raw bits.
261                let bits = input.to_bits_raw_le();
262                // Return the bits as a plaintext array.
263                circuit::Value::Plaintext(circuit::Plaintext::from_bit_array(bits, length)?)
264            }
265            _ => bail!("Invalid destination type '{}' for instruction '{}'", &self.destination_type, Self::opcode(),),
266        };
267
268        // Store the output.
269        registers.store_circuit(stack, &self.destination, output)
270    }
271
272    /// Finalizes the instruction.
273    #[inline]
274    pub fn finalize(&self, stack: &impl StackTrait<N>, registers: &mut impl RegistersTrait<N>) -> Result<()> {
275        self.evaluate(stack, registers)
276    }
277
278    /// Returns the output type from the given program and input types.
279    pub fn output_types(
280        &self,
281        stack: &impl StackTrait<N>,
282        input_types: &[RegisterType<N>],
283    ) -> Result<Vec<RegisterType<N>>> {
284        // Ensure the number of operands is correct.
285        check_number_of_operands(VARIANT, self.operands.len())?;
286        // Ensure the operand type is valid.
287        check_operand_type_is_valid(VARIANT, &self.operand_type)?;
288        // Ensure the destination type is valid.
289        check_destination_type_is_valid(VARIANT, &self.destination_type)?;
290
291        // Check that the input type matches the operand type.
292        ensure!(input_types.len() == 1, "Expected exactly one input type");
293        match &input_types[0] {
294            RegisterType::Plaintext(plaintext_type) => {
295                ensure!(
296                    plaintext_type == &self.operand_type,
297                    "Input type {} does not match operand type {}",
298                    input_types[0],
299                    self.operand_type
300                )
301            }
302            type_ => bail!("Input type {type_} does not match operand type {}", self.operand_type),
303        }
304
305        // A helper to get a struct declaration.
306        let get_struct = |identifier: &Identifier<N>| stack.program().get_struct(identifier).cloned();
307
308        // A helper to get an external struct declaration.
309        let get_external_struct = |locator: &Locator<N>| {
310            stack.get_external_stack(locator.program_id())?.program().get_struct(locator.resource()).cloned()
311        };
312
313        // Get the size in bits of the operand.
314        let size_in_bits = match VARIANT {
315            0 => self.operand_type.size_in_bits(&get_struct, &get_external_struct)?,
316            1 => self.operand_type.size_in_bits_raw(&get_struct, &get_external_struct)?,
317            variant => bail!("Invalid `serialize` variant '{variant}'"),
318        };
319
320        // Check that the number of bits of the operand matches the destination.
321        ensure!(
322            size_in_bits == **self.destination_type.length() as usize,
323            "The number of bits of the operand '{size_in_bits}' does not match the destination '{}'",
324            **self.destination_type.length()
325        );
326
327        Ok(vec![RegisterType::Plaintext(PlaintextType::Array(self.destination_type.clone()))])
328    }
329}
330
331impl<N: Network, const VARIANT: u8> Parser for SerializeInstruction<N, VARIANT> {
332    /// Parses a string into an operation.
333    fn parse(string: &str) -> ParserResult<Self> {
334        /// Parse the operands from the string.
335        fn parse_operands<N: Network>(string: &str, num_operands: usize) -> ParserResult<Vec<Operand<N>>> {
336            let mut operands = Vec::with_capacity(num_operands);
337            let mut string = string;
338
339            for _ in 0..num_operands {
340                // Parse the whitespace from the string.
341                let (next_string, _) = Sanitizer::parse_whitespaces(string)?;
342                // Parse the operand from the string.
343                let (next_string, operand) = Operand::parse(next_string)?;
344                // Update the string.
345                string = next_string;
346                // Push the operand.
347                operands.push(operand);
348            }
349
350            Ok((string, operands))
351        }
352
353        // Parse the opcode from the string.
354        let (string, _) = tag(*Self::opcode())(string)?;
355        // Parse the operands from the string.
356        let (string, operands) = parse_operands(string, 1)?;
357
358        // Parse the whitespace from the string.
359        let (string, _) = Sanitizer::parse_whitespaces(string)?;
360        // Parse the "(" from the string.
361        let (string, _) = tag("(")(string)?;
362        // Parse the whitespace from the string.
363        let (string, _) = Sanitizer::parse_whitespaces(string)?;
364        // Parse the operand type from the string.
365        let (string, operand_type) = PlaintextType::parse(string)?;
366        // Parse the ")" from the string.
367        let (string, _) = tag(")")(string)?;
368
369        // Parse the whitespace from the string.
370        let (string, _) = Sanitizer::parse_whitespaces(string)?;
371        // Parse the "into" from the string.
372        let (string, _) = tag("into")(string)?;
373        // Parse the whitespace from the string.
374        let (string, _) = Sanitizer::parse_whitespaces(string)?;
375        // Parse the destination register from the string.
376        let (string, destination) = Register::parse(string)?;
377
378        // Parse the whitespace from the string.
379        let (string, _) = Sanitizer::parse_whitespaces(string)?;
380        // Parse the "(" from the string.
381        let (string, _) = tag("(")(string)?;
382        // Parse the whitespace from the string.
383        let (string, _) = Sanitizer::parse_whitespaces(string)?;
384        // Parse the destination register type from the string.
385        let (string, destination_type) = ArrayType::parse(string)?;
386        // Parse the ")" from the string.
387        let (string, _) = tag(")")(string)?;
388
389        // Construct the instruction, checking for errors.
390        match Self::new(operands, operand_type, destination, destination_type) {
391            Ok(instruction) => Ok((string, instruction)),
392            Err(e) => map_res(fail, |_: ParserResult<Self>| {
393                Err(error(format!("Failed to parse '{}' instruction: {e}", Self::opcode())))
394            })(string),
395        }
396    }
397}
398
399impl<N: Network, const VARIANT: u8> FromStr for SerializeInstruction<N, VARIANT> {
400    type Err = Error;
401
402    /// Parses a string into an operation.
403    fn from_str(string: &str) -> Result<Self> {
404        match Self::parse(string) {
405            Ok((remainder, object)) => {
406                // Ensure the remainder is empty.
407                ensure!(remainder.is_empty(), "Failed to parse string. Found invalid character in: \"{remainder}\"");
408                // Return the object.
409                Ok(object)
410            }
411            Err(error) => bail!("Failed to parse string. {error}"),
412        }
413    }
414}
415
416impl<N: Network, const VARIANT: u8> Debug for SerializeInstruction<N, VARIANT> {
417    /// Prints the operation as a string.
418    fn fmt(&self, f: &mut Formatter) -> fmt::Result {
419        Display::fmt(self, f)
420    }
421}
422
423impl<N: Network, const VARIANT: u8> Display for SerializeInstruction<N, VARIANT> {
424    /// Prints the operation to a string.
425    fn fmt(&self, f: &mut Formatter) -> fmt::Result {
426        write!(f, "{} ", Self::opcode())?;
427        self.operands.iter().try_for_each(|operand| write!(f, "{operand} "))?;
428        write!(f, " ({}) into {} ({})", self.operand_type, self.destination, self.destination_type)
429    }
430}
431
432impl<N: Network, const VARIANT: u8> FromBytes for SerializeInstruction<N, VARIANT> {
433    /// Reads the operation from a buffer.
434    fn read_le<R: Read>(mut reader: R) -> IoResult<Self> {
435        // Read the operand.
436        let operand = Operand::read_le(&mut reader)?;
437        // Read the operand type.
438        let operand_type = PlaintextType::read_le(&mut reader)?;
439        // Read the destination register.
440        let destination = Register::read_le(&mut reader)?;
441        // Read the destination register type.
442        let destination_type = ArrayType::read_le(&mut reader)?;
443        // Return the operation.
444        match Self::new(vec![operand], operand_type, destination, destination_type) {
445            Ok(instruction) => Ok(instruction),
446            Err(e) => Err(error(format!("Failed to read '{}' instruction: {e}", Self::opcode()))),
447        }
448    }
449}
450
451impl<N: Network, const VARIANT: u8> ToBytes for SerializeInstruction<N, VARIANT> {
452    /// Writes the operation to a buffer.
453    fn write_le<W: Write>(&self, mut writer: W) -> IoResult<()> {
454        // Write the operands.
455        self.operands.iter().try_for_each(|operand| operand.write_le(&mut writer))?;
456        // Write the operand type.
457        self.operand_type.write_le(&mut writer)?;
458        // Write the destination register.
459        self.destination.write_le(&mut writer)?;
460        // Write the destination register type.
461        self.destination_type.write_le(&mut writer)
462    }
463}
464
465#[cfg(test)]
466mod tests {
467    use super::*;
468    use console::{network::MainnetV0, types::U32};
469
470    type CurrentNetwork = MainnetV0;
471
472    /// **Attention**: When changing this, also update in `tests/instruction/serialize.rs`.
473    fn valid_source_types<N: Network>() -> &'static [PlaintextType<N>] {
474        &[
475            PlaintextType::Literal(LiteralType::Address),
476            PlaintextType::Literal(LiteralType::Field),
477            PlaintextType::Literal(LiteralType::Group),
478            PlaintextType::Literal(LiteralType::I8),
479            PlaintextType::Literal(LiteralType::I16),
480            PlaintextType::Literal(LiteralType::I32),
481            PlaintextType::Literal(LiteralType::I128),
482            PlaintextType::Literal(LiteralType::I64),
483            PlaintextType::Literal(LiteralType::U8),
484            PlaintextType::Literal(LiteralType::U16),
485            PlaintextType::Literal(LiteralType::U32),
486            PlaintextType::Literal(LiteralType::U64),
487            PlaintextType::Literal(LiteralType::U128),
488            PlaintextType::Literal(LiteralType::Scalar),
489        ]
490    }
491
492    /// Randomly sample a destination type.
493    fn sample_destination_type<N: Network, const VARIANT: u8>(rng: &mut TestRng) -> ArrayType<N> {
494        // Generate a random array length between 1 and N::MAX_ARRAY_ELEMENTS.
495        let array_length = 1 + (u32::rand(rng) % u32::try_from(N::MAX_ARRAY_ELEMENTS).unwrap());
496        match VARIANT {
497            0 | 1 => {
498                ArrayType::new(PlaintextType::Literal(LiteralType::Boolean), vec![U32::new(array_length)]).unwrap()
499            }
500            _ => panic!("Invalid variant"),
501        }
502    }
503
504    fn run_parser_test<const VARIANT: u8>(rng: &mut TestRng) {
505        for source_type in valid_source_types() {
506            {
507                let opcode = SerializeVariant::opcode(VARIANT);
508                let destination_type = sample_destination_type::<CurrentNetwork, VARIANT>(rng);
509                let instruction = format!("{opcode} r0 ({source_type}) into r1 ({destination_type})");
510                println!("Parsing instruction: '{instruction}'");
511
512                let (string, serialize) = SerializeInstruction::<CurrentNetwork, VARIANT>::parse(&instruction).unwrap();
513                assert!(string.is_empty(), "Parser did not consume all of the string: '{string}'");
514                assert_eq!(serialize.operands.len(), 1, "The number of operands is incorrect");
515                assert_eq!(
516                    serialize.operands[0],
517                    Operand::Register(Register::Locator(0)),
518                    "The first operand is incorrect"
519                );
520                assert_eq!(&serialize.operand_type, source_type, "The operand type is incorrect");
521                assert_eq!(serialize.destination, Register::Locator(1), "The destination register is incorrect");
522                assert_eq!(&serialize.destination_type, &destination_type, "The destination type is incorrect");
523            }
524        }
525    }
526
527    #[test]
528    fn test_parse() {
529        // Initialize an RNG.
530        let rng = &mut TestRng::default();
531
532        // Run the parser test for each variant.
533        run_parser_test::<{ SerializeVariant::ToBits as u8 }>(rng);
534        run_parser_test::<{ SerializeVariant::ToBitsRaw as u8 }>(rng);
535
536        SerializeBitsRaw::<CurrentNetwork>::from_str("serialize.bits.raw r0 (boolean) into r1 ([boolean; 1u32])")
537            .unwrap();
538    }
539}
snarkvm_synthesizer_program/logic/instruction/operation/serialize.rs

snarkvm_synthesizer_program/logic/instruction/operation/
serialize.rs
