TopicFilter

type TopicEntry = HashType | readonly HashType[] | null;

type TopicFilterType = readonly [
  TopicEntry?,
  TopicEntry?,
  TopicEntry?,
  TopicEntry?
] & {
  readonly [brand]: "TopicFilter";
};

event Transfer(address indexed from, address indexed to, uint256 value);
//              topic1             topic2           (not indexed, in data)

import * as TopicFilter from './primitives/TopicFilter/index.js';
import { Hash } from './primitives/Hash/index.js';

// Match specific event
const filter = TopicFilter.from([eventSigHash]);

// Match with wildcards
const filter2 = TopicFilter.from([eventSigHash, null, recipientHash]);

// Match any of multiple values (OR)
const filter3 = TopicFilter.from([[eventSig1, eventSig2]]);

const isMatch = TopicFilter.matches(filter, log.topics);

// Filter: [eventSig, null, recipientHash]
TopicFilter.matches(filter, [eventSig, senderHash, recipientHash]); // true
TopicFilter.matches(filter, [eventSig, anyHash, recipientHash]);    // true
TopicFilter.matches(filter, [eventSig, anyHash, wrongHash]);        // false

// Filter: [[eventSig1, eventSig2], null]
TopicFilter.matches(filter, [eventSig1, anyHash]); // true
TopicFilter.matches(filter, [eventSig2, anyHash]); // true
TopicFilter.matches(filter, [eventSig3, anyHash]); // false

const empty = TopicFilter.isEmpty(filter);

// ALL non-null positions must match
const filter = TopicFilter.from([hash1, hash2, hash3]);

// Matches: topics must be [hash1, hash2, hash3]
// Does NOT match: [hash1, hash2, wrongHash]

// ANY hash in array matches
const filter = TopicFilter.from([[hash1, hash2]]);

// Matches: [hash1, ...] OR [hash2, ...]
// Does NOT match: [hash3, ...]

// null matches anything
const filter = TopicFilter.from([hash1, null, hash3]);

// Matches: [hash1, ANYTHING, hash3]

import { EventSignature } from './primitives/EventSignature/index.js';

// Transfer(address,address,uint256)
const transferSig = EventSignature.fromSignature(
  "Transfer(address,address,uint256)"
);
const filter = TopicFilter.from([transferSig]);

const senderHash = Address.from("0x...").toBytes32();
const filter = TopicFilter.from([transferSig, senderHash]);

const recipientHash = Address.from("0x...").toBytes32();
const filter = TopicFilter.from([transferSig, null, recipientHash]);

// Match Transfer OR Approval
const filter = TopicFilter.from([[transferSig, approvalSig]]);

// From addr1 OR to addr1
const addr1Hash = Address.from("0x...").toBytes32();
const filter = TopicFilter.from([
  transferSig,
  [addr1Hash], // from addr1
  [addr1Hash]  // OR to addr1
]);

// Node first checks bloom filter
if (block.logsBloom.mightContainTopic(topic)) {
  // Only then scan actual logs
  const logs = block.logs.filter(log =>
    TopicFilter.matches(filter, log.topics)
  );
}

import * as TopicFilter from './primitives/TopicFilter/index.js';
import * as LogFilter from './primitives/LogFilter/index.js';
import { EventSignature } from './primitives/EventSignature/index.js';
import { Address } from './primitives/Address/index.js';

// Uniswap V2 Swap event
const swapSig = EventSignature.fromSignature(
  "Swap(address,uint256,uint256,uint256,uint256,address)"
);

// WETH address as topic (if indexed)
const wethAddr = Address.from("0xC02aaA39b223FE8D0A0e5C4F27eAD9083C756Cc2");
const wethHash = wethAddr.toBytes32();

// Match swaps involving WETH
const topics = TopicFilter.from([
  swapSig,
  null,              // any sender
  [wethHash, null]   // WETH as token0 OR token1
]);

const filter = LogFilter.from({
  fromBlock: "latest",
  topics
});

// Poll for new swaps
const logs = await rpc.eth_getLogs(filter);

// FAST: Specific event + address
const filter1 = TopicFilter.from([eventSig, addrHash]);

// SLOWER: Event only (many addresses to check)
const filter2 = TopicFilter.from([eventSig]);

// SLOWEST: Wildcard (bloom filter can't help)
const filter3 = TopicFilter.from([null]);