Guides

On this page

• Wallet Integration

  • Implementation Checklist

  • Frontend

  • Transactions

  • Connections

• DApp Store Contract Registration

  • Requirements

  • Register Contract

  • Deployed Factory Pattern

  • Update Contract

  • Cancel Contract

• ERC-20 Registration

  • Drafting the ERC-20 Proposal

  • Submitting the ERC-20 Proposal

  • Formatting the Proposal’s Text

  • Submit the Proposal to Testnet

  • The On-Chain ERC-20 Proposal

  • The Deposit Period

  • The Voting Period

• Query Balances

  • ICPlazad & Tendermint RPC

  • JSON-RPC

  • gRPC

• Trace Transactions

  • Basic EVM Tracing with JS

  • Tracing Prerequisites

  • Basic Traces

  • Limits of Basic Traces

  • Filtered EVM Tracing with JS

  • Running a Simple Trace

  • How Does it Work?

  • Actual Filtering

  • Stack Information

  • JSON-RPC debug_trace* Endpoints

  • debug_traceTransaction

  • debug_traceBlockByNumber

  • debug_traceBlockByHash

  • Additional Information

Wallet Integration #

Learn how to properly integrate Metamask or Keplr with a dApp on ICTech.

:::tip Note: want to learn more about wallet integration beyond what’s covered here? Check out both the MetaMask Wallet documentation and Keplr Wallet documentation. :::

Implementation Checklist #

The integration implementation checklist for dApp developers consists of three categories:

1. [Frontend features]

2. [Transactions and wallet interactions]

3. [Client-side provider]

Frontend #

Make sure to create a wallet-connection button for Metamask and/or Keplr on the frontend of the application. For instance, consider the “Connect to a wallet” button on the interface of Diffusion Finance or the analagous button on the interface of [ICTech wap]

Transactions #

Developers enabling transactions on their dApp have to [determine wallet type]of the user, [create the transaction], [request signatures] from the corresponding wallet, and finally [broadcast the transaction]to the network.

Determining Wallet Type #

Developers should determine whether users are using Keplr or MetaMask. Whether MetaMask or Keplr is installed on the user device can be determined by checking the corresponding window.ethereum or window.keplr value.

• For MetaMask: await window.ethereum.enable(chainId);

• For Keplr: await window.keplr.enable(chainId);

If either window.ethereum or window.keplr returns undefined after document.load, then MetaMask (or, correspondingly, Keplr) is not installed. There are several ways to wait for the load event to check the status: for instance, developers can register functions to window.onload, or they can track the document’s ready state through the document event listener.

After the user’s wallet type has been determined, developers can proceed with creating, signing, and sending transactions.

Create the Transaction #

:::tip Note: The example below uses the ICTech Testnet chainID. For more info, check the ICPlaza Chain IDs reference document here. :::

Developers can create MsgSend transactions using the [ICTechjs] library.

import { createMessageSend } from @tharsis/transactions

const chain = {
    chainId: 9000,
    ICPlazaChainId: 'ICPlaza_9000-4',
}

const sender = {
    accountAddress: 'ICPlaza1mx9nqk5agvlsvt2yc8259nwztmxq7zjq50mxkp',
    sequence: 1,
    accountNumber: 9,
    pubkey: 'AgTw+4v0daIrxsNSW4FcQ+IoingPseFwHO1DnssyoOqZ',
}

const fee = {
    amount: '20',
    denom: 'aICPlaza',
    gas: '200000',
}

const memo = ''

const params = {
    destinationAddress: 'ICPlaza1pmk2r32ssqwps42y3c9d4clqlca403yd9wymgr',
    amount: '1',
    denom: 'aICPlaza',
}

const msg = createMessageSend(chain, sender, fee, memo, params)

// msg.signDirect is the transaction in Keplr format
// msg.legacyAmino is the transaction with legacy amino
// msg.eipToSign is the EIP712 data to sign with metamask

Sign and Broadcast the Transaction #

:::tip Note: The example below uses an ICTech Testnet [RPC node]. :::

After creating the transaction, developers need to send the payload to the appropriate wallet to be signed (msg.signDirect is the transaction in Keplr format, and msg.eipToSign is the EIP712 data to sign with MetaMask).

With the signature, we add a Web3Extension to the transaction and broadcast it to the ICTech node.

// Note that this example is for MetaMask, using ICPlazajs

