rename dir

documentation/src/SUMMARY.md

@@ -0,0 +1,20 @@
+# Summary
+
+- [Introduction](./introduction/introduction.md)
+  <!-- - [Anomaly Detection](./introduction/anomaly_detection.md) -->
+- [Getting Started / Installation](./getting_started/getting_started.md)
+  - [Setting up Simulations](./getting_started/setting_up_simulations.md)
+  - [Configuring Agents](./getting_started/agents.md)
+  <!-- - [Examples](./getting_started/examples.md) -->
+- [Auditing](./auditing/auditing.md)
+  - [Identifying your random variable](./auditing/random_variable.md)
+- [Quantifying Economic Risk / Economic Audits](./economic_risk/economic_risk.md)
+  - [Arbitrage Profit](./economic_risk/arbitrage.md)
+  - [LP Revenue](./economic_risk/lp_revenue.md)
+  - [Fee Growth](./economic_risk/fee_growth.md)
+  - [Frameworks for modeling risk](./economic_risk/modeling_risk.md)
+  - [Jump diffusion](./economic_risk/jump_diffusion.md)
+- [Contributing](./contributing/contributing.md)
+  - [Project Architecture](./contributing/architecture.md)
+  - [Vulnerability Corpus](./contributing/vulnerability_corpus.md)
+  - [Open source and free to use](./contributing/open_source.md)

documentation/src/auditing/auditing.md

@@ -0,0 +1 @@
+# Auditing

documentation/src/auditing/random_variable.md

@@ -0,0 +1 @@
+# Identifying your random variable

documentation/src/contributing/architecture.md

@@ -0,0 +1 @@
+# Project Architecture

documentation/src/contributing/contributing.md

@@ -0,0 +1 @@
+# Contributing

documentation/src/contributing/open_source.md

@@ -0,0 +1 @@
+# Open source and free to use

documentation/src/contributing/vulnerability_corpus.md

