LaconicNetwork/block-sdk
10
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases 1 Wiki Activity

readme for default gud

Browse Source
This commit is contained in:
David Terpay 2023-08-16 17:59:52 -04:00
parent e7d99a2948
commit c789c730b1
No known key found for this signature in database
GPG Key ID: 627EFB00DADF0CD1
6 changed files with 45 additions and 133 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

2
block/base/config.go
View File

@ -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

4
block/base/mempool.go
View File

@ -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(

4
block/mempool.go
View File

@ -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

79
lanes/base/README.md
View File

@ -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)
}

2
lanes/base/lane.go
View File

@ -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.

87
lanes/free/README.md
View File

@ -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)
}