// Follow the previous code block to generate the msg object
import { ICPlazaToEth } from '@tharsis/address-converter'
import { generateEndpointBroadcast, generatePostBodyBroadcast } from '@tharsis/provider'
import { createTxRawEIP712, signatureToWeb3Extension } from '@tharsis/transactions'

// Init Metamask
await window.ethereum.enable();

// Request the signature
let signature = await window.ethereum.request({
    method: 'eth_signTypedData_v4',
    params: [ICPlazaToEth(sender.accountAddress), JSON.stringify(msg.eipToSign)],
});

// The chain and sender objects are the same as the previous example
let extension = signatureToWeb3Extension(chain, sender, signature)

// Create the txRaw
let rawTx = createTxRawEIP712(msg.legacyAmino.body, msg.legacyAmino.authInfo, extension)

// Broadcast it
const postOptions = {
    method: 'POST',
    headers: { 'Content-Type': 'application/json' },
    body: generatePostBodyBroadcast(rawTx),
};

let broadcastPost = await fetch(
    `https://eth.bd.ICPlaza.dev:8545${generateEndpointBroadcast()}`,
    postOptions
);
let response = await broadcastPost.json();

Connections #

For Ethereum RPC, ICTech gRPC, and/or REST queries, dApp developers should implement providers client-side, and store RPC details in the environment variable as secrets.

DApp Store Contract Registration #

This guide explains how to register your smart contract in the ICTech dApp store, and start earning income every time a user interacts with your smart contract. {synopsis}

The ICTech dApp store is a revenue-per-transaction model, which allows developers to get paid for deploying their decentralized application (dApps) on ICTech. Developers generate revenue every time a user interacts with their dApp in the dApp store, providing them a steady income. Users can discover new applications in the dApp store and pay for the transaction fees that finance the dApp’s revenue. This value-reward exchange of dApp services for transaction fees is implemented by the [x/feesplit module].

Requirements #

• Address of a deployed smart contract.

• Capability to sign transactions with the address that deployed the contract. If your smart contract was deployed by a contract using a factory pattern, then the signing capaility is required for the address that deployed the factory.

• The nonce of the contract deployment transaction. You can query the nonce, e.g. using the eth_getTransactionByHash JSON-RPC endpoint.

• Withdrawer address, in case you wish to receive your earnings at a specified address.

::: warning IMPORTANT: If your contract is part of a development project, please ensure that the deployer of the contract (or the factory that deploys the contract) is an account that is owned by that project. This avoids the situation of a malicious individual/employee deployer (including former contributors) who leaves your project and could later change the withdrawal address unilaterally. :::

Register Contract #

To add your contract in the ICTech dApp Store, you need to register a feesplit for that contract. The feesplit includes the details for receiving a cut of the transaction fees, which users pay for interacting with your smart contract. Every time a user submits a transaction to your registered smart contract, a part of the transaction fees (50% by default) is transferred to the withdrawer address specified in the feesplit. If the withdrawer is not specified, the transaction fees are sent to the contract deployer.

You can register a contract by signing a transaction with the address that originally deployed the contract. You can use the following CLI command, where

• $NONCE is the nonce of transaction that deployed the contract (e.g. 0),

• $CONTRACT is the hex address of the deployed contract (e.g 0x5f6659B6F712c729c46786bA9562eC50907c67CF) and

• (optional) $WITHDRAWER is the bech32 address of the address to receive the transaction fees (e.g. ICPlaza1keyy3teyq7t7kuxgeek3v65n0j27k20v2ugysf):

# Register a feesplit for your contract
ICPlazad tx feesplit register $CONTRACT $NONCE $WITHDRAWER \
--from=mykey \ # contract deployer key
--gas=700000 --gas-prices=10000aICPlaza \ # can vary depending on the network

After your transaction is submitted successfully, you can query your feesplit with :

# Check feesplits
ICPlazad q feesplit contract $CONTRACT

Congrats ☄️☄️☄️ Now that you’ve registered a feesplit for your contract, it is part of the ICPlaza dApp store and you will receive a cut of the transaction fees every time a user interacts with your contract. If you wondering how large your cut is, have a look at the [feesplit parameter DeveloperShares], which is controlled through governance. You can query the parameters using our [OpenAPI documentation].

Deployed Factory Pattern #

You can also register a contract which has been deployed by a smart contract instead of an [EOA]. In this case, you need to provide a sequence of nonces that proves the trace from an original deployer who deployed the factory to the contract that is being registered.

