Ingress: How Chainflip Gets Assets
Ingress is the generic process that enables funds to be sent to the Chainflip Settlement Layer, but is processed slightly differently depending on the intention of the user. The three cases that would induce the ingress process are:
- A user wants to stake $FLIP to the State Chain (for Validator auction bidding, relayer operation, or any other reason);
- A Liquidity provider wants to add liquidity to their position, or;
- A user wants to swap using the Chainflip protocol.
The main commonality between the three cases is Witnessing. All of the above processes rely on the ability for the Validator network to come to consensus about what deposits have actually been made to the vaults. Conceptually, we can say that the Witnessing process is functionally equivalent to a Chainflip-specific Oracle service.
The Statechain can tell Validators what to look at on external chains. Certain contracts on Ethereum, particular wallet addresses on Bitcoin, and a myriad of other addresses and contracts on other chains can all be added to a kind of “watchlist” for the Validators to keep an eye on.
As an essential function of the Settlement Layer, Validators are required to maintain connections to light clients, full nodes, or other kinds of services which allow the Validator to query all Chainflip supported blockchains. The way this is configured is up to each individual operator, but by losing connections to the external blockchains, the Validator will be sent offline until it has resolved the problem.
Once a related transaction to an address or contract on the “watchlist” occurs on the external chain, the Validators must wait until a pre-specified confirmation window has passed. The exact length of the confirmation window (measured in blocks) is assessed on a case-by-case basis for different supported blockchains.
No decentralised interoperability protocol can escape the reality of blockchain finality and are uniquely vulnerable to rollbacks on other chains, thus resulting in a delay before witnessing and processing can occur.
However, as soon as a block is detected on the supported blockchain which causes a deposit to be considered ‘final’ according to the Chainflip protocol’s definition, every Validator in the Authority Set submits a ‘witness’ extrinsic to the State Chain. When over 2/3rds of the Authority Set (100 of 150 in the standard case) have done so, this finalises the witness event. From then on, the State Chain registers the deposit as ‘real,’ and the transaction details such as the TXID, asset, amount, and any relevant metadata are recorded on the State Chain.
If a Validator submitted a witness extrinsic which didn’t align with what other Validators have seen on the supported blockchain, the witness extrinsic would never reach sufficient consensus on the State Chain. This ‘false’ witness could then be used as proof to punish the Validator that submitted it. Similarly, nodes which frequently fail to witness events that the other 2/3rds of Validators catch within a given timeframe could also be grounds to programmatically punish a Validator through Slashing.
Witnessing is effectively how assets are passed through the settlement layer into the accounting layer, and is at the heart of all ingress processes. Let’s look at each one of the three cases that invoke ingress:
$FLIP is an ERC20 token. This means that in order to acquire a balance on the Chainflip State Chain, users have to lock collateral directly in the Stake Manager smart contract.
- 1.The staker submits a transaction to the Ethereum chain that calls a function in the Stake Manager contract that passes in their ChainflipAccountID (a hex representation of a substrate SS58 encoded public key) and the amount of $FLIP tokens being staked.
- 2.The Authority set listens to the Ethereum blockchain for transactions related to the StakeManager contract. Once the staking transaction has been confirmed on the Ethereum network, the Authority Set commences the Witnessing process.
- 3.As the transaction becomes witnessed, the deposit is considered “settled” - and so the account specified in the contract call becomes funded on the State Chain (or conceptually, the “virtual Accounting Layer”) with that amount of $FLIP which can then be used to bid in auctions for Authority set slots as a Validator, or simply to pay for LP or Relay transactions on the State Chain.
Liquidity Providers use a similar process as described above, to add collateral to fund their liquidity positions in the Chainflip AMM. To pass in funds, Liquidity providers need to have an on-chain account for the Chainflip State Chain and refund addresses ready for each asset.
- 1.The liquidity provider creates a State Chain account by staking a nominal amount of $FLIP using the Staking process in Case 1. This is used to pay for State Chain fees.
- 2.The LP then submits an extrinsic to the State Chain requesting a deposit address for each asset it wishes to deposit to use as collateral for their LP position. For example, a BTC-USDC pool would require the LP to submit two extrinsics requesting ingress addresses for BTC and USDC.
- 3.Once confirmed on the State Chain, the Liquidity provider locally derives deterministically generated ingress addresses for both BTC and USDC. This can be done easily by taking the primary multisig key generated by the current Authority Set keys and the confirmed index reserved using the request-ingress extrinsic. In the case of Bitcoin, the result is a Hierarchical Deterministic (HD) wallet address, and in the case of Ethereum for USDC, is an address derived using the CREATE2function, both of which are totally unique to that liquidity provider, but linked to each of the asset’s vaults in the Chainflip Settlement Layer. Read more about Ingress Addressing here.
- 4.The Liquidity provider then sends funds using any wallet to each derived address. The transactions are in turn witnessed by the Validators, resulting in the credit of balances for each asset on the State Chain.
- 5.Finally, the Liquidity provider can submit another extrinsic to utilise the balance of funds available in their State Chain accounts to open a liquidity position, which will then include their funds in the virtual BTC-USDC liquidity pool in the ranges specified by the LP. Ranges can be easily updated by submitting follow up extrinsics to the State Chain.
Finally, and perhaps most importantly, a third type of ingress process is used by users to send funds to be swapped in the virtual Chainflip JIT AMM, although in this case, the requirement to have a State Chain account is circumvented.
- 1.A user requests a swap using a Relayer. A relayer can be run by anyone and is used to bypass the need for on-chain accounts. All the user needs to provide is the asset they have, the asset they want, and a Payout Address where they wish their funds to be sent to after their funds have been swapped. Relayers are covered in more detail in the Appendix. The Relayer submits this information to the State Chain as a Swap Intent extrinsic.
- 2.Once the swap intent is included in a State Chain block, the user can once again locally derive a Swap Address unique to their swap intent.
- 3.If they send funds of the correct asset to that address, the Authority Set will witness the deposit and automatically begin the process of swapping the asset through the event driven Chainflip JIT AMM.