@@ -0,0 +1,38 @@
+# Vulnerability Corpus
+
+Here is a running list of vulnerabilities that have been found with Arbiter. This list is not exhaustive, but it is a good starting point for understanding how to use Arbiter to find vulnerabilities. Arbiter has a unique ability to detect anomaly behavior in a production-like environment. This can be used to audit mechanism design in smart contract systems as well as detect vulnerabilities in smart contracts.
+
+## Vulnerabilities
+
+
+### Portfolio Rebalancing: Severity - High
+
+This was a critical vulnerability discovered in the [Portfolio Contracts](https://github.com/primitivefinance/portfolio) that we were auditing internally. The bug is described in this [PR](https://github.com/primitivefinance/portfolio_simulations/pull/36/files). To reproduce the vulnerability you can run the following command:
+
+```bash
+git clone https://github.com/primitivefinance/portfolio_simulations.git
+cd portfolio_simulations
+git checkout (bug-found)-invariant-pre-post-swap
+cargo run --release
+```
+The bug was not caught by our [prior audits](https://github.com/primitivefinance/security) and [extensive test suit](https://github.com/primitivefinance/portfolio/tree/main/test). The simulation ran an arbitrageur against the Portfolio AMM and a stochastic price path. The bug was identified after 18,000 swaps. It turns out that that Portfolio pools can reach an edge case where the pool reaches one of the tails of its liquidity distribution and causes the invariant to jump, affecting the price of the trade. This would allow a swapper to take advantage of the mispriced funds and take funds from LPs. With arbiter we were able to run ~20000 swaps with this emulated protocol state in parallel with other parameters in <30s allowing us to discover this anomaly. 
+
+## Rating System 
+
+**Low**: Includes both Non-critical (code style, clarity, syntax, versioning, off-chain monitoring (events, etc) and Low risk (e.g. assets are not at risk: state handling, function incorrect as to spec, issues with comments). 
+
+**Med**: Assets not at direct risk, but the function of the protocol or its availability could be impacted, or leak value with a hypothetical attack path with stated assumptions, but external requirements.
+
+**High**: Assets can be stolen/lost/compromised directly (or indirectly if there is a valid attack path that does not have hand-wavy hypotheticals). These are considered critical issues that should be addressed immediately.
+
+This criteria is based on the [Code4rena](https://docs.code4rena.com/awarding/judging-criteria/severity-categorization) judging criteria.
+
+### Resources for Classifying Vulnerabilities
+- [CVSS](https://www.first.org/cvss/v3.0/user-guide) system.
+- [OWASP](https://owasp.org/www-community/vulnerabilities/) system.
+- [SWC](https://swcregistry.io/) system.
+- [Code4rena](https://docs.code4rena.com/awarding/judging-criteria/severity-categorization)
+
+## Contributing to the Corpus
+
+If you find any vulnerabilities with Arbiter, please submit a pull request to this file with the vulnerability and a description of the vulnerability, a link to the arbiter repo and post mortem and steps to reproduce. If the vulnerability is in the wild and has not yet been patched, please do your best to work with the team responsible for the vulnerability to resolve the vulnerability before disclosing it publicly. 

documentation/src/economic_risk/arbitrage.md

@@ -0,0 +1 @@
+# Arbitrage Profit

documentation/src/economic_risk/economic_risk.md

@@ -0,0 +1 @@
+# Quantifying Economic Risk / Economic Audits

documentation/src/economic_risk/fee_growth.md

@@ -0,0 +1 @@
+# Fee Growth

documentation/src/economic_risk/jump_diffusion.md

@@ -0,0 +1 @@
+# Jump diffusion

documentation/src/economic_risk/lp_revenue.md

@@ -0,0 +1 @@
+# LP Revenue

documentation/src/economic_risk/modeling_risk.md

@@ -0,0 +1 @@
+# Frameworks for modeling risk

documentation/src/getting_started/agents.md

@@ -0,0 +1,3 @@
+# Configuring agents
+
+Once your contract state is initialized you can think about iterating over your stochastic process and designing your agents to react to certain changes in the systems and contracts. For example an arbitraguer will want to react to price changes in the system.

documentation/src/getting_started/examples.md

@@ -0,0 +1 @@
+# Examples

documentation/src/getting_started/getting_started.md

@@ -0,0 +1,60 @@
+# Getting Started
+
+## Prerequisites
+
+Before installing Arbiter, ensure that you have Rust installed. You can install and verify your Rust installation from the [official website](https://www.rust-lang.org/tools/install).
+
+The Arbiter CLI works alongside [Foundry](https://github.com/foundry-rs/foundry) and aims to provide a similar CLI interface of setting up and interacting with Arbiter projects. Install Foundry from the [official website](https://getfoundry.sh/).
+
+## Installing the Arbiter CLI
+
+### Install using Cargo
+
+Once Rust is installed, you can install Arbiter from the package registry using Cargo. To do this, just run:
+```bash
+cargo install arbiter
+```
+
+You can now run `arbiter --version` to verify your installation.
+
+### Building From Source
+Install Git, if you haven't already. There are many online guides on how to install Git on different devices, including one from [Github](https://github.com/git-guides/install-git).
+
+Once you're done with the above, you can install Arbiter by cloning the repository. The local crate can then be used to install the Arbiter binary on your machine.
+
+```bash
+git clone https://github.com/primitivefinance/arbiter.git
+cargo install --path ./arbiter
+```
+
+You can now run `arbiter --help` to verify your installation and view the help menu.
+
+## Interacting with the Arbiter CLI
+Arbiter provides a Foundry-like CLI experience. You can initialize new projects, generate bindings and execute simulations using the CLI.
+
+To create a new Arbiter project:
+```bash
+arbiter init your-new-project
+cd your-new-project
+```
+
+This initializes a new Arbiter project with a template. You can generate the bindings again by running:
+
+```bash
+arbiter bind
+```
+Arbiter bind wraps `forge bind` and is configured from your cargo.toml. There are three optional fields you can add to your toml to configure arbiter bind. 
+```toml
+[arbiter]
+bindings_workspace = "simulation" # must be a valid workspace member
+submodules = false # change to true if you want the submodule bindings to be generated
+ignore_interfaces = false # change to true if you want to ignore interfaces contracts
+```
+
+The template is executable at this point and you can run it by running:
+
+```bash
+cargo run
+```
+
+You can load or write your own smart contracts in the templates `contracts/` directory and begin writing your own simulations. Arbiter treats Rust smart-contract bindings as first-class citizens. The contract bindings are generated via Foundry's forge command. arbiter bind wraps forge with some convenience features that will generate all your bindings to `src/bindings` as a rust module. Foundry power-users are welcome to use forge directly. You can also manage project dependencies using git submodules via `forge install`. The [Foundry book](https://book.getfoundry.sh/reference/forge/forge-install) provides further details on managing project dependencies and other features.

documentation/src/getting_started/setting_up_simulations.md

@@ -0,0 +1,13 @@
+# Setting up Simulations
+
+At a high level it could be a good idea map out your simulation before you start writing it. Understand some key objectives of your simulation for example maybe you want to look for anomaly behavior and attempt to identify any critical failure points in the system. In this case you want to understand what a failure point is and how you can identify it. Another key thing to think about is what random process do you want to simulate over. Maybe you want to simulate over a random process that represents the price of a token with Geometric Brownian Motion or something more complex like a jump diffusion process, arbiter reexports rust quant and a binding for a liquid exchange that supports this. The last thing to consider is who are the agents in your simulation. Are they arbitrage bots, are they liquidity providers, are they random agents, or are they a combination of all of these. Identify key externally owned accounts and thing about what actions they can take in your simulation.
+
+When deisigning a simulation the first thing you need to think about is what contracts are in your simulation systems. You can start with just a one like in the template repository and add them as you continue your development. Almost all simulation design will start like this.
+
+## Set up Steps
+- Identify key contracts
+- Generate bindings for those contracts
+- Deploy these contracts to the local in memory instance of revm (you can also skip this step in favor of using the forking feature)
+
+After you have a system deployed in your in memory revm instance you are going to want to make sure your system state is correct. This could mean making sure you contracts hold enough balance of some specific tokens. Maybe you want to mint some tokens to a specific address, or you need to do token aprovals for your contracts.
+

documentation/src/getting_started/simulation.md

@@ -0,0 +1 @@
+# Setting up Simulations

documentation/src/introduction/anomaly_detection.md

@@ -0,0 +1 @@
+# Anomaly Detection

documentation/src/introduction/introduction.md

@@ -0,0 +1,10 @@
+# Introduction
+
+Arbiter is a free an open source EVM analysis tool for complex smart contract systems. At it's core it is an in memory EVM sanbox with a set of analysis tools built on top of it. It is designed to be modular, extensible and performant. Arbiter is capable of delivering an array of stachastic analysis toold with evm execution parity. 
+
+## Motivation
+Smart contract engineers need to test their contracts against a wide array of potentially adversarial environments and contract parameters. The static stateless testing of contracts can only take you so far. To truly test the security of a contract, you need to test it against a wide array of dynamic environments that encompass the externalities of Ethereum mainnet. We wanted to do just that with Arbiter.
+
+Both smart contract and financial engineers come together in Decentralized Finance (DeFi) to build and deploy a wide array of complex decentralized applications as well as fincancial strategies respectively. For the latter, a financial engineer may want to test their strategies against thousands of market conditions, contract settings, shocks, and autonomous or random or even AI agents all while making sure their strategy isn't vulnerable to bytecode-level exploits.
+
+To configure such a rich simulation environment on a test or local network is also possible with Arbiter by a change in choice of middleware. The most efficient choice for getting robust, yet quick, simulations would bypass any networking and use a low level language's implementation of the EVM. Furthermore, we can gain control over the EVM worldstate by working directly on revm. We would like the user to have a choice in how they want to simulate their contracts and Arbiter provides that choice.