Smart Contract Events

Listen to smart contract events on peaq with ethers.js. Load a contract ABI, parse emitted logs, and filter specific events for your application.

Contracts emit events during execution, and those events are written to the chain as logs. You can capture and parse them to build responsive dApps, monitor activity, or trigger off-chain workflows.

This guide shows how to listen to and parse smart contract events on the peaq network with ethers.js.

Prerequisites

1. A smart contract deployed on the peaq network that emits events.
2. Node.js, with ethers.js installed.
3. A peaq network RPC endpoint, for example https://quicknode1.peaq.xyz.
4. The address of the deployed contract and its ABI.

Instructions

1. Set Up Your Project

Install ethers.js:

npm install ethers dotenv

2. Initialize Connection to the peaq Network

Connect to the peaq network using ethers.js:

import { ethers } from "ethers";
const provider = new ethers.JsonRpcProvider("https://quicknode1.peaq.xyz");

3. Load the Smart Contract

To interact with the smart contract, load its address and ABI:

const contractAddress = "0xYourContractAddress"; // Replace with your smart contract's address
const contractABI = [
  // Add your contract's ABI here or import with require() instead
];

const contract = new ethers.Contract(contractAddress, contractABI, provider);

4. Listen for Events

Using ethers.js, you can set up listeners for specific events emitted by the contract:

contract.on("YourEventName", (param1, param2, event) => {
  console.log(`Event received:`);
  console.log(`Param 1: ${param1}`);
  console.log(`Param 2: ${param2}`);
  console.log(`Full Event:`, event);
});

5. Parse Events

To handle every log the contract emits, subscribe to the contract address and decode each log yourself. parseLog returns null for a log that does not match the ABI:

provider.on({ address: contractAddress }, (log) => {
  const parsedLog = contract.interface.parseLog(log);
  if (parsedLog) {
    console.log("Parsed Log:", parsedLog);
  }
});

6. Filter Specific Events

To reduce overhead, use filters to listen for specific events:

const filter = contract.filters.YourEventName(); // Add any indexed parameters if applicable

contract.on(filter, (param1, param2, event) => {
  console.log(`Filtered Event: ${event.eventName}`);
  console.log(`Event Data:`, event.args);
});

7. Testing the Listener

Trigger events in your smart contract (e.g., using a wallet or script) and ensure the listener captures them correctly. Example: Emit an event in your smart contract:

event YourEventName(address indexed user, uint256 value);
emit YourEventName(msg.sender, 1000);

Expected console output:

Console Logs Example
...................
Event received:
Param 1: 0xYourWalletAddress
Param 2: 1000
Full Event: {...}

Putting it all Together

JavaScript

//event-listener.js

import dotenv from 'dotenv';
dotenv.config();

import { ethers } from "ethers";
import { readFileSync } from "node:fs";

// Load environment variables
const RPC_URL = process.env.PEAQ_RPC_URL || "https://quicknode1.peaq.xyz"; // Replace with your preferred peaq RPC URL
const CONTRACT_ADDRESS = process.env.CONTRACT_ADDRESS; // Replace with your contract address
// Replace with the path to your contract ABI JSON file
const CONTRACT_ABI = JSON.parse(readFileSync(new URL("./contract_abi.json", import.meta.url), "utf8"));

// Initialize provider and contract
const provider = new ethers.JsonRpcProvider(RPC_URL);
const contract = new ethers.Contract(CONTRACT_ADDRESS, CONTRACT_ABI, provider);

// Function to listen for events
const listenForEvents = () => {
  console.log("Listening for events on contract:", CONTRACT_ADDRESS);

  // Replace "YourEventName" with the event name from your contract ABI
  contract.on("YourEventName", (param1, param2, event) => {
    console.log("Event Received:");
    console.log(`Param 1: ${param1}`);
    console.log(`Param 2: ${param2}`);
    console.log("Raw Event Data:", event);
  });
};

// Error handling and script execution
const main = async () => {
  try {
    listenForEvents();
  } catch (error) {
    console.error("Error in event listener:", error);
    process.exit(1);
  }
};

main();

Tips

1. Batch Processing: Combine historical event fetching (getLogs) with real-time listeners so you do not lose events emitted while your listener was down.

2. Indexed Parameters: Mark event parameters as indexed so you can filter by their values.

   event YourEventName(address indexed user, uint256 value);
   

   Then filter by the address:

   const filter = contract.filters.YourEventName("0xSpecificAddress");
   

3. Environment Variables: Keep RPC URLs and contract addresses in a .env file rather than in the source.