4/21 Rust SDK tools community update

[austinabell]

4.0 near-sdk-rs changes

Collections updates

• Under near_sdk::store module
• In 4.0 pre-release versions (currently 4.0.0-pre.8), using the unstable feature flag on the SDK
• 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)

Function call error handling

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

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

#[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),
        }
    }
}

#[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> {
        // ...
    }
}

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 breaking changes for people using Result types as function returns. The annotation will not be needed in 5.0 when that comes.

Callback result error handling

Avoid 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() {
            // ...
        }
    }

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.

If you want to skip the validation, you can use AccountId::new_unchecked.

Removed need for near_sdk::setup_alloc!()

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

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) }

NEP264 protocol change and proposed 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.

This PR enables avoiding having to provide a static amount of gas to fund transactions with, based on the motivation from the API proposal issue.

The benefits to this are more optimized cross-contract calls, more concise and intuitive code, and less error-prone cross-contract execution.

4.0.0 stable release plan

NEP264 implementation was just released to testnet. near-sdk version 4.0.0 stable will be released once this update gets released on mainnet, as the above API change relies on the new promise_batch_action_function_call_weight host function on the NEAR runtime.

Tracking issue here

---

ACI (Application Contract Interface)

Name not final but roughly equivalent to Solidity ABI. Intended to be a generated, human-readable schema to be able to identify a contract's API to be able to interact with it externally or from another contract more easily.

Schema format

Early stages of iterating through possible designs. Will publish a document once this stabilizes to get input.

Example schema (not final)

{
	"schema_version": "0.0.1",
	"methods": [
		{
			"name": "add",
			"is_view": true,
			"is_init": false,
			"args": [
				0,
				0
			],
			"callbacks": [],
			"callbacks_vec": [],
			"result": 0
		}
	],
	"types": [
		{
			"id": 0,
			"schema": {
			"title": "Pair",
			"type": "array",
			"items": [
				{
					"type": "integer",
					"format": "uint32",
					"minimum": 0.0
				},
				{
					"type": "integer",
					"format": "uint32",
					"minimum": 0.0
				}
			],
			"maxItems": 2,
			"minItems": 2
			}
		}
	]
}

Schema generation from SDK(s)

Currently, work on a PoC is done by @itegulov on a branch, but updates will be shared once this is ready to be used generally.

Client generation from ACI schema

• Generate boilerplate code to interact with the contract in a frontend through Rust or JS/TS tooling
• Generate boilerplate to interact with contract on-chain through any SDK

The benefit to this is to connect all interfaces of a full-stack dapp at compile time to increase developer velocity, reduce bugs, and unlock new possibilities.

[On0n0k1]

We can build an entire social media platform with that ACI feature. Looking forward to the new release!

[On0n0k1]

Also, any possibility of ACI to display the hash value of the contract's wasm file? That way we can make sure that the contract we are interacting with in the blockchain is the same as the one we want.

[itegulov]

We are exploring what meta information could be added to the schema format. The presented schema format is in no way final and we have been considering adding the hash value of the wasm file. Although where the ACI file will live is still an open question (keeping it a part of the deployed contract is quite costly), so it might not necessarily help the use case described by you.

[On0n0k1]

Thanks for the info. I'm sure the end result will be great.

[coleFD]

Regarding ACI, it looks like it requires a derive macro JsonSchema/BorshSchema for each custom type. Will this result in problems when importing types that dont have the macro defined, or can it be bypassed?

[itegulov]

This would be a problem, yes. There are ways to overcome this though. You could wrap the third-party type into your own transparent type and implement JsonSchema/BorshSchema manually (which is going take some time especially for more complex types). Alternatively, we could implement remote derivation capabilities analogous to serde (see https://serde.rs/remote-derive.html), but this has not been explored yet.