diff --git a/block/base/config.go b/block/base/config.go index 61bf266..e9a404f 100644 --- a/block/base/config.go +++ b/block/base/config.go @@ -9,7 +9,7 @@ import ( "github.com/skip-mev/pob/block" ) -// LaneConfig defines the basic functionality needed for a lane. +// LaneConfig defines the basic configurations needed for a lane. type LaneConfig struct { Logger log.Logger TxEncoder sdk.TxEncoder diff --git a/block/base/mempool.go b/block/base/mempool.go index 3efe9ff..22bcf05 100644 --- a/block/base/mempool.go +++ b/block/base/mempool.go @@ -11,7 +11,7 @@ import ( ) type ( - // ConstructorMempool defines a mempool that orders transactions based on the + // Mempool defines a mempool that orders transactions based on the // txPriority. The mempool is a wrapper on top of the SDK's Priority Nonce mempool. // It include's additional helper functions that allow users to determine if a // transaction is already in the mempool and to compare the priority of two @@ -79,7 +79,7 @@ func DefaultTxPriority() TxPriority[string] { } } -// NewMempool returns a new ConstructorMempool. +// NewMempool returns a new Mempool. func NewMempool[C comparable](txPriority TxPriority[C], txEncoder sdk.TxEncoder, maxTx int) *Mempool[C] { return &Mempool[C]{ index: NewPriorityMempool( diff --git a/block/mempool.go b/block/mempool.go index 61290c6..4029c09 100644 --- a/block/mempool.go +++ b/block/mempool.go @@ -14,7 +14,7 @@ import ( var _ Mempool = (*LanedMempool)(nil) type ( - // LanedMempool defines the Block SDK mempool interface. + // Mempool defines the Block SDK mempool interface. Mempool interface { sdkmempool.Mempool @@ -40,7 +40,7 @@ type ( } ) -// NewLanedMempool returns a new Block SDK mempool. The laned mempool is +// NewLanedMempool returns a new Block SDK LanedMempool. The laned mempool is // comprised of a registry of lanes. Each lane is responsible for selecting // transactions according to its own selection logic. The lanes are ordered // according to their priority. The first lane in the registry has the highest diff --git a/lanes/base/README.md b/lanes/base/README.md index 9355271..24be4b4 100644 --- a/lanes/base/README.md +++ b/lanes/base/README.md @@ -1,28 +1,11 @@ -# Default Lane +# 🏗️ Default Lane Setup -> The Default Lane is the most general and least restrictive lane. The Default -> Lane accepts all transactions that are not accepted by the other lanes, is -> generally the lowest priority lane, and consumes all blockspace that is not -> consumed by the other lanes. - -## 📖 Overview - -The default lane should be used to accept all transactions that are not accepted -by the other lanes. - -## 🏗️ Setup - -> **Note** -> -> For a more in depth example of how to use the Block SDK, check out our -> example application in `block-sdk/tests/app/app.go`. - -### 📦 Dependencies +## 📦 Dependencies The Block SDK is built on top of the Cosmos SDK. The Block SDK is currently compatible with Cosmos SDK versions greater than or equal to `v0.47.0`. -### 📥 Installation +## 📥 Installation To install the Block SDK, run the following command: @@ -30,12 +13,13 @@ To install the Block SDK, run the following command: $ go install github.com/skip-mev/block-sdk ``` -### 📚 Usage +## 📚 Usage 1. First determine the set of lanes that you want to use in your application. The -available lanes can be found in our **Lane App Store** in `block-sdk/lanes`. In -your base application, you will need to create a `LanedMempool` composed of the -lanes that you want to use. +available lanes can be found in our +[Lane App Store](https://docs.skip.money/chains/lanes/existing-lanes/default). +In your base application, you will need to create a `LanedMempool` composed of the +lanes you want to use. 2. Next, order the lanes by priority. The first lane is the highest priority lane and the last lane is the lowest priority lane. **It is recommended that the last lane is the default lane.** @@ -45,9 +29,6 @@ proposals respectively. Configure the order of the lanes in the `PrepareProposalHandler` and `ProcessProposalHandler` to match the order of the lanes in the `LanedMempool`. -NOTE: This example walks through setting up the MEV, Free, and Default Lanes. To -only utilize the default lane, ignore the MEV and Free Lane setup. - ```golang import ( "github.com/skip-mev/block-sdk/abci" @@ -56,9 +37,7 @@ import ( ) ... -``` -```golang func NewApp() { ... // 1. Create the lanes. @@ -68,36 +47,9 @@ func NewApp() { // transactions to bid for inclusion at the top of the next block. // // For more information on how to utilize the LaneConfig please - // visit the README in block-sdk/block/base. + // visit the README in docs.skip.money/chains/lanes/build-your-own-lane#-lane-config. // - // MEV lane hosts an action at the top of the block. - mevConfig := base.LaneConfig{ - Logger: app.Logger(), - TxEncoder: app.txConfig.TxEncoder(), - TxDecoder: app.txConfig.TxDecoder(), - MaxBlockSpace: math.LegacyZeroDec(), - MaxTxs: 0, - } - mevLane := mev.NewMEVLane( - mevConfig, - mev.NewDefaultAuctionFactory(app.txConfig.TxDecoder()), - ) - - // Free lane allows transactions to be included in the next block for free. - freeConfig := base.LaneConfig{ - Logger: app.Logger(), - TxEncoder: app.txConfig.TxEncoder(), - TxDecoder: app.txConfig.TxDecoder(), - MaxBlockSpace: math.LegacyZeroDec(), - MaxTxs: 0, - } - freeLane := free.NewFreeLane( - freeConfig, - base.DefaultTxPriority(), - free.DefaultMatchHandler(), - ) - - // Default lane accepts all other transactions. + // Default lane accepts all transactions. defaultConfig := base.LaneConfig{ Logger: app.Logger(), TxEncoder: app.txConfig.TxEncoder(), @@ -107,10 +59,8 @@ func NewApp() { } defaultLane := defaultlane.NewDefaultLane(defaultConfig) - // 2. Set up the relateive priority of lanes + // 2. Set up the relative priority of lanes lanes := []block.Lane{ - mevLane, - freeLane, defaultLane, } mempool := block.NewLanedMempool(app.Logger(), true, lanes...) @@ -118,11 +68,11 @@ func NewApp() { ... - // 3. Set up the ante handler. + // 3. Set up the ante handler. anteDecorators := []sdk.AnteDecorator{ ante.NewSetUpContextDecorator(), ... - utils.NewIgnoreDecorator( // free lane specific set up + utils.NewIgnoreDecorator( ante.NewDeductFeeDecorator( options.BaseOptions.AccountKeeper, options.BaseOptions.BankKeeper, @@ -137,6 +87,9 @@ func NewApp() { anteHandler := sdk.ChainAnteDecorators(anteDecorators...) // Set the lane ante handlers on the lanes. + // + // NOTE: This step is very important. Without the antehandlers, lanes will not + // be able to verify transactions. for _, lane := range lanes { lane.SetAnteHandler(anteHandler) } diff --git a/lanes/base/lane.go b/lanes/base/lane.go index d34b786..136284f 100644 --- a/lanes/base/lane.go +++ b/lanes/base/lane.go @@ -14,7 +14,7 @@ var _ block.Lane = (*DefaultLane)(nil) // DefaultLane defines a default lane implementation. The default lane orders // transactions by the transaction fees. The default lane accepts any transaction -// that is should not be ignored (as defined by the IgnoreList in the LaneConfig). +// that should not be ignored (as defined by the IgnoreList in the LaneConfig). // The default lane builds and verifies blocks in a similar fashion to how the // CometBFT/Tendermint consensus engine builds and verifies blocks pre SDK version // 0.47.0. diff --git a/lanes/free/README.md b/lanes/free/README.md index eef9d3a..db89eb9 100644 --- a/lanes/free/README.md +++ b/lanes/free/README.md @@ -1,29 +1,11 @@ -# Free Lane +# 🏗️ Free Lane Setup -> Leverage the free lane to encourage certain activity (such as staking) on -> your chain. - -## 📖 Overview - -The Free Lane is a lane that allows transactions to be included in the next block -for free. By default, transactions that are staking related (e.g. delegation, -undelegation, redelegate, etc.) are included in the Free Lane, however, this -can be easily replaced! For more information on that, please see the -`MatchHandler` section in the README found in `block-sdk/block/base`. - -## 🏗️ Setup - -> **Note** -> -> For a more in depth example of how to use the Block SDK, check out our -> example application in `block-sdk/tests/app/app.go`. - -### 📦 Dependencies +## 📦 Dependencies The Block SDK is built on top of the Cosmos SDK. The Block SDK is currently compatible with Cosmos SDK versions greater than or equal to `v0.47.0`. -### 📥 Installation +## 📥 Installation To install the Block SDK, run the following command: @@ -31,15 +13,16 @@ To install the Block SDK, run the following command: $ go install github.com/skip-mev/block-sdk ``` -### 📚 Usage +## 📚 Usage 1. First determine the set of lanes that you want to use in your application. The -available lanes can be found in our **Lane App Store** in `block-sdk/lanes`. In -your base application, you will need to create a `LanedMempool` composed of the -lanes that you want to use. +available lanes can be found in our +[Lane App Store](https://docs.skip.money/chains/lanes/existing-lanes/default). +In your base application, you will need to create a `LanedMempool` composed of the +lanes you want to use. *The free lane should not exist on its own. At minimum, it +is recommended that the free lane is paired with the default lane.* 2. Next, order the lanes by priority. The first lane is the highest priority lane -and the last lane is the lowest priority lane. Determine exactly where you want -the free lane to be in the priority order. +and the last lane is the lowest priority lane. 3. Set up your `FeeDeductorDecorator` to ignore the free lane where ever you initialize your `AnteHandler`. This will ensure that the free lane is not subject to deducting transaction fees. @@ -49,16 +32,18 @@ proposals respectively. Configure the order of the lanes in the `PrepareProposalHandler` and `ProcessProposalHandler` to match the order of the lanes in the `LanedMempool`. +NOTE: This example walks through setting up the Free and Default lanes. + ```golang import ( "github.com/skip-mev/block-sdk/abci" - "github.com/skip-mev/block-sdk/lanes/free" + "github.com/skip-mev/block-sdk/block/base" + defaultlane "github.com/skip-mev/block-sdk/lanes/base" + freelane "github.com/skip-mev/block-sdk/lanes/free" ) ... -``` -```golang func NewApp() { ... // 1. Create the lanes. @@ -68,36 +53,9 @@ func NewApp() { // transactions to bid for inclusion at the top of the next block. // // For more information on how to utilize the LaneConfig please - // visit the README in block-sdk/block/base. + // visit the README in docs.skip.money/chains/lanes/build-your-own-lane#-lane-config. // - // MEV lane hosts an action at the top of the block. - mevConfig := base.LaneConfig{ - Logger: app.Logger(), - TxEncoder: app.txConfig.TxEncoder(), - TxDecoder: app.txConfig.TxDecoder(), - MaxBlockSpace: math.LegacyZeroDec(), - MaxTxs: 0, - } - mevLane := mev.NewMEVLane( - mevConfig, - mev.NewDefaultAuctionFactory(app.txConfig.TxDecoder()), - ) - - // Free lane allows transactions to be included in the next block for free. - freeConfig := base.LaneConfig{ - Logger: app.Logger(), - TxEncoder: app.txConfig.TxEncoder(), - TxDecoder: app.txConfig.TxDecoder(), - MaxBlockSpace: math.LegacyZeroDec(), - MaxTxs: 0, - } - freeLane := free.NewFreeLane( - freeConfig, - base.DefaultTxPriority(), - free.DefaultMatchHandler(), - ) - - // Default lane accepts all other transactions. + // Default lane accepts all transactions. defaultConfig := base.LaneConfig{ Logger: app.Logger(), TxEncoder: app.txConfig.TxEncoder(), @@ -105,12 +63,10 @@ func NewApp() { MaxBlockSpace: math.LegacyZeroDec(), MaxTxs: 0, } - defaultLane := base.NewStandardLane(defaultConfig) + defaultLane := defaultlane.NewDefaultLane(defaultConfig) - // 2. Set up the relateive priority of lanes + // 2. Set up the relative priority of lanes lanes := []block.Lane{ - mevLane, - freeLane, defaultLane, } mempool := block.NewLanedMempool(app.Logger(), true, lanes...) @@ -118,7 +74,7 @@ func NewApp() { ... - // 3. Set up the ante handler. + // 3. Set up the ante handler. anteDecorators := []sdk.AnteDecorator{ ante.NewSetUpContextDecorator(), ... @@ -137,6 +93,9 @@ func NewApp() { anteHandler := sdk.ChainAnteDecorators(anteDecorators...) // Set the lane ante handlers on the lanes. + // + // NOTE: This step is very important. Without the antehandlers, lanes will not + // be able to verify transactions. for _, lane := range lanes { lane.SetAnteHandler(anteHandler) }