docs: patched crate documentation (#1221)

succinctlabs · Aug 2, 2024 · 6b6f9f8 · 6b6f9f8
1 parent f0e6311
commit 6b6f9f8
Showing 1 changed file with 74 additions and 18 deletions.
diff --git 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 [email protected]
 ```
 
 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 <patch-crate-name>
 ```
 
 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 <patch-crate-name>
 ```
 
 You can permanently set this value in `~/.cargo/config`: