snarkvm_synthesizer_program/traits/
finalize_store.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::FinalizeOperation;
17use console::{
18    network::Network,
19    prelude::Result,
20    program::{Identifier, Plaintext, ProgramID, Value},
21};
22
23pub trait FinalizeStoreTrait<N: Network> {
24    /// Returns `true` if the given `program ID` and `mapping name` is confirmed to exist.
25    fn contains_mapping_confirmed(&self, program_id: &ProgramID<N>, mapping_name: &Identifier<N>) -> Result<bool>;
26
27    /// Returns `true` if the given `program ID` and `mapping name` exist.
28    /// This method was added to support execution of constructors during deployment.
29    /// Prior to supporting program upgrades, `contains_mapping_confirmed` was used to check that a mapping exists before executing a command like `set`, `get`, `remove`, etc.
30    /// However, during deployment, the mapping only speculatively exists, so `contains_mapping_speculative` should be used instead.
31    /// This usage is safe because the mappings used in a program are statically verified to exist in `FinalizeTypes::from_*` before the deployment or upgrade's constructor is executed.
32    fn contains_mapping_speculative(&self, program_id: &ProgramID<N>, mapping_name: &Identifier<N>) -> Result<bool>;
33
34    /// Returns `true` if the given `program ID`, `mapping name`, and `key` exist.
35    fn contains_key_speculative(
36        &self,
37        program_id: ProgramID<N>,
38        mapping_name: Identifier<N>,
39        key: &Plaintext<N>,
40    ) -> Result<bool>;
41
42    /// Returns the speculative value for the given `program ID`, `mapping name`, and `key`.
43    fn get_value_speculative(
44        &self,
45        program_id: ProgramID<N>,
46        mapping_name: Identifier<N>,
47        key: &Plaintext<N>,
48    ) -> Result<Option<Value<N>>>;
49
50    /// Stores the given `(key, value)` pair at the given `program ID` and `mapping name` in storage.
51    /// If the `mapping name` is not initialized, an error is returned.
52    /// If the `key` already exists, the method returns an error.
53    fn insert_key_value(
54        &self,
55        program_id: ProgramID<N>,
56        mapping_name: Identifier<N>,
57        key: Plaintext<N>,
58        value: Value<N>,
59    ) -> Result<FinalizeOperation<N>>;
60
61    /// Stores the given `(key, value)` pair at the given `program ID` and `mapping name` in storage.
62    /// If the `mapping name` is not initialized, an error is returned.
63    /// If the `key` does not exist, the `(key, value)` pair is initialized.
64    /// If the `key` already exists, the `value` is overwritten.
65    fn update_key_value(
66        &self,
67        program_id: ProgramID<N>,
68        mapping_name: Identifier<N>,
69        key: Plaintext<N>,
70        value: Value<N>,
71    ) -> Result<FinalizeOperation<N>>;
72
73    /// Removes the key-value pair for the given `program ID`, `mapping name`, and `key` from storage.
74    /// If the `key` does not exist, the method returns `None`.
75    fn remove_key_value(
76        &self,
77        program_id: ProgramID<N>,
78        mapping_name: Identifier<N>,
79        key: &Plaintext<N>,
80    ) -> Result<Option<FinalizeOperation<N>>>;
81}
snarkvm_synthesizer_program/traits/finalize_store.rs

snarkvm_synthesizer_program/traits/
finalize_store.rs