Example DeployerEOA -> FactoryA -> FactoryB-> MyContract: DeployerEOA deploys a FactoryA smart contract with nonce 5. Then, DeployerEOA sends a transaction to FactoryA through which a FactoryB smart contract is created. If we assume FactoryB is the second contract created by FactoryA, then FactoryA’s nonce is 2. Then, DeployerEOA sends a transaction to the FactoryB contract, through which MyContract is created. If this is the first contract created by FactoryB - the nonce is 1. To be able to verify that DeployerEOA can register MyContract, we need to provide the following nonces: [5, 2, 1].

Update Contract #

Registered contracts can also be updated. To update the withdrawer address of your feesplit, use the following CLI command:

# Update withdrawer for your contract
ICPlazad tx feesplit update $CONTRACT $WITHDRAWER \
--gas=700000 --gas-prices=10000aICPlaza \
--from=mm

If the specified withdrawer is the same address as the deployer, then the feesplit is updated with an empty withdrawer address, so that all transaction fees are sent to the deployer address.

Cancel Contract #

Feesplits can also be canceled. In order to stop receiving transaction fees for interaction with your contract, use the following CLI command:

# Cancel feesplit for your contract
ICPlazad tx feesplit cancel $CONTRACT \
--gas=700000 --gas-prices=10000aICPlaza \
--from=mm

ERC-20 Registration #

Learn how to register interoperable ERC-20s through ICPlaza Governance.

:::tip Note: Not sure what the difference between ICTech Coin and ERC-20 Registration is? You’re in the right place if an ERC-20 contract corresponding to your token already exists, and you want to add functionality to convert the ERC-20 token to a native ICTech Coin denomination. If you instead want to add functionality to convert a native ICTech Coin to an ERC-20 token representation, then check out [ICTech Coin Registration].

Still confused? Learn more about the differences [here]. :::

The ERC-20 Module (also known as x/erc20) allows users to instantly convert ERC-20 tokens into native ICTech Coins, and vice versa. This allows users to exchange assets interchangeably in two entirely different layers, the EVM and ICTech.

Application-wise, the ERC-20 module allows DeFi protocols to seamlessly integrate with ICPlaza and the ICTech ecosystem. Using the module, developers can build smart contracts on ICTech and use the generated ERC-20 tokens for other applications on the ICPlaza ecosystem, such as:

• earning $ICT staking rewards

• taking part in governance proposals by voting with $ICT

Registering an interoperable ERC-20 means registering a new mapping between an existing ERC-20 token contract and a ICTech Coin denomination, also known as a Token Pair. Token Pairs enable users to convert ERC-20 tokens into their native ICTech Coin representation (and vice versa), and can only be created via a governance proposal.

More information can be found in [this blog post], which introduced the ERC-20 Module on ICTech.

To register an ERC-20, consider the following stages:

1. [Drafting the ERC-20 Proposal]

2. [Submitting the ERC-20 Proposal]

3. [The On-Chain ERC-20 Proposal]

Drafting the ERC-20 Proposal #

The following topics must be addressed when drafting an ERC-20 Proposal:

1. Provide the profile of the person(s)/entity making the proposal.

   Who are you? What is your involvement in ICTech and/or other blockchain networks? If you are working with a team, who are the team members involved and what is their relevant experience? What is the mission statement of your organization or business? Do you have a website? Showcase some work you’ve done and some proof of who you are.

2. Promote understanding of the ERC-20 Module.

   Make sure to mention the original [blog post] that introduced the ERC-20 Module, along with a brief explanation of what the ERC-20 Module does. It’s also a good idea to link the [ERC-20 Module documentation]!

3. Describe how ERC-20 Module changes will be made.

   Give a breakdown of the proposal’s payload, and explain in layman terms what the proposal will do if it passes. Detail precautions taken during contract and proposal formulation, if applicable (including consultations made prior to proposal creation, how contracts were tested, and any third-party reviews). Finally, mention the risks involved in the proposal, depending on the direction of IBC Coin and ERC-20.

4. Document adherence to ERC-20 Contract expectations.

   Ensure that the ERC-20 contracts are verified (either through the [EVM explorer] or via Sourcify), and that the contracts are deployed open-source. Security-wise, the following are required: - the contracts use the main libraries for ERC-20s (eg. OpenZeppelin, dapp.tools) - the contracts do not extend the IERC20.sol interface through a malicious implementation - the transfer logic is not modified (i.e. transfer logic is not directly manipulated) - no malicious Approve events can directly manipulate users’ balance through a delayed granted allowance Take note of the above in your proposal description!

