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.

ink! 3.0.0 RC 9

Version 3.0-rc9

This is the 9th release candidate for ink! 3.0.

Breaking Changes

We removed all data structures other than Mapping from the public ink! API

This is a drastic breaking change; it was no easy decision for us.
It affects Lazy and Memory as well. The rationale behind this change,
as well as some notes on migrating existing contracts, are explained
in #1111 and
#1137.

If you used Memory in your contract, you can achieve the same functionality
by passing this data via arguments. If you think there's a case to be
made for bringing it back, please get in contact with us.

If you use ink_storage::Mapping
in your contract, you need to initialize the data structure using the helper function
ink_lang::utils::initialize_contract(…).
For more code examples you can take a look at our examples, e.g.
erc20.

Please upgrade scale-info and parity-scale-codec in your contract's dependencies

In this release candidate we upgraded scale-info and parity-scale-codec. You have to use a compatible
version in your contract's Cargo.toml as well; cargo-contract will throw an error otherwise.

The Cargo.toml should contain

scale-info = { version = "2", default-features = false, features = ["derive"], optional = true }
scale = { package = "parity-scale-codec", version = "3", default-features = false, features = ["derive", "full"] }

Added

• Export ink_lang::utils::initialize_contract(…) - #1077.
• Add get_owner() function to dns example contract - #1118 (thanks @agryaznov).
• Improved usage documentation of ink_storage::Mapping - #1138.

Changed

• Updated to parity-scale-codec = "3" and scale-info = "2" - #1132.

Removed

• Remove collection and lazy modules from public ink! API - #1111.
• Remove Memory from public ink! API - #1137.

Fixed

• Fix bug with referencing two external trait definitions - #1141.
• Explicitly specify trait in dispatching - #1131 (thanks @xgreenx).
• Make rust-analyzer expand ink! macros without warning - #1107.

ink! 3.0.0 RC 8

Version 3.0-rc8

This is the 8th release candidate for ink! 3.0.

Compatibility

You need to upgrade to a new version of the contracts pallet in order to use this
ink! release. Specifically we recommend you upgrade to at least the pallet version
249dbbb
(or newer than Jan 17, 2022).

For substrate-contracts-node we just issued a new release v0.5.0, which has been synchronized
to the latest Substrate master and hence is compatible with this ink! release candidate.

Also, the metadata changed with this release, so you need to have a recent version of
the user interface you are using. For polkadot-js/api and polkadot-js/apps the metadata
changes are supported since Jan 19, 2022.

Metadata Changes

There are two metadata changes in this release candidate:

For messages and constructors: name: Array ➔ label: String

The messages and constructors exposed by a contract were previously denoted with

"name": ["foo", "bar"]

Now they are instead denoted with

"label": "foo"

For public contract methods that are implemented from a trait, the trait name is prefixed to
the method name with :: as the separator. So e.g. trait_name::get_owner.

The ink! PR which implemented this is #923,
for the polkadot-js/api it was polkadot-js/api#4255.

Constructors got a new field: payable: bool

Constructors now have to be specified payable if it's intended for them to receive value
(i.e. tokens). This is a breaking change, beforehand they were by default payable,
now they are by default non-payable.

The ink! PR which implemented this is #1065, the PR that updated the ink!
metadata to V3 is #1100, and for the polkadot-js/api it was polkadot-js/api#4432.

Changed

• Update metadate to support payable constructors - #1100.
• Make constructors non-payable by default, require specifying payable explicitly - #1065.
• Renamed the error code EcdsaRecoverFailed to EcdsaRecoveryFailed ‒ #1064.
• Renamed the ink_env function transferred_balance() to transferred_value() ‒ #1063.
• Removed the error codes BelowSubsistenceThreshold and NewContractNotFunded ‒ #1062.
• Updated ink! to use the most recent contracts pallet API ‒ #1053.
• Explicitly link against rlibc to get non-buggy version of memcpy ‒ #1049.
• Changed the metadata field name to label for messages and constructors ‒ #923 (thanks @xgreenx).

Added

• Added a remove method to the Mapping data structure ‒ #1023.

ink! 3.0.0 RC 7

Version 3.0-rc7

This is the 7th release candidate for ink! 3.0.

Since our last release candidate we implemented a number of contract size improvements.
With those improvements the size of our erc20 example has reduced significantly:

		Release Build with cargo-contract
erc20	3.0.0-rc6	29.3 K
erc20	3.0.0-rc7	10.4 K

The savings apply partly to our other examples; for erc20 they are most
significant since it has been migrated to use a new Mapping
data structure, which we introduce with this release candidate.
The other examples will be migrated to this new data structure as a next step.

Removed

• Removed the state rent API ‒ #1036.

Added

