ab_contracts_common/
env.rs

1use crate::ContractError;
2use crate::method::{ExternalArgs, MethodFingerprint};
3use ab_core_primitives::address::Address;
4use ab_core_primitives::shard::ShardIndex;
5use ab_io_type::trivial_type::TrivialType;
6use core::ffi::c_void;
7use core::marker::PhantomData;
8use core::ptr::NonNull;
9
10/// Context for method call.
11///
12/// The correct mental model for context is "user of the child process," where "process" is a method
13/// call. Essentially, something executed with a context of a contract can be thought as done
14/// "on behalf" of that contract, which depending on circumstances may or may not be desired.
15///
16/// Initially, the context is [`Address::NULL`]. For each call into another contract, the context of
17/// the current method can be either preserved, reset to [`Address::NULL`] or replaced with the
18/// current contract's address. Those are the only options. Contracts do not have privileges to
19/// change context to the address of an arbitrary contract.
20#[derive(Debug, Copy, Clone, Eq, PartialEq, TrivialType)]
21#[repr(u8)]
22pub enum MethodContext {
23    /// Keep current context
24    Keep,
25    /// Reset context to [`Address::NULL`]
26    Reset,
27    /// Replace context with the current contract's address
28    Replace,
29}
30
31/// Method to be called by the executor
32#[derive(Debug)]
33#[repr(C)]
34#[must_use]
35pub struct PreparedMethod<'a> {
36    /// Address of the contract that contains a function to the below fingerprint
37    pub contract: Address,
38    /// Fingerprint of the method being called
39    pub fingerprint: MethodFingerprint,
40    /// Anonymous pointer to a struct that implements `ExternalArgs` of the method with the above
41    /// `fingerprint`
42    pub external_args: NonNull<c_void>,
43    /// Context for method call
44    pub method_context: MethodContext,
45    /// Used to tie the lifetime to `ExternalArgs`
46    pub phantom: PhantomData<&'a ()>,
47}
48
49#[cfg(feature = "guest")]
50unsafe extern "C" {
51    /// Host-level API
52    fn __ab_host_call_import(method: &PreparedMethod<'_>) -> crate::ExitCode;
53}
54
55/// Internal wrapper around [`__ab_host_call_import()`] that will always have a single copy (never
56/// inlined) in the binary and will be possible to locate in the final binary for inspection and
57/// rewriting if necessary while completely ignoring relocation of `__ab_host_call_import()`
58#[cfg(feature = "guest")]
59#[unsafe(no_mangle)]
60#[inline(never)]
61#[doc(hidden)]
62pub extern "C" fn __ab_host_call(method: &PreparedMethod<'_>) -> crate::ExitCode {
63    // SAFETY: FFI call with correct argument, there are no other safety requirements
64    unsafe { __ab_host_call_import(method) }
65}
66
67/// Environment state
68#[derive(Debug, Copy, Clone, TrivialType)]
69#[repr(C)]
70pub struct EnvState {
71    /// Shard index where execution is happening
72    pub shard_index: ShardIndex,
73    /// Explicit padding, contents must be all zeroes
74    pub padding_0: [u8; 4],
75    /// Own address of the contract
76    pub own_address: Address,
77    /// Context of the execution
78    pub context: Address,
79    /// Caller of this contract
80    pub caller: Address,
81}
82
83/// Executor context that can be used to interact with executor
84#[cfg(feature = "executor")]
85pub trait ExecutorContext: core::fmt::Debug {
86    /// Call prepared method
87    fn call(
88        &self,
89        previous_env_state: &EnvState,
90        prepared_method: &mut PreparedMethod<'_>,
91    ) -> Result<(), ContractError>;
92}
93
94#[cfg(all(feature = "executor", feature = "guest", not(any(doc, unix, windows))))]
95compile_error!(
96    "`executor` and `guest` features are mutually exclusive due to it affecting `Env` layout"
97);
98
99/// Ephemeral execution environment.
100///
101/// In guest environment equivalent to just [`EnvState`], while on Unix and Windows an executor
102/// context is also present
103#[derive(Debug)]
104#[repr(C)]
105pub struct Env<'a> {
106    state: EnvState,
107    #[cfg(feature = "executor")]
108    executor_context: &'a mut dyn ExecutorContext,
109    #[cfg(not(feature = "executor"))]
110    phantom_data: PhantomData<&'a ()>,
111}
112
113// TODO: API to "attach" data structures to the environment to make sure pointers to it can be
114//  returned safely, will likely require `Pin` and return some reference from which pointer is to
115//  be created
116#[cfg_attr(
117    not(feature = "executor"),
118    expect(
119        clippy::elidable_lifetime_names,
120        reason = "False-positive, see https://github.com/rust-lang/rust-clippy/issues/17638"
121    )
122)]
123impl<'a> Env<'a> {
124    /// Instantiate environment with executor context
125    #[cfg(feature = "executor")]
126    #[inline(always)]
127    #[cfg_attr(feature = "no-panic", no_panic::no_panic)]
128    pub fn with_executor_context(
129        state: EnvState,
130        executor_context: &'a mut dyn ExecutorContext,
131    ) -> Self {
132        Self {
133            state,
134            executor_context,
135        }
136    }
137
138    /// Instantiate environment with executor context
139    #[cfg(feature = "executor")]
140    #[inline(always)]
141    #[cfg_attr(feature = "no-panic", no_panic::no_panic)]
142    pub fn get_mut_executor_context(&mut self) -> &mut dyn ExecutorContext {
143        self.executor_context
144    }
145
146    /// Shard index where execution is happening
147    #[inline(always)]
148    #[cfg_attr(feature = "no-panic", no_panic::no_panic)]
149    pub fn shard_index(&self) -> ShardIndex {
150        self.state.shard_index
151    }
152
153    /// Own address of the contract
154    #[inline(always)]
155    #[cfg_attr(feature = "no-panic", no_panic::no_panic)]
156    pub fn own_address(&self) -> Address {
157        self.state.own_address
158    }
159
160    /// Context of the execution
161    #[inline(always)]
162    #[cfg_attr(feature = "no-panic", no_panic::no_panic)]
163    pub fn context<'b>(self: &'b &'b mut Self) -> Address {
164        self.state.context
165    }
166
167    /// Caller of this contract
168    #[inline(always)]
169    #[cfg_attr(feature = "no-panic", no_panic::no_panic)]
170    pub fn caller<'b>(self: &'b &'b mut Self) -> Address {
171        self.state.caller
172    }
173
174    /// Call a method at specified address and with specified arguments.
175    ///
176    /// This is a shortcut for [`Self::prepare_method_call()`] + [`Self::call_prepared()`].
177    #[inline(always)]
178    pub fn call<Args>(
179        &self,
180        contract: Address,
181        args: &mut Args,
182        method_context: MethodContext,
183    ) -> Result<(), ContractError>
184    where
185        Args: ExternalArgs,
186    {
187        let prepared_method = Self::prepare_method_call(contract, args, method_context);
188        self.call_prepared(prepared_method)
189    }
190
191    /// Prepare a single method for calling at specified address and with specified arguments.
192    ///
193    /// The result is to be used with [`Self::call_prepared()`] afterward.
194    #[inline(always)]
195    #[cfg_attr(feature = "no-panic", no_panic::no_panic)]
196    pub fn prepare_method_call<Args>(
197        contract: Address,
198        args: &mut Args,
199        method_context: MethodContext,
200    ) -> PreparedMethod<'_>
201    where
202        Args: ExternalArgs,
203    {
204        PreparedMethod {
205            contract,
206            fingerprint: Args::FINGERPRINT,
207            external_args: NonNull::from_mut(args).cast::<c_void>(),
208            method_context,
209            phantom: PhantomData,
210        }
211    }
212
213    /// Call prepared method.
214    ///
215    /// In most cases, this doesn't need to be called directly. Extension traits provide a more
216    /// convenient way to make method calls and are enough in most cases.
217    #[inline]
218    pub fn call_prepared(&self, method: PreparedMethod<'_>) -> Result<(), ContractError> {
219        cfg_select! {
220            feature = "executor" => {
221                let mut method = method;
222                self.executor_context.call(&self.state, &mut method)
223            }
224            feature = "guest" => __ab_host_call(&method).into(),
225            _ => {
226                let _: PreparedMethod<'_> = method;
227                Err(ContractError::InternalError)
228            }
229        }
230    }
231}
ab_contracts_common/env.rs

ab_contracts_common/
env.rs
