Contract Reference

The Aori protocol is implemented through a set of smart contracts that handle order management, cross-chain messaging, and settlement. This reference provides comprehensive documentation of the contract interfaces and their functionality.

Core Contracts

Aori.sol

The main protocol contract that implements all trading functionality for both single-chain and cross-chain operations.

Contract Address: Deployed on all supported chains
Interface: IAori.sol
Dependencies: LayerZero OApp, OpenZeppelin utilities

Data Structures

Order

The fundamental data structure representing a trading intent.

Order Struct

struct Order {
    uint128 inputAmount;      // Amount of input token to send
    uint128 outputAmount;     // Amount of output token to receive
    address inputToken;       // Input token contract address
    address outputToken;      // Output token contract address
    uint32 startTime;         // Unix timestamp when order becomes valid
    uint32 endTime;           // Unix timestamp when order expires
    uint32 srcEid;            // Source chain LayerZero endpoint ID
    uint32 dstEid;            // Destination chain LayerZero endpoint ID
    address offerer;          // Address that created the order
    address recipient;        // Address to receive output tokens
}

Order Status

Orders progress through distinct states during their lifecycle.

OrderStatus Enum

enum OrderStatus {
    Unknown,    // Order not found in the system
    Active,     // Order deposited, tokens locked, awaiting fill
    Filled,     // Order filled on destination, pending settlement
    Cancelled,  // Order cancelled, tokens available for withdrawal
    Settled     // Order completed, tokens transferred to solver
}

Hook Structures

Hooks enable custom logic execution during order processing.

Hook Structs

struct SrcHook {
    address hookAddress;                    // Hook contract address
    address preferredToken;                 // Preferred output token
    uint256 minPreferedTokenAmountOut;     // Minimum output amount
    bytes instructions;                     // Custom hook instructions
}

struct DstHook {
    address hookAddress;                    // Hook contract address
    address preferredToken;                 // Preferred token type
    bytes instructions;                     // Custom hook instructions
    uint256 preferedDstInputAmount;        // Preferred input amount
}

Core Functions

Source Chain Functions

Functions available on the chain where orders originate.

deposit()

Locks user tokens and activates an order for cross-chain or delayed single-chain settlement.

Deposit Functions

// Basic deposit
function deposit(Order calldata order, bytes calldata signature) external;

// Deposit with source chain hook
function deposit(
    Order calldata order,
    bytes calldata signature,
    SrcHook calldata hook
) external;

Parameters:

order: The order to be deposited
signature: User's signature authorizing the order
hook: Optional hook configuration for custom logic

Effects:

Transfers input tokens from user to contract
Marks order as Active
Emits Deposit event

withdraw()

Allows users and solvers to withdraw their unlocked token balances.

Withdraw Function

function withdraw(address token) external;

Parameters:

token: Address of the token to withdraw

Effects:

Transfers unlocked balance to caller
Emits Withdraw event

cancel()

Cancels an active order on the source chain.

Cancel Function

function cancel(bytes32 orderId) external;

Parameters:

orderId: Hash of the order to cancel

Effects:

Marks order as Cancelled
Unlocks user's tokens for withdrawal
Emits Cancel event

Destination Chain Functions

Functions available on the chain where orders are fulfilled.

fill()

Fulfills an order by providing the required output tokens.

Fill Functions

// Basic fill
function fill(Order calldata order) external;

// Fill with destination hook
function fill(Order calldata order, DstHook calldata hook) external;

Parameters:

order: The order to fill
hook: Optional hook configuration

Effects:

Transfers output tokens from solver to recipient
Records fill for settlement
Emits Fill event

settle()

Settles filled orders by sending confirmation to the source chain.

Settle Function

function settle(
    uint32 srcEid,
    address filler,
    bytes calldata extraOptions
) external payable;

Parameters:

srcEid: Source chain endpoint ID
filler: Address of the order filler
extraOptions: LayerZero messaging options

Effects:

Sends settlement message to source chain
Emits SettleSent event with MessagingReceipt data

cancel() (Destination)

Cancels an expired order from the destination chain.

Destination Cancel

function cancel(
    bytes32 orderId,
    Order calldata orderToCancel,
    bytes calldata extraOptions
) external payable;

Parameters:

orderId: Hash of the order to cancel
orderToCancel: Full order data
extraOptions: LayerZero messaging options

Effects:

Sends cancellation message to source chain
Emits CancelSent event

Single-Chain Functions

Optimized functions for same-chain trading.

swap()

Executes an atomic single-chain swap.

Swap Function

function swap(Order calldata order, bytes calldata signature) external;

Parameters:

order: The swap order (srcEid == dstEid)
signature: User's authorization signature

Effects:

Transfers input tokens from user to contract
Transfers output tokens from solver to recipient
Credits input tokens to solver
Marks order as Settled

View Functions

Balance Queries

Balance Functions

function getLockedBalances(address holder, address token) 
    external view returns (uint256);

function getUnlockedBalances(address holder, address token) 
    external view returns (uint256);

Utility Functions

// Generate order hash
function hash(Order calldata order) external pure returns (bytes32);

// Quote LayerZero fees
function quote(
    uint32 _dstEid,
    uint8 _msgType,
    bytes calldata _options,
    bool _payInLzToken,
    uint32 _srcEid,
    address _filler
) external view returns (uint256 fee);

Events

Source Chain Events

Source Events

event Deposit(bytes32 indexed orderId, Order order);
event Cancel(bytes32 indexed orderId);
event Settle(bytes32 indexed orderId);
event Withdraw(address indexed holder, address indexed token, uint256 amount);

Destination Chain Events

Destination Events

event Fill(bytes32 indexed orderId, Order order);

event SettleSent(
    uint32 indexed srcEid,
    address indexed filler,
    bytes payload,
    bytes32 guid,
    uint64 nonce,
    uint256 fee
);

event CancelSent(
    bytes32 indexed orderId,
    bytes32 guid,
    uint64 nonce,
    uint256 fee
);

Chain Management Events

Management Events

event ChainSupported(uint32 indexed eid);
event ChainRemoved(uint32 indexed eid);
event settlementFailed(
    bytes32 indexed orderId,
    uint32 expectedEid,
    uint32 submittedEid,
    string reason
);

Common Errors

The contract implements comprehensive error handling for various failure scenarios:

Invalid Signatures: Orders with invalid or expired signatures are rejected
Timing Violations: Orders outside their validity window are rejected
Insufficient Balances: Operations requiring tokens check balance availability
Chain Mismatches: Cross-chain operations validate endpoint IDs
Settlement Failures: Failed settlements are logged but don't revert batches