diff --git a/CODEOWNERS b/CODEOWNERS index cc8bf64ca..9a7ed72c3 100644 --- a/CODEOWNERS +++ b/CODEOWNERS @@ -27,3 +27,4 @@ rust-toolchain @astriaorg/rust-reviewers .cargo/ @astriaorg/rust-reviewers nextest.toml @astriaorg/rust-reviewers rusfmt.toml @astriaorg/rust-reviewers +crates/src/*/CHANGELOG.md @astriaorg/rust-reviewers diff --git a/Cargo.lock b/Cargo.lock index 273ebe907..77eebec8a 100644 --- a/Cargo.lock +++ b/Cargo.lock @@ -514,7 +514,7 @@ dependencies = [ [[package]] name = "astria-bridge-withdrawer" -version = "1.0.0-rc.2" +version = "1.0.0" dependencies = [ "astria-bridge-contracts", "astria-build-info", @@ -592,7 +592,7 @@ dependencies = [ [[package]] name = "astria-composer" -version = "1.0.0-rc.2" +version = "1.0.0" dependencies = [ "astria-build-info", "astria-config", @@ -636,7 +636,7 @@ dependencies = [ [[package]] name = "astria-conductor" -version = "1.0.0-rc.2" +version = "1.0.0" dependencies = [ "astria-build-info", "astria-config", @@ -781,7 +781,7 @@ dependencies = [ [[package]] name = "astria-merkle" -version = "1.0.0-rc.1" +version = "1.0.0" dependencies = [ "ct-merkle", "divan", @@ -792,7 +792,7 @@ dependencies = [ [[package]] name = "astria-sequencer" -version = "1.0.0-rc.2" +version = "1.0.0" dependencies = [ "astria-build-info", "astria-config", @@ -867,7 +867,7 @@ dependencies = [ [[package]] name = "astria-sequencer-relayer" -version = "1.0.0-rc.2" +version = "1.0.0" dependencies = [ "assert-json-diff", "astria-build-info", diff --git a/crates/astria-bridge-withdrawer/CHANGELOG.md b/crates/astria-bridge-withdrawer/CHANGELOG.md index e1a34fc11..e6a9a7b55 100644 --- a/crates/astria-bridge-withdrawer/CHANGELOG.md +++ b/crates/astria-bridge-withdrawer/CHANGELOG.md @@ -9,6 +9,12 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0 ## [Unreleased] +## [1.0.0] - 2024-10-25 + +### Changed + +- Bump penumbra dependencies [#1740](https://github.com/astriaorg/astria/pull/1740). + ## [1.0.0-rc.2] - 2024-10-23 ### Added @@ -87,7 +93,8 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0 - Initial release of EVM Withdrawer. -[unreleased]: https://github.com/astriaorg/astria/compare/bridge-withdrawer-v1.0.0-rc.2...HEAD +[unreleased]: https://github.com/astriaorg/astria/compare/bridge-withdrawer-v1.0.0...HEAD +[1.0.0]: https://github.com/astriaorg/astria/compare/bridge-withdrawer-v1.0.0-rc.2...bridge-withdrawer-v1.0.0 [1.0.0-rc.2]: https://github.com/astriaorg/astria/compare/bridge-withdrawer-v1.0.0-rc.1...bridge-withdrawer-v1.0.0-rc.2 [1.0.0-rc.1]: https://github.com/astriaorg/astria/compare/bridge-withdrawer-v0.3.0...bridge-withdrawer-v1.0.0-rc.1 [0.3.0]: https://github.com/astriaorg/astria/compare/bridge-withdrawer-v0.2.1...bridge-withdrawer-v0.3.0 diff --git a/crates/astria-bridge-withdrawer/Cargo.toml b/crates/astria-bridge-withdrawer/Cargo.toml index d59f11ba0..ade0a71d3 100644 --- a/crates/astria-bridge-withdrawer/Cargo.toml +++ b/crates/astria-bridge-withdrawer/Cargo.toml @@ -1,6 +1,6 @@ [package] name = "astria-bridge-withdrawer" -version = "1.0.0-rc.2" +version = "1.0.0" edition = "2021" rust-version = "1.81.0" license = "MIT OR Apache-2.0" diff --git a/crates/astria-composer/CHANGELOG.md b/crates/astria-composer/CHANGELOG.md index 01384cbcb..e430c3d06 100644 --- a/crates/astria-composer/CHANGELOG.md +++ b/crates/astria-composer/CHANGELOG.md @@ -9,6 +9,12 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0 ## [Unreleased] +## [1.0.0] - 2024-10-25 + +### Changed + +- Bump penumbra dependencies [#1740](https://github.com/astriaorg/astria/pull/1740). + ## [1.0.0-rc.2] - 2024-10-23 ### Changed @@ -203,7 +209,8 @@ TransferAction` [#719](https://github.com/astriaorg/astria/pull/719). - Initial release. -[unreleased]: https://github.com/astriaorg/astria/compare/composer-v1.0.0-rc.2...HEAD +[unreleased]: https://github.com/astriaorg/astria/compare/composer-v1.0.0...HEAD +[1.0.0]: https://github.com/astriaorg/astria/compare/composer-v1.0.0-rc.2...composer-v1.0.0 [1.0.0-rc.2]: https://github.com/astriaorg/astria/compare/composer-v1.0.0-rc.1...composer-v1.0.0-rc.2 [1.0.0-rc.1]: https://github.com/astriaorg/astria/compare/composer-v0.8.3...composer-v1.0.0-rc.1 [0.8.3]: https://github.com/astriaorg/astria/compare/composer-v0.8.2...composer-v0.8.3 diff --git a/crates/astria-composer/Cargo.toml b/crates/astria-composer/Cargo.toml index 33a71f0b3..5c62d2de7 100644 --- a/crates/astria-composer/Cargo.toml +++ b/crates/astria-composer/Cargo.toml @@ -1,6 +1,6 @@ [package] name = "astria-composer" -version = "1.0.0-rc.2" +version = "1.0.0" edition = "2021" rust-version = "1.81.0" license = "MIT OR Apache-2.0" diff --git a/crates/astria-conductor/CHANGELOG.md b/crates/astria-conductor/CHANGELOG.md index ff04c7535..eb75e304d 100644 --- a/crates/astria-conductor/CHANGELOG.md +++ b/crates/astria-conductor/CHANGELOG.md @@ -9,6 +9,12 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0 ## [Unreleased] +## [1.0.0] - 2024-10-25 + +### Changed + +- Bump penumbra dependencies [#1740](https://github.com/astriaorg/astria/pull/1740). + ## [1.0.0-rc.2] - 2024-10-23 ### Changed @@ -346,7 +352,8 @@ address [#721](https://github.com/astriaorg/astria/pull/721). - Initial release. -[unreleased]: https://github.com/astriaorg/astria/compare/conductor-v1.0.0-rc.2...HEAD +[unreleased]: https://github.com/astriaorg/astria/compare/conductor-v1.0.0...HEAD +[1.0.0]: https://github.com/astriaorg/astria/compare/conductor-v1.0.0-rc.2...conductor-v1.0.0 [1.0.0-rc.2]: https://github.com/astriaorg/astria/compare/conductor-v1.0.0-rc.1...conductor-v1.0.0-rc.2 [1.0.0-rc.1]: https://github.com/astriaorg/astria/compare/conductor-v0.20.1...conductor-v1.0.0-rc.1 [0.20.1]: https://github.com/astriaorg/astria/compare/conductor-v0.20.0...conductor-v0.20.1 diff --git a/crates/astria-conductor/Cargo.toml b/crates/astria-conductor/Cargo.toml index 6f12d7291..8dc3f608a 100644 --- a/crates/astria-conductor/Cargo.toml +++ b/crates/astria-conductor/Cargo.toml @@ -1,6 +1,6 @@ [package] name = "astria-conductor" -version = "1.0.0-rc.2" +version = "1.0.0" edition = "2021" rust-version = "1.81.0" license = "MIT OR Apache-2.0" diff --git a/crates/astria-core/src/generated/astria.protocol.transaction.v1.rs b/crates/astria-core/src/generated/astria.protocol.transaction.v1.rs index c45f771b9..6bd2ba2fd 100644 --- a/crates/astria-core/src/generated/astria.protocol.transaction.v1.rs +++ b/crates/astria-core/src/generated/astria.protocol.transaction.v1.rs @@ -140,7 +140,7 @@ pub struct Ics20Withdrawal { pub return_address: ::core::option::Option< super::super::super::primitive::v1::Address, >, - /// the height (on Astria) at which this transfer expires. + /// the height (on the counterparty chain) at which this transfer expires. #[prost(message, optional, tag = "5")] pub timeout_height: ::core::option::Option, /// the unix timestamp (in nanoseconds) at which this transfer expires. diff --git a/crates/astria-core/src/generated/astria.protocol.transaction.v1alpha1.rs b/crates/astria-core/src/generated/astria.protocol.transaction.v1alpha1.rs index dbc3f654f..75c1bf44b 100644 --- a/crates/astria-core/src/generated/astria.protocol.transaction.v1alpha1.rs +++ b/crates/astria-core/src/generated/astria.protocol.transaction.v1alpha1.rs @@ -140,7 +140,7 @@ pub struct Ics20Withdrawal { pub return_address: ::core::option::Option< super::super::super::primitive::v1::Address, >, - /// the height (on Astria) at which this transfer expires. + /// the height (on the counterparty chain) at which this transfer expires. #[prost(message, optional, tag = "5")] pub timeout_height: ::core::option::Option, /// the unix timestamp (in nanoseconds) at which this transfer expires. diff --git a/crates/astria-core/src/protocol/transaction/v1/action/mod.rs b/crates/astria-core/src/protocol/transaction/v1/action/mod.rs index fedc694ed..c4f8320f9 100644 --- a/crates/astria-core/src/protocol/transaction/v1/action/mod.rs +++ b/crates/astria-core/src/protocol/transaction/v1/action/mod.rs @@ -897,7 +897,7 @@ pub struct Ics20Withdrawal { // an Astria address to use to return funds from this withdrawal // in the case it fails. pub return_address: Address, - // the height (on Astria) at which this transfer expires. + // the height (on the counterparty chain) at which this transfer expires. pub timeout_height: IbcHeight, // the unix timestamp (in nanoseconds) at which this transfer expires. pub timeout_time: u64, @@ -1360,7 +1360,7 @@ enum FeeAssetChangeErrorKind { pub struct InitBridgeAccount { // the rollup ID to register for the sender of this action pub rollup_id: RollupId, - // the assets accepted by the bridge account + // the asset accepted by the bridge account pub asset: asset::Denom, // the fee asset which to pay this action's fees with pub fee_asset: asset::Denom, diff --git a/crates/astria-merkle/CHANGELOG.md b/crates/astria-merkle/CHANGELOG.md index 79cfa766b..bd0d51371 100644 --- a/crates/astria-merkle/CHANGELOG.md +++ b/crates/astria-merkle/CHANGELOG.md @@ -9,7 +9,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0 ## Unreleased -## 1.0.0-rc.1 - 2024-10-17 +## 1.0.0 - 2024-10-25 ### Added diff --git a/crates/astria-merkle/Cargo.toml b/crates/astria-merkle/Cargo.toml index 36f2f967f..19af2d1aa 100644 --- a/crates/astria-merkle/Cargo.toml +++ b/crates/astria-merkle/Cargo.toml @@ -1,6 +1,6 @@ [package] name = "astria-merkle" -version = "1.0.0-rc.1" +version = "1.0.0" edition = "2021" rust-version = "1.81.0" license = "MIT OR Apache-2.0" diff --git a/crates/astria-sequencer-relayer/CHANGELOG.md b/crates/astria-sequencer-relayer/CHANGELOG.md index dd5903743..63d39156a 100644 --- a/crates/astria-sequencer-relayer/CHANGELOG.md +++ b/crates/astria-sequencer-relayer/CHANGELOG.md @@ -9,6 +9,12 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0 ## [Unreleased] +## [1.0.0] - 2024-10-25 + +### Changed + +- Bump penumbra dependencies [#1740](https://github.com/astriaorg/astria/pull/1740). + ## [1.0.0-rc.2] - 2024-10-23 ### Changed @@ -261,7 +267,8 @@ address [#721](https://github.com/astriaorg/astria/pull/721). - Initial release. -[unreleased]: https://github.com/astriaorg/astria/compare/sequencer-relayer-v1.0.0-rc.2...HEAD +[unreleased]: https://github.com/astriaorg/astria/compare/sequencer-relayer-v1.0.0...HEAD +[1.0.0]: https://github.com/astriaorg/astria/compare/sequencer-relayer-v1.0.0-rc.2...sequencer-relayer-v1.0.0 [1.0.0-rc.2]: https://github.com/astriaorg/astria/compare/sequencer-relayer-v1.0.0-rc.1...sequencer-relayer-v1.0.0-rc.2 [1.0.0-rc.1]: https://github.com/astriaorg/astria/compare/sequencer-relayer-v0.16.2...sequencer-relayer-v1.0.0-rc.1 [0.16.2]: https://github.com/astriaorg/astria/compare/sequencer-relayer-v0.16.1...sequencer-relayer-v0.16.2 diff --git a/crates/astria-sequencer-relayer/Cargo.toml b/crates/astria-sequencer-relayer/Cargo.toml index 0a8609bc9..a0eed0eb6 100644 --- a/crates/astria-sequencer-relayer/Cargo.toml +++ b/crates/astria-sequencer-relayer/Cargo.toml @@ -1,6 +1,6 @@ [package] name = "astria-sequencer-relayer" -version = "1.0.0-rc.2" +version = "1.0.0" edition = "2021" license = "MIT OR Apache-2.0" rust-version = "1.81.0" diff --git a/crates/astria-sequencer/CHANGELOG.md b/crates/astria-sequencer/CHANGELOG.md index a9bce246d..9e18802d9 100644 --- a/crates/astria-sequencer/CHANGELOG.md +++ b/crates/astria-sequencer/CHANGELOG.md @@ -9,6 +9,13 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0 ## [Unreleased] +## [1.0.0] - 2024-10-25 + +### Changed + +- Bump penumbra dependencies [#1740](https://github.com/astriaorg/astria/pull/1740). +- Move fee event recording to transaction from block [#1718](https://github.com/astriaorg/astria/pull/1718). + ## [1.0.0-rc.2] - 2024-10-23 ### Changed @@ -435,7 +442,8 @@ address [#721](https://github.com/astriaorg/astria/pull/721). - Initial release. -[unreleased]: https://github.com/astriaorg/astria/compare/sequencer-v1.0.0-rc.2...HEAD +[unreleased]: https://github.com/astriaorg/astria/compare/sequencer-v1.0.0...HEAD +[1.0.0]: https://github.com/astriaorg/astria/compare/sequencer-v1.0.0-rc.2...sequencer-v1.0.0 [1.0.0-rc.2]: https://github.com/astriaorg/astria/compare/sequencer-v1.0.0-rc.1...sequencer-v1.0.0-rc.2 [1.0.0-rc.1]: https://github.com/astriaorg/astria/compare/sequencer-v0.17.0...sequencer-v1.0.0-rc.1 [0.17.0]: https://github.com/astriaorg/astria/compare/cli-v0.4.0...sequencer-v0.17.0 diff --git a/crates/astria-sequencer/Cargo.toml b/crates/astria-sequencer/Cargo.toml index ca1c440af..d56d38dd4 100644 --- a/crates/astria-sequencer/Cargo.toml +++ b/crates/astria-sequencer/Cargo.toml @@ -1,6 +1,6 @@ [package] name = "astria-sequencer" -version = "1.0.0-rc.2" +version = "1.0.0" edition = "2021" license = "MIT OR Apache-2.0" rust-version = "1.81.0" diff --git a/proto/protocolapis/astria/protocol/transaction/v1/action.proto b/proto/protocolapis/astria/protocol/transaction/v1/action.proto index 4493c3566..26cab7579 100644 --- a/proto/protocolapis/astria/protocol/transaction/v1/action.proto +++ b/proto/protocolapis/astria/protocol/transaction/v1/action.proto @@ -78,7 +78,7 @@ message Ics20Withdrawal { // an Astria address to use to return funds from this withdrawal // in the case it fails. astria.primitive.v1.Address return_address = 4; - // the height (on Astria) at which this transfer expires. + // the height (on the counterparty chain) at which this transfer expires. IbcHeight timeout_height = 5; // the unix timestamp (in nanoseconds) at which this transfer expires. uint64 timeout_time = 6; diff --git a/proto/protocolapis/astria/protocol/transaction/v1alpha1/action.proto b/proto/protocolapis/astria/protocol/transaction/v1alpha1/action.proto index 686db5fbd..7cabb29e5 100644 --- a/proto/protocolapis/astria/protocol/transaction/v1alpha1/action.proto +++ b/proto/protocolapis/astria/protocol/transaction/v1alpha1/action.proto @@ -82,7 +82,7 @@ message Ics20Withdrawal { // an Astria address to use to return funds from this withdrawal // in the case it fails. astria.primitive.v1.Address return_address = 4; - // the height (on Astria) at which this transfer expires. + // the height (on the counterparty chain) at which this transfer expires. IbcHeight timeout_height = 5; // the unix timestamp (in nanoseconds) at which this transfer expires. uint64 timeout_time = 6; diff --git a/specs/sequencer-app.md b/specs/sequencer-app.md index 23c1088ee..1779e85bc 100644 --- a/specs/sequencer-app.md +++ b/specs/sequencer-app.md @@ -1,4 +1,4 @@ -# Sequencer application +# Sequencer Application A sequencer blockchain node consists of two components: [CometBFT](https://github.com/cometbft/cometbft) (formerly known as tendermint) @@ -13,7 +13,7 @@ into the application when necessary to execute the state transition logic. This document aims to specify the application logic of the sequencer chain. -## Background and transaction types +## Background and Transaction Types The sequencer chain's primary purpose is to sequence (order) data. This data is not executed on the sequencer chain, as it's destined for other chains (i.e. @@ -23,9 +23,10 @@ Additionally, the sequencer chain has a native token used to pay fees for sequencing. The sequencer is account-based, so every account has an associated balance. -### Accounts and keys +### Accounts and Keys -Currently, the sequencer supports ed25519 keys for accounts and signing. +Currently, the sequencer supports [Ed25519](https://ed25519.cr.yp.to/) keys for +accounts and signing. An address is specified by the first 20 bytes of the sha256 hash of the encoded public key. Similarly to Ethereum, every account implicitly exists on the chain, @@ -41,143 +42,313 @@ idea of "messages", where every transaction can contain multiple messages. The benefit of this is that it guarantees that multiple actions can be executed atomically. -The structure of an unsigned transaction is as follows: +The structure of a transaction body is as follows: ```rust -pub struct Unsigned { - pub(crate) nonce: Nonce, - pub(crate) actions: Vec, +pub struct TransactionBody { + params: TransactionParams, + actions: Actions, } ``` -`Nonce` is an incrementing value that represents how many transactions have been -previously submitted by this account; thus it starts at 0, and must strictly -increase by 1 for each transaction. - -The structure of a signed transaction is as follows: +Transaction parameters and actions are defined as the following: ```rust -pub struct Signed { - /// transaction signature - pub(crate) signature: ed25519_consensus::Signature, - /// the public key of the signer - pub(crate) public_key: ed25519_consensus::VerificationKey, - /// the transaction that was signed - pub(crate) transaction: Unsigned, +pub struct TransactionParams { + nonce: u32, + chain_id: String, } -``` - -The address corresponding to the signer is derived from the -`ed25519_consensus::VerificationKey` (i.e. the public key). -### Actions - -There are currently 2 types of actions implemented. - -The first, part of the `accounts` component, is a value-transfer action: - -```rust -pub struct Transfer { - to: Address, - amount: Balance, +pub(crate) struct Actions { + group: Group, // actions are grouped by "bundleability" and authority level + inner: Vec, } ``` -This action transfers the specified amount funds from the sender to the -recipient. +`Nonce` is an incrementing value that represents how many transactions have been +previously submitted by the transaction signer; thus it starts at 0, and must strictly +increase by 1 for each following transaction. -The second, part of the `sequence` component, accepts generic data with a -specified chain ID: +The structure of a (signed) transaction is as follows: ```rust -pub struct Action { - pub(crate) chain_id: Vec, - pub(crate) data: Vec, +pub struct Transaction { + /// The transaction signature. + signature: ed25519_consensus::Signature, + /// The verification key of the signer. + verification_key: ed25519_consensus::VerificationKey, + /// The transaction body which is signed. + body: TransactionBody, + /// A bytes representation of the transaction body that was signed. Re-encoding + /// the body with protobuf may not be deterministic. + body_bytes: Bytes, } ``` -Note that this action does not have any effect on the state of the sequencer; it -is simply ordered by the sequencer and placed into a block. +The address corresponding to the signer is derived from the +`ed25519_consensus::VerificationKey` (i.e. the public key). -## ABCI block lifecycle +## [Actions](https://buf.build/astria/protocol-apis/docs/main:astria.protocol.transaction.v1) + +The following is an exhaustive list of all user-accessible actions available +to be submitted. + +### Core Protocol Actions + +* `Transfer`: represents a value transfer action between two accounts. It consists +of the following fields: + + | **Field** | **Type** | **Description** | + | --------- | -------- | ----------- | + | to | `Address`| The recipient of the transfer. The "from" address is assumed| + ||| to be the signer of the transaction. | + | amount | `uint128`| The amount to transfer. | + | asset | `string` | The asset to transfer. | + | fee_asset | `string` | The asset used to pay for the action's fees. | + +* `RollupDataSubmission`: a transaction ordered by the sequencer, whose destination +is another chain. It consists of the following: + + | **Field** | **Type** | **Description** | + | --------- | -------- | ----------- | + | rollup_id | `RollupId`| ID of the destination chain. | + | data | `bytes` | The opaque transaction data. | + | fee_asset | `string` | The asset used to pay for the action's fees. | + +### Bridge Actions + +These actions deal with transfering funds to/from a bridge account to be used on +a rollup. + +* `InitBridgeAccount`: initializes a bridge account for the given rollup on the +sequencer chain. The `withdrawer_address` is the only actor authorized to transfer +out of the account. It is set by default to the signer of the transaction, but +can also be set to a different address within the action itself, or changed later +via a `BridgeSudoChange` action. `InitBridgeAccount` consists of the following +fields: + + | **Field** | **Type** | **Description** | + | --------- | -------- | ----------- | + | rollup_id | `RollupId` | The rollup ID with which to register the bridge account.| + | asset | `string` | The asset ID that will be accepted by the account.| + | fee_asset | `string` | The asset with which to pay fees for this action. | + | sudo_address | `Address` | The address which has authority over the bridge| + ||| account. If empty, assigned to the signer. | + | withdrawer_address | `Address` | The address which is allowed to withdraw funds| + ||| from the bridge account. If empty, assigned to the signer.| + +* `BridgeLock`: transfers funds from a sequencer account to a bridge account. +It is effectively similar to `Transfer`. Upon execution of a bridge lock action, +a `Deposit` event will be included in the block data for the rollup this bridge +account is registered to, containing the information of the transfer. + + | **Field** | **Type** | **Description** | + | --------- | -------- | ----------- | + | to | `Address`| The bridge account to transfer to. The "from" address| + ||| is assumed to be the signer of the transaction. | + | amount | `uint128`| The amount to transfer. | + | asset | `string` | The asset to transfer. | + | fee_asset | `string` | The asset used to pay for the action's fees. | + | destination_chain_address | `string` | The address on the destination chain| + ||| which will receive the bridged funds. | + +* `BridgeUnlock`: transfers funds from a bridge account to a sequencer account. +The signer of this transaciton *must* be the authorized withdrawer for this `bridge_address`. +Effectively similar to `Transfer`, it contains the following fields: + + | **Field** | **Type** | **Description** | + | --------- | -------- | ----------- | + | to | `Address`| The account to transfer to. | + | amount | `uint128`| The amount to transfer. | + | fee_asset | `string` | The asset used to pay for the action's fees. | + | memo | `string` | Can be used to provide unique, identifying information| + ||| about the bridge unlock action. | + | bridge_address | `Address` | The address of the bridge account to transfer| + ||| from. | + | rollup_block_number | `uint64` | The block number on the rollup which triggered| + ||| the transaction underlying the bridge unlock. | + | rollup_withdrawal_event_id | `string` | An identifier of the rollup withdrawal| + ||| transaction which can be used to trace distinct rollup events from the bridge.| + +* `BridgeSudoChange`: changes the sudo and/or withdrawer address for the given +bridge account. The signer must be the current bridge sudo account. + + | **Field** | **Type** | **Description** | + | --------- | -------- | ----------- | + | bridge_address | `Address` | The address of the bridge account to which these| + ||| changes should be made. | + | new_sudo_address | `Address` | The new sudo address for the bridge account.| + ||| If unset, will stay the same. | + | new_withdrawer_address | `Address` | The new withdrawer address for the bridge| + ||| account. If unset, will stay the same. | + | fee_asset | `string` | The asset with which to pay fees for this action.| + +### IBC User Actions + +Actions which deal with the IBC protocol. + +* `IbcRelay`: transmits data packets between the sequencer chain and another +chain using the [IBC](https://www.ibcprotocol.dev/) protocol. This is a permissioned +action, and only authorized accounts can relay. As a result, this action is also +free to submit. It has one field: + + | **Field** | **Type** | **Description** | + | --------- | -------- | ----------- | + | raw_action | `google.protobuf.Any` | The raw IBC action. Can be any of | + ||| [these types](https://github.com/penumbra-zone/penumbra/blob/c23270bd3610f0b6b139d4c2e13c8a4a5bb16f07/crates/core/component/ibc/src/ibc_action.rs#L41).| + +* `Ics20Withdrawal`: transfers tokens from a sequencer account to a different +chain via [ICS-20 protocol](https://github.com/cosmos/ibc/blob/main/spec/app/ics-020-fungible-token-transfer/README.md). +It consists of the following: + + | **Field** | **Type** | **Description** | + | --------- | -------- | ----------- | + | amount | `uint218`| The amount to transfer. | + | denom | `string` | The denomination to transfer. | + | destination_chain_address | `string` | The address on the destination chain| + ||| to send the transfer to. Not validated by Astria. | + | return_address | `Address` | The sequencer chain address to return funds to| + ||| in case the withdrawal fails. | + | timeout_height | `IbcHeight` | The counterparty height at which this action expires.| + | timeout_time | `uint64` | The unix timestamp (ns) at which this transfer expires.| + | source_channel | `string` | The source channel used for the withdrawal. | + | fee_asset | `string` | The asset used to pay fees with. | + | memo | `string` | A memo to include with the transfer. | + +## ABCI Block Lifecycle CometBFT makes progress through successive consensus rounds. During each round, -a new block is proposed, voted on by validators, and if >2/3 of validator +a new block is proposed and voted on by validators. If >2/3 of validator staking power votes on a block, it will be committed (finalized). During each round, CometBFT calls into the sequencer app to execute the state transition logic via ABCI (application blockchain interface). -As of CometBFT v0.37, The ABCI methods called during a one-round period are as +As of CometBFT v0.38, The ABCI methods called during a one-round period are as follows: -1. [PrepareProposal](https://docs.cometbft.com/v0.37/spec/abci/abci++_methods#prepareproposal) +1. Prepare/Process Proposal + * [PrepareProposal](https://docs.cometbft.com/v0.38/spec/abci/abci++_methods#prepareproposal) (if the node is a proposer), - [ProcessProposal](https://docs.cometbft.com/v0.37/spec/abci/abci++_methods#processproposal) - (if the node is a validator but not a proposer) -2. [BeginBlock](https://docs.cometbft.com/v0.37/spec/abci/abci++_methods#beginblock) -3. [DeliverTx](https://docs.cometbft.com/v0.37/spec/abci/abci++_methods#delivertx) - (called once for every transaction in the block) -4. [EndBlock](https://docs.cometbft.com/v0.37/spec/abci/abci++_methods#endblock) -5. [Commit](https://docs.cometbft.com/v0.37/spec/abci/abci++_methods#commit) + * [ProcessProposal](https://docs.cometbft.com/v0.38/spec/abci/abci++_methods#processproposal) + (if the node is not a proposer) +2. [FinalizeBlock](https://docs.cometbft.com/v0.38/spec/abci/abci++_methods#finalizeblock) +3. [Commit](https://docs.cometbft.com/v0.38/spec/abci/abci++_methods#commit) ### PrepareProposal -If the node is a validator, and the proposer for this round, `PrepareProposal` -is called. `PrepareProposal` allows the list of transactions suggested by -CometBFT to be modified. Currently, the only modification we make is adding a -commitment to the rollup data for each block. See the [related -spec](./sequencer-inclusion-proofs.md) for more details. +If the given node is a validator as well as the proposer for this round, +`PrepareProposal` is called. `PrepareProposal` allows the list of transactions +suggested by CometBFT to be modified. Currently, the only modification we make is +adding commitments to the rollup data for each block. See the [related spec](./sequencer-inclusion-proofs.md) +for more details. ### ProcessProposal -If the node is a validator, but not the proposer for this round, -`ProcessProposal` is called. This checks if the commitment to the rollup data is -correct. If it is not correct, the validator rejects the block. - -### BeginBlock - -This is executed by all sequencer nodes at the start of a block. It updates the -current block height and timestamp in the state. - -### DeliverTx +For all nodes,`ProcessProposal` is called. However, only validator nodes need to +validate and vote on the proposal. This checks if the commitment to the rollup +data is correct. If it is not correct, the validator rejects the block. -This is executed by all sequencer nodes for each transaction in a block. It -receives bytes, which it parses into a signed transaction. It then performs -stateless and stateful checks before executing the transaction's state changes. +### FinalizeBlock -### EndBlock +This is executed by all sequencer nodes. It is equivalent to the following series +of steps in CometBFT v0.37: -This is executed by all sequencer nodes at the end of a block. It currently is a -no-op. +1. [BeginBlock](https://docs.cometbft.com/v0.37/spec/abci/abci++_methods#beginblock) + * Updates the current block height and timestamp in the app state, then removes + byzantine validators from the app state's current validator set. +2. [DeliverTx](https://docs.cometbft.com/v0.37/spec/abci/abci++_methods#delivertx) + * Performs stateless and stateful checks, then executes each transaction's + state changes for every transaction in the block. After each transaction's + execution, its fees (if any) are deducted from the signer's balance. Fees + are paid to receiver in `EndBlock`. See [fees](#fees) for more details. +3. [EndBlock](https://docs.cometbft.com/v0.37/spec/abci/abci++_methods#endblock) + * Stores any updates to the current validator set, then pays fees to the receiver. ### Commit This is executed by all sequencer nodes to write the state changes to disk. -## Transaction lifecycle +## Transaction Lifecycle The lifecycle of a sequencer transaction is as follows: -- a user/application constructs a `Unsigned` transaction, which they sign, - converting it into a `Signed` transaction -- this transaction is serialized and submitted to a sequencer node via +* A user/application constructs a `TransactionBody`, which they sign, + converting it into a signed `Transaction`. +* This transaction is serialized and submitted to a sequencer node via CometBFT's RPC endpoints `broadcast_tx_..` -- CometBFT calls into the sequencer application to validate the transaction +* CometBFT calls into the sequencer application to validate the transaction using the ABCI method `CheckTx`. `CheckTx` returns either success or an error. - if success is returned, the transaction is added to the CometBFT mempool and - broadcast throughout the network; otherwise, the transaction is discarded. -- the transaction will live in the mempool until it's included in a block + If it is successful, the transaction is added to the CometBFT mempool and + broadcasted throughout the network; otherwise, the transaction is discarded. +* The transaction will live in the mempool until it is included in a block proposal by a proposer. -- once inside a proposed block, the transaction will be executed by `DeliverTx` - during that block's lifecycle. at this point, the transaction will either - execute successfully or fail, but it is included in the block either way. if - the transaction fails, it will be included in the block with a failure result, - and will not have made any state changes. +* During the proposal phase, the proposer executes the transactions it wishes to +include, and only includes ones which succeed. Any transactions which fail execution +are removed from the mempool. Other nodes only accept blocks where all transactions +succeed. + +## ABCI Queries + +The sequencer supports queries directly into its state via ABCI. The current queries +support by the sequencer are the following: + +* **Account Balance:** returns a list of assets and their corresponding balances +for the given account, at the current block height. Usage: + +```sh +abci-cli query --path=accounts/balance/
+``` -## ABCI queries +* **Account Nonce:** returns the account's current nonce. Usage: -The sequencer supports queries directly into its state via ABCI. Currently, the -state queries supported are for: +```sh +abci-cli query --path=accounts/nonce/
+``` + +* **Denom Request:** returns the full asset denomination given the asset ID. Usage: + +```sh +abci-cli query --path=asset/denom/ +``` + +* **Allowed Fee Assets:** returns a list of all currently allowed fee assets. Usage: + +```sh +abci-cli query --path=asset/allowed_fee_assets +``` + +* **Last Bridge TX Hash:** returns the hash of the last transaction that interacted +with the given bridge account. Usage: + +```sh +abci-cli query --path=bridge/account_last_tx_hash/ +``` + +* **Transaction Fee:** returns the estimated fees a given transaction will incur. +Usage: + +```sh +abci-cli query --path=transaction/fee --data= +``` + +* **Bridge Account Info:** returns the `rollup_id`, `asset`, `sudo_address`, and +`withdrawer_address` for the given bridge account. Usage: + +```sh +abci-cli query --path=bridge/account_info/ +``` + +## Fees + +All `Action`s implement fee payment via the same linear formula: + +```text +base + (variable_component * multiplier) +``` -- account balance via the `accounts/balance/ADDRESS` path -- account nonce via the `accounts/nonce/ADDRESS` path +This formula makes it easy to estimate and replicate fees. For actions with no +associated fees, the `base` and `multiplier` are simply stored in the app state +as "0". If there are no fees stored in the state (as opposed to *explicitly* "0"), +the action is de facto "deactivated", and will fail execution. Actions can be "activated" +by calling `FeeChange` for the given action and assigning it fees. Currently, there +is no way to deactivate an action after it has been assigned fees in the app state.