• Added support for wildcard selectors ‒ #1020.
  • This enables writing upgradable smart contracts using the proxy/forward pattern.
    We added a new example to illustrate this ‒ the proxy example.
  • Annotating a wildcard selector in traits is not supported.
• The ink! codegen now heavily relies on static type information based on traits defined in ink_lang ‒ #665.
  • Some of those traits and their carried information can be used for static reflection of ink!
    smart contracts. Those types and traits reside in the new ink_lang::reflect module and is
    publicly usable by ink! smart contract authors.

Changed

• Upgraded to the seal_call v1 API ‒ #960.
  • This API now enables control over the behavior of cross-contract calls, e.g. to forward/clone input,
    enable tail calls and control reentrancy.
    The crate documentation contains more details on the CallFlags.
  • Note: The default behavior of cross-contract calls now disallows reentering the calling contract.
• ink! contract definitions via #[ink::contract] ‒ #665.
  
  For ink! smart contracts we now generate two contract types. Given MyContract:
  • MyContract will still be the storage struct.
    However, it can now additionally be used as static dependency in other smart contracts.
    Static dependencies can be envisioned as being directly embedded into a smart contract.
  • MyContractRef is pretty much the same of what we had gotten with the old ink-as-dependency.
    It is a typed thin-wrapper around an AccountId that is mirroring the ink! smart contract's API
    and implemented traits.
• ink! trait definitions via #[ink::trait_definition] ‒ #665.
  • ink! trait definitions no longer can define trait constructors.
  • ink! trait implementations now inherit selector and payable properties for trait messages.
    • Now explicitly setting selector or payable property for an implemented ink! trait method
      will only act as a guard that the set property is in fact the same as defined by the ink!
      trait definition.
• Improved some ink! specific compile errors ‒ #665.
  • For example, when using ink! messages and constructors which have inputs (or
    outputs) that cannot be encoded (or decoded) using the SCALE codec.
• Simplified selector computation for ink! trait methods ‒ #665.
  • Now selectors are encoded as blake2b({namespace}::{trait_identifier}::{message_identifier})[0..4].
    If no namespace is set for the ink! trait definition then the formula is
    blake2b({trait_identifier}::{message_identifier})[0..4].
    Where trait_identifier and message_identifier both refer to the identifiers of the ink! trait
    definition and ink! trait message respectively.
• We switched to Rust edition 2021 ‒ #977.
• Update chain extension example to show argument passing ‒ #1029.

Fixed

• Contracts now revert the transaction if an ink! message returns Result::Err ‒ #975, #998.
  • It is still possible to match against a Result return type for a called dependency contract
    ‒ i.e. a sub-contract specified in the contract's Cargo.toml.
• We implemented a number of Wasm contract size improvements:
  • Simple Mapping Storage Primitive ‒ #946.
  • Remove always from inline to allow compiler decide that to do ‒ #1012 (thanks @xgreenx).
  • Add a way to allocate a storage facility using spread (and packed) layouts ‒ #978.
  • Extract non-generic part of push_topic to reduce code size ‒ #1026.

ink! 3.0.0 RC 6

Version 3.0-rc6

This is the 6th release candidate for ink! 3.0.

Added

• Added an Ethereum-compatibility function to recover a public key from an ECDSA signature and message hash - #914 (thanks @xgreenx).

Changed

• Update to scale-info 1.0 - #845.
• Message and constructor selectors no longer take their inputs as string, but as u32 decodable integer - #928.
  For example:
  • It is no longer possible to specify a selector as #[ink(selector = "0xC0DECAFE")].
  • The newly allowed formats are #[ink(selector = 0xC0DECAFE)] and #[ink(selector = 42)].
  • Smart contract authors are required to update their smart contracts for this change.
• Improved the multisig example - #962.
• Changed the link to our beginner's workshop to the migrated workshop on substrate.io - #957.

Fixed

• Fixed a mistake in the ink_env::block_timestamp() documentation - #937.

ink! 3.0.0 RC 5

Version 3.0-rc5 (2021-09-08)

This is the 5th release candidate for ink! 3.0.

The list below shows the additions, changes and fixes that are visible to users of ink!.

Compatibility

In the past we recommended using our canvas-node for local contract development and testing. We've now migrated this node to be run as a Parachain. This new setup comes with some additional overhead though (such as requiring a local Polkadot installation); for local development this is often unnecessary.

We've therefore created a new project, the substrate-contracts-node. It fulfills the same purpose the canvas-node did before ‒ it's a standalone node which is just Substrate's node-template modified to include the contracts pallet.
You can install the newest version like this:

cargo install contracts-node --git https://github.com/paritytech/substrate-contracts-node.git --force

After you've installed the node it can be run via substrate-contracts-node --tmp --dev.

