> ## Documentation Index
> Fetch the complete documentation index at: https://docs.chainstack.com/llms.txt
> Use this file to discover all available pages before exploring further.
# subscribe ("logs") | Avalanche
> Reference for the subscribe ("logs") JSON-RPC method on the Avalanche blockchain via Chainstack nodes. Parameters, response, and examples included.
Subscription equivalent to [eth\_newFilter](/reference/avalanche-newfilter). `subscribe("logs")` allows developers to subscribe to real-time updates about new event logs on the Avalanche blockchain; the application will receive notifications whenever new logs matching the filter are emitted.
## Parameters
* `string` — a keyword identifying the type of event to subscribe to, `logs` in this case.
* `object` — (optional) The subscription options:
* `fromBlock` — an integer that specifies the starting block number from which the logs should be fetched. `null` by default.
* `address` — the contract address from which the logs should be fetched. It can be a single address or an array of addresses.
* `topics` — an array of `DATA` topics. The event topics for which the logs should be fetched. It can be a single topic or an array of topics.
* `function` — (optional) a callback function that will be called every time a new event of the specified type is received. This function takes two parameters: `error` and `result`. The error parameter contains any error that occurred while subscribing to the event, and the result parameter contains the data for the event that was received.
## Response
* `array` — an array of log objects that match the specified filter:
* `address` — the contract address from which the event originated.
* `topics` — an array of 32-byte data fields containing indexed event parameters.
* `data` — the non-indexed data that was emitted along with the event.
* `blocknumber` — the block number in which the event was included. `null` if it is pending.
* `transactionhash` — the hash of the transaction that triggered the event. `null` if pending.
* `transactionindex` — the integer index of the transaction within the block's list of transactions. `null` if it is pending.
* `blockhash` — the hash of the block in which the event was included. `null` if it is pending.
* `logindex` — the integer identifying the index of the event within the block's list of events. `null` if pending.
* `removed` — the boolean value indicating if the event was removed from the blockchain due to a chain reorganization. `True` if the log was removed. `False` if it is a valid log.
## `subscribe("logs")` code example
Note that log subscriptions require a WebSocket connection.
Use the [`ethers.WebSocketProvider`](https://docs.ethers.org/v6/api/providers/#WebSocketProvider) `provider.on` method to attach a listener to the log filter:
* The listener fires for each new log matching the filter.
* `provider.websocket.on("error", ...)` activates if an error is detected during the subscription.
* `provider.websocket.on("open", ...)` activates after the connection is successfully established.
* `provider.off(filter)` removes the listener and stops receiving updates.
```javascript index.js theme={"system"}
const ethers = require("ethers");
const NODE_URL = "CHAINSTACK_WSS_URL";
const provider = new ethers.WebSocketProvider(NODE_URL);
// Only log transfer events from the WETH smart contract.
const logsFilter = {
address: '0x82aF49447D8a07e3bd95BD0d56f35241523fBab1',
topics: ['0xddf252ad1be2c89b69c2b068fc378daa952ba7f163c4a11628f55a4df523b3ef']
}
async function subscribeToLogs() {
try {
// React to connection and error events on the underlying WebSocket
provider.websocket.on('open', handleConnected);
provider.websocket.on('error', handleError);
// Create a new subscription to the logs matching the filter
provider.on(logsFilter, handleLogs);
} catch (error) {
console.error(`Error subscribing to new logs: ${error}`);
}
}
/* Fallback functions to react to the different events */
// Event listener that logs a message when the subscription is connected
function handleConnected() {
console.log(`New subscription connected`);
}
// Event listener that logs the filtered events
async function handleLogs(logs) {
console.log(logs)
}
// Event listener that logs any errors that occur
function handleError(error) {
console.error(`Error receiving new blocks: ${error}`);
}
subscribeToLogs();
```
## Use case
A practical use case for `subscribe("logs")` is a DApp that continuously listens for new specific event logs and isolates certain fields for analytics purposes. This is useful, for example, to only track events about a specific ERC-721 token.
The following is an implementation of this concept using ethers.js subscriptions; this program will only track the `Transfer` event from the [FunnelHeads collection](https://snowtrace.io/token/0x5378d068001d7e53d6c0a7ef539fbe213b5eb075#code) smart contract.
The `Tranfer` event looks like this in the smart contract:
```sol IERC721.sol theme={"system"}
event Transfer(address indexed from, address indexed to, uint256 indexed tokenId);
```
The following code will log all of the new `Transfer` events and extract the block number. This can be useful to analyze when tokens are moved.
```javascript index.js theme={"system"}
const ethers = require("ethers");
const NODE_URL = "CHAINSTACK_WSS_URL";
const provider = new ethers.WebSocketProvider(NODE_URL);
// Only log Tranfer events from the Avalanche FunnelHeads smart contract.
const logsFilter = {
address: '0x5378d068001D7E53D6c0a7ef539fbE213B5eB075',
topics: ['0xddf252ad1be2c89b69c2b068fc378daa952ba7f163c4a11628f55a4df523b3ef']
}
async function subscribeToLogs() {
try {
// React to connection and error events on the underlying WebSocket
provider.websocket.on('open', handleConnected);
provider.websocket.on('error', handleError);
// Create a new subscription to the logs matching the filter
provider.on(logsFilter, handleLogs);
} catch (error) {
console.error(`Error subscribing to new blocks: ${error}`);
}
}
// Use this function to unsuscribe and exit the program
function unsubscribe() {
provider.off(logsFilter);
console.log("Successfully unsubscribed!");
return process.exit(1)
}
/* Fallback functions to react to the different events */
// Event listener that logs a message when the subscription is connected
function handleConnected() {
console.log(`New subscription connected`);
}
// Event listener that logs the filtered events
async function handleLogs(logs) {
const block = logs.blockNumber
console.log(`A FunnelHead was transferred in this block: ${block}`)
}
// Event listener that logs any errors that occur
function handleError(error) {
console.error(`Error receiving new blocks: ${error}`);
}
subscribeToLogs();
```
This code creates a new subscription to the logs matching the filter using the `provider.on` method. This method attaches a listener that fires every time a new log matching the filter is emitted.
The code defines three event listener functions: `handleConnected`, `handleLogs`, and `handleError`. The `handleConnected` function is called when the WebSocket connection opens, and it logs a message. The `handleLogs` function is called when a new log matching the filter is emitted, then extracts the block number field and logs it to the console.
The `handleError` function is called when an error occurs, and it logs an error message.
The code includes the `unsubscribe` function that can be implemented in the logic to unsubscribe and exit the program when a condition is met.
Finally, the code calls the `subscribeToLogs` function, which creates the subscription and attaches the event listeners. When a new event log is received, the `handleLogs` function is called to extract the data and log it to the console.