LIP Integration Guide

LiquidsFi Interoperability Protocol — Soroban ↔ EVM Integration

The LiquidsFi Interoperability Protocol (LIP) enables secure cross-chain messaging and bridging between Soroban (Stellar) and EVM chains. LIP supports both fungible token transfers and NFT / arbitrary-data transfers through the same oracle messaging primitive.

This page explains how to integrate LIP for both scenarios.

---

1. Overview of Some Integration Types

Integration Type	Purpose	Data Sent	Main Logic
Fungible Token Bridge	Move tokens between Soroban ↔ EVM	amount, token addresses, decimals, recipient	lock/mint, burn/release, rebalance
NFT Bridge	Transfer unique assets	tokenId and attributes	burn/mint wrappers, attribute propagation
Arbitrary Data Messaging	Send any structured payload	custom fields	generic message receiver

Both integrations follow the same LIP flow:

1. Origin contract encodes payload

2. Oracle network validates and relays it

3. Destination contract receives the finalized payload

What changes between FT and NFT bridging is simply the payload schema, not the oracle flow.

---

2. Integration Architecture

Soroban Contract Integration

You will implement:

• Outgoing messages: lip_data_send

• Incoming messages: on_oracle_data

EVM Contract Integration

Covered in a later section — similar patterns apply.

---

3. Fungible Token Bridging (FT Bridge)

This section provides a dedicated fungible-token bridging integration.

---

3.1 Payload Structure

For FT transfers, LIP sends:

Index	Field	Type	Description
0	recipient	address/string	Address on destination chain
1	destToken	address	Token address on destination
2	amount	uint256	Token amount
3	decimals	uint256	Source token decimals
4	isRebalance	bool	Whether transfer is rebalance or user withdrawal

---

3.2 Outgoing Transfer Function (Soroban → EVM)

A polished generic version of your function:

fn bridge_ft_to_evm(
    e: Env,
    user: Address,
    dest_chain_id: u64,
    recipient: String,
    token_id: Address,
    amount: i128,
    is_rebalance: bool,
) -> Result<(), ContractError> {
    // 1. Auth
    user.require_auth();

    // 2. Check token support
    if !read_token_is_supported(&e, token_id.clone()) {
        return Err(ContractError::TokenNotSupported);
    }

    // 3. Apply liquidity + bridge fees
    let liquidity_fee = calculate_liquidity_fee(&e, token_id.clone(), amount);
    take_token(&e, &token_id, &user, amount + liquidity_fee);
    write_total_liquidity_fee_collected(&e, token_id.clone(), liquidity_fee);

    let fee = read_bridge_fee_details(&e).unwrap();
    take_token(&e, &fee.token, &user, fee.rate);
    write_total_bridge_fee_collected(&e, fee.rate);

    // 4. Update internal balances
    write_total_balance(&e, token_id.clone(), amount);

    // 5. Prepare payload
    let payload: Vec<Val> = vec![
        &e,
        recipient.into_val(&e),
        read_dest_token(e.clone(), token_id.clone(), dest_chain_id).into_val(&e),
        amount.into_val(&e),
        read_token_decimal(&e, token_id.clone()).into_val(&e),
        is_rebalance.into_val(&e),
    ];

    let types: Vec<Val> = vec![
        &e,
        String::from_str(&e, "address").into_val(&e),
        String::from_str(&e, "address").into_val(&e),
        String::from_str(&e, "uint256").into_val(&e),
        String::from_str(&e, "uint256").into_val(&e),
        String::from_str(&e, "bool").into_val(&e),
    ];

    // 6. Send to oracle
    let args: Vec<Val> = vec![
        &e,
        dest_chain_id.into_val(&e),
        user.into_val(&e),
        e.current_contract_address().into_val(&e),
        read_dest_chain_client(e.clone(), dest_chain_id).into_val(&e),
        payload.into_val(&e),
        types.into_val(&e),
    ];

    e.invoke_contract(&read_oracle(&e), &Symbol::new(&e, "lip_data_send"), args);

    Ok(())
}

---

3.3 Incoming FT Transfer (EVM → Soroban)

