Environment agnostic contract invocation API

[ascjones]

The next foundational layer towards #1674.

 let executor =
    executor::PalletContractsExecutor::<ink::env::DefaultEnvironment, T> {
        origin: who.clone(),
        contract: contract.clone(),
        value: 0.into(),
        gas_limit,
        storage_deposit_limit,
        marker: Default::default(),
    };

let mut flipper = ink::message_builder!(Flip);
let result = flipper.flip().exec(&executor)?;

This PR:

• decouples the generation of the message execution payload (selector + input args + return type) from the other call parameters: the callee account id and the other gas and storage limit parameters.
• introduces an Executor trait which can be implemented in different environments (e.g. pallet-contracts, see example). The Executor implementation has the responsibility of gathering the other call parameters and performing the environment specific invocation, as well as decoding the result.
• modifies the existing call builder codegen to use the message builder codegen to reduce duplication.
• adds the message_builder! macro which instantiates the generated message builder instance for use to generate and invoke messages.

This PR does not:

• provide an opinionated API for how to perform calls into contracts from pallet-contracts, it requires a boilerplate impl of Executor (see integration-tests). The reason this is not provided as part of the lib is that it would require matching versions of pallet-contracts etc. with the target runtime. Need to think carefully about how best do this for maximum convenience for the user and minimum maintenance cost on the ink side.
• allow access to non trait messages, only works for trait impls (for now). 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.
• offer a similar API for constructors, the existing create builder API and ContractRef would have to be used for that,
• integrate with the existing CallBuilder API which provides a nice interface for applying the weight and storage limit parameters etc.

These can be resolved in subsequent work. The goal here is to provide a relatively simple non-breaking stepping stone to a possible universal contract invocation API, can use in the cross-contract context, from pallet-contracts and from e2e tests.

[github-actions]

🦑 📈 ink! Example Contracts ‒ Changes Report 📉 🦑

These are the results when building the integration-tests/* contracts from this branch with cargo-contract and comparing them to ink! master:

Contract	Upstream Size (kB)	PR Size (kB)	Diff (kB)	Diff (%)	Change
call-builder-return-value	9.249	9.249	0	0	➖
e2e-runtime-only-backend	1.901	1.901	0	0	➖
lang-err/call-builder-delegate	2.65	2.65	0	0	➖
lang-err/call-builder	5.571	5.571	0	0	➖
lang-err/constructors-return-value	1.997	1.997	0	0	➖
lang-err/contract-ref	5.062	5.062	0	0	➖
lang-err/integration-flipper	1.827	1.827	0	0	➖
mother	12.753	12.753	0	0	➖
sr25519-verification	1.154	1.154	0	0	➖
call-runtime	2.071	2.071	0	0	➖
combined-extension	2.132	2.132	0	0	➖
conditional-compilation	1.502	1.502	0	0	➖
contract-storage	7.58	7.58	0	0	➖
contract-terminate	1.369	1.369	0	0	➖
contract-transfer	1.731	1.731	0	0	➖
cross-contract-calls	7.732	7.732	0	0	➖
cross-contract-calls/other-contract	1.595	1.595	0	0	➖
custom-allocator	7.787	7.787	0	0	➖
custom-environment	2.158	2.158	0	0	➖
dns	7.355	7.355	0	0	➖
e2e-call-runtime	1.32	1.32	0	0	➖
erc1155	14.345	14.345	0	0	➖
erc20	6.955	6.955	0	0	➖
erc721	10.044	10.044	0	0	➖
events	5.27	5.27	0	0	➖
flipper	1.651	1.651	0	0	➖
incrementer	1.516	1.516	0	0	➖
lazyvec	4.66	4.66	0	0	➖
mapping	8.036	8.036	0	0	➖
multi-contract-caller	6.654	6.654	0	0	➖
multi-contract-caller/accumulator	1.388	1.388	0	0	➖
multi-contract-caller/adder	1.922	1.922	0	0	➖
multi-contract-caller/subber	1.942	1.942	0	0	➖
multisig	21.871	21.871	0	0	➖
payment-channel	5.742	5.742	0	0	➖
psp22-extension	7.083	7.083	0	0	➖
rand-extension	2.977	2.977	0	0	➖
runtime-call-contract	1.596	1.596	0	0	➖
static-buffer	2.578	2.578	0	0	➖
trait-dyn-cross-contract-calls	2.899	2.899	0	0	➖
trait-dyn-cross-contract-calls/contracts/incrementer	1.557	1.557	0	0	➖
trait-erc20	7.331	7.331	0	0	➖
trait-flipper	1.502	1.502	0	0	➖
trait-incrementer	1.626	1.626	0	0	➖
upgradeable-contracts/delegator	3.96	3.96	0	0	➖
upgradeable-contracts/delegator/delegatee	1.641	1.641	0	0	➖
upgradeable-contracts/delegator/delegatee2	1.641	1.641	0	0	➖
upgradeable-contracts/set-code-hash-migration	1.755	1.755	0	0	➖
upgradeable-contracts/set-code-hash-migration/migration	1.462	1.462	0	0	➖
upgradeable-contracts/set-code-hash-migration/updated-incrementer	1.909	1.909	0	0	➖
upgradeable-contracts/set-code-hash	1.755	1.755	0	0	➖
upgradeable-contracts/set-code-hash/updated-incrementer	1.733	1.733	0	0	➖
wildcard-selector	2.858	2.858	0	0	➖

Link to the run | Last update: Fri Apr 26 14:13:31 CEST 2024

[cmichi]

Please merge master and adopt the license header (Parity Tech) as well.

[cmichi]

Please also add a changelog entry.