v4.0.0-beta

Version 4.0.0-beta

The focus of the first beta release is to establish the stable ABI for the final 4.0.0
release. It means that whilst subsequent beta releases may contain breaking contract
code changes, the ABI will remain the same so that any contract compiled and deployed
with 4.0.0-beta continue to be compatible with all future 4.0.0 versions.

Compatibility

In order to build contracts which use ink! v4.0.0-beta you need to use
cargo-contract v2.0.0-beta.

You can install it as follows:

cargo install cargo-contract --version 2.0.0-beta

You will also need to use a version of pallet-contracts later than 265e3f1 (Nov 3, 2022)
in your node.

The v0.22.1 release of the substrate-contracts-node is
compatible with the ink! 4.0.0-beta release.

Breaking Changes

Constructors and Messages now return LangErrors

We have added a way to handle errors that are neither specific to a particular contract,
nor from the underlying execution environment (e.g pallet-contracts). Instead these are
errors that may come from the smart contracting language itself.

For example, take the case where a contract message is called using an invalid selector.
This is not something a smart contract author should need to define as failure case, nor
is it something that the Contracts pallet needs to be aware of.

Previously, the contract execution would trap if an invalid selector was used, leaving
callers with no way to handle the error gracefully. This can now be handled with the help
of the newly added LangError.

In short, this change means that all ink! messages and constructors now return a
Result<R, LangError>, where R is the original return type. Contract callers can
choose to handle the LangError.

In order to make this error compatible with other languages we have also added a
lang_error field to the metadata format. This will be the central registry of all the
different error variants which languages may want to emit in the future.

Related pull-requests:

• #1450
• #1504

Related discussions:

• #1207
• paritytech/substrate#11018
• #1002

Random function removed

We had to remove ink_env::random with #1442.

This function allowed contract developers getting random entropy.
There is unfortunately no way how this can be done safely enough
with built-in Substrate primitives on-chain currently. We're
following the recommendation of our auditors to remove it.

The alternative right now is to provide random entropy off-chain to
the contract, to use a random entropy oracle, or to have a chain-extension
that does this, in case the chain has a possibility to do so.

We hope to bring this function back in a future release of ink!, the
best hope right now is that it could come back with Sassafras, a block production
protocol for future versions of Polkadot.

Added

• Allow using Result<Self, Error> as a return type in constructors ‒ #1446
• Add Mapping::take() function allowing to get a value removing it from storage ‒ #1461

Changed

• Add support for language level errors (LangError) ‒ #1450
• Return LangErrors from constructors ‒ #1504
• Update scale-info requirement to 2.3 ‒ #1467
• Merge Mapping::insert(key, val) and Mapping::insert_return_size(key, val) into one method - #1463

Removed

• Remove ink_env::random function ‒ #1442

v3.4.0

Version 3.4.0

We keep ink! v3 updated with nice features and fixes from the master branch.

This release:

• Introduces the ink_env::pay_with_call! helper macro for the emulation of invoking payble messages in off-chain tests.
  As response to ink! developers request on the Substrate StackExchange.
• Fixes contracts compilation error with the latest Rust +nightly ‒ #1417 (thanks @xgreenx).

See the back portation PR #1439 for details.

v4.0.0-alpha.3

4.0.0-alpha.2 was skipped because of an error in the release process

Breaking Changes

New ink crate

The ink_lang crate has been replaced in #1223 by a new top level ink
crate. All existing sub-crates are reexported and should be used via the new ink crate, so e.g. ink::env instead of
ink_env. Contract authors should now import the top level ink crate instead of the individual crates.

Migration

• In Cargo.toml Replace all individual ink_* crate dependencies with the ink crate.
• In the contract source:
  • Remove the commonly used use ink_lang as ink idiom.
  • Replace all usages of individual crates with reexports, e.g. ink_env ➜ ink::env.

Storage Rework

#1331 changes the way ink! works with contract storage. Storage keys
are generated at compile-time, and user facing abstractions which determine how contract data is laid out in storage
have changed.

Migration

• Initialize Mapping fields with Mapping::default() instead of ink_lang::utils::initialize_contract in
  constructors. See erc20 and other examples which use a Mapping.
• Remove SpreadAllocate, SpreadLayout and PackedLayout implementations.

Removal of wee-alloc support

ink! uses a bump allocator by default, additionally we supported another allocator (wee-alloc)
through a feature flag. wee-alloc is no longer maintained and we removed support for it.

Changed

• Introduce ink entrance crate ‒ #1223
• Use XXH32 instead of sha256 for calculating storage keys ‒ #1393

Fixed

