diff --git a/.github/workflows/build.yml b/.github/workflows/build.yml index 09a1fe8..2ae5fad 100644 --- a/.github/workflows/build.yml +++ b/.github/workflows/build.yml @@ -3,6 +3,7 @@ on: paths-ignore: - 'cli' - 'cloud' + - 'docs' - 'frontend' push: branches: diff --git a/README.md b/README.md index 907ab79..9e0d4be 100644 --- a/README.md +++ b/README.md @@ -16,238 +16,16 @@ If, however, no one is able to submit a valid exploit until a certain deadline, [^1]: Some notable examples of programming languages that can run inside Bug Buster are C, C++, Python, Lua, JavaScript, and Rust. [^2]: Bug Buster supports +300 wallets, such as WalletConnect, MetaMask, Trust Wallet, and Coinbase. -## Dependencies - -For your purposes, not all dependencies may be required. -To help you figure out which dependencies you actually need, here is a tree of dependencies for each part of the code base. - -```mermaid -flowchart LR - - %% External Dependencies - - classDef dependency fill:#008DA5,color:#fff - - bash:::dependency - docker:::dependency - cast:::dependency - go:::dependency - jq:::dependency - make:::dependency - pnpm:::dependency - tar:::dependency - xz:::dependency - - %% Bug Buster Components - - classDef component fill:#00F6FF,color:#000 - - BackEnd:::component - Shell:::component - BountyExamples:::component - Tests:::component - PopulateScript:::component - CLI:::component - FrontEnd:::component - - %% Components -> Dependencies - - BackEnd --> docker - BackEnd --> pnpm - Shell --> BackEnd - Shell --> docker - Shell --> make - BountyExamples --> make - BountyExamples --> tar - BountyExamples --> xz - Tests ---> docker - Tests ---> make - Tests --> BountyExamples - PopulateScript ---> bash - PopulateScript ---> cast - PopulateScript ---> jq - PopulateScript ---> pnpm - PopulateScript --> BountyExamples - PopulateScript --> CLI - CLI --> cast - CLI --> go - FrontEnd ---> pnpm -``` - -## Back-end - -### Set up - -First, you need to install the Cartesi CLI with `pnpm`. - -```sh -pnpm i -``` - -### Building the Cartesi Machine image - -#### From source - -```sh -make machine -``` - -#### From a tagged image - -Every release, the machine image is built and published to GitHub Container Registry. -You can retrieve any given version using the `docker pull` command. - -```sh -docker pull --platform linux/riscv64 ghcr.io/crypto-bug-hunters/bug-buster-machine:$VERSION -``` - -Then, you can build the Cartesi Machine image like so. - -```sh -pnpm exec cartesi build --from-image ghcr.io/crypto-bug-hunters/bug-buster-machine:$VERSION -``` - -### Running the Cartesi Node - -``` -pnpm start -``` - -## Tests - -Make sure you first built the machine image. -Then, you may run the tests. - -```sh -make test -``` - -## CLI - -To interact with the contract, you may use the Bug Buster CLI. -For all the options, run the command below. - -```sh -go run ./cli help -``` - -### Showing the current state - -```sh -go run ./cli state -``` - -### Sending dapp address - -```sh -go run ./cli send dapp-address -``` - -### Sending bounty - -```sh -go run ./cli send bounty \ - -n "Lua Bounty" \ - -d "Description of Lua bounty" \ - -c ./tests/bounties/dist/lua-5.4.3-bounty.tar.xz \ - -t 0x92C6bcA388E99d6B304f1Af3c3Cd749Ff0b591e2 -``` - -### Sending sponsor - -```sh -go run ./cli send sponsor \ - -b 0 \ - -n "Sponsor Name" \ - -t 0x92C6bcA388E99d6B304f1Af3c3Cd749Ff0b591e2 \ - -v 5000000 -``` - -### Sending exploit - -```sh -go run ./cli send exploit \ - -b 0 \ - -n "Hacker Name" \ - -e ./tests/bounties/src/lua/exploit-lua-5.4.3.lua -``` - -### Withdraw bounty - -```sh -go run ./cli send withdraw -b 0 -``` - -### Testing exploit - -```sh -go run ./cli test \ - -b 0 \ - -e ./tests/bounties/src/lua/exploit-lua-5.4.3.lua -``` - -## Populating DApp - -Run the following command to fill up the DApp with test data. - -```sh -make populate -``` - -## Front-end - -To run the frontend, execute the commands below. - -```sh -cd frontend -pnpm i -pnpm dev -``` - -Open http://localhost:3000 in your browser. - -## Future Work - -The initial version of this project was developed in one week for the ETHOnline 2023 hackathon. -During this one week, we had to design and implement a project from scratch. -With this very tight schedule, some of the features were left out for later implementation. -Below are some of those features. - -- Support ENS -- Support other types of assets (Ether, ERC-721, and ERC-1155) -- Support syntax highlight on code blocks -- Add optional one-time setup phase for applications -- Add option to download bounty bundle -- Sandbox applications with Hypervisor - -## Debugging - -When running Bug Buster locally, you might want to perform some operations that would otherwise be impossible in a production environment. -To this end, we advise you to install the [Foundry](https://book.getfoundry.sh/getting-started/installation) toolkit. - -### Shell - -If you want to run the machine locally through a shell interface, you can do so through the following command. -Please make sure you have built the machine beforehand. - -```sh -make shell -``` - -### Time travel - -When testing sponsor withdrawals, it's handy to be able to instantly advance time past the expiry date of some bounty. -The following command advances time in 30 days, expressed in seconds. - -```sh -cast rpc evm_increaseTime $((60*60*24*30)) -``` - -### Funding a wallet - -In order to publish transactions, you need some Ether. -The following command sets the balance of address `0xf39Fd...92266` to 1 Ether, expressed in Wei. - -```sh -cast rpc anvil_setBalance 0xf39Fd6e51aad88F6F4ce6aB8827279cffFb92266 $(cast to-wei 1 ether) -``` +## Documentation + +- [Dependencies](docs/dependencies.md) +- Running + - [Back-end](docs/backend.md) + - [Populate script](docs/populate.md) + - [Front-end](docs/frontend.md) +- Contributing + - [Guidelines](docs/contributing.md) + - [Tests](docs/tests.md) + - [Bug Buster CLI](docs/cli.md) + - [Debugging](docs/debug.md) +- [Future work](docs/future.md) diff --git a/docs/backend.md b/docs/backend.md new file mode 100644 index 0000000..2fcf299 --- /dev/null +++ b/docs/backend.md @@ -0,0 +1,38 @@ +## Back-end + +### Set up + +First, you need to install the Cartesi CLI with `pnpm`. + +```sh +pnpm i +``` + +### Building the Cartesi Machine image + +#### From source + +```sh +make machine +``` + +#### From a tagged image + +Every release, the machine image is built and published to GitHub Container Registry. +You can retrieve any given version using the `docker pull` command. + +```sh +docker pull --platform linux/riscv64 ghcr.io/crypto-bug-hunters/bug-buster-machine:$VERSION +``` + +Then, you can build the Cartesi Machine image like so. + +```sh +pnpm exec cartesi build --from-image ghcr.io/crypto-bug-hunters/bug-buster-machine:$VERSION +``` + +### Running the Cartesi Node + +``` +pnpm start +``` diff --git a/docs/cli.md b/docs/cli.md new file mode 100644 index 0000000..188c8ae --- /dev/null +++ b/docs/cli.md @@ -0,0 +1,63 @@ +## CLI + +To interact with the contract, you may use the Bug Buster CLI. +For all the options, run the command below. + +```sh +go run ./cli help +``` + +### Showing the current state + +```sh +go run ./cli state +``` + +### Sending dapp address + +```sh +go run ./cli send dapp-address +``` + +### Sending bounty + +```sh +go run ./cli send bounty \ + -n "Lua Bounty" \ + -d "Description of Lua bounty" \ + -c ./tests/bounties/dist/lua-5.4.3-bounty.tar.xz \ + -t 0x92C6bcA388E99d6B304f1Af3c3Cd749Ff0b591e2 +``` + +### Sending sponsor + +```sh +go run ./cli send sponsor \ + -b 0 \ + -n "Sponsor Name" \ + -t 0x92C6bcA388E99d6B304f1Af3c3Cd749Ff0b591e2 \ + -v 5000000 +``` + +### Sending exploit + +```sh +go run ./cli send exploit \ + -b 0 \ + -n "Hacker Name" \ + -e ./tests/bounties/src/lua/exploit-lua-5.4.3.lua +``` + +### Withdraw bounty + +```sh +go run ./cli send withdraw -b 0 +``` + +### Testing exploit + +```sh +go run ./cli test \ + -b 0 \ + -e ./tests/bounties/src/lua/exploit-lua-5.4.3.lua +``` diff --git a/CONTRIBUTING.md b/docs/contributing.md similarity index 100% rename from CONTRIBUTING.md rename to docs/contributing.md diff --git a/docs/debug.md b/docs/debug.md new file mode 100644 index 0000000..704bf18 --- /dev/null +++ b/docs/debug.md @@ -0,0 +1,31 @@ +## Debugging + +When running Bug Buster locally, you might want to perform some operations that would otherwise be impossible in a production environment. +To this end, we advise you to install the [Foundry](https://book.getfoundry.sh/getting-started/installation) toolkit. + +### Shell + +If you want to run the machine locally through a shell interface, you can do so through the following command. +Please make sure you have built the machine beforehand. + +```sh +make shell +``` + +### Time travel + +When testing sponsor withdrawals, it's handy to be able to instantly advance time past the expiry date of some bounty. +The following command advances time in 30 days, expressed in seconds. + +```sh +cast rpc evm_increaseTime $((60*60*24*30)) +``` + +### Funding a wallet + +In order to publish transactions, you need some Ether. +The following command sets the balance of address `0xf39Fd...92266` to 1 Ether, expressed in Wei. + +```sh +cast rpc anvil_setBalance 0xf39Fd6e51aad88F6F4ce6aB8827279cffFb92266 $(cast to-wei 1 ether) +``` diff --git a/docs/dependencies.md b/docs/dependencies.md new file mode 100644 index 0000000..385060d --- /dev/null +++ b/docs/dependencies.md @@ -0,0 +1,57 @@ +## Dependencies + +For your purposes, not all dependencies may be required. +To help you figure out which dependencies you actually need, here is a tree of dependencies for each part of the code base. + +```mermaid +flowchart LR + + %% External Dependencies + + classDef dependency fill:#008DA5,color:#fff + + bash:::dependency + docker:::dependency + cast:::dependency + go:::dependency + jq:::dependency + make:::dependency + pnpm:::dependency + tar:::dependency + xz:::dependency + + %% Bug Buster Components + + classDef component fill:#00F6FF,color:#000 + + BackEnd:::component + Shell:::component + BountyExamples:::component + Tests:::component + PopulateScript:::component + CLI:::component + FrontEnd:::component + + %% Components -> Dependencies + + BackEnd --> docker + BackEnd --> pnpm + Shell --> BackEnd + Shell --> docker + Shell --> make + BountyExamples --> make + BountyExamples --> tar + BountyExamples --> xz + Tests ---> docker + Tests ---> make + Tests --> BountyExamples + PopulateScript ---> bash + PopulateScript ---> cast + PopulateScript ---> jq + PopulateScript ---> pnpm + PopulateScript --> BountyExamples + PopulateScript --> CLI + CLI --> cast + CLI --> go + FrontEnd ---> pnpm +``` diff --git a/docs/frontend.md b/docs/frontend.md new file mode 100644 index 0000000..26ea76f --- /dev/null +++ b/docs/frontend.md @@ -0,0 +1,11 @@ +## Front-end + +To run the frontend, execute the commands below. + +```sh +cd frontend +pnpm i +pnpm dev +``` + +Open http://localhost:3000 in your browser. diff --git a/docs/future.md b/docs/future.md new file mode 100644 index 0000000..8945c40 --- /dev/null +++ b/docs/future.md @@ -0,0 +1,13 @@ +## Future Work + +The initial version of this project was developed in one week for the ETHOnline 2023 hackathon. +During this one week, we had to design and implement a project from scratch. +With this very tight schedule, some of the features were left out for later implementation. +Below are some of those features. + +- Support ENS +- Support other types of assets (Ether, ERC-721, and ERC-1155) +- Support syntax highlight on code blocks +- Add optional one-time setup phase for applications +- Add option to download bounty bundle +- Sandbox applications with Hypervisor diff --git a/docs/populate.md b/docs/populate.md new file mode 100644 index 0000000..4a94100 --- /dev/null +++ b/docs/populate.md @@ -0,0 +1,7 @@ +## Populating DApp + +Run the following command to fill up the DApp with test data. + +```sh +make populate +``` diff --git a/docs/tests.md b/docs/tests.md new file mode 100644 index 0000000..d9eafb8 --- /dev/null +++ b/docs/tests.md @@ -0,0 +1,8 @@ +## Tests + +Make sure you first built the machine image. +Then, you may run the tests. + +```sh +make test +```