From 8e7e0dd950a142b390d19d7b0208b0d108442b78 Mon Sep 17 00:00:00 2001 From: Leigh McCulloch <351529+leighmcculloch@users.noreply.github.com> Date: Wed, 6 Nov 2024 13:38:49 +1000 Subject: [PATCH] Create migration notes in Rust docs for v22 (#1248) ### What Add migration notes for v22. ### Screenshot ![soroban_sdk___migrating - Rust](https://github.com/user-attachments/assets/e03cd750-4dee-43ca-97e4-7fc9c6ad7f4b) ### Why To make the most of docs.rs to provide more complete and thorough migration notes that have not only textual descriptions, but examples and working code that can be tested. This change adds a GitHub Actions workflow that checks that for any new releases we are preparing, that the migration notes are added. Close #1048 --- .github/workflows/rust.yml | 13 +- Cargo.lock | 23 ++++ soroban-sdk/Cargo.toml | 1 + soroban-sdk/src/_migrating.rs | 236 ++++++++++++++++++++++++++++++++++ soroban-sdk/src/lib.rs | 2 + 5 files changed, 274 insertions(+), 1 deletion(-) create mode 100644 soroban-sdk/src/_migrating.rs diff --git a/.github/workflows/rust.yml b/.github/workflows/rust.yml index ba849d00..e8911300 100644 --- a/.github/workflows/rust.yml +++ b/.github/workflows/rust.yml @@ -18,7 +18,7 @@ jobs: complete: if: always() - needs: [fmt, check-git-rev-deps, semver-checks, build-and-test, docs, readme] + needs: [fmt, check-git-rev-deps, semver-checks, build-and-test, docs, readme, migration-docs] runs-on: ubuntu-latest steps: - if: contains(needs.*.result, 'failure') || contains(needs.*.result, 'cancelled') @@ -165,6 +165,17 @@ jobs: - run: make readme - run: git add -N . && git diff HEAD --exit-code + migration-docs: + runs-on: ubuntu-latest + steps: + - uses: actions/checkout@v3 + - uses: stellar/actions/rust-cache@main + - run: rustup update + - run: | + version="$(cargo metadata --format-version 1 --no-deps | jq -r '.packages[] | select(.name == "soroban-sdk") | .version | split("\\.";"")[0] | "v"+.')" + git grep "${version}" -- soroban-sdk/src/_migrating.rs \ + || (echo "The _migrating ${version} section is missing." && exit 1) + publish-dry-run: if: github.event_name == 'push' || startsWith(github.head_ref, 'release/') strategy: diff --git a/Cargo.lock b/Cargo.lock index abc19d65..65530516 100644 --- a/Cargo.lock +++ b/Cargo.lock @@ -246,6 +246,8 @@ version = "1.1.21" source = "registry+https://github.com/rust-lang/crates.io-index" checksum = "07b1695e2c7e8fc85310cde85aeaab7e3097f593c91d209d3f9df76c928100f0" dependencies = [ + "jobserver", + "libc", "shlex", ] @@ -736,6 +738,15 @@ version = "1.0.11" source = "registry+https://github.com/rust-lang/crates.io-index" checksum = "49f1f14873335454500d59611f1cf4a4b0f786f9ac11f4312a78e4cf2566695b" +[[package]] +name = "jobserver" +version = "0.1.32" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "48d1dbcbbeb6a7fec7e059840aa538bd62aaccf972c7346c4d9d2059312853d0" +dependencies = [ + "libc", +] + [[package]] name = "js-sys" version = "0.3.70" @@ -778,6 +789,17 @@ version = "0.2.158" source = "registry+https://github.com/rust-lang/crates.io-index" checksum = "d8adc4bb1803a324070e64a98ae98f38934d91957a99cfb3a43dcbc01bc56439" +[[package]] +name = "libfuzzer-sys" +version = "0.4.7" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "a96cfd5557eb82f2b83fed4955246c988d331975a002961b07c81584d107e7f7" +dependencies = [ + "arbitrary", + "cc", + "once_cell", +] + [[package]] name = "libm" version = "0.2.8" @@ -1309,6 +1331,7 @@ dependencies = [ "curve25519-dalek", "ed25519-dalek", "hex", + "libfuzzer-sys", "proptest", "proptest-arbitrary-interop", "rand", diff --git a/soroban-sdk/Cargo.toml b/soroban-sdk/Cargo.toml index 5d7472bc..adc49ad8 100644 --- a/soroban-sdk/Cargo.toml +++ b/soroban-sdk/Cargo.toml @@ -50,6 +50,7 @@ hex = "0.4.3" arbitrary = { version = "1.3.0", features = ["derive"] } proptest = "1.2.0" proptest-arbitrary-interop = "0.1.0" +libfuzzer-sys = "0.4.7" [features] alloc = [] diff --git a/soroban-sdk/src/_migrating.rs b/soroban-sdk/src/_migrating.rs new file mode 100644 index 00000000..a7139264 --- /dev/null +++ b/soroban-sdk/src/_migrating.rs @@ -0,0 +1,236 @@ +//! # Migrating from v21 to v22 +//! +//! 1. [`Env::register`] and [`Env::register_at`] replace [`Env::register_contract`] and [`Env::register_contract_wasm`]. +//! +//! [`register`] registers both native contracts previously registered with +//! [`register_contract`] and Wasm contracts previously registered with +//! [`register_contract_wasm`]. It accepts a tuple that is passed to the +//! contracts constructor. Pass `()` if the contract has no constructor. +//! +//! ``` +//! use soroban_sdk::{contract, contractimpl, Env}; +//! +//! #[contract] +//! pub struct Contract; +//! +//! #[contractimpl] +//! impl Contract { +//! // .. +//! } +//! +//! #[test] +//! fn test() { +//! # } +//! # #[cfg(feature = "testutils")] +//! # fn main() { +//! let env = Env::default(); +//! let address = env.register( +//! Contract, // 👈 👀 The contract being registered, or a Wasm `&[u8]`. +//! (), // 👈 👀 The constructor arguments, or (). +//! ); +//! // .. +//! } +//! # #[cfg(not(feature = "testutils"))] +//! # fn main() { } +//! ``` +//! +//! [`register_at`] registers both native contracts previously registered +//! with [`register_contract`] and Wasm contracts previously registered with +//! [`register_contract_wasm`], and allows setting the address that the +//! contract is registered at. It accepts a tuple that is passed to the +//! contracts constructor. Pass `()` if the contract has no constructor. +//! +//! ``` +//! use soroban_sdk::{contract, contractimpl, Env, Address, testutils::Address as _}; +//! +//! #[contract] +//! pub struct Contract; +//! +//! #[contractimpl] +//! impl Contract { +//! // .. +//! } +//! +//! #[test] +//! fn test() { +//! # } +//! # #[cfg(feature = "testutils")] +//! # fn main() { +//! let env = Env::default(); +//! let address = Address::generate(&env); +//! env.register_at( +//! &address, // 👈 👀 The address to register the contract at. +//! Contract, // 👈 👀 The contract being registered, or a Wasm `&[u8]`. +//! (), // 👈 👀 The constructor arguments, or (). +//! ); +//! // .. +//! } +//! # #[cfg(not(feature = "testutils"))] +//! # fn main() { } +//! ``` +//! +//! 2. [`DeployerWithAddress::deploy_v2`] replaces [`DeployerWithAddress::deploy`]. +//! +//! [`deploy_v2`] is the same as [`deploy`], except it accepts a list of +//! arguments to be passed to the contracts constructor that will be called +//! when it is deployed. For deploying existing contracts that do not have +//! constructors, pass `()`. +//! +//! ``` +//! use soroban_sdk::{contract, contractimpl, BytesN, Env}; +//! +//! #[contract] +//! pub struct Contract; +//! +//! #[contractimpl] +//! impl Contract { +//! pub fn exec(env: Env, wasm_hash: BytesN<32>) { +//! let salt = [0u8; 32]; +//! let deployer = env.deployer().with_current_contract(salt); +//! // Pass `()` for contracts that have no contstructor, or have a +//! // constructor and require no arguments. Pass arguments in a +//! // tuple if any required. +//! let contract_address = deployer.deploy_v2(wasm_hash, ()); +//! } +//! } +//! +//! #[test] +//! fn test() { +//! # } +//! # #[cfg(feature = "testutils")] +//! # fn main() { +//! let env = Env::default(); +//! let contract_address = env.register(Contract, ()); +//! let contract = ContractClient::new(&env, &contract_address); +//! // Upload the contract code before deploying its instance. +//! const WASM: &[u8] = include_bytes!("../doctest_fixtures/contract.wasm"); +//! let wasm_hash = env.deployer().upload_contract_wasm(WASM); +//! contract.exec(&wasm_hash); +//! } +//! # #[cfg(not(feature = "testutils"))] +//! # fn main() { } +//! ``` +//! +//! 2. Deprecated [`fuzz_catch_panic`]. Use [`Env::try_invoke_contract`] and the `try_` client functions instead. +//! +//! The `fuzz_catch_panic` function could be used in fuzz tests to catch a contract panic. Improved behavior can be found by invoking a contract with the `try_` variant of the invoke function contract clients. +//! +//! ``` +//! use libfuzzer_sys::fuzz_target; +//! use soroban_sdk::{contract, contracterror, contractimpl, Env, testutils::arbitrary::*}; +//! +//! #[contract] +//! pub struct Contract; +//! +//! #[contracterror] +//! #[derive(Debug, PartialEq)] +//! pub enum Error { +//! Overflow = 1, +//! } +//! +//! #[contractimpl] +//! impl Contract { +//! pub fn add(x: u32, y: u32) -> Result { +//! x.checked_add(y).ok_or(Error::Overflow) +//! } +//! } +//! +//! #[derive(Arbitrary, Debug)] +//! pub struct Input { +//! pub x: u32, +//! pub y: u32, +//! } +//! +//! fuzz_target!(|input: Input| { +//! let env = Env::default(); +//! let id = env.register(Contract, ()); +//! let client = ContractClient::new(&env, &id); +//! +//! let result = client.try_add(&input.x, &input.y); +//! match result { +//! // Returned if the function succeeds, and the value returned is +//! // the type expected. +//! Ok(Ok(_)) => {} +//! // Returned if the function succeeds, and the value returned is +//! // NOT the type expected. +//! Ok(Err(_)) => panic!("unexpected type"), +//! // Returned if the function fails, and the error returned is +//! // recognised as part of the contract errors enum. +//! Err(Ok(_)) => {} +//! // Returned if the function fails, and the error returned is NOT +//! // recognised, or the contract panic'd. +//! Err(Err(_)) => panic!("unexpected error"), +//! } +//! }); +//! +//! # fn main() { } +//! ``` +//! +//! 3. Events in test snapshots are now reduced to only contract events and system events. Diagnostic events will no longer appear in test snapshots. +//! +//! This will cause all test snapshot JSON files generated by the SDK to change when upgrading to this major version of the SDK. The change should be isolated to events and should omit only diagnostic events. +//! +//! [`Env::register`]: crate::Env::register +//! [`register`]: crate::Env::register +//! [`Env::register_at`]: crate::Env::register_at +//! [`register_at`]: crate::Env::register_at +//! [`Env::register_contract`]: crate::Env::register_contract +//! [`register_contract`]: crate::Env::register_contract +//! [`Env::register_contract_wasm`]: crate::Env::register_contract_wasm +//! [`register_contract_wasm`]: crate::Env::register_contract_wasm +//! [`DeployerWithAddress::deploy_v2`]: crate::deploy::DeployerWithAddress::deploy_v2 +//! [`deploy_v2`]: crate::deploy::DeployerWithAddress::deploy_v2 +//! [`DeployerWithAddress::deploy`]: crate::deploy::DeployerWithAddress::deploy +//! [`deploy`]: crate::deploy::DeployerWithAddress::deploy +//! [`fuzz_catch_panic`]: crate::testutils::arbitrary::fuzz_catch_panic +//! [`Env::try_invoke_contract`]: crate::Env::try_invoke_contract +//! +//! # Migrating from v20 to v21 +//! +//! 1. [`CustomAccountInterface::__check_auth`] function `signature_payload` parameter changes from type [`BytesN<32>`] to [`Hash<32>`]. +//! +//! The two types are interchangeable. [`Hash<32>`] contains a [`BytesN<32>`] and can only be constructed in contexts where the value has been generated by a secure cryptographic function. +//! +//! To convert from a [`Hash<32>`] to a [`BytesN<32>`], use [`Hash<32>::to_bytes`] or [`Into::into`]. +//! +//! Current implementations of the interface will see a build error, and should change [`BytesN<32>`] to [`Hash<32>`]. +//! +//! ``` +//! use soroban_sdk::{ +//! auth::{Context, CustomAccountInterface}, contract, +//! contracterror, contractimpl, crypto::Hash, Env, +//! Vec, +//! }; +//! +//! #[contract] +//! pub struct Contract; +//! +//! #[contracterror] +//! pub enum Error { +//! AnError = 1, +//! // ... +//! } +//! +//! #[contractimpl] +//! impl CustomAccountInterface for Contract { +//! type Signature = (); +//! type Error = Error; +//! +//! fn __check_auth( +//! env: Env, +//! signature_payload: Hash<32>, // 👈 👀 +//! signatures: (), +//! auth_contexts: Vec, +//! ) -> Result<(), Self::Error> { +//! // ... +//! # todo!() +//! } +//! } +//! +//! # fn main() { } +//! ``` +//! +//! [`CustomAccountInterface::__check_auth`]: crate::auth::CustomAccountInterface::__check_auth +//! [`BytesN<32>`]: crate::BytesN +//! [`Hash<32>`]: crate::crypto::Hash +//! [`Hash<32>::to_bytes`]: crate::crypto::Hash::to_bytes diff --git a/soroban-sdk/src/lib.rs b/soroban-sdk/src/lib.rs index 0e218dfe..ebfdec9d 100644 --- a/soroban-sdk/src/lib.rs +++ b/soroban-sdk/src/lib.rs @@ -44,6 +44,8 @@ #![cfg_attr(feature = "docs", feature(doc_cfg))] #![allow(dead_code)] +pub mod _migrating; + #[cfg(all(target_family = "wasm", feature = "testutils"))] compile_error!("'testutils' feature is not supported on 'wasm' target");