docs: add Bonsai Eth examples (risc0#1127)

Adding examples of how Bonsai and the zkVM can be used w/ Ethereum. I broke convention with the hierarchy of the zkVM examples doc and used H3's for each example instead of a bulleted list because these examples require additional context and more thorough descriptions. All of the links in this additional context made the page difficult to read without making this change. --------- Co-authored-by: Brett Carter <[email protected]> Co-authored-by: Frank Laub <[email protected]>
0xZRA · Nov 13, 2023 · 9aa0531 · 9aa0531
1 parent d71a742
commit 9aa0531
Show file tree

Hide file tree

Showing 8 changed files with 194 additions and 0 deletions.
diff --git a/website/api/bonsai/eth-examples.md b/website/api/bonsai/eth-examples.md
@@ -0,0 +1,27 @@
+# Ethereum Examples
+
+While all of the [zkVM examples][zkvm-examples] can be run on Bonsai by [configuring Bonsai][remote-proving] as your remote prover, those examples do not interact with or are intended to interact with Ethereum or any other blockchain. The references below are examples of how Bonsai and the zkVM can be integrated with Ethereum.
+
+### Zeth
+
+[Zeth][zeth-repo] produces ZK validity proofs for Ethereum Virtual Machine blocks (EVM). This is accomplished by running [revm], a Rust implementation of the EVM in the zkVM. The end result is an open-source zkEVM with high code reuse and minute, not hour, proving times on Bonsai. For more info check out [Announcing Zeth: The first Type Zero zkEVM][zeth-article].
+
+### DAO Governance Example
+
+This [example app][governance-example] uses Bonsai as an Ethereum coprocessor. The protocol, based on the OpenZeppelin [Governor smart contract standard], batches signature verifications off-chain for a DAO governance vote. The end result is that in [~160 lines of Rust][signature-aggregation], a gas savings of 66% is achieved with significant room for optimizations.
+
+### BonsaiStarter.sol
+
+This [test contract][bonsai-starter.sol] in the [Bonsai Foundry Template][foundry-template] provides an example of two different ways Bonsai can be integrated with Ethereum smart contracts using the [Bonsai Ethereum Relay][eth-relay].
+
+[zkvm-examples]: /api/zkvm/examples
+[remote-proving]: /api/zkvm/quickstart#remote-proving
+[zeth-repo]: https://github.com/risc0/zeth
+[revm]: https://crates.io/crates/revm
+[zeth-article]: https://www.risczero.com/news/zeth-release
+[governance-example]: https://github.com/risc0/risc0/tree/main/bonsai/examples/governance
+[Governor smart contract standard]: https://docs.openzeppelin.com/contracts/4.x/api/governance
+[signature-aggregation]: https://github.com/risc0/risc0/blob/main/bonsai/examples/governance/methods/guest/src/bin/finalize_votes.rs
+[bonsai-starter.sol]: https://github.com/risc0/bonsai-foundry-template/blob/main/contracts/BonsaiStarter.sol
+[foundry-template]: https://github.com/risc0/bonsai-foundry-template
+[eth-relay]: https://github.com/risc0/risc0/tree/main/bonsai/ethereum-relay
diff --git a/website/api/bonsai/rest-api.md b/website/api/bonsai/rest-api.md
@@ -0,0 +1,33 @@
+# REST API
+
+In its current form, Bonsai is available as REST API which parallelizes proving for individual proofs across a number of GPU workers to maximize performance.
+
+To request an API key, complete the application form at [bonsai.xyz/apply](https://bonsai.xyz/apply).
+
+## Key Features
+
+### STARK To SNARK
+
+While STARK proofs, like the ones that are generated by the zkVM, offer a number of advantages over SNARKs, they're notoriosly big and computationally intensive to verify on-chain. Bonsai offers the best of both worlds by wrapping zkVM STARKs in circom Groth16 SNARKs for easy and gas-efficient on-chain verification. Check out how do this with the [Bonsai Rust SDK](https://github.com/risc0/risc0/tree/main/bonsai/sdk#stark-to-snark) or directly [via the API](https://api.bonsai.xyz/swagger-ui/#/snark/route_snark_create).
+
+## API Limits
+
+Bonsai enforces a number of API limits. These limits are configurable on a per API key basis. If your limits are too low to support your use case or you run out cycles, email us at [email protected] to request more.
+
+These limits are:
+
+- **Concurrent proofs**: The max number of proofs you can generate simultaneously.
+- **Cycle budget**: The max number of [cycles] you can prove on Bonsai.
+- **Cycle usage**: The historical count of cycles used by your API key.
+- **Executor cycle limit**: The max number of cycles your API key can prove for an individual proof.
+- **Max parallelism**: The maximum number of workers an individual proof can be parallelized across (this limit is currently inactive).
+
+### Checking your limits
+
+You can request your individual limits using the [user/quotas](https://api.bonsai.xyz/swagger-ui/#/user/route_user_quota) API route.
+
+### Understanding cycle counts
+
+You can log the cycle count and other performance info for your zkVM Guest program by following the instructions [here](/api/zkvm/quickstart#executor-statistics).
+
+[cycles]: /terminology#clock-cycles
diff --git a/website/api_versioned_docs/version-0.18/bonsai/eth-examples.md b/website/api_versioned_docs/version-0.18/bonsai/eth-examples.md
@@ -0,0 +1,27 @@
+# Ethereum Examples
+
+While all of the [zkVM examples][zkvm-examples] can be run on Bonsai by [configuring Bonsai][remote-proving] as your remote prover, those examples do not interact with or are intended to interact with Ethereum or any other blockchain. The references below are examples of how Bonsai and the zkVM can be integrated with Ethereum.
+
+### Zeth
+
+[Zeth][zeth-repo] produces ZK validity proofs for Ethereum Virtual Machine blocks (EVM). This is accomplished by running [revm], a Rust implementation of the EVM in the zkVM. The end result is an open-source zkEVM with high code reuse and minute, not hour, proving times on Bonsai. For more info check out [Announcing Zeth: The first Type Zero zkEVM][zeth-article].
+
+### DAO Governance Example
+
+This [example app][governance-example] uses Bonsai as an Ethereum coprocessor. The protocol, based on the OpenZeppelin [Governor smart contract standard], batches signature verifications off-chain for a DAO governance vote. The end result is that in [~160 lines of Rust][signature-aggregation], a gas savings of 66% is achieved with significant room for optimizations.
+
+### BonsaiStarter.sol
+
+This [test contract][bonsai-starter.sol] in the [Bonsai Foundry Template][foundry-template] provides an example of two different ways Bonsai can be integrated with Ethereum smart contracts using the [Bonsai Ethereum Relay][eth-relay].
+
+[zkvm-examples]: /api/zkvm/examples
+[remote-proving]: /api/zkvm/quickstart#remote-proving
+[zeth-repo]: https://github.com/risc0/zeth
+[revm]: https://crates.io/crates/revm
+[zeth-article]: https://www.risczero.com/news/zeth-release
+[governance-example]: https://github.com/risc0/risc0/tree/release-0.18/bonsai/examples/governance
+[Governor smart contract standard]: https://docs.openzeppelin.com/contracts/4.x/api/governance
+[signature-aggregation]: https://github.com/risc0/risc0/blob/release-0.18/bonsai/examples/governance/methods/guest/src/bin/finalize_votes.rs
+[bonsai-starter.sol]: https://github.com/risc0/bonsai-foundry-template/blob/release-0.18/contracts/BonsaiStarter.sol
+[foundry-template]: https://github.com/risc0/bonsai-foundry-template
+[eth-relay]: https://github.com/risc0/risc0/tree/release-0.18/bonsai/ethereum-relay
diff --git a/website/api_versioned_docs/version-0.19/bonsai/eth-examples.md b/website/api_versioned_docs/version-0.19/bonsai/eth-examples.md
@@ -0,0 +1,27 @@
+# Ethereum Examples
+
+While all of the [zkVM examples][zkvm-examples] can be run on Bonsai by [configuring Bonsai][remote-proving] as your remote prover, those examples do not interact with or are intended to interact with Ethereum or any other blockchain. The references below are examples of how Bonsai and the zkVM can be integrated with Ethereum.
+
+### Zeth
+
+[Zeth][zeth-repo] produces ZK validity proofs for Ethereum Virtual Machine blocks (EVM). This is accomplished by running [revm], a Rust implementation of the EVM in the zkVM. The end result is an open-source zkEVM with high code reuse and minute, not hour, proving times on Bonsai. For more info check out [Announcing Zeth: The first Type Zero zkEVM][zeth-article].
+
+### DAO Governance Example
+
+This [example app][governance-example] uses Bonsai as an Ethereum coprocessor. The protocol, based on the OpenZeppelin [Governor smart contract standard], batches signature verifications off-chain for a DAO governance vote. The end result is that in [~160 lines of Rust][signature-aggregation], a gas savings of 66% is achieved with significant room for optimizations.
+
+### BonsaiStarter.sol
+
+This [test contract][bonsai-starter.sol] in the [Bonsai Foundry Template] provides an example of two different ways Bonsai can be integrated with Ethereum smart contracts using the [Bonsai Ethereum Relay][eth-relay].
+
+[zkvm-examples]: /api/zkvm/examples
+[remote-proving]: /api/zkvm/quickstart#remote-proving
+[zeth-repo]: https://github.com/risc0/zeth
+[revm]: https://crates.io/crates/revm
+[zeth-article]: https://www.risczero.com/news/zeth-release
+[governance-example]: https://github.com/risc0/risc0/tree/release-0.19/bonsai/examples/governance
+[Governor smart contract standard]: https://docs.openzeppelin.com/contracts/4.x/api/governance
+[signature-aggregation]: https://github.com/risc0/risc0/blob/release-0.19/bonsai/examples/governance/methods/guest/src/bin/finalize_votes.rs
+[bonsai-starter.sol]: https://github.com/risc0/bonsai-foundry-template/blob/main/contracts/BonsaiStarter.sol
+[foundry-template]: https://github.com/risc0/bonsai-foundry-template
+[eth-relay]: https://github.com/risc0/risc0/tree/release-0.19/bonsai/ethereum-relay
diff --git a/website/api_versioned_docs/version-0.19/bonsai/rest-api.md b/website/api_versioned_docs/version-0.19/bonsai/rest-api.md
@@ -0,0 +1,33 @@
+# REST API
+
+In its current form, Bonsai is available as REST API which parallelizes proving for individual proofs across a number of GPU workers to maximize performance.
+
+To request an API key, complete the application form at [bonsai.xyz/apply](https://bonsai.xyz/apply).
+
+## Key Features
+
+### STARK To SNARK
+
+While STARK proofs, like the ones that are generated by the zkVM, offer a number of advantages over SNARKs, they're notoriosly big and computationally intensive to verify on-chain. Bonsai offers the best of both worlds by wrapping zkVM STARKs in circom Groth16 SNARKs for easy and gas-efficient on-chain verification. Check out how do this with the [Bonsai Rust SDK](https://github.com/risc0/risc0/tree/release-0.19/bonsai/sdk#stark-to-snark) or directly [via the API](https://api.bonsai.xyz/swagger-ui/#/snark/route_snark_create).
+
+## API Limits
+
+Bonsai enforces a number of API limits. These limits are configurable on a per API key basis. If your limits are too low to support your use case or you run out cycles, email us at [email protected] to request more.
+
+These limits are:
+
+- **Concurrent proofs**: The max number of proofs you can generate simultaneously.
+- **Cycle budget**: The max number of [cycles] you can prove on Bonsai.
+- **Cycle usage**: The historical count of cycles used by your API key.
+- **Executor cycle limit**: The max number of cycles your API key can prove for an individual proof.
+- **Max parallelism**: The maximum number of workers an individual proof can be parallelized across (this limit is currently inactive).
+
+### Checking your limits
+
+You can request your individual limits using the [user/quotas](https://api.bonsai.xyz/swagger-ui/#/user/route_user_quota) API route.
+
+### Understanding cycle counts
+
+You can log the cycle count and other performance info for your zkVM Guest program by following the instructions [here](/api/zkvm/quickstart#executor-statistics).
+
+[cycles]: /terminology#clock-cycles
diff --git a/website/api_versioned_sidebars/version-0.18-sidebars.json b/website/api_versioned_sidebars/version-0.18-sidebars.json
@@ -28,6 +28,11 @@
           "type": "doc",
           "label": "A Blockchain Dev's Guide to zkVM Development",
           "id": "bonsai/blockchain-zkvm-guide"
+        },
+        {
+          "type": "doc",
+          "label": "Ethereum Examples",
+          "id": "bonsai/eth-examples"
         }
       ]
     },

diff --git a/website/api_versioned_sidebars/version-0.19-sidebars.json b/website/api_versioned_sidebars/version-0.19-sidebars.json
@@ -24,6 +24,27 @@
           "type": "doc",
           "label": "A Blockchain Dev's Guide to zkVM Development",
           "id": "bonsai/blockchain-zkvm-guide"
+        },
+        {
+          "type": "doc",
+          "label": "Ethereum Examples",
+          "id": "bonsai/eth-examples"
+        },
+        {
+          "type": "category",
+          "label": "REST API",
+          "link": {
+            "type": "doc",
+            "id": "bonsai/rest-api"
+          },
+          "collapsed": false,
+          "items": [
+            {
+              "type": "link",
+              "label": "API Reference Docs",
+              "href": "https://api.bonsai.xyz/swagger-ui/"
+            }
+          ]
         }
       ]
     },

diff --git a/website/sidebarsApi.js b/website/sidebarsApi.js
@@ -28,6 +28,27 @@ export default {
           label: "A Blockchain Dev's Guide to zkVM Development",
           id: "bonsai/blockchain-zkvm-guide",
         },
+        {
+          type: "doc",
+          label: "Ethereum Examples",
+          id: "bonsai/eth-examples",
+        },
+        {
+          type: "category",
+          label: "REST API",
+          link: {
+            type: `doc`,
+            id: "bonsai/rest-api",
+          },
+          collapsed: false,
+          items: [
+            {
+              type: "link",
+              label: "API Reference Docs",
+              href: "https://api.bonsai.xyz/swagger-ui/",
+            },
+          ],
+        },
       ],
     },
     {