• Trim single whitespace prefix in the metadata docs field ‒ #1385
• Allow pay_with_call to take multiple arguments ‒ #1401

Added

• Add ink_env::pay_with_call! helper macro for off-chain emulation of sending payments with contract message calls ‒ #1379

Removed

• Remove wee-alloc ‒ #1403

v4.0.0-alpha.1

Version 4.0.0-alpha.1

Compatibility

In order to build contracts which use ink! v4.0.0-alpha.1 you need to use cargo-contract
v2.0.0-alpha.1. You can install it as follows:

cargo install cargo-contract --version 2.0.0-alpha.1

We recommend using a version of the pallet-contracts later than 6b85535
(Aug 12, 2022) in your node.

The compatibility issues will be with ChainExtension's and the functions mentioned above.

Breaking Changes

This release contains a few breaking changes. These are indicated with the ❌ emoji.
Most of these were intitially introduced in v3.1.0 and v3.2.0 releases but
compatibility was restored in v3.3.0.

• As part of #1224 the return type of ink_env::set_contract_storage() was changed to
  return an Option<u32> instead of ().
• As part of #1233 the eth_compatibility crate was removed. The
  ecdsa_to_eth_address() function from it can now be found in the ink_env crate.
• As part of #1267 an argument to ink_lang::codegen::execute_constructor() (which is
  used internally by the ink! macros) was removed.
• As part of #1313 the ink! ABI was changed so that the version was specified using a
  dedicated version key instead of an implicit key which wrapped the entire ABI.

Added

• ❌ Add Mapping::contains(key) and Mapping::insert_return_size(key, val) ‒ #1224
• Add payment-channel example ‒ #1248
• ❌ Add version field to ink! metadata ‒ #1313
• The rand-extension example has been adapted to an updated version of the ChainExtension API ‒ #1356

Changed

• ❌ Contract size optimization in case contract doesn't accept payment ‒ #1267 (thanks @xgreenx).
• Move ink! linter into ink repository ‒ #1361

Removed

• ❌ Implement ecdsa_to_eth_address() and remove eth_compatibility crate ‒ #1233

v3.3.1

Version 3.3.1

At the moment teams which use both Substrate and ink! in the same codebase are
experiencing some issues with updating to Substrate's polkadot-0.9.27 branch.
This is because that branch uses the secp256k1@0.24, which is incompatible with
secp256k1@0.22

This release bumps the secp256k1 version from v0.22 to v0.24.

v3.3.0

Version 3.3.0

This release restores SemVer compatibility in the v3.x series of releases, as well as compatibility with the v0.13.0 release of the substrate-contracts-node.

Compatibility

This version will work fine with substrate-contracts-node versions from 0.13.0 up to 0.16.0.

Changed

Context: user-reported issues on our SE unveiled backward incompatibility introduced in 3.1.0 release.

1. CodeRejected when using ink! v3.1.0
2. Incompatibility between ink! v3.0.1 and v3.2.0

The following has been done to restore backward compatibility:

• Reverted backward-incompatible piece of #1224.
  • The return signature of ink_env::set_contract_storage() was changed to return an Option<u32>.
    This could have broken existing code, so this should've been done in a MAJOR release.
  • Under the hood the PR also changed Mapping::insert() to use a new SEAL API
    ([seal1] seal_set_storage), which resulted in CodeRejected errors in nodes which did not have this API (e.g substrate-contracts-node@0.13.0).
• Reverted "Optimise deny_payment. Use everywhere semantic of deny (#1267)"
  • This one is to restore compatibility between minor versions of ink! crates; see @HCastano's SE answer in this regard.
• Reverted backward-incompatible piece of #1233.
  • The removal of the eth_compatibility crate should have been done in a MAJOR release.

All these breaking changes are subjects to the upcoming MAJOR ink! release 4.0.0.

v3.2.0

Version 3.2.0

Compatibility

We recommend using a version of the pallet-contracts later than c0ee2ad (May 23, 2022) in your node.

This is the case in the latest release of the substrate-contracts-nodev0.16.0.

Added

• Contract size optimization in case contract doesn't accept payment ‒ #1267 (thanks @xgreenx).

Changed

• Two functions have been stabilized: ink_env::ecdsa_recover and ink_env::ecdsa_to_eth_address ‒ #1270 #1273

Fixed

• Fixed bug with recent Rust and cargo test ‒ #1272 (thanks @xgreenx).

v3.1.0

Version 3.1.0

Compatibility

We recommend using a version of the pallet-contracts later than 7d233c2 (May 13, 2022) in your node.

This is the case in the latest release of the substrate-contracts-nodev0.15.1 and the latest Polkadot release v0.9.22.

Breaking Changes

