The conditional transfer flow
Conditional transfers are off-chain transfers that are valid only if an on-chain event occurred. Use cases of conditional transfers include:
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 as the condition for executing the transfer.
Technically, the condition is a Keccak hash of
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
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
ConditionalTransfer transaction type.
The StarkEx REST API reference includes all necessary information.
StarkEx REST API reference
Message encoding for the structure of a conditional transfer
StarkEx validates the transfer request in The transfer flow
StarkExchange: Fast Withdrawals using Cookie Jars on Medium.