ink! Smart Contract Language

ink! is a collection of crates designed for no_std environments (except for metadata and engine). The core components include:

• ink: The central umbrella crate for the ink! eDSL.
• allocator: A simple bump allocator for dynamic memory. It never frees space to minimize gas costs and complexity, as memory is reset for every contract call.
• env: Provides environmental functions (e.g., caller info, self-termination) and the connection to pallet-revive for storage and pallet interaction.
• metadata: Describes the contract interface, types, and storage layout in a platform-agnostic way.
• prelude: Provides access to standard library-like functionality (e.g., vec, string) in a no_std context.
• storage: Collections available for contract developers to use in smart contract storage.
• engine: An off-chain testing engine for simulating blockchain environments.
• e2e: An end-to-end testing framework requiring a Polkadot SDK node with pallet-revive.

When using ink! on pallet-revive, developers should be aware of several architectural constraints inherited from the fork of pallet-contracts. These factors impact performance, data encoding, and error debugging:

Performance and Encoding

• Pre-compile Overhead: Many host functions have been migrated to pre-compiles. Calling these functions incurs the performance overhead of a contract-to-contract call rather than a direct host call.
• ABI Encoding: pallet-revive pre-compiles use a Solidity interface instead of SCALE encoding. ink! must re-encode arguments into the Solidity ABI format and decode responses, which adds computational overhead.

Data Types and Events

• Balance Types: Developers must handle two different types for contract balances: the generic Balance (defined in chain configuration) and the Ethereum-native U256.
• Event Availability: Most smart-contract-specific events (e.g., Called, ContractCodeUpdated, CodeStored, CodeRemoved, Terminated, DelegateCalled, StorageDepositTransferredAndHeld, StorageDepositTransferredAndReleased) have been removed. The Instantiated event remains available.

Debugging and Errors

• Error Semantics: Due to the shift to pre-compiles, some semantic error information is lost. For example, a call that fails due to insufficient Gas (which previously returned OutOfGas) may now return ContractTrapped. This can make it more difficult to distinguish between logic errors and resource exhaustion.

The Delegator pattern uses the low-level host function delegate_call to allow a contract to delegate execution to on-chain uploaded code. Unlike a traditional cross-contract call, delegate_call delegates to the code rather than the contract address, meaning the execution occurs within the context of the caller's storage.

Storage Compatibility and CallFlags

Because the delegated code operates on the caller's storage, you must manage storage layouts carefully:

• Layout-full storage: If the delegated code modifies any field that is NOT a Lazy or Mapping type, you must specify the CallFlags::TAIL_CALL flag and ensure the storage layouts match exactly.
• Lazy or Mapping fields: If the delegated code only modifies Lazy or Mapping fields, the keys must be identical. In this case, CallFlags::TAIL_CALL is optional because these types interact with storage directly without loading/flushing the entire storage state.
• Layoutless storage: If your storage consists only of Lazy and Mapping fields, the order of fields and the overall layout do not need to match.

When a struct uses a generic KEY: StorageKey, the #[ink::storage_item] macro sets the ParentKey generic value to KEY, effectively concatenating them. This allows you to reuse the same type definition in different contexts with different storage keys.

Example usage in a contract:

#[ink(storage)]
struct MyContract {
    my_struct: MyStruct<ManualKey<123>>,
}

Important: Avoid direct assignment of default instances. Because every type is unique after code generation (due to its specific storage key), assigning a value like Balances::default() to a field that expects a specific ManualKey will cause a type mismatch error.

Incorrect:

instance.balances = Balances::<ManualKey<123>>::default(); // Error

Correct: Use Default::default() to allow the compiler to generate the correct type with the expected storage key:

instance.balances = Default::default();

#[ink(storage)]
struct MyContract {
    my_struct: MyStruct<ManualKey<123>>,
}

// Inside a constructor or method:
instance.balances = Default::default();

When an upgrade introduces a new storage layout, you can use an intermediate migration contract to perform the migration. This prevents the contract from becoming unusable due to storage mismatch.

Workflow:

1. Upload a migration contract: This contract must include a migrate message designed to perform the storage migration.
2. Update code hash: Use set_code_hash() to point the contract address to the migration contract.
3. Upload new version: Upload the upgraded version of your original contract.
4. Execute migration: Call the migrate message on the migration contract, passing the code hash of the new upgraded contract as an argument.

Critical Requirement: Steps 2 through 4 must be executed as a single message. If the migration is not completed in the same transaction that sets the code hash, the contract will fail to load the migrated storage and will become uncallable.