本体技术视点 | 一文读懂Substrate的合约机制（三）

//这个函数用于gas的计费，是合约代码部署时的预处理时插入的。因此正常的合约不能导入。
fn gas(amount: u32);

// 在指定的key下存储value，value的长度不能超过预定的值，且不能为空，key是定长的32字节，因此参数不需要指定长度。
fn seal_set_storage(key_ptr:u32, value_ptr: u32, value_len: u32);

// 清除指定的key的存储。
seal_clear_storage(key_ptr: u32);

// 获取指定key下的value值，结果存在out_ptr指定的内存中，out_len_ptr指向一个u32整数，是输入和输出参数，用于指定out_ptr指向内存buffer的长度，同时用于返回实际value对应的长度，函数返回值用于指明key是否存在。当out_len太小时会导致trap（其他函数也一样，只要发生越界会直接trap)。
fn seal_get_storage(key_ptr: u32, out_ptr: u32, out_len_ptr: u32) -> ReturnCode;

给某一个账户进行转账，account必须要能够解码为T::AccountId, value必须要能解码为T::Balance，否则直接trap，转账失败返回错误有`BelowSubsistenceThreshold`和`TransferFailed`。
fn seal_transfer(account_ptr: u32, account_len: u32, value_ptr: u32, value_len: u32) -> ReturnCode;

// 跨合约调用，当output_ptr为u32::max_value()时，表示忽略返回值。output_len_ptr是输入输出参数。存在如下错误码：`CalleeReverted`, `CalleeTrapped` `BelowSubsistenceThreshold` `TransferFailed` `NotCallable`
seal_call(callee_ptr, callee_len, gas, value_ptr, value_len,
    input_data_ptr, input_data_len, output_ptr, output_len_ptr: u32) -> ReturnCode

// 合约实例化
seal_instantiate(code_hash_ptr, code_hash_len, gas: u64, value_ptr, value_len, input_data_ptr, input_data_len, address_ptr: u32,
    address_len_ptr, output_ptr, output_len_ptr, salt_ptr, salt_len: u32) -> ReturnCode

// 销毁当前的合约，并将余额转到指定的账户，这个函数不会返回。
seal_terminate(beneficiary_ptr: u32, beneficiary_len: u32) ;

// 读取合约的输入，从实现上看，好像输入只能读取一次。
seal_input(buf_ptr: u32, buf_len_ptr: u32);

// 终止合约的执行，并返回结果。flags用于指定返回状态，目前只用了最低的一个bit，表示是否revert。其他的保留位必须为0，否则会导致trap。
seal_return(flags: u32, data_ptr: u32, data_len: u32) ;

// 获取调用方地址
seal_caller(out_ptr: u32, out_len_ptr: u32) 

// 获取合约自己的地址
seal_address(out_ptr: u32, out_len_ptr: u32) 

// 计算gas对应需要消耗的balance，注意不推荐使用小的gas参数，因为单位gas对应的balance可能小于1.
seal_weight_to_fee(gas: u64, out_ptr: u32, out_len_ptr: u32) 

//查询剩余的gas，为u32整数。
seal_gas_left(out_ptr: u32, out_len_ptr: u32) 

// 返回当前合约的余额
seal_balance(out_ptr: u32, out_len_ptr: u32) 

// 返回当前调用转的balance值。
seal_value_transferred(out_ptr: u32, out_len_ptr: u32)

// 根据当前的区块和subject获取一个随机值，结果是一个T::Hash
seal_random(subject_ptr: u32, subject_len: u32, out_ptr: u32, out_len_ptr: u32)

// 获取最后一个区块的时间戳
seal_now(out_ptr: u32, out_len_ptr: u32) 

// 获取账户不被删除所需要的最小balance
seal_minimum_balance(out_ptr: u32, out_len_ptr: u32) 

// 获取合约可以为tombsone状态存储的最小balance。注：为了使合约能够成为tombsone，其balance必须要大于tombsone deposit + existential deposit，代码中把两者之和称为subsistence threshold。
seal_tombstone_deposit(out_ptr: u32, out_len_ptr: u32);

// 恢复tombsone状态的合约
seal_restore_to(dest_ptr, dest_len, code_hash_ptr, code_hash_len, rent_allowance_ptr, 
    rent_allowance_len, delta_ptr, delta_count: u32) 

// 合约吐event，topics_ptr指向的是一个编码为Vec<T::Hash>的buffer，且内容不可重复。
seal_deposit_event(topics_ptr: u32, topics_len: u32, data_ptr: u32, data_len: u32) 

// 设置可以收取的最大租金额度
seal_set_rent_allowance(value_ptr: u32, value_len: u32) 

// 获取可收取的最大租金额度
seal_rent_allowance(out_ptr: u32, out_len_ptr: u32) 

// 打印log，只能用于调试链。
seal_println(str_ptr: u32, str_len: u32) 

// 获取当前区块号
fn seal_block_number(out_ptr: u32, out_len_ptr: u32) 

// 计算sha2-256/keccak-256/blake2-256/blake2-128的hash
fn seal_hash_sha2_256(input_ptr: u32, input_len: u32, output_ptr: u32)     
fn seal_hash_keccak_256(input_ptr: u32, input_len: u32, output_ptr: u32)
fn seal_hash_blake2_256(input_ptr: u32, input_len: u32, output_ptr: u32) 
fn seal_hash_blake2_128(input_ptr: u32, input_len: u32, output_ptr: u32)

pub trait Sandbox {
    /// 获取sandbox指定位置的内存
    fn memory_get(
        &mut self,
        memory_id: MemoryId,
        offset: WordSize,
        buf_ptr: Pointer<u8>,
        buf_len: WordSize,
    ) -> Result<u32>;
    /// 设置sandbox指定位置的内存
    fn memory_set(
        &mut self,
        memory_id: MemoryId,
        offset: WordSize,
        val_ptr: Pointer<u8>,
        val_len: WordSize,
    ) -> Result<u32>;
    /// 删除内存实例
    fn memory_teardown(&mut self, memory_id: MemoryId) -> Result<()>;
    /// 新建内存实例
    fn memory_new(&mut self, initial: u32, maximum: u32) -> Result<MemoryId>;
    /// 调用wasm中的某个导出函数
    fn invoke(
        &mut self,
        instance_id: u32,
        export_name: &str,
        args: &[u8],
        return_val: Pointer<u8>,
        return_val_len: WordSize,
        state: u32,
    ) -> Result<u32>;
    /// 删除wasm实例
    fn instance_teardown(&mut self, instance_id: u32) -> Result<()>;
    /// 创建sandbox wasm实例
    fn instance_new(
        &mut self,
        dispatch_thunk_id: u32,
        wasm: &[u8],
        raw_env_def: &[u8],
        state: u32,
    ) -> Result<u32>;

    /// 获取wasm实例的全局变量
    fn get_global_val(&self, instance_idx: u32, name: &str) -> Result<Option<Value>>;
}

fn dispatch_thunk(invoke_args_ptr, invoke_args_len: u32, state: u32, func_idx: u32) -> u64

define_env!(
    fn seal_set_storage(ctx, key_ptr:u32, value_ptr: u32, value_len: u32);
)

fn seal_set_storage(ctx: &mut T, args:&[Value]);