Summary

This is our first alpha release for ink! v6. We release it together with cargo-contract v6.0.0-alpha.

The biggest change is that we are in the process of migrating from pallet-contracts +
WebAssembly (executed in wasmi) to pallet-revive +
RISC-V (executed in PolkaVM).
This is a major breaking change, ink! v6 will only be compatible with cargo-contract >= v6
and chains that include pallet-revive.

We did a detailed write-up of the background to this development and the reasoning
here. We also updated the ink/ARCHITECTURE.md
to reflect the new setup.

Compatibility of this release:

In the following we'll describe some breaking changes on a high-level. The
context to understand them is that the pallet-revive team has Ethereum/Solidity
support as the number one priority. All their design decisions derive from that,
they don't want to maintain code that is unnecessary for that objective.

🚧 This is an alpha release, changes will still happen and there are rough edges. 🚧

Cross-contract calling Solidity contracts

We are introducing a new attribute abi for the #[ink::contract] macro.
These are the values it takes:

#[ink::contract(abi = "all")]
#[ink::contract(abi = "sol")]
#[ink::contract(abi = "ink")]

The default currently is abi = "ink", but we might change this before a production
release.

The implication of supporting Solidity ABI encoding is that there is a restriction on
the types you can use as constructor/message arguments or return types.
You won't be able to use Rust types for which no mapping to a Solidity type exists.
An error about a missing trait implementation for this type will be thrown.

Please note that your contract sizes will get larger if you support both the ink!
and Solidity ABI.

Types

Contract Balance: `U256`

For the type of a contract's balance, pallet-revive uses depending on the context

