Liquidity Request

What is Liquidity Request

Problem

During cross-chain transfer of Native tokens, a situation may arise when there are insufficient tokens on the Native Proxy in the destination network to complete the transfer.

Example: User wants to transfer 1000 USDT from network A to network B. In network B, this is a Native token that needs to be unlocked from Proxy. But Proxy only has 500 USDT — transfer cannot complete.

Solution

Liquidity Request (LR) is a mechanism that allows:

1. Pause the transfer until missing liquidity is received
2. Set a bounty — recipient can offer part of the amount as reward
3. Attract Liquidity Provider — third party who will provide missing tokens

How It Works

1. Sending tokens — user initiates cross-chain transfer from network A to network B
2. Proof verification — Event contract in network B receives and verifies Merkle proof of transaction
3. Unlock attempt — Event contract calls Native Proxy to unlock tokens
4. Insufficient liquidity — Proxy discovers balance is less than required amount and calls notEnoughLiquidity() on Event contract
5. LR creation — Event contract transitions to LiquidityRequested status and emits event

Three ways to resolve LR:

Option	Action	Result
LP provides liquidity	LP sends amount - bounty tokens to Event contract	Recipient gets tokens, LP gets reverse transfer for full amount in source network
User cancels	Sender or recipient calls cancel()	Tokens returned to sender in source network
Retry when liquidity appears	Anyone calls retry() after Proxy is topped up	Transfer completes normally

Key Participants

Participant	Role
Sender	Initiates transfer, can cancel LR
Recipient	Receives tokens, can set bounty, can cancel LR
Liquidity Provider (LP)	Provides missing liquidity for reward
Native Proxy	Contract holding liquidity in destination network

When LR is Created

Transfer Types

Transfer Type	Description	Requires LR?
Native → Alien	Native tokens locked, Alien minted	No — minting doesn't require liquidity
Alien → Native	Alien burned, Native unlocked	Yes — requires liquidity in Proxy
Native → Native	Native via hub network	Yes — requires liquidity

LR Creation Conditions

LR is created automatically when:

1. Transfer is verified and confirmed (Confirmed status) — transaction proof passed cryptographic verification
2. Proxy attempts to send tokens to recipient
3. Proxy balance is less than required amount
4. Proxy calls notEnoughLiquidity() on Event contract

After this, Event contract transitions to LiquidityRequested status and emits LiquidityRequested(bounty) event.

LR Data

Field	Description
token	Token address
amount	Full transfer amount
recipient	Recipient address
sender	Sender address
bounty	Reward for LP (set by recipient)
status	Current LR status

LR Lifecycle

State Diagram

Status Descriptions

Status	What Happens	What Can Be Done
Initializing	Event contract created	Waiting for proof
Pending	Proof sent for verification	Waiting for confirmation
Verified	Verification passed	Waiting for configuration
Confirmed	Transfer confirmed, executing	—
LiquidityRequested	Waiting for LP	Set bounty, cancel, retry
LimitReached	Daily limit reached	Approve, reject, cancel
LiquidityProvided	LP provided liquidity	Final status
Cancelled	Transfer cancelled	Final status
Rejected	Transfer rejected	Final status

Contract Events

Event	When Emitted
LiquidityRequested(bounty)	On LR creation or bounty change
LiquidityProvided(tokenSender)	On successful liquidity provision
Cancelled()	On transfer cancellation
LimitReached(approver)	On reaching daily limit
Rejected()	On transfer rejection

Managing LR

Providing Liquidity (Approve)

Liquidity Provider (LP) can provide missing liquidity:

1. LP sends amount - bounty tokens to Event contract
2. Recipient receives tokens
3. LP receives reverse transfer for full amount in source network

Cancellation (Cancel)

Sender or recipient can cancel LR:

• Status changes to Cancelled
• Reverse transfer to specified address is created
• Tokens returned to source network (minus fees)

Who can cancel:

• Sender (sender)
• Recipient (recipient)
• Limit approver (if status is LimitReached)

Setting Bounty

Recipient or sender can change bounty to attract LP:

• Bounty can be from 0 to full transfer amount
• Higher bounty makes LR more attractive to LP
• On bounty change, LiquidityRequested(newBounty) event is emitted

Retry

If liquidity appeared in Proxy, retry attempt is possible:

• retry() function is called
• Transfer attempts to execute again via Proxy

Who can call retry:

• Sender
• Recipient
• Initializer

Who is Initializer

Initializer is the address that sent the transaction with proof to the destination network and initialized the Event contract. Usually this is:

• The user themselves (via bridge UI)
• Bridge automated service
• Any third party who wants to speed up the transfer

Initializer has the right to call retry() as they already spent gas on Event contract initialization.

Timeouts

There is no explicit timeout for LR in contracts. Liquidity Request can remain in LiquidityRequested status indefinitely.

Errors and Edge Cases

Error Codes Table

Code	Description
2324	Invalid status for operation
2326	takeWalletAddress called not from token root
2331	notEnoughLiquidity called not from Proxy
2332	cancel/setBounty called not by recipient/sender
2333	Bounty > amount
2334	transferNotification called not from token wallet
2335	approveLimit/rejectLimit called not by approver

Edge Cases

LP Competition

If multiple LPs see one LR and send tokens simultaneously:

• First transferNotification with correct amount will be accepted
• Status atomically changes to LiquidityProvided
• All subsequent transactions return tokens to senders

Partial Execution

Cannot send less tokens than amount - bounty. Any amount less than required will be rejected and returned.

LR Without Activity

LR can remain in LiquidityRequested status indefinitely. Solutions:

1. Increase bounty to attract LP
2. Cancel via cancel()
3. Wait for Proxy to be topped up and call retry()

Bounty = 0

With zero bounty, LP must send full amount. This is unattractive (profit = 0), so such LRs are usually not processed.