stellar/rs-soroban-sdk v28.0.0-rc.1

28.0.0-rc.1

on GitHub

This is a pre-release supporting Protocol 28. Upgrading requires changes to some contracts. See the migration guide for the full detail on each breaking change below.

Note that any changes including breaking changes may be made until the stable release.

Breaking changes

• Build contracts with stellar-cli v25.2.0 or newer. Spec shaking is now always on, so the SDK emits a spec entry for every type and relies on the build system to strip the unreachable ones. Remove the experimental_spec_shaking_v2 feature from the soroban-sdk dependency, and remove any export = ... argument from contracttype, contracterror, and contractevent, which is now a compile error. Native builds and unit tests are unaffected. #1968
• Remove any lib = ... argument from contracttype, contracterror, and contractevent. It is now a compile error, and contractimport! always generates the full type definition instead of aliasing into another crate. #1951 #2000
• A contracttype struct can be read from stored data with extra or missing fields (CAP-86). A field missing from the map reads as None if it is an Option, and errors otherwise, and a map key that is not a field of the struct is ignored and dropped, where both used to trap. An Option field can now be added or removed without migrating everything already stored. Writing is unchanged and still writes every field. #2006
• Events no longer publish fields that are unset (CAP-86). In a contractevent with data_format = "map", a field whose value is void, which a None Option is, is left out of the published map rather than written as void. Anything consuming the events must tolerate the absent key. Keep publishing every field with #[contractevent(sparse = false)]. #2008
• Deploying and upgrading take a ContractExecutable (CAP-85). deploy_contract replaces deploy_v2, and update_current_contract replaces update_current_contract_wasm; the old ones still work but are deprecated. Wrap the Wasm hash in ContractExecutable::Wasm(...) to migrate. #2020
• Test snapshots change for tests that register contracts natively. Every natively registered contract now gets its own contract code entry rather than sharing one empty entry, so snapshot JSON files are regenerated on upgrade. For a test that depended on contracts sharing a code entry, upload the contract once with Env::upload and deploy it repeatedly instead. #2014
• The Approve event field expiration_ledger is renamed live_until_ledger, matching the name SEP-41 uses. Rename it wherever the event is constructed or matched on. #1985
• #[contractimpl(contracttrait)] on an impl block that does not implement a trait is now a compile error. It was accepted and silently did nothing, so remove the argument or implement a trait. #1992
• Some test utilities now panic when called inside a contract function. Call them from the test, outside the contract. #2010

New features

• Protocol 28 support, with soroban-env-* at 28.0.2 and stellar-xdr at 28.0.0. #1986
• Manage contract executable references from a contract (CAP-85) with Env::executable_refs(), and deploy from one by passing ContractExecutable::ExternalRef. #2020
• Upload a natively defined contract in tests with Env::upload and Env::upload_at, making it possible to test a factory, or anything else that deploys from an existing code entry, without building to Wasm. #2007
• Fuzz and property test with account addresses using the new ArbitraryAddressAccount prototype, which generates G... addresses so the account path of a contract gets exercised. ArbitraryAddress still generates contract addresses and is also named ArbitraryAddressContract. #2024
• Use SorobanArbitrary prototypes with proptest, now documented in testutils::proptest. #2011

Full Changelog: v27.0.6...v28.0.0