Skip to main content

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; 
}
FieldTypeDescription
tokenstringThe token Id for the token (e.g., "usdc", "weth", "dai").
token_typeTokenTypeThe 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..."
        }
      }
    }
  }
}
FieldDescription
token_1Information about the first token.
token_2Information 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;
}
FieldTypeDescription
token_1TokenWithDenomAndAmountFirst token in the pair.
token_2TokenWithDenomAndAmountSecond token in the pair.

TokenWithDenomAndAmount

FieldTypeDescription
tokenstringThe internal token ID (e.g., "usdc", "eth").
amountuint256The amount of the token being added to the pool.
token_typeTokenTypeSpecifies 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; 
}
FieldTypeDescription
tokenTypeTokenTypeEnumThe type of token: Native, Smart, or Voucher.
denomstringThe denomination (only used for native tokens).
contractAddressaddressThe 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;
}
FieldTypeDescription
tokenstringThe token ID/name.
amountuint256Amount of the token.
token_typeTokenTypeWhether the token is native, smart-based, or voucher.

Pair

Token pair consisting of two token IDs.

struct Pair {
    string token_1;
    string token_2;
}
FieldTypeDescription
token_1stringID of the first token in the pair.
token_2stringID of the second token in the pair.

CrossChainUser

Represents a user address on a different blockchain.

struct CrossChainUser {
    string chain_uid;
    string address;
}
FieldTypeDescription
chain_uidstringUnique identifier of the target chain.
addressstringThe 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"
  }
}
FieldTypeDescription
userCrossChainUserThe destination user and their chain UID.
limitLimitOptional constraint on how much to release to the user.
preferred_denomTokenTypePreferred token format/type for receiving assets (native, smart, or voucher).
refund_addressstringOptional refund address if transaction fails. Defaults to sender if omitted.
forwarding_messageEuclidReceiveOptional 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;
}
FieldTypeDescription
minuint256Lower bound filter (inclusive).
maxuint256Upper bound filter (inclusive).
skipuint64How many records to skip.
limituint64Max number of results to return.