setup utoipa foundations

Author: d4mr

Cargo.lock

@@ -17,3 +17,4 @@ async-nats = "0.40.0"
 twmq = { version = "0.1.0", path = "../twmq" }
 thirdweb-core = { version = "0.1.0", path = "../thirdweb-core" }
 uuid = { version = "1.17.0", features = ["v4"] }
+utoipa = "5.4.0"

core/Cargo.toml

@@ -2,19 +2,19 @@ use alloy::primitives::{Address, Bytes};
 use schemars::JsonSchema;
 use serde::{Deserialize, Serialize};
 
-#[derive(JsonSchema, Serialize, Deserialize, Clone)]
+#[derive(JsonSchema, Serialize, Deserialize, Clone, utoipa::ToSchema)]
 #[serde(remote = "Address", transparent)]
-/// # Address
+/// ### Address
 /// Used to represent an EVM address. This is a string of length 42 with a `0x` prefix. Non-checksummed addresses are also supported, but will be converted to checksummed.
 pub struct AddressDef(pub String);
 
-#[derive(JsonSchema, Serialize, Deserialize, Clone)]
+#[derive(JsonSchema, Serialize, Deserialize, Clone, utoipa::ToSchema)]
 #[serde(remote = "Bytes", transparent)]
 /// # Bytes
 /// Used to represent "bytes". This is a 0x prefixed hex string.
 pub struct BytesDef(pub String);
 
-#[derive(JsonSchema, Serialize, Deserialize, Clone)]
+#[derive(JsonSchema, Serialize, Deserialize, Clone, utoipa::ToSchema)]
 /// # U256
 /// Used to represent a 256-bit unsigned integer. Engine can parse these from any valid encoding of the Ethereum "quantity" format.
 pub struct U256Def(pub String);

core/src/defs.rs

@@ -13,7 +13,7 @@ use twmq::error::TwmqError;
 
 use crate::chain::Chain;
 
