Contracts

Constructors and contract instantiation

When a contract is deployed, the contract storage is initialized to the initializer values provided, and any constructor is called. A constructor is not required for a contract. A constructor is defined like so:

contract flipper {
        bool private value;

        /// Constructor that initializes the `bool` value to the given `init_value`.
        constructor(bool initvalue) {
                value = initvalue;
        }

        /// A message that can be called on instantiated contracts.
        /// This one flips the value of the stored `bool` from `true`
        /// to `false` and vice versa.
        function flip() public {
                value = !value;
        }

        /// Simply returns the current value of our `bool`.
        function get() public view returns (bool) {
                return value;
        }
}

A constructor can have any number of arguments. If a constructor has arguments, they must be supplied when the contract is deployed.

If a contract is expected to receive value on instantiation, the constructor should be declared payable.

Note

Solang allows naming constructors in the Substrate target:

abstract contract Foo {
    constructor my_new_foo() {}
}

Constructors without a name will be called new in the metadata.

Note that constructor names are only used in the generated metadata. For contract instantiation, the correct constructor matching the function signature will be selected automatically.

Instantiation using new

Contracts can be created using the new keyword. The contract that is being created might have constructor arguments, which need to be provided.

contract hatchling {
    string name;
    address private origin;

    constructor(string id, address parent) {
        require(id != "", "name must be provided");
        name = id;
        origin = parent;
    }

    function root() public returns (address) {
        return origin;
    }
}

contract adult {
    function test() public {
        hatchling h = new hatchling("luna", address(this));
    }
}

On Solana, the contract being created must have the @program_id() annotation, and the address of the new account must be specified using the {address: new_address} syntax.

contract hatchling {
    string name;
    address private origin;

    constructor(string id, address parent) {
        require(id != "", "name must be provided");
        name = id;
        origin = parent;
    }

    function root() public returns (address) {
        return origin;
    }
}

contract adult {
    function test() public {
        hatchling h = new hatchling("luna", address(this));
    }
}

The constructor might fail for various reasons, for example require() might fail here. This can be handled using the Try Catch Statement statement, else errors cause the transaction to fail.

Note

On Solana, the Try Catch Statement statement is not supported, as any failure will cause the entire transaction to fail.

Sending value to the new contract

It is possible to send value to the new contract. This can be done with the {value: 500} syntax, like so:

contract hatchling {
    string name;
    address private origin;

    constructor(string id, address parent) payable {
        require(id != "", "name must be provided");
        name = id;
        origin = parent;
    }

    function root() public returns (address) {
        return origin;
    }
}

contract adult {
    function test() public {
        hatchling h = new hatchling{value: 500}("luna", address(this));
    }
}

The constructor should be declared payable for this to work.

Note

If no value is specified, then on Parity Substrate the minimum balance (also know as the existential deposit) is sent.

Note

On Solana, this functionality is not available.

Setting the salt, gas, and address for the new contract

Note

The gas or salt cannot be set on Solana. However, when creating a contract on Solana, the address of the new account must be set using address:.

When a new contract is created, the address for the new contract is a hash of the input (the constructor arguments) to the new contract. So, a contract cannot be created twice with the same input. This is why the salt is concatenated to the input. The salt is either a random value or it can be explicitly set using the {salt: 2} syntax. A constant will remove the need for the runtime random generation, however creating a contract twice with the same salt and arguments will fail. The salt is of type uint256.

If gas is specified, this limits the amount gas the constructor for the new contract can use. gas is a uint64.

contract hatchling {
    string name;
    address private origin;

    constructor(string id, address parent) {
        require(id != "", "name must be provided");
        name = id;
        origin = parent;
    }

    function root() public returns (address) {
        return origin;
    }
}

contract adult {
    function test() public {
        hatchling h = new hatchling{salt: 0, gas: 10000}("luna", address(this));
    }
}

Instantiating a contract on Solana

On Solana, contracts are deployed to a program account, which holds only the contract’s executable binary. When calling a constructor, one needs to provide an address that will serve as the contract’s data account, by using the call argument address:

@program_id("5kQ3iJ43gHNDjqmSAtE1vDu18CiSAfNbRe4v5uoobh3U")
contract hatchling {
    string name;

    constructor(string id) payable {
        require(id != "", "name must be provided");
        name = id;
    }
}

contract adult {
    function test(address addr) public {
        hatchling h = new hatchling{address: addr}("luna");
    }
}

Alternatively, the data account to be initialized can be provided using the accounts call argument. In this case, one needs to instantiate a fixed length array of type AccountMeta to pass to the call. The array must contain all the accounts the transaction is going to need, in addition to the data account to be initialized.

For the creation of a contract, the data account must the first element in such a vector and the system account 11111111111111111111111111111111 must also be present. If the constructor one is calling has the @payer annotation, the payer account should appear in the array as well. Moreover, the is_signer and is_writable bool flags need to be properly set, according to the following example:

import 'solana';

contract creator {
    Child public c;
    Child public c_metas;

    function create_with_metas(address data_account_to_initialize, address payer) public {
        AccountMeta[3] metas = [
            AccountMeta({
                pubkey: data_account_to_initialize,
                is_signer: true,
                is_writable: true}),
            AccountMeta({
                pubkey: payer,
                is_signer: true,
                is_writable: true}),
            AccountMeta({
                pubkey: address"11111111111111111111111111111111",
                is_writable: false,
                is_signer: false})
        ];

        c_metas = new Child{accounts: metas}(payer);

        c_metas.use_metas();
    }
}

@program_id("Chi1d5XD6nTAp2EyaNGqMxZzUjh6NvhXRxbGHP3D1RaT")
contract Child {
    @payer(payer)
    constructor(address payer) {
        print("In child constructor");
    }

    function use_metas() pure public {
        print("I am using metas");
    }
}

