v4.0.1

Version 4.0.1

Fixed

• Fixing ManualKey<0> to act properly - #1670
• Indicated latest release of cargo-contract in e2e crate

v4.0.0

Version 4.0.0

The latest stable release of ink! is here 🥳

This version brings a lot of usability improvements, making the language better suited for the needs of production parachains.

A couple of highlights include:

• Changes to how contract storage works, which significantly reduced the sizes of
  contract binaries
• A new end-to-end testing framework, letting you easily write integration tests
• Changes to the metadata format, which (in part) makes error handling more expressive

There's a lot more to dig through, so take some time to poke around the CHANGELOG (including the 4.0.0-alpha and 4.0.0-beta releases).

You may notice there have been a few breaking changes. No need to be scared though, we wrote up a migration guide covering all of the breaking changes and how to update your ink! 3.x contract accordingly.

Thanks to everyone that helped make this release possible ❤️

Compatibility

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

cargo install cargo-contract --forced --locked

You will also need to use a version of pallet-contracts later than polkadot-v0.9.37 in your node.

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

For full compatibility requirements see the migration guide.

Added

• Add Mapping::contains(key) and Mapping::insert_return_size(key, val) ‒ #1224
• Add payment-channel example ‒ #1248 (thanks @kanishkatn!)
• Add version field to ink! metadata ‒ #1313
• The rand-extension example has been adapted to an updated version of the ChainExtension API ‒ #1356
• Add ink_env::pay_with_call! helper macro for off-chain emulation of sending payments with contract message calls ‒ #1379
• 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
• Add E2E testing framework MVP ‒ #1395
• Add E2E tests for Mapping functions - #1492
• E2E: expose call dry-run method ‒ #1624
• Make cross-contract callee non-optional ‒ #1636
• Support custom environment in E2E tests - #1645 (thanks @pmikolajczyk41!)

Changed

• Contract size optimization in case contract doesn't accept payment ‒ #1267 (thanks @xgreenx!)
• Move ink! linter into ink repository ‒ #1361
• Introduce ink entrance crate ‒ #1223
• Use XXH32 instead of sha256 for calculating storage keys ‒ #1393
• Storage Refactoring ‒ #1331
• 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
• FFI: no more __unstable__ wasm import module ‒ #1522
• Clean up CallBuilder return() type ‒ #1525
• Fix trait message return type metadata ‒ #1531
• Bump Dylint dependencies ‒ #1551
• Stabilize take_storage ‒ #1568
• Chain Extension: Evaluation of method return type at compile time ‒ #1569
• Make more functions be const ‒ #1574 (thanks @yjhmelody!)
• Unify fallible and non fallible instantiate methods ‒ #1591
• Make CallBuilder and CreateBuilder error handling optional ‒ #1602
• Rename CallBuilder::fire() method to invoke() ‒ #1604
• chore: add minimum rust version to the ink crate ‒ #1609 (thanks @Kurtsley!)
• Rename _checked codegen call methods with try_ ‒ #1621
• Bump Substrate and subxt dependencies ‒ #1549
• E2E: spawn a separate contracts node instance per test ‒ #1642

Fixed

• Trim single whitespace prefix in the metadata docs field ‒ #1385
• Allow pay_with_call to take multiple arguments ‒ #1401
• Add Determinism enum from pallet-contracts ‒ #1547
• Added missed WhereClosure for the generics into storage_item ‒ #1536 (thanks @xgreenx!)

Removed

• Implement ecdsa_to_eth_address() and remove eth_compatibility crate ‒ #1233
• Remove wee-alloc ‒ #1403
• Remove ink_env::random function ‒ #1442
• Remove Default implementation for AccountId ‒ #1255

v4.0.0-rc

The first release candidate is here! This is the first release which could become the final
v4.0.0. Any subsequent release candidates should only contain bug fixes: no API changes,
breaking or otherwise.

Breaking Changes

1. We've renamed some of the generated message methods on the ContractRef struct. They
   have been changed from _checked to try_ (#1621)
2. We have removed the Default implementation for AccountIds. This is because of
   security concerns around the use of the zero address which has a known private key in
   the sr25519 and ed25519 curves (#1255).
3. We have replaced the CallBuilder::callee() method with a call() method and also
   added a delegate() method. This streamlines the Call and DelegateCall workflows
   (#1636)

Added

• E2E: expose call dry-run method ‒ #1624
• Make cross-contract callee non-optional ‒ #1636

Changed

• Rename _checked codegen call methods with try_ ‒ #1621
• Bump Substrate and subxt dependencies ‒ #1549

Removed

• Remove Default implementation for AccountId ‒ #1255

v4.0.0-beta.1

This supersedes #1590, but RC coming soon™

Version 4.0.0-beta.1

The coolest feature included in this release is the first first published version of
ink!'s native "end-to-end" (E2E) testing framework.

This enables testing of a contract by deploying and calling it on a Substrate node with
pallet-contracts. See the erc20 example for usage.

Breaking Changes

This release includes a couple of breaking changes.

1. The CallBuilder::returns() method does not require an extra MessageResult anymore
   as the type is now added under the hood (#1525)
2. The CallBuilder::invoke() and CreateBuilder::instantiate() methods now unwrap the
   Result from pallet-contracts under the hood (#1602)
   If you wish to handle the error use the new try_ variants of those methods instead.
3. The CallBuilder::fire() method has been renamed to invoke()
   (#1604)
4. The returns_result flag has been removed from the #[ink(extension = …)] attribute
   (#1569)
   We now infer this information at compile time. If handle_status is set to true,
   the return type will still be wrapped into Result as before.
5. The Minimum Supported Rust Version (MSRV) has been set to 1.63.0. This was already
   the case, but previously it was enforced by cargo-contract instead of ink!
   (#1609)

Added

• Add E2E testing framework MVP ‒ #1395
• Add E2E tests for Mapping functions - #1492

Fixed

• Add Determinism enum from pallet-contracts ‒ #1547
• Added missed WhereClosure for the generics into storage_item ‒ #1536 (thanks @xgreenx)

Changed

• Handle LangError from instantiate ‒ #1512
• FFI: no more __unstable__ wasm import module ‒ #1522
• Clean up CallBuilder return() type ‒ #1525
• Fix trait message return type metadata ‒ #1531
• Bump Dylint dependencies ‒ #1551
• Stabilize take_storage ‒ #1568
• Chain Extension: Evaluation of method return type at compile time ‒ #1569
• Make more functions be const ‒ #1574 (thanks @yjhmelody)
• Unify fallible and non fallible instantiate methods ‒ #1591
• Make CallBuilder and CreateBuilder error handling optional ‒ #1602
• Rename CallBuilder::fire() method to invoke() ‒ #1604
• chore: add minimum rust version to the ink crate ‒ #1609 (thanks @Kurtsley)

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 [email protected], which is incompatible with
[email protected]

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 [email protected]).
• 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.