CrossChainer

This project implements a decentralized cross-chain atomic swap protocol, enabling trustless exchange of assets between the Flow blockchain (a non-EVM environment utilizing the Cadence programming language) and an EVM-compatible blockchain (such as Ethereum or its testnets).

The fundamental mechanism ensuring the atomicity of these swaps is the Hashed Timelock Contract (HTLC). HTLCs are deployed on both the Flow and EVM chains. When a user wishes to swap assets, they initiate a transaction that locks their assets in an HTLC on the source chain. This contract specifies a cryptographic hash; the funds can only be unlocked by providing the corresponding secret (preimage) within a set timeframe. If the timelock expires before the secret is revealed, the funds are returned to the original owner.

A critical component of this system is the Next.js-based relayer application, which acts as an off-chain intermediary. The relayer's primary responsibility is to monitor both the Flow and EVM blockchains for HTLC creation events. When an HTLC is detected on one chain (representing an "order" or an intent to swap), the relayer facilitates the creation of a corresponding HTLC on the counterparty chain. This involves taking the hashlock from the first HTLC and using it to set up the second HTLC, ensuring that the same secret controls both locks.

The relayer also observes events related to secret revelation; once the secret is revealed on one chain to claim assets, the relayer propagates this secret to the other chain, allowing the other party to claim their assets. To manage the state of ongoing swaps, transaction details, and potentially user information, the relayer utilizes an SQL database.

This off-chain database helps ensure operational resilience and allows the relayer to track and manage the lifecycle of each swap effectively, including handling timeouts and potential refund scenarios. The use of 1inch's Escrow contracts on the EVM side further provides a secure and audited foundation for those HTLC implementations.

This project was constructed as a cross-chain atomic swap solution, enabling transfers between the Flow blockchain (a non-EVM environment) and an EVM-compatible chain. The core architecture involves smart contracts on both chains, a relayer service to orchestrate the swap, and an off-chain database for state management.

Technologies Used and Integration:

1. Flow Blockchain (Non-EVM Side):

   • Language: Cadence was used to write the smart contracts for the Flow side.
   • Contracts: Key contracts include FungibleTokenHTLC (for managing Hashed Timelock Contracts with fungible tokens), FooToken (a specific fungible token implementation for testing/use), and MinimalHTLC (likely a simplified or core HTLC logic). These contracts handle the initiation or fulfillment of one leg of the swap, locking tokens under specific conditions (hashlock, timelock).
   • Interaction: The flow CLI was used for deploying contracts and executing transactions/scripts on the Flow testnet, as evidenced in docs/notes.md.

2. EVM-Compatible Chain (e.g., Ethereum Sepolia):

   • Contracts: Solidity was used for the EVM smart contracts. The project leverages 1inch's Escrow contracts. Specifically, a MinimalEscrowFactory was deployed, which is responsible for creating instances of source and destination escrow contracts. A MockBooToken (MBOO) was also deployed for use in these escrows.
   • Partner Technology (1inch): The utilization of 1inch's Escrow contracts significantly benefited the project by providing robust, audited, and battle-tested escrow logic. This saved considerable development time and effort that would have been required to build secure escrow mechanisms from scratch, allowing the project to focus on the cross-chain aspects.

3. Relayer Application:

   • Framework: A Next.js application serves as the relayer. This application is crucial for monitoring events on both chains and triggering corresponding actions to progress the swap.
   • Functionality: The relayer likely listens for HTLC creation events on one chain and then initiates the creation of a corresponding escrow or HTLC on the other chain. It would also handle events like secret revelation (for claiming funds) or timeouts (for refunds).

4. Off-Chain Database:

   • Technology: A SQL database is used for off-chain storage.
   • Purpose: This database likely stores metadata about ongoing swaps, such as transaction hashes, user details, swap statuses, corresponding HTLC/escrow IDs across chains, and potentially pre-images or secrets. This allows the relayer to maintain state and recover or continue operations reliably.

How they are pieced together:

The typical flow would involve a user initiating a swap on one chain, which locks their assets in an HTLC (on Flow) or an Escrow (on EVM). The relayer detects this event. It then facilitates the creation of a corresponding contract on the other chain, locking assets for the counterparty. When the secret (preimage of the hashlock) is revealed by one party to claim funds, the relayer ensures this secret is propagated to the other chain, allowing the other party to claim their funds, thus completing the atomic swap. The SQL database helps the relayer keep track of all these steps and manage the state of each swap.

Particularly "Hacky" or Notable Details:

• Simplified Escrow Address Derivation: As noted in our previous discussions, for the EVM side, the initial approach might have involved deterministic address prediction for the destination escrow contract (addressOfEscrowDst). However, to simplify development, especially in a hackathon context, this was changed. Instead of predicting the address, the relayer now likely waits for the createDstEscrow transaction to complete and then derives the escrow address directly from the DstEscrowCreated event emitted by the MinimalEscrowFactory. While less complex, this approach relies on successful event emission and retrieval.