From 6b6f9f82418aa6de385cad440abe34ff7ee01290 Mon Sep 17 00:00:00 2001 From: Ratan Kaliani Date: Fri, 2 Aug 2024 15:08:34 -0700 Subject: [PATCH] docs: patched crate documentation (#1221) --- book/writing-programs/patched-crates.md | 92 ++++++++++++++++++++----- 1 file changed, 74 insertions(+), 18 deletions(-) diff --git a/book/writing-programs/patched-crates.md b/book/writing-programs/patched-crates.md index 31333eb338..43efc5f7d5 100644 --- a/book/writing-programs/patched-crates.md +++ b/book/writing-programs/patched-crates.md @@ -6,7 +6,6 @@ Under the hood, we use [precompiles](./precompiles.md) to achieve tremendous per **If you know of a library or library version that you think should be patched, please open an issue or a pull request!** ## Supported Libraries - | Crate Name | Repository | Notes | | ------------------- | ------------------------------------------------------------------------------------- | ---------------------- | | sha2 | [sp1-patches/RustCrypto-hashes](https://github.com/sp1-patches/RustCrypto-hashes) | sha256 | @@ -16,6 +15,8 @@ Under the hood, we use [precompiles](./precompiles.md) to achieve tremendous per | ed25519-consensus | [sp1-patches/ed25519-consensus](http://github.com/sp1-patches/ed25519-consensus) | ed25519 verify | | curve25519-dalek-ng | [sp1-patches/curve25519-dalek-ng](https://github.com/sp1-patches/curve25519-dalek-ng) | ed25519 verify | | curve25519-dalek | [sp1-patches/curve25519-dalek](https://github.com/sp1-patches/curve25519-dalek) | ed25519 verify | +| ecdsa-core | [sp1-patches/signatures](http://github.com/sp1-patches/signatures) | secp256k1 verify | +| secp256k1 | [sp1-patches/rust-secp256k1](http://github.com/sp1-patches/rust-secp256k1) | secp256k1 verify | ## Using Patched Crates @@ -30,10 +31,12 @@ sha3-v0-9-8 = { git = "https://github.com/sp1-patches/RustCrypto-hashes", packag sha3-v0-10-6 = { git = "https://github.com/sp1-patches/RustCrypto-hashes", package = "sha3", branch = "patch-sha3-v0.10.6" } sha3-v0-10-8 = { git = "https://github.com/sp1-patches/RustCrypto-hashes", package = "sha3", branch = "patch-sha3-v0.10.8" } crypto-bigint = { git = "https://github.com/sp1-patches/RustCrypto-bigint", branch = "patch-v0.5.5" } -curve25519-dalek = { git = "https://github.com/sp1-patches/curve25519-dalek", branch = "patch-v4.1.1" } +tiny-keccak = { git = "https://github.com/sp1-patches/tiny-keccak", branch = "patch-v2.0.2" } +curve25519-dalek = { git = "https://github.com/sp1-patches/curve25519-dalek", branch = "patch-curve25519-v4.1.3" } curve25519-dalek-ng = { git = "https://github.com/sp1-patches/curve25519-dalek-ng", branch = "patch-v4.1.1" } ed25519-consensus = { git = "https://github.com/sp1-patches/ed25519-consensus", branch = "patch-v2.1.0" } -tiny-keccak = { git = "https://github.com/sp1-patches/tiny-keccak", branch = "patch-v2.0.2" } +ecdsa-core = { git = "https://github.com/sp1-patches/signatures", package = "ecdsa", branch = "patch-ecdsa-v0.16.9" } +secp256k1 = { git = "https://github.com/sp1-patches/rust-secp256k1", branch = "patch-v0.29.0" } ``` If you are patching a crate from Github instead of from crates.io, you need to specify the @@ -46,44 +49,97 @@ sha3 = { git = "https://github.com/sp1-patches/RustCrypto-hashes", package = "sh An example of using patched crates is available in our [Tendermint Example](https://github.com/succinctlabs/sp1/blob/main/examples/tendermint/program/Cargo.toml#L22-L25). +## Ed25519 Acceleration + +To accelerate Ed25519 operations, you'll need to patch crates depending on if you're using `ed25519-consensus` or `ed25519-dalek`. + +Generally, `ed25519-consensus` has better performance than `ed25519-dalek` by a factor of 2. +### Patches + +Apply the following patches based on what crates are in your dependencies. + +- `ed25519-consensus` + ```toml + ed25519-consensus = { git = "https://github.com/sp1-patches/ed25519-consensus", branch = "patch-v2.1.0" } + ``` + + Note: The curve operations for Ed25519 occur mainly inside of `curve25519-dalek-ng`, but the crate also exposes + a `u32_backend` feature flag which accelerates signature recovery by 10% over the default `u64_backend`, which is why + `ed25519-consensus` is patched rather than `ed25519-dalek`. + +- `ed25519-dalek` + ```toml + curve25519-dalek = { git = "https://github.com/sp1-patches/curve25519-dalek", branch = "patch-curve25519-v4.1.3" } + ``` + + Note: The curve operations occur inside of the `curve25519-dalek` crate. + +- `curve25519-dalek` + ```toml + curve25519-dalek = { git = "https://github.com/sp1-patches/curve25519-dalek-ng", branch = "patch-v4.1.3" } + ``` + +## Secp256k1 Acceleration + +To accelerate Secp256k1 operations, you'll need to patch `k256` or `secp256k1` depending on your usage. + +Generally, if a crate you're using (ex. `revm`) has support for using `k256` instead of `secp256k1`, you should use `k256`. + +### Patches + +Apply the following patches based on what crates are in your dependencies. + +- `k256` + ```toml + ecdsa-core = { git = "https://github.com/sp1-patches/signatures", package = "ecdsa", branch = "patch-ecdsa-v0.16.9" } + ``` + + Note: The curve operations for `k256` are inside of the `ecdsa-core` crate. + +- `secp256k1` + ```toml + secp256k1 = { git = "https://github.com/sp1-patches/rust-secp256k1", branch = "patch-v0.29.0" } + ``` + + +## Troubleshooting ### Verifying Patch Usage: Cargo You can check if the patch was applied by using cargo's tree command to print the dependencies of the crate you patched. ```bash -cargo tree -p sha2 cargo tree -p sha2@0.9.8 ``` Next to the package name, it should have a link to the Github repository that you patched with. +Ex. + +``` +sha2 v0.9.8 (https://github.com/sp1-patches/RustCrypto-hashes?branch=patch-sha2-v0.9.8#afdbfb09) +├── ... +``` + ### Verifying Patch Usage: SP1 -To check if a precompile is used by your program, you can observe SP1's log output. Make sure to setup the logger with `sp1_sdk::utils::setup_logger()` and run your program with `RUST_LOG=info`. +To check if a precompile is used by your program, you can view SP1's ExecutionReport, which is returned when executing a program with `execute`. In `ExecutionReport` you can view the `syscall_counts` map to view if a specific syscall was used. -In the example below, note how the `sha256_extend` precompile was reported as being used eight times. +For example, if you wanted to check `sha256` was used, you would look for `SHA_EXTEND` and `SHA_COMPRESS` in `syscall_counts`. -```bash -2024-07-03T04:46:33.753527Z INFO prove_core: execution report (syscall counts): -2024-07-03T04:46:33.753550Z INFO prove_core: 8 sha256_extend -2024-07-03T04:46:33.753550Z INFO prove_core: 8 commit -2024-07-03T04:46:33.753553Z INFO prove_core: 8 commit_deferred_proofs -2024-07-03T04:46:33.753554Z INFO prove_core: 4 write -2024-07-03T04:46:33.753555Z INFO prove_core: 1 halt -``` +An example of this is available in our [Patch Testing Example](../../examples/patch-testing/script/src/main.rs). -### Troubleshooting +### Cargo Version Issues -You may also need to update your `Cargo.lock` file. For example: +If you encounter issues with version commits on your patches, you should try updating the patched crate manually. ```bash -cargo update -p ed25519-consensus +cargo update -p ``` If you encounter issues relating to cargo / git, you can try setting `CARGO_NET_GIT_FETCH_WITH_CLI`: ```bash -CARGO_NET_GIT_FETCH_WITH_CLI=true cargo update -p ed25519-consensus +CARGO_NET_GIT_FETCH_WITH_CLI=true cargo update -p ``` You can permanently set this value in `~/.cargo/config`: