Event decoders

Decode on-chain logs into typed event objects.

Utilities for decoding raw eth_getLogs entries into typed event objects.

Import

import {
  decodeOnChainEvents,
  TOKEN_TOPICS,
  decodeConfidentialTransfer,
  decodeWrap,
  decodeUnwrapRequested,
  decodeUnwrapFinalized,
  findWrap,
  findUnwrapRequested,
  // ACL delegation events
  ACL_TOPICS,
  decodeDelegatedForUserDecryption,
  decodeRevokedDelegationForUserDecryption,
  decodeAclEvent,
  decodeAclEvents,
  findDelegatedForUserDecryption,
  findRevokedDelegationForUserDecryption,
} from "@zama-fhe/sdk";

decodeOnChainEvents

(logs: RawLog[]) => OnChainEvent[]

Decodes an array of raw log entries into typed event objects. Each returned event has an .eventName discriminator.

const logs = await publicClient.getLogs({ address: tokenAddress, topics: [TOKEN_TOPICS] });

const events = decodeOnChainEvents(logs);

for (const event of events) {
  switch (event.eventName) {
    case "ConfidentialTransfer":
      console.log(event.from, event.to, event.encryptedAmount);
      break;
    case "Wrap":
      console.log(event.to, event.roundedAmount, event.encryptedWrappedAmount);
      break;
    case "UnwrapRequested":
      console.log(event.receiver, event.unwrapRequestId);
      break;
    case "UnwrapFinalized":
      console.log(event.receiver, event.cleartextAmount);
      break;
  }
}

Parameter	Type	Description
logs	RawLog[]	Raw log entries from eth_getLogs or a transaction receipt

Returns: OnChainEvent[] — each event has an .eventName of "ConfidentialTransfer", "Wrap", "UnwrapRequested", or "UnwrapFinalized".

A shield emits both a ConfidentialTransfer(from=zeroAddress, …) and a Wrap event. Wrap.encryptedWrappedAmount is the same FHE handle as the co-emitted ConfidentialTransfer.encryptedAmount — use Wrap as the shield marker (it carries the cleartext roundedAmount) and correlate the two halves rather than counting both.

TOKEN_TOPICS

Hex[]

Array of topic hashes for all supported token events. Pass this to eth_getLogs to fetch relevant logs in a single RPC call.

const logs = await publicClient.getLogs({
  address: tokenAddress,
  topics: [TOKEN_TOPICS],
  fromBlock: startBlock,
  toBlock: "latest",
});

Individual decoders

Each decoder takes a single log entry and returns a typed event object, or null if the log does not match.

Decoder	Event type	Description
decodeConfidentialTransfer(log)	ConfidentialTransfer	Encrypted transfer between accounts
decodeWrap(log)	Wrap	Tokens wrapped (shielded)
decodeUnwrapRequested(log)	UnwrapRequested	Unwrap initiated; includes unwrapRequestId
decodeUnwrapFinalized(log)	UnwrapFinalized	Unwrap completed; includes unwrapRequestId

import { decodeConfidentialTransfer } from "@zama-fhe/sdk";

for (const log of receipt.logs) {
  const transfer = decodeConfidentialTransfer(log);
  if (transfer) {
    console.log(`Transfer from ${transfer.from} to ${transfer.to}`);
  }
}

Convenience finders

Search a log array and return the first matching event.

findWrap

(logs: RawLog[]) => WrapEvent | null

Finds the first Wrap event in a set of logs. Useful after a shield transaction.

import { findWrap } from "@zama-fhe/sdk";

const receipt = await walletClient.waitForTransactionReceipt({ hash: txHash });
const wrapEvent = findWrap(receipt.logs);
if (wrapEvent) {
  console.log(`Wrapped ${wrapEvent.roundedAmount} tokens`);
}

findUnwrapRequested

(logs: RawLog[]) => UnwrapRequestedEvent | null

Finds the first UnwrapRequested event in a set of logs. Useful after an unshield initiation.

import { findUnwrapRequested } from "@zama-fhe/sdk";

const unwrapEvent = findUnwrapRequested(receipt.logs);
if (unwrapEvent) {
  console.log(`Unwrap requested for ${unwrapEvent.encryptedAmount}`);
}

ACL delegation events

The ACL contract emits events when delegations are created or revoked. These are separate from token events — they use their own topic hashes and decoders.

Import

import {
  ACL_TOPICS,
  AclTopics,
  decodeDelegatedForUserDecryption,
  decodeRevokedDelegationForUserDecryption,
  decodeAclEvent,
  decodeAclEvents,
  findDelegatedForUserDecryption,
  findRevokedDelegationForUserDecryption,
} from "@zama-fhe/sdk";

ACL_TOPICS

Hex[]

Array of topic hashes for both ACL delegation events. Pass this to eth_getLogs to fetch delegation events from the ACL contract.

const logs = await publicClient.getLogs({
  address: aclAddress,
  topics: [ACL_TOPICS],
  fromBlock: startBlock,
  toBlock: "latest",
});

Individual decoders

Decoder	Event type	Description
decodeDelegatedForUserDecryption(log)	DelegatedForUserDecryption	Delegation created or renewed
decodeRevokedDelegationForUserDecryption(log)	RevokedDelegationForUserDecryption	Delegation revoked

DelegatedForUserDecryptionEvent

Field	Type	Description
eventName	string	"DelegatedForUserDecryption"
delegator	Address	Account granting access
delegate	Address	Account receiving access
contractAddress	Address	Contract the delegation applies to
delegationCounter	bigint	Monotonic delegation counter
oldExpirationDate	bigint	Previous expiration (0 if first delegation)
newExpirationDate	bigint	New expiration timestamp

RevokedDelegationForUserDecryptionEvent

Field	Type	Description
eventName	string	"RevokedDelegationForUserDecryption"
delegator	Address	Account that granted access
delegate	Address	Account that had access
contractAddress	Address	Contract the revocation applies to
delegationCounter	bigint	Monotonic delegation counter
oldExpirationDate	bigint	Expiration date before revocation

Convenience finders

Finder	Returns
findDelegatedForUserDecryption(logs)	First DelegatedForUserDecryptionEvent or null
findRevokedDelegationForUserDecryption(logs)	First RevokedDelegationForUserDecryptionEvent or null

Batch decoders

Decoder	Description
decodeAclEvent(log)	Try both ACL decoders on a single log, return first match
decodeAclEvents(logs)	Batch-decode an array of logs, skipping unrecognized entries

ACL delegation events are not included in TOKEN_TOPICS or decodeOnChainEvents. They are emitted by the ACL contract, not by token contracts. Use ACL_TOPICS and decodeAclEvents separately.

Related

• Decrypt values from event logs — decrypt the encrypted amounts these decoders return

• Delegated Decryption — delegation API with on-chain event examples

• Token — high-level API for token operations