Skip to main content

Transaction Verification Aspect

Introduction​

Aspect can provide transaction verification service when bound to certain dApp and EoA. If an Aspect has been bound to certain dApp and EoA as a transaction verifier, instead of doing the legacy secp256k1 signature verification, Aspect will replace it with the customized verification logic implemented in the verifyTx method.

verify.svg

Interface​

interface ITransactionVerifier extends IAspectBase {
verifyTx(input: TxVerifyInput): Uint8Array;
}
  • Parameter
    • input: TxVerifyInput; The base layer will deliver the TxVerifyInput object to Aspect in this join point.
      • input.block.number: current block number.
      • input.tx.from: caller of the transaction.
      • input.tx.to: to address of the transaction.
      • input.tx.hash: hash of the transaction.
  • Returns
    • Uint8Array; verified account address.

Example​

To function as a transaction verifier Aspect, an Aspect must implement the ITransactionVerifier interface. This interface comprises a single method, verifyTx, which is invoked for transactions sent from an EoA without a valid ECDSA signature.

import {
ITransactionVerifier, allocate, entryPoint, execute, sys, TxVerifyInput
} from "@artela/aspect-libs";

class Aspect implements ITransactionVerifier {
verifyTx(input: TxVerifyInput): Uint8Array {
return sys.aspect.property.get<Uint8Array>('verifyAccount');
}

/**
* isOwner is the governance account implemented by the Aspect, when any of the governance operation
* (including upgrade, config, destroy) is made, isOwner method will be invoked to check
* against the initiator's account to make sure it has the permission.
*
* @param ctx context of Aspect state
* @param sender address of the operation initiator
* @return true if check success, false if check fail
*/
isOwner(sender: Uint8Array): bool {
// always return false on isOwner can make the Aspect immutable
return true;
}
}

// 2.register aspect Instance
const aspect = new Aspect();
entryPoint.setAspect(aspect);

// 3.must export it
export {execute, allocate};

Programming Guide​

There are two programming modes that can be used in this method:

  1. By utilizing the 'input' input argument, it provides essential insights into transactions and block processing. see how to use input.

  2. Using the 'sys' namespace, it provides both hight level API and low-level API access to system data and contextual information generated during blockchain runtime, including details about the environment, blocks, transactions, and utility classes such as crypto and ABI encoding/decoding. see more details.

Host APIs​

For a comprehensive overview of all APIs and their usage see API References.

Each join-point has access to different host APIs, and the host APIs available within the current breakpoint can be found at the following table.

System APIsAvailabilityDescription
sys.revertβœ…Forces the current transaction to fail.
sys.requireβœ…Checks if certain conditions are met; if not, forces the entire transaction to fail.
sys.logβœ…A wrapper for sys.hostApi.util.log, prints log messages to Artela output for debugging on the localnet.
sys.aspect.idβœ…Retrieves the ID of the aspect.
sys.aspect.version βœ…Retrieves the version of the aspect.
sys.aspect.mutableState❌A wrapper for sys.hostApi.aspectState that facilitates easier reading or writing of values of a specified type to aspect state.
sys.aspect.propertyβœ…A wrapper for sys.hostApi.aspectProperty that facilitates easier reading of values of a specified type from aspect property.
sys.aspect.readonlyStateβœ…A wrapper for sys.hostApi.aspectState that facilitates easier reading of values of a specified type from aspect state.
sys.aspect.transientStorage❌A wrapper for sys.hostApi.aspectTransientStorage that facilitates easier reading or writing of values of a specified type to aspect transient storage.
sys.hostApi.aspectPropertyβœ…Retrieves the property of the aspect as written in aspect deployment.
sys.hostApi.aspectStateβœ…Retrieves or writes the state of the aspect.
sys.hostApi.aspectTransientStorage❌Retrieves or writes to the transient storage of the aspect. This storage is only valid within the current transaction lifecycle.
sys.hostApi.crypto.ecRecoverβœ…Calls crypto methods ecRecover.
sys.hostApi.crypto.keccakβœ…Calls crypto methods keccak.
sys.hostApi.crypto.ripemd160βœ…Calls crypto methods ripemd160.
sys.hostApi.crypto.sha256βœ…Calls crypto methods sha256.
sys.hostApi.runtimeContextβœ…Retrieves runtime context by the key. Refer to the runtime context to see which keys can be accessed by the current join point.
sys.hostApi.stateDb.balance❌Gets the balance of the specified address from the EVM state database.
sys.hostApi.stateDb.codeHash❌Gets the hash of the code from the EVM state database.
sys.hostApi.stateDb.codeSize❌Gets the size of the code from the EVM state database.
sys.hostApi.stateDb.hasSuicided❌Gets the codehash from the EVM state database.
sys.hostApi.stateDb.nonce❌Checks if the contract at the specified address is suicided in the current transactions.
sys.hostApi.stateDb.stateAt❌Gets the state at a specific point.
sys.hostApi.evmCall.jitCall❌Creates a contract call and executes it immediately.
sys.hostApi.evmCall.staticCallβœ…Creates a static call and executes it immediately.
sys.hostApi.trace.queryCallTree❌Returns the call tree of EVM execution.
sys.hostApi.trace.queryStateChange❌Returns the state change in EVM execution for the specified key.

