📝 Rule Docs

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,25 @@ 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 define the expected behavior of
+the state transitions, check their invariants, and assert that their solver's suggestions are valid with respect to
+the state's invariants.
 
-*todo*
+![rules](./assets/rules.png)
 
 <!-- LINKS -->
 [op-stack]: https://github.com/ethereum-optimism/optimism

crates/fault/README.md

@@ -0,0 +1,34 @@
+# `durin-fault`
+
+> **Note**
+> WIP
+
+This crate contains an implementation of a solver for the [OP Stack][op-stack]'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.
+
+<!-- LINKS -->
+[op-stack]: https://github.com/ethereum-optimism/optimism
+[cannon]: https://github.com/ethereum-optimism/optimism/tree/develop/cannon
+[asterisc]: https://github.com/protolambda/asterisc

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<Arc<FaultDisputeState>>] {
+        &[]
+    }
+
+    fn post_move_rules() -> &'static [Rule<Arc<FaultDisputeState>>] {
+        &[]
+    }
+}
+
 // TODO: prop tests for solving claims.
 #[cfg(test)]
 mod test {

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;

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<T> = Box<dyn Fn(T) -> anyhow::Result<T>>;
+pub type Rule<T> = Box<dyn Fn(T) -> anyhow::Result<T>>;
 
 #[macro_export]
 macro_rules! chain_rules {
@@ -19,6 +23,7 @@ macro_rules! chain_rules {
     }};
 }
 
+#[cfg(test)]
 mod test {
     use super::*;