From 3001d4f58742065b04c5e7eafb12b66e99ab8b49 Mon Sep 17 00:00:00 2001 From: elizabeth Date: Sat, 8 Jun 2024 18:45:28 -0400 Subject: [PATCH 1/8] wip bridge protocol doc --- specs/bridge.md | 23 +++++++++++++++++++++++ 1 file changed, 23 insertions(+) create mode 100644 specs/bridge.md diff --git a/specs/bridge.md b/specs/bridge.md new file mode 100644 index 0000000000..7e6387d616 --- /dev/null +++ b/specs/bridge.md @@ -0,0 +1,23 @@ +# Astria rollup bridging protocol + +The Astria sequencer implements a native bridging protocol which allows for bridging assets from the sequencer to rollups which decide to use this protocol. + +At a high level, the sequencer-to-rollup protocol works as follows: + +- a bridge account is initialized on the sequencer which has an associated rollup ID, which is the rollup ID that the rollup reads its block data from +- the rollup enshrines the sequencer bridge account into its consensus, authorizing transfers (locks) into this bridge account of a specific asset to result in mints of the synthetic token on the rollup +- users then send transfers to the sequencer bridge account, which result in `Deposit` events being included as part of the rollup's block data +- when the rollup sees a `Deposit`, it mints the corresponding tokens to the user's account + +This is similar to how existing L1-to-rollup bridges work, where some lock event happening on the L1 results in a deposit transaction being derived automatically on the rollup. + +The rollup-to-sequencer protocol works as follows: +- the bridge account has an associated private key. this could potentially be backed by the threshold signature scheme/multisig. +- a bridge withdrawer is able to sign transaction which move funds out of the bridge account to other sequencer accounts. +- there is a withdrawal contract deployed on the rollup which emits `Withdrawal` events when funds are locked in it (and effectively burned, as the contract should not be able to transfer its own funds). +- the bridge withdrawer watches for these `Withdrawal` events. when it sees one, it sends a sequencer transaction which transfers funds from the bridge account to the account specified in the withdrawal event. + +Since the sequencer can support multiple assets via IBC, the bridging protocol also has support for deposits and withdrawals via IBC, as well as support for various assets to be bridged to the rollup. + +The one-step deposit flow from another IBC chain is as follows: +- From fc082b8fd847e8859299b9de3d32a4c801a877dc Mon Sep 17 00:00:00 2001 From: elizabeth Date: Mon, 10 Jun 2024 22:07:37 -0400 Subject: [PATCH 2/8] more docs --- specs/bridge.md | 11 ++++++++++- 1 file changed, 10 insertions(+), 1 deletion(-) diff --git a/specs/bridge.md b/specs/bridge.md index 7e6387d616..17d1fb6e81 100644 --- a/specs/bridge.md +++ b/specs/bridge.md @@ -20,4 +20,13 @@ The rollup-to-sequencer protocol works as follows: Since the sequencer can support multiple assets via IBC, the bridging protocol also has support for deposits and withdrawals via IBC, as well as support for various assets to be bridged to the rollup. The one-step deposit flow from another IBC chain is as follows: -- +- a user initiates an ICS20 withdrawal from some IBC chain to Astria. +- the user sets the destination chain address as the sequencer bridge address which corresponds to the rollup they wish to deposit to. +- the user sets the withdrawal memo to their rollup address. +- when the ICS20 transfer is executed on Astria, the funds are locked into the bridge address, and a `Deposit` event is created for that rollup's ID with the user's rollup address. + +The one-step withdrawal flow from a rollup to another IBC chain is as follows: +- the user withdraws the asset by burning it on the rollup, which emits a `Withdrawal` event that includes the asset, the amount, and a memo. +- the memo contains the needed information for creating an Ics20 withdrawal on the sequencer, such as the recipient destination chain address. +- the bridge withdrawer sees the `Withdrawal` event and submits a sequencer transaction which withdraws the funds to the destination IBC chain. +- in the case that the transfer to the destination IBC chain fails, the sequencer is notified of this, and emits a `Deposit` refunding the funds back to the origin rollup address. From a93d2b1bde0baf43d4595aa9e014ab98389f21ca Mon Sep 17 00:00:00 2001 From: elizabeth Date: Tue, 11 Jun 2024 13:50:59 -0400 Subject: [PATCH 3/8] action details --- specs/bridge.md | 18 ++++++++++++++++++ 1 file changed, 18 insertions(+) diff --git a/specs/bridge.md b/specs/bridge.md index 17d1fb6e81..da6d2713d2 100644 --- a/specs/bridge.md +++ b/specs/bridge.md @@ -30,3 +30,21 @@ The one-step withdrawal flow from a rollup to another IBC chain is as follows: - the memo contains the needed information for creating an Ics20 withdrawal on the sequencer, such as the recipient destination chain address. - the bridge withdrawer sees the `Withdrawal` event and submits a sequencer transaction which withdraws the funds to the destination IBC chain. - in the case that the transfer to the destination IBC chain fails, the sequencer is notified of this, and emits a `Deposit` refunding the funds back to the origin rollup address. + +### Implementation + +Within the sequencer application, the bridging logic is located in the [`bridge`](https://github.com/astriaorg/astria/tree/main/crates/astria-sequencer/src/bridge) module, and the IBC-bridging logic is in the [`ibc`](https://github.com/astriaorg/astria/tree/main/crates/astria-sequencer/src/ibc) module. + +The bridge related actions are: +- [`InitBridgeAccountAction`](https://github.com/astriaorg/astria/blob/6902ef35370e5980a76302fc756e1a9a56af21b5/proto/protocolapis/astria/protocol/transactions/v1alpha1/types.proto#L167): initializes the signer of the action as a bridge account. The associated rollup ID and asset ID which this account accepts are provided. Optional `sudo_address` and `withdrawer_address` fields can be provided, which are set to the action sender if unset. + - the account's rollup ID and asset ID cannot be changed once initialized. + - `sudo_address` is authorized to change the rollup account's `sudo_address` and `withdrawer_address`. + - to make withdrawals from the bridge account, the `withdrawer_address` must be the transaction signer. + - withdrawals are allowed using either `BridgeUnlockAction` or `Ics20Withdrawal`. +- [`BridgeLockAction`](https://github.com/astriaorg/astria/blob/6902ef35370e5980a76302fc756e1a9a56af21b5/proto/protocolapis/astria/protocol/transactions/v1alpha1/types.proto#L188): transfers funds to a bridge account, locking them and emitting a [`Deposit`](https://github.com/astriaorg/astria/blob/6902ef35370e5980a76302fc756e1a9a56af21b5/proto/sequencerblockapis/astria/sequencerblock/v1alpha1/block.proto#L76). The `destination_chain_address` is the rollup account funds are minted to. +- [`BridgeUnlockAction](https://github.com/astriaorg/astria/blob/main/proto/protocolapis/astria/protocol/transactions/v1alpha1/types.proto#L207): transfers funds from a bridge account to another account. The asset transferred is the one for the bridge account (ie. the asset ID specified in `InitBridgeAccountAction`). The signer of this action must be the bridge account's `withdrawer_address`. +- [`BridgeSudoChangeAction`](https://github.com/astriaorg/astria/blob/6902ef35370e5980a76302fc756e1a9a56af21b5/proto/protocolapis/astria/protocol/transactions/v1alpha1/types.proto#L222) changes the bridge account's sudo and/or withdrawer addresses. The signer of this action must be the bridge account's `sudo_address`. + +The two IBC actions which can also perform bridging actions are an `IbcRelay` which contains an `Ics20Transfer` packet, and `Ics20Withdrawal`. +- [`Ics20Transfer`](https://github.com/astriaorg/astria/blob/6902ef35370e5980a76302fc756e1a9a56af21b5/crates/astria-sequencer/src/ibc/ics20_transfer.rs#L370) packets are received when an IBC transfer to Astria from another chain occurs. If the recipient of the packet is a bridge account and the asset transferred is valid, the funds are locked in the bridge account and a `Deposit` is created. +- [`Ics20Withdrawal`](https://github.com/astriaorg/astria/blob/6902ef35370e5980a76302fc756e1a9a56af21b5/proto/protocolapis/astria/protocol/transactions/v1alpha1/types.proto#L102) represents a withdrawal from Astria to another IBC chain. If the `bridge_address` field is set, the funds are transferred out of a bridge account. Alternatively, if `bridge_address` is unset but the signer of the action is a bridge address, and the withdrawer address is the same as the bridge address, the funds are transferred out of the bridge account. From 13e8bacf5053019ec6427c66e00069b4d57a990e Mon Sep 17 00:00:00 2001 From: elizabeth Date: Tue, 11 Jun 2024 13:52:36 -0400 Subject: [PATCH 4/8] fix --- specs/bridge.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/specs/bridge.md b/specs/bridge.md index da6d2713d2..c74b42c3a0 100644 --- a/specs/bridge.md +++ b/specs/bridge.md @@ -42,7 +42,7 @@ The bridge related actions are: - to make withdrawals from the bridge account, the `withdrawer_address` must be the transaction signer. - withdrawals are allowed using either `BridgeUnlockAction` or `Ics20Withdrawal`. - [`BridgeLockAction`](https://github.com/astriaorg/astria/blob/6902ef35370e5980a76302fc756e1a9a56af21b5/proto/protocolapis/astria/protocol/transactions/v1alpha1/types.proto#L188): transfers funds to a bridge account, locking them and emitting a [`Deposit`](https://github.com/astriaorg/astria/blob/6902ef35370e5980a76302fc756e1a9a56af21b5/proto/sequencerblockapis/astria/sequencerblock/v1alpha1/block.proto#L76). The `destination_chain_address` is the rollup account funds are minted to. -- [`BridgeUnlockAction](https://github.com/astriaorg/astria/blob/main/proto/protocolapis/astria/protocol/transactions/v1alpha1/types.proto#L207): transfers funds from a bridge account to another account. The asset transferred is the one for the bridge account (ie. the asset ID specified in `InitBridgeAccountAction`). The signer of this action must be the bridge account's `withdrawer_address`. +- [`BridgeUnlockAction`](https://github.com/astriaorg/astria/blob/main/proto/protocolapis/astria/protocol/transactions/v1alpha1/types.proto#L207): transfers funds from a bridge account to another account. The asset transferred is the one for the bridge account (ie. the asset ID specified in `InitBridgeAccountAction`). The signer of this action must be the bridge account's `withdrawer_address`. - [`BridgeSudoChangeAction`](https://github.com/astriaorg/astria/blob/6902ef35370e5980a76302fc756e1a9a56af21b5/proto/protocolapis/astria/protocol/transactions/v1alpha1/types.proto#L222) changes the bridge account's sudo and/or withdrawer addresses. The signer of this action must be the bridge account's `sudo_address`. The two IBC actions which can also perform bridging actions are an `IbcRelay` which contains an `Ics20Transfer` packet, and `Ics20Withdrawal`. From f93206d3850f49b0b4581f70b136f18c166d28bc Mon Sep 17 00:00:00 2001 From: elizabeth Date: Tue, 11 Jun 2024 13:53:51 -0400 Subject: [PATCH 5/8] add details --- specs/bridge.md | 1 + 1 file changed, 1 insertion(+) diff --git a/specs/bridge.md b/specs/bridge.md index c74b42c3a0..6ad5ba9fa0 100644 --- a/specs/bridge.md +++ b/specs/bridge.md @@ -38,6 +38,7 @@ Within the sequencer application, the bridging logic is located in the [`bridge` The bridge related actions are: - [`InitBridgeAccountAction`](https://github.com/astriaorg/astria/blob/6902ef35370e5980a76302fc756e1a9a56af21b5/proto/protocolapis/astria/protocol/transactions/v1alpha1/types.proto#L167): initializes the signer of the action as a bridge account. The associated rollup ID and asset ID which this account accepts are provided. Optional `sudo_address` and `withdrawer_address` fields can be provided, which are set to the action sender if unset. - the account's rollup ID and asset ID cannot be changed once initialized. + - the account cannot be re-initialized as a bridge account, and it cannot be converted back into a non-bridge account. - `sudo_address` is authorized to change the rollup account's `sudo_address` and `withdrawer_address`. - to make withdrawals from the bridge account, the `withdrawer_address` must be the transaction signer. - withdrawals are allowed using either `BridgeUnlockAction` or `Ics20Withdrawal`. From 81932e6abcc175bc0899b955ebccbd1bd3523f92 Mon Sep 17 00:00:00 2001 From: elizabeth Date: Tue, 11 Jun 2024 14:05:46 -0400 Subject: [PATCH 6/8] line length --- specs/bridge.md | 106 +++++++++++++++++++++++++++++++++++------------- 1 file changed, 78 insertions(+), 28 deletions(-) diff --git a/specs/bridge.md b/specs/bridge.md index 6ad5ba9fa0..e927385460 100644 --- a/specs/bridge.md +++ b/specs/bridge.md @@ -1,51 +1,101 @@ # Astria rollup bridging protocol -The Astria sequencer implements a native bridging protocol which allows for bridging assets from the sequencer to rollups which decide to use this protocol. +The Astria sequencer implements a native bridging protocol which allows for +bridging assets from the sequencer to rollups which decide to use this protocol. At a high level, the sequencer-to-rollup protocol works as follows: -- a bridge account is initialized on the sequencer which has an associated rollup ID, which is the rollup ID that the rollup reads its block data from -- the rollup enshrines the sequencer bridge account into its consensus, authorizing transfers (locks) into this bridge account of a specific asset to result in mints of the synthetic token on the rollup -- users then send transfers to the sequencer bridge account, which result in `Deposit` events being included as part of the rollup's block data -- when the rollup sees a `Deposit`, it mints the corresponding tokens to the user's account +- a bridge account is initialized on the sequencer which has an associated +rollup ID, which is the rollup ID that the rollup reads its block data from +- the rollup enshrines the sequencer bridge account into its consensus, +authorizing transfers (locks) into this bridge account of a specific asset +to result in mints of the synthetic token on the rollup +- users then send transfers to the sequencer bridge account, which result in +`Deposit` events being included as part of the rollup's block data +- when the rollup sees a `Deposit`, it mints the corresponding tokens to the +user's account -This is similar to how existing L1-to-rollup bridges work, where some lock event happening on the L1 results in a deposit transaction being derived automatically on the rollup. +This is similar to how existing L1-to-rollup bridges work, where some lock +event happening on the L1 results in a deposit transaction being derived +automatically on the rollup. The rollup-to-sequencer protocol works as follows: -- the bridge account has an associated private key. this could potentially be backed by the threshold signature scheme/multisig. -- a bridge withdrawer is able to sign transaction which move funds out of the bridge account to other sequencer accounts. -- there is a withdrawal contract deployed on the rollup which emits `Withdrawal` events when funds are locked in it (and effectively burned, as the contract should not be able to transfer its own funds). -- the bridge withdrawer watches for these `Withdrawal` events. when it sees one, it sends a sequencer transaction which transfers funds from the bridge account to the account specified in the withdrawal event. +- the bridge account has an associated private key. this could potentially be +backed by the threshold signature scheme/multisig. +- a bridge withdrawer is able to sign transaction which move funds out of the +bridge account to other sequencer accounts. +- there is a withdrawal contract deployed on the rollup which emits `Withdrawal` +events when funds are locked in it (and effectively burned, as the contract +should not be able to transfer its own funds). +- the bridge withdrawer watches for these `Withdrawal` events. when it sees +one, it sends a sequencer transaction which transfers funds from the bridge +account to the account specified in the withdrawal event. -Since the sequencer can support multiple assets via IBC, the bridging protocol also has support for deposits and withdrawals via IBC, as well as support for various assets to be bridged to the rollup. +Since the sequencer can support multiple assets via IBC, the bridging protocol +also has support for deposits and withdrawals via IBC, as well as support for +various assets to be bridged to the rollup. The one-step deposit flow from another IBC chain is as follows: - a user initiates an ICS20 withdrawal from some IBC chain to Astria. -- the user sets the destination chain address as the sequencer bridge address which corresponds to the rollup they wish to deposit to. +- the user sets the destination chain address as the sequencer bridge address +which corresponds to the rollup they wish to deposit to. - the user sets the withdrawal memo to their rollup address. -- when the ICS20 transfer is executed on Astria, the funds are locked into the bridge address, and a `Deposit` event is created for that rollup's ID with the user's rollup address. +- when the ICS20 transfer is executed on Astria, the funds are locked into the +bridge address, and a `Deposit` event is created for that rollup's ID with the +user's rollup address. The one-step withdrawal flow from a rollup to another IBC chain is as follows: -- the user withdraws the asset by burning it on the rollup, which emits a `Withdrawal` event that includes the asset, the amount, and a memo. -- the memo contains the needed information for creating an Ics20 withdrawal on the sequencer, such as the recipient destination chain address. -- the bridge withdrawer sees the `Withdrawal` event and submits a sequencer transaction which withdraws the funds to the destination IBC chain. -- in the case that the transfer to the destination IBC chain fails, the sequencer is notified of this, and emits a `Deposit` refunding the funds back to the origin rollup address. +- the user withdraws the asset by burning it on the rollup, which emits a +`Withdrawal` event that includes the asset, the amount, and a memo. +- the memo contains the needed information for creating an Ics20 withdrawal on +the sequencer, such as the recipient destination chain address. +- the bridge withdrawer sees the `Withdrawal` event and submits a sequencer +transaction which withdraws the funds to the destination IBC chain. +- in the case that the transfer to the destination IBC chain fails, the +sequencer is notified of this, and emits a `Deposit` refunding the funds back +to the origin rollup address. -### Implementation +## Implementation -Within the sequencer application, the bridging logic is located in the [`bridge`](https://github.com/astriaorg/astria/tree/main/crates/astria-sequencer/src/bridge) module, and the IBC-bridging logic is in the [`ibc`](https://github.com/astriaorg/astria/tree/main/crates/astria-sequencer/src/ibc) module. +Within the sequencer application, the bridging logic is located in the +[`bridge`](https://github.com/astriaorg/astria/tree/main/crates/astria-sequencer/src/bridge) +module, and the IBC-bridging logic is in the +[`ibc`](https://github.com/astriaorg/astria/tree/main/crates/astria-sequencer/src/ibc) module. The bridge related actions are: -- [`InitBridgeAccountAction`](https://github.com/astriaorg/astria/blob/6902ef35370e5980a76302fc756e1a9a56af21b5/proto/protocolapis/astria/protocol/transactions/v1alpha1/types.proto#L167): initializes the signer of the action as a bridge account. The associated rollup ID and asset ID which this account accepts are provided. Optional `sudo_address` and `withdrawer_address` fields can be provided, which are set to the action sender if unset. +- [`InitBridgeAccountAction`](https://github.com/astriaorg/astria/blob/6902ef35370e5980a76302fc756e1a9a56af21b5/proto/protocolapis/astria/protocol/transactions/v1alpha1/types.proto#L167): +initializes the signer of the action as a bridge account. The associated rollup +ID and asset ID which this account accepts are provided. Optional `sudo_address` +and `withdrawer_address` fields can be provided, which are set to the action +sender if unset. - the account's rollup ID and asset ID cannot be changed once initialized. - - the account cannot be re-initialized as a bridge account, and it cannot be converted back into a non-bridge account. - - `sudo_address` is authorized to change the rollup account's `sudo_address` and `withdrawer_address`. - - to make withdrawals from the bridge account, the `withdrawer_address` must be the transaction signer. + - the account cannot be re-initialized as a bridge account, and it cannot be + converted back into a non-bridge account. + - `sudo_address` is authorized to change the rollup account's `sudo_address` + and `withdrawer_address`. + - to make withdrawals from the bridge account, the `withdrawer_address` must + be the transaction signer. - withdrawals are allowed using either `BridgeUnlockAction` or `Ics20Withdrawal`. -- [`BridgeLockAction`](https://github.com/astriaorg/astria/blob/6902ef35370e5980a76302fc756e1a9a56af21b5/proto/protocolapis/astria/protocol/transactions/v1alpha1/types.proto#L188): transfers funds to a bridge account, locking them and emitting a [`Deposit`](https://github.com/astriaorg/astria/blob/6902ef35370e5980a76302fc756e1a9a56af21b5/proto/sequencerblockapis/astria/sequencerblock/v1alpha1/block.proto#L76). The `destination_chain_address` is the rollup account funds are minted to. -- [`BridgeUnlockAction`](https://github.com/astriaorg/astria/blob/main/proto/protocolapis/astria/protocol/transactions/v1alpha1/types.proto#L207): transfers funds from a bridge account to another account. The asset transferred is the one for the bridge account (ie. the asset ID specified in `InitBridgeAccountAction`). The signer of this action must be the bridge account's `withdrawer_address`. -- [`BridgeSudoChangeAction`](https://github.com/astriaorg/astria/blob/6902ef35370e5980a76302fc756e1a9a56af21b5/proto/protocolapis/astria/protocol/transactions/v1alpha1/types.proto#L222) changes the bridge account's sudo and/or withdrawer addresses. The signer of this action must be the bridge account's `sudo_address`. +- [`BridgeLockAction`](https://github.com/astriaorg/astria/blob/6902ef35370e5980a76302fc756e1a9a56af21b5/proto/protocolapis/astria/protocol/transactions/v1alpha1/types.proto#L188): +transfers funds to a bridge account, locking them and emitting a +[`Deposit`](https://github.com/astriaorg/astria/blob/6902ef35370e5980a76302fc756e1a9a56af21b5/proto/sequencerblockapis/astria/sequencerblock/v1alpha1/block.proto#L76). +The `destination_chain_address` is the rollup account funds are minted to. +- [`BridgeUnlockAction`](https://github.com/astriaorg/astria/blob/main/proto/protocolapis/astria/protocol/transactions/v1alpha1/types.proto#L207): +transfers funds from a bridge account to another account. The asset transferred +is the one for the bridge account (ie. the asset ID specified in `InitBridgeAccountAction`). +The signer of this action must be the bridge account's `withdrawer_address`. +- [`BridgeSudoChangeAction`](https://github.com/astriaorg/astria/blob/6902ef35370e5980a76302fc756e1a9a56af21b5/proto/protocolapis/astria/protocol/transactions/v1alpha1/types.proto#L222) +changes the bridge account's sudo and/or withdrawer addresses. The signer of +this action must be the bridge account's `sudo_address`. The two IBC actions which can also perform bridging actions are an `IbcRelay` which contains an `Ics20Transfer` packet, and `Ics20Withdrawal`. -- [`Ics20Transfer`](https://github.com/astriaorg/astria/blob/6902ef35370e5980a76302fc756e1a9a56af21b5/crates/astria-sequencer/src/ibc/ics20_transfer.rs#L370) packets are received when an IBC transfer to Astria from another chain occurs. If the recipient of the packet is a bridge account and the asset transferred is valid, the funds are locked in the bridge account and a `Deposit` is created. -- [`Ics20Withdrawal`](https://github.com/astriaorg/astria/blob/6902ef35370e5980a76302fc756e1a9a56af21b5/proto/protocolapis/astria/protocol/transactions/v1alpha1/types.proto#L102) represents a withdrawal from Astria to another IBC chain. If the `bridge_address` field is set, the funds are transferred out of a bridge account. Alternatively, if `bridge_address` is unset but the signer of the action is a bridge address, and the withdrawer address is the same as the bridge address, the funds are transferred out of the bridge account. +- [`Ics20Transfer`](https://github.com/astriaorg/astria/blob/6902ef35370e5980a76302fc756e1a9a56af21b5/crates/astria-sequencer/src/ibc/ics20_transfer.rs#L370) +packets are received when an IBC transfer to Astria from another chain occurs. +If the recipient of the packet is a bridge account and the asset transferred is +valid, the funds are locked in the bridge account and a `Deposit` is created. +- [`Ics20Withdrawal`](https://github.com/astriaorg/astria/blob/6902ef35370e5980a76302fc756e1a9a56af21b5/proto/protocolapis/astria/protocol/transactions/v1alpha1/types.proto#L102) +represents a withdrawal from Astria to another IBC chain. If the `bridge_address` +field is set, the funds are transferred out of a bridge account. Alternatively, +if `bridge_address` is unset but the signer of the action is a bridge address, +and the withdrawer address is the same as the bridge address, the funds are +transferred out of the bridge account. From 76119e82243cbfbce84087a34caac8cecf5cd82b Mon Sep 17 00:00:00 2001 From: elizabeth Date: Tue, 11 Jun 2024 14:08:32 -0400 Subject: [PATCH 7/8] lint --- specs/bridge.md | 107 +++++++++++++++++++++++++----------------------- 1 file changed, 56 insertions(+), 51 deletions(-) diff --git a/specs/bridge.md b/specs/bridge.md index e927385460..9b7f9db943 100644 --- a/specs/bridge.md +++ b/specs/bridge.md @@ -1,101 +1,106 @@ # Astria rollup bridging protocol -The Astria sequencer implements a native bridging protocol which allows for +The Astria sequencer implements a native bridging protocol which allows for bridging assets from the sequencer to rollups which decide to use this protocol. At a high level, the sequencer-to-rollup protocol works as follows: -- a bridge account is initialized on the sequencer which has an associated +- a bridge account is initialized on the sequencer which has an associated rollup ID, which is the rollup ID that the rollup reads its block data from -- the rollup enshrines the sequencer bridge account into its consensus, -authorizing transfers (locks) into this bridge account of a specific asset +- the rollup enshrines the sequencer bridge account into its consensus, +authorizing transfers (locks) into this bridge account of a specific asset to result in mints of the synthetic token on the rollup -- users then send transfers to the sequencer bridge account, which result in +- users then send transfers to the sequencer bridge account, which result in `Deposit` events being included as part of the rollup's block data -- when the rollup sees a `Deposit`, it mints the corresponding tokens to the +- when the rollup sees a `Deposit`, it mints the corresponding tokens to the user's account -This is similar to how existing L1-to-rollup bridges work, where some lock -event happening on the L1 results in a deposit transaction being derived +This is similar to how existing L1-to-rollup bridges work, where some lock +event happening on the L1 results in a deposit transaction being derived automatically on the rollup. The rollup-to-sequencer protocol works as follows: -- the bridge account has an associated private key. this could potentially be + +- the bridge account has an associated private key. this could potentially be backed by the threshold signature scheme/multisig. -- a bridge withdrawer is able to sign transaction which move funds out of the +- a bridge withdrawer is able to sign transaction which move funds out of the bridge account to other sequencer accounts. -- there is a withdrawal contract deployed on the rollup which emits `Withdrawal` -events when funds are locked in it (and effectively burned, as the contract +- there is a withdrawal contract deployed on the rollup which emits `Withdrawal` +events when funds are locked in it (and effectively burned, as the contract should not be able to transfer its own funds). -- the bridge withdrawer watches for these `Withdrawal` events. when it sees -one, it sends a sequencer transaction which transfers funds from the bridge +- the bridge withdrawer watches for these `Withdrawal` events. when it sees +one, it sends a sequencer transaction which transfers funds from the bridge account to the account specified in the withdrawal event. -Since the sequencer can support multiple assets via IBC, the bridging protocol -also has support for deposits and withdrawals via IBC, as well as support for +Since the sequencer can support multiple assets via IBC, the bridging protocol +also has support for deposits and withdrawals via IBC, as well as support for various assets to be bridged to the rollup. The one-step deposit flow from another IBC chain is as follows: + - a user initiates an ICS20 withdrawal from some IBC chain to Astria. -- the user sets the destination chain address as the sequencer bridge address +- the user sets the destination chain address as the sequencer bridge address which corresponds to the rollup they wish to deposit to. - the user sets the withdrawal memo to their rollup address. -- when the ICS20 transfer is executed on Astria, the funds are locked into the -bridge address, and a `Deposit` event is created for that rollup's ID with the +- when the ICS20 transfer is executed on Astria, the funds are locked into the +bridge address, and a `Deposit` event is created for that rollup's ID with the user's rollup address. The one-step withdrawal flow from a rollup to another IBC chain is as follows: -- the user withdraws the asset by burning it on the rollup, which emits a + +- the user withdraws the asset by burning it on the rollup, which emits a `Withdrawal` event that includes the asset, the amount, and a memo. -- the memo contains the needed information for creating an Ics20 withdrawal on +- the memo contains the needed information for creating an Ics20 withdrawal on the sequencer, such as the recipient destination chain address. -- the bridge withdrawer sees the `Withdrawal` event and submits a sequencer +- the bridge withdrawer sees the `Withdrawal` event and submits a sequencer transaction which withdraws the funds to the destination IBC chain. -- in the case that the transfer to the destination IBC chain fails, the -sequencer is notified of this, and emits a `Deposit` refunding the funds back +- in the case that the transfer to the destination IBC chain fails, the +sequencer is notified of this, and emits a `Deposit` refunding the funds back to the origin rollup address. ## Implementation -Within the sequencer application, the bridging logic is located in the -[`bridge`](https://github.com/astriaorg/astria/tree/main/crates/astria-sequencer/src/bridge) -module, and the IBC-bridging logic is in the -[`ibc`](https://github.com/astriaorg/astria/tree/main/crates/astria-sequencer/src/ibc) module. +Within the sequencer application, the bridging logic is located in the +[`bridge`](https://github.com/astriaorg/astria/tree/main/crates/astria-sequencer/src/bridge) +module, and the IBC-bridging logic is in the +[`ibc`](https://github.com/astriaorg/astria/tree/main/crates/astria-sequencer/src/ibc) module. The bridge related actions are: -- [`InitBridgeAccountAction`](https://github.com/astriaorg/astria/blob/6902ef35370e5980a76302fc756e1a9a56af21b5/proto/protocolapis/astria/protocol/transactions/v1alpha1/types.proto#L167): -initializes the signer of the action as a bridge account. The associated rollup -ID and asset ID which this account accepts are provided. Optional `sudo_address` -and `withdrawer_address` fields can be provided, which are set to the action + +- [`InitBridgeAccountAction`](https://github.com/astriaorg/astria/blob/6902ef35370e5980a76302fc756e1a9a56af21b5/proto/protocolapis/astria/protocol/transactions/v1alpha1/types.proto#L167): +initializes the signer of the action as a bridge account. The associated rollup +ID and asset ID which this account accepts are provided. Optional `sudo_address` +and `withdrawer_address` fields can be provided, which are set to the action sender if unset. - the account's rollup ID and asset ID cannot be changed once initialized. - - the account cannot be re-initialized as a bridge account, and it cannot be + - the account cannot be re-initialized as a bridge account, and it cannot be converted back into a non-bridge account. - - `sudo_address` is authorized to change the rollup account's `sudo_address` + - `sudo_address` is authorized to change the rollup account's `sudo_address` and `withdrawer_address`. - - to make withdrawals from the bridge account, the `withdrawer_address` must + - to make withdrawals from the bridge account, the `withdrawer_address` must be the transaction signer. - withdrawals are allowed using either `BridgeUnlockAction` or `Ics20Withdrawal`. -- [`BridgeLockAction`](https://github.com/astriaorg/astria/blob/6902ef35370e5980a76302fc756e1a9a56af21b5/proto/protocolapis/astria/protocol/transactions/v1alpha1/types.proto#L188): -transfers funds to a bridge account, locking them and emitting a -[`Deposit`](https://github.com/astriaorg/astria/blob/6902ef35370e5980a76302fc756e1a9a56af21b5/proto/sequencerblockapis/astria/sequencerblock/v1alpha1/block.proto#L76). +- [`BridgeLockAction`](https://github.com/astriaorg/astria/blob/6902ef35370e5980a76302fc756e1a9a56af21b5/proto/protocolapis/astria/protocol/transactions/v1alpha1/types.proto#L188): +transfers funds to a bridge account, locking them and emitting a +[`Deposit`](https://github.com/astriaorg/astria/blob/6902ef35370e5980a76302fc756e1a9a56af21b5/proto/sequencerblockapis/astria/sequencerblock/v1alpha1/block.proto#L76). The `destination_chain_address` is the rollup account funds are minted to. -- [`BridgeUnlockAction`](https://github.com/astriaorg/astria/blob/main/proto/protocolapis/astria/protocol/transactions/v1alpha1/types.proto#L207): -transfers funds from a bridge account to another account. The asset transferred -is the one for the bridge account (ie. the asset ID specified in `InitBridgeAccountAction`). +- [`BridgeUnlockAction`](https://github.com/astriaorg/astria/blob/main/proto/protocolapis/astria/protocol/transactions/v1alpha1/types.proto#L207): +transfers funds from a bridge account to another account. The asset transferred +is the one for the bridge account (ie. the asset ID specified in `InitBridgeAccountAction`). The signer of this action must be the bridge account's `withdrawer_address`. -- [`BridgeSudoChangeAction`](https://github.com/astriaorg/astria/blob/6902ef35370e5980a76302fc756e1a9a56af21b5/proto/protocolapis/astria/protocol/transactions/v1alpha1/types.proto#L222) -changes the bridge account's sudo and/or withdrawer addresses. The signer of +- [`BridgeSudoChangeAction`](https://github.com/astriaorg/astria/blob/6902ef35370e5980a76302fc756e1a9a56af21b5/proto/protocolapis/astria/protocol/transactions/v1alpha1/types.proto#L222) +changes the bridge account's sudo and/or withdrawer addresses. The signer of this action must be the bridge account's `sudo_address`. The two IBC actions which can also perform bridging actions are an `IbcRelay` which contains an `Ics20Transfer` packet, and `Ics20Withdrawal`. -- [`Ics20Transfer`](https://github.com/astriaorg/astria/blob/6902ef35370e5980a76302fc756e1a9a56af21b5/crates/astria-sequencer/src/ibc/ics20_transfer.rs#L370) -packets are received when an IBC transfer to Astria from another chain occurs. -If the recipient of the packet is a bridge account and the asset transferred is + +- [`Ics20Transfer`](https://github.com/astriaorg/astria/blob/6902ef35370e5980a76302fc756e1a9a56af21b5/crates/astria-sequencer/src/ibc/ics20_transfer.rs#L370) +packets are received when an IBC transfer to Astria from another chain occurs. +If the recipient of the packet is a bridge account and the asset transferred is valid, the funds are locked in the bridge account and a `Deposit` is created. -- [`Ics20Withdrawal`](https://github.com/astriaorg/astria/blob/6902ef35370e5980a76302fc756e1a9a56af21b5/proto/protocolapis/astria/protocol/transactions/v1alpha1/types.proto#L102) -represents a withdrawal from Astria to another IBC chain. If the `bridge_address` -field is set, the funds are transferred out of a bridge account. Alternatively, -if `bridge_address` is unset but the signer of the action is a bridge address, -and the withdrawer address is the same as the bridge address, the funds are +- [`Ics20Withdrawal`](https://github.com/astriaorg/astria/blob/6902ef35370e5980a76302fc756e1a9a56af21b5/proto/protocolapis/astria/protocol/transactions/v1alpha1/types.proto#L102) +represents a withdrawal from Astria to another IBC chain. If the `bridge_address` +field is set, the funds are transferred out of a bridge account. Alternatively, +if `bridge_address` is unset but the signer of the action is a bridge address, +and the withdrawer address is the same as the bridge address, the funds are transferred out of the bridge account. From 95d111a0f04d5cb7832f2a0073386b6516032ea2 Mon Sep 17 00:00:00 2001 From: elizabeth Date: Tue, 11 Jun 2024 14:10:03 -0400 Subject: [PATCH 8/8] lint --- specs/bridge.md | 16 +++++++++------- 1 file changed, 9 insertions(+), 7 deletions(-) diff --git a/specs/bridge.md b/specs/bridge.md index 9b7f9db943..6ab4487ae1 100644 --- a/specs/bridge.md +++ b/specs/bridge.md @@ -63,7 +63,8 @@ to the origin rollup address. Within the sequencer application, the bridging logic is located in the [`bridge`](https://github.com/astriaorg/astria/tree/main/crates/astria-sequencer/src/bridge) module, and the IBC-bridging logic is in the -[`ibc`](https://github.com/astriaorg/astria/tree/main/crates/astria-sequencer/src/ibc) module. +[`ibc`](https://github.com/astriaorg/astria/tree/main/crates/astria-sequencer/src/ibc) +module. The bridge related actions are: @@ -72,14 +73,14 @@ initializes the signer of the action as a bridge account. The associated rollup ID and asset ID which this account accepts are provided. Optional `sudo_address` and `withdrawer_address` fields can be provided, which are set to the action sender if unset. - - the account's rollup ID and asset ID cannot be changed once initialized. - - the account cannot be re-initialized as a bridge account, and it cannot be + - the account's rollup ID and asset ID cannot be changed once initialized. + - the account cannot be re-initialized as a bridge account, and it cannot be converted back into a non-bridge account. - - `sudo_address` is authorized to change the rollup account's `sudo_address` + - `sudo_address` is authorized to change the rollup account's `sudo_address` and `withdrawer_address`. - - to make withdrawals from the bridge account, the `withdrawer_address` must + - to make withdrawals from the bridge account, the `withdrawer_address` must be the transaction signer. - - withdrawals are allowed using either `BridgeUnlockAction` or `Ics20Withdrawal`. + - withdrawals are allowed using either `BridgeUnlockAction` or `Ics20Withdrawal`. - [`BridgeLockAction`](https://github.com/astriaorg/astria/blob/6902ef35370e5980a76302fc756e1a9a56af21b5/proto/protocolapis/astria/protocol/transactions/v1alpha1/types.proto#L188): transfers funds to a bridge account, locking them and emitting a [`Deposit`](https://github.com/astriaorg/astria/blob/6902ef35370e5980a76302fc756e1a9a56af21b5/proto/sequencerblockapis/astria/sequencerblock/v1alpha1/block.proto#L76). @@ -92,7 +93,8 @@ The signer of this action must be the bridge account's `withdrawer_address`. changes the bridge account's sudo and/or withdrawer addresses. The signer of this action must be the bridge account's `sudo_address`. -The two IBC actions which can also perform bridging actions are an `IbcRelay` which contains an `Ics20Transfer` packet, and `Ics20Withdrawal`. +The two IBC actions which can also perform bridging actions are an `IbcRelay` +which contains an `Ics20Transfer` packet, and `Ics20Withdrawal`. - [`Ics20Transfer`](https://github.com/astriaorg/astria/blob/6902ef35370e5980a76302fc756e1a9a56af21b5/crates/astria-sequencer/src/ibc/ics20_transfer.rs#L370) packets are received when an IBC transfer to Astria from another chain occurs.