EVM Onboarding

​

1. Working with Finality

​

1.1 Three Presets

Golden rule: a latest block is optimistic; a finalized block is forever.

​

1.2 Decision matrix

• FAST (0 confirms, ~1 s) – Great for real-time UI updates and analytics. Roll back if a reorg shows up.
• SAFE (~7 authored blocks, ~7-8 s) – Default for ordinary user actions (token transfers, approvals, simple swaps). Rarely reorgs yet still snappy.
• FINAL (relay-chain finalized, ~15-20 s) – Use for anything that must be absolutely irreversible: treasury moves, bridge deposits, high-value NFT mints, etc.

​

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. Pin EVM version to london
   solidity: {
     version: "0.8.21",
     settings: { evmVersion: "london" }
   }
   
3. Estimate gas then add a ×2 buffer
   const gas = await provider.estimateGas(tx);
   tx.gasLimit = gas.mul(2);
   
4. Deploy as usual npx hardhat run scripts/deploy.js --network peaq

​

3. Handling Reorgs & Using Finalized Blocks

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

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

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

​

5. Tracing & Debugging

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

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

💡 Note:
Before enabling tracing RPCs, you must build the runtime with the evm-tracing feature and place the resulting .wasm file in a folder used for overrides. Then, start the node with tracing RPCs enabled and point --wasm-runtime-overrides to that directory (not a file). The override is not included in the Docker image, so you must mount your own folder. If the path isn’t a real directory or the file doesn’t end in .wasm, the override will be ignored and tracing won’t work. For more information on building the runtime with tracing enabled, see the peaq-node-builder repository.

​

6. Frequently Asked Questions

​

7. Resources

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