EVM Onboarding

Configure EVM development for peaq, choose transaction finality presets, estimate gas, and deploy contracts with the network’s RPC settings.

1. Working with Finality

1.1 Three Presets

Preset	Use-case	How to code it	Typical delay
FAST	UI refresh, analytics	provider.getBlock("latest")	~7 s
SAFE	Most user actions	await tx.wait(7)	~50 s
FINAL	Treasury, bridge, NFT mint	receipt.blockNumber <= finalizedBlock.number (poll as shown below)	~40 s

A latest block is optimistic; a finalized block cannot be dropped.

For the FINAL preset, poll the receipt and the finalized block until the receipt’s block number is no higher than the finalized block’s number, then check that the canonical block at that height is the receipt’s block. If it is not, the transaction was reorganized out of that block, so keep polling for a fresh receipt. Replace txHash with your submitted transaction hash:

import { ethers } from 'ethers';

const provider = new ethers.JsonRpcProvider('https://quicknode1.peaq.xyz');
const txHash = '0xYourTransactionHash';

async function waitForFinality() {
  while (true) {
    const receipt = await provider.getTransactionReceipt(txHash);
    const finalizedBlock = await provider.getBlock('finalized');
    if (receipt && finalizedBlock && receipt.blockNumber <= finalizedBlock.number) {
      const block = await provider.getBlock(receipt.blockNumber);
      if (block && block.hash === receipt.blockHash) {
        if (receipt.status !== 1) {
          throw new Error('Transaction failed');
        }
        return receipt;
      }
      // Reorganized out of that block: poll again for the current receipt
    }
    await new Promise(resolve => setTimeout(resolve, 6000));
  }
}

const finalizedReceipt = await waitForFinality();
console.log('Finalized transaction:', finalizedReceipt.hash);

1.2 Decision matrix

• FAST (0 confirms, ~7 s): real-time UI updates and analytics. Roll back if a reorg shows up.
• SAFE (7 authored blocks, ~50 s): ordinary user actions such as token transfers, approvals, and simple swaps. Rarely reorgs. The finalized tag usually arrives sooner (~40 s) and cannot be dropped, so prefer finalized over the 7-block wait when your provider supports it.
• FINAL (finalized tag, ~40 s): anything that must be irreversible, such as treasury moves, bridge deposits, and high-value NFT mints.

---

2. Quick-Start Checklist

1. RPC & chain-ID

   • Mainnet RPC https://quicknode1.peaq.xyz ID 3338
   • Testnet RPC https://peaq-agung.api.onfinality.io/public ID 9990

2. Check your EVM version

   peaq runs the Cancun opcode set apart from the blob opcodes (BLOBHASH, BLOBBASEFEE). Newer targets are not supported: solc 0.8.30 and later default to prague or osaka, and the Osaka CLZ opcode fails on peaq. Set evmVersion to cancun:

   solidity: {
     version: "0.8.28",
     settings: { evmVersion: "cancun" }
   }
   

3. Estimate gas then add a 10 to 20 percent buffer (see estimate gas fees)

   const gas = await provider.estimateGas(tx);
   tx.gasLimit = (gas * 120n) / 100n;
   

4. Deploy as usual

   npx hardhat ignition deploy ./ignition/modules/SimpleStorage.js --network peaq (add a peaq network to hardhat.config.js with chainId: 3338, as for agung in Build Smart Contract)

---

3. Handling Reorgs & Using Finalized Blocks

Reorgs When two blocks land at almost the same time the chain briefly forks. The shorter fork is later dropped, so its last few blocks, and any transactions inside them, vanish and must be re-included.

Why finalized blocks help Extra votes lock a block in permanently; once finalized, that block (and all earlier ones) can never be dropped, so reorgs can only touch the unfixed tip of the chain.

// Latest for optimistic UI
const latest = await provider.getBlock("latest");

// Finalized for deterministic reads
const finalized = await provider.send(
  "eth_getBlockByNumber",
  ["finalized", false]
);

When monitoring blocks:

let lastHash;
provider.on("block", async (n) => {
  const blk = await provider.getBlock(n);
  if (lastHash && blk.parentHash !== lastHash) {
    // reorg detected: revert optimistic state
  }
  lastHash = blk.hash;
});

---

4. peaq-Specific Nuances

Topic	What’s different	What to do
block.difficulty / prevrandao	Always 0	For low-stakes off-chain applications, query randomnessCollectiveFlip through Substrate RPC at finalized height.
Gas schedule	Storage is pricier than on Ethereum mainnet	Always run eth_estimateGas, never hard-code.
Account abstraction (ERC-4337)	Canonical EntryPoint v0.6 deployed at 0x5FF137D4b0FDCD49DcA30c7CF57E578a026d2789; peaqOS machine smart accounts are wired to it	See peaqOS smart contracts.
Deep traces	debug_* RPCs only on tracing-enabled nodes	Run a node with --ethapi=debug,trace,txpool and a runtime built with the evm-tracing feature.

---

5. Tracing & Debugging

Add these flags to your node startup command (the Docker command on Connecting to peaq shows the rest):

./peaq-node \
  --chain ./node/src/chain-specs/peaq-raw.json \
  --ethapi=debug,trace,txpool \
  --rpc-methods=Unsafe \
  --state-pruning archive \
  --wasm-runtime-overrides=parachain-peaq \
  --runtime-cache-size 64

Then:

curl -X POST -H "Content-Type: application/json" -d \
 '{"jsonrpc":"2.0","id":1,"method":"debug_traceTransaction","params":["<txHash>",{"tracer":"callTracer"}]}' \
 https://evm.yourevmnode.xyz

Before enabling tracing RPCs, build the runtime with the evm-tracing feature and put the resulting .wasm file in an overrides folder. Then start the node with tracing RPCs enabled and point --wasm-runtime-overrides at that directory, not at the file. The override is not part of the Docker image, so mount your own folder. If the path is not a real directory, or the file does not end in .wasm, the override is ignored and tracing does not work. For the build scripts, see the peaq-node-builder repository.

---

6. Frequently Asked Questions

How many confirmations are really “safe”? Waiting for the finalized tag is the strongest guarantee. Seven authored blocks (≈ 50 s) is the community standard for ordinary user actions.

Can a finalized block revert? Only if at least a third of the stake is slashed, which is economically irrational.

My tx failed, how do I debug? Simulate with provider.call(tx) first; for deep dives use debug_traceTransaction on a tracing node.

---

7. Resources

• Explorer https://peaq.subscan.io
• Discord https://discord.gg/UKTFkPWsyH
• GitHub https://github.com/peaqnetwork