There are two breaking changes in this release:

• As part of #1235 the message selectors of your contract may change. A change of selectors would affect your client, frontend, Dapp, etc..
• As part of #1233 we removed the eth_compatibility crate.
  Its recovery functionality has been moved to ink_env now: ink_env::ecdsa_to_eth_address. The reason for this change is that we moved the gas-expensive crypto operations into pallet-contracts.
  The crates to_default_account_id function has been removed; the reason for this change is that ink! doesn't have knowledge about the specific Substrate types on the underlying chain. If you want to retain the function in your contract and are just using standard Substrate types you should add the prior functionality to your contract ‒ it was a simple <Blake2x256 as CryptoHash>::hash(&ecdsa_pubkey[u8; 33]).

New API functions

We added two new Mapping API functions: Mapping::contains and Mapping::insert_return_size ‒ #1224. These are more gas-efficient than whatever you were using previously.

Additionaly there are a couple new ink_env functions now:

• ink_env::set_code_hash
• ink_env::own_code_hash
• ink_env::code_hash
• ink_env::ecdsa_to_eth_address

New Upgradeable Contract Example

We've added a new example: upgradeable-contracts/set-code-hash.

It illustrates how the newly added ink_env::set_code_hash can be used to implement an upgradeable contract that replaces its own code.

Added

• Implement seal_code_hash and seal_own_code_hash ‒ #1205
• Add set_code_hash function and example ‒ #1203
• Implement ink_env::ecdsa_to_eth_address ‒ #1233
• Add Mapping::contains(key) and Mapping::insert_return_size(key, val) ‒ #1224

Fixed

• Fix ordering of message ids if the trait is implemented before the inherent section ‒ #1235

Removed

• Removed eth_compatibility crate and moved its functionality partly into ink_env ‒ #1233

v3.0.1

Version 3.0.1

Changed

• Improve upgradeable examples folder structure, explain differences ‒ #1188

Fixed

• Update codegen after SCALE v3.1.2 release ‒ #1189
• Stop using CallData in multisig example doc test ‒ #1202

v3.0.0

Version 3.0.0

This is the stable release for ink! 3.0.

It took us a while to get here and going forward we want to do smaller releases more often.

Please note that ink! has not been audited.

Compatibility

We recommend using a version of the contracts pallet later than cc282f84ba53ed2a08374d2a655dc8f08cbc5e86 (March 15, 2022) in your node.

This is the case in the latest release of the substrate-contracts-node: v0.10.0.

Breaking Changes

We replaced the default off-chain testing environment

The off-chain testing environment can be used to write unit tests for your smart contract with a simulated chain. We've now replaced the existing off-chain environment with a new one, which has a bit of a different API.

The major changes are that there is no longer any notion of "execution context" ‒ so no more push_execution_context or pop_execution_context. You can achieve all the same things with the new API, see here for the API documentation.

We've also switched all our examples to this new environment, you can find more "template use-cases" there (e.g. for chain extension testing)

We removed the dynamic storage allocator

More details on the reasoning behind this can be found in #1148.

CallBuilder API changed to support delegate calls

The CallBuilder API changed to now support two types of calls:

• Call: a cross-contract call.
  
  This was the default until this new API change.
• DelegateCall: a delegated call.
  
  This enables writing upgradeable contracts using the delegate pattern. An example has been added to demonstrate this: delegate-calls.

This is a breaking change, users must now specify the call_type to the builder manually.

If you want to keep existing behavior you just need to specify the type Call now.

More details on this change can be found in #1133.

Unify ink_env::{eval_contract, invoke_contract}

The API for eval_contract and invoke_contract changed. You can read more about the change in #1165.

Added

• Added keep_attr to #[ink::contract] and #[ink::trait_definition] ‒ #1145 (thanks @xgreenx)..
• Implemented the seal_is_contract and seal_caller_is_origin API ‒ #1129 #1166.
• Add tests in experimental off-chain env for trait-erc20 ‒ #1158.
• Add tests in experimental off-chain env for erc721 ‒ #1157.
• Add tests in experimental off-chain env for multisig ‒ #1159.
• Add tests in experimental off-chain env for dns ‒ #1156.
• Implemented chain extension testing in experimental off-chain env ‒ #1152.

Changed

• Replaced default off-chain testing engine with experimental one ‒ #1144.
• Changed CallBuilder API to now support delegate calls ‒ #1133 (thanks @VargSupercolony and @xgreenx).
• Unify ink_env::{eval_contract, invoke_contract} ‒ #1165.

Removed

• Removed the dynamic storage allocator ‒ #1148.
• Removed compile_as_dependency config option ‒ #1168.