Runtime context​

The Aspect Runtime Context encapsulates data generated through the consensus process. With the acquired Runtime Context object, retrieve specific data by specifying the relevant Context Key. Each Context Key is associated with a particular type of data or information.

Usage​


const isCall = sys.hostApi.runtimeContext.get('isCall');
// decode BoolData
const isCallData = Protobuf.decode < BoolData > (isCall, BoolData.decode);
sys.log('is call' + ' ' + isCallData.data.toString());

const number = sys.hostApi.runtimeContext.get('block.header.number');
// decode UintData
const numberData = Protobuf.decode < UintData > (number, UintData.decode);
sys.log('block.header.number' + ' ' + numberData.data.toString(10));

Key table​

Context keyValue typeDescription
isCallBoolDataGet the current transaction is Call or Send. If it is Call, return true.
tx.typeUintDataReturns the transaction type id. LegacyTxType=0x00 AccessListTxType=0x01 DynamicFeeTxType=0x02 BlobTxType=0x03
tx.chainIdBytesDataReturns the EIP155 chain ID of the transaction. The return value will always be non-nil. For legacy transactions which are not replay-protected, the return value is zero.
tx.accessListEthAccessListAccessListTx is the data of EIP-2930 access list transactions.
tx.nonceUintDataReturns the sender account nonce of the transaction.
tx.gasPriceBytesDataReturns the gas price of the transaction.
tx.gasUintDataReturns the gas limit of the transaction.
tx.gasTipCapBytesDataReturns the gasTipCap per gas of the transaction.
tx.gasFeeCapBytesDataReturns the fee cap per gas of the transaction.
tx.toBytesDataReturns the recipient address of the transaction. For contract-creation transactions, To returns nil.
tx.valueBytesDataReturns the ether amount of the transaction.
tx.dataBytesDataReturns the input data of the transaction.
tx.bytesBytesDataReturns the transaction marshal binary.
tx.hashBytesDataReturns the transaction hash.
tx.unsigned.bytesBytesDataReturns the unsigned transaction marshal binary.
tx.unsigned.hashBytesDataReturns the unsigned transaction hash.
block.header.numberUintDataGet the current block number.
env.extraEIPsIntArrayDataRetrieve the EVM module parameters for the 'extra_eips': defines the additional EIPs for the vm.Config.
env.enableCreateBoolDataRetrieve the EVM module parameters for the 'enable_create': toggles states transitions that use the vm.Create function.
env.enableCallBoolDataRetrieve the EVM module parameters for the 'enable_call': toggles states transitions that use the vm.Call function.
env.allowUnprotectedTxsBoolDataRetrieve the EVM module parameters for the 'allow_unprotected_txs': defines if replay-protected (i.e non EIP155 // signed) transactions can be executed on the states machine.
env.chain.chainIdUintDataRetrieve the Ethereum chain config id.
env.chain.homesteadBlockUintDataRetrieve the Ethereum chain configuration for the 'homestead_block': switch (nil no fork, 0 = already homestead)
env.chain.daoForkBlockUintDataRetrieve the Ethereum chain configuration for the 'dao_fork_block': corresponds to TheDAO hard-fork switch block (nil no fork)
env.chain.daoForkSupportBoolDataRetrieve the Ethereum chain configuration for the 'dao_fork_support': defines whether the nodes supports or opposes the DAO hard-fork
env.chain.eip150BlockUintDataRetrieve the Ethereum chain configuration for the 'eip150_block': EIP150 implements the Gas price changes (https://github.com/ethereum/EIPs/issues/150) EIP150 HF block (nil no fork)
env.chain.eip155BlockUintDataRetrieve the Ethereum chain configuration for the 'eip155_block'.
env.chain.eip158BlockUintDataRetrieve the Ethereum chain configuration for the 'eip158_block'.
env.chain.byzantiumBlockUintDataRetrieve the Ethereum chain configuration for the 'byzantium_block': Byzantium switch block (nil no fork, 0 =already on byzantium)
env.chain.constantinopleBlockUintDataRetrieve the Ethereum chain configuration for the 'constantinople_block': Constantinople switch block (nil no fork, 0 = already activated)
env.chain.petersburgBlockUintDataRetrieve the Ethereum chain configuration for the 'petersburg_block': Petersburg switch block (nil no fork, 0 = already activated)
env.chain.istanbulBlockUintDataRetrieve the Ethereum chain configuration for the 'istanbul_block': Istanbul switch block (nil no fork, 0 = already on istanbul)
env.chain.muirGlacierBlockUintDataRetrieve the Ethereum chain configuration for the 'muir_glacier_block': Eip-2384 (bomb delay) switch block ( nil no fork, 0 = already activated).
env.chain.berlinBlockUintDataRetrieve the Ethereum chain configuration for the 'berlin_block': Berlin switch block (nil = no fork, 0 = already on berlin)
env.chain.londonBlockUintDataRetrieve the Ethereum chain configuration for the 'london_block': London switch block (nil = no fork, 0 = already on london)
env.chain.arrowGlacierBlockUintDataRetrieve the Ethereum chain configuration for the 'arrow_glacier_block': Eip-4345 (bomb delay) switch block (nil = no fork, 0 = already activated)
env.chain.grayGlacierBlockUintDataRetrieve the Ethereum chain configuration for the 'gray_glacier_block': EIP-5133 (bomb delay) switch block (nil = no fork, 0 = already activated)
env.chain.mergeNetSplitBlockUintDataRetrieve the Ethereum chain configuration for the 'merge_netsplit_block': Virtual fork after The Merge to use as a network splitter.
env.chain.shanghaiTimeUintDataRetrieve the Ethereum chain configuration for the 'shanghaiTime': Shanghai switch time (nil = no fork, 0 = already on shanghai).
env.chain.cancunTimeUintDataRetrieve the Ethereum chain configuration for the 'CancunTime': Cancun switch time (nil = no fork, 0 = already on cancun).
env.chain.pragueTimeUintDataRetrieve the Ethereum chain configuration for the 'PragueTime': Prague switch time (nil = no fork, 0 = already on prague).
env.consensusParams.block.maxGasIntDataRetrieve the max gas per block.
env.consensusParams.block.maxBytesIntDataRetrieve the max block size, in bytes.
env.consensusParams.evidence.maxAgeDurationIntDataRetrieve the max age duration.It should correspond with an app's "unbonding period" or other similar mechanism for handling.
env.consensusParams.evidence.maxAgeNumBlocksIntDataThe basic formula for calculating this is: MaxAgeDuration / {average block time}.
env.consensusParams.evidence.maxBytesIntDataRetrieve the maximum size of total evidence in bytes that can be committed in a single block.
env.consensusParams.validator.pubKeyTypesStringArrayDataRestrict the public key types validators can use.
env.consensusParams.appVersionUintDataGet the ABCI application version.
aspect.idBytesDataReturns current aspect id.
aspect.versionUintDataReturns current aspect version.

To trigger​

To trigger the 'VerifyTx' join point, a customized verification transaction without a signature is necessary. The format of this transaction is as follows:

magic prefix + checksum(encodedData) + encodedData(validation data + raw calldata)

Description:

  • 0xCAFECAFE serves as a fixed value with a magical prefix.
  • checksum(encodedData) represents a 4-byte checksum of the encoded data.
  • encodedData is the result of ABI encoding, combining validation data and raw call data using `ABI.encode( ValidationData, CallData)."

Example:

0xCAFECAFE75bac07d00000000000000000000000000000000000000000000000000000000000000400000000000000000000000000000000000000
0000000000000000000000000c000000000000000000000000000000000000000000000000000000000000000557d7cfdeff97cbabdc4124c779d51
bb2520cbdc769840c6fee4566e23c7c22ea2a3e071dc794283b70608de4566c9dc0fd5f1854d7032676996fd95284693ecad5b2eeca9864734af5131
ed015c52cd1b5b3d9f841c000000000000000000000000000000000000000000000000000000000000000000000000000000000000241003e2d2000
000000000000000000000000000000000000000000000000000000000000100000000000000000000000000000000000000000000000000000000
  • 0xCAFECAFE is a magical prefix.
  • 75bac07d is 4-byte checksum of the encoded data. calculate the checksum like keccak256(encodedData).slice(2, 10).
  • The remaining bytes represent the result of ABI encoding for ValidationData and CallData. like abi.encodeParameters(['bytes', 'bytes'], [validationData, contractCallData]).

Here is a case demonstration on how to create a customized verification transaction. Through this example, you can gain a clearer understanding of how to utilize Verify Tx.