Base contracts, abstract contracts and interfaces

Solidity contracts support object-oriented programming. The style Solidity is somewhat similar to C++, but there are many differences. In Solidity we are dealing with contracts, not classes.

Specifying base contracts

To inherit from another contract, you have to specify it as a base contract. Multiple contracts can be specified here.

contract a is b, c {
    constructor() {}
}

contract b {
    int256 foo;

    function func2() public {}

    constructor() {}
}

contract c {
    int256 bar;

    constructor() {}

    function func1() public {}
}

In this case, contract a inherits from both b and c. Both func1() and func2() are visible in contract a, and will be part of its public interface if they are declared public or external. In addition, the contract storage variables foo and bar are also availabe in a.

Inheriting contracts is recursive; this means that if you inherit a contract, you also inherit everything that that contract inherits. In this example, contract a inherits b directly, and inherits c through b. This means that contract b also has a variable bar.

contract a is b {
    constructor() {}
}

contract b is c {
    int256 foo;

    function func2() public {}

    constructor() {}
}

contract c {
    int256 bar;

    constructor() {}

    function func1() public {}
}

Virtual Functions

When inheriting from a base contract, it is possible to override a function with a newer function with the same name. For this to be possible, the base contract must have specified the function as virtual. The inheriting contract must then specify the same function with the same name, arguments and return values, and add the override keyword.

contract a is b {
    function func(int256 a) public override returns (int256) {
        return a + 11;
    }
}

contract b {
    function func(int256 a) public virtual returns (int256) {
        return a + 10;
    }
}

If the function is present in more than one base contract, the override attribute must list all the base contracts it is overriding.

contract a is b, c {
    function func(int256 a) public override(b, c) returns (int256) {
        return a + 11;
    }
}

contract b {
    function func(int256 a) public virtual returns (int256) {
        return a + 10;
    }
}

contract c {
    function func(int256 a) public virtual returns (int256) {
        return a + 5;
    }
}

Calling function in base contract

When a virtual function is called, the dispatch is virtual. If the function being called is overriden in another contract, then the overriding function is called. For example:

contract b is a {
    function baz() public pure returns (uint64) {
        return foo();
    }

    function foo() internal pure override returns (uint64) {
        return 2;
    }
}

abstract contract a {
    function foo() internal virtual returns (uint64) {
        return 1;
    }

    function bar() internal returns (uint64) {
        // since foo() is virtual, is a virtual dispatch call
        // when foo is called and a is a base contract of b, then foo in contract b will
        // be called; foo will return 2.
        return foo();
    }

    function bar2() internal returns (uint64) {
        // this explicitly says "call foo of base contract a", and dispatch is not virtual
        return a.foo();
    }
}

Rather than specifying the base contract, use super as the contract to call the base contract function.

contract a is b {
    function baz() public returns (uint64) {
        // this will return 1
        return super.foo();
    }

    function foo() internal override returns (uint64) {
        return 2;
    }
}

abstract contract b {
    function foo() internal virtual returns (uint64) {
        return 1;
    }
}

If there are multiple base contracts which the define the same function, the function of the first base contract is called.

contract a is b1, b2 {
    function baz() public returns (uint64) {
        // this will return 100
        return super.foo();
    }

    function foo() internal override(b1, b2) returns (uint64) {
        return 2;
    }
}

abstract contract b1 {
    function foo() internal virtual returns (uint64) {
        return 100;
    }
}

abstract contract b2 {
    function foo() internal virtual returns (uint64) {
        return 200;
    }
}

Specifying constructor arguments

If a contract inherits another contract, then when it is instantiated or deployed, then the constructor for its inherited contracts is called. The constructor arguments can be specified on the base contract itself.

contract a is b(1) {
    constructor() {}
}

contract b is c(2) {
    int256 foo;

    function func2(int256 i) public {}

    constructor(int256 j) {}
}

contract c {
    int256 bar;

    constructor(int32 j) {}

    function func1() public {}
}

When a is deployed, the constructor for c is executed first, then b, and lastly a. When the constructor arguments are specified on the base contract, the values must be constant. It is possible to specify the base arguments on the constructor for inheriting contract. Now we have access to the constructor arguments, which means we can have runtime-defined arguments to the inheriting constructors.

contract a is b {
    constructor(int256 i) b(i + 2) {}
}

contract b is c {
    int256 foo;

    function func2() public {}

    constructor(int256 j) c(int32(j + 3)) {}
}

contract c {
    int256 bar;

    constructor(int32 k) {}

    function func1() public {}
}

The execution is not entirely intuitive in this case. When contract a is deployed with an int argument of 10, then first the constructor argument or contract b is calculated: 10+2, and that value is used as an argument to constructor b. constructor b calculates the arguments for constructor c to be: 12+3. Now, with all the arguments for all the constructors established, constructor c is executed with argument 15, then constructor b with argument 12, and lastly constructor a with the original argument 10.

Abstract Contracts

An abstract contract is one that cannot be instantiated, but it can be used as a base for another contract, which can be instantiated. A contract can be abstract because the functions it defines do not have a body, for example:

abstract contract a {
    function func2() public virtual;
}

This contract cannot be instantiated, since there is no body or implementation for func2. Another contract can define this contract as a base contract and override func2 with a body.

Another reason why a contract must be abstract is missing constructor arguments. In this case, if we were to instantiate contract a we would not know what the constructor arguments to its base b would have to be. Note that contract c does inherit from a and can specify the arguments for b on its constructor, even though c does not directly inherit b (but does indirectly).

abstract contract a is b {
    constructor() {}
}

contract b {
    int256 public j;

    constructor(int256 _j) {}
}

contract c is a {
    int256 public k;

    constructor(int256 k) b(k * 2) {}
}