EVM - Garden Docs

Contract architecture

Garden uses Hashed Time Lock Contracts (HTLCs) to implement atomic swap functionality on EVM chains. The contract manages the lifecycle of a swap through four main operations with enhanced signature support and flexible initiation methods:

Initiate

Redeem

Refund

Instant refund

Core functions

Initiate

The initiate function creates a new HTLC by locking tokens in the contract. EVM provides different implementations for ERC20 tokens vs. native ETH:

Basic initiation

function initiate(
    address redeemer,
    uint256 timelock,
    uint256 amount,
    bytes32 secretHash
) external

function initiate(
    address payable redeemer,
    uint256 timelock,
    uint256 amount,
    bytes32 secretHash
) external payable

Initiation on behalf

function initiateOnBehalf(
    address initiator,
    address redeemer,
    uint256 timelock,
    uint256 amount,
    bytes32 secretHash
) external

function initiateOnBehalf(
    address payable initiator,
    address payable redeemer,
    uint256 timelock,
    uint256 amount,
    bytes32 secretHash
) external payable

Signature-based initiation (ERC20 only)

function initiateWithSignature(
    address initiator,
    address redeemer,
    uint256 timelock,
    uint256 amount,
    bytes32 secretHash,
    bytes calldata signature
) external

Uses EIP712 signatures for off-chain authorization, enabling gasless transactions where authorized third parties can initiate swaps on behalf of users.

Redeem

The redeem function allows the redeemer to claim the locked tokens by providing the secret that hashes to the stored secret hash.

function redeem(
    bytes32 orderID,
    bytes calldata secret
) external

function redeem(
    bytes32 orderID,
    bytes calldata secret
) external

The secret must hash to the exact value stored during initiation using SHA256. Once revealed, this secret enables the counterparty to claim funds on the other chain. No signature required - anyone can execute if they know the secret.

Refund

The refund function allows the initiator to reclaim their tokens after the timelock has expired and the redeemer has not claimed the funds.

function refund(bytes32 orderID) external

function refund(bytes32 orderID) external

Uses absolute block numbers for timelock, which provides predictable settlement windows based on consistent block production times.

Instant refund

The instant refund function provides a way for the redeemer to consent to canceling the swap before the timelock expires using EIP712 signatures.

function instantRefund(
    bytes32 orderID,
    bytes calldata signature
) external

function instantRefund(
    bytes32 orderID,
    bytes calldata signature
) external

This requires the redeemer’s EIP712 signature to prevent unauthorized instant refunds. This ensures mutual consent before the settlement window expires.

EVM-specific features

Order state management

Both contracts use a struct to store swap state with different address types for native vs. ERC20 handling:

struct Order {
    address initiator;
    address redeemer;
    uint256 initiatedAt;
    uint256 timelock;
    uint256 amount;
    uint256 fulfilledAt;
}

struct Order {
    address payable initiator;
    address payable redeemer;
    uint256 initiatedAt;
    uint256 timelock;
    uint256 amount;
    uint256 fulfilledAt;
}

Token handling differences

ERC20 implementation:

Uses SafeERC20 for secure token transfers.
Requires token approval before initiation.
Transfers tokens via transferFrom and transfer.

Native ETH implementation:

Uses payable functions and msg.value.
Direct ETH transfers via .transfer().
No approval required.

The native ETH version simplifies the user experience by eliminating the need for token approvals, while the ERC20 version provides compatibility with all standard tokens.

EIP712 signature support

Both contracts implement EIP712 for secure off-chain message signing:

bytes32 private constant _REFUND_TYPEHASH = keccak256("Refund(bytes32 orderId)");

function instantRefundDigest(bytes32 orderID) public view returns (bytes32) {
    return _hashTypedDataV4(keccak256(abi.encode(_REFUND_TYPEHASH, orderID)));
}

Event logging

Both contracts emit identical events for each state transition to enable efficient off-chain monitoring:

event Initiated(bytes32 indexed orderID);
event Redeemed(bytes32 indexed orderID, bytes secret);
event Refunded(bytes32 indexed orderID);

Order ID generation

Unique order identifiers are generated using SHA256 hashing with chain-specific parameters:

bytes32 orderID = sha256(abi.encode(
    block.chainid, 
    secretHash, 
    initiator, 
    redeemer, 
    timelock, 
    amount
));

Chain ID inclusion prevents cross-chain replay attacks, while the parameter combination ensures each order is uniquely identifiable across the network.

​Contract architecture

Initiate

Redeem

Refund

Instant refund

​Core functions

​Initiate

​Basic initiation

​Initiation on behalf

​Signature-based initiation (ERC20 only)

​Redeem

​Refund

​Instant refund

​EVM-specific features

​Order state management

​Token handling differences

​EIP712 signature support

​Event logging

​Order ID generation

Contract architecture

Core functions

Initiate

Basic initiation

Initiation on behalf

Signature-based initiation (ERC20 only)

Redeem

Refund

Instant refund

EVM-specific features

Order state management

Token handling differences

EIP712 signature support

Event logging

Order ID generation