logs

Emits logs attached to a new block that match certain topic filters.

The logs subscription type emits logs that match a specified topic filter and are included in newly added blocks. To learn more about logs on Ethereum and other EVM chains, check out Understanding Logs: Deep Dive into eth_getLogs.

📘

Note on Chain Reorganizations (ReOrgs)

When a chain reorganization occurs, logs that are part of blocks on the old chain will be emitted again with the property removed set to true. Logs that are part of the blocks on the new chain are also emitted so it is possible to see logs for the same transaction multiple times in the case of a reorganization.

If removed is not included in the response payload then the logs are still a part of the canonical chain.

Supported Networks

NetworkEthereumPolygonOptimismArbitrumAstar
logs:white-check-mark::white-check-mark::white-check-mark::white-check-mark::white-check-mark:

Parameters

An object with the following fields:

  • adddress (optional): string] or [array of strings] Singular address or array of addresses. Only logs created from one of these addresses will be emitted.
  • topics: an array of topic specifiers.
    • Each topic specifier is either null, a single string, or an array of strings.
    • For every non null topic, a log will be emitted when activity associated with that topic occurs.

📘

Topic Specifications:

  • []: Any topics allowed.
  • [A]: A in first position (and anything after).
  • [null, B]: Anything in first position and B in second position (and anything after).
  • [A, B]: A in first position and B in second position (and anything after).
  • [[A, B], [A, B]]: (A or B) in first position and (A or B) in second position (and anything after).

To learn more about how log topics work, check out this tutorial.

Request

// initiate websocket stream first
wscat -c wss://eth-mainnet.g.alchemy.com/v2/demo

// then call subscription 
{"jsonrpc":"2.0","id": 1, "method": "eth_subscribe", "params": ["logs", {"address": "0xa0b86991c6218b36c1d19d4a2e9eb0ce3606eb48", "topics": ["0xddf252ad1be2c89b69c2b068fc378daa952ba7f163c4a11628f55a4df523b3ef"]}]}
import { Alchemy, Network } from "alchemy-sdk";
import { ethers } from "ethers";

const settings = {
  apiKey: "demo", // Replace with your Alchemy API Key.
  network: Network.ETH_MAINNET, // Replace with your network.
};
const alchemy = new Alchemy(settings);

// This filter could also be generated with the Contract or
// Interface API. If address is not specified, any address
// matches and if topics is not specified, any log matches
const filter = {
  address: "dai.tokens.ethers.eth",
  topics: [ethers.utils.id("Transfer(address,address,uint256)")],
};

alchemy.ws.on(filter, (log, event) => {
  // Emitted whenever a DAI token transfer occurs
});

// Notice this is an array of topic-sets and is identical to
// using a filter with no address (i.e. match any address)
const topicSets = [
  ethers.utils.id("Transfer(address,address,uint256)"),
  null,
  [address1, address2],
];

alchemy.ws.on(topicSets, (log, event) => {
  // Emitted any token is sent TO either address
});

Result

{
    "jsonrpc":"2.0",
    "id":1,
    "result":"0x4a8a4c0517381924f9838102c5a4dcb7"
}

{
    "jsonrpc":"2.0",
    "method":"eth_subscription",
    "params": {
        "subscription":"0x4a8a4c0517381924f9838102c5a4dcb7",
        "result":{
            "address":"0x8320fe7702b96808f7bbc0d4a888ed1468216cfd",
            "blockHash":"0x61cdb2a09ab99abf791d474f20c2ea89bf8de2923a2d42bb49944c8c993cbf04",
            "blockNumber":"0x29e87",
            "data":"0x00000000000000000000000000000000000000000000000000000000000000010000000000000000000000000000000000000000000000000000000000000003",
            "logIndex":"0x0",
            "topics":["0xd78a0cb8bb633d06981248b816e7bd33c2a35a6089241d099fa519e361cab902"],
            "transactionHash":"0xe044554a0a55067caafd07f8020ab9f2af60bdfe337e395ecd84b4877a3d1ab4",
            "transactionIndex":"0x0"
        }
    }
}