Encoding

The first step to executing a trade on-chain is encoding.

Our Rust crate converts your trades into calldata that the Tycho contracts can execute.

See this Quickstart section for an example of how to encode your trade.

Models

These are the models used as input and output of the encoding crate.

Solution

The Solution struct defines your order and how it should be filled. This is the input to the encoding module.

Attribute	Type	Description
sender	Bytes	Address of the sender of the token in
receiver	Bytes	Address of the receiver of the token out. If set to the TychoRouter address, these funds will be assigned to the user's Vault.
token_in	Bytes	The token being sold
amount_in	BigUint	Amount of the input token
token_out	Bytes	The token being bought.
min_amount_out	BigUint	Minimum amount the receiver must receive at the end of the transaction
swaps	Vec<Swap>	List of swaps to fulfil the solution.
user_transfer_type	UserTransferType	How user funds are transferred into the router (see below)

UserTransferType

Swap

Encoded Solution

Encoder

TychoRouterEncoder prepares calldata for execution via the Tycho Router contract. It supports multi-hop and split swaps.

Builder

Builder options:

• swap_encoder_registry — Registry of protocol-specific SwapEncoder s used during encoding. Use add_default_encoders for built-in support, or add custom encoders for protocols you've implemented locally.

• router_address — Router address for execution. Defaults to the deployed address for the given chain ( see Tycho addresses).

Builder Example Usage

let swap_encoder_registry = SwapEncoderRegistry::new(Chain::Ethereum)
.add_default_encoders(None)
.expect("Failed to get default SwapEncoderRegistry");

let encoder = TychoRouterEncoderBuilder::new()
.chain(Chain::Ethereum)
.swap_encoder_registry(swap_encoder_registry)
.build()
.expect("Failed to build encoder");

Swap Encoders

Each protocol needs its own SwapEncoder to define how the protocol encodes swaps into calldata.

The SwapEncoderRegistry manages these encoders. Call add_default_encoders() to use the built-in implementations. This method accepts an optional executors_addresses JSON string with executor addresses for encoding. Pass None to default to config/executor_addresses.json.

If you need to add custom protocol support, register your own encoder implementation:

registry.register_encoder("my_protocol", Box::new(MyCustomEncoder));

Encode

Convert solutions into calldata:

let encoded_solutions = encoder.encode_solutions(solutions);

This returns a Vec<EncodedSolution> containing only the encoded swaps. It does **not ** build the full calldata. You must encode the full method call yourself. If you use Permit2, you also need to sign the permit object.

The full method call includes the following parameters, which act as execution guardrails:

• amountIn and tokenIn — the amount and token to be transferred into the TychoRouter from you.

• minAmountOut and tokenOut — the minimum amount you want to receive. For maximum security, determine this from a * third-party source*.

• receiver — who receives the final output. Set this to the TychoRouter address to credit output tokens to the vault.

• nTokens — (split swaps only) the number of distinct tokens in the split routing graph.

• clientFeeParams — controls fee-taking and client contribution (see Client Fee Signature below). Pass all-zero values if you don't need fees.

The ClientFeeParams struct is defined as:

Field	Description
clientFeeBps	Fee percentage in basis points. 100 = 1%. Set to 0 to disable.
clientFeeReceiver	Address that receives the client's portion of the fee (credited to their vault balance).
maxClientContribution	Maximum amount the client is willing to pay out of pocket if slippage causes the output to fall below minAmountOut. If the shortfall exceeds this value, the transaction reverts. Set to 0 if the client should not subsidize.
deadline	Unix timestamp after which the signature is no longer valid.
clientSignature	EIP-712 signature over all other fields, signed by clientFeeReceiver.

These execution guardrails protect against MEV exploits. Setting them correctly gives you full control over swap security.

Refer to the quickstart for an example of converting an EncodedSolution into full calldata. Tailor the example to your use case. See the TychoRouter contract functions for reference.

Client Fee Signature

If you don't want fees, pass all-zero values: clientFeeBps: 0, clientFeeReceiver: address(0), maxClientContribution: 0, deadline: 0, and an empty clientSignature.

If you do want fees, the clientFeeReceiver must sign the fee parameters using EIP-712. This prevents third parties from spoofing fee configurations. The signature covers the following typed struct:

ClientFee(uint16 clientFeeBps,address clientFeeReceiver, uint256 maxClientContribution, uint256 deadline)

