freenet_stdlib/contract_interface/
state.rs

1//! Contract state types: State, StateDelta, and StateSummary.
2
3use std::{
4    borrow::Cow,
5    ops::{Deref, DerefMut},
6};
7
8use serde::{Deserialize, Serialize};
9use serde_with::serde_as;
10
11#[serde_as]
12#[derive(Debug, PartialEq, Eq, Clone, Serialize, Deserialize)]
13#[cfg_attr(feature = "testing", derive(arbitrary::Arbitrary))]
14pub struct State<'a>(
15    // TODO: conver this to Arc<[u8]> instead
16    #[serde_as(as = "serde_with::Bytes")]
17    #[serde(borrow)]
18    Cow<'a, [u8]>,
19);
20
21impl State<'_> {
22    /// Gets the number of bytes of data stored in the `State`.
23    pub fn size(&self) -> usize {
24        self.0.len()
25    }
26
27    pub fn into_owned(self) -> State<'static> {
28        State(self.0.into_owned().into())
29    }
30
31    /// Extracts the owned data as a `Vec<u8>`.
32    pub fn into_bytes(self) -> Vec<u8> {
33        self.0.into_owned()
34    }
35
36    /// Acquires a mutable reference to the owned form of the `State` data.
37    pub fn to_mut(&mut self) -> &mut Vec<u8> {
38        self.0.to_mut()
39    }
40}
41
42impl From<Vec<u8>> for State<'_> {
43    fn from(state: Vec<u8>) -> Self {
44        State(Cow::from(state))
45    }
46}
47
48impl<'a> From<&'a [u8]> for State<'a> {
49    fn from(state: &'a [u8]) -> Self {
50        State(Cow::from(state))
51    }
52}
53
54impl AsRef<[u8]> for State<'_> {
55    fn as_ref(&self) -> &[u8] {
56        match &self.0 {
57            Cow::Borrowed(arr) => arr,
58            Cow::Owned(arr) => arr.as_ref(),
59        }
60    }
61}
62
63impl<'a> Deref for State<'a> {
64    type Target = Cow<'a, [u8]>;
65
66    fn deref(&self) -> &Self::Target {
67        &self.0
68    }
69}
70
71impl DerefMut for State<'_> {
72    fn deref_mut(&mut self) -> &mut Self::Target {
73        &mut self.0
74    }
75}
76
77impl std::io::Read for State<'_> {
78    fn read(&mut self, buf: &mut [u8]) -> std::io::Result<usize> {
79        self.as_ref().read(buf)
80    }
81}
82
83/// Represents a modification to some state - similar to a diff in source code.
84///
85/// The exact format of a delta is determined by the contract. A [contract](Contract) implementation will determine whether
86/// a delta is valid - perhaps by verifying it is signed by someone authorized to modify the
87/// contract state. A delta may be created in response to a [State Summary](StateSummary) as part of the State
88/// Synchronization mechanism.
89#[serde_as]
90#[derive(Clone, Serialize, Deserialize, Debug, PartialEq, Eq)]
91#[cfg_attr(feature = "testing", derive(arbitrary::Arbitrary))]
92pub struct StateDelta<'a>(
93    // TODO: conver this to Arc<[u8]> instead
94    #[serde_as(as = "serde_with::Bytes")]
95    #[serde(borrow)]
96    Cow<'a, [u8]>,
97);
98
99impl StateDelta<'_> {
100    /// Gets the number of bytes of data stored in the `StateDelta`.
101    pub fn size(&self) -> usize {
102        self.0.len()
103    }
104
105    /// Extracts the owned data as a `Vec<u8>`.
106    pub fn into_bytes(self) -> Vec<u8> {
107        self.0.into_owned()
108    }
109
110    pub fn into_owned(self) -> StateDelta<'static> {
111        StateDelta(self.0.into_owned().into())
112    }
113}
114
115impl From<Vec<u8>> for StateDelta<'_> {
116    fn from(delta: Vec<u8>) -> Self {
117        StateDelta(Cow::from(delta))
118    }
119}
120
121impl<'a> From<&'a [u8]> for StateDelta<'a> {
122    fn from(delta: &'a [u8]) -> Self {
123        StateDelta(Cow::from(delta))
124    }
125}
126
127impl AsRef<[u8]> for StateDelta<'_> {
128    fn as_ref(&self) -> &[u8] {
129        match &self.0 {
130            Cow::Borrowed(arr) => arr,
131            Cow::Owned(arr) => arr.as_ref(),
132        }
133    }
134}
135
136impl<'a> Deref for StateDelta<'a> {
137    type Target = Cow<'a, [u8]>;
138
139    fn deref(&self) -> &Self::Target {
140        &self.0
141    }
142}
143
144impl DerefMut for StateDelta<'_> {
145    fn deref_mut(&mut self) -> &mut Self::Target {
146        &mut self.0
147    }
148}
149
150/// Summary of `State` changes.
151///
152/// Given a contract state, this is a small piece of data that can be used to determine a delta
153/// between two contracts as part of the state synchronization mechanism. The format of a state
154/// summary is determined by the state's contract.
155#[serde_as]
156#[derive(Clone, Serialize, Deserialize, Debug, PartialEq, Eq)]
157#[cfg_attr(feature = "testing", derive(arbitrary::Arbitrary))]
158pub struct StateSummary<'a>(
159    // TODO: conver this to Arc<[u8]> instead
160    #[serde_as(as = "serde_with::Bytes")]
161    #[serde(borrow)]
162    Cow<'a, [u8]>,
163);
164
165impl StateSummary<'_> {
166    /// Extracts the owned data as a `Vec<u8>`.
167    pub fn into_bytes(self) -> Vec<u8> {
168        self.0.into_owned()
169    }
170
171    /// Gets the number of bytes of data stored in the `StateSummary`.
172    pub fn size(&self) -> usize {
173        self.0.len()
174    }
175
176    pub fn into_owned(self) -> StateSummary<'static> {
177        StateSummary(self.0.into_owned().into())
178    }
179
180    pub fn deser_state_summary<'de, D>(deser: D) -> Result<StateSummary<'static>, D::Error>
181    where
182        D: serde::Deserializer<'de>,
183    {
184        let value = <StateSummary as Deserialize>::deserialize(deser)?;
185        Ok(value.into_owned())
186    }
187}
188
189impl From<Vec<u8>> for StateSummary<'_> {
190    fn from(state: Vec<u8>) -> Self {
191        StateSummary(Cow::from(state))
192    }
193}
194
195impl<'a> From<&'a [u8]> for StateSummary<'a> {
196    fn from(state: &'a [u8]) -> Self {
197        StateSummary(Cow::from(state))
198    }
199}
200
201impl AsRef<[u8]> for StateSummary<'_> {
202    fn as_ref(&self) -> &[u8] {
203        match &self.0 {
204            Cow::Borrowed(arr) => arr,
205            Cow::Owned(arr) => arr.as_ref(),
206        }
207    }
208}
209
210impl<'a> Deref for StateSummary<'a> {
211    type Target = Cow<'a, [u8]>;
212
213    fn deref(&self) -> &Self::Target {
214        &self.0
215    }
216}
217
218impl DerefMut for StateSummary<'_> {
219    fn deref_mut(&mut self) -> &mut Self::Target {
220        &mut self.0
221    }
222}
freenet_stdlib/contract_interface/state.rs

freenet_stdlib/contract_interface/
state.rs
