feat: mev

content/learn/_meta.js

@@ -30,6 +30,13 @@ export default {
 	seidb: 'SeiDB',
 	'sei-giga': 'Sei Giga',
 
+	'-- MEV': {
+		type: 'separator',
+		title: 'MEV'
+	},
+	mev: 'MEV on Sei',
+	'mev-plugins': 'MEV Plugins',
+
 	'-- Consensus': {
 		type: 'separator',
 		title: 'Consensus'

content/learn/mev-plugins.mdx

@@ -0,0 +1,122 @@
+---
+title: "How to Build and Run MEV Plugins on Sei"
+description: "A practical guide for developers and operators to implement, register, and operate MEV plugins on Sei, with annotated code and visual process flows."
+keywords: ["MEV", "plugin", "Sei", "developer guide", "block production", "transaction ordering"]
+---
+
+# How to Build and Run MEV Plugins on Sei
+
+## Introduction
+
+Sei's MEV system is designed to make value extraction programmable, auditable, and operationally transparent. This guide provides a step-by-step walkthrough for experienced developers and node operators who want to implement, register, and operate MEV plugins on Sei. The approach here mirrors the technical rigor and visual clarity of Sei's core protocol explainers.
+
+## Prerequisites
+
+Before you begin, ensure you have:
+
+- Proficiency with Go
+- [Access to the Sei node source code and build environment](/running-a-node)
+- Familiarity with MEV concepts and block production
+
+## MEV Plugin Interface
+
+A Sei MEV plugin is a Go module that implements the following interface:
+
+```go
+// MEVPlugin defines the required methods for a plugin.
+type MEVPlugin interface {
+    Init(config PluginConfig) error
+    OnBundleSubmission(bundle MEVBundle) (BundleResult, error)
+    OnBlockProposal(ctx BlockContext, txs []Tx) ([]Tx, error)
+    Shutdown() error
+}
+```
+
+- `Init`: Called at plugin startup for initialization and configuration.
+- `OnBundleSubmission`: Handles incoming MEV bundles. Use this for validation, filtering, or other custom logic.
+- `OnBlockProposal`: Allows transaction reordering, filtering, or injection during block proposal.
+- `Shutdown`: Cleanup logic on node shutdown.
+
+## Example: Minimal Plugin Implementation
+
+Below is a minimal example of a plugin that accepts all bundles and does not reorder transactions. You can extend this structure to implement custom logic as needed.
+
+```go
+package mymevplugin
+
+import "github.com/sei-protocol/sei-chain/x/mev"
+
+type MyPlugin struct{}
+
+func (p *MyPlugin) Init(config mev.PluginConfig) error {
+    // Initialization logic
+    return nil
+}
+
+func (p *MyPlugin) OnBundleSubmission(bundle mev.MEVBundle) (mev.BundleResult, error) {
+    // Accept all bundles (example)
+    return mev.BundleResult{Accepted: true}, nil
+}
+
+func (p *MyPlugin) OnBlockProposal(ctx mev.BlockContext, txs []mev.Tx) ([]mev.Tx, error) {
+    // No reordering (pass-through)
+    return txs, nil
+}
+
+func (p *MyPlugin) Shutdown() error {
+    // Cleanup logic
+    return nil
+}
+```
+
+## Plugin Registration and Deployment
+
+To register and deploy your MEV plugin:
+
+1. **Place your plugin code** in the `x/mev/plugins/` directory of the Sei node source.
+2. **Register the plugin** in the node configuration file or via a CLI flag.
+3. **Rebuild the node binary** to include your plugin.
+4. **Restart your node** to load the new plugin.
+
+After these steps, your plugin will be loaded and invoked as part of block production.
+
+## Submitting MEV Bundles
+
+You can submit MEV bundles to the node using the `/mev/submitBundle` RPC endpoint. For example:
+
+```json
+{
+  "bundle": [
+    {"tx": "0xabc123...", "metadata": {"searcher": "alice"}},
+    {"tx": "0xdef456..."}
+  ]
+}
+```
+
+POST this JSON to the node's `/mev/submitBundle` endpoint. The plugin's `OnBundleSubmission` method will process the bundle. To query plugin status, use the `/mev/pluginStatus` endpoint.
+
+import { Callout } from 'nextra/components';
+
+<Callout type="info" title="Best Practices">
+<ul>
+  <li>Log plugin activity and errors for operational visibility.</li>
+  <li>Track relevant metrics, such as bundle acceptance rate and processing time.</li>
+  <li>Use standard monitoring tools to observe node and plugin health.</li>
+  <li>Test plugins on a staging node before deploying to production.</li>
+</ul>
+</Callout>
+
+## Security Considerations
+
+<Callout type="danger" title="Security Checklist">
+<ul>
+  <li>Only run plugins that have been reviewed and audited.</li>
+  <li>Restrict access to MEV RPC endpoints by using IP allowlists or API keys.</li>
+  <li>Log and rate-limit bundle submissions to prevent abuse.</li>
+  <li>Review plugin code for panics, resource leaks, and unsafe operations.</li>
+</ul>
+</Callout>
+
+## Troubleshooting
+
+If a plugin fails to load, verify registration and compatibility with the node version. Node crashes may indicate panics or resource exhaustion in plugin code. Rejected bundles may be due to invalid payloads or plugin logic errors. Use profiling tools to diagnose performance issues.

content/learn/mev.mdx

@@ -0,0 +1,110 @@
+---
+title: "MEV on Sei: Technical Overview and Architecture"
+description: "A deep dive into Sei's plugin-based MEV system, including its modular architecture, plugin lifecycle, and integration points."
+keywords: ["MEV", "block production", "plugin system", "Sei architecture", "validator", "searcher", "transaction ordering"]
+---
+
+# MEV on Sei
+
+## Introduction
+
+Maximal Extractable Value (MEV) is a central force in blockchain economics. It determines how transactions are ordered, how blocks are composed, and how incentives are distributed among validators and searchers. While many networks treat MEV as a risk to be minimized, Sei treats it as a programmable, auditable part of the protocol. The MEV system is designed to make extraction explicit, configurable, and observable.
+
+Sei's MEV system is designed for:
+
+- **Parallelized EVM:** Supports high-throughput MEV strategies with efficient transaction processing.
+- **Instant Finality:** MEV outcomes are deterministic and available immediately after block inclusion.
+- **Open Plugin Ecosystem:** Any developer can build, audit, and deploy MEV plugins.
+- **Operational Transparency:** Plugins are observable via logs and metrics, and node operators can manage them without protocol changes.
+- **Extensibility:** The system is designed for future enhancements, including plugin versioning and hot-reloading.
+
+### Intended Users
+
+- **Validators:** Can implement and operate custom MEV strategies to optimize block rewards and transaction flow.
+- **Searchers:** Can submit bundles directly to nodes running compatible plugins.
+- **dApp Developers:** Can build applications that interact with or leverage MEV plugins.
+- **Infrastructure Providers:** Can offer monitoring, analytics, and plugin management services.
+
+## System Architecture
+
+Sei's MEV system is a modular extension to the block production pipeline. It enables node operators to load custom plugins that participate in transaction ordering and bundle processing. The architecture is designed for extensibility, operational transparency, and high throughput.
+> The diagram below illustrates the flow of bundles and data through the Sei MEV system, including external actors, the MEV RPC endpoint, plugin orchestration, transaction pool, and telemetry/monitoring.
+
+```mermaid
+graph TD
+    subgraph Sei Node
+        direction TB
+        A[Block Proposal Engine] -->|Invokes| B[Plugin Manager]
+        B -->|Executes| C[MEV Plugin 1]
+        B -->|Executes| D[MEV Plugin 2]
+        B -->|Executes| E[...]
+        B --> F[Telemetry/Logging]
+        B --> G[Transaction Pool]
+    end
+    H[External Searcher/Relay] -- Submit Bundle --> I(MEV RPC Endpoint)
+    I -- Forwards Bundle --> B
+    C -- May reorder/filter --> G
+    D -- May reorder/filter --> G
+    E -- May reorder/filter --> G
+    F -- Metrics/Logs --> J[Monitoring/Analytics]
+```
+
+### Component Breakdown
+
+The **Block Proposal Engine** is the core of block production. At defined stages, it triggers the plugin manager to allow MEV logic to participate in transaction selection and ordering.
+
+The **Plugin Manager** discovers, loads, and manages all registered MEV plugins. It coordinates plugin execution, ensuring each plugin receives the correct context and data at each lifecycle stage.
+
+**MEV Plugins** are user-defined Go modules that implement the MEV Plugin Interface. Each plugin can inspect, reorder, or filter transactions, and can accept or reject bundles submitted via RPC. Multiple plugins can be loaded simultaneously, and their effects are composed by the plugin manager.
+
+The **Transaction Pool** is the set of candidate transactions for block inclusion. Plugins can modify the contents or order of this pool before block finalization.
+
+The **MEV RPC Endpoint** is an HTTP interface that allows external actors (searchers, relays) to submit bundles or query plugin status. Bundles submitted here are forwarded to the plugin manager for processing.
+
+**Telemetry and Logging** are integrated for operational transparency. All plugin actions, bundle submissions, and transaction modifications are observable for monitoring and analytics.
+
+## Plugin Lifecycle
+
+The MEV plugin lifecycle in Sei is designed to provide clear, auditable stages for plugin operation. Each stage is invoked by the plugin manager at the appropriate time in the block production process.
+
+<div className="grid grid-cols-6 gap-4 my-8">
+  <div className="col-span-1 flex flex-col items-center">
+    <div className="bg-blue-900 text-white rounded-full w-10 h-10 flex items-center justify-center font-bold mb-2">1</div>
+    <div className="text-center text-xs">Registration</div>
+  </div>
+  <div className="col-span-1 flex flex-col items-center">
+    <div className="bg-blue-900 text-white rounded-full w-10 h-10 flex items-center justify-center font-bold mb-2">2</div>
+    <div className="text-center text-xs">Initialization</div>
+  </div>
+  <div className="col-span-1 flex flex-col items-center">
+    <div className="bg-blue-900 text-white rounded-full w-10 h-10 flex items-center justify-center font-bold mb-2">3</div>
+    <div className="text-center text-xs">Bundle Submission</div>
+  </div>
+  <div className="col-span-1 flex flex-col items-center">
+    <div className="bg-blue-900 text-white rounded-full w-10 h-10 flex items-center justify-center font-bold mb-2">4</div>
+    <div className="text-center text-xs">Block Proposal</div>
+  </div>
+  <div className="col-span-1 flex flex-col items-center">
+    <div className="bg-blue-900 text-white rounded-full w-10 h-10 flex items-center justify-center font-bold mb-2">5</div>
+    <div className="text-center text-xs">Telemetry & Logging</div>
+  </div>
+  <div className="col-span-1 flex flex-col items-center">
+    <div className="bg-blue-900 text-white rounded-full w-10 h-10 flex items-center justify-center font-bold mb-2">6</div>
+    <div className="text-center text-xs">Shutdown</div>
+  </div>
+</div>
+
+1. **Registration:** At node startup, the plugin manager scans for available plugins based on configuration or CLI flags. Each plugin is loaded and registered with the manager.
+2. **Initialization:** The plugin manager calls each plugin's initialization method, providing configuration and context. Plugins can allocate resources, load parameters, or establish connections as needed.
+3. **Bundle Submission:** When an external actor submits a bundle via the MEV RPC endpoint, the plugin manager forwards the bundle to all registered plugins. Each plugin can validate, accept, or reject the bundle based on custom logic. Accepted bundles are added to the transaction pool for consideration during block proposal.
+4. **Block Proposal:** During block proposal, the plugin manager invokes each plugin's block proposal hook. Plugins can inspect the transaction pool, reorder or filter transactions, and inject new transactions if required. The final transaction order is determined after all plugins have executed.
+5. **Telemetry and Logging:** Throughout operation, plugins emit logs and metrics. These are collected by the node and made available for monitoring and analytics. All bundle submissions, transaction modifications, and plugin actions are recorded for auditability.
+6. **Shutdown:** On node shutdown, the plugin manager calls each plugin's shutdown method. Plugins can release resources, flush state, or perform cleanup tasks as needed.
+
+## Integration Points
+
+Sei's MEV system exposes several integration points for developers and operators:
+
+- **Block Proposal:** Plugins can reorder, filter, or inject transactions during block proposal.
+- **Bundle Submission:** Plugins can accept and validate MEV bundles via RPC.
+- **Telemetry/Logging:** Plugins can emit custom metrics and logs for monitoring and analytics.