Zebra relies on numerous Electric Coin Company (ECC) dependencies, and updating them can be a complex task. This guide will help you navigate the process.
The main dependency that influences that is zcash itself. This is because zebra_script links to specific files from it (zcash_script.cpp and all on which it depends). Due to the architecture of zcash, this requires linking to a lot of seemingly unrelated dependencies like orchard, halo2, etc (which are all Rust crates).
Let's dive into the details of each step required to perform an upgrade:
Determine the version of
zcashdto use. This version will determine which versions of other crates to use. Typically, this should be a tag, but in some cases, it might be a reference to a branch (e.g., nu5-consensus) for testing unreleased developments.
zcash_scriptcrate can be challenging, depending on changes in the latest
zcashdrelease. Follow the instructions in the project's README for guidance.
Upgrade and release
zcash_scriptbefore upgrading other ECC dependencies in Zebra.
- Use the
cargo upgradecommand to upgrade all the ECC dependency versions in Zebra. For example, in this PR, the following command was used:
cargo upgrade --incompatible -p bridgetree -p incrementalmerkletree -p orchard -p zcash_primitives -p zcash_proofs -p zcash_address -p zcash_encoding -p zcash_note_encryption -p zcash_script
Insert all the crate names to be updated to the command.
crate-name@versionto upgrade to a specific version of that crate, instead of just the highest version.
- Ensure that the crate versions in the
Cargo.tomlof the zcashd release,
zcash_script, and the
Cargo.tomlfiles of Zebra crates are all the same. Version consistency is crucial.
- Build zebra and make sure it compiles.
- Test Zebra and make sure all test code compiles and all tests pass:
When upgrading, it's common for things to break, such as deprecated or removed functionality. Address these issues by referring to the broken dependency's changelog, which often provides explanations and workarounds.
If you encounter issues that you can't resolve, consider reaching out to ECC team members who worked on the upgrade, as they may have more context.
- Review Zebra's
deny.tomlfile for potential duplicates that can be removed due to the upgrade. You may also need to add new entries to
- You can identify issues with the dependencies using
cargo deny check banscommand, need to have cargo deny installed.
- Push your changes and let the CI identify any additional problems.
- Push the pull request with all the changes and ensure that the full CI process passes.
- Seek approval for the PR.
- Merge to