From 73c68f27e2fd0de89bebaae2c786d9a9922760ce Mon Sep 17 00:00:00 2001 From: Thomas Chataigner Date: Wed, 13 Nov 2024 11:35:09 +0100 Subject: [PATCH] docs: audit state of the doc + split/single doc --- aptos/docs/src/components/proof_server.md | 25 ++++++++++++++++ aptos/docs/src/design/security.md | 5 ++++ ethereum/docs/src/components/proof_server.md | 30 +++++++++++++++----- ethereum/docs/src/design/security.md | 24 +++++++++++++++- ethereum/docs/src/run/setup_proof_server.md | 3 +- kadena/docs/src/components/proof_server.md | 15 ++++++---- kadena/docs/src/design/security.md | 7 ++++- 7 files changed, 94 insertions(+), 15 deletions(-) diff --git a/aptos/docs/src/components/proof_server.md b/aptos/docs/src/components/proof_server.md index ed9f7efd..c49ec285 100644 --- a/aptos/docs/src/components/proof_server.md +++ b/aptos/docs/src/components/proof_server.md @@ -42,6 +42,31 @@ be verified cheaply on-chain. The server is a layer added on top of the proving service that makes it available to external users. It is a simple TCP server that is open to incoming connections on a port specified at runtime. + +The prover can be ran with two specific mode, either `single` or `split`. + +`single` means that only one instance of the prover will be handling all the proof generation. +As the resource consumption for proof generation is quite high, it means that +only one types of proof will be generated at any given time. In the context of the +Aptos light client, it means that at the start of an epoch, the client will have to wait +for the proof of the Epoch Change to be finalized before resuming the production +of the inclusion proofs. + +`split` means that two instances of the prover will be running, one for each proof type. +In such a scenario, the latency created by the `single` mode is avoided, but the resource +to be allocated to the prover have to be doubled. The interaction between each proof server +is done through HTTP as a client does with a prover. + +> **Info** +> +> In our [Kubernetes configuration](https://github.com/argumentcomputer/zk-light-clients/tree/dev/docker) +> the proof server is ran using `single` mode and the load balancing is handled by +> K8S itself. + +The HTTP endpoints available for the proof server can be found in the section about [the operation of +the bridge](../run/operate_bridge.md). The messages sent over HTTO are defined +in [`proof-server/src/types/proof_server.rs`](https://github.com/argumentcomputer/zk-light-clients/blob/dev/ethereum/light-client/src/types/network.rs). + The server is divided in two, with one main entrypoint. This allows us to handle the worst-case scenario of having to generate both proofs in parallel, since each server handles one proof at a time. It is possible to generate and verify both STARK core proofs and SNARK proofs. diff --git a/aptos/docs/src/design/security.md b/aptos/docs/src/design/security.md index 6e9f8624..c51dd16a 100644 --- a/aptos/docs/src/design/security.md +++ b/aptos/docs/src/design/security.md @@ -1,5 +1,10 @@ # Security considerations +## Codebase + +Please note that the current code for the programs is not audited and should not be used in production. +The code is provided as a reference implementation and should be used at the users risks. + ## Sphinx The [Sphinx](https://github.com/argumentcomputer/sphinx) prover is a fork of [SP1](https://github.com/succinctlabs/sp1) diff --git a/ethereum/docs/src/components/proof_server.md b/ethereum/docs/src/components/proof_server.md index 6e1e0c55..240a6f8c 100644 --- a/ethereum/docs/src/components/proof_server.md +++ b/ethereum/docs/src/components/proof_server.md @@ -39,12 +39,28 @@ be verified cheaply on-chain. ## Server The server is a layer added on top of the proving service that makes it available to external users. It is a simple -TCP server that is open to incoming connections on a port specified at runtime. +HTTP server that is open to incoming connections on a port specified at runtime. -The server is divided in two, with one main entrypoint. This allows us to handle the worst-case scenario of having to -generate both proofs in parallel, since each server handles one proof at a time. It is possible to generate and verify -both STARK core proofs and SNARK proofs. +The prover can be ran with two specific mode, either `single` or `split`. -The RPC protocol used by the servers is a very simple length-prefixed protocol passing serialized messages back and forth. -The messages are defined in [`proof-server/src/types/proof_server.rs`](https://github.com/argumentcomputer/zk-light-clients/blob/dev/ethereum/light-client/src/types/network.rs). -See also the documentation on the [client](./client.md). \ No newline at end of file +`single` means that only one instance of the prover will be handling all the proof generation. +As the resource consumption for proof generation is quite high, it means that +only one types of proof will be generated at any given time. In the context of the +Ethereum light client, it means that once every 54.6 hours the client will have to wait +for the proof of the Sync Committee change to be finalized before resuming the production +of the inclusion proofs. + +`split` means that two instances of the prover will be running, one for each proof type. +In such a scenario, the latency created by the `single` mode is avoided, but the resource +to be allocated to the prover have to be doubled. The interaction between each proof server +is done through HTTP as a client does with a prover. + +> **Info** +> +> In our [Kubernetes configuration](https://github.com/argumentcomputer/zk-light-clients/tree/dev/docker) +> the proof server is ran using `single` mode and the load balancing is handled by +> K8S itself. + +The HTTP endpoints available for the proof server can be found in the section about [the operation of +the bridge](../run/operate_bridge.md). The messages sent over HTTO are defined +in [`proof-server/src/types/proof_server.rs`](https://github.com/argumentcomputer/zk-light-clients/blob/dev/ethereum/light-client/src/types/network.rs). \ No newline at end of file diff --git a/ethereum/docs/src/design/security.md b/ethereum/docs/src/design/security.md index 8332a992..7dc24ea0 100644 --- a/ethereum/docs/src/design/security.md +++ b/ethereum/docs/src/design/security.md @@ -1 +1,23 @@ -# Security considerations \ No newline at end of file +# Security considerations + +## Codebase + +Please note that the current code for the programs is not audited and should not be used in production. +The code is provided as a reference implementation and should be used at the users risks. + +## Sphinx + +The [Sphinx](https://github.com/argumentcomputer/sphinx) prover is a fork of [SP1](https://github.com/succinctlabs/sp1) +and as such inherits a lot from its security design. The current release of Sphinx (`dev`) has backported all the +upstream security fixes as of SP1 `v1.0.8-testnet`. We will continue to update Sphinx with backports of upstream +security fixes and subsequent updates to both Sphinx and the Light Client, making them available as hotfixes. + +In terms of Sphinx-specific changes that require special attention, here is a non-exhaustive list of Sphinx +AIR chips used for precompiles that are either not present in upstream SP1, or have had non-trivial changes: + +- `Blake2sRoundChip`: Chip for the Blake2s hash function compression, as specified in [RFC 7693](https://datatracker.ietf.org/doc/html/rfc7693). +- `Sha512CompressChip`, `Sha512ExtendChip`: Chips for the SHA-512 hash function compression. + +Notably, the Kadena light client does not use BLS12-381 related precompiles, such as field operations (`FieldAddChip`, `FieldSubChip`, `FieldMulChip`) or G1 decompression (`Bls12381G1DecompressChip`), neither does it use `Secp256k1DecompressChip`, a chip for decompressing K256 compressed points. Therefore, the light client’s proof does not depend on the correctness of these precompiles. + +There are also some SP1 chips and precompiles that are not present in Sphinx, such as `Uint256MulChip`. \ No newline at end of file diff --git a/ethereum/docs/src/run/setup_proof_server.md b/ethereum/docs/src/run/setup_proof_server.md index 094c36cd..89090b31 100644 --- a/ethereum/docs/src/run/setup_proof_server.md +++ b/ethereum/docs/src/run/setup_proof_server.md @@ -7,7 +7,8 @@ > refer to [the dedicated documentation](https://github.com/argumentcomputer/zk-light-clients/tree/dev/docker). For the Proof Server, we have to take into account that generating a proof is a heavy operation. To avoid -overloading the server, we can split the proof generation into two servers. The primary server will handle +overloading the server in this tutorial, we will demonstrate how to use `split` mode for the proof server, +effectively sharing the proof generation workload into two servers. The primary server will handle inclusion proofs, and the secondary server will handle epoch change proofs. For best results, the primary and secondary servers should be deployed to **different server instances**, so that diff --git a/kadena/docs/src/components/proof_server.md b/kadena/docs/src/components/proof_server.md index 0eca8e22..41e5c7f0 100644 --- a/kadena/docs/src/components/proof_server.md +++ b/kadena/docs/src/components/proof_server.md @@ -39,11 +39,16 @@ The server is a layer added on top of the proving service that makes it availabl REST server that is open to incoming connections on a port specified at runtime. The server have two possible mode of operation: -- _Single_: The deployed server will handle all incoming proving and verifying requests. -- _Split_: The deployed server will handle only part of the requests, and will forward the rest to another server. +- `single`: The deployed server will handle all incoming proving and verifying requests. +- `split`: The deployed server will handle only part of the requests, and will forward the rest to another server. It is possible to generate and verify both STARK core proofs and SNARK proofs. -The RPC protocol used by the servers is a very simple bytes protocol passing serialized messages back and forth. -The messages are defined in [`light-client/src/types/network.rs`](https://github.com/argumentcomputer/zk-light-clients/blob/dev/kadena/light-client/src/types/network.rs). -See also the documentation on the [client](./client.md). \ No newline at end of file +> **Note** +> +> As a light client for PoW chains only requires one proof, the SPV one, it is safe to only run +> the server in `single` mode. + +The HTTP protocol used by the servers is a very simple bytes protocol passing serialized messages back and forth. +The available endpoints are documented in the section about [the operation of the bridge](../run/operate_bridge.md). +The messages are defined in [`light-client/src/types/network.rs`](https://github.com/argumentcomputer/zk-light-clients/blob/dev/kadena/light-client/src/types/network.rs). \ No newline at end of file diff --git a/kadena/docs/src/design/security.md b/kadena/docs/src/design/security.md index 41c099ff..c0b3e5b8 100644 --- a/kadena/docs/src/design/security.md +++ b/kadena/docs/src/design/security.md @@ -1,5 +1,10 @@ # Security considerations +## Codebase + +Please note that the current code for the programs is not audited and should not be used in production. +The code is provided as a reference implementation and should be used at the users risks. + ## Sphinx The [Sphinx](https://github.com/argumentcomputer/sphinx) prover is a fork of [SP1](https://github.com/succinctlabs/sp1) @@ -15,4 +20,4 @@ AIR chips used for precompiles that are either not present in upstream SP1, or h Notably, the Kadena light client does not use BLS12-381 related precompiles, such as field operations (`FieldAddChip`, `FieldSubChip`, `FieldMulChip`) or G1 decompression (`Bls12381G1DecompressChip`), neither does it use `Secp256k1DecompressChip`, a chip for decompressing K256 compressed points. Therefore, the light client’s proof does not depend on the correctness of these precompiles. -There are also some SP1 chips and precompiles that are not present in Sphinx, such as `Uint256MulChip`. +There are also some SP1 chips and precompiles that are not present in Sphinx, such as `Uint256MulChip`. \ No newline at end of file