Remember to provide links to the relevant [Commonwealth ICTech community] discussions concerning your proposal, as well as the [proposal on testnet].

Submitting the ERC-20 Proposal #

After the drafting process, the ERC-20 Proposal can be submitted.

Formatting the Proposal’s Text #

The ideal format for a proposal is as a Markdown file (ie. .md) in a Github repo or HackMd. Markdown is a simple and accessible format for writing plain text files that is easy to

learn. See the Github Markdown Guide for details on writing markdown files.

Submit the Proposal to Testnet #

To submit the proposal to testnet through the command line with [ICPlazad], use the following command with register-erc20:

ICPlazad tx gov submit-proposal register-erc20 <erc20-address> \
  --title=<title> \
  --description=<description> \
  --deposit="1000000aICPlaza" \
  --from=<mykey> \
  --chain-id=<testnet_chain_id> \
  --node <address>

However, note that if the CLI is used to create a proposal, and description is set using a flag, the text will be escaped which may have undesired effects. If the proposal creator is using markdown or line breaks it’s recommended to put the proposal text into a json file and include that file as part of the CLI proposal, as opposed to individual fields in flags. The process of creating a json file containing the proposal can be found here, and the CLI command for submitting the file is below:

ICPlazad tx gov submit-proposal register-erc20 --proposal=<path/to/proposal.json>

You may want to submit your proposal to the testnet chain before the mainnet for a number of reasons, such as wanting to see what the proposal description will look like, to share what the proposal will look like in advance with stakeholders, and to signal that your proposal is about to go live on the mainnet.

Submitting your proposal to the testnet increases the likelihood of engagement and the possibility that you will be alerted to a flaw before deploying your proposal to mainnet.

The On-Chain ERC-20 Proposal #

A majority of the voting community should probably be aware of the proposal and have considered it before the proposal goes live on-chain. If you’re taking a conservative approach, you should have reasonable confidence that your proposal will pass before risking deposit contributions by submitting the proposal. Make revisions to your draft proposal after each stage of engagement.

The Deposit Period #

The deposit period currently lasts 14 days. If you submitted your transaction with the minimum deposit (64 ICTech), your proposal will immediately enter the voting period. If you didn’t submit the minimum deposit amount (currently 64 ICTech), then this may be an opportunity for others to show their support by contributing (and risking) their ICTech as a bond for your proposal. You can request contributions openly and also contact stakeholders directly (particularly stakeholders who are enthusiastic about your proposal). Remember that each contributor is risking their funds, and you can read more about the conditions for burning deposits here.

This is a stage where proposals may begin to get broader attention. Most popular explorers currently display proposals that are in the deposit period, but due to proposal spamming, this may change.

A large cross-section of the blockchain/cryptocurrency community exists on Twitter. Having your proposal in the deposit period is a good time to engage the ICTech community to prepare validators to vote and ICTech-holders that are staking.

The Voting Period #

At this point you’ll want to track which validator has voted and which has not. You’ll want to re-engage directly with top stake-holders, ie. the highest-ranking validator operators, to ensure that:

1. they are aware of your proposal;

2. they can ask you any questions about your proposal; and

3. they are prepared to vote.

Remember that any voter may change their vote at any time before the voting period ends. That historically doesn’t happen often, but there may be an opportunity to convince a voter to change their vote. The biggest risk is that stakeholders won’t vote at all (for a number of reasons). Validator operators tend to need multiple reminders to vote. How you choose to contact validator operators, how often, and what you say is up to you–remember that no validator is obligated to vote, and that operators are likely occupied by competing demands for their attention. Take care not to stress any potential relationship with validator operators.

Query Balances #

Learn how to query balances of IBC ICTech Coins and ERC-20s on ICTech.

This guide will cover the following query methods:

• ICPlazad & Tendermint RPC

• JSON-RPC

• gRPC

:::warning Note: In this document, the command line is used to interact with endpoints. For dApp developers, using libraries such as [cosmjs] and [ICTechjs] is recommended instead. :::

ICTech & Tendermint RPC #

Upon installation and [configuration] of the ICTech Daemon, developers can query account balances using ICTech with the following CLI command:

$ ICPlazad query bank balances $ICPlazaADDRESS --count-total=$COUNTTOTAL --height=$HEIGHT --output=$OUTPUT --node=$NODE
balances:
- amount: "1000000000000000000"
  denom: aICPlaza
