Trait Precompile

pub trait Precompile {
    type T: Config;
    type Interface: SolInterface;

    const MATCHER: AddressMatcher;
    const HAS_CONTRACT_INFO: bool;

    // Provided methods
    fn call(
        address: &[u8; 20],
        input: &Self::Interface,
        env: &mut impl Ext<T = Self::T>,
    ) -> Result<Vec<u8>, Error> { ... }
    fn call_with_info(
        address: &[u8; 20],
        input: &Self::Interface,
        env: &mut impl ExtWithInfo<T = Self::T>,
    ) -> Result<Vec<u8>, Error> { ... }
}

Type that can be implemented in other crates to extend the list of pre-compiles.

Only implement exactly one function. Either call or call_with_info.

Warning

Pre-compiles are unmetered code. Hence they have to charge an appropriate amount of weight themselves. Generally, their first line of code should be a call to env.charge(weight).

Required Associated Constants

const MATCHER: AddressMatcher

Defines at which addresses this pre-compile exists.

const HAS_CONTRACT_INFO: bool

Defines whether this pre-compile needs a contract info data structure in storage.

Enabling it unlocks more APIs for the pre-compile to use. Only pre-compiles with a fixed matcher can set this to true. This is enforced at compile time. Reason is that contract info is per address and not per pre-compile. Too many contract info structures and accounts would be created otherwise.

When set to true

• An account will be created at the pre-compiles address when it is called for the first time. The ed is minted.
• Contract info data structure will be created in storage on first call.
• Only call_with_info should be implemented. call is never called.

When set to false

• No account or any other state will be created for the address.
• Only call should be implemented. call_with_info is never called.

What to use

Should be set to false if the additional functionality is not needed. A pre-compile with contract info will incur both a storage read and write to its contract metadata when called.

The contract info enables additional functionality:

• Storage deposits: Collect deposits from the origin rather than the caller. This makes it easier for contracts to interact with the pre-compile as deposits are paid by the transaction signer (just like gas). It also makes refunding easier.
• Contract storage: You can use the contracts key value child trie storage instead of providing your own state. The contract storage automatically takes care of deposits. Providing your own storage and using pallet_revive to collect deposits is also possible, though.
• Instantitation: Contract instantiation requires the instantiator to have an account. This is because its nonce is used to derive the new contracts account id and child trie id.

Have a look at ExtWithInfo to learn about the additional APIs that a contract info unlocks.

Required Associated Types

type T: Config

Your runtime.

type Interface: SolInterface

The Solidity ABI definition of this pre-compile.

Use the [self::alloy::sol] macro to define your interface using Solidity syntax. The input the caller passes to the pre-compile will be validated and parsed according to this interface.

Please note that the return value is not validated and it is the pre-compiles duty to return the abi encoded bytes conformant with the interface here.

Provided Methods

fn call( address: &[u8; 20], input: &Self::Interface, env: &mut impl Ext<T = Self::T>, ) -> Result<Vec<u8>, Error>

Entry point for your pre-compile when HAS_CONTRACT_INFO = false.

fn call_with_info( address: &[u8; 20], input: &Self::Interface, env: &mut impl ExtWithInfo<T = Self::T>, ) -> Result<Vec<u8>, Error>

Entry point for your pre-compile when HAS_CONTRACT_INFO = true.

Dyn Compatibility

This trait is not dyn compatible.

In older versions of Rust, dyn compatibility was called "object safety", so this trait is not object safe.

Implementors