# Introduction
Most Bridge is a cutting-edge L2<>L1 bridging solution, currently supporting unidirectional transfers from Optimism and Starknet Sepolia to Ethereum Sepolia. Our innovative approach achieves unprecedented bridging finality, setting a new standard in cross-chain asset transfers.
Market Maker CLI
### The Problem
Despite being advanced technologies, blockchains still can't communicate with one another seamlessly. Their native messaging systems either aren't compatible or can take an extended amount of time—sometimes up to a week—to process. With the growing number of blockchains available, users don't want their funds locked on a single network, especially when they could benefit from lower gas fees offered by L2s, for instance. At the end of the day, users should have the freedom to move their assets across networks as they see fit, without unnecessary delays or complications.
### Key Features
* **Blazing Fast**: Complete bridging in less than a minute.
* **Cost-Effective**: Only three transactions required.
* **Highly Secure**: Leverages Zero Knowledge Proofs and the Herodotus Data Processor(HDP).
* **Simple Architecture**: Minimizes attack vectors.
* **Modular Design**: Adaptable to various blockchains.
# How It Works
How Most Bridge Works
### The Bridging Process
1. **User Initiates**: Lock funds in the Escrow contract (optionally swap via a temporary Hook Executor before locking) and set a market maker fee.
2. **Market Maker Acts**: Picks up the event and fulfills the intent.
3. **Proof Submission**: Market maker provides proof using HDP.
4. **Claim Funds**: Market maker claims locked funds at their convenience.
### Why Choose Most Bridge?
* **Speed**: Achieve finality in seconds, not hours.
* **Efficiency**: Streamlined process with just three transactions.
* **Security**: Mainnet-level security without long delays.
* **Flexibility**: Adaptable to various blockchain ecosystems.
* **Simplicity**: Straightforward architecture reduces complexity and risk.
### Supported Networks
#### Testnet
* Source: Optimism Sepolia, Starknet Sepolia
* Destination: Ethereum Sepolia
# Quick Start Guide
The bridging process is quite simple. Follow these steps to bridge your assets:
1. Head over to [most.wtf](https://most.wtf)
2. Connect your wallet, and switch to the OP Sepolia chain
3. Input the amount of OP Sepolia ETH\* you would like to bridge
4. Press "Review Details"
5. Confirm the transaction
6. Done!
After placing the intent, the funds should be available on the destination chain in less than 30 seconds, so you won't be waiting for long!
\*To get some OP Sepolia ETH head over to one of the faucets: [here](https://docs.optimism.io/builders/tools/build/faucets)
# User Interface
The Most Bridge user interface is designed to be intuitive and straightforward, allowing you to bridge your assets quickly and easily. Let's walk through the main components of the interface:
## Main Bridge View
* **Amount Input**: Enter the amount you want to bridge (e.g., ETH). You can type in the amount or use the "Max" button to select your entire balance.
* **Destination Chain**: Currently, the destination is set to Ethereum Sepolia. In future versions, you may be able to select from multiple destination chains.
* **Destination Address**: By default, this will be your current wallet address. You can change it if you want to send the bridged assets to a different address.
* **Review Details Button**: Once you've entered all the details, click to review all your entries are correct.
All details should match the previous view. Additionally you can now see:
* **Estimated Fee**: This shows the fee you'll pay for using the bridge. The fee goes to the Market Makers who facilitate the transfer.
After initiating a bridge transaction, you'll see status updates:
* **Confirming Transaction**: Confirms that your intent has been received and is being processed.
* **Bridge Transaction Complete**: Indicates that your assets have been sent to the destination chain.
* **Bridge Transaction Failed**: Indicates that your bridge transaction has failed and provides details why it failed.
You can track the progress of your transfer right in the interface, with no need to switch between different explorers or websites.
## Past Transactions View
You can also view your past transactions.
## Market Maker View
Market Maker UI
While this view is primarily for Market Makers, it's helpful for users to understand what happens behind the scenes:
1. **Intents List**: Shows all current bridge intents.
2. **Intent Details**: Displays information about each intent, including amount, fees, and status.
3. **Action Buttons**: Allow Market Makers to fulfill intents and manage the bridging process.
As a user, you don't need to interact with this part of the interface, but it's good to know that this is where Market Makers work to ensure your assets are bridged quickly and securely.
# Architecture Overview
While Most Bridge is designed to be user-friendly, understanding some of the underlying architecture can help you appreciate the security and efficiency of the system. In this section, we'll explore three key aspects of Most Bridge's architecture: HDP Integration, the Market Maker System, and the comparison between Single Market Maker (SMM) and Multiple Market Makers (MMM) approaches.
# HDP Integration
Herodotus Data Processor (HDP) is a crucial component of Most Bridge's security system. It provides a way to cryptographically verify that a transaction has occurred on one blockchain and prove it on another, without requiring complex consensus mechanisms between the two chains.
## How HDP works
1. **Transaction Recording**: When a Market Maker fulfills your intent on the destination chain, the details of this transaction are stored in the blockchain's state in our Payment Registry contract.
2. **Proof Generation**: The Market Maker then generates a proof of this storage state, which includes cryptographic evidence that your transaction was included in the blockchain.
3. **Verification**: This proof is submitted to the source chain, where it can be verified without needing to directly access the destination chain.
4. **Fund Release**: Once verified, the proof allows the locked funds to be released to the Market Maker on the source chain.
## Benefits of HDP
* **Security**: Provides cryptographic certainty that your transaction was completed.
* **Efficiency**: Allows for fast verification without waiting for long confirmation periods.
* **Scalability**: Works across different types of blockchains without requiring special compatibility.
# Market Maker System
The Market Maker (MM) is a key player in the Most Bridge design. They facilitate the quick transfer of assets between chains by providing liquidity and handling the cross-chain transactions.
## Role of the Market Maker
1. **Intent Fulfillment**: When you initiate a bridge transaction, the MM sees this intent and fulfills it on the destination chain.
2. **Liquidity Provision**: MMs use their own funds to send assets to you on the destination chain, allowing for near-instant transfers.
3. **Proof Submission**: After fulfilling an intent, the MM submits the proof using HDP to the source chain.
4. **Fee Collection**: In return for their service, MMs collect the fee you pay when initiating a bridge transaction.
## Benefits of the Market Maker System
* **Speed**: Allows for quick transfers without waiting for long confirmation times.
* **Efficiency**: MMs can batch transactions and optimize for gas fees, reducing costs.
# SMM vs. MMM
Most Bridge can operate in two different modes: Single Market Maker (SMM) and Multiple Market Makers (MMM). Currently, Most Bridge operates in SMM mode, but it's designed to be able to transition to MMM in the future.
## Single Market Maker (SMM)
In the SMM model, which is currently deployed:
* One trusted entity handles all intent fulfillment.
* Allows for efficient batching of transactions.
* Provides a single point of contact for monitoring and issue resolution.
**Benefits for Users:**
* Consistent experience and predictable fees.
* Potentially faster intent fulfillment due to streamlined operations.
**Considerations:**
* Relies on the reliability and liquidity of a single entity.
## Multiple Market Makers (MMM)
In the MMM model, which may be implemented in future versions:
* Multiple entities can compete to fulfill intents.
* More decentralized approach.
* Potential for more competitive fees due to competition.
**Benefits for Users:**
* Potentially lower fees due to competition.
* Increased resilience due to multiple liquidity providers.
**Considerations:**
* May introduce some variability in user experience and fees.
## Comparison
| Aspect | SMM (Current) | MMM (Potential Future) |
| ---------------------- | ------------- | ---------------------------- |
| Decentralization | Lower | Higher |
| Operational Efficiency | Higher | Potentially Lower |
| Fee Competitiveness | Fixed | Potentially More Competitive |
| Liquidity Risk | Concentrated | Distributed |
Most Bridge's architecture is designed to be flexible, allowing for a potential transition from SMM to MMM in the future, should that be deemed beneficial for the ecosystem and users.
By understanding these architectural components, you can better appreciate the balance of security, speed, and efficiency that Most Bridge provides in your cross-chain transactions.
# Security Considerations
At Most Bridge, we prioritize the security of your assets above all else. While we use advanced technology to ensure fast and efficient bridging, we've also implemented multiple layers of security to protect your funds throughout the bridging process.
### Current Single Market Maker Model
It's important to note that the current deployed version of Most Bridge operates on a Single Market Maker (SMM) model. This means that one trusted entity handles all intent fulfillment and claims the fees. While this model allows for faster and more efficient operations, we want you to be aware of:
1. **Centralized Fulfillment**: All bridge intents are processed by a single entity.
2. **Trusted Operator**: The Market Maker is a vetted and trusted part of our system.
3. **Efficient Processing**: This model allows for batching of transactions, reducing costs.
### Key Security Features
1. **Smart Contract Security**: Our smart contracts have been carefully designed to ensure they function exactly as intended, with no hidden vulnerabilities.
2. **Herodotus Data Processor**: We use advanced HDP technology to verify that every transaction has been correctly executed on the destination chain before releasing funds on the source chain.
3. **Funds Always Secured**: Your assets are locked in our secure Escrow contract, and then sent directly to your designated address on the destination chain. There's no point in the process where your funds are unsecured.
4. **Refund Intent**: If for any reason your intent isn't fulfilled within the expiration window, you can reclaim your funds from the Escrow contract. This ensures you always have control over your assets.
5. **Simplified Architecture**: By keeping our system architecture straightforward, we minimize the potential for errors or exploits.
### Continuous Monitoring
Our team constantly monitors the bridge operations to quickly detect and respond to any unusual activities. We’ve also introduced a health-check system that automatically creates intents and verifies their fulfillment, ensuring we’re alerted right away if anything goes wrong with Most. While the Single Market Maker model allows for this level of oversight, we're committed to maintaining the same level of security as we evolve.
# Future Roadmap
Most Bridge is committed to continuous improvement and expansion. Here's a glimpse into what we're working on for future versions:
### Multi-Chain Expansion
* **Goal**: Support bridging between across more chains, not limited to the Ethereum ecosystem.
### Multiple Market Maker (MMM) Model
* **Current**: Single Market Maker model.
* **Future**: Transition to a decentralized model with multiple market makers.
### Enhanced User Features
* **Transaction History**: Easy-to-access log of your past bridge transactions.
* **Advanced Analytics**: Tools to help you track and optimize your cross-chain activities.
* **Mobile Support**: Bridging on-the-go from your smartphone.
We're excited about these future developments and are working hard to bring them to you. As always, we'll implement these features with a strong focus on security and user experience. Stay tuned for updates as we continue to evolve and improve Most Bridge!
# Support
For technical support or questions about integrating with Most Bridge, please open an issue in our GitHub repository or contact our developer support team at .
Remember to never share private keys or sensitive information when seeking support.
# Quick Overview
Achieve lightning-fast bridging between L2 and L1 in just 23.258 seconds!
#### What is Most Bridge?
Most Bridge is a cutting-edge L2<>L1 bridging solution, currently supporting unidirectional transfers from Optimism Sepolia and Starknet Sepolia (source) to Ethereum Sepolia (destination). Our innovative approach achieves unprecedented bridging finality, setting a new standard in cross-chain asset transfers.
**Key Features**
* **Blazing Fast**: Complete bridging in just 23.258 seconds
* **Cost-Effective**: Only three transactions required for the whole bridging process: Lock, Fulfill, Prove
* **Highly Secure**: Leverages Zero Knowledge Proofs and Storage Proofs
* **Simple Architecture**: Minimizes attack vectors
* **Modular Design**: Adaptable to various blockchains and circumstances
## Introduction
For the @User
#### The Problem
Despite being advanced technologies, blockchains still can't communicate with one another seamlessly. Their native messaging systems either aren't compatible or can take an extended amount of time—sometimes up to a week—to process. With the growing number of blockchains available, users don’t want their funds locked on a single network, especially when they could benefit from lower gas fees offered by L2s, for instance. At the end of the day, users should have the freedom to move their assets across networks as they see fit, without unnecessary delays or complications.
#### What is Most?
In an ideal world, transferring funds between chains would be fast, easy, and secure—exactly what Most Bridge aims to deliver. Most Bridge is the newest, fastest, and most secure way to move funds between blockchains. And in case you’re wondering, “most” means “bridge” in 🇵🇱 Polish! So, yes, technically, it's called “bridge bridge”.
#### Features
What sets Most Bridge apart is its incredible speed. Once an intent is placed, users can receive their funds on the destination chain in under 25 seconds. It’s also highly secure. Governed by Solidity smart contracts, Most ensures that market makers are only paid once the exact transfer, as specified in the initial intent, has been completed. The transfer on the destination chain is then verified on the source chain, releasing the locked funds to the MM. Leveraging advanced Herodotus Data Processor(HDP) Modules, Most Bridge uses verifiable data to confirm that the transfer has occurred on the destination chain, ensuring that users' funds are neither lost nor exploited. Its smart contract architecture is intentionally simple, enhancing security by assigning each contract a clear, limited role, leaving no room for malicious actors to exploit loopholes.
Most Bridge is also highly modular. The architecture used for Most v1 can be applied to almost any blockchain, whether it's L2 or L1. The way market makers facilitate the bridging process is equally flexible. The v0 proof of concept was built with a multiple market maker approach (MMM), while v1 used a singular market maker (SMM). Both approaches are adaptable, depending on the needs of the organization or blockchain integrating Most Bridge into their ecosystem. Additionally, the smart contracts can be written in any language supported by the blockchain, including Solidity, Cairo, Rust, or Vyper. This flexibility allows Most Bridge to function seamlessly across chains, regardless of their native messaging system, giving users a reliable and secure way to move funds cross-chain.
#### How Does It Work?
The bridging process is straightforward:
1. You create an intent on the source chain using the Escrow contract. Optionally, Escrow deploys a temporary Hook Executor to swap your ERC20 into a target token before locking it, reducing price risk for the market maker (MM).
2. A MM fulfills your intent on the destination chain by sending funds to your address and calling the Payment Registry’s `mostFulfillOrders` function (supports single or batched fulfillments). The registry records the fulfillment details on-chain.
3. Later, the MM proves the fulfillments on the source chain by calling `proveAndWithdrawBatch` on Escrow. Escrow uses the Herodotus Data Processor (HDP) to verify the recorded fulfillments from the Payment Registry and, once validated, releases the locked funds to the MM.
4. If an intent isn’t fulfilled before its expiry window, you can reclaim your funds from Escrow.
# Tutorial
## Quick Start Guide
The bridging process is quite simple.
1. Head over to [most.wtf](https://github.com/Most-Bridge/most-docs/blob/master/user/most.wtf).
2. Connect your wallet, and switch to the right chain.
3. Input the amount you would like to bridge.
4. Press "Bridge Assets"
5. Confirm the transaction
6. Done!
After placing the intent, the funds should be available on the destination chain in less than 30 seconds, so you won't be waiting for long!
# Technical Overview
While Most Bridge uses advanced technology under the hood, which you can read more about in the other pages, here's a high-level overview of how the bridge works:
### Key Components
1. **Escrow Contract**: Securely holds user funds on the source chain and coordinates proof verification and withdrawals.
2. **Hook Executor**: An temporary contract deployed by Escrow to execute pre-bridge swaps (hooks) so MMs are not exposed to token volatility.
3. **Payment Registry**: Records fulfillments and transfers funds to users on the destination chain.
4. **Market Makers**: Facilitate fast delivery of assets to the destination chain.
5. **HDP Module**: Verifies, in a cryptographically sound way, that destination-chain fulfillments occurred.
6. **Operator Service**: The glue connecting the UI, smart contracts, backend, and HDP.
### How It All Works Together
1. You initiate a bridge transaction. Optionally, Escrow deploys a Hook Executor to swap your ERC20 into a target token before locking it.
2. A Market Maker fulfills your intent by sending funds to your destination address on the destination chain.
3. The Payment Registry records the fulfillment (emits `FulfillmentReceipt`) and marks it in the `fulfillments` mapping.
4. On the source chain, Escrow verifies the fulfillments via the HDP Module (aggregated proof) and then releases funds.
5. The Market Maker receives the locked funds on the source chain.
This process happens quickly and securely, allowing you to receive your assets on the destination chain in seconds.
### Security Measures
Most Bridge prioritizes the security of your assets:
* Funds are locked in Escrow until the Payment Registry fulfillment is proven via HDP.
* Pre-bridge swaps are executed in a temporary Hook Executor with atomic execution, minimizing MM volatility exposure.
* The design emphasizes simplicity, audited libraries (OpenZeppelin), and security checks.
### What If Something Goes Wrong?
If your intent isn't fulfilled before its expiry window:
* Your funds remain safely locked in the Escrow Contract.
* After the expiry window you set, you can reclaim your funds from the Escrow Contract.
This ensures that your assets are either successfully bridged or returnable to you, at all times.
# Key Components
The Most Bridge is made up of 5 main components:
# Escrow
The Escrow contract acts as the central settlement point for bridging transactions on Most. Its primary responsibilities are to securely hold user funds, validate that an order has been fulfilled on the destination chain, and release those funds to the Market Maker (MM) once the proof is confirmed. It also supports pre-bridge token swaps, allowing users to deposit in one asset and have it converted before bridging.
## Intent Creation
The bridging process begins when a user creates an order to send funds to another chain. This can happen in two ways:
* Direct deposit using createOrder, where the user sends either native ETH or an ERC20 token directly to the contract.
* Swap then deposit using swapAndCreateOrder, where the user’s ERC20 tokens are swapped through a series of hooks before being deposited into the Escrow.
In both cases, the contract records the source and destination details, the amount to be bridged, and an expiry time after which the order can be refunded if not fulfilled. Each order is hashed and stored in the contract’s state, with its initial status set to pending.
If the order is created via the swap function, a HookExecutor is deployed using CREATE2 and executes the swap instructions on-chain. Once the swap is complete, the resulting tokens and amounts are stored and used as the source assets for the order.
## Proving Fulfillment and Withdrawing
Once the funds have been delivered on the destination chain, the Market Maker responsible for fulfilling the order must prove this to the Escrow contract. This is done through a single call to proveAndWithdrawBatch, which both validates the proof and releases the funds.
Under the hood, the proof is verified using the Herodotus Data Processor (HDP). The contract prepares the order hashes, destination chain details, and the block number at which fulfillment occurred, and sends these as inputs to the HDP program. The HDP checks that each order exists in the payment registry on the destination chain, which is only possible if the order was actually fulfilled there, and returns a Merkle root of the result. The Escrow contract computes its own Merkle root from the expected output and compares it against the HDP’s result, ensuring that the proof is authentic.
If the verification passes, all orders in the batch are marked as completed, and the aggregated amounts owed to each Market Maker are released. This flow allows multiple orders to be proven and withdrawn in one call, reducing gas costs and operational overhead.
## Refunding Expired Orders
If an order isn’t fulfilled before its expiry time, the user who created it can reclaim their funds by calling refundOrder. The contract verifies that the caller is the original depositor, that the order is still pending, and that the expiry time has passed. If these checks succeed, the order is marked as reclaimed and the original funds are returned, whether they were deposited in ETH or ERC20 tokens. Refunding is never subject to the contract’s paused state, ensuring users can always retrieve their expired orders.
## Additional Contract Features
The Escrow contract supports both native ETH and ERC20 tokens, integrates seamlessly with the HDP for proof verification, and allows orders to be created with or without an initial swap step. The initial swap is used to protect MMs from being exposed to price volatility over extended periods of time. The Escrow also includes safety features such as pausing functionality, reentrancy protection, and strict validation of all order data before any state changes occur. Destination chain connections for the HDP can be added by the contract owner, enabling the system to expand to new networks over time.
This design allows the Escrow to operate as a secure, flexible bridge settlement layer, capable of handling straightforward deposits, complex swap flows, and batched cross-chain settlement proofs, all while maintaining strict cryptographic guarantees that only real, fulfilled orders can be paid out.
# Hook Executor
The `HookExecutor` is a helper contract deployed by `Escrow` to execute a sequence of on-chain hooks (typically DEX swaps) before locking funds for bridging. This lets the user convert their ERC20 tokens into a stable asset upfront so the Market Maker (MM) who fronts liquidity on the destination chain is not exposed to volatility risk.
Hooks are precomputed off-chain by calling the Most public API and are passed into `Escrow.swapAndCreateOrder`, which deploys a fresh `HookExecutor` via CREATE2, funds it, and triggers execution. When the swap completes, the executor returns the swapped tokens to `Escrow`, which then creates the order using the swapped token and amount.
## Key Interfaces
* Struct `Hook`:
* `target`: address to call
* `callData`: ABI-encoded calldata for the target
## Execution Lifecycle
1. `Escrow.swapAndCreateOrder(...)` deploys `HookExecutor` with CREATE2 (using `hookExecutorSalt`), and transfers the user’s `_srcAmount` of `_srcToken` to the executor.
2. `Escrow` calls `HookExecutor.execute(swapId, hooks, _srcToken, _expectedOutToken, address(this))`.
3. The executor:
* Reads its `tokenIn` balance and approves each `hooks[i].target` to spend that balance.
* Iterates through `hooks` and performs `target.call(callData)` in order.
* Checks the resulting `tokenOut` balance; reverts if zero
* Transfers all `tokenOut` to `escrow` and invokes `onPreBridgeSwapReturn(swapId, tokenOut, amountOut)` on `Escrow`
* Verifies no residual `tokenIn` or `tokenOut` remain; reverts if any are left
* Self-destructs to `escrow` (safe under EIP-6780 since creation and destruction occur in the same transaction)
If any hook call fails, the executor reverts the entire transaction (`HookFailed`). If `tokenOut` balance is zero at the end, it reverts (`ZeroOutputTokens`).
## How Escrow Uses the Result
* In `swapAndCreateOrder`, after `execute` returns, `Escrow` expects the executor to have called `onPreBridgeSwapReturn`
* `Escrow` validates that the executor returned and provided a non-zero `tokenOut` address. It then sets the order’s source token/amount to the returned values and proceeds to create the order as usual
* `Escrow` emits `SwapCompleted` with the swap details
## Parameters and Constraints
* `hooks`: Ordered list of calls to perform the swap route. Provided by the Most public API and passed through by the client.
* `tokenIn`: ERC20 to be swapped. Swaps require ERC20; native ETH is not supported in the hook flow.
* `tokenOut`: The expected output token address used by the executor to determine the balance to forward back to `Escrow`.
* `swapId`: Unique identifier binding the executor run to a specific `swapAndCreateOrder` call.
## Security and Safety Considerations
* The executor only holds funds explicitly sent for this swap and destroys itself at the end; it reverts if any tokens remain unreturned, limiting any potential attack vectors.
* Approvals are set per-hook target for the current executor `tokenIn` balance only.
* Hooks are external calls and may be unsafe if crafted maliciously, however the risk is minimized with the creation and destruction of the HookExecutor with each call. In practice, they are generated by the Most public API; clients should validate slippage and route off-chain. In the near future the hooks passed will be computed and checked on the client side to prevent the need for any trust.
* The flow is atomic: a failure in any hook or post-conditions reverts the entire `swapAndCreateOrder` call.
## Minimal Flow
1. User calls `swapAndCreateOrder` with `_srcToken`, `_srcAmount`, `hooks`, `_expectedOutToken`, and `hookExecutorSalt`.
2. `Escrow` deploys `HookExecutor`, sends it `_srcAmount`, and calls `execute`.
3. `HookExecutor` performs the swap route, sends `tokenOut` back, calls `onPreBridgeSwapReturn`, and self-destructs.
4. `Escrow` records the swapped token/amount and creates the order.
# Payment Registry
The Payment Registry accepts fulfillments from Market Makers (MMs), transfers funds to users on the destination chain, and records immutable fulfillment data used later for HDP verification.
## Storage
* `mapping(bytes32 => bytes32) fulfillments`: maps a fulfillment order hash to the MM’s source address (stored as `bytes32`). A non-zero value indicates the order has been fulfilled and by whom.
## HDP Integration
* The `fulfillments` mapping is the on-chain ground truth that orders were paid on the destination chain.
* HDP reads the EVM storage slot for each order’s fulfillment hash to verify non-zero presence and who fulfilled it.
* The mapping slot index is fixed by the contract’s storage layout and is used by the HDP module to derive the storage key for proofs.
## Controls and Safety
* `Pausable` admin switch and `onlyOwner` pause/unpause.
* `ReentrancyGuard` on fulfillment entrypoint.
* Uses `SafeERC20` for token transfers.
* `fulfillments[orderHash] == 0` check prevents double-fulfillment.
# Operator Service
{% hint style="warning" %}
MM-UI and MM-Service Repositories are currently closed source
{% endhint %}
To complete the bridging process and enable data transmission between smart contracts, the Operator service is essential. Previously known as "eventWatch," the Operator's primary role is to listen for on-chain events.
While the core functionality is handled by the smart contracts, the Operator service is crucial for a fully operational bridge. Although it can be run locally, in a production environment, it's currently deployed on a server as an API service that the front-end can interact with. The Operator service also integrates a database to store all the intents, their statuses, and other relevant information. Inside the repository, there are several listeners that wait for events from the smart contracts, and upon receiving an event, they initiate the corresponding workflow.
## Workflows
The first workflow is triggered when a user places an intent, the listener captures the intent details and logs them in the database, which the front-end queries to display the information for the MM to fulfill. The function checks if the intent already exists in the database, and if not, it adds it. Next, it verifies if the MM has enabled auto-transfers. If enabled, it calls `executeSendTransfer`, which automatically fulfills the intent on behalf of the MM. After fulfillment, the database is updated to reflect the intent's completion.
The second workflow is triggered when a fulfillment is made on the Payment Registry contract. The listener detects the `FulfillmentReceipt` event and updates the database to indicate that the intent has been fulfilled. This is also where the automatic withdrawal system could be activated to start the proving and withdrawing process as soon as fulfillments are made via `mostFulfillOrders` (single or batched). However, in the current SMM setup, the MM has the flexibility to withdraw the funds at a more convenient time, either manually or through an automated system. This system can monitor the MM's liquidity on the destination chain, the amount owed on the source chain, and the current gas prices to optimize the withdrawal process.
To start the proof process, when done automatically, the process begins with calculating if a rebalancing of funds is required. Meaning is the market maker owed more on the source chain than the amount of funds they have on the destination chain. If a rebalance is needed, and gas prices are lower, the MM can choose how many intents it wishes to prove and withdraw to improve its liquidity position.
The service will then gather the necessary intent information that is used for proving, and send it over to the Escrow contract that will begin the proof generation process by validating the passed data, sending it to our custom HDP module, and then receiving an answer if said intent has been fulfilled.
The calculation of storage slots used to be performed by the Operator service, however has since been offloaded to the HDP module, for a more secure and robust system, as once deployed via cairo, there is no way to change how the system will work, ensuring it's soundness.
This completes the core function of the Operator service. There are some differences depending on how the bridge is used, such as MMM versus SMM scenarios, as well as the option for auto-filling intents. Additionally, the Market Maker situation evaluator and executor monitors your outstanding debts on the destination chain. Depending on your liquidity and current gas fees, it will decide whether to start withdrawing smaller intents when gas prices are low or to withdraw one large intent when gas prices are high but you are low on liquidity on the destination chain.
# HDP Module
HDP Is the Herodotus Data Processor, it is what allows us to in a cryptographically verifiable manner, check what data is a available on another chain, via a storage proof system.
## Contract
The contract is implemented as a Starknet module. It uses the HDP Cairo library for interacting with EVM storage, and Keccak to compute storage slots for Solidity mappings.
If you're curious about why we need to calculate storage slots, you can learn more about how storage works in Solidity smart contracts [here](https://docs.soliditylang.org/en/la/internals/layout_in_storage.html).
Fulfillment records are stored in a Solidity mapping within the Payment Registry. In Solidity, a mapping value is stored at slot `keccak(abi.encode(key, mappingSlotIndex))`. In our case:
* `key` is the `fulfillment_keccak_hash` from each order (`u256`)
* `mappingSlotIndex` is a constant `FULFILLMENTS_MAPPING_SLOT = 2` (from the Payment Registry storage layout)
We compute `keccak(encode(fulfillment_keccak_hash, 2))` to derive the storage slot for each order’s fulfillment record.
## Main Function
This is the core verification function which iterates through a set of fulfilled intents and checks whether each one has been successfully recorded in the Payment Registry contract. It takes in parameters like the HDP module instance for storage access, the destination chain id, the payment registry address on which the fulfillment was made, the block number, which acts as the point in time, and the array of orders that have been fulfilled.
## Workflow
1. The function initializes is\_verified\_correctly to true.
2. It iterates over the provided orders and computes the EVM storage slot for each order’s fulfillment status using Keccak:
```
let mut bytes: Bytes = BytesTrait::new(0, array![]);
bytes.append_u256(order.fulfillment_keccak_hash);
bytes.append_u256(FULFILLMENTS_MAPPING_SLOT); // 2
let slot = bytes.keccak();
```
3. It queries the HDP EVM storage module for the slot’s value:
```
let storage_slot_value = hdp.evm.storage_get_slot(
@StorageKey {
chain_id: destination_chain_id,
block_number: block_number.into(),
address: payment_registry_address,
storage_slot: slot,
},
);
```
4. If the retrieved value is zero, it means the fulfillment has not been recorded (the mapping stores the MM’s source address as a non-zero `bytes32`). In that case, `is_verified_correctly` is set to false.
5. The function returns true if all fulfillment records are present (non-zero), otherwise false.
## Data Structures
* `OrderData { fulfillment_keccak_hash: u256 }`: the key used to look up each order’s fulfillment status in the Payment Registry mapping.
## Using the HDP Module
This HDP Module, is what is called from our Escrow smart contract on the source chain when the MM claims that they have fulfilled a certain intent. This HDP Module Ensures successful fulfillments in cross-chain operations by verifying state commitments on the destination chain, and allows the MM to safely unlock the funds locked on the source chain, as a repayment for facilitating the cross chain transfer.
# End To End
1. The user creates an intent using the Escrow smart contract on the source chain.
2. A hash of the intent details is stored in `orderStatus`.
3. An `OrderPlaced` event is emitted.
4. The Operator service, listening for the `OrderPlaced` event, detects the new intent.
5. The Market Maker (MM) calls the `mostFulfillOrders` function on the PaymentRegistry smart contract on the destination chain, using details from the `OrderPlaced` event.
6. The PaymentRegistry contract records the transaction details and transfers the funds to the user on the destination chain.
7. The Operator service, listens for the `FulfillmentReceipt` event from the PaymentRegistry contract.
8. Once the `FulfillmentReceipt` event is detected, the MM can either begin the proof process immediately or wait for better gas prices and batch proof their intent fulfillments.
9. When the proof process begins, the Operator service gathers data specifying which intent is being proved.
10. The Operator service forwards the data for the intents claimed as fulfilled back to the Escrow smart contract, which sends the data to an HDP module that calculates which storage slots in the `PaymentRegistry` smart contract certify intent fulfillment.
11. The HDP module verifies that the storage slot for each order hash stores a non-zero `bytes32` (the MM’s source address). If so, the module output is validated by Escrow and the funds are released to the MM.
# FAQ
### Why is it called "Most"?
"Most" means "bridge" in Polish, and this bridge is proudly built in Poland. So, technically, we're calling it "Bridge Bridge"! We liked the simplicity and directness of the name, while sprinkling in some of our polish roots into the crypto ecosystem.
### What happens if my intent is not fulfilled?
If the intent isn’t fulfilled, the funds stay locked in the Escrow contract and can be reclaimed after the expiry window you set when the intent was created. Your funds are safe and can only be claimed by a Market Maker who proves they've fulfilled the intent, or by you if the intent expires without being fulfilled.
### What chains does Most Bridge currently support?
Currently, Most Bridge supports transfers from Optimism Sepolia and Starknet Sepolia (source chains) to Ethereum Sepolia (destination chain). We're working on rolling out broader mainnet support.
### Is Most Bridge decentralized?
Most Bridge is not decentralized. Currently in v1, Most Bridge operates on an SMM model, where one trusted entity handles all intent fulfillments. In the future, we want to transition to an MMM model, where multiple entities compete to fulfill intents, potentially leading to lower fees and increased decentralization. You can read more about the differences here: [SMM vs. MMM](/architecture-overview/smm-vs.-mmm)
### What is a Market Maker (MM)?
A market maker is an entity that facilitates the cross-chain transfer by fronting their funds to the user on the destination chain, in exchange for a fee.
### What fees do I need to pay?
There are two types of fees:
1. A Market Maker fee, which you set when initiating the bridge transaction. This incentivizes Market Makers to process your transaction quickly.
2. Gas fees for the transaction on the source chain.
The total amount you'll receive on the destination chain is your transfer amount minus the Market Maker fee.
### Can I cancel a bridge transaction after I've initiated it?
Once a transaction is initiated and confirmed on the blockchain, it can't be cancelled. However, if the Market Maker hasn't processed it, you can reclaim your funds after 24 hours using the refund intent mechanism.
### What is HDP and why is it important?
Herodotus Data Processor (HDP) is a solution developed by [Herodotus](https://x.com/HerodotusDev) that allows Most Bridge to cryptographically verify that a transaction has occurred on the destination chain without needing to directly access that chain. This enables fast and secure cross-chain transfers without relying on complex consensus mechanisms between chains.
### Will Most Bridge support other cryptocurrencies besides ETH?
Yes. Most supports ETH and ERC-20 tokens. We plan to expand supported assets and networks over time. Stay tuned for announcements [here](https://x.com/most_wtf)!