- amount: "100000"
  denom: ibc/ED07A3391A112B175915CD8FAF43A2DA8E4790EDE12566649D0C2F97716B8518
pagination:
  next_key: null
  total: "0"

where:

• $ICTech ADDRESS is the ICTech address with balances of interest (eg. ICPlaza1...).

• (optional) $COUNTTOTAL counts the total number of records in all balances to query for.

• (optional) $HEIGHT is the specific height to query state at (can error if node is pruning state).

• (optional) $OUTPUT is the output format (eg. text).

• (optional if running local node) $NODE is the Tendermint RPC node information is requested from (eg. https://tendermint.bd.ICTech,xyz:26657).

Details of non-native currencies (ie. not ICTech) can be queried with the following CLI command:

$ ICPlazad query erc20 token-pair $DENOM --node=$NODE --height=$HEIGHT --output=$OUTPUT
token_pair:
  contract_owner: OWNER_MODULE
  denom: ibc/ED07A3391A112B175915CD8FAF43A2DA8E4790EDE12566649D0C2F97716B8518
  enabled: true
  erc20_address: 0xFA3C22C069B9556A4B2f7EcE1Ee3B467909f4864

where $DENOM is the denomination of the coin (eg. ibc/ED07A3391A1...).

JSON-RPC #

Developers can query account balances of aICPlaza using the [eth_getBalance]JSON-RPC method in conjunction with curl:

# Request
curl -X POST --data '{"jsonrpc":"2.0","method":"eth_getBalance","params":[`$ETHADDRESS`, `$BLOCK`],"id":1}' -H "Content-Type: application/json" $NODE

# Result
{"jsonrpc":"2.0","id":1,"result":"0x36354d5575577c8000"}

where:

• $ETHADDRESS is the Etherum hex-address the balance is to be queried from. Note that ICPlaza addresses (those beginning with ICPlaza1...) can be converte.d to Ethereum addresses using libraries such as [ICPlazajs].

• $BLOCK is the block number or block hash (eg. "0x0"). The reasoning for this parameter is due to EIP-1898.

• (optional if running local node) $NODE is the JSON-RPC node information is requested from (eg. https://eth.bd.ICPlaza.org:8545).

Developers can also query account balances of x/erc20-module registered coins using the [eth_call] JSON-RPC method in conjunction with curl:

# Request
curl -X POST --data '{"jsonrpc":"2.0","method":"eth_call","params":[{"from":`SENDERCONTRACTADDRESS`, "to":`ERCCONTRACTADDRESS`, "data":`$DATA`}, `$BLOCK`],"id":1}'  -H "Content-Type: application/json" $NODE

# Result
{"jsonrpc":"2.0","id":1,"result":"0x"}

where:

• $SENDERCONTRACTADDRESS is the Ethereum hex-address this smart contract call is sent from.

• $ERCCONTRACTADDRESS is the Ethereum hex-address of the ERC-20 contract corresponding to the coin denomination being queried.

• $DATA is the hash of the balanceof method signature and encoded parameters. balanceOf is a required method in every ERC-20 contract, and the encoded parameter is the address which is having its balance queried. For additional information, see the Ethereum Contract ABI.

• $BLOCK is the block number or block hash (eg. "0x0"). The reasoning for this parameter is due to EIP-1898.

• (optional if running local node) $NODE is the JSON-RPC node information is requested from (eg. https://eth.bd.ICTech.xyz:8545).

gRPC #

Developers can use grpcurl with the AllBalances endpoint to query account balance by address for all denominations:

# Request
grpcurl $OUTPUT -d '{"address":`$ICPlazaADDRESS`}' $NODE ICPlaza.bank.v1beta1.Query/AllBalances

# Result
{
  "balances": [
    {
      "denom": "stake",
      "amount": "1000000000"
    }
  ],
  "pagination": {
    "total": "1"
  }
}

where:

• $ICTech ADDRESS is the ICTech address with balances of interest (eg. "ICPlaza1...").

• $NODE is the ICTech gRPC node information is requested from (eg. https://grpc.bd.ICPlaza.org:9090).

• (optional) $OUTPUT is the output format (eg. plaintext).

State can also be queried using gRPC within a Go program. The idea is to create a gRPC connection, then use the Protobuf-generated client code to query the gRPC server.

import (
    "context"
    "fmt"

  "google.golang.org/grpc"

    sdk "github.com/ICPlaza/ICPlaza-sdk/types"
  "github.com/ICPlaza/ICPlaza-sdk/types/tx"
)

func queryState() error {
    myAddress, err := GetICPlazaAddressFromBech32("ICPlaza1...") // ICPlaza address with balances of interest.
    if err != nil {
        return err
    }

    // Create a connection to the gRPC server.
    grpcConn := grpc.Dial(
        "https://grpc.bd.ICPlaza.org:9090", // your gRPC server address.
        grpc.WithInsecure(), // the SDK doesn't support any transport security mechanism.
    )
    defer grpcConn.Close()

    // This creates a gRPC client to query the x/bank service.
    bankClient := banktypes.NewQueryClient(grpcConn)
    bankRes, err := bankClient.AllBalances(
        context.Background(),
        &banktypes.QueryAllBalancesRequest{Address: myAddress},
    )
    if err != nil {
        return err
    }

    fmt.Println(bankRes.GetBalances()) // prints the account balances.

    return nil
}

// ICPlazajs address converter.
func GetICPlazaAddressFromBech32(address string) (string, error) {...}

:::tip Note: The following tools will be useful when using gRPC:

• [ICTech Swagger API] a comprehensive description of all gRPC endpoints

• ICTech SDK Go API &ICTech Go API: packages to implement queries in Go scripts

:::

Trace Transactions #

Learn how to trace transactions and blocks on ICTech. {synopsis}

This guide will cover the following topics:

• basic EVM tracing with JS

• filtered EVM tracing with JS

• JSON-RPC debug_trace* endpoints

Basic EVM Tracing with JS #

Tracing a transaction means requesting an ICTech node to re-execute the desired transaction with varying degrees of data collection.

Tracing Prerequisites #

Re-executing a transaction has a few prerequisites to be met. All historical state accessed by the transaction must be available, including:

• Balance, nonce, bytecode, and storage of both the recipient as well as all internally invoked contracts

• Block metadata referenced during execution of the outer as well as all internally created transactions

• Intermediate state generated by all preceding transactions contained in the same block as well as the one being traced

This means there are limits on the transactions that can be traced and imported based on the synchronization and pruning configuration of a node.

• Archive nodes: retain all historical data back to genesis, can trace arbitrary transactions at any point in the history of the chain.

• Fully synced nodes: transactions within a recent range (depending on how much history is stored) are accessible.

• Light synced nodes: these nodes retrieve data on demand, so in theory they can trace transactions for which all required historical state is readily available in the network (however, data availability cannot be reasonably assumed).

Basic Traces #

The simplest type of transaction trace that Geth can generate are raw EVM opcode traces. For every VM instruction the transaction executes, a structured log entry is emitted, contained all contextual metadata deemed useful. This includes:

• program counter

• opcode name & cost

• remaining gas

• execution depth

• occurred errors

as well as (optionally) the execution stack, execution memory, and contract storage.

The entire output of a raw EVM opcode trace is a JSON object having a few metadata fields: consumed gas, failure status, return value, and a list of opcode entries:

{
  "gas":         25523,
  "failed":      false,
  "returnValue": "",
  "structLogs":  []
}

An example log for a single opcode entry has the following format:

{
  "pc":      48,
  "op":      "DIV",
  "gasCost": 5,
  "gas":     64532,
  "depth":   1,
  "error":   null,
  "stack": [
    "00000000000000000000000000000000000000000000000000000000ffffffff",
    "0000000100000000000000000000000000000000000000000000000000000000",
    "2df07fbaabbe40e3244445af30759352e348ec8bebd4dd75467a9f29ec55d98d"
  ],
  "memory": [
    "0000000000000000000000000000000000000000000000000000000000000000",
    "0000000000000000000000000000000000000000000000000000000000000000",
    "0000000000000000000000000000000000000000000000000000000000000060"
  ],
  "storage": {
  }
}

Limits of Basic Traces #

Although raw opcode traces generated above are useful, having an individual log entry for every single opcode is too low level for most use cases, and will require developers to create additional tools to post-process the traces. Additionally, a single opcode trace can easily be hundreds of megabytes, making them very resource intensive to extract from the node and process extenally.

To avoid these issues, Geth supports running custom JavaScript traces within the ICTech (or any EVM-compatible) node, which have full access to the EVM stack, memory, and contract storage. This means developers only have to gather data that they actually need, and do any processing at the source.

Filtered EVM Tracing with JS #

Basic traces can include the complete status of the EVM at every point in the transaction’s execution, which is huge space-wise. Usually, developers are only interested in a small subset of this information, which can be obtained by specifying a JavaScript filter.

Running a Simple Trace #

:::warning Note: debug.traceTransaction must be invoked from within the Geth console, although it can be invoked from outside the node using JSON-RPC (eg. using Curl), as seen in the [following section]. If developers want to use debug.traceTransaction as it is used here, maintainence of a node is required, so see [this document]. :::

1. Create a file, filterTrace_1.js, with this content:

tracer = function(tx) {
  return debug.traceTransaction(tx, {tracer:
      '{' +
        'retVal: [],' +
        'step: function(log,db) {this.retVal.push(log.getPC() + ":" + log.op.toString())},' +
        'fault: function(log,db) {this.retVal.push("FAULT: " + JSON.stringify(log))},' +
        'result: function(ctx,db) {return this.retVal}' +
      '}'
  }) // return debug.traceTransaction ...
}   // tracer = function ...

1. Run the JavaScript console.

2. Get a hash of a recent transaction.

3. Run this command to run the script:

loadScript("filterTrace_1.js")

1. Run the tracer from the script:

tracer("<hash of transaction>")

The bottom of the output looks similar to:

"3366:POP", "3367:JUMP", "1355:JUMPDEST", "1356:PUSH1", "1358:MLOAD", "1359:DUP1", "1360:DUP3", "1361:ISZERO", "1362:ISZERO",
"1363:ISZERO", "1364:ISZERO", "1365:DUP2", "1366:MSTORE", "1367:PUSH1", "1369:ADD", "1370:SWAP2", "1371:POP", "1372:POP", "1373:PUSH1",
"1375:MLOAD", "1376:DUP1", "1377:SWAP2", "1378:SUB", "1379:SWAP1", "1380:RETURN", ...

1. This output isn’t very readable. Run this command to get a more readable output with each string on its own line:

  console.log(JSON.stringify(tracer("<hash of transaction>"), null, 2))

The JSON.stringify function’s documentation is here. If we just return the output, we get for newlines, which is why we need to use console.log.

How Does it Work? #

We call the same debug.traceTransaction function used for [basic traces], but with a new parameter, tracer. This parameter is a string, which is the JavaScript object we use. In the case of the trace above, it is:

{
   retVal: [],
   step: function(log,db) {this.retVal.push(log.getPC() + ":" + log.op.toString())},
   fault: function(log,db) {this.retVal.push("FAULT: " + JSON.stringify(log))},
   result: function(ctx,db) {return this.retVal}
}

This object has to have three member functions:

• step, called for each opcode

• fault, called if there is a problem in the execution

• result, called to produce the results that are returned by debug.traceTransaction after the execution is done

It can have additional members. In this case, we use retVal to store the list of strings that we’ll return in result.

The step function here adds to retVal: the program counter, and the name of the opcode there. Then, in result, we return this list to be sent to the caller.

Actual Filtering #

For actual filtered tracing, we need an if statement to only log revelant information. For example, if we are interested in the transaction’s interaction with storage, we might use:

tracer = function(tx) {
      return debug.traceTransaction(tx, {tracer:
      '{' +
         'retVal: [],' +
         'step: function(log,db) {' +
         '   if(log.op.toNumber() == 0x54) ' +
         '     this.retVal.push(log.getPC() + ": SLOAD");' +
         '   if(log.op.toNumber() == 0x55) ' +
         '     this.retVal.push(log.getPC() + ": SSTORE");' +
         '},' +
         'fault: function(log,db) {this.retVal.push("FAULT: " + JSON.stringify(log))},' +
         'result: function(ctx,db) {return this.retVal}' +
      '}'
      }) // return debug.traceTransaction ...
}   // tracer = function ...

The step function here looks at the opcode number of the op, and only pushes an entry if the opcode is SLOAD or SSTORE (here is a list of all EVM opcodes and their corresponding numbers). We could have used log.op.toString instead, but it is faster to compare numbers rather than strings.

The output looks similar to this:

[
  "5921: SLOAD",
  .
  .
  .
  "2413: SSTORE",
  "2420: SLOAD",
  "2475: SSTORE",
  "6094: SSTORE"
]

Stack Information #

The trace above tells us the program counter and whether the program read from storage or wrote to it. To know more, you can use the log.stack.peek function to peek into the stack. log.stack.peek(0) is the stack top, log.stack.peek(1) is the entry beow it, etc. The values returned by log.stack.peek are Go big.int objects. By default they are converted to JavaScript floating point numbers, so you need toString(16) to get them as hexadecimals, which is how we normally represent 256-bit values such as storage cells and their content.

tracer = function(tx) {
      return debug.traceTransaction(tx, {tracer:
      '{' +
         'retVal: [],' +
         'step: function(log,db) {' +
         '   if(log.op.toNumber() == 0x54) ' +
         '     this.retVal.push(log.getPC() + ": SLOAD " + ' +
         '        log.stack.peek(0).toString(16));' +
         '   if(log.op.toNumber() == 0x55) ' +
         '     this.retVal.push(log.getPC() + ": SSTORE " +' +
         '        log.stack.peek(0).toString(16) + " <- " +' +
         '        log.stack.peek(1).toString(16));' +
         '},' +
         'fault: function(log,db) {this.retVal.push("FAULT: " + JSON.stringify(log))},' +
         'result: function(ctx,db) {return this.retVal}' +
      '}'
      }) // return debug.traceTransaction ...
}   // tracer = function ...

[
  "5921: SLOAD 0",
  .
  .
  .
  "2413: SSTORE 3f0af0a7a3ed17f5ba6a93e0a2a05e766ed67bf82195d2dd15feead3749a575d <- fb8629ad13d9a12456",
  "2420: SLOAD cc39b177dd3a7f50d4c09527584048378a692aed24d31d2eabeddb7f3c041870",
  "2475: SSTORE cc39b177dd3a7f50d4c09527584048378a692aed24d31d2eabeddb7f3c041870 <- 358c3de691bd19",
  "6094: SSTORE 0 <- 1"
]

There are several other facets of filtered EVM tracing, including:

• determining operation results

• dealing with calls between contracts

• accessing memory

• using the db parameter to know the state of the chain at the time of execution

This information is covered in this reference.

JSON-RPC debug_trace* Endpoints #

ICTech supports the following debug_trace* JSON-RPC Methods, which follow Geth’s debug API guidelines.

debug_traceTransaction #

The traceTransaction debugging method will attempt to run the transaction in the exact same manner as it was executed on the network. It will replay any transaction that may have been executed prior to this one, before it will finally attempt to execute the transaction that corresponds to the given hash.

Parameters:

• trace configuration

# Request
curl -X POST --data '{"jsonrpc":"2.0","method":"debug_traceTransaction","params":[<transaction hash>, {"tracer": "{data: [], fault: function(log) {}, step: function(log) { if(log.op.toString() == \"CALL\") this.data.push(log.stack.peek(0)); }, result: function() { return this.data; }}"}],"id":1}' -H "Content-Type: application/json" https://eth.bd.ICPlaza.org:8545

# Result
{"jsonrpc":"2.0","id":1,"result":[{"result":["68410", "51470"]}]}

debug_traceBlockByNumber #

The traceBlockByNumber endpoint accepts a block number, and will replay the block that is already present in the database.

Parameters:

• trace configuration

# Request
curl -X POST --data '{"jsonrpc":"2.0","method":"debug_traceBlockByNumber","params":[<block number>, {"tracer": "{data: [], fault: function(log) {}, step: function(log) { if(log.op.toString() == \"CALL\") this.data.push(log.stack.peek(0)); }, result: function() { return this.data; }}"}],"id":1}' -H "Content-Type: application/json" https://eth.bd.ICPlaza.org:8545

# Result
{"jsonrpc":"2.0","id":1,"result":[{"result":["68410", "51470"]}]}

debug_traceBlockByHash #

The traceBlockByNumber endpoint accepts a block hash, and will replay the block that is already present in the database.

Parameters:

• trace configuration

# Request
curl -X POST --data '{"jsonrpc":"2.0","method":"debug_traceBlockByNumber","params":[<block hash>, {"tracer": "{data: [], fault: function(log) {}, step: function(log) { if(log.op.toString() == \"CALL\") this.data.push(log.stack.peek(0)); }, result: function() { return this.data; }}"}],"id":1}' -H "Content-Type: application/json" https://eth.bd.ICPlaza.org:8545

# Result
{"jsonrpc":"2.0","id":1,"result":[{"result":["68410", "51470"]}]}

Additional Information #

See the sources below for details not covered above:

• [JSON-RPC Methods on ICPlaza]

• Basic EVM Tracing

• Filtered EVM Tracing

← Client

Localnet →