diff --git a/README.md b/README.md index eabbc67..d4cd7e2 100644 --- a/README.md +++ b/README.md @@ -4,6 +4,9 @@ A framework for building solvers for the [OP Stack][op-stack]'s dispute protocol. +> **Note** +> WIP + ## Overview * [`durin-primitives`](./crates/primitives) - Contains primitive types and traits used by other solvers within `durin` as well as agents utilizing the solvers. @@ -26,8 +29,24 @@ implementations of this primitive. The `durin` framework allows developers to cr implementation of a `Dispute Game` and use them within simulations, challenge agents, testing, and more. ## Creating a Solver +1. Create a new crate for your solver under the `crates` directory. +2. Add `durin-primitives` as a dependency to your crate. + 1. Implement the `DisputeGame` trait to model the state of your dispute. + 1. Implement the `DisputeSolver` trait on your solver struct. + 1. Create `Rule`s for your solver. + +### What's a `Rule`? + +A `Rule` is an isolated invariant check on a `DisputeGame`'s state that can be used to determine if a solver's suggested +state transitions hold the state's invariants. The `durin-primitives` trait exports the `Rule` type as well as the `chain_rules` +macro, which can be used to apply multiple rules on top of each other when asserting pre or post conditions for the game's +state transitions. + +As the solvers within `durin` are meant to be consumed by agents who act on their suggestions, it is critical that the +state invariants of the respective games are upheld. `Rule`s allow developers to easily check these invariants and +assert that their solver's suggestions are valid with respect to the state's invariants. -*todo* +![rules](./assets/rules.png) [op-stack]: https://github.com/ethereum-optimism/optimism diff --git a/assets/rules.png b/assets/rules.png new file mode 100644 index 0000000..87d05ca Binary files /dev/null and b/assets/rules.png differ diff --git a/crates/fault/README.md b/crates/fault/README.md new file mode 100644 index 0000000..f9cd3d1 --- /dev/null +++ b/crates/fault/README.md @@ -0,0 +1,34 @@ +# `durin-fault` + +> **Note** +> WIP + +This crate contains an implementation of a solver for [Optimism][optimism]'s `FaultDisputeGame`. This implementation is currently +generic over the `TraceProvider`, `ClaimSolver`, and local resolution algorithm. This allows for expanding the solver to support multiple +backends, such as [Asterisc][asterisc] or [Cannon][cannon], as well as multiple local resolution algorithms, such as @inphi's +new sub-game resolution mechanism. + +## Solvers +* [`AlphaClaimSolver`](./src/solvers/alpha.rs) - The first iteration of the Fault dispute game solver used in the alpha release of the Fault proof system on Optimism. + +### Rules + +`Rules` (see: [Rules](../../README.md)) in `durin-fault` are defined within the `solvers` module. These rules are used to describe the +expected behavior of all possible state transitions that the solver can suggest to the game's state. + +## Trace Providers +* [`AlphabetTraceProvider`](./src/providers/alphabet.rs) - A mock trace provider for the `AlphabetVM` used for testing. + +## Resolution Functions +* *todo* +* [`(Planned) Sweep`] - "Sweep" resolution is the first implementation of a global resolution algorithm for the fault dispute game. In reverse + chronological order, the algorithm looks for the left-most uncountered instruction in the game DAG and compares its + agreement with the root claim to determine the outcome of the game. +* [`(Planned) @inphi's Sub-Game Resolution`] - @inphi's sub-game resolution algorithm is a new resolution algorithm that allows for + the resolution of a game to be split into multiple sub-games. This allows for the solver to reduce the amount of + moves necessary to resolve a game as well as enforce incentive compatibility in bond payouts. + + +[op-stack]: https://github.com/ethereum-optimism/optimism +[cannon]: https://github.com/ethereum-optimism/optimism/tree/develop/cannon +[asterisc]: https://github.com/protolambda/asterisc diff --git a/crates/fault/src/solvers/alpha.rs b/crates/fault/src/solvers/alpha.rs index 7ddad78..c239bcf 100644 --- a/crates/fault/src/solvers/alpha.rs +++ b/crates/fault/src/solvers/alpha.rs @@ -189,6 +189,26 @@ where } } +/// The rules module contains implementations of the [Rule] type for the +/// alpha solver. +/// +/// These rules define the conditions of the game state that must be met before +/// and after state transitions and are used to test the validity of the solving +/// algorithm with various resolution methods. +pub mod rules { + use crate::FaultDisputeState; + use durin_primitives::rule::Rule; + use std::sync::Arc; + + fn pre_move_rules() -> &'static [Rule>] { + &[] + } + + fn post_move_rules() -> &'static [Rule>] { + &[] + } +} + // TODO: prop tests for solving claims. #[cfg(test)] mod test { diff --git a/crates/primitives/src/lib.rs b/crates/primitives/src/lib.rs index 1c98113..21f63ed 100644 --- a/crates/primitives/src/lib.rs +++ b/crates/primitives/src/lib.rs @@ -12,5 +12,4 @@ pub use dispute_game::{Claim, GameStatus, GameType}; mod traits; pub use traits::{DisputeGame, DisputeSolver}; -#[cfg(test)] pub mod rule; diff --git a/crates/primitives/src/rule.rs b/crates/primitives/src/rule.rs index 7ed0e47..ea4ad9b 100644 --- a/crates/primitives/src/rule.rs +++ b/crates/primitives/src/rule.rs @@ -1,7 +1,11 @@ //! This module contains the [Rule] type as well as several helper macros for applying //! rules on top of one another. +//! +//! [Rule]s are functions that take a state, run validation for an invariant, and return +//! the state back if successful or an error if not. They are used to validate state +//! transitions in tests where the various solvers in durin suggest a state transition. -type Rule = Box anyhow::Result>; +pub type Rule = Box anyhow::Result>; #[macro_export] macro_rules! chain_rules { @@ -19,6 +23,7 @@ macro_rules! chain_rules { }}; } +#[cfg(test)] mod test { use super::*;