The conditional transfer flow

conditional transfers

Conditional transfers are offchain transfers that are valid only if an onchain event occurred. Use cases of conditional transfers include:

Fast Withdrawals

Alice wants to receive money onchain without waiting for a proof. In the regular withdrawal flow, the funds become available onchain only once the proof is accepted onchain. She signs a conditional transfer, giving 1000 USDC to a liquidity provider’s offchain vault, conditional on getting 1000 USDC minus a fee, from the liquidity provider’s onchain Ethereum address to her onchain Ethereum address.
Swap assets at Uniswap

Alice doesn’t like the current ETH/DAI ratio in the offchain app, and wants to take advantage of a particularly high ETH price on Uniswap. She signs an offchain conditional transfer, giving 1 ETH to a liquidity provider’s vault. This transfer takes place only if the liquidity provider deposits to StarkEx the amount of DAI that Alice expects to receive for 0.99 ETH on Uniswap.

1. Alice sends a conditional transfer request to the application

Alice sends a conditional transfer request using the offchain application. The request includes the same information as for a non-conditional transfer request, as well as the following:

  • An address of a smart contract on Ethereum. This contract should implement the Fact Registry pattern.

  • A fact that should be registered in the smart contract.

Technically, the condition for executing the transfer is a Keccak hash of fact_registry_address and fact.

Alice knows that her transaction is valid only if the fact in the smart contract is true, and the application can execute it.

The Fact Registry contract is external to the StarkEx system and can have arbitrary logic. Users should verify the contract to ensure it implements the conditional logic they expect.

2. An onchain transaction registers the fact

The operator sends an onchain transaction to the Fact Registry contract. If the fact is true, the transaction results in the registration of the fact as valid.

In the above example of a fast withdrawal, the fact is the hash of Alice’s Ethereum address, the type of token, and the amount. When the operator sends a transaction to the Fact Registry contract, the contract first transfers the necessary amount of funds from the sender to Alice’s Ethereum address, and then registers the fact as true.

Alice knows that her offchain conditional transfer is only valid after the required amount of funds are transferred to her onchain address.

3. The application sends the conditional transfer transaction to StarkEx

After the fact is registered as true in the Fact Registry, the application sends the conditional transfer transaction to the StarkEx gateway, using the add_transaction API with the ConditionalTransfer transaction type.

4. StarkEx validates the transfer request.

StarkEx validates the conditional transfer request by checking the same data as in a non-conditional transfer request.

5. The conditional transfer is included in a batch

If the transaction is valid, it is included in a batch to be submitted onchain along with a validity proof. The stateUpdate onchain transaction includes the address and the fact as calldata. If the fact is not registered as true, the state update is rejected, ensuring that the transfer does not occur without first satisfying the onchain condition.

Implementing a conditional transfer in your application

To implement conditional transfer functionality in your application, use the add_transaction API with the ConditionalTransfer transaction type.

The StarkEx REST API reference includes all necessary information.

Additional resources