The conditional transfer flow

conditional transfers

Conditional transfers are off-chain transfers that are valid only if an on-chain event occurred. Use cases of conditional transfers include:

Fast Withdrawals

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

Swap assets at Uniswap

Alice doesn’t like the current ETH/DAI ratio in the off-chain app, and wants to take advantage of a particularly high ETH price on Uniswap. She signs an off-chain 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 off-chain 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 on-chain transaction registers the fact

The operator sends an on-chain 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 off-chain conditional transfer is only valid after the required amount of funds are transferred to her on-chain 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 ConditionalTransferRequest 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 on-chain along with a validity proof. The stateUpdate on-chain 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 on-chain condition.

Implementing a conditional transfer in your application

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

The StarkEx REST API reference includes all necessary information.

Additional resources