-#[derive(Debug, Error, Clone, Serialize, Deserialize, JsonSchema)]
+#[derive(Debug, Error, Clone, Serialize, Deserialize, JsonSchema, utoipa::ToSchema)]
 pub enum RpcErrorKind {
     /// Server returned an error response.
     #[error("server returned an error response: {0}")]
@@ -58,7 +58,7 @@ pub enum RpcErrorKind {
     OtherTransportError(String),
 }
 
-#[derive(Debug, Serialize, Deserialize, Clone, JsonSchema)]
+#[derive(Debug, Serialize, Deserialize, Clone, JsonSchema, utoipa::ToSchema)]
 pub struct RpcErrorResponse {
     /// The error code.
     pub code: i64,
@@ -99,7 +99,7 @@ pub struct RpcErrorInfo {
 }
 
 /// A serializable contract interaction error type
-#[derive(Debug, Error, Serialize, Deserialize, Clone, JsonSchema)]
+#[derive(Debug, Error, Serialize, Deserialize, Clone, JsonSchema, utoipa::ToSchema)]
 pub enum ContractInteractionErrorKind {
     /// Unknown function referenced.
     #[error("unknown function: function {0} does not exist")]
@@ -159,7 +159,7 @@ pub enum ContractInteractionErrorKind {
     FunctionResolutionFailed(String),
 }
 
-#[derive(Error, Debug, Serialize, Clone, Deserialize, JsonSchema)]
+#[derive(Error, Debug, Serialize, Clone, Deserialize, JsonSchema, utoipa::ToSchema)]
 pub enum EngineError {
     #[error("RPC error on chain {chain_id} at {rpc_url}: {message}")]
     RpcError {
@@ -198,6 +198,7 @@ pub enum EngineError {
     ContractInteractionError {
         /// Contract address
         #[schemars(with = "Option<AddressDef>")]
+        #[schema(value_type = Option<AddressDef>)]
         contract_address: Option<Address>,
         /// Chain ID
         chain_id: u64,

core/src/error.rs

@@ -8,7 +8,7 @@ use serde::{Deserialize, Deserializer, Serialize};
 
 use crate::constants::{DEFAULT_FACTORY_ADDRESS_V0_7, ENTRYPOINT_ADDRESS_V0_7};
 
-#[derive(Deserialize, Serialize, Debug, JsonSchema, Clone, Copy)]
+#[derive(Deserialize, Serialize, Debug, JsonSchema, Clone, Copy, utoipa::ToSchema)]
 pub enum EntrypointVersion {
     #[serde(rename = "0.6")]
     V0_6,
@@ -28,55 +28,58 @@ pub struct EntrypointAndFactoryDetails {
     pub factory_address: Address,
 }
 
-/// # ERC-4337 Execution Options
+/// ### ERC-4337 Execution Options
 /// This struct allows flexible configuration of ERC-4337 execution options,
 /// with intelligent defaults and inferences based on provided values.
 ///
-/// ## Field Inference
+/// ### Field Inference
 /// When fields are omitted, the system uses the following inference rules:
 ///
-/// 1. **Version Inference**:
-///    - If `entrypointVersion` is provided, it's used directly
-///    - Otherwise, tries to infer from `entrypointAddress` (if provided)
-///    - If that fails, tries to infer from `factoryAddress` (if provided)
-///    - Defaults to version 0.7 if no inference is possible
+/// 1. Version Inference:
+///     - If `entrypointVersion` is provided, it's used directly
+///     - Otherwise, tries to infer from `entrypointAddress` (if provided)
+///     - If that fails, tries to infer from `factoryAddress` (if provided)
+///     - Defaults to version 0.7 if no inference is possible
 ///
-/// 2. **Entrypoint Address Inference**:
+/// 2. Entrypoint Address Inference:
 ///    - If provided explicitly, it's used as-is
 ///    - Otherwise, uses the default address corresponding to the inferred version:
 ///      - V0.6: 0x5FF137D4b0FDCD49DcA30c7CF57E578a026d2789
 ///      - V0.7: 0x0576a174D229E3cFA37253523E645A78A0C91B57
 ///
-/// 3. **Factory Address Inference**:
+/// 3. Factory Address Inference:
 ///    - If provided explicitly, it's used as-is
 ///    - Otherwise, uses the default factory corresponding to the inferred version:
-///      - V0.6: [DEFAULT_FACTORY_ADDRESS_V0_6]
-///      - V0.7: [DEFAULT_FACTORY_ADDRESS_V0_7]
+///      - V0.6: 0x85e23b94e7F5E9cC1fF78BCe78cfb15B81f0DF00 [DEFAULT_FACTORY_ADDRESS_V0_6]
+///      - V0.7: 0x4bE0ddfebcA9A5A4a617dee4DeCe99E7c862dceb [DEFAULT_FACTORY_ADDRESS_V0_7]
 ///
-/// 4. **Account Salt**:
+/// 4. Account Salt:
 ///    - If provided explicitly, it's used as-is
 ///    - Otherwise, defaults to "0x" (commonly used as the defauult "null" salt for smart accounts)
 ///
-/// 5. **Smart Account Address**:
+/// 5. Smart Account Address:
 ///    - If provided explicitly, it's used as-is
 ///    - Otherwise, it's read from the smart account factory
 ///
 /// All optional fields can be omitted for a minimal configuration using version 0.7 defaults.
-#[derive(Deserialize, Serialize, Debug, Clone, JsonSchema)]
+#[derive(Deserialize, Serialize, Debug, Clone, JsonSchema, utoipa::ToSchema)]
 #[serde(rename_all = "camelCase")]
 pub struct Erc4337ExecutionOptions {
     #[schemars(with = "AddressDef")]
+    #[schema(value_type = AddressDef)]
     pub signer_address: Address,
 
     #[serde(flatten)]
     #[schemars(with = "EntrypointAndFactoryDetailsDeserHelper")]
+    #[schema(value_type = EntrypointAndFactoryDetailsDeserHelper)]
     pub entrypoint_details: EntrypointAndFactoryDetails,
 
     #[serde(default = "default_account_salt")]
     pub account_salt: String,
 
     #[serde(skip_serializing_if = "Option::is_none")]
     #[schemars(with = "Option::<AddressDef>")]
+    #[schema(value_type = Option<AddressDef>)]
     pub smart_account_address: Option<Address>,
 }
 
@@ -91,41 +94,41 @@ pub fn default_entrypoint_address() -> Address {
 pub fn default_account_salt() -> String {
     "0x".to_string()
 }
-#[derive(Deserialize, JsonSchema)]
+#[derive(Deserialize, JsonSchema, utoipa::ToSchema)]
 struct EntrypointAndFactoryDetailsDeserHelper {
-    /// # Entrypoint Contract Address
+    /// ### Entrypoint Contract Address
     /// The address of the ERC-4337 entrypoint contract.
     ///
     /// If omitted, defaults to the standard address for the specified/inferred version.
     ///
     /// Known addresses:
     ///
     /// - V0.6: 0x5FF137D4b0FDCD49DcA30c7CF57E578a026d2789
-    ///
     /// - V0.7: 0x0000000071727De22E5E9d8BAf0edAc6f37da032
     #[serde(rename = "entrypointAddress")]
     #[schemars(with = "Option<AddressDef>")]
+    #[schema(value_type = Option<AddressDef>)]
     entrypoint_address: Option<Address>,
 
-    /// # Entrypoint Version
+    /// ### Entrypoint Version
     /// The version of the ERC-4337 standard to use.
     ///
     /// If omitted, the version will be inferred from the entrypoint address,
     /// then from factory address, or defaults to V0.7.
     #[serde(rename = "entrypointVersion")]
     version: Option<EntrypointVersion>,
 
-    /// # Account Factory Address
+    /// ### Account Factory Address
     /// The address of the smart account factory contract.
     /// If omitted, defaults to the thirweb default account factory for the specified/inferred version.
     ///
     /// Known addresses:
     ///
     /// - V0.6: 0x85e23b94e7F5E9cC1fF78BCe78cfb15B81f0DF00
-    ///
     /// - V0.7: 0x4bE0ddfebcA9A5A4a617dee4DeCe99E7c862dceb
     #[serde(rename = "factoryAddress")]
     #[schemars(with = "Option<AddressDef>")]
+    #[schema(value_type = Option<AddressDef>)]
     factory_address: Option<Address>,
 }
 

core/src/execution_options/aa.rs

@@ -0,0 +1,19 @@
+use schemars::JsonSchema;
+use serde::{Deserialize, Serialize};
+
+#[derive(Debug, Clone, Serialize, Deserialize, JsonSchema, utoipa::ToSchema)]
+#[schema(title = "Auto Determine Execution")]
+#[serde(rename_all = "camelCase")]
+/// This is the default execution option.
+/// If you do not specify an execution type, and only specify a "from" string,
+/// engine will automatically determine the most optimal options for you.
+/// If you would like to specify granular options about execution strategy
+/// choose one of the other executionOptions type and provide them.
+pub struct AutoExecutionOptions {
+    /// The identifier of the entity to send the transaction from.
+    /// Automatically picks best execution strategy based on the identifier.
+    /// - If EOA address, execution uses EIP7702 based smart-wallet execution
+    /// - If 7702 not supported on chain, falls back to smart-contract wallet (ERC4337) with default smart account for this EOA (v0.7)
+    /// - UNLESS this is a zk-chain, in which case, zk-sync native-aa is used
+    pub from: String,
+}