-
Notifications
You must be signed in to change notification settings - Fork 75
Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
specs: add native bridging protocol doc (#1177)
## Summary add spec doc which explains the sequencer's native bridging protocol and related actions. ## Background we didn't have any spec doc before on how the bridging protocol worked. ## Changes - add spec doc which explains the sequencer's native bridging protocol and related actions.
- Loading branch information
Showing
1 changed file
with
108 additions
and
0 deletions.
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,108 @@ | ||
| # 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: | ||
|
|
||
| - 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. | ||
|
|
||
| ## 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. | ||
| - 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`. | ||
|
|
||
| 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. |