Skip to main content

iota_core/authority/
test_authority_builder.rs

1// Copyright (c) Mysten Labs, Inc.
2// Modifications Copyright (c) 2024 IOTA Stiftung
3// SPDX-License-Identifier: Apache-2.0
4
5use std::{collections::BTreeSet, num::NonZeroUsize, path::PathBuf, sync::Arc};
6
7use fastcrypto::traits::KeyPair;
8use iota_config::{
9    ExecutionCacheConfig,
10    certificate_deny_config::CertificateDenyConfig,
11    genesis::Genesis,
12    node::{AuthorityOverloadConfig, AuthorityStorePruningConfig, ExpensiveSafetyCheckConfig},
13    transaction_deny_config::TransactionDenyConfig,
14    verifier_signing_config::VerifierSigningConfig,
15};
16use iota_network::randomness;
17use iota_protocol_config::{Chain, ProtocolConfig};
18use iota_swarm_config::{genesis_config::AccountConfig, network_config::NetworkConfig};
19use iota_types::{
20    base_types::AuthorityName, crypto::AuthorityKeyPair, digests::ChainIdentifier,
21    executable_transaction::VerifiedExecutableTransaction, iota_system_state::IotaSystemStateTrait,
22    object::Object, supported_protocol_versions::SupportedProtocolVersions,
23    transaction::VerifiedTransaction,
24};
25use prometheus_filtered::Registry;
26
27use super::{
28    ExecutionEnv, backpressure::BackpressureManager, epoch_start_configuration::EpochFlag,
29};
30use crate::{
31    authority::{
32        AuthorityState, AuthorityStore, authority_per_epoch_store::AuthorityPerEpochStore,
33        authority_store_tables::AuthorityPerpetualTables,
34        epoch_start_configuration::EpochStartConfiguration,
35    },
36    checkpoints::CheckpointStore,
37    epoch::{
38        committee_store::CommitteeStore, epoch_metrics::EpochMetrics, randomness::RandomnessManager,
39    },
40    execution_cache::build_execution_cache,
41    mock_consensus::{ConsensusMode, MockConsensusClient},
42    module_cache_metrics::ResolverMetrics,
43    rpc_indexes::{
44        RpcIndexesStore,
45        schema::{IndexGroup, RPC_INDEXES_DIR},
46    },
47    signature_verifier::SignatureVerifierMetrics,
48};
49
50#[derive(Default, Clone)]
51pub struct TestAuthorityBuilder<'a> {
52    store_base_path: Option<PathBuf>,
53    store: Option<Arc<AuthorityStore>>,
54    transaction_deny_config: Option<TransactionDenyConfig>,
55    certificate_deny_config: Option<CertificateDenyConfig>,
56    verifier_signing_config: Option<VerifierSigningConfig>,
57    protocol_config: Option<ProtocolConfig>,
58    reference_gas_price: Option<u64>,
59    node_keypair: Option<&'a AuthorityKeyPair>,
60    genesis: Option<&'a Genesis>,
61    starting_objects: Option<&'a [Object]>,
62    expensive_safety_checks: Option<ExpensiveSafetyCheckConfig>,
63    disable_indexer: bool,
64    accounts: Vec<AccountConfig>,
65    /// By default, we don't insert the genesis checkpoint, which isn't needed
66    /// by most tests.
67    insert_genesis_checkpoint: bool,
68    authority_overload_config: Option<AuthorityOverloadConfig>,
69    cache_config: Option<ExecutionCacheConfig>,
70    disable_execute_genesis_transactions: bool,
71    chain_override: Option<Chain>,
72    num_epochs_to_retain: Option<u64>,
73    num_epochs_to_retain_for_checkpoints: Option<u64>,
74    num_epochs_to_retain_for_indexes: Option<u64>,
75    post_consensus_validation_readers: Option<NonZeroUsize>,
76}
77
78/// The readers a test authority validates a commit with unless a test sets
79/// another number: more than one, whatever the machine, so that tests take
80/// the path that reads inputs ahead of the validation loop.
81const TEST_POST_CONSENSUS_VALIDATION_READERS: NonZeroUsize = NonZeroUsize::new(4).unwrap();
82
83impl<'a> TestAuthorityBuilder<'a> {
84    pub fn new() -> Self {
85        Self::default()
86    }
87
88    pub fn with_post_consensus_validation_readers(mut self, readers: NonZeroUsize) -> Self {
89        assert!(
90            self.post_consensus_validation_readers
91                .replace(readers)
92                .is_none()
93        );
94        self
95    }
96
97    pub fn with_store_base_path(mut self, path: PathBuf) -> Self {
98        assert!(self.store_base_path.replace(path).is_none());
99        self
100    }
101
102    pub fn with_starting_objects(mut self, objects: &'a [Object]) -> Self {
103        assert!(self.starting_objects.replace(objects).is_none());
104        self
105    }
106
107    pub fn with_store(mut self, store: Arc<AuthorityStore>) -> Self {
108        assert!(self.store.replace(store).is_none());
109        self
110    }
111
112    pub fn with_transaction_deny_config(mut self, config: TransactionDenyConfig) -> Self {
113        assert!(self.transaction_deny_config.replace(config).is_none());
114        self
115    }
116
117    pub fn with_certificate_deny_config(mut self, config: CertificateDenyConfig) -> Self {
118        assert!(self.certificate_deny_config.replace(config).is_none());
119        self
120    }
121
122    pub fn with_verifier_signing_config(mut self, config: VerifierSigningConfig) -> Self {
123        assert!(self.verifier_signing_config.replace(config).is_none());
124        self
125    }
126
127    pub fn with_protocol_config(mut self, config: ProtocolConfig) -> Self {
128        assert!(self.protocol_config.replace(config).is_none());
129        self
130    }
131
132    pub fn with_reference_gas_price(mut self, reference_gas_price: u64) -> Self {
133        // If genesis is already set then setting rgp is meaningless since it will be
134        // overwritten.
135        assert!(self.genesis.is_none());
136        assert!(
137            self.reference_gas_price
138                .replace(reference_gas_price)
139                .is_none()
140        );
141        self
142    }
143
144    pub fn with_genesis_and_keypair(
145        mut self,
146        genesis: &'a Genesis,
147        keypair: &'a AuthorityKeyPair,
148    ) -> Self {
149        assert!(self.genesis.replace(genesis).is_none());
150        assert!(self.node_keypair.replace(keypair).is_none());
151        self
152    }
153
154    pub fn with_keypair(mut self, keypair: &'a AuthorityKeyPair) -> Self {
155        assert!(self.node_keypair.replace(keypair).is_none());
156        self
157    }
158
159    /// When providing a network config, we will use the \node_idx validator's
160    /// key as the keypair for the new node.
161    pub fn with_network_config(self, config: &'a NetworkConfig, node_idx: usize) -> Self {
162        self.with_genesis_and_keypair(
163            &config.genesis,
164            config.validator_configs()[node_idx].authority_key_pair(),
165        )
166    }
167
168    pub fn disable_indexer(mut self) -> Self {
169        self.disable_indexer = true;
170        self
171    }
172
173    pub fn insert_genesis_checkpoint(mut self) -> Self {
174        self.insert_genesis_checkpoint = true;
175        self
176    }
177
178    pub fn with_expensive_safety_checks(mut self, config: ExpensiveSafetyCheckConfig) -> Self {
179        assert!(self.expensive_safety_checks.replace(config).is_none());
180        self
181    }
182
183    pub fn with_accounts(mut self, accounts: Vec<AccountConfig>) -> Self {
184        self.accounts = accounts;
185        self
186    }
187
188    pub fn with_authority_overload_config(mut self, config: AuthorityOverloadConfig) -> Self {
189        assert!(self.authority_overload_config.replace(config).is_none());
190        self
191    }
192
193    pub fn with_cache_config(mut self, config: ExecutionCacheConfig) -> Self {
194        self.cache_config = Some(config);
195        self
196    }
197
198    pub fn disable_execute_genesis_transactions(mut self) -> Self {
199        self.disable_execute_genesis_transactions = true;
200        self
201    }
202
203    /// The number of historic epochs whose superseded object versions are
204    /// retained beyond the current one. `u64::MAX` retains all of them.
205    pub fn with_num_epochs_to_retain(mut self, num_epochs_to_retain: u64) -> Self {
206        assert!(
207            self.num_epochs_to_retain
208                .replace(num_epochs_to_retain)
209                .is_none()
210        );
211        self
212    }
213
214    /// The number of epochs of transaction and checkpoint history retained,
215    /// counting the epoch the node has last executed. Left unset, the
216    /// pruning config's own default applies.
217    pub fn with_num_epochs_to_retain_for_checkpoints(mut self, num_epochs_to_retain: u64) -> Self {
218        assert!(
219            self.num_epochs_to_retain_for_checkpoints
220                .replace(num_epochs_to_retain)
221                .is_none()
222        );
223        self
224    }
225
226    /// The number of epochs of RPC index history retained, counting the
227    /// epoch the node is in. Left unset, index pruning is off.
228    pub fn with_num_epochs_to_retain_for_indexes(mut self, num_epochs_to_retain: u64) -> Self {
229        assert!(
230            self.num_epochs_to_retain_for_indexes
231                .replace(num_epochs_to_retain)
232                .is_none()
233        );
234        self
235    }
236
237    pub fn with_chain_override(mut self, chain: Chain) -> Self {
238        self.chain_override = Some(chain);
239        self
240    }
241
242    pub async fn build(self) -> Arc<AuthorityState> {
243        let protocol_config = self.protocol_config.clone();
244
245        // Genesis must build the system framework at the binary format version it was
246        // compiled with. A test override that lowers `move_binary_format_version`
247        // must not apply while genesis verifies the system packages.
248        // Build genesis with the framework's binary format version
249        // restored, then apply the unmodified override below for transaction
250        // execution.
251        let local_network_config = {
252            let _genesis_guard = protocol_config.clone().map(|mut config| {
253                let framework_binary_format_version =
254                    ProtocolConfig::get_for_version(config.version, Chain::Unknown)
255                        .move_binary_format_version();
256                config.set_move_binary_format_version_for_testing(framework_binary_format_version);
257                ProtocolConfig::apply_overrides_for_testing(move |_, _| config.clone())
258            });
259
260            let mut local_network_config_builder =
261                iota_swarm_config::network_config_builder::ConfigBuilder::new_with_temp_dir()
262                    .with_accounts(self.accounts)
263                    .with_reference_gas_price(self.reference_gas_price.unwrap_or(500));
264            if let Some(protocol_config) = &self.protocol_config {
265                local_network_config_builder =
266                    local_network_config_builder.with_protocol_version(protocol_config.version);
267            }
268            local_network_config_builder.build()
269        };
270
271        // `_guard` must be declared here so it is not dropped before
272        // `AuthorityPerEpochStore::new` is called
273        let _guard = protocol_config
274            .map(|config| ProtocolConfig::apply_overrides_for_testing(move |_, _| config.clone()));
275
276        let genesis = &self.genesis.unwrap_or(&local_network_config.genesis);
277        let genesis_committee = genesis.committee().unwrap();
278        let storage_dir = self
279            .store_base_path
280            .unwrap_or_else(|| iota_common::tempdir().keep());
281        let mut config = local_network_config.validator_configs()[0].clone();
282        let registry = Registry::new();
283
284        let authority_store = match self.store {
285            Some(store) => store,
286            None => {
287                // unwrap ok - for testing only.
288                let (perpetual_tables, historic_objects, historic_ledger, epoch_markers) =
289                    AuthorityPerpetualTables::open_with_historic_objects(
290                        &storage_dir.join("store"),
291                        None,
292                    )
293                    .unwrap();
294                AuthorityStore::open_with_committee_for_testing(
295                    Arc::new(perpetual_tables),
296                    Arc::new(historic_objects),
297                    Arc::new(historic_ledger),
298                    Arc::new(epoch_markers),
299                    &genesis_committee,
300                    genesis,
301                )
302                .await
303                .unwrap()
304            }
305        };
306        if let Some(cache_config) = self.cache_config {
307            config.execution_cache_config = cache_config;
308        }
309
310        let keypair = if let Some(keypair) = self.node_keypair {
311            keypair.copy()
312        } else {
313            config.authority_key_pair().copy()
314        };
315
316        let secret = Arc::pin(keypair.copy());
317        let name: AuthorityName = secret.public().into();
318        let cache_metrics = Arc::new(ResolverMetrics::new(&registry));
319        let signature_verifier_metrics = SignatureVerifierMetrics::new(&registry);
320        let epoch_flags = EpochFlag::default_flags_for_new_epoch(&config);
321        let epoch_start_configuration = EpochStartConfiguration::new(
322            genesis.iota_system_object().into_epoch_start_state(),
323            *genesis.checkpoint().digest(),
324            &genesis.objects(),
325            epoch_flags,
326        )
327        .unwrap();
328        let expensive_safety_checks = self.expensive_safety_checks.unwrap_or_default();
329
330        let checkpoint_store = CheckpointStore::new(&storage_dir.join("checkpoints"));
331        let backpressure_manager =
332            BackpressureManager::new_from_checkpoint_store(&checkpoint_store);
333
334        let cache_traits = build_execution_cache(
335            &config.execution_cache_config,
336            &registry,
337            &authority_store,
338            backpressure_manager.clone(),
339        );
340
341        let chain_id = ChainIdentifier::from(*genesis.checkpoint().digest());
342        let chain = match self.chain_override {
343            Some(chain) => chain,
344            None => chain_id.chain(),
345        };
346
347        let epoch_store = AuthorityPerEpochStore::new(
348            name,
349            Arc::new(genesis_committee.clone()),
350            &storage_dir.join("store"),
351            None,
352            EpochMetrics::new(&registry),
353            epoch_start_configuration,
354            cache_traits.backing_package_store.clone(),
355            cache_metrics,
356            signature_verifier_metrics,
357            &expensive_safety_checks,
358            (chain_id, chain),
359            checkpoint_store
360                .get_highest_executed_checkpoint_seq_number()
361                .unwrap()
362                .unwrap_or(0),
363        )
364        .expect("failed to create authority per epoch store");
365        let committee_store = Arc::new(CommitteeStore::new(
366            storage_dir.join("epochs"),
367            &genesis_committee,
368            None,
369        ));
370
371        if self.insert_genesis_checkpoint {
372            checkpoint_store.insert_genesis_checkpoint(
373                genesis.checkpoint(),
374                genesis.checkpoint_contents().clone(),
375                &epoch_store,
376            );
377        }
378        let rpc_indexes_store = if self.disable_indexer {
379            None
380        } else {
381            Some(
382                RpcIndexesStore::new(
383                    storage_dir.join(RPC_INDEXES_DIR),
384                    None,
385                    &registry,
386                    BTreeSet::from([IndexGroup::JsonRpc, IndexGroup::Grpc]),
387                    epoch_store
388                        .protocol_config()
389                        .max_move_identifier_len_as_option(),
390                    self.num_epochs_to_retain_for_indexes,
391                    &authority_store,
392                    &checkpoint_store,
393                    Arc::default(),
394                )
395                .await
396                .expect("failed to open the RPC index store"),
397            )
398        };
399
400        let transaction_deny_config = self.transaction_deny_config.unwrap_or_default();
401        let certificate_deny_config = self.certificate_deny_config.unwrap_or_default();
402        let verifier_signing_config = self.verifier_signing_config.unwrap_or_default();
403        let authority_overload_config = self.authority_overload_config.unwrap_or_default();
404        let mut pruning_config = AuthorityStorePruningConfig::default();
405        if let Some(num_epochs_to_retain) = self.num_epochs_to_retain {
406            pruning_config.set_num_epochs_to_retain(num_epochs_to_retain);
407        }
408        if let Some(num_epochs_to_retain) = self.num_epochs_to_retain_for_checkpoints {
409            pruning_config.set_num_epochs_to_retain_for_checkpoints(Some(num_epochs_to_retain));
410        }
411
412        config.transaction_deny_config = transaction_deny_config;
413        config.certificate_deny_config = certificate_deny_config;
414        config.verifier_signing_config = verifier_signing_config;
415        config.authority_overload_config = authority_overload_config;
416        config.authority_store_pruning_config = pruning_config;
417        config.post_consensus_validation_readers = Some(
418            self.post_consensus_validation_readers
419                .unwrap_or(TEST_POST_CONSENSUS_VALIDATION_READERS),
420        );
421
422        let chain_identifier = ChainIdentifier::from(*genesis.checkpoint().digest());
423        let policy_config = config.policy_config.clone();
424
425        let state = AuthorityState::new(
426            name,
427            secret,
428            SupportedProtocolVersions::SYSTEM_DEFAULT,
429            authority_store,
430            cache_traits,
431            epoch_store.clone(),
432            committee_store,
433            rpc_indexes_store,
434            checkpoint_store,
435            &registry,
436            config.clone(),
437            None,
438            chain_identifier,
439            policy_config,
440            None,
441        )
442        .await;
443
444        // Set up randomness with no-op consensus (DKG will not complete).
445        let consensus_client = Box::new(MockConsensusClient::new(
446            Arc::downgrade(&state),
447            ConsensusMode::Noop,
448        ));
449        let randomness_manager = RandomnessManager::try_new(
450            Arc::downgrade(&epoch_store),
451            consensus_client,
452            randomness::Handle::new_stub(),
453            &keypair,
454        )
455        .await;
456        if let Ok(randomness_manager) = randomness_manager {
457            // Randomness might fail if test configuration does not permit DKG init.
458            // In that case, skip setting it up.
459            epoch_store
460                .set_randomness_manager(randomness_manager)
461                .await
462                .unwrap();
463        }
464
465        if !self.disable_execute_genesis_transactions {
466            // For any type of local testing that does not actually spawn a node, the
467            // checkpoint executor won't be started, which means we won't actually
468            // execute the genesis transaction. In that case, the genesis objects
469            // (e.g. all the genesis test coins) won't be accessible. Executing it
470            // explicitly makes sure all genesis objects are ready for use.
471            state
472                .try_execute_immediately(
473                    &VerifiedExecutableTransaction::new_from_checkpoint(
474                        VerifiedTransaction::new_unchecked(genesis.transaction().clone()),
475                        genesis.epoch(),
476                        genesis.checkpoint().sequence_number,
477                    ),
478                    ExecutionEnv::new(),
479                    &state.epoch_store_for_testing(),
480                )
481                .unwrap();
482
483            let batch = state.get_cache_commit().build_db_batch(
484                epoch_store.epoch(),
485                genesis.checkpoint().sequence_number,
486                &[*genesis.transaction().digest()],
487            );
488
489            state.get_cache_commit().commit_transaction_outputs(
490                epoch_store.epoch(),
491                batch,
492                &[*genesis.transaction().digest()],
493            );
494        }
495
496        // We want to insert these objects directly instead of relying on genesis
497        // because genesis process would set the previous transaction field for
498        // these objects, which would change their object digest. This makes it
499        // difficult to write tests that want to use these objects directly.
500        // TODO: we should probably have a better way to do this.
501        if let Some(starting_objects) = self.starting_objects {
502            state
503                .insert_objects_unsafe_for_testing_only(starting_objects)
504                .await;
505        };
506        state
507    }
508}