Overview

In the Architecture Overview, we explored the core components that make up the Euclid Unified Liquidity layer. This section covers the Solidity (EVM) smart contracts that power Euclid on EVM-compatible chains.

Since the Factory smart contract is the only entry point for users/projects to interact with the Euclid layer, we will be providing a breakdown of the execute messages as well as the queries. For the rest of the contracts, no messages can be called directly on them so we are only interested in the available queries.

Common Types

A list of structs that are used in many of our contracts.

TokenWithDenom

Represents a token identifier along with its token type (native, smart, or voucher).

struct TokenWithDenom {
    string token;        
    TokenType token_type; 
}

Field	Type	Description
token	string	The token Id for the token (e.g., "usdc", "weth", "dai").
token_type	TokenType	The token's type (native, smart, or voucher).

PairWithDenom

Defines a token pair. Each token includes its name and token type.

struct PairWithDenom {
    TokenWithDenom token_1;
    TokenWithDenom token_2;
}

{
  "pair_with_denom": {
    "token_1": {
      "token": "amoy",
      "token_type": {
        "native": {
          "denom": "pol"
        }
      }
    },
    "token_2": {
      "token": "euclid",
      "token_type": {
        "smart": {
          "contract_address": "0x1e..."
        }
      }
    }
  }
}

Field	Description
token_1	Information about the first token.
token_2	Information about the second token.

PairWithDenomAndAmount

Specifies a token pair, their denoms, and an amount for each. Used when adding liquidity to a pool.

struct PairWithDenomAndAmount {
    TokenWithDenomAndAmount token_1;
    TokenWithDenomAndAmount token_2;
}

struct TokenWithDenomAndAmount {
    string token;
    uint256 amount;
    TokenType token_type;
}

Field	Type	Description
token_1	TokenWithDenomAndAmount	First token in the pair.
token_2	TokenWithDenomAndAmount	Second token in the pair.

TokenWithDenomAndAmount

Field	Type	Description
token	string	The internal token ID (e.g., "usdc", "eth").
amount	uint256	The amount of the token being added to the pool.
token_type	TokenType	Specifies if the token is native, smart contract, or voucher.

TokenType

Defines the type and source of a token used in the Euclid protocol.

enum TokenTypeEnum {
    Native,
    Smart,
    Voucher
}
struct TokenType {
    TokenTypeEnum tokenType;
    string denom;           
    address contractAddress; 
}

Field	Type	Description
tokenType	TokenTypeEnum	The type of token: Native, Smart, or Voucher.
denom	string	The denomination (only used for native tokens).
contractAddress	address	The ERC20 contract address (only used for smart tokens).

TokenWithDenomAndAmount

Used when providing liquidity or other functions that require a token, amount, and type.

struct TokenWithDenomAndAmount {
    string token;
    uint256 amount;
    TokenType token_type;
}

Field	Type	Description
token	string	The token ID/name.
amount	uint256	Amount of the token.
token_type	TokenType	Whether the token is native, smart-based, or voucher.

Pair

Token pair consisting of two token IDs.

struct Pair {
    string token_1;
    string token_2;
}

Field	Type	Description
token_1	string	ID of the first token in the pair.
token_2	string	ID of the second token in the pair.

---

CrossChainUser

Represents a user address on a different blockchain.

struct CrossChainUser {
    string chain_uid;
    string address;
}

Field	Type	Description
chain_uid	string	Unique identifier of the target chain.
address	string	The user’s address on that chain.

---

CrossChainUserWithLimit

An extension of CrossChainUser that adds an optional withdrawal limit, refund fallback, and optional message forwarding.

struct CrossChainUserWithLimit {
    CrossChainUser user;
    Limit limit;
    TokenType preferred_denom;
    string refund_address;
    EuclidReceive forwarding_message;
}

 struct EuclidReceive {
     //Encoded message to be executed on the destination
    bytes data;
    // Optional metadata to log with the transaction
    string meta;
    }

struct Limit {
    LimitType limitType;
    uint256 value;
}

    enum LimitType {
    LessThanOrEqual,
    Equal,
    GreaterThanOrEqual
}

{
  "user": {
    "chain_uid": "amoy",
    "address": "0x123abc..."
  },
  "limit": {
    "limitType": "LessThanOrEqual",
    "value": "1000000"
  },
  "preferred_denom": {
    "native": {
      "denom": "usdc"
    }
  },
  "refund_address": "0x123abc...",
  "forwarding_message": {
    "data": "0xabcdef123456...",
    "meta": "some-meta"
  }
}

Field	Type	Description
user	CrossChainUser	The destination user and their chain UID.
limit	Limit	Optional constraint on how much to release to the user.
preferred_denom	TokenType	Preferred token format/type for receiving assets (native, smart, or voucher).
refund_address	string	Optional refund address if transaction fails. Defaults to sender if omitted.
forwarding_message	EuclidReceive	Optional message to be executed on the receiver's side post-transfer.

LimitType

Defines how much a cross-chain recipient is allowed or required to receive during fund distribution. This enum is used inside the limit field of a CrossChainUserWithLimit.

• LessThanOrEqual: This is the most flexible option. It allows the recipient to receive up to the specified amount, but not more. If the total available is less than the limit, the contract will still send whatever it can. This is useful when distributing across multiple recipients. For example, if two addresses both have a limit of 1000 and 1500 is available, firt one will receive 1000, and the other 500.

• Equal: This enforces that the recipient must receive exactly the specified amount. If that exact amount isn’t available, the transaction will fail. This is used when an exact value is required and partial delivery is not acceptable.

• GreaterThanOrEqual: This option guarantees that the recipient receives at least the specified amount. If the amount available is less than the specified minimum, the transaction fails. It’s useful for recipients that need a minimum amount to trigger a downstream action (like a forwarding message). Typically, this is used on the last or only recipient in the list.

Pagination

Used in query messages to paginate responses.

struct Pagination {
    uint256 min;
    uint256 max;
    uint64 skip;
    uint64 limit;
}

Field	Type	Description
min	uint256	Lower bound filter (inclusive).
max	uint256	Upper bound filter (inclusive).
skip	uint64	How many records to skip.
limit	uint64	Max number of results to return.