From df6f81553f95d890bb97e0bd3fafc30cbad78c6e Mon Sep 17 00:00:00 2001
From: Leigh McCulloch <351529+leighmcculloch@users.noreply.github.com>
Date: Fri, 1 Nov 2024 06:35:26 +1000
Subject: [PATCH] wip

---
 Cargo.lock                        | 311 +++++++++++++++++++++++++-----
 soroban-sdk/Cargo.toml            |   3 +-
 soroban-sdk/src/_migrating/v21.rs |  50 ++++-
 3 files changed, 311 insertions(+), 53 deletions(-)

diff --git a/Cargo.lock b/Cargo.lock
index ff8ae13a..dddadb89 100644
--- a/Cargo.lock
+++ b/Cargo.lock
@@ -62,7 +62,7 @@ dependencies = [
  "ark-std",
  "derivative",
  "hashbrown 0.13.2",
- "itertools",
+ "itertools 0.10.5",
  "num-traits",
  "zeroize",
 ]
@@ -79,7 +79,7 @@ dependencies = [
  "ark-std",
  "derivative",
  "digest",
- "itertools",
+ "itertools 0.10.5",
  "num-bigint",
  "num-traits",
  "paste",
@@ -168,6 +168,12 @@ version = "0.2.0"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "4c7f02d4ea65f2c1853089ffd8d2787bdbc63de2f0d29dedbcf8ccdfa0ccd4cf"
 
+[[package]]
+name = "base32"
+version = "0.4.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "23ce669cd6c8588f79e15cf450314f9638f967fc5770ff1c7c1deb0925ea7cfa"
+
 [[package]]
 name = "base64"
 version = "0.13.1"
@@ -730,6 +736,15 @@ dependencies = [
  "either",
 ]
 
+[[package]]
+name = "itertools"
+version = "0.11.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "b1c173a5686ce8bfa551b3563d0c2170bf24ca44da99c7ca4bfdab5418c3fe57"
+dependencies = [
+ "either",
+]
+
 [[package]]
 name = "itoa"
 version = "1.0.11"
@@ -1199,18 +1214,48 @@ version = "1.13.2"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "3c5e1a9a646d36c3599cd173a41282daf47c44583ad367b8e6837255952e5c67"
 
+[[package]]
+name = "soroban-builtin-sdk-macros"
+version = "21.2.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "2f57a68ef8777e28e274de0f3a88ad9a5a41d9a2eb461b4dd800b086f0e83b80"
+dependencies = [
+ "itertools 0.11.0",
+ "proc-macro2",
+ "quote",
+ "syn 2.0.77",
+]
+
 [[package]]
 name = "soroban-builtin-sdk-macros"
 version = "22.0.0-rc.3"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "c45d2492cd44f05cc79eeb857985f153f12a4423ce51b4b746b5925024c473b1"
 dependencies = [
- "itertools",
+ "itertools 0.10.5",
  "proc-macro2",
  "quote",
  "syn 2.0.77",
 ]
 
+[[package]]
+name = "soroban-env-common"
+version = "21.2.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "2fd1c89463835fe6da996318156d39f424b4f167c725ec692e5a7a2d4e694b3d"
+dependencies = [
+ "crate-git-revision",
+ "ethnum",
+ "num-derive",
+ "num-traits",
+ "serde",
+ "soroban-env-macros 21.2.1",
+ "soroban-wasmi",
+ "static_assertions",
+ "stellar-xdr 21.2.0",
+ "wasmparser",
+]
+
 [[package]]
 name = "soroban-env-common"
 version = "22.0.0-rc.3"
@@ -1223,21 +1268,63 @@ dependencies = [
  "num-derive",
  "num-traits",
  "serde",
- "soroban-env-macros",
+ "soroban-env-macros 22.0.0-rc.3",
  "soroban-wasmi",
  "static_assertions",
- "stellar-xdr",
+ "stellar-xdr 22.0.0-rc.1.1",
  "wasmparser",
 ]
 
+[[package]]
+name = "soroban-env-guest"
+version = "21.2.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "6bfb2536811045d5cd0c656a324cbe9ce4467eb734c7946b74410d90dea5d0ce"
+dependencies = [
+ "soroban-env-common 21.2.1",
+ "static_assertions",
+]
+
 [[package]]
 name = "soroban-env-guest"
 version = "22.0.0-rc.3"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "4002fc582cd20cc9b9fbb73959bc5d6b5b15feda11485cbfab0c28e78ecbab3e"
 dependencies = [
- "soroban-env-common",
+ "soroban-env-common 22.0.0-rc.3",
+ "static_assertions",
+]
+
+[[package]]
+name = "soroban-env-host"
+version = "21.2.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "2b7a32c28f281c423189f1298960194f0e0fc4eeb72378028171e556d8cd6160"
+dependencies = [
+ "curve25519-dalek",
+ "ecdsa",
+ "ed25519-dalek",
+ "elliptic-curve",
+ "generic-array",
+ "getrandom",
+ "hex-literal",
+ "hmac",
+ "k256",
+ "num-derive",
+ "num-integer",
+ "num-traits",
+ "p256",
+ "rand",
+ "rand_chacha",
+ "sec1",
+ "sha2",
+ "sha3",
+ "soroban-builtin-sdk-macros 21.2.1",
+ "soroban-env-common 21.2.1",
+ "soroban-wasmi",
  "static_assertions",
+ "stellar-strkey 0.0.8",
+ "wasmparser",
 ]
 
 [[package]]
@@ -1268,29 +1355,58 @@ dependencies = [
  "sec1",
  "sha2",
  "sha3",
- "soroban-builtin-sdk-macros",
- "soroban-env-common",
+ "soroban-builtin-sdk-macros 22.0.0-rc.3",
+ "soroban-env-common 22.0.0-rc.3",
  "soroban-wasmi",
  "static_assertions",
- "stellar-strkey",
+ "stellar-strkey 0.0.9",
  "wasmparser",
 ]
 
+[[package]]
+name = "soroban-env-macros"
+version = "21.2.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "242926fe5e0d922f12d3796cd7cd02dd824e5ef1caa088f45fce20b618309f64"
+dependencies = [
+ "itertools 0.11.0",
+ "proc-macro2",
+ "quote",
+ "serde",
+ "serde_json",
+ "stellar-xdr 21.2.0",
+ "syn 2.0.77",
+]
+
 [[package]]
 name = "soroban-env-macros"
 version = "22.0.0-rc.3"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "a328297a568ae98999fdb06902e3362dfd8a2bfa9abea40beaeb7dc93a402fe7"
 dependencies = [
- "itertools",
+ "itertools 0.10.5",
  "proc-macro2",
  "quote",
  "serde",
  "serde_json",
- "stellar-xdr",
+ "stellar-xdr 22.0.0-rc.1.1",
  "syn 2.0.77",
 ]
 
+[[package]]
+name = "soroban-ledger-snapshot"
+version = "21.7.6"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "43793d5deb5fc27c3e14e036e24cb3afcf7d1e2a172d9166e37f3d174b928749"
+dependencies = [
+ "serde",
+ "serde_json",
+ "serde_with",
+ "soroban-env-common 21.2.1",
+ "soroban-env-host 21.2.1",
+ "thiserror",
+]
+
 [[package]]
 name = "soroban-ledger-snapshot"
 version = "22.0.0-rc.3"
@@ -1299,11 +1415,29 @@ dependencies = [
  "serde",
  "serde_json",
  "serde_with",
- "soroban-env-common",
- "soroban-env-host",
+ "soroban-env-common 22.0.0-rc.3",
+ "soroban-env-host 22.0.0-rc.3",
  "thiserror",
 ]
 
+[[package]]
+name = "soroban-sdk"
+version = "21.7.6"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "25c539fecb2862ce0c1f49880134660a855e2d35889692e01d1e8d8a1e53f98e"
+dependencies = [
+ "bytes-lit",
+ "rand",
+ "rustc_version",
+ "serde",
+ "serde_json",
+ "soroban-env-guest 21.2.1",
+ "soroban-env-host 21.2.1",
+ "soroban-ledger-snapshot 21.7.6",
+ "soroban-sdk-macros 21.7.6",
+ "stellar-strkey 0.0.8",
+]
+
 [[package]]
 name = "soroban-sdk"
 version = "22.0.0-rc.3"
@@ -1320,13 +1454,34 @@ dependencies = [
  "rustc_version",
  "serde",
  "serde_json",
- "soroban-env-guest",
- "soroban-env-host",
- "soroban-ledger-snapshot",
- "soroban-sdk-macros",
- "soroban-spec",
- "stellar-strkey",
- "stellar-xdr",
+ "soroban-env-guest 22.0.0-rc.3",
+ "soroban-env-host 22.0.0-rc.3",
+ "soroban-ledger-snapshot 22.0.0-rc.3",
+ "soroban-sdk 21.7.6",
+ "soroban-sdk-macros 22.0.0-rc.3",
+ "soroban-spec 22.0.0-rc.3",
+ "stellar-strkey 0.0.9",
+ "stellar-xdr 22.0.0-rc.1.1",
+]
+
+[[package]]
+name = "soroban-sdk-macros"
+version = "21.7.6"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "a9ad528a770ec7adb524635d855b424ae2fd4fef04fb702bb0ab466a4c354d78"
+dependencies = [
+ "crate-git-revision",
+ "darling",
+ "itertools 0.11.0",
+ "proc-macro2",
+ "quote",
+ "rustc_version",
+ "sha2",
+ "soroban-env-common 21.2.1",
+ "soroban-spec 21.7.6",
+ "soroban-spec-rust 21.7.6",
+ "stellar-xdr 21.2.0",
+ "syn 2.0.77",
 ]
 
 [[package]]
@@ -1335,29 +1490,57 @@ version = "22.0.0-rc.3"
 dependencies = [
  "crate-git-revision",
  "darling",
- "itertools",
+ "itertools 0.10.5",
  "proc-macro2",
  "quote",
  "rustc_version",
  "sha2",
- "soroban-env-common",
- "soroban-spec",
- "soroban-spec-rust",
- "stellar-xdr",
+ "soroban-env-common 22.0.0-rc.3",
+ "soroban-spec 22.0.0-rc.3",
+ "soroban-spec-rust 22.0.0-rc.3",
+ "stellar-xdr 22.0.0-rc.1.1",
  "syn 2.0.77",
 ]
 
+[[package]]
+name = "soroban-spec"
+version = "21.7.6"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "5b262c82d840552f71ee9254f2e928622fd803bd4df4815e65f73f73efc2fa9c"
+dependencies = [
+ "base64 0.13.1",
+ "stellar-xdr 21.2.0",
+ "thiserror",
+ "wasmparser",
+]
+
 [[package]]
 name = "soroban-spec"
 version = "22.0.0-rc.3"
 dependencies = [
  "base64 0.13.1",
  "pretty_assertions",
- "stellar-xdr",
+ "stellar-xdr 22.0.0-rc.1.1",
  "thiserror",
  "wasmparser",
 ]
 
+[[package]]
+name = "soroban-spec-rust"
+version = "21.7.6"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "85a061820c2dd0bd3ece9411e0dd3aeb6ed9ca2b7d64270eda9e798c3b6dec5f"
+dependencies = [
+ "prettyplease",
+ "proc-macro2",
+ "quote",
+ "sha2",
+ "soroban-spec 21.7.6",
+ "stellar-xdr 21.2.0",
+ "syn 2.0.77",
+ "thiserror",
+]
+
 [[package]]
 name = "soroban-spec-rust"
 version = "22.0.0-rc.3"
@@ -1367,8 +1550,8 @@ dependencies = [
  "proc-macro2",
  "quote",
  "sha2",
- "soroban-spec",
- "stellar-xdr",
+ "soroban-spec 22.0.0-rc.3",
+ "stellar-xdr 22.0.0-rc.1.1",
  "syn 2.0.77",
  "thiserror",
 ]
@@ -1377,7 +1560,7 @@ dependencies = [
 name = "soroban-token-sdk"
 version = "22.0.0-rc.3"
 dependencies = [
- "soroban-sdk",
+ "soroban-sdk 22.0.0-rc.3",
 ]
 
 [[package]]
@@ -1415,6 +1598,17 @@ version = "1.1.0"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "a2eb9349b6444b326872e140eb1cf5e7c522154d69e7a0ffb0fb81c06b37543f"
 
+[[package]]
+name = "stellar-strkey"
+version = "0.0.8"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "12d2bf45e114117ea91d820a846fd1afbe3ba7d717988fee094ce8227a3bf8bd"
+dependencies = [
+ "base32",
+ "crate-git-revision",
+ "thiserror",
+]
+
 [[package]]
 name = "stellar-strkey"
 version = "0.0.9"
@@ -1426,6 +1620,21 @@ dependencies = [
  "thiserror",
 ]
 
+[[package]]
+name = "stellar-xdr"
+version = "21.2.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "2675a71212ed39a806e415b0dbf4702879ff288ec7f5ee996dda42a135512b50"
+dependencies = [
+ "base64 0.13.1",
+ "crate-git-revision",
+ "escape-bytes",
+ "hex",
+ "serde",
+ "serde_with",
+ "stellar-strkey 0.0.8",
+]
+
 [[package]]
 name = "stellar-xdr"
 version = "22.0.0-rc.1.1"
@@ -1439,7 +1648,7 @@ dependencies = [
  "hex",
  "serde",
  "serde_with",
- "stellar-strkey",
+ "stellar-strkey 0.0.9",
 ]
 
 [[package]]
@@ -1493,140 +1702,140 @@ dependencies = [
 name = "test_account"
 version = "22.0.0-rc.3"
 dependencies = [
- "soroban-sdk",
+ "soroban-sdk 22.0.0-rc.3",
 ]
 
 [[package]]
 name = "test_add_i128"
 version = "22.0.0-rc.3"
 dependencies = [
- "soroban-sdk",
+ "soroban-sdk 22.0.0-rc.3",
 ]
 
 [[package]]
 name = "test_add_u128"
 version = "22.0.0-rc.3"
 dependencies = [
- "soroban-sdk",
+ "soroban-sdk 22.0.0-rc.3",
 ]
 
 [[package]]
 name = "test_add_u64"
 version = "22.0.0-rc.3"
 dependencies = [
- "soroban-sdk",
+ "soroban-sdk 22.0.0-rc.3",
 ]
 
 [[package]]
 name = "test_alloc"
 version = "22.0.0-rc.3"
 dependencies = [
- "soroban-sdk",
+ "soroban-sdk 22.0.0-rc.3",
 ]
 
 [[package]]
 name = "test_auth"
 version = "22.0.0-rc.3"
 dependencies = [
- "soroban-sdk",
+ "soroban-sdk 22.0.0-rc.3",
 ]
 
 [[package]]
 name = "test_constructor"
 version = "22.0.0-rc.3"
 dependencies = [
- "soroban-sdk",
+ "soroban-sdk 22.0.0-rc.3",
 ]
 
 [[package]]
 name = "test_contract_data"
 version = "22.0.0-rc.3"
 dependencies = [
- "soroban-sdk",
+ "soroban-sdk 22.0.0-rc.3",
 ]
 
 [[package]]
 name = "test_empty"
 version = "22.0.0-rc.3"
 dependencies = [
- "soroban-sdk",
+ "soroban-sdk 22.0.0-rc.3",
 ]
 
 [[package]]
 name = "test_empty2"
 version = "22.0.0-rc.3"
 dependencies = [
- "soroban-sdk",
+ "soroban-sdk 22.0.0-rc.3",
 ]
 
 [[package]]
 name = "test_errors"
 version = "22.0.0-rc.3"
 dependencies = [
- "soroban-sdk",
+ "soroban-sdk 22.0.0-rc.3",
 ]
 
 [[package]]
 name = "test_events"
 version = "22.0.0-rc.3"
 dependencies = [
- "soroban-sdk",
+ "soroban-sdk 22.0.0-rc.3",
 ]
 
 [[package]]
 name = "test_fuzz"
 version = "22.0.0-rc.3"
 dependencies = [
- "soroban-sdk",
+ "soroban-sdk 22.0.0-rc.3",
 ]
 
 [[package]]
 name = "test_import_contract"
 version = "22.0.0-rc.3"
 dependencies = [
- "soroban-sdk",
+ "soroban-sdk 22.0.0-rc.3",
 ]
 
 [[package]]
 name = "test_invoke_contract"
 version = "22.0.0-rc.3"
 dependencies = [
- "soroban-sdk",
+ "soroban-sdk 22.0.0-rc.3",
 ]
 
 [[package]]
 name = "test_logging"
 version = "22.0.0-rc.3"
 dependencies = [
- "soroban-sdk",
+ "soroban-sdk 22.0.0-rc.3",
 ]
 
 [[package]]
 name = "test_modular"
 version = "22.0.0-rc.3"
 dependencies = [
- "soroban-sdk",
+ "soroban-sdk 22.0.0-rc.3",
 ]
 
 [[package]]
 name = "test_multiimpl"
 version = "22.0.0-rc.3"
 dependencies = [
- "soroban-sdk",
+ "soroban-sdk 22.0.0-rc.3",
 ]
 
 [[package]]
 name = "test_udt"
 version = "22.0.0-rc.3"
 dependencies = [
- "soroban-sdk",
+ "soroban-sdk 22.0.0-rc.3",
 ]
 
 [[package]]
 name = "test_workspace_contract"
 version = "22.0.0-rc.3"
 dependencies = [
- "soroban-sdk",
+ "soroban-sdk 22.0.0-rc.3",
  "test_workspace_lib",
 ]
 
@@ -1634,7 +1843,7 @@ dependencies = [
 name = "test_workspace_lib"
 version = "22.0.0-rc.3"
 dependencies = [
- "soroban-sdk",
+ "soroban-sdk 22.0.0-rc.3",
 ]
 
 [[package]]
diff --git a/soroban-sdk/Cargo.toml b/soroban-sdk/Cargo.toml
index 5d7472bc..ef0463ce 100644
--- a/soroban-sdk/Cargo.toml
+++ b/soroban-sdk/Cargo.toml
@@ -19,6 +19,7 @@ doctest = false
 rustc_version = "0.4.1"
 
 [dependencies]
+soroban-sdk-21 = { package = "soroban-sdk", version = "=21.1.1", optional = true }
 soroban-sdk-macros = { workspace = true }
 bytes-lit = "0.0.5"
 
@@ -55,7 +56,7 @@ proptest-arbitrary-interop = "0.1.0"
 alloc = []
 testutils = ["soroban-sdk-macros/testutils", "soroban-env-host/testutils", "dep:ed25519-dalek", "dep:arbitrary", "dep:ctor"]
 hazmat = []
-docs = []
+docs = ["dep:soroban-sdk-21"]
 
 [package.metadata.docs.rs]
 all-features = true
diff --git a/soroban-sdk/src/_migrating/v21.rs b/soroban-sdk/src/_migrating/v21.rs
index b4338616..338f4135 100644
--- a/soroban-sdk/src/_migrating/v21.rs
+++ b/soroban-sdk/src/_migrating/v21.rs
@@ -1,3 +1,51 @@
 //! # Migrating from v20 to v21
 //!
-//! - `CustomAccountInterface`'s `__check_auth` function `signature_payload` parameter changes from type `BytesN<32>` to `Hash<32>`.
+//! ## `CustomAccountInterface`'s `__check_auth` function `signature_payload` parameter changes from type `BytesN<32>` to `Hash<32>`.
+//!
+//! ### Before
+//!
+//! ```
+//! # use soroban_sdk_21 as soroban_sdk;
+//! use soroban_sdk::auth::CustomAccountInterface;
+//!
+//! #[contract]
+//! pub struct Contract;
+//!
+//! impl CustomAccountInterface for Contract {
+//!     type Signature = ();
+//!     type Error: Into<Error> = u32;
+//!
+//!     fn __check_auth(
+//!         env: Env,
+//!         signature_payload: BytesN<32>,
+//!         signatures: Self::Signature,
+//!         auth_contexts: Vec<Context>,
+//!     ) -> Result<(), Self::Error> {
+//!         // ...
+//!     }
+//! }
+//! ```
+//!
+//! ### After
+//!
+//! ```
+//! use soroban_sdk::auth::CustomAccountInterface;
+//!
+//! #[contract]
+//! pub struct Contract;
+//!
+//! impl CustomAccountInterface for Contract {
+//!     type Signature = ();
+//!     type Error: Into<Error> = u32;
+//!
+//!     fn __check_auth(
+//!         env: Env,
+//!         signature_payload: Hash<32>,
+//!         signatures: Self::Signature,
+//!         auth_contexts: Vec<Context>,
+//!     ) -> Result<(), Self::Error> {
+//!         // ...
+//!     }
+//! }
+//! ```
+//!