diff --git a/docs/user/tutorials/_category_.json b/docs/user/tutorials/_category_.json new file mode 100644 index 000000000..c7268a343 --- /dev/null +++ b/docs/user/tutorials/_category_.json @@ -0,0 +1,6 @@ +{ + "label": "Tutorials", + "position": 0, + "link": null + +} \ No newline at end of file diff --git a/docs/user/tutorials/vote-extensions/_category_.json b/docs/user/tutorials/vote-extensions/_category_.json new file mode 100644 index 000000000..48a74d72f --- /dev/null +++ b/docs/user/tutorials/vote-extensions/_category_.json @@ -0,0 +1,5 @@ +{ + "label": "Vote Extensions", + "position": 0, + "link": null +} \ No newline at end of file diff --git a/docs/user/tutorials/vote-extensions/mitigate-frontrunning.md b/docs/user/tutorials/vote-extensions/mitigate-frontrunning.md new file mode 100644 index 000000000..90dacc865 --- /dev/null +++ b/docs/user/tutorials/vote-extensions/mitigate-frontrunning.md @@ -0,0 +1,500 @@ +# Mitigate Auction Front-Running + +In this tutorial, we will be covering: + +* [What are Vote extensions?](#what-are-vote-extensions) +* [Context](#context) +* [Simulation of Auction Front-Running](#simulation-of-auction-front-running) +* [Mitigating Front-running with Vote Extensions](#mitigating-front-running-with-vote-extensions) +* [Demo of Mitigating Front-Running with Vote Extensions](#demo-of-mitigating-front-running-with-vote-extensions) + +## What are Vote extensions? + +Vote extensions is arbitrary information which can be inserted into a block. This feature is part of ABCI 2.0, which is available for use in the SDK 0.50 release and part of the 0.38 CometBFT release. + +More information about vote extensions can be seen [here](../../../build/abci/03-vote-extensions.md). + +## Context + +For this tutorial we are using an example of an application that is mitigating auction front-running. + +Front-running is a potential issue in blockchain systems where a participant gains an advantage by being able to perform actions or transactions ahead of others. In the context of this application, front-running can occur when a validator, who is also a proposer, spots a bid in the mempool and replaces it with their own higher bid. This is also known as "bid sniping". + +Please checkout https://github.com/fatal-fruit/abci-workshop to see the example. + +## Simulation of Auction Front-Running + +To verify an occurrence of front-running, you can navigate to the logs and search for instances of `💨 :: Found a Bid to Snipe`. This specific log message indicates that the validator has identified a bid to potentially front-run. + +Before we start, we need to set up a single node blockchain for local testing. This can be done by running the `setup.sh` script located in the `scripts/single_node` directory. This script initialises a new blockchain and creates three accounts (val1, alice, bob) with initial balances. + +Please switch to the `part-1` branch of the example repository. To run the script, use the following command: + +```shell +./scripts/single_node/setup.sh +``` + +Following running this script, your local testing environment should be ready and you can proceed with the next steps. + +Here's how you can do it: + +1. Run the front-running script: + +```shell +scripts/single_node/frontrun.sh. +``` + +This script simulates a transaction where a user tries to reserve a namespace before another user does. When running the script we see alice attempts to reserve the namespace `bob.cosmos`. + +2. Open the log file of the validator node. The location of this file can vary depending on your setup, but it's typically located in a directory like `$HOME/cosmos/nodes/#{validator}/logs`. The directory in this case will be under the validator so, `beacon` `val1` or `val2`. + +```shell +tail -f $HOME/cosmos/nodes/#{validator}/logs +``` + +3. Search for the log message `💨 :: Found a Bid to Snipe`. You can do this manually or use a command like grep if you're using a Unix-like operating system. + +If you find instances of `💨 :: Found a Bid to Snipe`, it indicates that the validator has identified a bid to potentially front-run. This is the desired behavior in this scenario, demonstrating that front-running has occurred. + +Remember, this is a demonstration of potential malicious behavior by a validator and is not a recommended practice in a real-world application. The purpose of this exercise is to understand the potential issues and how to mitigate them. + +An example of what you might see in the logs is: + +```shell +5:46PM INF 💨 :: Found a Bid to Snipe module=server +``` + +If the log message `💨 :: Found a Bid to Snipe` is not present after running the front-running script, ensure there are bid transactions in the mempool and that your logging level includes Info messages. If these conditions are met and the message is still absent, it indicates that no bids were identified for potential front-running during the proposal building process. + +Next, to verify the status of the namespace `bob.cosmos`, we perform the following command: + +```shell +./build/cosmappd query ns whois bob.cosmos +``` + +You should receive something like this: + +```shell +name: + amount: + - amount: "2000" + denom: uatom + name: bob.cosmos + owner: cosmos185gc7c296w0xjlq9kjdt6gghnqvdmyckv64e7a + resolve_address: cosmos185gc7c296w0xjlq9kjdt6gghnqvdmyckv64e7a +``` + +The owner address corresponds to Alice (`val1` in the keyring) + +## Mitigating Front-running with Vote Extensions + +In this section, we will discuss the steps to mitigate front-running using vote extensions. We will introduce new types within the `abci/types.go` file. These types will be used to handle the process of preparing proposals, processing proposals, and handling vote extensions. + +### Implementing Structs for Vote Extensions + +First, copy the following structs into the `abci/types.go` file during `part-1` of the tutorial and each of these structs serves a specific purpose in the process of mitigating front-running using vote extensions: + +```go +package abci + +import ( + //import the necessary files +) + +type PrepareProposalHandler struct { + logger log.Logger + txConfig client.TxConfig + cdc codec.Codec + mempool *mempool.ThresholdMempool + txProvider provider.TxProvider + keyname string + runProvider bool +} +``` + +The `PrepareProposalHandler` struct is used to handle the preparation of a proposal in the consensus process. It contains several fields: logger for logging information and errors, txConfig for transaction configuration, cdc (Codec) for encoding and decoding transactions, mempool for referencing the set of unconfirmed transactions, txProvider for building the proposal with transactions, keyname for the name of the key used for signing transactions, and runProvider, a boolean flag indicating whether the provider should be run to build the proposal. + +```go +type ProcessProposalHandler struct { + TxConfig client.TxConfig + Codec codec.Codec + Logger log.Logger +} +``` + +After the proposal has been prepared and vote extensions have been included, the ProcessProposalHandler is used to process the proposal. This includes validating the proposal and the included vote extensions. The `ProcessProposalHandler` allows you to access the transaction configuration and codec, which are necessary for processing the vote extensions. + +```go +type VoteExtHandler struct { + logger log.Logger + currentBlock int64 + mempool *mempool.ThresholdMempool + cdc codec.Codec +} +``` + +This struct is used to handle vote extensions. It contains a logger for logging events, the current block number, a mempool for storing transactions, and a codec for encoding and decoding. Vote extensions are a key part of the process to mitigate front-running, as they allow for additional information to be included with each vote. + +```go +type InjectedVoteExt struct { + VoteExtSigner []byte + Bids [][]byte +} + +type InjectedVotes struct { + Votes []InjectedVoteExt +} +``` + +These structs are used to handle injected vote extensions. They include the signer of the vote extension and the bids associated with the vote extension. Each byte array in Bids is a serialised form of a bid transaction. Injected vote extensions are used to add additional information to a vote after it has been created, which can be useful for adding context or additional data to a vote. The serialised bid transactions provide a way to include complex transaction data in a compact, efficient format. + +```go +type AppVoteExtension struct { + Height int64 + Bids [][]byte +} +``` + +This struct is used for application vote extensions. It includes the height of the block and the bids associated with the vote extension. Application vote extensions are used to add additional information to a vote at the application level, which can be useful for adding context or additional data to a vote that is specific to the application. + +```go +type SpecialTransaction struct { + Height int + Bids [][]byte +} +``` + +This struct is used for special transactions. It includes the height of the block and the bids associated with the transaction. Special transactions are used for transactions that need to be handled differently from regular transactions, such as transactions that are part of the process to mitigate front-running. + + +### Implementing Handlers + +To establish the `VoteExtensionHandler`, follow these steps: + +1. Navigate to the `abci/proposal.go` file. This is where we will implement the `VoteExtensionHandler``. + +2. Implement the `NewVoteExtensionHandler` function. This function is a constructor for the `VoteExtHandler` struct. It takes a logger, a mempool, and a codec as parameters and returns a new instance of `VoteExtHandler`. + +```go +func NewVoteExtensionHandler(lg log.Logger, mp *mempool.ThresholdMempool, cdc codec.Codec) *VoteExtHandler { + return &VoteExtHandler{ + logger: lg, + mempool: mp, + cdc: cdc, + } +} +``` + +3. Implement the `ExtendVoteHandler()` method. This method should handle the logic of extending votes, including inspecting the mempool and submitting a list of all pending bids. This will allow you to access the list of unconfirmed transactions in the abci.`RequestPrepareProposal` during the ensuing block. + +```go +func (h *VoteExtHandler) ExtendVoteHandler() sdk.ExtendVoteHandler { + return func(ctx sdk.Context, req *abci.RequestExtendVote) (*abci.ResponseExtendVote, error) { + h.logger.Info(fmt.Sprintf("Extending votes at block height : %v", req.Height)) + + voteExtBids := [][]byte{} + + // Get mempool txs + itr := h.mempool.SelectPending(context.Background(), nil) + for itr != nil { + tmptx := itr.Tx() + sdkMsgs := tmptx.GetMsgs() + + // Iterate through msgs, check for any bids + for _, msg := range sdkMsgs { + switch msg := msg.(type) { + case *nstypes.MsgBid: + // Marshal sdk bids to []byte + bz, err := h.cdc.Marshal(msg) + if err != nil { + h.logger.Error(fmt.Sprintf("Error marshalling VE Bid : %v", err)) + break + } + voteExtBids = append(voteExtBids, bz) + default: + } + } + + // Move tx to ready pool + err := h.mempool.Update(context.Background(), tmptx) + + // Remove tx from app side mempool + if err != nil { + h.logger.Info(fmt.Sprintf("Unable to update mempool tx: %v", err)) + } + + itr = itr.Next() + } + + // Create vote extension + voteExt := AppVoteExtension{ + Height: req.Height, + Bids: voteExtBids, + } + + // Encode Vote Extension + bz, err := json.Marshal(voteExt) + if err != nil { + return nil, fmt.Errorf("Error marshalling VE: %w", err) + } + + return &abci.ResponseExtendVote{VoteExtension: bz}, nil +} +``` + +4. Configure the handler in `app/app.go` as shown below + +```go +bApp := baseapp.NewBaseApp(AppName, logger, db, txConfig.TxDecoder(), baseAppOptions...) +voteExtHandler := abci2.NewVoteExtensionHandler(logger, mempool, appCodec) +bApp.SetExtendVoteHandler(voteExtHandler.ExtendVoteHandler()) +``` + +To give a bit of context on what is happening above, we first create a new instance of `VoteExtensionHandler` with the necessary dependencies (logger, mempool, and codec). Then, we set this handler as the `ExtendVoteHandler` for our application. This means that whenever a vote needs to be extended, our custom `ExtendVoteHandler()` method will be called. + +To test if vote extensions have been propagated, add the following to the `PrepareProposalHandler`: + +```go +if req.Height > 2 { + voteExt := req.GetLocalLastCommit() + h.logger.Info(fmt.Sprintf("🛠️ :: Get vote extensions: %v", voteExt)) +} +``` + +This is how the whole function should look: + +```go +func (h *PrepareProposalHandler) PrepareProposalHandler() sdk.PrepareProposalHandler { + return func(ctx sdk.Context, req *abci.RequestPrepareProposal) (*abci.ResponsePrepareProposal, error) { + h.logger.Info(fmt.Sprintf("🛠️ :: Prepare Proposal")) + var proposalTxs [][]byte + + var txs []sdk.Tx + + // Get Vote Extensions + if req.Height > 2 { + voteExt := req.GetLocalLastCommit() + h.logger.Info(fmt.Sprintf("🛠️ :: Get vote extensions: %v", voteExt)) + } + + itr := h.mempool.Select(context.Background(), nil) + for itr != nil { + tmptx := itr.Tx() + + txs = append(txs, tmptx) + itr = itr.Next() + } + h.logger.Info(fmt.Sprintf("🛠️ :: Number of Transactions available from mempool: %v", len(txs))) + + if h.runProvider { + tmpMsgs, err := h.txProvider.BuildProposal(ctx, txs) + if err != nil { + h.logger.Error(fmt.Sprintf("❌️ :: Error Building Custom Proposal: %v", err)) + } + txs = tmpMsgs + } + + for _, sdkTxs := range txs { + txBytes, err := h.txConfig.TxEncoder()(sdkTxs) + if err != nil { + h.logger.Info(fmt.Sprintf("❌~Error encoding transaction: %v", err.Error())) + } + proposalTxs = append(proposalTxs, txBytes) + } + + h.logger.Info(fmt.Sprintf("🛠️ :: Number of Transactions in proposal: %v", len(proposalTxs))) + + return &abci.ResponsePrepareProposal{Txs: proposalTxs}, nil + } +} +``` + +As mentioned above, we check if vote extensions have been propagated, you can do this by checking the logs for any relevant messages such as `🛠️ :: Get vote extensions:`. If the logs do not provide enough information, you can also reinitialise your local testing environment by running the `./scripts/single_node/setup.sh` script again. + +5. Implement the `ProcessProposalHandler()`. This function is responsible for processing the proposal. It should handle the logic of processing vote extensions, including inspecting the proposal and validating the bids. + +```go +func (h *ProcessProposalHandler) ProcessProposalHandler() sdk.ProcessProposalHandler { + return func(ctx sdk.Context, req *abci.RequestProcessProposal) (resp *abci.ResponseProcessProposal, err error) { + h.Logger.Info(fmt.Sprintf("⚙️ :: Process Proposal")) + + // The first transaction will always be the Special Transaction + numTxs := len(req.Txs) + + h.Logger.Info(fmt.Sprintf("⚙️:: Number of transactions :: %v", numTxs)) + + if numTxs >= 1 { + var st SpecialTransaction + err = json.Unmarshal(req.Txs[0], &st) + if err != nil { + h.Logger.Error(fmt.Sprintf("❌️:: Error unmarshalling special Tx in Process Proposal :: %v", err)) + } + if len(st.Bids) > 0 { + h.Logger.Info(fmt.Sprintf("⚙️:: There are bids in the Special Transaction")) + var bids []nstypes.MsgBid + for i, b := range st.Bids { + var bid nstypes.MsgBid + h.Codec.Unmarshal(b, &bid) + h.Logger.Info(fmt.Sprintf("⚙️:: Special Transaction Bid No %v :: %v", i, bid)) + bids = append(bids, bid) + } + // Validate Bids in Tx + txs := req.Txs[1:] + ok, err := ValidateBids(h.TxConfig, bids, txs, h.Logger) + if err != nil { + h.Logger.Error(fmt.Sprintf("❌️:: Error validating bids in Process Proposal :: %v", err)) + return &abci.ResponseProcessProposal{Status: abci.ResponseProcessProposal_REJECT}, nil + } + if !ok { + h.Logger.Error(fmt.Sprintf("❌️:: Unable to validate bids in Process Proposal :: %v", err)) + return &abci.ResponseProcessProposal{Status: abci.ResponseProcessProposal_REJECT}, nil + } + h.Logger.Info("⚙️:: Successfully validated bids in Process Proposal") + } + } + + return &abci.ResponseProcessProposal{Status: abci.ResponseProcessProposal_ACCEPT}, nil + } +} +``` + +6. Implement the `ProcessVoteExtensions()` function. This function should handle the logic of processing vote extensions, including validating the bids. + +```go +func processVoteExtensions(req *abci.RequestPrepareProposal, log log.Logger) (SpecialTransaction, error) { + log.Info(fmt.Sprintf("🛠️ :: Process Vote Extensions")) + + // Create empty response + st := SpecialTransaction{ + 0, + [][]byte{}, + } + + // Get Vote Ext for H-1 from Req + voteExt := req.GetLocalLastCommit() + votes := voteExt.Votes + + // Iterate through votes + var ve AppVoteExtension + for _, vote := range votes { + // Unmarshal to AppExt + err := json.Unmarshal(vote.VoteExtension, &ve) + if err != nil { + log.Error(fmt.Sprintf("❌ :: Error unmarshalling Vote Extension")) + } + + st.Height = int(ve.Height) + + // If Bids in VE, append to Special Transaction + if len(ve.Bids) > 0 { + log.Info("🛠️ :: Bids in VE") + for _, b := range ve.Bids { + st.Bids = append(st.Bids, b) + } + } + } + + return st, nil +} +``` + +7. Configure the `ProcessProposalHandler()` in app/app.go: + +```go +processPropHandler := abci2.ProcessProposalHandler{app.txConfig, appCodec, logger} +bApp.SetProcessProposal(processPropHandler.ProcessProposalHandler()) +``` + +This sets the `ProcessProposalHandler()` for our application. This means that whenever a proposal needs to be processed, our custom `ProcessProposalHandler()` method will be called. + +To test if the proposal processing and vote extensions are working correctly, you can check the logs for any relevant messages. If the logs do not provide enough information, you can also reinitialize your local testing environment by running the `./scripts/single_node/setup.sh` script again. + +## Demo of Mitigating Front-Running with Vote Extensions + +The purpose of this demo is to test the implementation of the `VoteExtensionHandler` and `PrepareProposalHandler` that we have just added to the codebase. These handlers are designed to mitigate front-running by ensuring that all validators have a consistent view of the mempool when preparing proposals. + +In this demo, we are using a 3 validator network. The Beacon validator is special because it has a custom transaction provider enabled. This means that it can potentially manipulate the order of transactions in a proposal to its advantage (i.e., front-running). + +1. Bootstrap the validator network: This sets up a network with 3 validators. The script `./scripts/configure.sh "bob.cosmos"` is used to configure the network and the validators. + +```shell +./scripts/configure.sh "bob.cosmos" +``` + +2. Have alice attempt to reserve `bob.cosmos`: This is a normal transaction that alice wants to execute. The script ``./scripts/reserve.sh "bob.cosmos"` is used to send this transaction. + +```shell +./scripts/reserve.sh "bob.cosmos" +``` + +3. Query to verify the name has been reserved: This is to check the result of the transaction. The script `./scripts/whois.sh "bob.cosmos"` is used to query the state of the blockchain. + +```shell +./scripts/whois.sh "bob.cosmos" +``` + +It should return: + +```{ + "name": { + "name": "bob.cosmos", + "owner": "cosmos1nq9wuvuju4jdmpmzvxmg8zhhu2ma2y2l2pnu6w", + "resolve_address": "cosmos1h6zy2kn9efxtw5z22rc5k9qu7twl70z24kr3ht", + "amount": [ + { + "denom": "uatom", + "amount": "1000" + } + ] + } +} +``` + +To detect front-running attempts by the beacon, scrutinise the logs during the `ProcessProposal` stage. Open the logs for each validator, including the beacon, `val1`, and `val2`, to observe the following behavior: + +```shell +2:47PM ERR ❌️:: Detected invalid proposal bid :: name:"bob.cosmos" resolveAddress:"cosmos1wmuwv38pdur63zw04t0c78r2a8dyt08hf9tpvd" owner:"cosmos1wmuwv38pdur63zw04t0c78r2a8dyt08hf9tpvd" amount: module=server +2:47PM ERR ❌️:: Unable to validate bids in Process Proposal :: module=server +2:47PM ERR prevote step: state machine rejected a proposed block; this should not happen:the proposer may be misbehaving; prevoting nil err=null height=142 module=consensus round=0 +``` + +5. List the Beacon's keys: This is to verify the addresses of the validators. The script `./scripts/list-beacon-keys.sh` is used to list the keys. + +```shell +./scripts/list-beacon-keys.sh +``` + +We should receive something similar to the following: + +```shell +[ + { + "name": "alice", + "type": "local", + "address": "cosmos1h6zy2kn9efxtw5z22rc5k9qu7twl70z24kr3ht", + "pubkey": "{\"@type\":\"/cosmos.crypto.secp256k1.PubKey\",\"key\":\"A32cvBUkNJz+h2vld4A5BxvU5Rd+HyqpR3aGtvEhlm4C\"}" + }, + { + "name": "barbara", + "type": "local", + "address": "cosmos1nq9wuvuju4jdmpmzvxmg8zhhu2ma2y2l2pnu6w", + "pubkey": "{\"@type\":\"/cosmos.crypto.secp256k1.PubKey\",\"key\":\"Ag9PFsNyTQPoJdbyCWia5rZH9CrvSrjMsk7Oz4L3rXQ5\"}" + }, + { + "name": "beacon-key", + "type": "local", + "address": "cosmos1ez9a6x7lz4gvn27zr368muw8jeyas7sv84lfup", + "pubkey": "{\"@type\":\"/cosmos.crypto.secp256k1.PubKey\",\"key\":\"AlzJZMWyN7lass710TnAhyuFKAFIaANJyw5ad5P2kpcH\"}" + }, + { + "name": "cindy", + "type": "local", + "address": "cosmos1m5j6za9w4qc2c5ljzxmm2v7a63mhjeag34pa3g", + "pubkey": "{\"@type\":\"/cosmos.crypto.secp256k1.PubKey\",\"key\":\"A6F1/3yot5OpyXoSkBbkyl+3rqBkxzRVSJfvSpm/AvW5\"}" + } +] +``` + +This allows us to match up the addresses and see that the bid was not front run by the beacon due as the resolve address is Alice's address and not the beacons address. + +By running this demo, we can verify that the `VoteExtensionHandler` and `PrepareProposalHandler` are working as expected and that they are able to prevent front-running. diff --git a/sidebars.js b/sidebars.js index 40c127c58..2f9cf3c70 100644 --- a/sidebars.js +++ b/sidebars.js @@ -14,9 +14,52 @@ /** @type {import('@docusaurus/plugin-content-docs').SidebarsConfig} */ const sidebars = { // By default, Docusaurus generates a sidebar from the docs folder structure - learnSidebar: [{ type: "autogenerated", dirName: "learn" }], - buildSidebar: [{ type: "autogenerated", dirName: "build" }], - userSidebar: [{ type: "autogenerated", dirName: "user" }], + learnSidebar: [{ type: "autogenerated", dirName: "learn" }, + { + type: "category", + label: "Tutorials", + collapsed: false, + items: [ + { + type: "doc", + id: "user/tutorials/vote-extensions/mitigate-frontrunning", + label: "Mitigating auction Frontrunning", + }, + { + type: "link", + label: "Developer Portal", + href: "https://tutorials.cosmos.network/tutorials/", + }, + ], + } + ], + buildSidebar: [{ type: "autogenerated", dirName: "build" }, + { + type: "category", + label: "Tutorials", + collapsed: false, + items: [ + { + type: "link", + label: "Run a Node, API, and CLI", + href: "https://tutorials.cosmos.network/tutorials/3-run-node/", + }, + { + type: "link", + label: "Run a Cosmos Chain with Ignite CLI", + href: "https://tutorials.cosmos.network/hands-on-exercise/1-ignite-cli/", + }, + { + type: "link", + label: "Understanding Modules", + href: "https://tutorials.cosmos.network/tutorials/8-understand-sdk-modules/", + }, + ], + } + ], + userSidebar: [ + { type: "autogenerated", dirName: "user" }, + ] }; module.exports = sidebars;