snarkvm_ledger_block/transition/input/
mod.rs

1// Copyright (c) 2019-2026 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 serialize;
18mod string;
19
20use console::{
21    network::prelude::*,
22    program::{Ciphertext, Plaintext, TransitionLeaf, ValueType},
23    types::Field,
24};
25
26type Variant = u8;
27
28/// The transition input.
29#[derive(Clone, PartialEq, Eq)]
30pub enum Input<N: Network> {
31    /// The plaintext hash and (optional) plaintext.
32    Constant(Field<N>, Option<Plaintext<N>>),
33    /// The plaintext hash and (optional) plaintext.
34    Public(Field<N>, Option<Plaintext<N>>),
35    /// The ciphertext hash and (optional) ciphertext.
36    Private(Field<N>, Option<Ciphertext<N>>),
37    /// The serial number and tag of the record.
38    Record(Field<N>, Field<N>),
39    /// The hash of the external record's (function_id, record, tvk, input index).
40    ExternalRecord(Field<N>),
41    /// The hash of the dynamic record's (function_id, record, tvk, input index).
42    DynamicRecord(Field<N>),
43    /// The serial number, tag, and dynamic ID of a record input in a dynamic call transition.
44    /// The `dynamic_id` is computed from `hash(function_id, record, tvk, index)`.
45    /// From the caller's perspective, this appears as `DynamicRecord(dynamic_id)`.
46    RecordWithDynamicID(Field<N>, Field<N>, Field<N>),
47    /// The external record hash and dynamic ID of an external record input in a dynamic call transition.
48    /// The `dynamic_id` is computed from `hash(function_id, record, tvk, index)`.
49    /// From the caller's perspective, this appears as `DynamicRecord(dynamic_id)`.
50    ExternalRecordWithDynamicID(Field<N>, Field<N>),
51}
52
53impl<N: Network> Input<N> {
54    /// Returns the variant of the input.
55    pub const fn variant(&self) -> Variant {
56        match self {
57            Input::Constant(..) => 0,
58            Input::Public(..) => 1,
59            Input::Private(..) => 2,
60            Input::Record(..) => 3, // <- Changing this will invalidate 'console::StatePath' and 'circuit::StatePath'.
61            Input::ExternalRecord(..) => 4,
62            Input::DynamicRecord(..) => 5,
63            Input::RecordWithDynamicID(..) => 6,
64            Input::ExternalRecordWithDynamicID(..) => 7,
65        }
66    }
67
68    /// Returns the ID of the input.
69    pub const fn id(&self) -> &Field<N> {
70        match self {
71            Input::Constant(id, ..) => id,
72            Input::Public(id, ..) => id,
73            Input::Private(id, ..) => id,
74            Input::Record(serial_number, ..) => serial_number,
75            Input::ExternalRecord(id) => id,
76            Input::DynamicRecord(id) => id,
77            Input::RecordWithDynamicID(serial_number, ..) => serial_number,
78            Input::ExternalRecordWithDynamicID(id, ..) => id,
79        }
80    }
81
82    /// Returns the input as a transition leaf.
83    /// Note: RecordWithDynamicID uses leaf variant 3 (same as Record) with version 2.
84    /// Note: ExternalRecordWithDynamicID uses leaf variant 4 (same as ExternalRecord) with version 2.
85    pub fn to_transition_leaf(&self, index: u8) -> TransitionLeaf<N> {
86        match self {
87            // RecordWithDynamicID produces leaf with version 2, variant 3.
88            Input::RecordWithDynamicID(..) => TransitionLeaf::new_record_with_dynamic_id(index, *self.id()),
89            // ExternalRecordWithDynamicID produces leaf with version 2, variant 4.
90            Input::ExternalRecordWithDynamicID(..) => {
91                TransitionLeaf::new_external_record_with_dynamic_id(index, *self.id())
92            }
93            // All other variants use their serialization variant byte.
94            _ => TransitionLeaf::new(index, self.variant(), *self.id()),
95        }
96    }
97
98    /// Returns the tag, if the input is a record.
99    pub const fn tag(&self) -> Option<&Field<N>> {
100        match self {
101            Input::Record(_, tag) | Input::RecordWithDynamicID(_, tag, _) => Some(tag),
102            _ => None,
103        }
104    }
105
106    /// Returns the tag, if the input is a record, and consumes `self`.
107    pub fn into_tag(self) -> Option<Field<N>> {
108        match self {
109            Input::Record(_, tag) | Input::RecordWithDynamicID(_, tag, _) => Some(tag),
110            _ => None,
111        }
112    }
113
114    /// Returns the serial number, if the input is a record.
115    pub const fn serial_number(&self) -> Option<&Field<N>> {
116        match self {
117            Input::Record(serial_number, ..) | Input::RecordWithDynamicID(serial_number, ..) => Some(serial_number),
118            _ => None,
119        }
120    }
121
122    /// Returns the serial number, if the input is a record, and consumes `self`.
123    pub fn into_serial_number(self) -> Option<Field<N>> {
124        match self {
125            Input::Record(serial_number, ..) | Input::RecordWithDynamicID(serial_number, ..) => Some(serial_number),
126            _ => None,
127        }
128    }
129
130    /// Returns the public verifier inputs for the proof.
131    pub fn verifier_inputs(&self) -> impl '_ + Iterator<Item = N::Field> {
132        [Some(self.id()), self.tag()].into_iter().flatten().map(|id| **id)
133    }
134
135    /// Returns the dynamic ID, if the input carries one.
136    pub const fn dynamic_id(&self) -> Option<&Field<N>> {
137        match self {
138            Input::RecordWithDynamicID(_, _, dynamic_id) | Input::ExternalRecordWithDynamicID(_, dynamic_id) => {
139                Some(dynamic_id)
140            }
141            _ => None,
142        }
143    }
144
145    /// Returns the input from the caller's perspective.
146    /// This converts internal variants (like RecordWithDynamicID) to what
147    /// the caller would see (like DynamicRecord).
148    pub fn to_caller_input(&self) -> Self {
149        match self {
150            // RecordWithDynamicID becomes DynamicRecord from caller's view.
151            Self::RecordWithDynamicID(_, _, dynamic_id) => Self::DynamicRecord(*dynamic_id),
152            // ExternalRecordWithDynamicID becomes DynamicRecord from caller's view.
153            Self::ExternalRecordWithDynamicID(_, dynamic_id) => Self::DynamicRecord(*dynamic_id),
154            // All other variants are unchanged.
155            other => other.clone(),
156        }
157    }
158
159    /// Returns `true` if the input is well-formed.
160    /// If the optional value exists, this method checks that it hashes to the input ID.
161    pub fn verify(&self, function_id: Field<N>, tcm: &Field<N>, index: usize) -> bool {
162        // Ensure the hash of the value (if the value exists) is correct.
163        let result = || match self {
164            Input::Constant(hash, Some(input)) => {
165                match input.to_fields() {
166                    Ok(fields) => {
167                        // Construct the (console) input index as a field element.
168                        let index = Field::from_u16(index as u16);
169                        // Construct the preimage as `(function ID || input || tcm || index)`.
170                        let mut preimage = Vec::new();
171                        preimage.push(function_id);
172                        preimage.extend(fields);
173                        preimage.push(*tcm);
174                        preimage.push(index);
175                        // Ensure the hash matches.
176                        match N::hash_psd8(&preimage) {
177                            Ok(candidate_hash) => Ok(hash == &candidate_hash),
178                            Err(error) => Err(error),
179                        }
180                    }
181                    Err(error) => Err(error),
182                }
183            }
184            Input::Public(hash, Some(input)) => {
185                match input.to_fields() {
186                    Ok(fields) => {
187                        // Construct the (console) input index as a field element.
188                        let index = Field::from_u16(index as u16);
189                        // Construct the preimage as `(function ID || input || tcm || index)`.
190                        let mut preimage = Vec::new();
191                        preimage.push(function_id);
192                        preimage.extend(fields);
193                        preimage.push(*tcm);
194                        preimage.push(index);
195                        // Ensure the hash matches.
196                        match N::hash_psd8(&preimage) {
197                            Ok(candidate_hash) => Ok(hash == &candidate_hash),
198                            Err(error) => Err(error),
199                        }
200                    }
201                    Err(error) => Err(error),
202                }
203            }
204            Input::Private(hash, Some(value)) => {
205                match value.to_fields() {
206                    // Ensure the hash matches.
207                    Ok(fields) => match N::hash_psd8(&fields) {
208                        Ok(candidate_hash) => Ok(hash == &candidate_hash),
209                        Err(error) => Err(error),
210                    },
211                    Err(error) => Err(error),
212                }
213            }
214            Input::Constant(_, None) | Input::Public(_, None) | Input::Private(_, None) => {
215                // This enforces that the transition *must* contain the value for this transition input.
216                // A similar rule is enforced for the transition output.
217                bail!("A transition input value is missing")
218            }
219            Input::Record(_, _)
220            | Input::ExternalRecord(_)
221            | Input::DynamicRecord(_)
222            | Input::RecordWithDynamicID(_, _, _)
223            | Input::ExternalRecordWithDynamicID(_, _) => Ok(true),
224        };
225
226        match result() {
227            Ok(is_hash_valid) => is_hash_valid,
228            Err(error) => {
229                eprintln!("{error}");
230                false
231            }
232        }
233    }
234
235    /// Returns `true` if the input matches the expected value type.
236    pub fn is_type(&self, expected_value_type: &ValueType<N>) -> bool {
237        matches!(
238            (self, expected_value_type),
239            (Self::Constant(..), ValueType::Constant(..))
240                | (Self::Public(..), ValueType::Public(..))
241                | (Self::Private(..), ValueType::Private(..))
242                | (Self::Record(..), ValueType::Record(..))
243                | (Self::RecordWithDynamicID(..), ValueType::Record(..))
244                | (Self::ExternalRecord(..), ValueType::ExternalRecord(..))
245                | (Self::ExternalRecordWithDynamicID(..), ValueType::ExternalRecord(..))
246                | (Self::DynamicRecord(..), ValueType::DynamicRecord)
247        )
248    }
249
250    /// Returns `true` if the input matches the given value type as seen by the callee. `Record`,
251    /// `ExternalRecord`, `DynamicRecord`, `RecordWithDynamicID` and `ExternalRecordWithDynamicID`
252    /// inputs are handled according to the value of `is_dynamic`:
253    ///  - `Some(true)` enforces type correspondence assuming the inputs refer to a dynamic call.
254    ///  - `Some(false)` enforces it assuming a static call.
255    ///  - `None` is flexible and makes no assumption about the type of call: both dynamic-call and
256    ///    static-call matching patterns return `true`.
257    ///
258    /// For inputs of an invalid type according to `is_dynamic`, this function returns false
259    /// regardless of the value type.
260    pub fn valid_as_argument(&self, callee_value_type: &ValueType<N>, is_dynamic: Option<bool>) -> bool {
261        if matches!(
262            (self, callee_value_type),
263            (Self::Constant(..), ValueType::Constant(..))
264                | (Self::Public(..), ValueType::Public(..))
265                | (Self::Private(..), ValueType::Private(..))
266        ) {
267            return true;
268        }
269
270        if is_dynamic == Some(true) {
271            // Unmatched variants:
272            //  - Self::Record: cannot be the callee's view of a dynamic-call input, so we return
273            //    false regardless of the ValueType
274            //  - Self::ExternalRecord: same as above
275            matches!(
276                (self, callee_value_type),
277                // Caller sees DynamicRecord, callee receives static Record, translation occurs
278                (Self::RecordWithDynamicID(..), ValueType::Record(..))
279                // Caller sees DynamicRecord, callee receives ExternalRecord, translation occurs
280                | (Self::ExternalRecordWithDynamicID(..), ValueType::ExternalRecord(..))
281                // Caller and callee see DynamicRecord, no translation occurs
282                | (Self::DynamicRecord(..), ValueType::DynamicRecord)
283            )
284        } else if is_dynamic == Some(false) {
285            // Unmatched variants:
286            //  - Self::RecordWithDynamicID: no translation can occur in static calls
287            //  - Self::ExternalRecordWithDynamicID: same as above
288            matches!(
289                (self, callee_value_type),
290                // This can only occur for the root transition since static local calls are
291                // disallowed
292                (Self::Record(..), ValueType::Record(..))
293                // Pass-through of External records (no translation )
294                | (Self::ExternalRecord(..), ValueType::ExternalRecord(..))
295                // Since this is a static call, dynamic records are only passed through
296                | (Self::DynamicRecord(..), ValueType::DynamicRecord)
297            )
298        } else {
299            // is_dynamic = None: flexible matching
300            self.is_type(callee_value_type)
301        }
302    }
303}
304
305#[cfg(test)]
306pub(crate) mod test_helpers {
307    use super::*;
308    use console::{network::MainnetV0, program::Literal};
309
310    type CurrentNetwork = MainnetV0;
311
312    /// Sample the transition inputs.
313    pub(crate) fn sample_inputs() -> Vec<(<CurrentNetwork as Network>::TransitionID, Input<CurrentNetwork>)> {
314        let rng = &mut TestRng::default();
315
316        // Sample a transition.
317        let transaction = crate::transaction::test_helpers::sample_execution_transaction_with_fee(true, rng, 0);
318        let transition = transaction.transitions().next().unwrap();
319
320        // Retrieve the transition ID and input.
321        let transition_id = *transition.id();
322        let input = transition.inputs().iter().next().unwrap().clone();
323
324        // Sample a random plaintext.
325        let plaintext = Plaintext::Literal(Literal::Field(Uniform::rand(rng)), Default::default());
326        let plaintext_hash = CurrentNetwork::hash_bhp1024(&plaintext.to_bits_le()).unwrap();
327        // Sample a random ciphertext.
328        let fields: Vec<_> = (0..10).map(|_| Uniform::rand(rng)).collect();
329        let ciphertext = Ciphertext::from_fields(&fields).unwrap();
330        let ciphertext_hash = CurrentNetwork::hash_bhp1024(&ciphertext.to_bits_le()).unwrap();
331
332        vec![
333            (transition_id, input),
334            (Uniform::rand(rng), Input::Constant(Uniform::rand(rng), None)),
335            (Uniform::rand(rng), Input::Constant(plaintext_hash, Some(plaintext.clone()))),
336            (Uniform::rand(rng), Input::Public(Uniform::rand(rng), None)),
337            (Uniform::rand(rng), Input::Public(plaintext_hash, Some(plaintext))),
338            (Uniform::rand(rng), Input::Private(Uniform::rand(rng), None)),
339            (Uniform::rand(rng), Input::Private(ciphertext_hash, Some(ciphertext))),
340            (Uniform::rand(rng), Input::Record(Uniform::rand(rng), Uniform::rand(rng))),
341            (Uniform::rand(rng), Input::ExternalRecord(Uniform::rand(rng))),
342            (
343                Uniform::rand(rng),
344                Input::RecordWithDynamicID(Uniform::rand(rng), Uniform::rand(rng), Uniform::rand(rng)),
345            ),
346            (Uniform::rand(rng), Input::ExternalRecordWithDynamicID(Uniform::rand(rng), Uniform::rand(rng))),
347            (Uniform::rand(rng), Input::DynamicRecord(Uniform::rand(rng))),
348        ]
349    }
350}
351
352#[cfg(test)]
353mod tests {
354    use super::*;
355    use console::network::MainnetV0;
356
357    type CurrentNetwork = MainnetV0;
358
359    #[test]
360    fn test_to_caller_input_record_with_dynamic_id() {
361        // RecordWithDynamicID should become DynamicRecord(dynamic_id) from caller's view.
362        let serial_number = Field::<CurrentNetwork>::from_u64(1);
363        let tag = Field::<CurrentNetwork>::from_u64(2);
364        let dynamic_id = Field::<CurrentNetwork>::from_u64(3);
365
366        let input = Input::<CurrentNetwork>::RecordWithDynamicID(serial_number, tag, dynamic_id);
367        let caller_input = input.to_caller_input();
368
369        assert_eq!(caller_input, Input::<CurrentNetwork>::DynamicRecord(dynamic_id));
370    }
371
372    #[test]
373    fn test_to_caller_input_external_record_with_dynamic_id() {
374        // ExternalRecordWithDynamicID should become DynamicRecord(dynamic_id) from caller's view.
375        let ext_id = Field::<CurrentNetwork>::from_u64(10);
376        let dynamic_id = Field::<CurrentNetwork>::from_u64(20);
377
378        let input = Input::<CurrentNetwork>::ExternalRecordWithDynamicID(ext_id, dynamic_id);
379        let caller_input = input.to_caller_input();
380
381        assert_eq!(caller_input, Input::<CurrentNetwork>::DynamicRecord(dynamic_id));
382    }
383
384    #[test]
385    fn test_to_caller_input_non_dynamic_variants_unchanged() {
386        // Non-dynamic variants must be returned unchanged.
387        let id = Field::<CurrentNetwork>::from_u64(42);
388
389        let constant = Input::<CurrentNetwork>::Constant(id, None);
390        assert_eq!(constant.to_caller_input(), constant);
391
392        let public = Input::<CurrentNetwork>::Public(id, None);
393        assert_eq!(public.to_caller_input(), public);
394
395        let dynamic_record = Input::<CurrentNetwork>::DynamicRecord(id);
396        assert_eq!(dynamic_record.to_caller_input(), dynamic_record);
397
398        let external = Input::<CurrentNetwork>::ExternalRecord(id);
399        assert_eq!(external.to_caller_input(), external);
400    }
401}
snarkvm_ledger_block/transition/input/mod.rs

snarkvm_ledger_block/transition/input/
mod.rs
