From 5889b06d566c4ddec2f157ea8ff0d0e7325cad40 Mon Sep 17 00:00:00 2001 From: Denis Fadeev Date: Wed, 9 Aug 2023 18:31:14 +0400 Subject: [PATCH] docs: state transition diagrams for cctx status (#755) * docs: state transition diagrams for cctx status * Update docs/spec/crosschain/messages.md Co-authored-by: Lucas Bertrand * replace Uniswap pool with contract instance * replace was with is * replace was with is * remove dot at the end * make specs * added EVM refund * make specs * overview: sidebar_position: 1 * make generate --------- Co-authored-by: Lucas Bertrand --- docs/spec/crosschain/messages.md | 86 ++++++++++++++----- docs/spec/crosschain/overview.md | 4 + docs/spec/emissions/overview.md | 4 + docs/spec/fungible/overview.md | 4 + docs/spec/observer/overview.md | 4 + .../keeper_cross_chain_tx_vote_inbound_tx.go | 39 +++++++-- .../keeper_cross_chain_tx_vote_outbound_tx.go | 45 ++++++---- 7 files changed, 143 insertions(+), 43 deletions(-) diff --git a/docs/spec/crosschain/messages.md b/docs/spec/crosschain/messages.md index ced6c54042..e02d171736 100644 --- a/docs/spec/crosschain/messages.md +++ b/docs/spec/crosschain/messages.md @@ -87,27 +87,42 @@ message MsgNonceVoter { Casts a vote on an outbound transaction observed on a connected chain (after it has been broadcasted to and finalized on a connected chain). If this is the first vote, a new ballot is created. When a threshold of votes is -reached, the ballot is finalized. When a ballot is finalized, if the amount -of zeta minted does not match the outbound transaction amount an error is -thrown. If the amounts match, the outbound transaction hash and the "last -updated" timestamp are updated. +reached, the ballot is finalized. When a ballot is finalized, the outbound +transaction is processed. -The transaction is proceeded to be finalized: - -If the observation was successful, the status is changed from "pending -revert/outbound" to "reverted/mined". The difference between zeta burned +If the observation is successful, the difference between zeta burned and minted is minted by the bank module and deposited into the module account. -If the observation was unsuccessful, and if the status is "pending outbound", -prices and nonce are updated and the status is changed to "pending revert". -If the status was "pending revert", the status is changed to "aborted". - -If there's an error in the finalization process, the CCTX status is set to -'aborted'. +If the observation is unsuccessful, the logic depends on the previous +status. + +If the previous status was `PendingOutbound`, a new revert transaction is +created. To cover the revert transaction fee, the required amount of tokens +submitted with the CCTX are swapped using a Uniswap V2 contract instance on +ZetaChain for the ZRC20 of the gas token of the receiver chain. The ZRC20 +tokens are then +burned. The nonce is updated. If everything is successful, the CCTX status is +changed to `PendingRevert`. + +If the previous status was `PendingRevert`, the CCTX is aborted. + +```mermaid +stateDiagram-v2 + + state observation <> + state success_old_status <> + state fail_old_status <> + PendingOutbound --> observation: Finalize outbound + observation --> success_old_status: Observation succeeded + success_old_status --> Reverted: Old status is PendingRevert + success_old_status --> OutboundMined: Old status is PendingOutbound + observation --> fail_old_status: Observation failed + fail_old_status --> PendingRevert: Old status is PendingOutbound + fail_old_status --> Aborted: Old status is PendingRevert + PendingOutbound --> Aborted: Finalize outbound error -After finalization the outbound transaction tracker and pending nonces are -removed, and the CCTX is updated in the store. +``` Only observer validators are authorized to broadcast this message. @@ -132,13 +147,40 @@ is the first vote, a new ballot is created. When a threshold of votes is reached, the ballot is finalized. When a ballot is finalized, a new CCTX is created. -If the receiver chain is a ZetaChain, the EVM deposit is handled and the -status of CCTX is changed to "outbound mined". If EVM deposit handling fails, -the status of CCTX is chagned to 'aborted'. +If the receiver chain is ZetaChain, `HandleEVMDeposit` is called. If the +tokens being deposited are ZETA, `MintZetaToEVMAccount` is called and the +tokens are minted to the receiver account on ZetaChain. If the tokens being +deposited are gas tokens or ERC20 of a connected chain, ZRC20's `deposit` +method is called and the tokens are deposited to the receiver account on +ZetaChain. If the message is not empty, system contract's `depositAndCall` +method is also called and an omnichain contract on ZetaChain is executed. +Omnichain contract address and arguments are passed as part of the message. +If everything is successful, the CCTX status is changed to `OutboundMined`. + +If the receiver chain is a connected chain, the `FinalizeInbound` method is +called to prepare the CCTX to be processed as an outbound transaction. To +cover the outbound transaction fee, the required amount of tokens submitted +with the CCTX are swapped using a Uniswap V2 contract instance on ZetaChain +for the ZRC20 of the gas token of the receiver chain. The ZRC20 tokens are +then burned. The nonce is updated. If everything is successful, the CCTX +status is changed to `PendingOutbound`. + +```mermaid +stateDiagram-v2 + + state evm_deposit_success <> + state finalize_inbound <> + state evm_deposit_error <> + PendingInbound --> evm_deposit_success: Receiver is ZetaChain + evm_deposit_success --> OutboundMined: EVM deposit success + evm_deposit_success --> evm_deposit_error: EVM deposit error + evm_deposit_error --> PendingRevert: Contract error + evm_deposit_error --> Aborted: Internal error, invalid chain, gas, nonce + PendingInbound --> finalize_inbound: Receiver is connected chain + finalize_inbound --> Aborted: Finalize inbound error + finalize_inbound --> PendingOutbound: Finalize inbound success -If the receiver chain is a connected chain, the inbound CCTX is finalized -(prices and nonce are updated) and status changes to "pending outbound". If -the finalization fails, the status of CCTX is changed to 'aborted'. +``` Only observer validators are authorized to broadcast this message. diff --git a/docs/spec/crosschain/overview.md b/docs/spec/crosschain/overview.md index 3f371d5274..32e1035e41 100644 --- a/docs/spec/crosschain/overview.md +++ b/docs/spec/crosschain/overview.md @@ -1,3 +1,7 @@ +--- +sidebar_position: 1 +--- + # Overview The `crosschain` module tracks inbound and outbound cross-chain transactions diff --git a/docs/spec/emissions/overview.md b/docs/spec/emissions/overview.md index 84593191ba..7a503d8895 100644 --- a/docs/spec/emissions/overview.md +++ b/docs/spec/emissions/overview.md @@ -1,3 +1,7 @@ +--- +sidebar_position: 1 +--- + # Overview The `emissions` module is responsible for orchestrating rewards distribution for diff --git a/docs/spec/fungible/overview.md b/docs/spec/fungible/overview.md index f7c477f2f3..1420c79e1b 100644 --- a/docs/spec/fungible/overview.md +++ b/docs/spec/fungible/overview.md @@ -1,3 +1,7 @@ +--- +sidebar_position: 1 +--- + # Overview The `fungible` module facilitates the deployment of fungible tokens of connected diff --git a/docs/spec/observer/overview.md b/docs/spec/observer/overview.md index 40f2893356..94a118da46 100644 --- a/docs/spec/observer/overview.md +++ b/docs/spec/observer/overview.md @@ -1,3 +1,7 @@ +--- +sidebar_position: 1 +--- + # Overview The `observer` module keeps track of ballots for voting, a mapping between diff --git a/x/crosschain/keeper/keeper_cross_chain_tx_vote_inbound_tx.go b/x/crosschain/keeper/keeper_cross_chain_tx_vote_inbound_tx.go index c0eef13893..0b3efe6d9e 100644 --- a/x/crosschain/keeper/keeper_cross_chain_tx_vote_inbound_tx.go +++ b/x/crosschain/keeper/keeper_cross_chain_tx_vote_inbound_tx.go @@ -19,13 +19,40 @@ import ( // reached, the ballot is finalized. When a ballot is finalized, a new CCTX is // created. // -// If the receiver chain is a ZetaChain, the EVM deposit is handled and the -// status of CCTX is changed to "outbound mined". If EVM deposit handling fails, -// the status of CCTX is chagned to 'aborted'. +// If the receiver chain is ZetaChain, `HandleEVMDeposit` is called. If the +// tokens being deposited are ZETA, `MintZetaToEVMAccount` is called and the +// tokens are minted to the receiver account on ZetaChain. If the tokens being +// deposited are gas tokens or ERC20 of a connected chain, ZRC20's `deposit` +// method is called and the tokens are deposited to the receiver account on +// ZetaChain. If the message is not empty, system contract's `depositAndCall` +// method is also called and an omnichain contract on ZetaChain is executed. +// Omnichain contract address and arguments are passed as part of the message. +// If everything is successful, the CCTX status is changed to `OutboundMined`. // -// If the receiver chain is a connected chain, the inbound CCTX is finalized -// (prices and nonce are updated) and status changes to "pending outbound". If -// the finalization fails, the status of CCTX is changed to 'aborted'. +// If the receiver chain is a connected chain, the `FinalizeInbound` method is +// called to prepare the CCTX to be processed as an outbound transaction. To +// cover the outbound transaction fee, the required amount of tokens submitted +// with the CCTX are swapped using a Uniswap V2 contract instance on ZetaChain +// for the ZRC20 of the gas token of the receiver chain. The ZRC20 tokens are +// then burned. The nonce is updated. If everything is successful, the CCTX +// status is changed to `PendingOutbound`. +// +// ```mermaid +// stateDiagram-v2 +// +// state evm_deposit_success <> +// state finalize_inbound <> +// state evm_deposit_error <> +// PendingInbound --> evm_deposit_success: Receiver is ZetaChain +// evm_deposit_success --> OutboundMined: EVM deposit success +// evm_deposit_success --> evm_deposit_error: EVM deposit error +// evm_deposit_error --> PendingRevert: Contract error +// evm_deposit_error --> Aborted: Internal error, invalid chain, gas, nonce +// PendingInbound --> finalize_inbound: Receiver is connected chain +// finalize_inbound --> Aborted: Finalize inbound error +// finalize_inbound --> PendingOutbound: Finalize inbound success +// +// ``` // // Only observer validators are authorized to broadcast this message. func (k msgServer) VoteOnObservedInboundTx(goCtx context.Context, msg *types.MsgVoteOnObservedInboundTx) (*types.MsgVoteOnObservedInboundTxResponse, error) { diff --git a/x/crosschain/keeper/keeper_cross_chain_tx_vote_outbound_tx.go b/x/crosschain/keeper/keeper_cross_chain_tx_vote_outbound_tx.go index be469262f9..76875922a6 100644 --- a/x/crosschain/keeper/keeper_cross_chain_tx_vote_outbound_tx.go +++ b/x/crosschain/keeper/keeper_cross_chain_tx_vote_outbound_tx.go @@ -15,27 +15,42 @@ import ( // Casts a vote on an outbound transaction observed on a connected chain (after // it has been broadcasted to and finalized on a connected chain). If this is // the first vote, a new ballot is created. When a threshold of votes is -// reached, the ballot is finalized. When a ballot is finalized, if the amount -// of zeta minted does not match the outbound transaction amount an error is -// thrown. If the amounts match, the outbound transaction hash and the "last -// updated" timestamp are updated. +// reached, the ballot is finalized. When a ballot is finalized, the outbound +// transaction is processed. // -// The transaction is proceeded to be finalized: -// -// If the observation was successful, the status is changed from "pending -// revert/outbound" to "reverted/mined". The difference between zeta burned +// If the observation is successful, the difference between zeta burned // and minted is minted by the bank module and deposited into the module // account. // -// If the observation was unsuccessful, and if the status is "pending outbound", -// prices and nonce are updated and the status is changed to "pending revert". -// If the status was "pending revert", the status is changed to "aborted". +// If the observation is unsuccessful, the logic depends on the previous +// status. +// +// If the previous status was `PendingOutbound`, a new revert transaction is +// created. To cover the revert transaction fee, the required amount of tokens +// submitted with the CCTX are swapped using a Uniswap V2 contract instance on +// ZetaChain for the ZRC20 of the gas token of the receiver chain. The ZRC20 +// tokens are then +// burned. The nonce is updated. If everything is successful, the CCTX status is +// changed to `PendingRevert`. +// +// If the previous status was `PendingRevert`, the CCTX is aborted. +// +// ```mermaid +// stateDiagram-v2 // -// If there's an error in the finalization process, the CCTX status is set to -// 'aborted'. +// state observation <> +// state success_old_status <> +// state fail_old_status <> +// PendingOutbound --> observation: Finalize outbound +// observation --> success_old_status: Observation succeeded +// success_old_status --> Reverted: Old status is PendingRevert +// success_old_status --> OutboundMined: Old status is PendingOutbound +// observation --> fail_old_status: Observation failed +// fail_old_status --> PendingRevert: Old status is PendingOutbound +// fail_old_status --> Aborted: Old status is PendingRevert +// PendingOutbound --> Aborted: Finalize outbound error // -// After finalization the outbound transaction tracker and pending nonces are -// removed, and the CCTX is updated in the store. +// ``` // // Only observer validators are authorized to broadcast this message. func (k msgServer) VoteOnObservedOutboundTx(goCtx context.Context, msg *types.MsgVoteOnObservedOutboundTx) (*types.MsgVoteOnObservedOutboundTxResponse, error) {