3.1.0 -> 4.0.0 near-sdk-rs Migration guide

[austinabell]

This document will note the primary breaking changes and additions for this most recent stable release. These sections will be ordered roughly in order of what will be most to least breaking.

This will not cover everything, as most additions/changes/optimizations do not affect migrating from an older version. The changelog can be used if a change is not listed here, or feel free to comment on what was not documented so that it can be added.

Validated AccountId by default

Previously was AccountId, which was an alias to String, and ValidAccountId was a wrapper around this for validation. Now there is just one type. This type will have the same borsh and JSON serialization format, except that it is validated on deserialization.

If you are coming from a String, you have two options:

let s: String = "account.near".to_string();

// Convert to AccountId with validation
let a: AccountId = s.try_into().unwrap();

// Construct without validation
let a = AccountId::new_unchecked(s);

Validation of the string will still happen in debug to avoid bugs in testing, but will not be validated (until used in the runtime) when compiling in release mode.

If you have a &str, you can use:

// Convert with validation
let a: AccountId = "account.near".parse();

// Convert without through String
let a = AccountId::new_unchecked("account.near".to_string());

For more information, see the Rustdocs for AccountId

PublicKey is now its own type no longer an alias of Vec<u8>

Similar to the above changes to AccountId, this change is to avoid requiring using the Base58PublicKey type to deserialize it correctly as JSON. This type will have the same borsh serialization format as both the old PublicKey and Base58PublicKey types. The JSON format of this type will match Base58PublicKey.

For more information on this type, see the docs.

Updated cross-contract call API

NEP264 allows for utilizing unspent gas for future async cross-contract calls. This enables gas to be used more efficiently but also enables a much cleaner API design.

The details of the change are defined in the API proposal issue.

The main things to know about this updated API is that for a trait annotated with #[ext_contract]:

#[ext_contract(cross_contract)]
pub trait ExtCrossContract {
	fn some_method(a: u8) -> String; 
}

What was previously called with:

let contract_account_id: AccountId = todo!();
cross_contract::some_method(8 /* parameters **/, contract_account_id /** account id **/, 0 /** deposit amount **/, 5_000_000_000_000 /** static amount of gas to attach */)

Which requires one to know the ordering of each parameter and how they combined, can now be:

let contract_account_id: AccountId = todo!();
cross_contract::ext(contract_account_id)
 	// Optional config
	.with_attached_deposit(1 /* default deposit of 0 */)
 	.with_static_gas(Gas(5_000_000_000_000) /* default of 0 */)
 	.with_unused_gas_weight(2 /* default 1 */)

 	// Then call any method to schedule the function call
 	.some_method(8 /* parameters */)

// Or very concise, if the defaults are fine
cross_contract::ext(contract_account_id).some_method(9);

Where each with_* method on this will modify the context the method is called with, but are all optional.

The default behavior, if none of the optional parameters are included, is splitting unused gas from the current function execution among all scheduled function calls.

If you only want a static amount of gas to be attached (which is the same as the previous behavior), you can just use with_unused_gas_weight(0).with_static_gas(Gas(<amount of gas>)). Otherwise, you can adjust the unused gas weight for each function call if you want it to use more of the unused gas by increasing the weight, which defaults at 1.

This API allows you to only specify what you want to configure, which also has a reasonable default that will just work for simple cases where you don't need to optimize where gas is allocated with multiple cross-contract calls.

NOTE: When dealing with callbacks, you likely still want to specify a static amount of gas to ensure it succeeds if other calls are made. For production-level contracts, you should still think about how gas is allocated, but this new functionality allows optimization of this without sacrificing control.

Another addition is that by default this API will be attached to the contract struct annotated with #[near_bindgen] which avoids the requirement to re-define the interface with #[ext_contract]. The method that will be attached to the struct is the same as ext_contract as ext(..):

#[near_bindgen]
#[derive(Default, BorshDeserialize, BorshSerialize)]
pub struct Contract;

#[near_bindgen]
impl Contract {
    /// Calls function c with a value that will always succeed
    pub fn a() -> Promise {
        Self::ext(env::current_account_id()).c(9)
    }

    /// Returns value passed in as is.
    #[private]
    pub fn c(value: u8) -> u8 {
        value
    }
}

And can be re-used within or external to the current crate so that the function signatures are connected at compile-time and remove the need to redefine interfaces twice.

More ergonomic log and panic API

Previously, the parameter for near_sdk::env::log and near_sdk::env::panic was bytes (&[u8]) despite the requirement through the NEAR runtime to be valid utf-8. Both of these are now soft deprecated in favor of near_sdk::env::log_str and near_sdk::env::panic_str, which both take &str.

This comes at no cost from the previous API, and there is no requirement to change if the deprecation warnings can be ignored.

The common difference is that instead of env::log(b"some log") you will now write env::log_str("some log") and same for panic.

Added fixed-length bytes alternatives to near_sdk::env

For functions that always returned a fixed length of bytes, improved APIs that do not allocate a Vec<u8> were added. The following were added as alternatives (none have been deprecated yet):

• keccak256: keccak256_array
• keccak512: keccak512_array
• random_seed: random_seed_array
• sha256: sha256_array

Function call error handling

An optional addition to the API is handling errors from #[near_bindgen] functions, which will panic with a str through near_sdk::env::panic_str.

