From c9d750743fe378aeb67c95e6942a2d3c59b6e1a1 Mon Sep 17 00:00:00 2001 From: Conrado Gouvea Date: Mon, 10 Jun 2024 12:17:54 -0300 Subject: [PATCH] update documentation for release 0.2.0 (#161) --- CHANGELOG.md | 10 +++++++- Cargo.lock | 2 +- Cargo.toml | 2 +- README.md | 69 ++++++++++++++-------------------------------------- src/lib.rs | 2 +- zcash.patch | 24 ------------------ 6 files changed, 30 insertions(+), 79 deletions(-) delete mode 100644 zcash.patch diff --git a/CHANGELOG.md b/CHANGELOG.md index 3b5022ce8..7a74399e5 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -8,6 +8,13 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0 ## [Unreleased] - ReleaseDate +## [0.2.0] - 2024-06-10 + +- Major API update. Most functions have been removed and a new callback-based + function was introduced. See `depend/zcash/src/script/zcash_script.h` for + documentation. This allows removing all dependencies from this crate, greatly + simplifying its maintenance. + ## [0.1.16] - 2024-04-26 ### Changed @@ -106,7 +113,8 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0 - Updated `bindgen` to a non yanked version -[Unreleased]: https://github.com/ZcashFoundation/zcash_script/compare/v0.1.16...HEAD +[Unreleased]: https://github.com/ZcashFoundation/zcash_script/compare/v0.2.0...HEAD +[0.2.0]: https://github.com/ZcashFoundation/zcash_script/compare/v0.1.16...v0.2.0 [0.1.16]: https://github.com/ZcashFoundation/zcash_script/compare/v0.1.15...v0.1.16 [0.1.15]: https://github.com/ZcashFoundation/zcash_script/compare/v0.1.14...v0.1.15 [0.1.14]: https://github.com/ZcashFoundation/zcash_script/compare/v0.1.13...v0.1.14 diff --git a/Cargo.lock b/Cargo.lock index 645606228..3a94d6378 100644 --- a/Cargo.lock +++ b/Cargo.lock @@ -412,7 +412,7 @@ checksum = "ed94fce61571a4006852b7389a063ab983c02eb1bb37b47f8272ce92d06d9538" [[package]] name = "zcash_script" -version = "0.1.16" +version = "0.2.0" dependencies = [ "bindgen", "cc", diff --git a/Cargo.toml b/Cargo.toml index 621baf9a8..3bf442428 100644 --- a/Cargo.toml +++ b/Cargo.toml @@ -1,6 +1,6 @@ [package] name = "zcash_script" -version = "0.1.16" +version = "0.2.0" authors = ["Tamas Blummer ", "Zcash Foundation "] license = "Apache-2.0" readme = "README.md" diff --git a/README.md b/README.md index 91ad908ad..fe1c188cd 100644 --- a/README.md +++ b/README.md @@ -17,18 +17,12 @@ Rust bindings to the ECC's `zcash_script` C++ library. This crate works by manually including the `zcash_script` .h and .cpp files, using `bindgen` to generate Rust bindings, and compiling everything together -into a single library. Due to the way the `zcash_script` is written we unfortunately need -to include a lot of other stuff e.g. the orchard library. +into a single library. ### Updating this crate 1. Create a new branch batch so all the release commits can be made into a PR 2. Update `depend/zcash` with the latest tagged version of `zcashd`, using the instructions below -3. Update `Cargo.toml` versions to match the versions used by the latest tagged version of `zcashd`, and its dependencies -4. For dependencies that are shared with Zebra (but not `zcashd`), match the latest version in Zebra's [Cargo.lock](https://github.com/ZcashFoundation/zebra/blob/main/Cargo.lock): - - use `cargo tree --invert ` to see if the crate is from `zcash_script` or another dependency - - see the list in [Cargo.toml](https://github.com/ZcashFoundation/zcash_script/blob/master/Cargo.toml#L69) -5. For new dependencies with a leading zero in their version (`0.x.y`), use a `>=` dependency [to make them automatically upgrade to match Zebra's dependencies](https://doc.rust-lang.org/cargo/reference/resolver.html#semver-compatibility) 6. Test if everything works by running `cargo test`. If you get any compiling errors, see the troubleshooting section below. 7. Check all open PRs to see if they can be merged before the release @@ -37,50 +31,23 @@ to include a lot of other stuff e.g. the orchard library. ### Updating `depend/zcash` -We keep a copy of the zcash source in `depend/zcash` with the help of `git subtree`. -It has one single difference that must be enforced every time it's updated: the root -`Cargo.toml` must be deleted, since otherwise cargo will ignore the entire folder -when publishing the crate (see https://github.com/rust-lang/cargo/issues/8597). - -However, `git subtree` requires merge commits in order to make further updates -work correctly. Since we don't allow those in our repository, we start over -every time, basically using it as a glorified `git clone`. This issue is being -tracked in https://github.com/ZcashFoundation/zcash_script/issues/35. - -We also need to patch the zcash source to enable Windows compatibility. This -is done by applying a patch file as described below. If the patch application -fails, check the patch file for reference on what needs to be changed (and -update the patch file). - -If you need to update the zcash source, run: - -```console -git rm -r depend/zcash -(commit changes) -git subtree add -P depend/zcash https://github.com/zcash/zcash.git --squash -git rm depend/zcash/Cargo.toml -git apply zcash.patch -(commit changes) -``` - -where `` is a reference to a branch, tag or commit (it should be a tag when preparing -a release, but it will be likely a branch or commit when testing). - -### Updating `Cargo.toml` - -Note that `zcash_script` (the C++ library/folder inside `zcash`) uses some Rust -FFI functions from `zcash`; and it also links to `librustzcash` which is written in Rust. -Therefore, when updating `zcash_script` (this crate), we need to make sure that shared dependencies -between all of those are the same versions (and are patched to the same revisions, if applicable). -To do that, check for versions in: - -- `zcash/Cargo.toml` in the revision pointed to by this crate (also check for patches) -- `librustzcash/Cargo.toml` in the revision pointed to by `zcash` (also check for patches) -- `librustzcash//Cargo.toml` in the revision pointed to by `zcash` -- `orchard/Cargo.toml` in the revision pointed to by `zcash` (also check for patches) - -To double-check, you can use `cargo tree` or `cargo deny check bans` on Zebra, -once the `zcash_script`, `librustzcash`, and `orchard` versions have all been updated. +We keep a copy of the zcash source in `depend/zcash`, but it has diverged +in 0.2.0 release (based on zcashd 5.9.0) with the following changes: + +- The root `Cargo.toml` was be deleted, since otherwise cargo will ignore the + entire folder when publishing the crate (see + https://github.com/rust-lang/cargo/issues/8597). +- New classes were introduced in interpreter.h/.cpp to support the callback API. +- Some #if guards were added to remove code that is not needed for script + verification. + +The simplified API now mostly require files that are truly required for script +verification. These are unlikely to change so this crate no longers need to keep +the zcashd source in sync, unless there was some bug fix in script verification. + +If updating zcashd source is required, you will need to manually update the +`depend/zcash` source tree and reapply changes that have been made to it. If +you do that, please document the process in detail in this file. ### Publishing New Releases diff --git a/src/lib.rs b/src/lib.rs index cb4e03a64..bcb36f928 100644 --- a/src/lib.rs +++ b/src/lib.rs @@ -1,7 +1,7 @@ //! Rust bindings for Zcash transparent scripts. #![doc(html_logo_url = "https://www.zfnd.org/images/zebra-icon.png")] -#![doc(html_root_url = "https://docs.rs/zcash_script/0.1.16")] +#![doc(html_root_url = "https://docs.rs/zcash_script/0.2.0")] #![allow(missing_docs)] #![allow(clippy::needless_lifetimes)] #![allow(non_upper_case_globals)] diff --git a/zcash.patch b/zcash.patch deleted file mode 100644 index 0c02353ec..000000000 --- a/zcash.patch +++ /dev/null @@ -1,24 +0,0 @@ -diff --git a/depend/zcash/src/zcash/cache.cpp b/depend/zcash/src/zcash/cache.cpp -index c5cd6b173c..1da334b377 100644 ---- a/depend/zcash/src/zcash/cache.cpp -+++ b/depend/zcash/src/zcash/cache.cpp -@@ -3,7 +3,7 @@ - // file COPYING or http://www.opensource.org/licenses/mit-license.php. - - #include "zcash/cache.h" --#include "util/system.h" -+// #include "util/system.h" - - namespace libzcash - { -@@ -11,8 +11,8 @@ std::unique_ptr NewBundleValidityCache(rust::Str kind, size - { - auto cache = std::unique_ptr(new BundleValidityCache()); - size_t nElems = cache->setup_bytes(nMaxCacheSize); -- LogPrintf("Using %zu MiB out of %zu requested for %s bundle cache, able to store %zu elements\n", -- (nElems * sizeof(BundleCacheEntry)) >> 20, nMaxCacheSize >> 20, kind, nElems); -+ // LogPrintf("Using %zu MiB out of %zu requested for %s bundle cache, able to store %zu elements\n", -+ // (nElems * sizeof(BundleCacheEntry)) >> 20, nMaxCacheSize >> 20, kind, nElems); - return cache; - } - } // namespace libzcash