ibc_core_client_context/
context.rs

1use ibc_core_client_types::Height;
2use ibc_core_host_types::error::HostError;
3use ibc_core_host_types::identifiers::ClientId;
4use ibc_core_host_types::path::{ClientConsensusStatePath, ClientStatePath};
5use ibc_primitives::prelude::*;
6use ibc_primitives::Timestamp;
7
8use crate::client_state::{ClientStateExecution, ClientStateValidation};
9use crate::consensus_state::ConsensusState;
10
11/// Defines the methods available to clients for validating client state
12/// transitions. The generic `V` parameter in
13/// [crate::client_state::ClientStateValidation] must
14/// inherit from this trait.
15pub trait ClientValidationContext: Sized {
16    type ClientStateRef: ClientStateValidation<Self>;
17    type ConsensusStateRef: ConsensusState;
18
19    /// Returns the ClientState for the given identifier `client_id`.
20    ///
21    /// Note: Clients have the responsibility to store client states on client creation and update.
22    fn client_state(&self, client_id: &ClientId) -> Result<Self::ClientStateRef, HostError>;
23
24    /// Retrieve the consensus state for the given client ID at the specified
25    /// height.
26    ///
27    /// Returns an error if no such state exists.
28    ///
29    /// Note: Clients have the responsibility to store consensus states on client creation and update.
30    fn consensus_state(
31        &self,
32        client_cons_state_path: &ClientConsensusStatePath,
33    ) -> Result<Self::ConsensusStateRef, HostError>;
34
35    /// Returns the timestamp and height of the host when it processed a client
36    /// update request at the specified height.
37    fn client_update_meta(
38        &self,
39        client_id: &ClientId,
40        height: &Height,
41    ) -> Result<(Timestamp, Height), HostError>;
42}
43
44/// Defines the methods that all client `ExecutionContext`s (precisely the
45/// generic parameter of
46/// [`crate::client_state::ClientStateExecution`] ) must
47/// implement.
48///
49/// Specifically, clients have the responsibility to store their client state
50/// and consensus states. This trait defines a uniform interface to do that for
51/// all clients.
52pub trait ClientExecutionContext:
53    ClientValidationContext<ClientStateRef = Self::ClientStateMut>
54{
55    type ClientStateMut: ClientStateExecution<Self>;
56
57    fn client_state_mut(&self, client_id: &ClientId) -> Result<Self::ClientStateMut, HostError> {
58        self.client_state(client_id)
59    }
60
61    /// Called upon successful client creation and update
62    fn store_client_state(
63        &mut self,
64        client_state_path: ClientStatePath,
65        client_state: Self::ClientStateRef,
66    ) -> Result<(), HostError>;
67
68    /// Called upon successful client creation and update
69    fn store_consensus_state(
70        &mut self,
71        consensus_state_path: ClientConsensusStatePath,
72        consensus_state: Self::ConsensusStateRef,
73    ) -> Result<(), HostError>;
74
75    /// Delete the consensus state from the store located at the given `ClientConsensusStatePath`
76    fn delete_consensus_state(
77        &mut self,
78        consensus_state_path: ClientConsensusStatePath,
79    ) -> Result<(), HostError>;
80
81    /// Called upon successful client update.
82    ///
83    /// Implementations are expected to use this to record the specified time
84    /// and height as the time at which this update (or header) was processed.
85    fn store_update_meta(
86        &mut self,
87        client_id: ClientId,
88        height: Height,
89        host_timestamp: Timestamp,
90        host_height: Height,
91    ) -> Result<(), HostError>;
92
93    /// Delete the update time and height associated with the client at the
94    /// specified height.
95    ///
96    /// This update time should be associated with a consensus state through the
97    /// specified height.
98    ///
99    /// Note that this timestamp is determined by the host.
100    fn delete_update_meta(&mut self, client_id: ClientId, height: Height) -> Result<(), HostError>;
101}
102
103/// An optional trait that extends the client validation context capabilities by
104/// providing additional methods for validating a client state. Mainly
105/// benefiting ICS-07 Tendermint clients by granting access to essential
106/// information from hosts.
107///
108/// Categorized under ICS-02, as it may also be utilized by other types of light
109/// clients. Developers may view this trait as an example of a custom context
110/// definition that expands client validation capabilities, according to their
111/// specific light client requirements.
112pub trait ExtClientValidationContext: ClientValidationContext {
113    /// Returns the current timestamp of the local chain.
114    fn host_timestamp(&self) -> Result<Timestamp, HostError>;
115
116    /// Returns the current height of the local chain.
117    fn host_height(&self) -> Result<Height, HostError>;
118
119    /// Returns all the heights at which a consensus state is stored.
120    fn consensus_state_heights(&self, client_id: &ClientId) -> Result<Vec<Height>, HostError>;
121
122    /// Search for the lowest consensus state higher than `height`.
123    fn next_consensus_state(
124        &self,
125        client_id: &ClientId,
126        height: &Height,
127    ) -> Result<Option<Self::ConsensusStateRef>, HostError>;
128
129    /// Search for the highest consensus state lower than `height`.
130    fn prev_consensus_state(
131        &self,
132        client_id: &ClientId,
133        height: &Height,
134    ) -> Result<Option<Self::ConsensusStateRef>, HostError>;
135}
136
137/// An optional trait that extends the client context required during execution.
138///
139/// This trait, as it stands right now, serves as a trait alias for types that
140/// implement both [`ExtClientValidationContext`] and
141/// [`ClientExecutionContext`], and it is auto-implemented for such types.
142///
143/// Light client developers who wish to define and utilize their own custom
144/// client contexts may choose to introduce execution methods within a similar
145/// trait, which would allow them to store additional client-specific data and
146/// conduct execution operations more efficiently, tailored to their light
147/// client implementation.
148pub trait ExtClientExecutionContext: ExtClientValidationContext + ClientExecutionContext {}
149
150impl<T> ExtClientExecutionContext for T where T: ExtClientValidationContext + ClientExecutionContext {}
151
152/// General-purpose helper converter enabling `TryFrom` and `Into` conversions
153/// primarily intended between an enum and its variants. This usually used by
154/// standalone functions as a trait bound allowing them to obtain the concrete
155/// local type from the enum containing that concrete type as its variant, like
156/// when enum `AnyConsensusState` contains the Tendermint `ConsensusState`.
157pub trait Convertible<C>: TryFrom<C> + Into<C> {}
158
159impl<T, C> Convertible<C> for T where T: TryFrom<C> + Into<C> {}
ibc_core_client_context/context.rs

ibc_core_client_context/
context.rs
