You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
**Smart Contracts in Solidity which serve as a core layer for Biconomy Modular Execution Environment (MEE) stack and unlock seamless cross-chain orchestration via SuperTransactions (Stx)**
-[Orchestration](https://docs.biconomy.io/new/learn-about-biconomy/understanding-composable-orchestration) in Biconomy Docs
8
+
-[Fusion research article](https://ethresear.ch/t/fusion-module-7702-alternative-with-no-protocol-changes/20949)
10
9
10
+
## Repo Contents
11
+
This repo contains all the contracts that have previously been divided into three different repositories.
12
+
-https://github.com/bcnmy/nexus
13
+
-https://github.com/bcnmy/mee-contracts
14
+
-https://github.com/bcnmy/composability
15
+
16
+
Since all of the above contracts follow the same purpose of unlocking Supertransactions (stx), they are now united within the same repository.
17
+
18
+
Thus, the repo contains the contracts that implement the following important entities:
19
+
20
+
### MEE K1 Validator
21
+
ERC-7579 Validator module that validates SuperTransactions.
22
+
A SuperTransaction is an array or Merkle tree of entries, such as UserOps or ERC-712 data structures (cross-chain intents, off-chain orders, etc.).
23
+
#### Modes
24
+
The K1 MEE Validator supports four distinct validation modes to accommodate different user flows:
25
+
-**Simple Mode:** User signs the EIP-712 Hash of a SuperTx data struct.
26
+
-**On-Chain Transaction Mode:** Fusion mode, where the user signs a standard Ethereum transaction that funds the orchestrator Smart Account and contains the Stx hash, thus the Stx entries are also signed with just one signature.
27
+
-**ERC-2612 Permit Mode:** Fusion mode that combines token approvals with SuperTx authorization in a single signature. In this and the above (on-chain) mode, the Stx is a Merkle tree of entries.
28
+
-**Non-MEE Fallback Mode:** For backwards compatibility with standard ERC-4337 UserOperations.
29
+
30
+
This flexibility allows users to interact with smart accounts using familiar EOA wallets while unlocking advanced batching and cross-chain orchestration capabilities.
31
+
32
+
#### SuperTransaction Architecture
33
+
At the core of the validator's design is support for SuperTransactions (Stx, SuperTx) - structured batches of operations that can include UserOps, ERC-712 messages, cross-chain intents, and off-chain orders.
34
+
Each operation within a SuperTx includes temporal constraints (lowerBoundTimestamp, upperBoundTimestamp) for scheduled execution windows.
35
+
36
+
This architecture enables users to sign once and authorize complex multi-step, potentially cross-chain workflows while maintaining cryptographic proof that each executed operation was part of the original batch.
37
+
38
+
#### Modular Account Integration & Security
39
+
Built as a singleton contract shared across all smart accounts, the K1 MEE Validator implements multiple standards including ERC-7579 (modular accounts), ERC-7780 (stateless validation), ERC-7739 (nested typed data signing), and ERC-1271 (contract signature verification). Each smart account installs the validator module and configures its own EOA owner, with ownership restricted to externally owned accounts (including EIP-7702 delegated EOAs).
40
+
41
+
### Composability contracts
42
+
43
+
**Smart contracts to unlock composable execution.**
44
+
The composability stack allows developers to create dynamic, multi-step transactions entirely from frontend code by injecting values into the calldata at runtime.
45
+
[More details on Runtime Parameters injection](https://docs.biconomy.io/new/getting-started/understanding-runtime-injection).
46
+
47
+
The smart contracts in this repo handle the composable execution logic, allowing developers to avoid any on-chain development and just use the SDK to build composable operations.
48
+
49
+
#### Features:
50
+
-**Single-chain composability**: Use outputs of one action as inputs for another.
51
+
For example, `swap()` method returns the amount of tokens received as a result of a swap.
52
+
This exact amount can be used as input for `approve()` method to allow a `stake()` method to execute.
53
+
-**Static types handling**: Inject any static types into the abi.encoded function call.
54
+
-**Several return values handling**: If function returns multiple values, you can use any amount of them as input for another function.
55
+
-**Constraints handling**: Validate any constraints on the input parameters.
56
+
57
+
#### Contracts included:
58
+
-**Composable Execution Module**: ERC-7579 module that allows Smart Accounts to execute composable transactions without changing the account implementation.
59
+
-**Composable Execution Base**: Base contract that Smart Accounts can inherit from to enable composable execution natively.
60
+
-**Composable Execution Lib**: Library that provides methods to process input and output parameters of a composable execution.
61
+
62
+
#### On storage slots for ComposableExecutionModule
63
+
As can be seen in the Storage.sol file, the actual storage slot used depends on both the `account` address and the `caller`
64
+
address.
65
+
66
+
Thus, if the ComposableExecutionModule is used via 'call' flows (as a Fallback and/or Executor module), the storage slot is different compared to the case when the module is used via 'delegatecall' flow.
67
+
68
+
It is however recommended that the smart account is consistent in terms of which flow - `call` or `delegatecall` - it uses.
69
+
70
+
### Nexus Smart Account
71
+
72
+
#### Standards Compliance & Ecosystem Integration
73
+
74
+
Nexus is a fully compliant ERC-7579 modular smart account supporting a comprehensive suite of standards:
This extensive standards support ensures Nexus works seamlessly across the entire Ethereum ecosystem, from DeFi protocols and NFT marketplaces to account abstraction infrastructure and the latest EIP-7702 innovations for EOA enhancement.
Nexus introduces groundbreaking features that set it apart from traditional smart accounts. **PREP Mode** (Provably Rootless EIP-7702 Proxy) enables rootless proxy initialization using cryptographic validation, allowing ERC-7702 accounts to bootstrap without traditional proxy overhead. **Module Enable Mode** permits installing validator modules during UserOp validation itself, dramatically reducing onboarding friction by allowing a module to validate its own installation. The **Composable Execution System** provides runtime parameter injection, enabling outputs from one call to feed as inputs to another with constraint validation (equality, range checks), perfect for complex DeFi workflows. Additional innovations include a **tri-modal nonce system** that encodes validation mode and validator address directly in the nonce for gas efficiency, **pre-validation hooks** that can modify hashes/signatures before validation (enabling session keys and spending limits), and an **emergency hook uninstall mechanism** with a 1-day timelock safeguard against malicious modules.
92
+
93
+
#### Gas Optimization & Architectural Excellence
94
+
95
+
Nexus is engineered for exceptional gas efficiency through multiple optimization techniques. It uses **transient storage** (EIP-1153 tstore/tload) for initialization flags, eliminating persistent storage costs. Critical execution paths leverage **assembly-optimized operations** with memory-safe annotations for compiler optimization, including specialized versions that skip return data when unnecessary. The storage layout employs **ERC-7201 namespaced storage** with packed data structures—validators and executors use gas-efficient **SentinelList** linked lists for O(1) contains checks, while the single-hook design avoids mapping overhead. The architecture implements a **default validator pattern** where an immutable validator is always available without storage lookups, and **minimal SLOAD operations** with early returns in validation flows. Batch execution includes optimized paths for operations that don't require return values, and the **module fallback system** handles ERC token receivers natively without requiring module installations, saving gas on common operations.
96
+
97
+
### Node Paymaster and Node Paymaster Factory
98
+
Utility smart contracts for MEE Nodes.
99
+
Node Paymaster allows MEE Nodes to pay for UserOps that are part of the Stx executed by the nodes.
100
+
#### Economic Model & Gas Sponsorship
101
+
The Node Paymaster implements a sophisticated economic model that ensures MEE Nodes can profitably sponsor gas fees while maintaining fairness for all participants. It supports flexible refund mechanisms where gas sponsors (users or dApps) pre-pay an estimated maximum gas cost plus a premium, and then receive refunds for unused gas after execution. The system offers two premium models: percentage-based and fixed-amount premiums. This design allows nodes to earn sustainable revenue for their infrastructure services while keeping gas costs predictable and competitive for end users.
102
+
#### Architecture & Access Control
103
+
Built on the ERC-4337 account abstraction standard, the Node Paymaster uses a factory deployment pattern with CREATE2 for deterministic, counterfactual addresses. Each MEE Node deploys its own NodePaymaster instance through the NodePaymasterFactory, which can automatically fund the paymaster's deposit at the EntryPoint during creation. The paymaster implements strict access control via tx.origin checks, restricting UserOp sponsorship to the node owner's master EOA and whitelisted worker EOAs. This intentional design makes it incompatible with public ERC-4337 mempools but optimized for MEE's private node infrastructure, where proven nodes operate within a trusted network with slashing mechanisms for malicious behavior.
104
+
105
+
## Security Audits
106
+
The Stx contracts suite is carefully audited by lead researchers in blockchain security.
107
+
Please explore the [`/audit/`](audit) folder to find the reports.
11
108
12
109
## Usage
13
110
@@ -20,5 +117,8 @@ $ forge build
20
117
### Test
21
118
22
119
```shell
23
-
$ forge test --isolate
24
-
```
120
+
$ pnpm test
121
+
```
122
+
123
+
### Deployments
124
+
See [`script/deploy/README.MD`](script/deploy/README.MD) to learn how to deploy the stx contracts to your chain.
0 commit comments