Skip to main content

iota_types/
messages_checkpoint.rs

1// Copyright (c) Mysten Labs, Inc.
2// Modifications Copyright (c) 2024 IOTA Stiftung
3// SPDX-License-Identifier: Apache-2.0
4
5use std::{
6    slice::Iter,
7    time::{Duration, SystemTime, UNIX_EPOCH},
8};
9
10use anyhow::Result;
11use fastcrypto::hash::MultisetHash;
12use iota_protocol_config::ProtocolConfig;
13use iota_sdk_types::{
14    CheckpointContents, CheckpointContentsDigest, CheckpointContentsV1, CheckpointDigest,
15    CheckpointSummary, CheckpointTransactionInfo, Digest, EndOfEpochData, GasCostSummary,
16    RandomnessRound, Transaction,
17    crypto::{Intent, IntentScope, UserSignature},
18};
19#[cfg(not(target_arch = "wasm32"))]
20use prometheus_filtered::Histogram;
21use serde::{Deserialize, Serialize};
22#[cfg(not(target_arch = "wasm32"))]
23use tap::TapFallible;
24use tracing::instrument;
25#[cfg(not(target_arch = "wasm32"))]
26use tracing::warn;
27
28use crate::{
29    attestation::{AttestationEntry, AttestationTotals},
30    base_types::{ExecutionData, ExecutionDigests, VerifiedExecutionData, random_object_ref},
31    committee::{Committee, EpochId},
32    crypto::{
33        AccountPrivateKey, AggregateAuthoritySignature, AuthoritySignInfo, AuthoritySignInfoTrait,
34        AuthorityStrongQuorumSignInfo, VerificationObligation, default_hash, get_key_pair,
35        zero_ed25519_signature,
36    },
37    effects::{TestEffectsBuilder, TransactionEffectsAPI},
38    error::{IotaError, IotaResult},
39    global_state_hash::GlobalStateHash,
40    message_envelope::{Envelope, Message, TrustedEnvelope, VerifiedEnvelope},
41    storage::ReadStore,
42    transaction::{TransactionAPI, TransactionEnvelope},
43};
44
45pub type CheckpointSequenceNumber = u64;
46pub type CheckpointTimestamp = u64;
47
48#[derive(Clone, Debug, Serialize, Deserialize)]
49pub struct CheckpointRequest {
50    /// if a sequence number is specified, return the checkpoint with that
51    /// sequence number; otherwise if None returns the latest checkpoint
52    /// stored (authenticated or pending, depending on the value of
53    /// `certified` flag)
54    pub sequence_number: Option<CheckpointSequenceNumber>,
55    // A flag, if true also return the contents of the
56    // checkpoint besides the meta-data.
57    pub request_content: bool,
58    // If true, returns certified checkpoint, otherwise returns pending checkpoint
59    pub certified: bool,
60}
61
62#[expect(clippy::large_enum_variant)]
63#[derive(Clone, Debug, Serialize, Deserialize)]
64pub enum CheckpointSummaryResponse {
65    Certified(CertifiedCheckpointSummary),
66    Pending(CheckpointSummary),
67}
68
69impl CheckpointSummaryResponse {
70    pub fn contents_digest(&self) -> CheckpointContentsDigest {
71        match self {
72            Self::Certified(s) => s.contents_digest,
73            Self::Pending(s) => s.contents_digest,
74        }
75    }
76}
77
78#[derive(Clone, Debug, Serialize, Deserialize)]
79pub struct CheckpointResponse {
80    pub checkpoint: Option<CheckpointSummaryResponse>,
81    pub contents: Option<CheckpointContents>,
82}
83
84// The constituent parts of checkpoints, signed and certified
85
86/// The Sha256 digest of an EllipticCurveMultisetHash committing to the live
87/// object set.
88#[derive(Clone, Debug, Serialize, Deserialize, PartialEq, Eq)]
89pub struct ECMHLiveObjectSetDigest {
90    pub digest: Digest,
91}
92
93impl From<fastcrypto::hash::Digest<32>> for ECMHLiveObjectSetDigest {
94    fn from(digest: fastcrypto::hash::Digest<32>) -> Self {
95        Self {
96            digest: Digest::new(digest.digest),
97        }
98    }
99}
100
101impl Default for ECMHLiveObjectSetDigest {
102    fn default() -> Self {
103        GlobalStateHash::default().digest().into()
104    }
105}
106
107impl Message for CheckpointSummary {
108    type DigestType = CheckpointDigest;
109    const SCOPE: IntentScope = IntentScope::CheckpointSummary;
110
111    fn digest(&self) -> Self::DigestType {
112        CheckpointDigest::new(default_hash(self))
113    }
114}
115
116mod checkpoint_summary_ext {
117    pub trait Sealed {}
118    impl Sealed for super::CheckpointSummary {}
119}
120
121/// Node-only helpers for [`CheckpointSummary`], which is defined in
122/// `iota_sdk_types`. These live on an extension trait because inherent methods
123/// cannot be added to a type that is foreign to this crate.
124pub trait CheckpointSummaryExt: Sized + checkpoint_summary_ext::Sealed {
125    /// `attestation_entries` are the attestation records other than `Valid`,
126    /// each at its transaction's position in `transactions`, and
127    /// `attestation_totals` the epoch's totals through this checkpoint. Both
128    /// are certified from summary version 2 on and ignored before.
129    ///
130    /// # Panics
131    ///
132    /// Under summary version 2, if an entry lies outside `transactions`.
133    fn new_with_protocol_config(
134        protocol_config: &ProtocolConfig,
135        epoch: EpochId,
136        sequence_number: CheckpointSequenceNumber,
137        network_total_transactions: u64,
138        transactions: &CheckpointContents,
139        previous_digest: Option<CheckpointDigest>,
140        epoch_rolling_gas_cost_summary: GasCostSummary,
141        end_of_epoch_data: Option<EndOfEpochData>,
142        timestamp_ms: CheckpointTimestamp,
143        randomness_rounds: Vec<RandomnessRound>,
144        attestation_entries: Vec<AttestationEntry>,
145        attestation_totals: AttestationTotals,
146    ) -> Self;
147
148    fn verify_epoch(&self, epoch: EpochId) -> IotaResult;
149
150    fn timestamp(&self) -> SystemTime;
151
152    #[cfg(not(target_arch = "wasm32"))]
153    fn report_checkpoint_age(&self, metrics: &Histogram);
154
155    fn parse_version_specific_data(
156        &self,
157        config: &ProtocolConfig,
158    ) -> Result<Option<CheckpointVersionSpecificData>>;
159}
160
161impl CheckpointSummaryExt for CheckpointSummary {
162    fn new_with_protocol_config(
163        protocol_config: &ProtocolConfig,
164        epoch: EpochId,
165        sequence_number: CheckpointSequenceNumber,
166        network_total_transactions: u64,
167        transactions: &CheckpointContents,
168        previous_digest: Option<CheckpointDigest>,
169        epoch_rolling_gas_cost_summary: GasCostSummary,
170        end_of_epoch_data: Option<EndOfEpochData>,
171        timestamp_ms: CheckpointTimestamp,
172        randomness_rounds: Vec<RandomnessRound>,
173        attestation_entries: Vec<AttestationEntry>,
174        attestation_totals: AttestationTotals,
175    ) -> Self {
176        let contents_digest = transactions.digest();
177
178        let version_specific_data =
179            match protocol_config.checkpoint_summary_version_specific_data_as_option() {
180                None | Some(0) => Vec::new(),
181                Some(1) => bcs::to_bytes(&CheckpointVersionSpecificData::V1(
182                    CheckpointVersionSpecificDataV1 { randomness_rounds },
183                ))
184                .expect("version specific data should serialize"),
185                Some(2) => {
186                    assert!(
187                        attestation_entries
188                            .iter()
189                            .all(|entry| (entry.position as usize) < transactions.len()),
190                        "attestation entries lie within the checkpoint"
191                    );
192                    bcs::to_bytes(&CheckpointVersionSpecificData::V2(
193                        CheckpointVersionSpecificDataV2 {
194                            randomness_rounds,
195                            attestation_entries,
196                            attestation_totals,
197                        },
198                    ))
199                    .expect("version specific data should serialize")
200                }
201                _ => unimplemented!(
202                    "unrecognized version_specific_data version for
203    CheckpointSummary"
204                ),
205            };
206
207        Self {
208            epoch,
209            sequence_number,
210            network_total_transactions,
211            contents_digest,
212            previous_digest,
213            epoch_rolling_gas_cost_summary,
214            end_of_epoch_data,
215            timestamp_ms,
216            version_specific_data,
217            checkpoint_commitments: Default::default(),
218        }
219    }
220
221    fn verify_epoch(&self, epoch: EpochId) -> IotaResult {
222        fp_ensure!(
223            self.epoch == epoch,
224            IotaError::WrongEpoch {
225                expected_epoch: epoch,
226                actual_epoch: self.epoch,
227            }
228        );
229        Ok(())
230    }
231
232    fn timestamp(&self) -> SystemTime {
233        UNIX_EPOCH + Duration::from_millis(self.timestamp_ms)
234    }
235
236    #[cfg(not(target_arch = "wasm32"))]
237    fn report_checkpoint_age(&self, metrics: &Histogram) {
238        SystemTime::now()
239            .duration_since(self.timestamp())
240            .map(|latency| {
241                metrics.observe(latency.as_secs_f64());
242            })
243            .tap_err(|err| {
244                warn!(
245                    checkpoint_seq = self.sequence_number,
246                    "unable to compute checkpoint age: {}", err
247                )
248            })
249            .ok();
250    }
251
252    fn parse_version_specific_data(
253        &self,
254        config: &ProtocolConfig,
255    ) -> Result<Option<CheckpointVersionSpecificData>> {
256        match config.checkpoint_summary_version_specific_data_as_option() {
257            None | Some(0) => Ok(None),
258            Some(1) | Some(2) => Ok(Some(bcs::from_bytes(&self.version_specific_data)?)),
259            _ => unimplemented!("unrecognized version_specific_data version in CheckpointSummary"),
260        }
261    }
262}
263
264// Checkpoints are signed by an authority and 2f+1 form a
265// certificate that others can use to catch up. The actual
266// content of the digest must at the very least commit to
267// the set of transactions contained in the certificate but
268// we might extend this to contain roots of merkle trees,
269// or other authenticated data structures to support light
270// clients and more efficient sync protocols.
271
272pub type CheckpointSummaryEnvelope<S> = Envelope<CheckpointSummary, S>;
273pub type CertifiedCheckpointSummary = CheckpointSummaryEnvelope<AuthorityStrongQuorumSignInfo>;
274pub type SignedCheckpointSummary = CheckpointSummaryEnvelope<AuthoritySignInfo>;
275
276pub type VerifiedCheckpoint = VerifiedEnvelope<CheckpointSummary, AuthorityStrongQuorumSignInfo>;
277pub type TrustedCheckpoint = TrustedEnvelope<CheckpointSummary, AuthorityStrongQuorumSignInfo>;
278
279impl CertifiedCheckpointSummary {
280    #[instrument(level = "trace", skip_all)]
281    pub fn verify_authority_signatures(&self, committee: &Committee) -> IotaResult {
282        self.data().verify_epoch(self.auth_sig().epoch)?;
283        self.auth_sig().verify_secure(
284            self.data(),
285            Intent::iota_app(IntentScope::CheckpointSummary),
286            committee,
287        )
288    }
289
290    /// Verifies the authority signatures of `summaries`, all certified by
291    /// `committee`, in a single batched signature verification. Cheaper than
292    /// verifying each summary on its own, at the cost of not saying which
293    /// summary failed; callers that need that can fall back to
294    /// [`Self::verify_authority_signatures`] per summary.
295    #[instrument(level = "trace", skip_all)]
296    pub fn batch_verify_authority_signatures(
297        summaries: &[Self],
298        committee: &Committee,
299    ) -> IotaResult {
300        let mut obligation = VerificationObligation::default();
301        for summary in summaries {
302            summary.data().verify_epoch(summary.auth_sig().epoch)?;
303            let idx = obligation.add_message(
304                summary.data(),
305                summary.auth_sig().epoch,
306                Intent::iota_app(IntentScope::CheckpointSummary),
307            );
308            summary
309                .auth_sig()
310                .add_to_verification_obligation(committee, &mut obligation, idx)?;
311        }
312        obligation.verify_all()
313    }
314
315    pub fn try_into_verified(self, committee: &Committee) -> IotaResult<VerifiedCheckpoint> {
316        self.verify_authority_signatures(committee)?;
317        Ok(VerifiedCheckpoint::new_from_verified(self))
318    }
319
320    pub fn verify_with_contents(
321        &self,
322        committee: &Committee,
323        contents: Option<&CheckpointContents>,
324    ) -> IotaResult {
325        self.verify_authority_signatures(committee)?;
326
327        if let Some(contents) = contents {
328            let contents_digest = contents.digest();
329            fp_ensure!(
330                contents_digest == self.data().contents_digest,
331                IotaError::GenericAuthority {
332                    error: format!(
333                        "Checkpoint contents digest mismatch: summary={:?}, received content digest {:?}, received {} transactions",
334                        self.data(),
335                        contents_digest,
336                        contents.len()
337                    )
338                }
339            );
340        }
341
342        Ok(())
343    }
344
345    pub fn into_summary_and_sequence(self) -> (CheckpointSequenceNumber, CheckpointSummary) {
346        let summary = self.into_data();
347        (summary.sequence_number, summary)
348    }
349
350    pub fn get_validator_signature(self) -> AggregateAuthoritySignature {
351        self.auth_sig().signature.clone()
352    }
353}
354
355impl SignedCheckpointSummary {
356    #[instrument(level = "trace", skip_all)]
357    pub fn verify_authority_signatures(&self, committee: &Committee) -> IotaResult {
358        self.data().verify_epoch(self.auth_sig().epoch)?;
359        self.auth_sig().verify_secure(
360            self.data(),
361            Intent::iota_app(IntentScope::CheckpointSummary),
362            committee,
363        )
364    }
365
366    pub fn try_into_verified(
367        self,
368        committee: &Committee,
369    ) -> IotaResult<VerifiedEnvelope<CheckpointSummary, AuthoritySignInfo>> {
370        self.verify_authority_signatures(committee)?;
371        Ok(VerifiedEnvelope::<CheckpointSummary, AuthoritySignInfo>::new_from_verified(self))
372    }
373}
374
375impl VerifiedCheckpoint {
376    pub fn into_summary_and_sequence(self) -> (CheckpointSequenceNumber, CheckpointSummary) {
377        self.into_inner().into_summary_and_sequence()
378    }
379}
380
381/// This is a message validators publish to consensus in order to sign
382/// checkpoint
383#[derive(Clone, Debug, Serialize, Deserialize)]
384pub struct CheckpointSignatureMessage {
385    pub summary: SignedCheckpointSummary,
386}
387
388impl CheckpointSignatureMessage {
389    pub fn verify(&self, committee: &Committee) -> IotaResult {
390        self.summary.verify_authority_signatures(committee)
391    }
392}
393
394fn execution_digests(info: &CheckpointTransactionInfo) -> ExecutionDigests {
395    ExecutionDigests {
396        transaction: info.transaction,
397        effects: info.effects,
398    }
399}
400
401mod checkpoint_contents_ext {
402    pub trait Sealed {}
403    impl Sealed for super::CheckpointContents {}
404}
405
406/// Node-only helpers for [`CheckpointContents`], which is defined in
407/// `iota_sdk_types`. They bridge the node's `ExecutionDigests` representation
408/// to the SDK type's parallel [`CheckpointTransactionInfo`] form.
409pub trait CheckpointContentsExt: Sized + checkpoint_contents_ext::Sealed {
410    fn new_with_digests_and_signatures(
411        contents: impl IntoIterator<Item = ExecutionDigests>,
412        user_signatures: Vec<Vec<UserSignature>>,
413    ) -> Self;
414
415    fn new_with_causally_ordered_execution_data<'a>(
416        contents: impl IntoIterator<Item = &'a VerifiedExecutionData>,
417    ) -> Self;
418
419    fn new_with_digests_only_for_tests(
420        contents: impl IntoIterator<Item = ExecutionDigests>,
421    ) -> Self;
422
423    fn iter(&self) -> impl DoubleEndedIterator<Item = ExecutionDigests> + ExactSizeIterator + '_;
424
425    fn into_iter_with_signatures(
426        self,
427    ) -> impl Iterator<Item = (ExecutionDigests, Vec<UserSignature>)>;
428
429    /// Enumerate the transactions in the contents, pairing each with its index
430    /// in the global ordering of executed transactions since genesis.
431    fn enumerate_transactions(
432        &self,
433        ckpt: &CheckpointSummary,
434    ) -> impl Iterator<Item = (u64, ExecutionDigests)> + '_;
435}
436
437impl CheckpointContentsExt for CheckpointContents {
438    fn new_with_digests_and_signatures(
439        contents: impl IntoIterator<Item = ExecutionDigests>,
440        user_signatures: Vec<Vec<UserSignature>>,
441    ) -> Self {
442        let transactions: Vec<_> = contents.into_iter().collect();
443        assert_eq!(transactions.len(), user_signatures.len());
444        Self::new_v1(CheckpointContentsV1::new(
445            transactions
446                .into_iter()
447                .zip(user_signatures)
448                .map(|(digests, signatures)| CheckpointTransactionInfo {
449                    transaction: digests.transaction,
450                    effects: digests.effects,
451                    signatures,
452                })
453                .collect(),
454        ))
455    }
456
457    fn new_with_causally_ordered_execution_data<'a>(
458        contents: impl IntoIterator<Item = &'a VerifiedExecutionData>,
459    ) -> Self {
460        Self::new_v1(CheckpointContentsV1::new(
461            contents
462                .into_iter()
463                .map(|data| {
464                    let digests = data.digests();
465                    CheckpointTransactionInfo {
466                        transaction: digests.transaction,
467                        effects: digests.effects,
468                        signatures: data.transaction.inner().data().signatures().to_owned(),
469                    }
470                })
471                .collect(),
472        ))
473    }
474
475    fn new_with_digests_only_for_tests(
476        contents: impl IntoIterator<Item = ExecutionDigests>,
477    ) -> Self {
478        Self::new_v1(CheckpointContentsV1::new(
479            contents
480                .into_iter()
481                .map(|digests| CheckpointTransactionInfo {
482                    transaction: digests.transaction,
483                    effects: digests.effects,
484                    signatures: Vec::new(),
485                })
486                .collect(),
487        ))
488    }
489
490    fn iter(&self) -> impl DoubleEndedIterator<Item = ExecutionDigests> + ExactSizeIterator + '_ {
491        self.transactions().iter().map(execution_digests)
492    }
493
494    fn into_iter_with_signatures(
495        self,
496    ) -> impl Iterator<Item = (ExecutionDigests, Vec<UserSignature>)> {
497        match self {
498            CheckpointContents::V1(v1) => v1.into_transactions().into_iter().map(|info| {
499                let digests = execution_digests(&info);
500                (digests, info.signatures)
501            }),
502            _ => unimplemented!("a new CheckpointContents variant was added and must be handled"),
503        }
504    }
505
506    fn enumerate_transactions(
507        &self,
508        ckpt: &CheckpointSummary,
509    ) -> impl Iterator<Item = (u64, ExecutionDigests)> + '_ {
510        let start = ckpt.network_total_transactions - self.len() as u64;
511
512        (0u64..)
513            .zip(self.iter())
514            .map(move |(i, digests)| (i + start, digests))
515    }
516}
517
518/// Same as CheckpointContents, but contains full contents of all Transactions
519/// and TransactionEffects associated with the checkpoint.
520// NOTE: This data structure is used for state sync of checkpoints. Therefore we attempt
521// to estimate its size in CheckpointBuilder in order to limit the maximum serialized
522// size of a checkpoint sent over the network. If this struct is modified,
523// CheckpointBuilder::split_checkpoint_chunks should also be updated accordingly.
524#[derive(Clone, Debug, PartialEq, Eq, Serialize, Deserialize)]
525#[serde(try_from = "RawFullCheckpointContents")]
526pub struct FullCheckpointContents {
527    transactions: Vec<ExecutionData>,
528    /// The signatures the checkpoint pins for each transaction, in the same
529    /// order and number as `transactions`. The checkpoint contents digest
530    /// covers them, unlike the signatures inside the transactions, and they
531    /// differ from those for system transactions: the ones the node builds
532    /// outside consensus, at genesis and at the end of an epoch, are pinned
533    /// with an empty set while their envelopes carry a zero placeholder
534    /// signature.
535    user_signatures: Vec<Vec<UserSignature>>,
536}
537
538/// The wire shape of [`FullCheckpointContents`]. Deserialization goes through
539/// it so that the two vectors are known to be the same length before a
540/// [`FullCheckpointContents`] value exists.
541#[derive(Deserialize)]
542struct RawFullCheckpointContents {
543    transactions: Vec<ExecutionData>,
544    user_signatures: Vec<Vec<UserSignature>>,
545}
546
547impl TryFrom<RawFullCheckpointContents> for FullCheckpointContents {
548    type Error = anyhow::Error;
549
550    fn try_from(raw: RawFullCheckpointContents) -> Result<Self> {
551        fp_ensure!(
552            raw.transactions.len() == raw.user_signatures.len(),
553            anyhow::anyhow!(
554                "checkpoint contents hold {} transactions but {} pinned signature sets",
555                raw.transactions.len(),
556                raw.user_signatures.len()
557            )
558        );
559        Ok(Self {
560            transactions: raw.transactions,
561            user_signatures: raw.user_signatures,
562        })
563    }
564}
565
566impl FullCheckpointContents {
567    pub fn new_with_causally_ordered_transactions<T>(contents: T) -> Self
568    where
569        T: IntoIterator<Item = ExecutionData>,
570    {
571        let (transactions, user_signatures): (Vec<_>, Vec<_>) = contents
572            .into_iter()
573            .map(|data| {
574                let sig = data.transaction.data().signatures().to_owned();
575                (data, sig)
576            })
577            .unzip();
578        assert_eq!(transactions.len(), user_signatures.len());
579        Self {
580            transactions,
581            user_signatures,
582        }
583    }
584
585    /// Pairs the signatures pinned in `contents` with `execution_data`.
586    ///
587    /// # Errors
588    ///
589    /// Returns an error when `execution_data` does not hold exactly one
590    /// transaction per entry of `contents`, so a caller assembling the two
591    /// from separately received parts gets a rejection rather than a panic.
592    pub fn from_contents_and_execution_data(
593        contents: CheckpointContents,
594        execution_data: impl Iterator<Item = ExecutionData>,
595    ) -> Result<Self> {
596        let transactions: Vec<_> = execution_data.collect();
597        let user_signatures: Vec<Vec<UserSignature>> = contents
598            .into_iter_with_signatures()
599            .map(|(_, signatures)| signatures)
600            .collect();
601        fp_ensure!(
602            transactions.len() == user_signatures.len(),
603            anyhow::anyhow!(
604                "checkpoint contents pin {} signature sets for {} transactions",
605                user_signatures.len(),
606                transactions.len()
607            )
608        );
609        Ok(Self {
610            transactions,
611            user_signatures,
612        })
613    }
614
615    /// Pairs the signatures pinned in `contents` with transactions from this
616    /// node's own store, and puts the pinned signatures on each transaction
617    /// the checkpoint pins signatures for, except where the stored or the
618    /// pinned signatures hold a `MoveAuthenticator`; those are left as stored,
619    /// so the contents fail [`Self::verify`] if the two copies differ.
620    ///
621    /// Only for transactions this node stored itself. Contents received from
622    /// elsewhere must pass [`Self::verify`] as received.
623    ///
624    /// # Errors
625    ///
626    /// Returns an error when `execution_data` does not hold exactly one
627    /// transaction per entry of `contents`.
628    pub fn from_contents_and_local_execution_data(
629        contents: CheckpointContents,
630        execution_data: impl Iterator<Item = ExecutionData>,
631    ) -> Result<Self> {
632        let mut full_contents = Self::from_contents_and_execution_data(contents, execution_data)?;
633        for (execution_data, pinned_signatures) in full_contents
634            .transactions
635            .iter_mut()
636            .zip(&full_contents.user_signatures)
637        {
638            let stored_signatures = execution_data.transaction.data().signatures();
639            // Genesis and end-of-epoch transactions pin no signatures and keep
640            // their placeholder.
641            if !pinned_signatures.is_empty()
642                && stored_signatures != pinned_signatures.as_slice()
643                // A `MoveAuthenticator` decides part of what the transaction
644                // executes and can read the digests of the other signatures, so
645                // with one in either copy the stored copy's effects might not
646                // match the pinned one. Only checkpoints before protocol version
647                // 36 can hold such a pair: from that version the account object
648                // must be shared, so the transaction is ordered by consensus and
649                // every node executes the copy consensus sequenced.
650                && !stored_signatures
651                    .iter()
652                    .chain(pinned_signatures)
653                    .any(UserSignature::is_move_authenticator)
654            {
655                execution_data.transaction = TransactionEnvelope::from_user_sig_data(
656                    execution_data.transaction.data().transaction().clone(),
657                    pinned_signatures.clone(),
658                );
659            }
660        }
661        Ok(full_contents)
662    }
663
664    pub fn try_from_checkpoint_contents<S>(
665        store: S,
666        contents: CheckpointContents,
667    ) -> Result<Option<Self>, crate::storage::error::Error>
668    where
669        S: ReadStore,
670    {
671        let (digests, user_signatures): (Vec<_>, Vec<_>) =
672            contents.into_iter_with_signatures().unzip();
673        let mut transactions = Vec::with_capacity(digests.len());
674        for tx in &digests {
675            if let (Some(t), Some(e)) = (
676                store.try_get_transaction(&tx.transaction)?,
677                store.try_get_transaction_effects(&tx.transaction)?,
678            ) {
679                transactions.push(ExecutionData::new((*t).clone().into_inner(), e))
680            } else {
681                return Ok(None);
682            }
683        }
684        Ok(Some(Self {
685            transactions,
686            user_signatures,
687        }))
688    }
689
690    pub fn iter(&self) -> Iter<'_, ExecutionData> {
691        self.transactions.iter()
692    }
693
694    /// Verifies that this checkpoint's digest matches the given digest, that
695    /// all internal Transaction and TransactionEffects digests are consistent,
696    /// and that every transaction carries the signatures the checkpoint pinned.
697    ///
698    /// The transactions and the signatures pinned for them are separate fields,
699    /// and the transaction digest does not cover the signatures, so a peer can
700    /// serve a transaction whose signatures differ from the ones the committee
701    /// agreed on without changing any digest. That matters for a transaction
702    /// authenticated by a `MoveAuthenticator`, whose payload decides what the
703    /// transaction executes.
704    pub fn verify_digests(&self, digest: CheckpointContentsDigest) -> Result<()> {
705        fp_ensure!(
706            self.transactions.len() == self.user_signatures.len(),
707            anyhow::anyhow!(
708                "checkpoint contents hold {} transactions but {} pinned signature sets",
709                self.transactions.len(),
710                self.user_signatures.len()
711            )
712        );
713
714        let self_digest = self.checkpoint_contents().digest();
715        fp_ensure!(
716            digest == self_digest,
717            anyhow::anyhow!(
718                "checkpoint contents digest {self_digest} does not match expected digest {digest}"
719            )
720        );
721        let placeholder_signature = [UserSignature::Simple(zero_ed25519_signature())];
722        for (tx, pinned_signatures) in self.transactions.iter().zip(self.user_signatures.iter()) {
723            let transaction_digest = tx.transaction.digest();
724            fp_ensure!(
725                tx.effects.transaction_digest() == transaction_digest,
726                anyhow::anyhow!(
727                    "transaction digest {transaction_digest} does not match expected digest {}",
728                    tx.effects.transaction_digest()
729                )
730            );
731            // Genesis and end-of-epoch transactions are the two the node builds
732            // outside consensus, and the checkpoint pins no signatures for
733            // them, while their envelopes carry the zero placeholder every
734            // system transaction is built with. For those two the placeholder
735            // is the reference; everything else must match what was pinned.
736            let transaction = tx.transaction.data().transaction();
737            let expected_signatures: &[UserSignature] = if pinned_signatures.is_empty()
738                && (transaction.is_genesis_tx() || transaction.is_end_of_epoch_tx())
739            {
740                &placeholder_signature
741            } else {
742                pinned_signatures.as_slice()
743            };
744            fp_ensure!(
745                tx.transaction.data().signatures() == expected_signatures,
746                anyhow::anyhow!(
747                    "transaction {transaction_digest} does not carry the signatures pinned by the checkpoint contents"
748                )
749            );
750        }
751        Ok(())
752    }
753
754    /// Verifies the contents against `digest` and, when they pass, hands them
755    /// back as verified. Contents received from a peer must go through here:
756    /// it is the only way to obtain a [`VerifiedCheckpointContents`] from
757    /// untrusted data.
758    pub fn verify(self, digest: CheckpointContentsDigest) -> Result<VerifiedCheckpointContents> {
759        self.verify_digests(digest)?;
760        Ok(VerifiedCheckpointContents::new_unchecked(self))
761    }
762
763    pub fn checkpoint_contents(&self) -> CheckpointContents {
764        CheckpointContents::new_with_digests_and_signatures(
765            self.transactions.iter().map(|tx| tx.digests()),
766            self.user_signatures.clone(),
767        )
768    }
769
770    pub fn into_checkpoint_contents(self) -> CheckpointContents {
771        let digests: Vec<_> = self.transactions.iter().map(|tx| tx.digests()).collect();
772        CheckpointContents::new_with_digests_and_signatures(digests, self.user_signatures)
773    }
774
775    pub fn size(&self) -> usize {
776        self.transactions.len()
777    }
778
779    pub fn random_for_testing() -> Self {
780        let (a, key): (_, AccountPrivateKey) = get_key_pair();
781        let transaction = TransactionEnvelope::from_data_and_signer(
782            Transaction::new_transfer(
783                a,
784                random_object_ref(),
785                a,
786                random_object_ref(),
787                100000000000,
788                100,
789            ),
790            vec![&key],
791        );
792        let effects = TestEffectsBuilder::new(transaction.data()).build();
793        let exe_data = ExecutionData {
794            transaction,
795            effects,
796        };
797        FullCheckpointContents::new_with_causally_ordered_transactions(vec![exe_data])
798    }
799}
800
801impl IntoIterator for FullCheckpointContents {
802    type Item = ExecutionData;
803    type IntoIter = std::vec::IntoIter<Self::Item>;
804
805    fn into_iter(self) -> Self::IntoIter {
806        self.transactions.into_iter()
807    }
808}
809
810#[derive(Clone, Debug, PartialEq, Eq)]
811pub struct VerifiedCheckpointContents {
812    transactions: Vec<VerifiedExecutionData>,
813    /// The signatures the checkpoint pins for each transaction, in the same
814    /// order and number as `transactions`. The checkpoint contents digest
815    /// covers them, unlike the signatures inside the transactions, and they
816    /// differ from those for system transactions: the ones the node builds
817    /// outside consensus, at genesis and at the end of an epoch, are pinned
818    /// with an empty set while their envelopes carry a zero placeholder
819    /// signature.
820    user_signatures: Vec<Vec<UserSignature>>,
821}
822
823impl VerifiedCheckpointContents {
824    /// Wraps contents without verifying them. Only for contents the node built
825    /// itself; anything received from a peer goes through
826    /// [`FullCheckpointContents::verify`].
827    pub fn new_unchecked(contents: FullCheckpointContents) -> Self {
828        Self {
829            transactions: contents
830                .transactions
831                .into_iter()
832                .map(VerifiedExecutionData::new_unchecked)
833                .collect(),
834            user_signatures: contents.user_signatures,
835        }
836    }
837
838    pub fn iter(&self) -> Iter<'_, VerifiedExecutionData> {
839        self.transactions.iter()
840    }
841
842    pub fn transactions(&self) -> &[VerifiedExecutionData] {
843        &self.transactions
844    }
845
846    pub fn into_inner(self) -> FullCheckpointContents {
847        FullCheckpointContents {
848            transactions: self
849                .transactions
850                .into_iter()
851                .map(|tx| tx.into_inner())
852                .collect(),
853            user_signatures: self.user_signatures,
854        }
855    }
856
857    pub fn into_checkpoint_contents(self) -> CheckpointContents {
858        self.into_inner().into_checkpoint_contents()
859    }
860
861    pub fn into_checkpoint_contents_digest(self) -> CheckpointContentsDigest {
862        self.into_inner().into_checkpoint_contents().digest()
863    }
864
865    pub fn num_of_transactions(&self) -> usize {
866        self.transactions.len()
867    }
868}
869
870/// Holds data in CheckpointSummary that is serialized into the
871/// `version_specific_data` field.
872#[derive(Clone, Debug, PartialEq, Eq, Serialize, Deserialize)]
873pub enum CheckpointVersionSpecificData {
874    V1(CheckpointVersionSpecificDataV1),
875    V2(CheckpointVersionSpecificDataV2),
876}
877
878impl CheckpointVersionSpecificData {
879    pub fn randomness_rounds(&self) -> &[RandomnessRound] {
880        match self {
881            Self::V1(v) => &v.randomness_rounds,
882            Self::V2(v) => &v.randomness_rounds,
883        }
884    }
885
886    /// Empty for V1.
887    pub fn attestation_entries(&self) -> &[AttestationEntry] {
888        match self {
889            Self::V1(_) => &[],
890            Self::V2(v) => &v.attestation_entries,
891        }
892    }
893
894    /// `None` for V1.
895    pub fn attestation_totals(&self) -> Option<&AttestationTotals> {
896        match self {
897            Self::V1(_) => None,
898            Self::V2(v) => Some(&v.attestation_totals),
899        }
900    }
901
902    pub fn empty_for_tests() -> CheckpointVersionSpecificData {
903        CheckpointVersionSpecificData::V1(CheckpointVersionSpecificDataV1 {
904            randomness_rounds: Vec::new(),
905        })
906    }
907}
908
909#[derive(Clone, Debug, Default, PartialEq, Eq, Serialize, Deserialize)]
910pub struct CheckpointVersionSpecificDataV1 {
911    /// Lists the rounds for which RandomnessStateUpdate transactions are
912    /// present in the checkpoint.
913    pub randomness_rounds: Vec<RandomnessRound>,
914}
915
916#[derive(Clone, Debug, Default, PartialEq, Eq, Serialize, Deserialize)]
917pub struct CheckpointVersionSpecificDataV2 {
918    /// Lists the rounds for which RandomnessStateUpdate transactions are
919    /// present in the checkpoint.
920    pub randomness_rounds: Vec<RandomnessRound>,
921    /// The attestation records other than `Valid`, each at its transaction's
922    /// position in checkpoint-contents order.
923    pub attestation_entries: Vec<AttestationEntry>,
924    /// The epoch's attestation totals through this checkpoint: the previous
925    /// summary's totals plus this checkpoint's `Refuted` records.
926    pub attestation_totals: AttestationTotals,
927}
928
929#[cfg(test)]
930mod tests {
931    use std::collections::BTreeMap;
932
933    use fastcrypto::traits::KeyPair;
934    use iota_sdk_types::{
935        ConsensusCommitDigest, ObjectId, TransactionDigest, TransactionEffectsDigest,
936        TransactionKind,
937    };
938    use rand::{SeedableRng, prelude::StdRng};
939
940    use super::*;
941    use crate::{
942        attestation::{AttestationRecord, AttestationVerdict},
943        object::OBJECT_START_VERSION,
944        transaction::VerifiedTransaction,
945        utils::make_committee_key,
946    };
947
948    // TODO use the file name as a seed
949    const RNG_SEED: [u8; 32] = [
950        21, 23, 199, 200, 234, 250, 252, 178, 94, 15, 202, 178, 62, 186, 88, 137, 233, 192, 130,
951        157, 179, 179, 65, 9, 31, 249, 221, 123, 225, 112, 199, 247,
952    ];
953
954    #[test]
955    fn test_signed_checkpoint() {
956        let mut rng = StdRng::from_seed(RNG_SEED);
957        let (keys, committee) = make_committee_key(&mut rng);
958        let (_, committee2) = make_committee_key(&mut rng);
959
960        let set = CheckpointContents::new_with_digests_only_for_tests([ExecutionDigests::random()]);
961
962        // TODO: duplicated in a test below.
963
964        let signed_checkpoints: Vec<_> = keys
965            .iter()
966            .map(|k| {
967                let name = k.public().into();
968
969                SignedCheckpointSummary::new(
970                    committee.epoch,
971                    CheckpointSummary::new_with_protocol_config(
972                        &ProtocolConfig::get_for_max_version_UNSAFE(),
973                        committee.epoch,
974                        1,
975                        0,
976                        &set,
977                        None,
978                        GasCostSummary::default(),
979                        None,
980                        0,
981                        Vec::new(),
982                        Vec::new(),
983                        AttestationTotals::default(),
984                    ),
985                    k,
986                    name,
987                )
988            })
989            .collect();
990
991        signed_checkpoints.iter().for_each(|c| {
992            c.verify_authority_signatures(&committee)
993                .expect("signature ok")
994        });
995
996        // fails when not signed by member of committee
997        signed_checkpoints
998            .iter()
999            .for_each(|c| assert!(c.verify_authority_signatures(&committee2).is_err()));
1000    }
1001
1002    #[test]
1003    fn test_certified_checkpoint() {
1004        let mut rng = StdRng::from_seed(RNG_SEED);
1005        let (keys, committee) = make_committee_key(&mut rng);
1006
1007        let set = CheckpointContents::new_with_digests_only_for_tests([ExecutionDigests::random()]);
1008
1009        let summary = CheckpointSummary::new_with_protocol_config(
1010            &ProtocolConfig::get_for_max_version_UNSAFE(),
1011            committee.epoch,
1012            1,
1013            0,
1014            &set,
1015            None,
1016            GasCostSummary::default(),
1017            None,
1018            0,
1019            Vec::new(),
1020            Vec::new(),
1021            AttestationTotals::default(),
1022        );
1023
1024        let sign_infos: Vec<_> = keys
1025            .iter()
1026            .map(|k| {
1027                let name = k.public().into();
1028
1029                SignedCheckpointSummary::sign(committee.epoch, &summary, k, name)
1030            })
1031            .collect();
1032
1033        let checkpoint_cert =
1034            CertifiedCheckpointSummary::new(summary, sign_infos, &committee).expect("Cert is OK");
1035
1036        // Signature is correct on proposal, and with same transactions
1037        assert!(
1038            checkpoint_cert
1039                .verify_with_contents(&committee, Some(&set))
1040                .is_ok()
1041        );
1042
1043        // Make a bad proposal
1044        let signed_checkpoints: Vec<_> = keys
1045            .iter()
1046            .map(|k| {
1047                let name = k.public().into();
1048                let set = CheckpointContents::new_with_digests_only_for_tests([
1049                    ExecutionDigests::random(),
1050                ]);
1051
1052                SignedCheckpointSummary::new(
1053                    committee.epoch,
1054                    CheckpointSummary::new_with_protocol_config(
1055                        &ProtocolConfig::get_for_max_version_UNSAFE(),
1056                        committee.epoch,
1057                        1,
1058                        0,
1059                        &set,
1060                        None,
1061                        GasCostSummary::default(),
1062                        None,
1063                        0,
1064                        Vec::new(),
1065                        Vec::new(),
1066                        AttestationTotals::default(),
1067                    ),
1068                    k,
1069                    name,
1070                )
1071            })
1072            .collect();
1073
1074        let summary = signed_checkpoints[0].data().clone();
1075        let sign_infos = signed_checkpoints
1076            .into_iter()
1077            .map(|v| v.into_sig())
1078            .collect();
1079        assert!(
1080            CertifiedCheckpointSummary::new(summary, sign_infos, &committee)
1081                .unwrap()
1082                .verify_authority_signatures(&committee)
1083                .is_err()
1084        )
1085    }
1086
1087    #[test]
1088    fn test_batch_verify_certified_checkpoints() {
1089        let mut rng = StdRng::from_seed(RNG_SEED);
1090        let (keys, committee) = make_committee_key(&mut rng);
1091
1092        let summary_for_sequence_number = |sequence_number| {
1093            let set =
1094                CheckpointContents::new_with_digests_only_for_tests([ExecutionDigests::random()]);
1095            CheckpointSummary::new_with_protocol_config(
1096                &ProtocolConfig::get_for_max_version_UNSAFE(),
1097                committee.epoch,
1098                sequence_number,
1099                0,
1100                &set,
1101                None,
1102                GasCostSummary::default(),
1103                None,
1104                0,
1105                Vec::new(),
1106                Vec::new(),
1107                AttestationTotals::default(),
1108            )
1109        };
1110        let certify = |summary: CheckpointSummary| {
1111            let sign_infos = keys
1112                .iter()
1113                .map(|k| {
1114                    SignedCheckpointSummary::sign(committee.epoch, &summary, k, k.public().into())
1115                })
1116                .collect();
1117            CertifiedCheckpointSummary::new(summary, sign_infos, &committee).expect("cert is OK")
1118        };
1119
1120        let summaries: Vec<_> = (1..=3)
1121            .map(|seq| certify(summary_for_sequence_number(seq)))
1122            .collect();
1123        CertifiedCheckpointSummary::batch_verify_authority_signatures(&summaries, &committee)
1124            .expect("signatures ok");
1125
1126        // A certificate whose signatures were made over a different summary
1127        // fails the batch.
1128        let mismatched = {
1129            let summary = summary_for_sequence_number(4);
1130            let sign_infos = keys
1131                .iter()
1132                .map(|k| {
1133                    SignedCheckpointSummary::sign(
1134                        committee.epoch,
1135                        &summary_for_sequence_number(4),
1136                        k,
1137                        k.public().into(),
1138                    )
1139                })
1140                .collect();
1141            CertifiedCheckpointSummary::new(summary, sign_infos, &committee).expect("cert is OK")
1142        };
1143        let with_mismatched: Vec<_> = summaries.into_iter().chain([mismatched]).collect();
1144        assert!(
1145            CertifiedCheckpointSummary::batch_verify_authority_signatures(
1146                &with_mismatched,
1147                &committee
1148            )
1149            .is_err()
1150        );
1151    }
1152
1153    // Generate a CheckpointSummary from the input transaction digest. All the other
1154    // fields in the generated CheckpointSummary will be the same. The generated
1155    // CheckpointSummary can be used to test how input transaction digest
1156    // affects CheckpointSummary.
1157    fn generate_test_checkpoint_summary_from_digest(
1158        digest: TransactionDigest,
1159    ) -> CheckpointSummary {
1160        CheckpointSummary::new_with_protocol_config(
1161            &ProtocolConfig::get_for_max_version_UNSAFE(),
1162            1,
1163            2,
1164            10,
1165            &CheckpointContents::new_with_digests_only_for_tests([ExecutionDigests::new(
1166                digest,
1167                TransactionEffectsDigest::ZERO,
1168            )]),
1169            None,
1170            GasCostSummary::default(),
1171            None,
1172            100,
1173            Vec::new(),
1174            Vec::new(),
1175            AttestationTotals::default(),
1176        )
1177    }
1178
1179    // Tests that ConsensusCommitPrologue with different consensus commit digest
1180    // will result in different checkpoint content.
1181    #[test]
1182    fn test_checkpoint_summary_with_different_consensus_digest() {
1183        // First, tests that same consensus commit digest will produce the same
1184        // checkpoint content.
1185        {
1186            let t1 = VerifiedTransaction::new_consensus_commit_prologue_v1(
1187                1,
1188                2,
1189                100,
1190                ConsensusCommitDigest::default(),
1191                Vec::new(),
1192            );
1193            let t2 = VerifiedTransaction::new_consensus_commit_prologue_v1(
1194                1,
1195                2,
1196                100,
1197                ConsensusCommitDigest::default(),
1198                Vec::new(),
1199            );
1200            let c1 = generate_test_checkpoint_summary_from_digest(*t1.digest());
1201            let c2 = generate_test_checkpoint_summary_from_digest(*t2.digest());
1202            assert_eq!(c1.digest(), c2.digest());
1203        }
1204
1205        // Next, tests that different consensus commit digests will produce the
1206        // different checkpoint contents.
1207        {
1208            let t1 = VerifiedTransaction::new_consensus_commit_prologue_v1(
1209                1,
1210                2,
1211                100,
1212                ConsensusCommitDigest::default(),
1213                Vec::new(),
1214            );
1215            let t2 = VerifiedTransaction::new_consensus_commit_prologue_v1(
1216                1,
1217                2,
1218                100,
1219                ConsensusCommitDigest::random(),
1220                Vec::new(),
1221            );
1222            let c1 = generate_test_checkpoint_summary_from_digest(*t1.digest());
1223            let c2 = generate_test_checkpoint_summary_from_digest(*t2.digest());
1224            assert_ne!(c1.digest(), c2.digest());
1225        }
1226    }
1227
1228    /// Contents built as served, plus a copy whose transaction was re-signed
1229    /// with a different key. The transaction digest is unchanged, so the
1230    /// contents digest is too; only the envelope's signatures differ.
1231    fn contents_with_a_swapped_envelope() -> (
1232        CheckpointContentsDigest,
1233        FullCheckpointContents,
1234        FullCheckpointContents,
1235    ) {
1236        let contents = FullCheckpointContents::random_for_testing();
1237        let digest = contents.checkpoint_contents().digest();
1238
1239        let (_, other_key): (_, AccountPrivateKey) = get_key_pair();
1240        let original = contents.transactions[0].transaction.clone();
1241        let swapped = TransactionEnvelope::from_data_and_signer(
1242            original.data().transaction().clone(),
1243            vec![&other_key],
1244        );
1245        assert_eq!(swapped.digest(), original.digest());
1246        assert_ne!(swapped.data().signatures(), original.data().signatures());
1247
1248        let mut tampered = contents.clone();
1249        tampered.transactions[0].transaction = swapped;
1250        assert_eq!(tampered.checkpoint_contents().digest(), digest);
1251
1252        (digest, contents, tampered)
1253    }
1254
1255    /// Contents built from a node's own copy of a transaction carry the pinned
1256    /// signatures, with the same transaction data and effects.
1257    #[test]
1258    fn local_execution_data_gets_the_pinned_signatures() {
1259        let (digest, contents, executed_copy) = contents_with_a_swapped_envelope();
1260
1261        let built = FullCheckpointContents::from_contents_and_local_execution_data(
1262            contents.checkpoint_contents(),
1263            executed_copy.into_iter(),
1264        )
1265        .unwrap();
1266
1267        assert_eq!(built, contents);
1268        built.verify_digests(digest).unwrap();
1269    }
1270
1271    /// An end-of-epoch transaction, which the checkpoint pins no signatures
1272    /// for, keeps its placeholder signature.
1273    #[test]
1274    fn local_execution_data_keeps_the_signatures_of_a_transaction_pinned_without_any() {
1275        let transaction = VerifiedTransaction::new_end_of_epoch_transaction(vec![]).into_inner();
1276        let effects = TestEffectsBuilder::new(transaction.data()).build();
1277        let execution_data = ExecutionData {
1278            transaction,
1279            effects,
1280        };
1281        let contents = CheckpointContents::new_with_digests_and_signatures(
1282            vec![execution_data.digests()],
1283            vec![vec![]],
1284        );
1285        let digest = contents.digest();
1286
1287        let built = FullCheckpointContents::from_contents_and_local_execution_data(
1288            contents,
1289            std::iter::once(execution_data.clone()),
1290        )
1291        .unwrap();
1292
1293        assert_eq!(built.transactions, vec![execution_data]);
1294        built.verify_digests(digest).unwrap();
1295    }
1296
1297    /// Copies with the same `MoveAuthenticator` that differ in their other
1298    /// signatures are left as stored: the authenticator can read the digests
1299    /// of the other signatures.
1300    #[test]
1301    fn local_execution_data_with_the_same_move_authenticator_keeps_the_stored_copy() {
1302        let (_, mut contents, mut executed_copy) = contents_with_a_swapped_envelope();
1303        let transaction = contents.transactions[0]
1304            .transaction
1305            .data()
1306            .transaction()
1307            .clone();
1308        let (authenticator, _) = crate::utils::make_move_authenticator_sig(transaction.sender());
1309        for full_contents in [&mut contents, &mut executed_copy] {
1310            let mut signatures = vec![authenticator.clone()];
1311            signatures.extend_from_slice(
1312                full_contents.transactions[0]
1313                    .transaction
1314                    .data()
1315                    .signatures(),
1316            );
1317            full_contents.transactions[0].transaction =
1318                TransactionEnvelope::from_user_sig_data(transaction.clone(), signatures.clone());
1319            full_contents.user_signatures[0] = signatures;
1320        }
1321        assert_ne!(contents.transactions, executed_copy.transactions);
1322
1323        let built = FullCheckpointContents::from_contents_and_local_execution_data(
1324            contents.checkpoint_contents(),
1325            executed_copy.clone().into_iter(),
1326        )
1327        .unwrap();
1328
1329        assert_eq!(built.transactions, executed_copy.transactions);
1330    }
1331
1332    /// A copy whose `MoveAuthenticator` differs from the pinned one is left as
1333    /// stored, whichever side has it.
1334    #[test]
1335    fn local_execution_data_keeps_a_move_authenticator() {
1336        let plain = FullCheckpointContents::random_for_testing();
1337        let transaction = plain.transactions[0]
1338            .transaction
1339            .data()
1340            .transaction()
1341            .clone();
1342        let (authenticator, _) = crate::utils::make_move_authenticator_sig(transaction.sender());
1343        let mut with_authenticator = plain.clone();
1344        with_authenticator.transactions[0].transaction =
1345            TransactionEnvelope::from_user_sig_data(transaction, vec![authenticator.clone()]);
1346        with_authenticator.user_signatures[0] = vec![authenticator];
1347
1348        for (pinned, stored) in [(&plain, &with_authenticator), (&with_authenticator, &plain)] {
1349            let built = FullCheckpointContents::from_contents_and_local_execution_data(
1350                pinned.checkpoint_contents(),
1351                stored.clone().into_iter(),
1352            )
1353            .unwrap();
1354
1355            assert_eq!(built.transactions, stored.transactions);
1356        }
1357    }
1358
1359    /// The checkpoint pins the signatures separately from the transactions, and
1360    /// no digest covers them, so a swapped envelope must be caught here.
1361    #[test]
1362    fn verify_digests_rejects_signatures_the_checkpoint_did_not_pin() {
1363        let (digest, contents, tampered) = contents_with_a_swapped_envelope();
1364        contents
1365            .verify_digests(digest)
1366            .expect("contents served as built must verify");
1367        tampered
1368            .verify_digests(digest)
1369            .expect_err("a transaction carrying unpinned signatures must be rejected");
1370    }
1371
1372    /// `verify` is the one door from untrusted contents to the verified type.
1373    #[test]
1374    fn verify_hands_back_verified_contents_that_carry_the_same_digest() {
1375        let (digest, contents, _) = contents_with_a_swapped_envelope();
1376
1377        let verified = contents
1378            .verify(digest)
1379            .expect("contents served as built must verify");
1380
1381        assert_eq!(verified.into_checkpoint_contents_digest(), digest);
1382    }
1383
1384    #[test]
1385    fn verify_refuses_contents_that_fail_verification() {
1386        let (digest, _, tampered) = contents_with_a_swapped_envelope();
1387
1388        tampered
1389            .verify(digest)
1390            .expect_err("contents that fail verification must not become verified");
1391    }
1392
1393    #[test]
1394    fn verify_digests_rejects_a_signature_count_that_does_not_match() {
1395        let contents = FullCheckpointContents::random_for_testing();
1396        let digest = contents.checkpoint_contents().digest();
1397
1398        let mut tampered = contents;
1399        tampered.user_signatures.clear();
1400
1401        // Building the contents asserts the two lengths are equal, so this has
1402        // to be rejected before that point.
1403        tampered
1404            .verify_digests(digest)
1405            .expect_err("a signature count that does not match must be rejected");
1406    }
1407
1408    /// The node pins an empty signature set for the system transactions it
1409    /// builds itself, while their envelopes carry a zero placeholder
1410    /// signature, so the pinned-signature check must leave them alone.
1411    #[test]
1412    fn verify_digests_accepts_a_system_transaction_pinned_without_signatures() {
1413        let transaction = VerifiedTransaction::new_end_of_epoch_transaction(vec![]).into_inner();
1414        assert_eq!(transaction.data().signatures().len(), 1);
1415        let effects = TestEffectsBuilder::new(transaction.data()).build();
1416        let execution_data = ExecutionData {
1417            transaction,
1418            effects,
1419        };
1420        let digests = execution_data.digests();
1421
1422        // Mirrors the checkpoint builder at the end of an epoch and the genesis
1423        // builder, which both pin no signatures for the transaction they
1424        // create.
1425        let checkpoint_contents =
1426            CheckpointContents::new_with_digests_and_signatures(vec![digests], vec![vec![]]);
1427        let digest = checkpoint_contents.digest();
1428        let contents = FullCheckpointContents::from_contents_and_execution_data(
1429            checkpoint_contents,
1430            std::iter::once(execution_data),
1431        )
1432        .expect("one transaction per pinned signature set");
1433
1434        contents
1435            .verify_digests(digest)
1436            .expect("a system transaction pinned without signatures must verify");
1437    }
1438
1439    /// Every system transaction is built with the same zero placeholder
1440    /// signature, so anything else in that slot did not come from the node.
1441    #[test]
1442    fn verify_digests_rejects_a_system_transaction_without_the_placeholder_signature() {
1443        let (_, key): (_, AccountPrivateKey) = get_key_pair();
1444        let system_data = Transaction::new_system_transaction(TransactionKind::EndOfEpoch(vec![]));
1445        let transaction = TransactionEnvelope::from_data_and_signer(system_data, vec![&key]);
1446        let effects = TestEffectsBuilder::new(transaction.data()).build();
1447        let execution_data = ExecutionData {
1448            transaction,
1449            effects,
1450        };
1451        let digests = execution_data.digests();
1452        let checkpoint_contents =
1453            CheckpointContents::new_with_digests_and_signatures(vec![digests], vec![vec![]]);
1454        let digest = checkpoint_contents.digest();
1455        let contents = FullCheckpointContents::from_contents_and_execution_data(
1456            checkpoint_contents,
1457            std::iter::once(execution_data),
1458        )
1459        .expect("one transaction per pinned signature set");
1460
1461        contents
1462            .verify_digests(digest)
1463            .expect_err("a system transaction signed with a real key must be rejected");
1464    }
1465
1466    /// The wire type must not admit a value whose two vectors disagree in
1467    /// length, so the invariant holds for every deserialized value.
1468    #[test]
1469    fn deserializing_contents_with_a_mismatched_signature_count_fails() {
1470        let mut tampered = FullCheckpointContents::random_for_testing();
1471        tampered.user_signatures.clear();
1472        let bytes = bcs::to_bytes(&tampered).expect("serializing the tampered value must work");
1473
1474        bcs::from_bytes::<FullCheckpointContents>(&bytes)
1475            .expect_err("a signature count that does not match must not deserialize");
1476    }
1477
1478    /// The two lists arrive in separate fields of the checkpoint data a node
1479    /// receives, so a mismatch is an input error, never a panic.
1480    #[test]
1481    fn from_contents_and_execution_data_rejects_mismatched_lengths() {
1482        let contents = FullCheckpointContents::random_for_testing();
1483        let checkpoint_contents = contents.checkpoint_contents();
1484
1485        FullCheckpointContents::from_contents_and_execution_data(
1486            checkpoint_contents,
1487            std::iter::empty(),
1488        )
1489        .expect_err("a signature count that does not match the transactions must be rejected");
1490    }
1491
1492    /// Only genesis and end-of-epoch transactions are pinned without
1493    /// signatures. A system transaction that went through consensus is pinned
1494    /// with its placeholder, so an empty pinned set for one is not something
1495    /// the node produces and must not be accepted.
1496    #[test]
1497    fn verify_digests_rejects_a_consensus_system_transaction_pinned_without_signatures() {
1498        let transaction = VerifiedTransaction::new_consensus_commit_prologue_v1(
1499            0,
1500            0,
1501            0,
1502            ConsensusCommitDigest::default(),
1503            vec![],
1504        )
1505        .into_inner();
1506        // The prologue mutates the shared clock, so the builder needs its
1507        // version to derive a valid lamport version.
1508        let effects = TestEffectsBuilder::new(transaction.data())
1509            .with_shared_input_versions(BTreeMap::from([(ObjectId::CLOCK, OBJECT_START_VERSION)]))
1510            .build();
1511        let execution_data = ExecutionData {
1512            transaction,
1513            effects,
1514        };
1515        let digests = execution_data.digests();
1516        let checkpoint_contents =
1517            CheckpointContents::new_with_digests_and_signatures(vec![digests], vec![vec![]]);
1518        let digest = checkpoint_contents.digest();
1519        let contents = FullCheckpointContents::from_contents_and_execution_data(
1520            checkpoint_contents,
1521            std::iter::once(execution_data),
1522        )
1523        .expect("one transaction per pinned signature set");
1524
1525        contents.verify_digests(digest).expect_err(
1526            "a consensus system transaction pinned without signatures must be rejected",
1527        );
1528    }
1529
1530    fn attestation_record(attestor: u8, verdict: AttestationVerdict) -> AttestationRecord {
1531        AttestationRecord { attestor, verdict }
1532    }
1533
1534    #[test]
1535    fn version_specific_data_v2_bcs_round_trip() {
1536        let v1 = CheckpointVersionSpecificData::V1(CheckpointVersionSpecificDataV1 {
1537            randomness_rounds: vec![RandomnessRound::new(3)],
1538        });
1539        let v2 = CheckpointVersionSpecificData::V2(CheckpointVersionSpecificDataV2 {
1540            randomness_rounds: vec![RandomnessRound::new(3)],
1541            attestation_entries: vec![
1542                AttestationEntry {
1543                    position: 1,
1544                    record: attestation_record(2, AttestationVerdict::Refuted { units: 5 }),
1545                },
1546                AttestationEntry {
1547                    position: 3,
1548                    record: attestation_record(1, AttestationVerdict::Undecided),
1549                },
1550            ],
1551            attestation_totals: AttestationTotals {
1552                refuted_units_squared: BTreeMap::from([(2, 16)]),
1553            },
1554        });
1555
1556        let v1_bytes = bcs::to_bytes(&v1).unwrap();
1557        let v2_bytes = bcs::to_bytes(&v2).unwrap();
1558        // The variant tag leaves the V1 encoding unchanged.
1559        assert_eq!(v1_bytes[0], 0);
1560        assert_eq!(v2_bytes[0], 1);
1561        assert_eq!(
1562            bcs::from_bytes::<CheckpointVersionSpecificData>(&v1_bytes).unwrap(),
1563            v1
1564        );
1565        assert_eq!(
1566            bcs::from_bytes::<CheckpointVersionSpecificData>(&v2_bytes).unwrap(),
1567            v2
1568        );
1569    }
1570
1571    #[test]
1572    fn summary_version_specific_data_follows_the_protocol_knob() {
1573        let contents = CheckpointContents::new_with_digests_only_for_tests([
1574            ExecutionDigests::random(),
1575            ExecutionDigests::random(),
1576        ]);
1577        let totals = || AttestationTotals {
1578            refuted_units_squared: BTreeMap::from([(1, 9)]),
1579        };
1580        let parsed_for = |version: u64, attestation_entries: Vec<AttestationEntry>| {
1581            let mut config = ProtocolConfig::get_for_max_version_UNSAFE();
1582            config.set_checkpoint_summary_version_specific_data_for_testing(version);
1583            CheckpointSummary::new_with_protocol_config(
1584                &config,
1585                1,
1586                2,
1587                10,
1588                &contents,
1589                None,
1590                GasCostSummary::default(),
1591                None,
1592                100,
1593                vec![RandomnessRound::new(5)],
1594                attestation_entries,
1595                totals(),
1596            )
1597            .parse_version_specific_data(&config)
1598            .unwrap()
1599            .expect("version specific data is present from version 1")
1600        };
1601        let entries = vec![AttestationEntry {
1602            position: 1,
1603            record: attestation_record(1, AttestationVerdict::Refuted { units: 3 }),
1604        }];
1605
1606        let v1 = parsed_for(1, entries.clone());
1607        assert_eq!(v1.randomness_rounds(), &[RandomnessRound::new(5)]);
1608        assert!(v1.attestation_entries().is_empty());
1609        assert!(v1.attestation_totals().is_none());
1610
1611        let v2 = parsed_for(2, entries.clone());
1612        assert_eq!(v2.randomness_rounds(), &[RandomnessRound::new(5)]);
1613        assert_eq!(v2.attestation_entries(), entries.as_slice());
1614        assert_eq!(v2.attestation_totals(), Some(&totals()));
1615    }
1616}