diff --git a/.github/workflows/book.yaml b/.github/workflows/book.yaml new file mode 100644 index 00000000..6ed80422 --- /dev/null +++ b/.github/workflows/book.yaml @@ -0,0 +1,132 @@ +name: book + +concurrency: + cancel-in-progress: true + group: ${{github.workflow}}-${{github.ref}} + +on: + push: + branches: [main] + pull_request: + branches: [main] + merge_group: + +jobs: + test: + runs-on: ubuntu-latest + name: test + + steps: + - uses: actions/checkout@v3 + + - name: Install mdbook + run: | + mkdir mdbook + curl -sSL https://github.com/rust-lang/mdBook/releases/download/v0.4.14/mdbook-v0.4.14-x86_64-unknown-linux-gnu.tar.gz | tar -xz --directory=./mdbook + echo `pwd`/mdbook >> $GITHUB_PATH + + - name: Install mdbook-template + run: | + mkdir mdbook-template + curl -sSL https://github.com/sgoudham/mdbook-template/releases/latest/download/mdbook-template-x86_64-unknown-linux-gnu.tar.gz | tar -xz --directory=./mdbook-template + echo `pwd`/mdbook-template >> $GITHUB_PATH + + - name: Run tests + run: mdbook test + + lint: + runs-on: ubuntu-latest + name: lint + + steps: + - uses: actions/checkout@v3 + + - name: Install mdbook-linkcheck + run: | + mkdir mdbook-linkcheck + curl -sSL -o mdbook-linkcheck.zip https://github.com/Michael-F-Bryan/mdbook-linkcheck/releases/latest/download/mdbook-linkcheck.x86_64-unknown-linux-gnu.zip + unzip mdbook-linkcheck.zip -d ./mdbook-linkcheck + chmod +x `pwd`/mdbook-linkcheck/mdbook-linkcheck + echo `pwd`/mdbook-linkcheck >> $GITHUB_PATH + + - name: Run linkcheck + run: mdbook-linkcheck --standalone + + build: + runs-on: ubuntu-latest + steps: + - uses: actions/checkout@v3 + with: + fetch-depth: 0 + + - name: Install toolchain + uses: dtolnay/rust-toolchain@nightly + - uses: Swatinem/rust-cache@v2 + with: + cache-on-failure: true + + - name: Install mdbook + run: | + mkdir mdbook + curl -sSL https://github.com/rust-lang/mdBook/releases/download/v0.4.14/mdbook-v0.4.14-x86_64-unknown-linux-gnu.tar.gz | tar -xz --directory=./mdbook + echo `pwd`/mdbook >> $GITHUB_PATH + + - name: Install mdbook-template + run: | + mkdir mdbook-template + curl -sSL https://github.com/sgoudham/mdbook-template/releases/latest/download/mdbook-template-x86_64-unknown-linux-gnu.tar.gz | tar -xz --directory=./mdbook-template + echo `pwd`/mdbook-template >> $GITHUB_PATH + + - name: Build book + run: mdbook build documentation + + - name: Build docs + run: RUSTDOCFLAGS="--enable-index-page -Zunstable-options" cargo +nightly doc --all --no-deps + + - name: Move docs to book folder + run: | + mkdir -p target/book/docs + mv target/doc documentation/book/docs + + - name: Archive artifact + shell: sh + run: | + chmod -c -R +rX "documentation/book" | + while read line; do + echo "::warning title=Invalid file permissions automatically fixed::$line" + done + tar \ + --dereference --hard-dereference \ + --directory "documentation/book" \ + -cvf "$RUNNER_TEMP/artifact.tar" \ + --exclude=.git \ + --exclude=.github \ + . + + - name: Upload artifact + uses: actions/upload-artifact@v3 + with: + name: github-pages + path: ${{ runner.temp }}/artifact.tar + retention-days: 1 + if-no-files-found: error + + deploy: + # Only deploy if a push to main + if: github.ref_name == 'main' && github.event_name == 'push' + runs-on: ubuntu-latest + needs: [test, lint, build] + + # Grant GITHUB_TOKEN the permissions required to make a Pages deployment + permissions: + pages: write + id-token: write + + environment: + name: github-pages + url: ${{ steps.deployment.outputs.page_url }} + + steps: + - name: Deploy to GitHub Pages + id: deployment + uses: actions/deploy-pages@v2 \ No newline at end of file diff --git a/book.toml b/book.toml index 97e6e903..f5a5e51a 100644 --- a/book.toml +++ b/book.toml @@ -2,5 +2,5 @@ authors = ["Sabnock01"] language = "en" multilingual = false -src = "docs/src" +src = "documentation/src" title = "Arbiter" diff --git a/docs/src/getting_started/agents.md b/docs/src/getting_started/agents.md deleted file mode 100644 index 93a31b2f..00000000 --- a/docs/src/getting_started/agents.md +++ /dev/null @@ -1 +0,0 @@ -# Configuring agents diff --git a/docs/src/getting_started/getting_started.md b/docs/src/getting_started/getting_started.md deleted file mode 100644 index bad55622..00000000 --- a/docs/src/getting_started/getting_started.md +++ /dev/null @@ -1 +0,0 @@ -# Getting Started diff --git a/docs/src/introduction/introduction.md b/docs/src/introduction/introduction.md deleted file mode 100644 index e10b99d0..00000000 --- a/docs/src/introduction/introduction.md +++ /dev/null @@ -1 +0,0 @@ -# Introduction diff --git a/docs/src/SUMMARY.md b/documentation/src/SUMMARY.md similarity index 78% rename from docs/src/SUMMARY.md rename to documentation/src/SUMMARY.md index 1fa0b22a..ef98aa5c 100644 --- a/docs/src/SUMMARY.md +++ b/documentation/src/SUMMARY.md @@ -1,12 +1,11 @@ # Summary - [Introduction](./introduction/introduction.md) - - [Anomaly Detection](./introduction/anomaly_detection.md) + - [Getting Started / Installation](./getting_started/getting_started.md) - - [CLI Installation with Cargo](./getting_started/cargo_install.md) - - [Setting up Simulations](./getting_started/simulation.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) diff --git a/docs/src/auditing/auditing.md b/documentation/src/auditing/auditing.md similarity index 100% rename from docs/src/auditing/auditing.md rename to documentation/src/auditing/auditing.md diff --git a/docs/src/auditing/random_variable.md b/documentation/src/auditing/random_variable.md similarity index 100% rename from docs/src/auditing/random_variable.md rename to documentation/src/auditing/random_variable.md diff --git a/docs/src/contributing/architecture.md b/documentation/src/contributing/architecture.md similarity index 100% rename from docs/src/contributing/architecture.md rename to documentation/src/contributing/architecture.md diff --git a/docs/src/contributing/contributing.md b/documentation/src/contributing/contributing.md similarity index 100% rename from docs/src/contributing/contributing.md rename to documentation/src/contributing/contributing.md diff --git a/docs/src/contributing/open_source.md b/documentation/src/contributing/open_source.md similarity index 100% rename from docs/src/contributing/open_source.md rename to documentation/src/contributing/open_source.md diff --git a/docs/src/contributing/vulnerability_corpus.md b/documentation/src/contributing/vulnerability_corpus.md similarity index 100% rename from docs/src/contributing/vulnerability_corpus.md rename to documentation/src/contributing/vulnerability_corpus.md diff --git a/docs/src/economic_risk/arbitrage.md b/documentation/src/economic_risk/arbitrage.md similarity index 100% rename from docs/src/economic_risk/arbitrage.md rename to documentation/src/economic_risk/arbitrage.md diff --git a/docs/src/economic_risk/economic_risk.md b/documentation/src/economic_risk/economic_risk.md similarity index 100% rename from docs/src/economic_risk/economic_risk.md rename to documentation/src/economic_risk/economic_risk.md diff --git a/docs/src/economic_risk/fee_growth.md b/documentation/src/economic_risk/fee_growth.md similarity index 100% rename from docs/src/economic_risk/fee_growth.md rename to documentation/src/economic_risk/fee_growth.md diff --git a/docs/src/economic_risk/jump_diffusion.md b/documentation/src/economic_risk/jump_diffusion.md similarity index 100% rename from docs/src/economic_risk/jump_diffusion.md rename to documentation/src/economic_risk/jump_diffusion.md diff --git a/docs/src/economic_risk/lp_revenue.md b/documentation/src/economic_risk/lp_revenue.md similarity index 100% rename from docs/src/economic_risk/lp_revenue.md rename to documentation/src/economic_risk/lp_revenue.md diff --git a/docs/src/economic_risk/modeling_risk.md b/documentation/src/economic_risk/modeling_risk.md similarity index 100% rename from docs/src/economic_risk/modeling_risk.md rename to documentation/src/economic_risk/modeling_risk.md diff --git a/documentation/src/getting_started/agents.md b/documentation/src/getting_started/agents.md new file mode 100644 index 00000000..f865e447 --- /dev/null +++ b/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. diff --git a/docs/src/getting_started/examples.md b/documentation/src/getting_started/examples.md similarity index 100% rename from docs/src/getting_started/examples.md rename to documentation/src/getting_started/examples.md diff --git a/docs/src/getting_started/cargo_install.md b/documentation/src/getting_started/getting_started.md similarity index 81% rename from docs/src/getting_started/cargo_install.md rename to documentation/src/getting_started/getting_started.md index 42004737..15dfcb37 100644 --- a/docs/src/getting_started/cargo_install.md +++ b/documentation/src/getting_started/getting_started.md @@ -1,4 +1,4 @@ -# CLI Installation with Cargo +# Getting Started ## Prerequisites @@ -15,7 +15,7 @@ Once Rust is installed, you can install Arbiter from the package registry using cargo install arbiter ``` -You can now run `arbiter --help` to verify your installation and view the help menu. +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). @@ -43,6 +43,13 @@ This initializes a new Arbiter project with a template. You can generate the bin ```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: diff --git a/documentation/src/getting_started/setting_up_simulations.md b/documentation/src/getting_started/setting_up_simulations.md new file mode 100644 index 00000000..5c6692dc --- /dev/null +++ b/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. + diff --git a/docs/src/getting_started/simulation.md b/documentation/src/getting_started/simulation.md similarity index 100% rename from docs/src/getting_started/simulation.md rename to documentation/src/getting_started/simulation.md diff --git a/docs/src/introduction/anomaly_detection.md b/documentation/src/introduction/anomaly_detection.md similarity index 100% rename from docs/src/introduction/anomaly_detection.md rename to documentation/src/introduction/anomaly_detection.md diff --git a/documentation/src/introduction/introduction.md b/documentation/src/introduction/introduction.md new file mode 100644 index 00000000..4d32aa32 --- /dev/null +++ b/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. \ No newline at end of file