ink! vs. Solidity
Here is a brief comparison of features between ink! and Solidity:
ink! | Solidity | |
---|---|---|
Virtual Machine | Any Wasm VM | EVM |
Encoding | Wasm | EVM Byte Code |
Language | Rust | Standalone |
Overflow Protection | Enabled by default | Yes |
Constructor Functions | Multiple | Single |
Tooling | Anything that supports Rust | Custom |
Versioning | Semantic | Semantic |
Has Metadata? | Yes | Yes |
Multi-File Project | Planned | Yes |
Storage Entries | Variable | 256 bits |
Supported Types | Docs | Docs |
Has Interfaces? | Yes (Rust Traits) | Yes |
Solidity to ink! Guide
Table of Contents
- Solidity to ink! Guide
- Table of Contents
- Converting a Solidity Contract to ink!
- Best Practices + Tips
- Syntax Equivalencies
public function
mapping declaration
mapping usage
struct
assertions / requires
timestamp
contract caller
contract's address
bytes
uint256
payable
received deposit / payment
contract balance
transfer tokens from contract
events & indexed
errors and returning
nested mappings + custom / advanced structures
cross-contract calling
submit generic transaction / dynamic cross-contract calling
- Limitations of ink! v3
- Troubleshooting Errors
- unit testing (off-chain)
Converting a Solidity Contract to ink!
1. Generate New ink! Contract
Run the following to generate ink! boilerplate code for ink!'s "Hello, World!" (the flipper
contract))
cargo contract new <contract-name>
2. Build ink! Contract
cargo +nightly contract build
3. Convert Solidity class fields to Rust struct
Solidity is an object oriented language, and uses classes. ink! (Rust) does not use classes.
An example Solidity class looks like:
contract MyContract {
bool private _theBool;
event UpdatedBool(bool indexed _theBool);
constructor(bool theBool_) {
require(theBool_ == true, "theBool_ must start as true");
_theBool = theBool_;
}
function setBool(bool newBool) public returns (bool boolChanged) {
if _theBool == newBool{
boolChanged = false;
}else{
boolChanged = true;
}
_theBool = newBool;
//emit event
UpdatedBool(newBool);
}
}
And the equivalent contract in ink! looks like:
#![cfg_attr(not(feature = "std"), no_std)]
use ink_lang as ink;
#[ink::contract]
mod mycontract {
#[ink(storage)]
pub struct MyContract {
the_bool: bool, //class members become struct fields
}
#[ink(event)]
pub struct UpdatedBool {
#[ink(topic)] //-> indexed
the_bool: bool,
}
impl MyContract {
#[ink(constructor)]
pub fn new(the_bool: bool) -> Self {
assert!(the_bool == true, "the_bool must start as true");
Self { the_bool }
}
#[ink(message)] //functions become struct implementations
pub fn set_bool(&mut self, new_bool: bool) -> bool{
let bool_changed = true;
if self.the_bool == new_bool{
bool_changed = false;
}else{
bool_changed = true;
}
self.the_bool = new_bool;
self.env().emit_event(UpdatedBool {
the_bool: new_bool
});
//return
bool_changed
}
}
}
A few key differences are:
- Solidity class variables / members will be placed in the contract struct in ink!
- All class methods in Solidity are
impl
emented for the contract struct in ink! - Solidity frequently prefixes variables with an underscore (
_name
). ink! / Rust only prefixes with an underscore for unused variables. - Solidity uses camelCase. ink! uses snake_case.
- In Solidity, the variable type comes before the variable name (e.g. bool myVar). While ink! specifies var type after the var name (e.g. my_var: bool)
4. Convert each function
-
Start converting each function one by one.
- A recommended approach is to, if possible, skip cross-contract calls at first and use mock data instead
- This way offchain unit tests can be written to test the core functionality
- unit tests are offchain and do not work with cross-contract calls
- Once fully tested, start adding in cross-contract calls and perform on-chain manual + integration tests
-
Ensure that function's visibility (public, private) are matched in ink!
-
In Solidity, if a function returns a
bool success
, ink! will use aResult<()>
instead (Result::Ok
orResult::Err
).// ink!
//result type
pub type Result<T> = core::result::Result<T, Error>;
// ...
//public function that returns a Result
#[ink(message)]
pub fn my_function(&self) -> Result<()>{
Ok(())
}
Best Practices + Tips
- If the Solidity contract uses a
string
, it is recommended to use aVec<u8>
to avoid the overhead of aString
. See here for more details on why. The smart contract should only contain the information that strictly needs to be placed on the blockchain and go through consensus. The UI should be used for displaying strings. - Double check all
.unwrap()
s performed. Solidity does not have as strict checking as ink! does. For example, a mapping field can be accessed as simple asmyMapping[someKey]
. ink!, however, requiresself.my_mapping.get(some_key).unwrap()
. A useful way to handleNone
cases is to use.unwrap_or(some_val)
. - Run the contracts node with
substrate-contracts-node --dev -lerror,runtime::contracts=debug
for debug prints, and errors to be displayed in the nodes console. - When passing parameters to a helper, it is recommended to pass references (even for primitives) as Wasm is more efficient with references. For example (see erc20 example):
/// Returns the account balance for the specified `owner`.
///
/// Returns `0` if the account is non-existent.
#[ink(message)]
pub fn balance_of(&self, owner: AccountId) -> Balance {
self.balance_of_impl(&owner)
}
/// Returns the account balance for the specified `owner`.
///
/// Returns `0` if the account is non-existent.
///
/// # Note
///
/// Prefer to call this method over `balance_of` since this
/// works using references which are more efficient in Wasm.
#[inline]
fn balance_of_impl(&self, owner: &AccountId) -> Balance {
self.balances.get(owner).unwrap_or_default()
}
- Just as in Solidity, ink! does not have floating point numbers due to the non-deterministic nature. Instead, the frontend should add decimal points as needed.
Syntax Equivalencies
public function
// solidity
function fnName() public {}
//or
//by default, functions are public
function fnName() {}
// ink!
#[ink(message)]
pub fn fn_name(&self) {}
mapping declaration
// solidity
mapping(address => uint128) private mapName;
//ink!
use ink_storage::{
traits::SpreadAllocate,
Mapping,
};
#[ink(storage)]
#[derive(SpreadAllocate)]
pub struct ContractName {
map_name: Mapping<AccountId, u128>,
}
when using a map in ink!, ink_lang::utils::initialize_contract
must be used in the constructor. See here for more details.
mapping usage
// solidity
//insert / update
aMap[aKey] = aValue;
// get
aMap[aKey]
// ink!
//insert / update
self.a_map.insert(&a_key, &a_value);
// get
self.a_map.get(a_key).unwrap()
struct
// solidity
struct MyPerson{
address person;
u64 favNum;
}
// ink!
struct MyPerson {
person: AccountId,
fav_num: u64,
}
assertions / requires
// solidity
require(someValue < 10, "someValue is not less than 10");
// ink!
assert!(some_value < 10, "some_value is not less than 10");
timestamp
// solidity
block.timestamp
// or
now
// ink!
self.env().block_timestamp()
contract caller
// solidity
address caller = msg.sender;
// ink!
let caller: AccountId = self.env().caller();
contract's address
// solidity
address(this)
// ink!
self.env().account_id()
bytes
Solidity has a type bytes
. bytes
is (essentially) equivalent to an array of uint8. So, bytes
in Solidity => Vec<u8>
or [u8; ...]
in ink!. See here for more details. If desired, a bytes
struct can be created in ink! to replicate the bytes
type in Solidity.
uint256
Solidity uses uint256
and uint
to represent a 256-bit type.
Solidity is 256-bit / 32-byte word optimized. Meaning, using uint256
in Solidity contracts will reduce gas usage -- but increase storage usage. The largest size ink! has built in is a u128
. ink! compiles to Wasm. The largest primitive Wasm has is 64bit (due to most computers using 64bit). So, there is no benefit to using any larger primitive over a collection.
When porting a uint256
from Solidity to ink!, it is recommended to, with discretion, determine the range of the value, and choose the appropriate size (u8, u16, u32, u64, u128). If a 256-bit hash value is required, ink! has a Hash
primitive available. In the event a value needs to be 256-bit, it is recommended to use an array (e.g. [u64; 4]
).
payable
// solidity
function myFunction() payable returns (uint64) {}
#[ink(message, payable)]
pub fn my_function() -> (u64) {}
received deposit / payment
// solidity
msg.value
// ink!
self.env().transferred_value()
contract balance
// solidity
this.balance
// ink!
self.env().balance()
transfer tokens from contract
// solidity
recipient.send(amount)
//ink!
if self.env().transfer(recipient, amount).is_err() {
panic!("error transferring")
}
events & indexed
// solidity
event MyCoolEvent(
u128 indexed indexedValue,
u128 notIndexedValue,
);
//emit event
MyCoolEvent (someValue, someOtherValue)
// ink!
#[ink(event)]
pub struct MyCoolEvent {
#[ink(topic)]
indexed_value: u128,
not_indexed_value: u128,
}
// emit event
self.env().emit_event(MyCoolEvent {
indexed_value: some_value,
not_indexed_value: some_other_value
});
errors and returning
Solidity has several error handling mechanisms: assert
, require
, revert
, and throw
. Each of these will revert the changed state when called. See this article for details on these.
ink! uses a Result
enum (Ok(T)
, Err(E)
), assert!
and panic!
. This Stack Exchange answer and GitHub discussion provide more details on these.
throw
Throw is deprecated in Solidity and would throw an invalid opcode error (no details) and revert the state. As an alternative to the if...{throw;}
pattern in Solidity, a Result::Err
should be returned for expected errors, and an assert!
should be used for errors that should not occur.
assert
In Solidity, assert
is used as internal guards against errors in the code. In general, properly functioning code should never hit a failing assert. assert
in Solidity does not have error strings. In ink!, use assert!
. assert!
will panic!
if it evaluates to false. The state will be reverted, and a CalleeTrapped
will be returned. The (optional) error string will be printed to the debug buffer.
// ink!
assert!(caller == owner, "caller is not owner")
require and revert
In Solidity, require
is used for general (normal) errors -- such as errors that occur based on user input. require
does have the option for an error string. revert
is very similar to require
except that revert
will be called in if ... else
chains. Both require
and revert
will revert the chain state. In ink!, if ... { return Err(Error::SomeError) }
should be used for require
or revert
. When a Result::Err
is returned in ink!, then all state is reverted.
In general, Result::Err
should be used when a calling contract needs to know why a function failed. Otherwise, assert!
should be used as it has less overhead than a Result
.
// Solidity
function myFunction(bool returnError) public {
require(!returnError, "my error here");
//or
if returnError {
revert("my error here");
}
}
//ink!
#[derive(Debug, PartialEq, Eq, scale::Encode, scale::Decode)]
#[cfg_attr(feature = "std", derive(scale_info::TypeInfo))]
pub enum Error {
/// Provide a detailed comment on the error
MyError,
}
// result type
pub type Result<T> = core::result::Result<T, Error>;
// ...
#[ink(message)]
pub fn my_function(&self, return_error: bool) -> Result<()> {
if return_error{
return Err(Error::MyError)
}
Ok(())
}
nested mappings + custom / advanced structures
In Solidity, it is easy to do nested mappings. It is not as straightforward in ink!.
imagine the following scenario
// solidity
contract Dao {
struct Proposal {
mapping (address => bool) votedYes
}
mapping (address => bool) public isWhitelisted;
Proposal[] public proposals;
}
in ink! this seems like it could be represented like so:
#[ink::contract]
mod dao {
#[derive(SpreadAllocate)]
pub struct Proposal {
voted_yes: Mapping<AccountId, bool>,
}
#[ink(storage)]
#[derive(SpreadAllocate)]
pub struct Dao {
proposals: Vec<Proposal>,
is_whitelisted: Mapping<AccountId, bool>,
}
impl Dao{
#[ink(constructor)]
pub fn new(/*...*/) -> Self {
//required for mappings
ink_lang::utils::initialize_contract(|contract| {/*...*/})
}
}
}
However, this will cause an error due to the nested mapping. This answer explains in detail why nested mappings are not allowed
So, as of now, to get around this issue an alternate data structure will need to be used. A data-structure that can be interchanged with the Mapping
syntax and with minimal additional implementations is the BTreeMap
. BTreeMap
is less efficient than Mapping
, but is an easy workaround until nested mappings are allowed. This will be used in the nested struct. Additional derive
s will need to be added to be compatible with the #[ink(storage)] struct (see below).
#[ink::contract]
mod dao {
use ink_prelude::collections::BTreeMap;
#[derive(
scale::Encode,
scale::Decode,
SpreadLayout,
PackedLayout,
SpreadAllocate,
)]
#[cfg_attr(
feature = "std",
derive(scale_info::TypeInfo, ink_storage::traits::StorageLayout)
)]
pub struct Proposal {
voted_yes: BTreeMap<AccountId, bool>,
}
#[ink(storage)]
#[derive(SpreadAllocate)]
pub struct Dao {
proposals: Vec<Proposal>,
is_whitelisted: Mapping<AccountId, bool>,
}
impl Dao{
#[ink(constructor)]
pub fn new(/*...*/) -> Self {
//required for mappings
ink_lang::utils::initialize_contract(|contract| {/*...*/})
}
}
}
This almost works as expected. However, there is still one issue. SpreadAllocate
(used with Mapping
) requires that Vec<Proposal>
implements PackedAllocate
. To fix this, Proposal
needs to implement PackedAllocate
. See here for details + examples. See the following for this example:
use ink_primitives::Key;
pub struct Proposal {
voted_yes: BTreeMap<AccountId, bool>,
}
impl ink_storage::traits::PackedAllocate for Proposal {
fn allocate_packed(&mut self, at: &Key){
PackedAllocate::allocate_packed(&mut *self, at)
}
}
cross-contract calling
In ink!, to do cross-contract calling, the contract will need to be added to the project. Ensure the contract is properly exporting its Structs. See the erc20
contract example:
#![cfg_attr(not(feature = "std"), no_std)]
use ink_lang as ink;
//make the structs visible
pub use self::erc20::{
Erc20,
//this is necessary
Erc20Ref,
};
#[ink::contract]
pub mod erc20 {}
In the new cross-called contract's Cargo.toml, add (or edit) the following:
[lib]
name = "erc20"
path = "lib.rs"
crate-type = [
# Used for normal contract Wasm blobs.
"cdylib",
# Used for ABI generation. Necessary for importing as a dependency
"rlib",
]
[features]
ink-as-dependency = []
ink-as-dependency
"tells the ink! code generator to always or never compile the smart contract as if it was used as a dependency of another ink! smart contract" (source).
Then, In the main contract's Cargo.toml, import the contract that will be cross-called.
erc20 = { path = "erc20", default-features = false, features = ["ink-as-dependency"] }
And make sure to add it to the std
field of the .toml file.
[features]
default = ["std"]
std = [
# ...
"erc20/std",
]
Now, import the cross-called-contract to the main contract:
// example
use erc20::Erc20Ref;
There are two methods to setup the other contract.
-
Instantiate the cross-called-contract in the main contract's constructor. See here for a tutorial, and here for an example.
-
Or, add the
AccountId
of an already deployed contract. Here is an example constructor to set this up:use my_other_contract::MyOtherContractRef;
// ...
fn new(contract_id: AccountId) -> Self {
//for already deployed contract
let contract_ref: MyOtherContractRef = ink_env::call::FromAccountId::from_account_id(contract_id);
Self {contract_ref}
}
Now, to perform the cross-contract call:
{
self.contract_ref.some_external_function(a_param);
}
Note: as of now (ink! v3.3.1), when using cross-contract calls, emitting events will not work and compile errors will occur. See issue #1000. Furthermore, the compiler will throw an error saying that (for example) Erc20Ref does not implement SpreadAllocate
. This issue #1149 explains more and has a workaround. These issues will be fixed in issue #1134.
submit generic transaction / dynamic cross-contract calling
// solidity
// invokes function found at`addr`, sends the `_amount` to the `addr`, and the `_transactionData` payload.
addr.call.value(_amount)(_transactionData)
// ink!
// ...
use ink_env::call::{
build_call,
Call,
ExecutionInput,
Selector,
};
/// A wrapper that allows us to encode a blob of bytes.
///
/// We use this to pass the set of untyped (bytes) parameters to the `CallBuilder`.
struct CallInput<'a>(&'a [u8]);
impl<'a> scale::Encode for CallInput<'a> {
fn encode_to<T: Output + ?Sized>(&self, dest: &mut T) {
dest.write(self.0);
}
}
// ...
// see: https://github.com/paritytech/ink-examples/blob/main/multisig/lib.rs#L535
fn invoke_transaction(
&mut self,
callee: AccountId,
transfer_amount: u128,
function_selector: [u8; 4],
transaction_data: Vec<u8>,
gas_limit: u64) -> Result<()> {
let result = build_call::<<Self as ::ink_lang::reflect::ContractEnv>::Env>()
.call_type(
Call::new()
.callee(callee) //contract to call
.gas_limit(*gas_limit)
.transferred_value(transfer_amount), //value to transfer with call
)
.exec_input(
ExecutionInput::new(Selector::from(*function_selector)).push_arg(CallInput(transaction_data)), //SCALE encoded parameters
)
.returns::<()>()
.fire()
.map_err(|_| Error::TransactionFailed);
result
}
Note: the function_selector
bytes can be found in the generated target/ink/metadata.json
Limitations of ink! v3
- Multi-file projects are not supported with pure ink!
- implementing traits / interfaces will not work
- There are alternatives that do add this functionality such as OpenBrush
- Nested structs and data structures can be difficult to use
- Cross-contract calling prevents events from being emitted. See here for details.
- Cross-contract calling can not be tested offchain with unit tests. On-chain integration tests will need to be used.
Troubleshooting Errors
ERROR: Validation of the Wasm failed.
ERROR: Validation of the Wasm failed.
ERROR: An unexpected panic function import was found in the contract Wasm.
This typically goes back to a known bug in the Rust compiler:
https://github.com/rust-lang/rust/issues/78744
As a workaround try to insert `overflow-checks = false` into your `Cargo.toml`.
This will disable safe math operations, but unfortunately we are currently not
aware of a better workaround until the bug in the compiler is fixed.
Solution Add the following to the contract Cargo.toml:
[profile.release]
overflow-checks = false
"failed to load bitcode of module '...' "
This happens when trying to import a contract for cross-contract calling.
Solution Ensure that the following is added to Cargo.toml contract import:`
features = ["ink-as-dependency"]
so the import would look like:
mycontract = { path = "mycontract/", default-features = false, features = ["ink-as-dependency"]}
unit testing (off-chain)
- Unit tests are an integral part of smart-contract development and ensuring your code works off-chain before testing on-chain.
- To run ink! tests, do not use
cargo +nightly contract test
. Usecargo +nightly test
. Add the--nocapture
flag for debug prints to show. See here for more info why. - From the contract module, make sure to make the contract struct and anything else that is going to be used in the unit tests public. For example:
// top of file
#![cfg_attr(not(feature = "std"), no_std)]
use ink_lang as ink;
pub use self::mycontract::{
MyContract
};
- Off-chain unit tests will not work with cross-contract calls. One workaround to ensure unit tests are still passing is to provide mock data.
An easy approach is to use conditional compiling with #[cfg(test)]
and #[cfg(not(test))]
.
Note: this solution is not ideal. ink! v4.0 will provide much better solutions.
For example, here is a read-only ERC20 cross-contract call:
//only compiles when *not* running tests
#[cfg(not(test))]
fn get_token_balance(&self, caller: &AccountId) -> Balance {
//calls the external ERC-20 contract
self.token.balance_of(*caller)
}
//only compiles when running tests
#[cfg(test)]
fn get_token_balance(&self, _: &AccountId) -> Balance {
//arbitrary value
1
}
And if the cross-contract call writes to storage, a mock field can be added to the contract struct. For example:
#[ink(storage)]
pub struct MyContract {
#[cfg(test)]
mock_field: SomeStruct, // will serve as a fake storage
}
...
//on-chain, performs cross-contract call
#[cfg(not(test))]
fn do_some_write(&mut self) {
self.external_contract.write_to_field(0xDEADBEEF);
}
//testing environment only
#[cfg(test)]
fn do_some_write(&mut self) {
self.mock_field.my_fake_storage_item = 0xDEADBEEF;
}
- useful code to interact and modify the contract environment for testing
// get the default accounts (alice, bob, ...)
let accounts = ink_env::test::default_accounts::<ink_env::DefaultEnvironment>();
accounts.alice //usage example
// set which account calls the contract
ink_env::test::set_caller::<ink_env::DefaultEnvironment>(accounts.bob);
//get the contract's address
let callee = ink_env::account_id::<ink_env::DefaultEnvironment>();
// set the contracts address.
// by default, this is alice's account
ink_env::test::set_callee::<ink_env::DefaultEnvironment>(callee);
// transfer native currency to the contract
ink_env::test::set_value_transferred::<ink_env::DefaultEnvironment>(2);
// increase block number (and block timestamp).
// this can be placed in a loop to advance the block many times
ink_env::test::advance_block::<ink_env::DefaultEnvironment>();
//generate arbitrary AccountId
AccountId::from([0x01; 32]);
//generate arbitrary Hash
Hash::from([0x01; 32])
//macro for tests that are expected to panic.
#[should_panic]