From 04228b5ec0a6ee83c09861845e1d8018d09ae3a9 Mon Sep 17 00:00:00 2001 From: Colin Roberts Date: Thu, 23 Mar 2023 13:51:43 -0600 Subject: [PATCH] edited README --- README.md | 40 +++++++------------------ crates/cli/src/main.rs | 4 +++ crates/simulate/src/agent.rs | 7 +++-- crates/simulate/src/lib.rs | 3 ++ crates/simulate/src/price_simulation.rs | 30 +++++++++++-------- 5 files changed, 41 insertions(+), 43 deletions(-) diff --git a/README.md b/README.md index 0b127e61..4340f0b8 100644 --- a/README.md +++ b/README.md @@ -7,15 +7,16 @@ > Perform high speed modeling and economic fuzzing with EVM parity. -Ethereum's execution environment, the Ethereum virtual machine (EVM), has given fruit to a rich collection of decentralized applications. The EVM is stack machine that sequentially executes opcodes as decentralized applications are used, deployed, or exploited. Arbiter is a highly configurable rust interface over [revm](https://github.com/bluealloy/revm). +The Ethereum blockchain's execution environment, the Ethereum Virtual machine (EVM), contains a rich collection of decentralized applications. The EVM is stack machine that sequentially executes opcodes sent to it by users and smart contracts. Arbiter is a highly configurable rust interface over [revm](https://github.com/bluealloy/revm) which is a Rust implementation of the EVM stack machine logic. The purpose of Arbiter is to interface with arbitrary agents and contracts and run this all directly on a blazing-fast simulated EVM. -Financial engineers need to study complex portfolio management strategies against many market conditions, contract parameters, and agents. To configure such a rich simulation environment on a test network would take months to get a sufficient quantity of data points to draw conclusions with confidence and isolate key variables. Even with a local network with no block time, the networking latency on port to port communication will be significant. +Financial engineers need to study a wide array of complex portfolio management strategies against thousands of market conditions, contract parameters, and agents. To configure such a rich simulation environment on a test network could be possible, but a more efficient choice for getting the most robust, yet quick, simulations would bypass any local networking and use a low level language's implementation of the EVM. -In financial engineering, this is a critical tool in evaluating capital efficiency, loss vs. rebalancing, and game theoretic security. Arbiter can be used for: +Arbiter is being primarily developed to be a tool in evaluating economic and game theoretic security of DeFi applications. -- Evaluating the game theoretic and composable security of smart contracts in production environments (Security Firms and Academics) -- Engineering and testing new financial products built on top of more primitive financial products (DeFi Firms and Academics) -- Evaluating financial risk and mitigation strategies (Funds, prop-shops, searchers) +Arbiter can be used for: +- Evaluating the game theoretic and composable security of smart contracts in production environments (security firms and academics) +- investigating risk, capital efficiency, rebalancing strategies, and portfolio replication (or performance). (LPs, funds, quants, traders) +- Engineering and testing new financial products built on top of more primitive financial products (DeFi firms and academics) ## Features: @@ -42,31 +43,12 @@ cargo install --path ./crates/cli Set the PROVIDER environment variable to use a custom provider. -## Setting Custom RPC - -If you would like to use your own RPC endpoint, then you can set the environment variable `PROVIDER`. By default, the provider we have set is via Alchemy. To set your own environment variable on a UNIX OS just perform: - -``` -export PROVIDER=https://url-to-your-RPC-endpoint.xyz -``` - -and replace your own URL as needed. Double check the environment variable is set by: - -``` -echo $PROVIDER -``` - -or just list all environment variables with: - -``` -env -``` - -If you need to unset the `PROVIDER` variable, do: - +## Generating Docs +To see the documentation for Arbiter, after cloning the repo, you can run: ``` -unset PROVIDER +cargo doc --workspace --no-deps --open ``` +This will generate and open the docs in your browser. From there, you can look at the documentation for each crate in the Arbiter workspace. ## Contributing diff --git a/crates/cli/src/main.rs b/crates/cli/src/main.rs index f7ecc728..398facb1 100644 --- a/crates/cli/src/main.rs +++ b/crates/cli/src/main.rs @@ -1,3 +1,6 @@ +#![warn(missing_docs)] +//! Main lives in the `cli` crate so that we can do our input parsing. + use clap::{CommandFactory, Parser, Subcommand}; use ethers::prelude::BaseContract; use eyre::Result; @@ -18,6 +21,7 @@ struct Args { command: Option, } +/// Subcommands for the Arbiter CLI. #[derive(Subcommand)] enum Commands { Sim { diff --git a/crates/simulate/src/agent.rs b/crates/simulate/src/agent.rs index 0dfccbae..291742d0 100644 --- a/crates/simulate/src/agent.rs +++ b/crates/simulate/src/agent.rs @@ -16,18 +16,21 @@ pub struct TransactSettings { } /// Basic traits that every `Agent` must implement in order to properly interact with an EVM. pub trait Agent { + /// Used to allow agentws to make a generic call a specific smart contract. fn call_contract( &mut self, contract: &SimulationContract, call_data: Bytes, value: U256, ) -> ExecutionResult; + /// A constructor to build a `TxEnv` for an agent (uses agent data like `address` and `TransactSettings`). fn build_call_transaction( &self, receiver_address: B160, call_data: Bytes, value: U256, ) -> TxEnv; - // TODO: Not sure this needs to be mutable self - fn read_logs(&mut self) -> Vec; + // TODO: Not sure `read_logs` needs to be mutable self. + /// Provides the ability to read event logs from the simulation's EVM. + fn read_logs(&mut self) -> Vec; } diff --git a/crates/simulate/src/lib.rs b/crates/simulate/src/lib.rs index 4f7c1631..ad076e06 100644 --- a/crates/simulate/src/lib.rs +++ b/crates/simulate/src/lib.rs @@ -1,3 +1,6 @@ +#![warn(missing_docs)] +//! Lib crate for describing simulations. + pub mod agent; pub mod environment; pub mod price_simulation; diff --git a/crates/simulate/src/price_simulation.rs b/crates/simulate/src/price_simulation.rs index 513bbad7..96fe2bd3 100644 --- a/crates/simulate/src/price_simulation.rs +++ b/crates/simulate/src/price_simulation.rs @@ -1,34 +1,39 @@ +#![warn(missing_docs)] +//! Used to generate price paths for a simulation. +//! Managers will be able to read from this data to change prices of for infinitely liquid pools. + use plotly::{Plot, Scatter}; use rand::prelude::*; use rand_chacha::ChaCha8Rng; use rand_distr::{Distribution, StandardNormal}; +/// Data needed for a Geometric Brownian Motion (GBM) price path generator information. #[derive(Debug)] pub struct PriceSimulation { - // Name/identifier for the simulation (will set filenames) + /// Name/identifier for the simulation (will set filenames) pub identifier: String, // E.g., "test" - // Numerical timestep for the simulation (typically just 1). + /// Numerical timestep for the simulation (typically just 1). pub timestep: f64, - // Time in string interpretation. + /// Time in string interpretation. pub timescale: String, // E.g., "day" - // Number of steps. + /// Number of steps. pub num_steps: usize, - // Initial price of the simulation. + /// Initial price of the simulation. pub initial_price: f64, - // Price drift of the underlying asset. + /// Price drift of the underlying asset. pub drift: f64, - // Volatility of the underlying asset.c + /// Volatility of the underlying asset.c pub volatility: f64, - // Time data for the simulation. + /// Time data for the simulation. pub time_data: Vec, - // Price data for the simulation. + /// Price data for the simulation. pub price_data: Vec, - // Seed for testing. + /// Seed for testing. pub seed: u64, } impl PriceSimulation { - // Public builder function that instantiates a `Simulation`. + /// Public builder function that instantiates a `Simulation`. pub fn new( timestep: f64, timescale: String, @@ -73,7 +78,7 @@ impl PriceSimulation { seed, } } - + /// Displays a plot of the GBM price path. pub fn plot(&self) { let mut filename = self.identifier.to_owned(); filename.push_str(".html"); @@ -86,6 +91,7 @@ impl PriceSimulation { } } +/// Produces a GBM price path. fn generate_gbm( initial_price: f64, timestep: f64,