mev lane update
This commit is contained in:
David Terpay
@@ -28,8 +28,7 @@ compatible with Cosmos SDK versions greater than or equal to `v0.47.0`.
|
||||
To install the Block SDK, run the following command:
|
||||
|
||||
```bash
|
||||
$ go get github.com/skip-mev/block-sdk/abci
|
||||
$ go get github.com/skip-mev/block-sdk/lanes/free
|
||||
$ go install github.com/skip-mev/block-sdk
|
||||
```
|
||||
|
||||
### 📚 Usage
|
||||
|
||||
+253
-118
@@ -17,144 +17,279 @@ type, called a MsgAuctionBid, that allows the submitter to execute multiple
|
||||
transactions at the top of the block atomically
|
||||
(atomically = directly next to each other).
|
||||
|
||||
## 🏗️ Setup
|
||||
## Install
|
||||
|
||||
> **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
|
||||
|
||||
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
|
||||
|
||||
To install the Block SDK, run the following command:
|
||||
|
||||
```bash
|
||||
$ go get github.com/skip-mev/block-sdk/abci
|
||||
$ go get github.com/skip-mev/block-sdk/lanes/mev
|
||||
```shell
|
||||
$ go install github.com/skip-mev/block-sdk
|
||||
```
|
||||
|
||||
### 📚 Usage
|
||||
## Setup
|
||||
|
||||
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.
|
||||
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 first
|
||||
lane is the MEV lane as the top of block is the most valuable block space.**
|
||||
3. You will also need to create a `PrepareProposalHandler` and a
|
||||
`ProcessProposalHandler` that will be responsible for preparing and processing
|
||||
proposals respectively. Configure the order of the lanes in the
|
||||
`PrepareProposalHandler` and `ProcessProposalHandler` to match the order of the
|
||||
lanes in the `LanedMempool`.
|
||||
> This set up guide will walk you through the process of setting up a POB
|
||||
> application. In particular, we will configure an application with the
|
||||
> following features:
|
||||
>
|
||||
>* MEV lane (auction lane). This will create an MEV lane where users can bid to
|
||||
> have their transactions executed at the top of the block.
|
||||
>* Free lane. This will create a free lane where users can submit transactions
|
||||
> that will be executed for free (no fees).
|
||||
>* Default lane. This will create a default lane where users can submit
|
||||
> transactions that will be executed with the default app logic.
|
||||
>* Builder module that pairs with the auction lane to process auction
|
||||
> transactions and distribute revenue to the auction house.
|
||||
|
||||
```golang
|
||||
import (
|
||||
"github.com/skip-mev/block-sdk/abci"
|
||||
"github.com/skip-mev/block-sdk/lanes/mev"
|
||||
)
|
||||
1. Import the necessary dependencies into your application. This includes the
|
||||
Block SDK proposal handlers + mempool, keeper, builder types, and builder
|
||||
module. This tutorial will go into more detail into each of the dependencies.
|
||||
|
||||
...
|
||||
```
|
||||
|
||||
```golang
|
||||
func NewApp() {
|
||||
```go
|
||||
import (
|
||||
...
|
||||
// 1. Create the lanes.
|
||||
//
|
||||
// NOTE: The lanes are ordered by priority. The first lane is the highest priority
|
||||
// lane and the last lane is the lowest priority lane. Top of block lane allows
|
||||
// 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.
|
||||
//
|
||||
// MEV lane hosts an action at the top of the block.
|
||||
mevConfig := constructor.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()),
|
||||
)
|
||||
"github.com/skip-mev/pob/block-sdk"
|
||||
"github.com/skip-mev/pob/block-sdk/abci"
|
||||
"github.com/skip-mev/pob/block-sdk/lanes/auction"
|
||||
"github.com/skip-mev/pob/block-sdk/lanes/base"
|
||||
"github.com/skip-mev/pob/block-sdk/lanes/free"
|
||||
buildermodule "github.com/skip-mev/block-sdk/x/builder"
|
||||
builderkeeper "github.com/skip-mev/block-sdk/x/builder/keeper"
|
||||
...
|
||||
)
|
||||
```
|
||||
|
||||
// Free lane allows transactions to be included in the next block for free.
|
||||
freeConfig := constructor.LaneConfig{
|
||||
Logger: app.Logger(),
|
||||
TxEncoder: app.txConfig.TxEncoder(),
|
||||
TxDecoder: app.txConfig.TxDecoder(),
|
||||
MaxBlockSpace: math.LegacyZeroDec(),
|
||||
MaxTxs: 0,
|
||||
}
|
||||
freeLane := free.NewFreeLane(
|
||||
freeConfig,
|
||||
constructor.DefaultTxPriority(),
|
||||
free.DefaultMatchHandler(),
|
||||
)
|
||||
2. Add your module to the the `AppModuleBasic` manager. This manager is in
|
||||
charge of setting up basic, non-dependent module elements such as codec
|
||||
registration and genesis verification. This will register the special
|
||||
`MsgAuctionBid` message. When users want to bid for top of block execution,
|
||||
they will submit a transaction - which we call an auction transaction - that
|
||||
includes a single `MsgAuctionBid`. We prevent any other messages from being
|
||||
included in auction transaction to prevent malicious behavior - such as front
|
||||
running or sandwiching.
|
||||
|
||||
// Default lane accepts all other transactions.
|
||||
defaultConfig := constructor.LaneConfig{
|
||||
Logger: app.Logger(),
|
||||
TxEncoder: app.txConfig.TxEncoder(),
|
||||
TxDecoder: app.txConfig.TxDecoder(),
|
||||
MaxBlockSpace: math.LegacyZeroDec(),
|
||||
MaxTxs: 0,
|
||||
}
|
||||
defaultLane := base.NewStandardLane(defaultConfig)
|
||||
```go
|
||||
var (
|
||||
ModuleBasics = module.NewBasicManager(
|
||||
...
|
||||
buildermodule.AppModuleBasic{},
|
||||
)
|
||||
...
|
||||
)
|
||||
```
|
||||
|
||||
// 2. Set up the relateive priority of lanes
|
||||
lanes := []block.Lane{
|
||||
mevLane,
|
||||
freeLane,
|
||||
defaultLane,
|
||||
}
|
||||
mempool := block.NewLanedMempool(app.Logger(), true, lanes...)
|
||||
app.App.SetMempool(mempool)
|
||||
3. The builder `Keeper` is POB's gateway to processing special `MsgAuctionBid`
|
||||
messages that allow users to participate in the top of block auction, distribute
|
||||
revenue to the auction house, and ensure the validity of auction transactions.
|
||||
|
||||
...
|
||||
a. First add the keeper to the app's struct definition. We also want to add
|
||||
MEV lane's custom checkTx handler to the app's struct definition. This will
|
||||
allow us to override the default checkTx handler to process bid transactions
|
||||
before they are inserted into the mempool. NOTE: The custom handler is
|
||||
required as otherwise the auction can be held hostage by a malicious
|
||||
users.
|
||||
|
||||
// 3. Set up the ante handler.
|
||||
anteDecorators := []sdk.AnteDecorator{
|
||||
ante.NewSetUpContextDecorator(),
|
||||
```go
|
||||
type App struct {
|
||||
...
|
||||
utils.NewIgnoreDecorator(
|
||||
ante.NewDeductFeeDecorator(
|
||||
options.BaseOptions.AccountKeeper,
|
||||
options.BaseOptions.BankKeeper,
|
||||
options.BaseOptions.FeegrantKeeper,
|
||||
options.BaseOptions.TxFeeChecker,
|
||||
),
|
||||
options.FreeLane,
|
||||
),
|
||||
// BuilderKeeper is the keeper that handles processing auction transactions
|
||||
BuilderKeeper builderkeeper.Keeper
|
||||
|
||||
// Custom checkTx handler
|
||||
checkTxHandler mev.CheckTx
|
||||
}
|
||||
```
|
||||
|
||||
b. Add the builder module to the list of module account permissions. This will
|
||||
instantiate the builder module account on genesis.
|
||||
|
||||
```go
|
||||
maccPerms = map[string][]string{
|
||||
builder.ModuleName: nil,
|
||||
...
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
anteHandler := sdk.ChainAnteDecorators(anteDecorators...)
|
||||
c. Instantiate the blockbuster mempool with the application's desired lanes.
|
||||
|
||||
// Set the lane ante handlers on the lanes.
|
||||
for _, lane := range lanes {
|
||||
lane.SetAnteHandler(anteHandler)
|
||||
}
|
||||
app.App.SetAnteHandler(anteHandler)
|
||||
```go
|
||||
// 1. Create the lanes.
|
||||
//
|
||||
// NOTE: The lanes are ordered by priority. The first lane is the
|
||||
// highest priority lane and the last lane is the lowest priority lane.
|
||||
// Top of block lane allows 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.
|
||||
//
|
||||
// MEV lane hosts an auction at the top of the block.
|
||||
mevConfig := constructor.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()),
|
||||
)
|
||||
|
||||
// 4. Set the abci handlers on base app
|
||||
// Free lane allows transactions to be included in the next block for free.
|
||||
freeConfig := constructor.LaneConfig{
|
||||
Logger: app.Logger(),
|
||||
TxEncoder: app.txConfig.TxEncoder(),
|
||||
TxDecoder: app.txConfig.TxDecoder(),
|
||||
MaxBlockSpace: math.LegacyZeroDec(),
|
||||
MaxTxs: 0,
|
||||
}
|
||||
freeLane := free.NewFreeLane(
|
||||
freeConfig,
|
||||
constructor.DefaultTxPriority(),
|
||||
free.DefaultMatchHandler(),
|
||||
)
|
||||
|
||||
// Standard lane accepts all other transactions.
|
||||
defaultConfig := constructor.LaneConfig{
|
||||
Logger: app.Logger(),
|
||||
TxEncoder: app.txConfig.TxEncoder(),
|
||||
TxDecoder: app.txConfig.TxDecoder(),
|
||||
MaxBlockSpace: math.LegacyZeroDec(),
|
||||
MaxTxs: 0,
|
||||
}
|
||||
defaultLane := base.NewStandardLane(defaultConfig)
|
||||
|
||||
// 2. Set up the relateive priority of lanes
|
||||
lanes := []block.Lane{
|
||||
mevLane,
|
||||
freeLane,
|
||||
defaultLane,
|
||||
}
|
||||
mempool := block.NewLanedMempool(app.Logger(), true, lanes...)
|
||||
app.App.SetMempool(mempool)
|
||||
```
|
||||
|
||||
d. Instantiate the antehandler chain for the application with awareness of the
|
||||
blockbuster mempool. This will allow the application to verify the validity
|
||||
of a transaction respecting the desired logic of a given lane. In this walkthrough,
|
||||
we want the `FeeDecorator` to be ignored for all transactions that should
|
||||
belong to the free lane. Additionally, we want to add the `x/builder`
|
||||
module's `AuctionDecorator` to the ante-handler chain. The `AuctionDecorator`
|
||||
is an AnteHandler decorator that enforces various chain configurable MEV rules.
|
||||
|
||||
```go
|
||||
import (
|
||||
...
|
||||
"github.com/skip-mev/pob/blockbuster"
|
||||
"github.com/skip-mev/pob/blockbuster/utils"
|
||||
builderante "github.com/skip-mev/pob/x/builder/ante"
|
||||
...
|
||||
)
|
||||
|
||||
anteDecorators := []sdk.AnteDecorator{
|
||||
ante.NewSetUpContextDecorator(),
|
||||
...
|
||||
utils.NewIgnoreDecorator(
|
||||
ante.NewDeductFeeDecorator(
|
||||
options.BaseOptions.AccountKeeper,
|
||||
options.BaseOptions.BankKeeper,
|
||||
options.BaseOptions.FeegrantKeeper,
|
||||
options.BaseOptions.TxFeeChecker,
|
||||
),
|
||||
options.FreeLane,
|
||||
),
|
||||
...
|
||||
builderante.NewBuilderDecorator(
|
||||
options.BuilderKeeper,
|
||||
options.TxEncoder,
|
||||
options.TOBLane,
|
||||
options.Mempool,
|
||||
),
|
||||
}
|
||||
|
||||
anteHandler := sdk.ChainAnteDecorators(anteDecorators...)
|
||||
app.SetAnteHandler(anteHandler)
|
||||
|
||||
// Set the antehandlers on the lanes.
|
||||
for _, lane := range lanes {
|
||||
lane.SetAnteHandler(anteHandler)
|
||||
}
|
||||
app.App.SetAnteHandler(anteHandler)
|
||||
```
|
||||
|
||||
e. Instantiate the builder keeper, store keys, and module manager. Note, be
|
||||
sure to do this after all the required keeper dependencies have been instantiated.
|
||||
|
||||
```go
|
||||
keys := storetypes.NewKVStoreKeys(
|
||||
buildertypes.StoreKey,
|
||||
...
|
||||
)
|
||||
|
||||
...
|
||||
app.BuilderKeeper := builderkeeper.NewKeeper(
|
||||
appCodec,
|
||||
keys[buildertypes.StoreKey],
|
||||
app.AccountKeeper,
|
||||
app.BankKeeper,
|
||||
app.DistrKeeper,
|
||||
app.StakingKeeper,
|
||||
authtypes.NewModuleAddress(govv1.ModuleName).String(),
|
||||
)
|
||||
|
||||
|
||||
app.ModuleManager = module.NewManager(
|
||||
builder.NewAppModule(appCodec, app.BuilderKeeper),
|
||||
...
|
||||
)
|
||||
```
|
||||
|
||||
e. Configure the proposal/checkTx handlers on base app.
|
||||
|
||||
```go
|
||||
|
||||
// Create the proposal handler that will be used to build and validate blocks.
|
||||
proposalHandler := abci.NewProposalHandler(
|
||||
app.Logger(),
|
||||
app.TxConfig().TxDecoder(),
|
||||
lanes,
|
||||
app.Logger(),
|
||||
app.txConfig.TxDecoder(),
|
||||
mempool,
|
||||
)
|
||||
app.App.SetPrepareProposal(proposalHandler.PrepareProposalHandler())
|
||||
app.App.SetProcessProposal(proposalHandler.ProcessProposalHandler())
|
||||
|
||||
|
||||
// Set the custom CheckTx handler on BaseApp.
|
||||
checkTxHandler := abci.NewCheckTxHandler(
|
||||
app.App,
|
||||
app.txConfig.TxDecoder(),
|
||||
tobLane,
|
||||
anteHandler,
|
||||
app.ChainID(),
|
||||
)
|
||||
app.SetCheckTx(checkTxHandler.CheckTx())
|
||||
...
|
||||
}
|
||||
```
|
||||
|
||||
|
||||
func (app *TestApp) CheckTx(req cometabci.RequestCheckTx)
|
||||
cometabci.ResponseCheckTx {
|
||||
return app.checkTxHandler(req)
|
||||
}
|
||||
|
||||
// SetCheckTx sets the checkTxHandler for the app.
|
||||
func (app *TestApp) SetCheckTx(handler abci.CheckTx) {
|
||||
app.checkTxHandler = handler
|
||||
}
|
||||
```
|
||||
|
||||
f. Finally, update the app's `InitGenesis` order and ante-handler chain.
|
||||
|
||||
```go
|
||||
genesisModuleOrder := []string{
|
||||
buildertypes.ModuleName,
|
||||
...,
|
||||
}
|
||||
```
|
||||
|
||||
## Params
|
||||
|
||||
Note, before building or upgrading the application, make sure to initialize the
|
||||
escrow address for POB in the parameters of the module. The default parameters
|
||||
initialize the escrow address to be the module account address.
|
||||
|
||||
@@ -35,8 +35,7 @@ compatible with Cosmos SDK versions greater than or equal to `v0.47.0`.
|
||||
To install the Block SDK, run the following command:
|
||||
|
||||
```bash
|
||||
$ go get github.com/skip-mev/block-sdk/abci
|
||||
$ go get github.com/skip-mev/block-sdk/lanes/standard
|
||||
$ go install github.com/skip-mev/block-sdk
|
||||
```
|
||||
|
||||
### 📚 Usage
|
||||
|
||||
Reference in New Issue
Block a user