fn on_oracle_data_ft(
    e: Env,
    tx_id: Bytes,
    origin_client: String,
    data: Vec<Val>,
) -> Result<(), ContractError> {

    // 1. Auth check
    read_oracle(&e).require_auth();

    // 2. Replay prevention
    if tx_id_processed(&e, tx_id.clone()) {
        panic!("already processed");
    }

    // 3. Validate origin
    if !is_allowed_origin(&e, origin_client.clone()) {
        panic!("origin not allowed");
    }

    // 4. Decode FT payload
    let recipient: Address = Address::from_val(&e, &data.get_unchecked(0));
    let token_id: Address = Address::from_val(&e, &data.get_unchecked(1));
    let raw_amount: i128 = i128::from_val(&e, &data.get_unchecked(2));
    let decimals: u32 = u32::from_val(&e, &data.get_unchecked(3));
    let is_rebalance: bool = bool::from_val(&e, &data.get_unchecked(4));

    // 5. Supported token check
    if !read_token_is_supported(&e, token_id.clone()) {
        return Err(ContractError::TokenNotSupported);
    }

    // 6. Normalize decimals
    let local_decimals = read_token_decimal(&e, token_id.clone());
    let amount = (raw_amount * 10_i128.pow(local_decimals)) / 10_i128.pow(decimals);

    // 7. Execute bridge logic
    if is_rebalance {
        send_token(&e, &token_id, &recipient, amount);
        write_total_balance(&e, token_id.clone(), -amount);
    } else {
        send_token(&e, &token_id, &recipient, amount);
        write_total_balance(&e, token_id.clone(), amount);
    }

    // 8. Finalize
    write_tx_processed(&e, tx_id);

    Ok(())
}

---

4. NFT / Arbitrary Data Bridging (NFT Bridge)

NFTs require a different payload schema, but the oracle flow is identical.

---

4.1 NFT Payload Structure

Index	Field	Type	Description
0	recipient	address/string	Destination owner
1	collection	address	NFT contract on destination
2	tokenId	uint256	The NFT identifier
3	metadata	bytes/string	Optional metadata blob
4	attributes	array	Arbitrary attributes

NFT payloads are intentionally flexible for project-defined metadata.

---

4.2 Outgoing NFT Transfer (Soroban → EVM)

fn bridge_nft_to_evm(
    e: Env,
    user: Address,
    dest_chain_id: u64,
    recipient: String,
    collection: Address,
    token_id: u128,
    metadata: Bytes,
    attributes: Vec<Val>,
) -> Result<(), ContractError> {
    user.require_auth();

    // Burn or lock NFT on Soroban
    burn_nft(&e, &collection, token_id);

    // Encode NFT payload
    let payload: Vec<Val> = vec![
        &e,
        recipient.into_val(&e),
        read_dest_collection(e.clone(), collection.clone(), dest_chain_id).into_val(&e),
        token_id.into_val(&e),
        metadata.into_val(&e),
        attributes.into_val(&e),
    ];

    let types: Vec<Val> = vec![
        &e,
        String::from_str(&e, "address").into_val(&e),
        String::from_str(&e, "address").into_val(&e),
        String::from_str(&e, "uint256").into_val(&e),
        String::from_str(&e, "bytes").into_val(&e),
        String::from_str(&e, "array").into_val(&e),
    ];

    let args: Vec<Val> = vec![
        &e,
        dest_chain_id.into_val(&e),
        user.into_val(&e),
        e.current_contract_address().into_val(&e),
        read_dest_chain_client(e.clone(), dest_chain_id).into_val(&e),
        payload.into_val(&e),
        types.into_val(&e),
    ];

    e.invoke_contract(&read_oracle(&e), &Symbol::new(&e, "lip_data_send"), args);

    Ok(())
}

---

4.3 Incoming NFT Transfer (EVM → Soroban)

fn on_oracle_data_nft(
    e: Env,
    tx_id: Bytes,
    origin_client: String,
    data: Vec<Val>,
) -> Result<(), ContractError> {

    read_oracle(&e).require_auth();

    if tx_id_processed(&e, tx_id.clone()) {
        panic!("already processed");
    }

    if !is_allowed_origin(&e, origin_client.clone()) {
        panic!("origin not allowed");
    }

    // Decode NFT payload
    let recipient: Address = Address::from_val(&e, &data.get_unchecked(0));
    let collection: Address = Address::from_val(&e, &data.get_unchecked(1));
    let token_id: u128 = u128::from_val(&e, &data.get_unchecked(2));
    let metadata: Bytes = Bytes::from_val(&e, &data.get_unchecked(3));
    let attributes: Vec<Val> = Vec::<Val>::from_val(&e, &data.get_unchecked(4));

    // Mint NFT on Soroban
    mint_nft(&e, &collection, &recipient, token_id, metadata, attributes);

    write_tx_processed(&e, tx_id);

    Ok(())
}

---

5. Summary: FT vs NFT Integration

Step	FT Bridge	NFT Bridge
Lock/burn on origin	tokens deducted	NFT burned/locked
Payload content	token data	NFT ID + metadata
Decoding	amount + decimals	tokenId + attributes
Destination logic	mint/release	mint NFT replica
Oracle flow	identical	identical

---

6. Notes for Developers

• LIP allows arbitrary structured data

• Payload size is optimized and validated by oracle nodes

• Developers may extend schemas for:

  • cross-chain governance

  • multi-chain account linking

  • multi-chain DeFi operations