The EIP-712 domain is:

EIP712Domain(string name,string version, uint256 chainId, address verifyingContract)

with name = "TychoRouter", version = "1", and verifyingContract set to the TychoRouter contract address.

Sign fee parameters example

Example of signing the fee parameters in Rust using alloy:

use alloy::primitives::{keccak256, Address, B256, U256};
use alloy::signers::{local::PrivateKeySigner, SignerSync};
use alloy::sol_types::SolValue;

fn sign_client_fee(
    chain_id: u64,
    router_address: Address,
    client_fee_bps: u16,
    client_fee_receiver: Address,
    max_client_contribution: U256,
    deadline: U256,
    signer: &PrivateKeySigner,
) -> Vec<u8> {
    // Must match CLIENT_FEE_TYPEHASH in TychoRouter.sol
    let type_hash: B256 = keccak256(
        b"ClientFee(uint16 clientFeeBps,address clientFeeReceiver,\
          uint256 maxClientContribution,uint256 deadline)",
    );

    // EIP-712 domain separator
    let domain_type_hash: B256 = keccak256(
        b"EIP712Domain(string name,string version,uint256 chainId,\
          address verifyingContract)",
    );
    let domain_separator: B256 = keccak256(
        (
            domain_type_hash,
            keccak256(b"TychoRouter"),
            keccak256(b"1"),
            U256::from(chain_id),
            router_address,
        )
            .abi_encode(),
    );

    // Struct hash
    let struct_hash: B256 = keccak256(
        (
            type_hash,
            U256::from(client_fee_bps),
            client_fee_receiver,
            max_client_contribution,
            deadline,
        )
            .abi_encode(),
    );

    // EIP-712 digest: keccak256("\x19\x01" ++ domainSeparator ++ structHash)
    let mut data = [0u8; 66];
    data[0] = 0x19;
    data[1] = 0x01;
    data[2..34].copy_from_slice(domain_separator.as_ref());
    data[34..66].copy_from_slice(struct_hash.as_ref());
    let digest: B256 = keccak256(data);

    signer
        .sign_hash_sync(&digest)
        .expect("signing failed")
        .as_bytes()
        .to_vec()
}

The returned 65-byte signature is passed as the clientSignature field in ClientFeeParams.

Run as a Binary

Installation

Build and install the binary:

# Build the project
cargo build --release

# Install the binary to your system
cargo install --path .

After installation, you can use the tycho-encode command from any directory in your terminal.

Commands

The command lets you choose the encoder:

• tycho-router: Encodes a transaction using the TychoRouterEncoder.

The commands accept the same options as the builder (more here).

Example

Encodes a swap from DAI to WETH using Uniswap V2 on Ethereum:

echo '{
  "sender": "0x1234567890123456789012345678901234567890",
  "receiver": "0x1234567890123456789012345678901234567890",
  "token_in": "0x6B175474E89094C44Da98b954EedeAC495271d0F",
  "amount_in": "1000000000000000000",
  "token_out": "0xC02aaA39b223FE8D0A0e5C4F27eAD9083C756Cc2",
  "exact_out": false,
  "min_amount_out": "1",
  "max_client_contribution": "0",
  "user_transfer_type": "TransferFrom",
  "swaps": [
    {
      "component": {
        "id": "0xA478c2975Ab1Ea89e8196811F51A7B7Ade33eB11",
        "protocol_system": "uniswap_v2",
        "protocol_type_name": "uniswap_v2_pool",
        "chain": "ethereum",
        "tokens": [
          "0xC02aaA39b223FE8D0A0e5C4F27eAD9083C756Cc2",
          "0x6B175474E89094C44Da98b954EedeAC495271d0F"
        ],
        "contract_addresses": [],
        "static_attributes": {
          "factory": "0x5c69bee701ef814a2b6a3edd4b1652cb9cc5aa6f"
        },
        "change": "Update",
        "creation_tx": "0x0000000000000000000000000000000000000000000000000000000000000000",
        "created_at": "2024-01-01T00:00:00"
      },
      "token_in": "0x6B175474E89094C44Da98b954EedeAC495271d0F",
      "token_out": "0xC02aaA39b223FE8D0A0e5C4F27eAD9083C756Cc2",
      "split": 0.0
    }
  ]
}' | tycho-encode --chain ethereum tycho-router