This is only a breaking change if you were previously serializing a Result<_, _> to JSON as a successful serialized return. If you would like to continue this pattern, you can follow the pattern below, but have a nested Result as the Ok type (Result<Result<_, _>, _>).

Avoid unwrapping and panic patterns in favor of cleaner error handling:

#[near_bindgen]
#[derive(Default, BorshDeserialize, BorshSerialize)]
pub struct Contract;

#[near_bindgen]
impl Contract {
    #[handle_result]
    // Can use a custom error type using fmt::Display through `FunctionError` derive.
    pub fn custom_errors() -> Result<u8, ErrorEnum> {
        // ...
    }
    // Or can use any type that implements `AsRef<str>`.
    #[handle_result]
    pub fn static_errors() -> Result<(), &'static str> {
        // ...
    }
}

#[derive(FunctionError, BorshSerialize)]
pub enum ErrorEnum {
    NotFound,
    Banned { account_id: String },
}

impl fmt::Display for ErrorEnum {
    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
        match self {
            ErrorEnum::NotFound => write!(f, "not found"),
            ErrorEnum::Banned { account_id } => write!(f, "account {} is banned", account_id),
        }
    }
}

This desugars to calling env::panic_str on error or serializing and returning Ok value.

#[handle_result] annotation will only be temporarily required for version 4.0 to avoid silently breaking the case mentioned above. The annotation will not be needed in 5.0 when that comes.

Callback result error handling

This addition avoids having to manually check the success of promises by using Result types with #[callback_result] annotation:

    #[private]
    pub fn handle_callbacks(
        // Old pattern, panics on failure
        #[callback_unwrap] a: u8,
        // New pattern, will gracefully handle failed callback results
        #[callback_result] b: Result<u8, near_sdk::PromiseError>,
    ) {
        if b.is_err() {
            // ...
        }
    }

The error type must be PromiseError from the SDK, which indicates the possible error cases of the callback.

With this change, #[callback_unwrap] was added, which is the exact same functionality as #[callback] but was added to be more clear about what it's doing and so that #[callback] can be removed/changed in a future version (there is no way to deprecate the annotation).

Deprecated near_sdk::setup_alloc!()

It is now initialized by default. Disable the wee_alloc feature on the SDK to remove.

Now, this macro is a no-op.

Cleaner low-level syscall interface

Removed need to go through BLOCKCHAIN_INTERFACE:

unsafe {
	near_sdk::env::BLOCKCHAIN_INTERFACE.with(|b| {
		// Load input into register 0.
		b.borrow()
			.as_ref()
			.unwrap()
			.input(0);
	});
}

is now:

unsafe { near_sdk::sys::input(0) }

This type is no longer exported, as there is no need to interact with BLOCKCHAIN_INTERFACE directly.

By extension of this, there is no need to set this interface with env::set_blockchain_interface(Box::new(near_blockchain::NearBlockchain {})); if writing a contract without #[near_bindgen] as this is only used for testing (non wasm32-unknown-unknown targets) and already is defaulted.

Updated testing APIs

Because the mocked interface is set as default for testing environments, as mentioned in the section above, there is no need to set it with some context with testing_env! or env::set_blockchain_interface unless you need to modify a specific context for testing.

Various types were modified/refactored to limit the connection with inner nearcore crates types. Most changes should not require any migration, but some APIs have been changed to be more correct or streamlined. If any do require migration, scan the changelog for what has specifically changed.

Another small change is that MockedBlockchain is no longer required to be imported for testing, which should not have been previously required. If you need to interact with or modify the MockedBlockchain, consider using near_sdk::mock::with_mocked_blockchain.

Removed unused proc macro attributes from near-sdk

Since annotations are handled manually within #[near_bindgen] there was no need to import the callback, callback_vec, result_serializer, init no-op macros. #770

For this, the only thing that needs to change is to remove the import of these functions if for some reason they are imported. Do not remove any of the annotations from the code, they function just as they did previously.

Collections updates

• Under near_sdk::store module
• To use, enable the unstable feature flag on the SDK
  • near-sdk = { version = "4.0.0", features = ["unstable"] }
• Will be stabilized soon. Existing ones will be moved under a legacy feature flag

Core differences from near_sdk::collections

• Caching layer to avoid redundant read/writes
• Less error-prone
  • API that (almost) exactly matches Rust's std::collections
  • Avoids data races and a class of errors that can be solved with Rust's type system
  • Entry and mutable iterator implementations for relevant structures
• Optimized state interactions for UnorderedMap, TreeMap, UnorderedSet and non-state breaking optimizations for others

Avoids manual patterns such as manually moving values, modifying, and re-inserting back into data structures:

let mut map = near_sdk::collections::UnorderedMap::<String, u64>::new(b"m");

// Load into owned value
let mut value: u64 = map.get(&"test".to_string()).unwrap();
// Modify value
value += 1;
// Insert the value back in the map
map.insert(&"test".to_string(), &value);

Can now be replaced with:

let mut map = near_sdk::store::UnorderedMap::<String, u64>::new(b"m");

// Modify value in-place
*map.get_mut("test").unwrap() += 1;

Known downsides

• Increased code size and logic for caching layer
• near-contract-standards are still currently using near_sdk::collections
• Using a more idiomatic Rust API and interacting with the borrow checker might be unintuitive for non-Rust devs
• Some collections are not backwards compatible at a storage level (UnorderedMap, TreeMap, UnorderedSet)

[On0n0k1]

#[handle_result] is making my contracts so much cleaner!

Great work on all the updates!