> ## Documentation Index
> Fetch the complete documentation index at: https://docs.peaq.xyz/llms.txt
> Use this file to discover all available pages before exploring further.

# EVM Onboarding

## 1. Working with Finality

### 1.1 Three Presets

| Preset    | Use-case                   | How to code it                   | Typical delay |
| --------- | -------------------------- | -------------------------------- | ------------- |
| **FAST**  | UI refresh, analytics      | `provider.getBlock("latest")`    | *\~1 s*       |
| SAFE      | Most user actions          | `await tx.wait(7)`               | *\~7-8 s*     |
| **FINAL** | Treasury, bridge, NFT mint | `provider.getBlock("finalized")` | *\~15-20 s*   |

> 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

**What is a Reorg?**
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 - vanish and must be re-included.

**Why does using Finalized block help in that case?**
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`                                      | Use Chainlink VRF or for low stakes`randomnessCollectiveFlip` queried at **finalized** height. |
| Gas schedule                      | Mostly London‑equivalent; storage a bit pricier | Always run `eth_estimateGas`, never hard‑code.                                                 |
| Account abstraction (ERC‑4337)    | Not yet live                                    | Wait for roadmap.                                                                              |
| Deep traces                       | `debug_*` RPCs only on tracing‑enabled nodes    | Run a node with `--ethapi=debug,trace,txpool` & `--features evm-tracing`.                      |

***

## 5. Tracing & Debugging

Enable in node startup:

```bash theme={"theme":{"light":"github-light-default","dark":"github-dark"}}
./peaq-node \
  --ethapi=debug,trace,txpool \
  --rpc-methods=Unsafe \
  --state-pruning archive \
  --wasm-runtime-overrides=parachain-peaq \
  --runtime-cache-size 64 \
```

Then:

```bash theme={"theme":{"light":"github-light-default","dark":"github-dark"}}
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](https://github.com/peaqnetwork/peaq-node-builder).

***

## 6. Frequently Asked Questions

**How many confirmations are really “safe”?**
Waiting for the **finalized** tag is bullet‑proof; seven authored blocks (≈ 7‑8 s) is the community standard for ordinary user actions.

**Can a finalized block revert?**
Only if ≥ ⅓ of stake is slashed — an economically irrational scenario.

**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

* Docs [https://docs.peaq.xyz](https://docs.peaq.xyz/)
* Explorer [https://peaq.subscan.io](https://peaq.subscan.io/)
* Discord [https://discord.gg/peaqnetwork](https://discord.gg/peaqnetwork)
* GitHub [https://github.com/peaqnetwork](https://github.com/peaqnetwork)

*Happy building – and welcome to peaq!*