either the configured pallet_revive::Config::Currency type (which corresponds
to the ink::Environment::Balance type.
or a hardcoded U256 (which corresponds to what Ethereum uses).
In this alpha release we just adhere to requiring the types that pallet-revive uses.
In an upcoming beta release this could be simplified to reduce UX friction by just
using one type everywhere and converting to the pallet-revive one.

Contract Address: `Address` / `H160`

For a contract's account, pallet-revive is using either the configured AccountId type
of the polkadot-sdk runtime, or H160.

Address is a more semantically named type alias for H160 defined in ink_primitives,
and re-exported in the ink crate.

Finding the Address/H160 for an AccountId is done via an address derivation scheme
derived in #7662.
After instantiating a contract, the address is no longer returned by pallet-revive.
Instead one has to derive it from given parameters (see the linked PR). cargo-contract
does that automatically.

For contract instantiations and contract calls the pallet requires that a 1-to-1 mapping
of an AccountId to an Address/H160 has been created. This can be done via the
map_account/unmap_account API.
The PR #6096 contains more
information.

Besides the publicly exposed crate functions, we've introduced a new subcommand
cargo contract account that allows resolving the H160 contract address to the
Substrate AccountId which it is mapped to.

Contract Hash: `H256`

For a contract's hash value, pallet-revive uses a fixed H256, Previously,
the ink::Environment::Hash type referenced the hash type being used for the
contract's hash. Now it's just a fixed H256.

Contract delegates can no longer be done by code

In pallet-contracts (and hence up until ink! v5), a pattern for upgradeable
contracts was to delegate the contract execution to a different code, e.g. to
a new version of the contract's code.

This distinction of contract code that was uploaded to a chain vs. an instantiated
contract from this code no longer exists in pallet-revive. If you want to
delegate the execution, you will have to specify another contract's address
to which code you want to delegate to. This other contract needs to be instantiated
on-chain.

For the execution, the context of the contract that delegates will continue
to be used (storage, caller, value).

Specifically the delegate API changed like this:

/// ink! v5
#[derive(Clone)]
pub struct DelegateCall<E: Environment> {
    code_hash: E::Hash,
    call_flags: CallFlags,
}

/// ink! v6
#[derive(Clone)]
pub struct DelegateCall {
    address: H160,
    flags: CallFlags,
    ref_time_limit: u64,
    proof_size_limit: u64,
    deposit_limit: Option<[u8; 32]>,
}

Feature `ink/unstable-hostfn`

In pallet-revive a number of functions can only be called by smart contracts
if the chain that the pallet is running on has enabled the feature
pallet-revive/unstable-hostfn.
This feature is not enabled on Kusama or Westend!

It is enabled for the substrate-contracts-node version that we linked above.

New debugging workflow

Previously pallet-contracts returned a debug_message field with contract
instantiations and dry-runs.
Whenever ink::env::debug_println was invoked in a contract, ink! wrote debugging
info to this field. This functionality has been removed. Instead pallet-revive now
supports other means of debugging.

The most relevant new debugging workflow is the tracing API. There are a number
of PRs that implemented it, so we won't link a specific one here. A good starting
point to look deeper into it is the tracing.rs.

We have implemented barebones support for this tracing API in the 6.0.0-alpha
versions of ink! + cargo-contract. But it's really barebones and should
certainly be improved before a production release.

Please see our developer documentation
for more details.
We've also added a contract example to illustrate these new debugging strategies:
debugging-strategies.

Restrictions which `cfg` attributes can be used

This change was done as a recommendation from the ink! 5.x audit.
In a nutshell it prevents developers from hiding functionality in a contract,
that would not be visible in the metadata (so e.g. on a block explorer).
The relevant PR is #2313.

From ink! 6.0 on only these attributes are allowed in #[cfg(…)]:

test
feature (without std)
any
not
all

Metadata Changes

The field source.wasm was renamed to source.contract_binary.

`no_main`

Previously ink! contracts started with this line:

#![cfg_attr(not(feature = "std"), no_std)]

This line instructs the Rust compiler to not link the Rust
standard library with your contract.
If you want to know about why:
we have an entry
"Why is Rust's standard library (stdlib) not available in ink!?"
Please see our developer documentation
in our FAQ.

With ink! v6, an additional crate-level attribute needs to be set:

#![cfg_attr(not(feature = "std"), no_std, no_main)]

It instructs the compiler not to use the default fn main() {} function as the
entry point for your smart contract. This is needed because PolkaVM uses a different
entry point (the deploy function).

`substrate-contracts-node` can no longer be used

The substrate-contracts-node is still maintained by Parity for ink! v5 and
pallet-contracts, but it does not support pallet-revive.

We've set up a new project in its place: ink-node.
As before, it functions as a simple local development node.
It contains pallet-revive in a default configuration.
You can find binary releases of the node here.

Changed

Restrict which cfg attributes can be used ‒ #2313
More idiomatic return types for metadata getters - #2398
Define static distributed events slice in ink crate - #2487

Added

Support for caller_is_root - #2332
Allow setting features for contract build in E2E tests - #2460
Improve support for Solidity ABI calling conventions - #2411
Implement contract invocation in off-chain environment engine - #1957
Abstractions for mapping arbitrary Rust types to Solidity ABI compatible types - #2441
Documentation for contract abi arg and provided Rust/ink! to Solidity type mappings - 2463
Implement SolDecode, SolTypeDecode and support SolBytes for boxed slices - ...

Fixed

[E2E] Have port parsing handle comma-separated list ‒ #2336

This is the first ink! release outside of Parity. ink! was started at Parity and during this year became a community project maintained by the ink! Alliance, a loose group of former Parity employees and teams who want ink! to ensure a bright future for ink!.

You can find more details about the community handover in this X post. Generally, the only thing changing on the user-facing side is that the repositories have been moved from paritytech to the new GitHub organization use-ink.

❣ We want to say a big thank you to our Polkadot community, which recently decided on funding the continued maintenance and development of ink! with a Polkadot Treasury grant.

Highlights

This version of ink! comes with three highlights plus some minor fixes.

(1) XCM Support

ink! 5.1 supports the usage of XCM in contracts, developers are no longer limited to cross-contract calls, but can now execute cross-parachain calls.

We added a contract example that demonstrates the usage: contract-xcm

We also added a new page on our documentation website: https://use.ink/basics/xcm.

You can view the Rust docs of the two functions here:

(2) Call an ink! contract from a `polkadot-sdk` runtime

ink! 5.1 comes with basic support for calling contracts from a Polkadot runtime. We've added this example that demonstrates how to call flipper from a polkadot-sdk runtime pallet.

Calling a contract from the runtime is an interesting application for parachains, as they can put logic into a contract instead of their runtime. Contracts have a number of advantages, as they are easier to upgrade and allow for faster development iteration cycles.

The limitations currently are:

Contract calls can only be made to trait messages. This makes sense in the pallet-contracts context, as it is better to depend on a trait rather than a contract impl, since you are working against an interface.
Only contract messages can be called currently, no constructors.
The API could be nicer.

(3) E2E Testing

We replaced our drink sandbox dependency with an internal ink! crate. In case you use DRink!:

First, you should upgrade your drink dependency to version = "0.18.0". Second, these are the two changes you have to make:

- #[ink_e2e::test(backend(runtime_only(sandbox = ink_e2e::MinimalSandbox)))]
+ #[ink_e2e::test(backend(runtime_only(sandbox = ink_e2e::DefaultSandbox)))]

- ink_e2e = { version = "5", features = ["drink"] }
+ ink_e2e = { version = "5", features = ["sandbox"] }

Compatibility

The compatibility changes a bit to ink! 5.0:

Rust: >= 1.81
cargo-contract: >= 5.0.0
polkadot-sdk: >= v1.12.0
(this release stabilized the pallet-contracts XCM functions that ink! uses)
substrate-contracts-node: >= 0.42.0
DRink!: >= 0.18.0
For the linter in cargo-contract the Rust toolchain version changed.
To upgrade:

export TOOLCHAIN_VERSION=nightly-2024-09-05
rustup install $TOOLCHAIN_VERSION
rustup component add rust-src --toolchain $TOOLCHAIN_VERSION
rustup run $TOOLCHAIN_VERSION cargo install cargo-dylint dylint-link

Added

[Runtime-to-Contract Calls] Environment agnostic contract invocation API, for calling contracts from runtime ‒ #2219
[Runtime-to-Contract Calls] Add no-panic-handler feature ‒ #2164
[Runtime-to-Contract Calls] Add example for calling a contract from a runtime pallet ‒ #2189
[XCM] Add xcm_execute and xcm_send support ‒ #1912
[Linter] Add links to detailed lint description ‒ #2170
[E2E] Adds a message to SandboxErr to add context for easier debugging ‒ #2218
[E2E] Add ability to take and restore snapshots ‒ #2261 (thanks @0xLucca!)
[E2E] Demonstrate usage of seeds for secret URIs in E2E test for chain snapshots ‒ #2163

Changed

Update repository URLs & references from paritytech GitHub organization to new use-ink one ‒ #2220 and #2248
[E2E] Update subxt and polkadot-sdk dependencies ‒ #2174
[Drink backend] Replace drink sandbox with internal ink_sandbox ‒ #2158

Fixed

[XCM] Fix XCM-support to single encode the XCM message ‒ #2278
[Examples] ERC-721: burn() clears token approval ‒ #2099
[E2E] Fix outdated docs for [ink_e2e::test] ‒ #2162
[E2E] Build contracts before initializing node rpc ‒ #2168
[E2E] set_account_balance now can't set balance below existential deposit ‒ #1983 (thanks @0xLucca!)
[E2E] Fix outdated docs for [ink_e2e::test] ‒ #2162

ℹ️ We have created a migration guide from ink! 4 to ink! 5. It also contains an overview over all breaking changes and newly added features.
You can view it here.

Summary

This release addresses the rest of the severities described in the OpenZeppelin security review of ink! and cargo-contract.
One of the notable addressed issues is the proxy selector clashing attack.
As of this release, ink! only allows exactly one other message with a well-known reserved selector to be defined.
You can read more about the change in the #1827 and #2031.

ink! 5.0.0 features a significant number of new features:

We have introduced a new API based on the calculated or specified selectors for the event definition. This allows events to be defined in separate files and modules, and be shared across multiple ink! contracts - #1827 and #2031.
@pmikolajczyk41 has introduced an alternative E2E testing framework, DRink!, that support quasi-testing model, it allows the test simulate a running node as part of the E2E test while improving debugging experience such as allowing to set breakpoint and step through each stage of execution cycle.
Following improvements in E2E, we have added a call builder API that allows to easily build calls while significantly reducing boilerplate code - #1917 and #2075
Another notable introduction in 5.0.0 release is the support for multiple chain extensions that empower developers
to build even more sophisticated and advanced contracts for supported chains - #1958.
To further address our consideration of the intrinsic security of ink! smart contracts,
we have disallowed unchecked arithmetic expressions. cargo-contract will fail to compile the contract with the raw arithmetic operation - #1831.

These are the main features we have introduced in this release. We also encourage developers
to have a look at more detailed changelog entries to find out about any breaking changes that may affect
the development of new ink! contracts.

Compatibility

See the compatibility section of our migration guide for a detailed description. On a high level:

Rust: >= 1.70
cargo-contract: >= 4.0.0
polkadot-sdk: >= 0.9.3. But if using the new functions introduced in #2123 and #2077 >= 1.8.0 and if using the new functions introduced in #2076 >= 1.9.0.
polkadot-js/api and polkadot-js/api-contract: >= 10.12.1
substrate-contracts-node: >= 0.39.0

Changelog

Added

Add Hash trait to Selector struct - #2149
instantiate_v2 with additional limit parameters #2123
Custom signature topic in Events - #2031
[Linter] non_fallible_api lint - #2004
[Linter] Publish the linting crates on crates.io - #2060
[E2E] Added create_call_builder for testing existing contracts - #2075
call_v2 cross-contract calls with additional limit parameters - #2077
delegate_dependency api calls - #2076
Allow mutable parameters in messages - #2004
Clean E2E configuration parsing - #1922
Make set_code_hash generic - #1906
Provide a StorageVec datastructure built on top of Lazy - #1995
Add fallible methods for Mapping and Lazy - #1910
[E2E] Allow testing with live-chain state - #1949
[E2E] Call builders and extra gas margin option - #1917
[Linter] storage_never_freed lint - #1932
[Linter] strict_balance_equality lint - #1914
[Linter] no_main lint - #2001
Reexport scale dependencies, introduce #[ink::scale_derive] - #1890
Upgradeable contracts example - #1889
Persist static buffer size in metadata - #1880
Modify static buffer size via environmental variables - #1869
Added sr25519_verify function to ink_env #1840
Events 2.0 - #1827
Add set_block_number to off-chain test api Engine - #1806
Stabilize call_runtime ‒ #1749
Schema generation - #1765
Restrict wildcard selectors to have exactly one other message - #1708
[Linter] Warn when primitive number is annotated as event topic - #1837
[Drink backend] allow for arbitrary runtime - #1892
[Drink backend] support runtime call - #1891
[Drink backend] Make tests generic E2EBackend trait - #1867
[Drink backend] Backend choice ‒ #1864
[Drink backend] Backend traits - #1857
[Drink backend] Abstract error and result structs - #1844

Changed

Use name-only syntax for anonymous ink! event item configuration argument - #2140
Restrict syntax for setting default ink! e2e test runtime-only emulator - #2143
Restrict syntax for setting ink! e2e test node to auto - #2146
Bump Substrate crates - #2141
Minor fixes - #2144,
#2137, #2132
Bump metadata version to 5 #2126
Use MaxEncodedLen for output buffer size #2128
Mapping: Reflect all possible failure cases in comments ‒ #2079
[E2E] Rename .call to .call_builder ‒ #2078
Improve syntax for ink! e2e runtime_only attribute argument - #2083
[E2E] Remove additional_contracts parameter #2098
[E2E] change node url backend config - #2101
Messages return TypeSpec directly - #1999
Fail when decoding from storage and not all bytes consumed - #1897
Support multiple chain extensions - #1958
- New example of how to use multiple chain extensions in one contract.
- Affects the usage of the #[ink::chain_extension] macro and the definition of the chain extension.
Split up ink_linting to mandatory and extra libraries - #2032
[E2E] resolve DispatchError error details for dry-runs - #1994
[E2E] update to new drink API - #2005
Reexport scale dependencies, introduce #[ink::scale_derive] ‒ #1890
Use of workspace dependencies and properties - #1835
Remove of unchecked arithmetic - #1831
Use decode_all for decoding cross contract call result - #1810
[E2E] build contracts at runtime instead of during codegen - #1881
[E2E] crate refactoring - #1830
[E2E] improve call API, remove build_message + callback - #1782

Fixed

Fix alignment in allocator [#2100](...

Changed

Use name-only syntax for anonymous ink! event item configuration argument - #2140
Restrict syntax for setting default ink! e2e test runtime-only emulator - #2143
Bump Substrate crates - #2141
Minor fixes - #2144,
#2137, #2132

Added

instantiate_v2 with additional limit parameters #2123

Changed

Bump metadata version to 5 #2126
Use MaxEncodedLen for output buffer size #2128

Fixed

Fix alignment in allocator #2100

Added

Custom signature topic in Events - #2031
[Linter] non_fallible_api lint - #2004
[Linter] Publish the linting crates on crates.io - #2060
[E2E] Added create_call_builder for testing existing contracts - #2075
call_v2 cross-contract calls with additional limit parameters - #2077

Changed

Mapping: Reflect all possible failure cases in comments ‒ #2079
[E2E] Rename .call to .call_builder ‒ #2078
Improve syntax for ink! e2e runtime_only attribute argument - #2083
[E2E] Remove additional_contracts parameter #2098
[E2E] change node url backend config - #2101

Fixed

Fix the StorageVec type by excluding the len_cached field from its type info - #2052
Fix panic in approve_for in the ERC-721 example - #2092
ERC-721: transfer_token_from now ensures the token owner is correct - #2093

This is a release candidate for ink! 5.0. Notable changes include:

Support for multiple chain extensions - #1958. This is a breaking change. Developers need to update their code utilising new API.
Lazy StorageVec structure that allows access vector data efficiently - #1995
E2E framework introduced a new builder API to simplify the call building - #1917

Added

Allow mutable parameters in messages - #2004
[E2E] Allow testing with live-chain state - #1949
[E2E] Call builders and extra gas margin option - #1917
Linter: storage_never_freed lint - #1932
Linter: strict_balance_equality lint - #1914
Linter: no_main lint - #2001
Clean E2E configuration parsing - #1922
Make set_code_hash generic - #1906
Provide a StorageVec datastructure built on top of Lazy - #1995

Changed

Messages return TypeSpec directly - #1999
Fail when decoding from storage and not all bytes consumed - #1897
[E2E] resolve DispatchError error details for dry-runs - #1944
[E2E] update to new drink API - #2005
Support multiple chain extensions - #1958
- New example of how to use multiple chain extensions in one contract.
- Affects the usage of the #[ink::chain_extension] macro and the definition of the chain extension.

@pmikolajczyk41

The preview release of the ink! 5.0.0 release.
This release addresses the majority of issues raised in the OpenZeppelin audit
in particular, we addressed the proxy selector clashing attack.
As of this release, ink! only allows exactly one other message with a well-known reserved selector to be defined.
You can read more about the change in the PR

There are also other notable changes:

Rework of event definitions - #1827.
Updated upgradeable contract example illustrating delegate_call
Removal of unchecked arithmetic. cargo-contract will fail compiling the contract with raw arithmetic operations.
Introduction of an alternative off-chain E2E testing backend, drink!
Big thanks to @pmikolajczyk41 for this massive contribution!

You can see a more detailed log of changes below:

Added

[Drink backend]: allow for arbitrary runtime - #1892
[Drink backend]: support runtime call - #1891
Reexport scale dependencies, introduce #[ink::scale_derive] - #1890
Upgradeable contracts example - #1889
Persist static buffer size in metadata - #1880
Modify static buffer size via environmental variables - #1869
[Drink backend]: Make tests generic E2EBackend trait - #1867
[Drink backend]: Backend choice ‒ #1864
[Drink backend]: Backend traits - #1857
[Drink backend]: Abstract error and result structs - #1844
Added sr25519_verify function to ink_env #1840
Warn when primitive number is annotated as event topic - #1837
Events 2.0 - #1827
Add set_block_number to off-chain test api Engine - #1806
Stabilize call_runtime ‒ #1749
Schema generation - #1765
Restrict wildcard selectors to have exactly one other message - #1708

Changed

Reexport scale dependencies, introduce #[ink::scale_derive] ‒ #1890
[ink_e2e] build contracts at runtime instead of during codegen - #1881
Use of workspace dependencies and properties - #1835
Remove of unchecked arithmetic - #1831
E2E crate refactoring - #1830
Use `decode_all`` for decoding cross contract call result - #1810
E2E: improve call API, remove build_message + callback - #1782

Version 4.3.0

This release is to fix compatibility of ink_e2e with newer (> 1.69) versions of Rust,
which produce signext instructions, and older versions of pallet_contracts which do
not yet support these instructions.

Backport use of contract-build to 3.2.0 to include signext lowering, and update
subxt to remove incompatible wasmi-instrument transient dependency ‒ #1884

Releases: use-ink/ink

v6.0.0-alpha

Cross-contract calling Solidity contracts

Types

Contract Balance: U256

Contract Address: Address / H160

Contract Hash: H256

Contract delegates can no longer be done by code

Feature ink/unstable-hostfn

New debugging workflow

Restrictions which cfg attributes can be used

Metadata Changes

no_main

substrate-contracts-node can no longer be used

Changed

Added

Uh oh!

v5.1.1

Fixed

Uh oh!

v5.1.0

Highlights

(1) XCM Support

(2) Call an ink! contract from a polkadot-sdk runtime

(3) E2E Testing

Compatibility

Added

Changed

Fixed

Uh oh!

v5.0.0

Summary

Compatibility

Changelog

Added

Changed

Fixed

Uh oh!

v5.0.0-rc.3

Changed

Uh oh!

v5.0.0-rc.2

Added

Changed

Fixed

Uh oh!

v5.0.0-rc.1

Added

Changed

Fixed

Uh oh!

v5.0.0-rc

Added

Changed

Uh oh!

v5.0.0-alpha

Added

Changed

Contributors

Uh oh!

v4.3.0

Version 4.3.0

Uh oh!

Contract Balance: `U256`

Contract Address: `Address` / `H160`

Contract Hash: `H256`

Feature `ink/unstable-hostfn`

Restrictions which `cfg` attributes can be used

`no_main`

`substrate-contracts-node` can no longer be used

(2) Call an ink! contract from a `polkadot-sdk` runtime