freenet_stdlib/contract_interface/
trait_def.rs

1//! Contract interface trait definition.
2//!
3//! This module defines the `ContractInterface` trait which all contracts must implement.
4
5use crate::parameters::Parameters;
6
7use super::{
8    ContractError, RelatedContracts, State, StateDelta, StateSummary, UpdateData,
9    UpdateModification, ValidateResult,
10};
11
12/// Trait to implement for the contract building.
13///
14/// Contains all necessary methods to interact with the contract.
15///
16/// # Examples
17///
18/// Implementing `ContractInterface` on a type:
19///
20/// ```
21/// # use freenet_stdlib::prelude::*;
22/// struct Contract;
23///
24/// #[contract]
25/// impl ContractInterface for Contract {
26///     fn validate_state(
27///         _parameters: Parameters<'static>,
28///         _state: State<'static>,
29///         _related: RelatedContracts
30///     ) -> Result<ValidateResult, ContractError> {
31///         Ok(ValidateResult::Valid)
32///     }
33///
34///     fn update_state(
35///         _parameters: Parameters<'static>,
36///         state: State<'static>,
37///         _data: Vec<UpdateData>,
38///     ) -> Result<UpdateModification<'static>, ContractError> {
39///         Ok(UpdateModification::valid(state))
40///     }
41///
42///     fn summarize_state(
43///         _parameters: Parameters<'static>,
44///         _state: State<'static>,
45///     ) -> Result<StateSummary<'static>, ContractError> {
46///         Ok(StateSummary::from(vec![]))
47///     }
48///
49///     fn get_state_delta(
50///         _parameters: Parameters<'static>,
51///         _state: State<'static>,
52///         _summary: StateSummary<'static>,
53///     ) -> Result<StateDelta<'static>, ContractError> {
54///         Ok(StateDelta::from(vec![]))
55///     }
56/// }
57/// ```
58// ANCHOR: contractifce
59/// # ContractInterface
60///
61/// This trait defines the core functionality for managing and updating a contract's state.
62/// Implementations must ensure that state delta updates are *commutative*. In other words,
63/// when applying multiple delta updates to a state, the order in which these updates are
64/// applied should not affect the final state. Once all deltas are applied, the resulting
65/// state should be the same, regardless of the order in which the deltas were applied.
66///
67/// Noncompliant behavior, such as failing to obey the commutativity rule, may result
68/// in the contract being deprioritized or removed from the p2p network.
69pub trait ContractInterface {
70    /// Verify that the state is valid, given the parameters.
71    fn validate_state(
72        parameters: Parameters<'static>,
73        state: State<'static>,
74        related: RelatedContracts<'static>,
75    ) -> Result<ValidateResult, ContractError>;
76
77    /// Update the state to account for the new data
78    fn update_state(
79        parameters: Parameters<'static>,
80        state: State<'static>,
81        data: Vec<UpdateData<'static>>,
82    ) -> Result<UpdateModification<'static>, ContractError>;
83
84    /// Generate a concise summary of a state that can be used to create deltas
85    /// relative to this state.
86    fn summarize_state(
87        parameters: Parameters<'static>,
88        state: State<'static>,
89    ) -> Result<StateSummary<'static>, ContractError>;
90
91    /// Generate a state delta using a summary from the current state.
92    /// This along with [`Self::summarize_state`] allows flexible and efficient
93    /// state synchronization between peers.
94    fn get_state_delta(
95        parameters: Parameters<'static>,
96        state: State<'static>,
97        summary: StateSummary<'static>,
98    ) -> Result<StateDelta<'static>, ContractError>;
99}
100// ANCHOR_END: contractifce
freenet_stdlib/contract_interface/trait_def.rs

freenet_stdlib/contract_interface/
trait_def.rs
