kona_preimage/
traits.rs

1use crate::{
2    PreimageKey,
3    errors::{ChannelResult, PreimageOracleResult},
4};
5use alloc::{boxed::Box, string::String, vec::Vec};
6use async_trait::async_trait;
7
8/// A [PreimageOracleClient] is a high-level interface to read data from the host, keyed by a
9/// [PreimageKey].
10#[async_trait]
11pub trait PreimageOracleClient {
12    /// Get the data corresponding to the currently set key from the host. Return the data in a new
13    /// heap allocated `Vec<u8>`
14    ///
15    /// # Returns
16    /// - `Ok(Vec<u8>)` if the data was successfully fetched from the host.
17    /// - `Err(_)` if the data could not be fetched from the host.
18    async fn get(&self, key: PreimageKey) -> PreimageOracleResult<Vec<u8>>;
19
20    /// Get the data corresponding to the currently set key from the host. Writes the data into the
21    /// provided buffer.
22    ///
23    /// # Returns
24    /// - `Ok(())` if the data was successfully written into the buffer.
25    /// - `Err(_)` if the data could not be written into the buffer.
26    async fn get_exact(&self, key: PreimageKey, buf: &mut [u8]) -> PreimageOracleResult<()>;
27}
28
29/// A [HintWriterClient] is a high-level interface to the hint pipe. It provides a way to write
30/// hints to the host.
31#[async_trait]
32pub trait HintWriterClient {
33    /// Write a hint to the host. This will overwrite any existing hint in the pipe, and block until
34    /// all data has been written.
35    ///
36    /// # Returns
37    /// - `Ok(())` if the hint was successfully written to the host.
38    /// - `Err(_)` if the hint could not be written to the host.
39    async fn write(&self, hint: &str) -> PreimageOracleResult<()>;
40}
41
42/// A [CommsClient] is a trait that combines the [PreimageOracleClient] and [HintWriterClient]
43pub trait CommsClient: PreimageOracleClient + Clone + HintWriterClient {}
44
45// Implement the super trait for any type that satisfies the bounds
46impl<T: PreimageOracleClient + Clone + HintWriterClient> CommsClient for T {}
47
48/// A [PreimageOracleServer] is a high-level interface to accept read requests from the client and
49/// write the preimage data to the client pipe.
50#[async_trait]
51pub trait PreimageOracleServer {
52    /// Get the next preimage request and return the response to the client.
53    ///
54    /// # Returns
55    /// - `Ok(())` if the data was successfully written into the client pipe.
56    /// - `Err(_)` if the data could not be written to the client.
57    async fn next_preimage_request<F>(&self, get_preimage: &F) -> PreimageOracleResult<()>
58    where
59        F: PreimageFetcher + Send + Sync;
60}
61
62/// A [HintReaderServer] is a high-level interface to read preimage hints from the
63/// [HintWriterClient] and prepare them for consumption by the client program.
64#[async_trait]
65pub trait HintReaderServer {
66    /// Get the next hint request and return the acknowledgement to the client.
67    ///
68    /// # Returns
69    /// - `Ok(())` if the hint was received and the client was notified of the host's
70    ///   acknowledgement.
71    /// - `Err(_)` if the hint was not received correctly.
72    async fn next_hint<R>(&self, route_hint: &R) -> PreimageOracleResult<()>
73    where
74        R: HintRouter + Send + Sync;
75}
76
77/// A [HintRouter] is a high-level interface to route hints to the appropriate handler.
78#[async_trait]
79pub trait HintRouter {
80    /// Routes a hint to the appropriate handler.
81    ///
82    /// # Arguments
83    /// - `hint`: The hint to route.
84    ///
85    /// # Returns
86    /// - `Ok(())` if the hint was successfully routed.
87    /// - `Err(_)` if the hint could not be routed.
88    async fn route_hint(&self, hint: String) -> PreimageOracleResult<()>;
89}
90
91/// A [PreimageFetcher] is a high-level interface to fetch preimages during preimage requests.
92#[async_trait]
93pub trait PreimageFetcher {
94    /// Get the preimage corresponding to the given key.
95    ///
96    /// # Arguments
97    /// - `key`: The key to fetch the preimage for.
98    ///
99    /// # Returns
100    /// - `Ok(Vec<u8>)` if the preimage was successfully fetched.
101    /// - `Err(_)` if the preimage could not be fetched.
102    async fn get_preimage(&self, key: PreimageKey) -> PreimageOracleResult<Vec<u8>>;
103}
104
105/// A [PreimageServerBackend] is a trait that combines the [PreimageFetcher] and [HintRouter]
106/// traits.
107pub trait PreimageServerBackend: PreimageFetcher + HintRouter {}
108
109// Implement the super trait for any type that satisfies the bounds
110impl<T: PreimageFetcher + HintRouter> PreimageServerBackend for T {}
111
112/// A [Channel] is a high-level interface to read and write data to a counterparty.
113#[async_trait]
114pub trait Channel {
115    /// Asynchronously read data from the channel into the provided buffer.
116    ///
117    /// # Arguments
118    /// - `buf`: The buffer to read data into.
119    ///
120    /// # Returns
121    /// - `Ok(usize)`: The number of bytes read.
122    /// - `Err(_)` if the data could not be read.
123    async fn read(&self, buf: &mut [u8]) -> ChannelResult<usize>;
124
125    /// Asynchronously read exactly `buf.len()` bytes into `buf` from the channel.
126    ///
127    /// # Arguments
128    /// - `buf`: The buffer to read data into.
129    ///
130    /// # Returns
131    /// - `Ok(())` if the data was successfully read.
132    /// - `Err(_)` if the data could not be read.
133    async fn read_exact(&self, buf: &mut [u8]) -> ChannelResult<usize>;
134
135    /// Asynchronously write the provided buffer to the channel.
136    ///
137    /// # Arguments
138    /// - `buf`: The buffer to write to the host.
139    ///
140    /// # Returns
141    /// - `Ok(usize)`: The number of bytes written.
142    /// - `Err(_)` if the data could not be written.
143    async fn write(&self, buf: &[u8]) -> ChannelResult<usize>;
144}
kona_preimage/traits.rs

kona_preimage/
traits.rs