Added

• Added example for mocking chain extensions in off-chain tests ‒ #882.
• Panic messages are now printed to debug buffer ‒ #894.

Changed

• Unlicensed smart contract examples ‒ #888.
• Stabilized seal_debug_message ‒ #902.

ink! 3.0.0 RC 4

Version 3.0-rc4 (2021-07-19)

This is the 4th release candidate for ink! 3.0.

The list below shows the additions, changes and fixes that are visible to users of ink!.

Compatibility

ink! 3.0-rc4 is compatible with

• The "ink! CLI" cargo-contract
  version 0.13.0 or newer.
  • Install the newest version using cargo install --force cargo-contract.
• Substrate version 4.0.0-dev including the contracts-pallet version 4.0.0-dev.
• canvas-node version 0.19.0 or newer.
  • Install the newest version using cargo install canvas-node --git https://github.com/paritytech/canvas-node.git --force.

The documentation on our Documentation Portal
is up to date with this release candidate. Since the last release candidate we notabley
added a number of Frequently Asked Questions
there.

Quality Assurance

In order to ensure a continuously high quality of our codebase we implemented a number
of key improvements to our testing setup:

• We've put an emphasis on automated testing of the usage examples in our crate documentation.
  Those are now tested in the context of a complete ink! contract. In the past this was not
  always the case, sometimes usage examples were just isolated code snippets.
• We started our ink-waterfall project,
  which runs End-to-End tests through our entire stack.
  All our examples are continuously built using the latest cargo-contract. They are
  subsequently deployed on the latest canvas-node by emulating browser interactions with
  both the canvas-ui and the
  polkadot-js UI.
  This testing setup enables us to detect bugs which only appear in the context of using
  multiple components together early on.
• To improve the readability of our documentation we introduced automated grammar and spell
  checking into our Continuous Integration environment.

Added

• Added support for the new seal_random API ‒ #734.
• Added missing documentation for the ink_storage_derive procedural macros ‒ #711.
• Implemented the (unstable) seal_rent_params API ‒ #755.
• Implemented the (unstable) seal_rent_status API ‒ #798.
• Implemented the (unstable) seal_debug_message API ‒ #792.
  • Printing debug messages can now be achieved via ink_env::debug_println!(…).
  • See our documentation
    for more information.
  • The examples have been updated to reflect this new way of printing debug messages.
• Added usage comments with code examples to the ink_env API ‒ #797.
  • The published crate documentation now contains
    much more code examples for the methods behind self.env() and Self::env().
• Added an example implementation for ERC-1155, a multi-token standard ‒ #800.
• Implemented binary search for collections::Vec ‒ #836.
• Added the ability of submitting payable transactions to the multisig example ‒ #820.
• Implemented Decode for Error types in the examples, enabling building them as dependencies ‒ #761.
• We started working on a new off-chain environment testing engine ‒ #712.
  • The old testing environment has a number of limitations, which we are well aware of.
    We're confident that with the new testing engine we will be able to conduct much more
    elaborate testing in an emulated chain environment.
  • For the moment, the new engine is unstable and only available behind a feature flag.
    A number of examples have already been converted to support the new testing engine.

Changed

• To reduce a contract's space footprint we switched the default allocator to a bump allocator implementation ‒ #831.
• A couple of readme's have been reworked:
  • Our main ink! readme ‒ #774.
  • The rand-extension example readme ‒ #793.
  • The delegator example readme ‒ #766.
• With the stabilization of Rust 1.51 we ware able to remove the ink-unstable feature, making
  collections::SmallVec and lazy::LazyArray available by default ‒ #746.
• To resolve confusion, we migrated all usages of #[test] in our examples to #[ink::test] ‒ #746.
  • The difference is that #[ink::test] spawns an emulated chain environment (an "off-chain" environment)
    and hence comes with a bit of overhead. It was not always clear to users when they require
    an off-chain environment, we decided to mitigate this confusion by using an emulated chain
    environment for all our example tests.
• With the stabilization of Rust's min_const_generics we were able to replace the fixed
  size implementations of SpreadLayout and PackedLayout for Arrays. These traits are
  now implemented for all Arrays of size usize ‒ #754.
• We were able to remove the pinned funty dependency ‒ #711.
• The contract-transfer example has been improved for better UI support ‒ #789.
• The contract-transfer example has been improved for better error handling ‒ #790.

Fixed

• Catch illegal struct destructuring pattern in ink! message arguments ‒ #846.
• Removed an erroneous Salt type in code generation for cross-contract calls ‒ #842.
• Do not generate metadata if compiled as dependency ‒ #811.
• Fix execution context parameters in DNS example tests ‒ #723.
• Fixed the Greeter contract example from our doc comments ‒ #773.