@utxopia/sdk 0.1.0-alpha.2 → 0.1.0-alpha.4

package/src/events.ts

@@ -0,0 +1,384 @@
+/**
+ * Event parser for UTXOpia sol_log_data events
+ *
+ * Events are emitted by the on-chain program as base64-encoded log data.
+ * Transaction logs contain lines like: "Program data: <base64>"
+ * Each base64 segment decodes to one slice from sol_log_data.
+ *
+ * ## Events
+ *
+ * - 0x02 NullifierSpent: disc(1) + hash(32) + op_type(1) = 34 bytes
+ * - 0x03 StealthAnnouncement: disc(1) + type(1) + ephemeral(32) + amount(8) + commitment(32) + leaf_index(4) = 78 bytes
+ * - 0x0B NullifiersBatch: flat payload in single segment
+ * - 0x0C AnnouncementsBatch: flat payload in single segment
+ */
+
+/** Event discriminators matching contracts/programs/utxopia/src/utils/events.rs */
+export const EVENT_NULLIFIER_SPENT = 0x02;
+export const EVENT_STEALTH_ANNOUNCEMENT = 0x03;
+export const EVENT_NULLIFIERS_BATCH = 0x0b;
+export const EVENT_ANNOUNCEMENTS_BATCH = 0x0c;
+/** Phase 2: sender memo (XChaCha20-Poly1305 AEAD payload). */
+export const EVENT_SENDER_MEMO = 0x12;
+export const EVENT_BTC_ORIGIN_ATTESTATION = 0x15;
+/** Method-Y: auditor ciphertext emitted alongside every shielded deposit into a permissioned pool. */
+export const EVENT_AUDITOR_CIPHERTEXT = 0x16;
+
+/** Parsed nullifier spent event */
+export interface NullifierSpentEvent {
+  type: "nullifier_spent";
+  nullifierHash: Uint8Array; // 32 bytes
+  operationType: number;
+}
+
+/** Parsed stealth announcement event (includes token_id) */
+export interface StealthAnnouncementEvent {
+  type: "stealth_announcement";
+  announcementType: number; // 0=deposit, 1=transfer
+  ephemeralPub: Uint8Array; // 32 bytes
+  encryptedAmount: Uint8Array; // 8 bytes
+  commitment: Uint8Array; // 32 bytes
+  leafIndex: number;
+  tokenId?: Uint8Array; // 32 bytes (present for deposit/unshield, zero for private transfers)
+}
+
+/** Parsed sender memo event (Phase 2). */
+export interface SenderMemoEvent {
+  type: "sender_memo";
+  /** 24-byte XChaCha20 nonce. */
+  nonce: Uint8Array;
+  /** 56-byte ChaCha20 ciphertext + Poly1305 tag. */
+  ciphertextWithTag: Uint8Array;
+  /** Commitment of the output this memo covers (also AAD). */
+  commitment: Uint8Array;
+  /** Leaf index of the covered output (also AAD). */
+  leafIndex: number;
+}
+
+/**
+ * BTC origin attestation, emitted alongside every SPV-verified deposit.
+ * Lets third-party auditors anchor commitments to their on-chain BTC
+ * origin without trusting our backend.
+ *
+ * Layout matches the Rust `emit_btc_origin_attestation` in
+ * `contracts/programs/utxopia/src/utils/events.rs`.
+ */
+export interface BtcOriginAttestationEvent {
+  type: "btc_origin_attestation";
+  blockHeight: bigint;
+  /** Bitcoin deposit txid in internal byte order (same as `complete_deposit` instruction data). */
+  depositTxid: Uint8Array;
+  /** Sweep transaction's output index that paid the pool. */
+  sweepVout: number;
+  /** Commitment inserted into the JoinSplit tree for this deposit. */
+  commitment: Uint8Array;
+  /** Pool-received amount in satoshis (after sweep fees). */
+  amountSats: bigint;
+}
+
+/**
+ * Auditor ciphertext event (Method-Y permissioned pools).
+ *
+ * Emitted alongside every shielded deposit into a permissioned pool so that
+ * a designated auditor can decrypt note viewing data off-chain.
+ */
+export interface AuditorCiphertextEvent {
+  type: "auditor_ciphertext";
+  /** 32-byte Poseidon commitment of the shielded note. */
+  commitment: Uint8Array;
+  /** 112-byte encrypted blob: eph_pub(32) || nonce(24) || ciphertextWithTag(56). */
+  blob: Uint8Array;
+}
+
+export type ProgramEvent =
+  | NullifierSpentEvent
+  | StealthAnnouncementEvent
+  | SenderMemoEvent
+  | BtcOriginAttestationEvent
+  | AuditorCiphertextEvent;
+
+/**
+ * Parse a nullifier spent event from decoded sol_log_data segments.
+ * Expected: disc(1) + nullifier_hash(32) + op_type(1)
+ */
+export function parseNullifierSpentEvent(segments: Uint8Array[]): NullifierSpentEvent | null {
+  if (segments.length < 3) return null;
+  if (segments[0].length !== 1 || segments[0][0] !== EVENT_NULLIFIER_SPENT) return null;
+
+  const nullifierHash = segments[1];
+  if (nullifierHash.length !== 32) return null;
+
+  const opType = segments[2];
+  if (opType.length !== 1) return null;
+
+  return {
+    type: "nullifier_spent",
+    nullifierHash,
+    operationType: opType[0],
+  };
+}
+
+/**
+ * Parse a stealth announcement event from decoded sol_log_data segments.
+ * v1: disc(1) + type(1) + ephemeral_pub(32) + encrypted_amount(8) + commitment(32) + leaf_index(4) = 6 segments
+ * v2: + token_id(32) = 7 segments
+ */
+export function parseStealthAnnouncementEvent(segments: Uint8Array[]): StealthAnnouncementEvent | null {
+  if (segments.length < 6) return null;
+  if (segments[0].length !== 1 || segments[0][0] !== EVENT_STEALTH_ANNOUNCEMENT) return null;
+
+  const atype = segments[1];
+  if (atype.length !== 1) return null;
+
+  const ephemeralPub = segments[2];
+  if (ephemeralPub.length !== 32) return null;
+
+  const encryptedAmount = segments[3];
+  if (encryptedAmount.length !== 8) return null;
+
+  const commitment = segments[4];
+  if (commitment.length !== 32) return null;
+
+  const liBytes = segments[5];
+  if (liBytes.length !== 4) return null;
+  const view = new DataView(liBytes.buffer, liBytes.byteOffset, 4);
+  const leafIndex = view.getUint32(0, true);
+
+  // v2: token_id at segment 6
+  let tokenId: Uint8Array | undefined;
+  if (segments.length >= 7 && segments[6].length === 32) {
+    tokenId = segments[6];
+  }
+
+  return {
+    type: "stealth_announcement",
+    announcementType: atype[0],
+    ephemeralPub,
+    encryptedAmount,
+    commitment,
+    leafIndex,
+    tokenId,
+  };
+}
+
+/**
+ * Parse an association-set update event (Phase 3) from decoded sol_log_data segments.
+ * Layout: disc(1) + new_root(32) + status(1) + version_le(8)
+ */
+/**
+ * Parse a BTC origin attestation event from decoded sol_log_data segments.
+ * Layout: disc(1) + block_height(8 LE) + deposit_txid(32) + sweep_vout(4 LE)
+ *       + commitment(32) + amount_sats(8 LE)
+ */
+export function parseBtcOriginAttestationEvent(
+  segments: Uint8Array[],
+): BtcOriginAttestationEvent | null {
+  if (segments.length < 6) return null;
+  if (segments[0].length !== 1 || segments[0][0] !== EVENT_BTC_ORIGIN_ATTESTATION) return null;
+
+  const bhBytes = segments[1];
+  if (bhBytes.length !== 8) return null;
+  let blockHeight = 0n;
+  for (let i = 7; i >= 0; i--) blockHeight = (blockHeight << 8n) | BigInt(bhBytes[i]);
+
+  const depositTxid = segments[2];
+  if (depositTxid.length !== 32) return null;
+
+  const voutBytes = segments[3];
+  if (voutBytes.length !== 4) return null;
+  const sweepVout = new DataView(
+    voutBytes.buffer,
+    voutBytes.byteOffset,
+    4,
+  ).getUint32(0, true);
+
+  const commitment = segments[4];
+  if (commitment.length !== 32) return null;
+
+  const amtBytes = segments[5];
+  if (amtBytes.length !== 8) return null;
+  let amountSats = 0n;
+  for (let i = 7; i >= 0; i--) amountSats = (amountSats << 8n) | BigInt(amtBytes[i]);
+
+  return {
+    type: "btc_origin_attestation",
+    blockHeight,
+    depositTxid,
+    sweepVout,
+    commitment,
+    amountSats,
+  };
+}
+
+/**
+ * Parse a sender memo event (Phase 2) from decoded sol_log_data segments.
+ * Layout: disc(1) + nonce(24) + ciphertext_and_tag(56) + commitment(32) + leaf_index(4)
+ */
+export function parseSenderMemoEvent(segments: Uint8Array[]): SenderMemoEvent | null {
+  if (segments.length < 5) return null;
+  if (segments[0].length !== 1 || segments[0][0] !== EVENT_SENDER_MEMO) return null;
+
+  const nonce = segments[1];
+  if (nonce.length !== 24) return null;
+
+  const ciphertextWithTag = segments[2];
+  if (ciphertextWithTag.length !== 56) return null;
+
+  const commitment = segments[3];
+  if (commitment.length !== 32) return null;
+
+  const liBytes = segments[4];
+  if (liBytes.length !== 4) return null;
+  const leafIndex = new DataView(liBytes.buffer, liBytes.byteOffset, 4).getUint32(0, true);
+
+  return { type: "sender_memo", nonce, ciphertextWithTag, commitment, leafIndex };
+}
+
+/**
+ * Parse batched nullifiers from a single flat segment.
+ * Layout: disc(1) + count(1) + op_type(1) + [hash(32)] x count
+ */
+function parseNullifiersBatch(data: Uint8Array): NullifierSpentEvent[] {
+  if (data.length < 3) return [];
+  const count = data[1];
+  const opType = data[2];
+  const expectedLen = 3 + count * 32;
+  if (data.length < expectedLen) return [];
+
+  const events: NullifierSpentEvent[] = [];
+  for (let i = 0; i < count; i++) {
+    const offset = 3 + i * 32;
+    events.push({
+      type: "nullifier_spent",
+      nullifierHash: data.slice(offset, offset + 32),
+      operationType: opType,
+    });
+  }
+  return events;
+}
+
+/**
+ * Parse batched announcements from a single flat segment.
+ * v1: disc(1) + count(1) + [type(1) + ephemeral(32) + amount(8) + commitment(32) + leaf_index(4)] x count (77 per item)
+ * v2: disc(1) + count(1) + [type(1) + ephemeral(32) + amount(8) + commitment(32) + leaf_index(4) + token_id(32)] x count (109 per item)
+ */
+function parseAnnouncementsBatch(data: Uint8Array): StealthAnnouncementEvent[] {
+  if (data.length < 2) return [];
+  const count = data[1];
+  if (count === 0) return [];
+
+  // Detect v1 vs v2 by checking total size
+  const remainingBytes = data.length - 2;
+  const v2ItemSize = 109;
+  const v1ItemSize = 77;
+  const isV2 = remainingBytes >= count * v2ItemSize;
+  const itemSize = isV2 ? v2ItemSize : v1ItemSize;
+
+  const expectedLen = 2 + count * itemSize;
+  if (data.length < expectedLen) return [];
+
+  const events: StealthAnnouncementEvent[] = [];
+  for (let i = 0; i < count; i++) {
+    const offset = 2 + i * itemSize;
+    const liView = new DataView(data.buffer, data.byteOffset + offset + 73, 4);
+    const event: StealthAnnouncementEvent = {
+      type: "stealth_announcement",
+      announcementType: data[offset],
+      ephemeralPub: data.slice(offset + 1, offset + 33),
+      encryptedAmount: data.slice(offset + 33, offset + 41),
+      commitment: data.slice(offset + 41, offset + 73),
+      leafIndex: liView.getUint32(0, true),
+    };
+    if (isV2) {
+      event.tokenId = data.slice(offset + 77, offset + 109);
+    }
+    events.push(event);
+  }
+  return events;
+}
+
+/**
+ * Parse an auditor ciphertext event (Method-Y) from decoded sol_log_data segments.
+ * Layout: disc(1) + commitment(32) + blob(112)
+ */
+export function parseAuditorCiphertextEvent(segments: Uint8Array[]): AuditorCiphertextEvent | null {
+  if (segments.length < 3) return null;
+  if (segments[0].length !== 1 || segments[0][0] !== EVENT_AUDITOR_CIPHERTEXT) return null;
+
+  const commitment = segments[1];
+  if (commitment.length !== 32) return null;
+
+  const blob = segments[2];
+  if (blob.length !== 112) return null;
+
+  return { type: "auditor_ciphertext", commitment, blob };
+}
+
+
+function decodeBase64(b64: string): Uint8Array {
+  const binary = atob(b64);
+  const bytes = new Uint8Array(binary.length);
+  for (let i = 0; i < binary.length; i++) {
+    bytes[i] = binary.charCodeAt(i);
+  }
+  return bytes;
+}
+
+/**
+ * Parse program events from Solana transaction log messages.
+ *
+ * sol_log_data emits log lines in the format:
+ *   "Program data: <base64_segment1> <base64_segment2> ..."
+ *
+ * @param logs - Array of log message strings from a transaction
+ * @param programId - Optional program ID to filter events (matches "Program <id> invoke" blocks)
+ */
+export function parseProgramEvents(logs: string[], programId?: string): ProgramEvent[] {
+  const events: ProgramEvent[] = [];
+  const DATA_PREFIX = "Program data: ";
+
+  for (const line of logs) {
+    if (!line.startsWith(DATA_PREFIX)) continue;
+
+    const b64Parts = line.slice(DATA_PREFIX.length).split(" ");
+    const segments = b64Parts.map(decodeBase64);
+
+    if (segments.length === 0) continue;
+
+    // Handle batch events (single flat segment)
+    if (segments.length === 1 && segments[0].length > 1) {
+      const disc = segments[0][0];
+      if (disc === EVENT_NULLIFIERS_BATCH) {
+        events.push(...parseNullifiersBatch(segments[0]));
+        continue;
+      }
+      if (disc === EVENT_ANNOUNCEMENTS_BATCH) {
+        events.push(...parseAnnouncementsBatch(segments[0]));
+        continue;
+      }
+    }
+
+    if (segments[0].length !== 1) continue;
+
+    const disc = segments[0][0];
+
+    if (disc === EVENT_NULLIFIER_SPENT) {
+      const event = parseNullifierSpentEvent(segments);
+      if (event) events.push(event);
+    } else if (disc === EVENT_STEALTH_ANNOUNCEMENT) {
+      const event = parseStealthAnnouncementEvent(segments);
+      if (event) events.push(event);
+    } else if (disc === EVENT_SENDER_MEMO) {
+      const event = parseSenderMemoEvent(segments);
+      if (event) events.push(event);
+    } else if (disc === EVENT_BTC_ORIGIN_ATTESTATION) {
+      const event = parseBtcOriginAttestationEvent(segments);
+      if (event) events.push(event);
+    } else if (disc === EVENT_AUDITOR_CIPHERTEXT) {
+      const event = parseAuditorCiphertextEvent(segments);
+      if (event) events.push(event);
+    }
+  }
+
+  return events;
+}

package/src/explorer.ts

@@ -0,0 +1,300 @@
+/**
+ * Explorer utilities for UTXOPIA
+ *
+ * Types, parsers, and fetchers for browsing on-chain UTXOpia activity:
+ * - Deposits (from event indexer)
+ * - Transfers (from event indexer)
+ * - Redemptions (RedemptionRequest accounts)
+ */
+
+import type { RpcClient } from "./commitment-tree";
+
+// =============================================================================
+// Constants
+// =============================================================================
+
+/** NullifierRecord account size (1 byte — slim layout, just discriminator) */
+export const NULLIFIER_RECORD_SIZE = 1;
+
+/** RedemptionRequest account size (178 bytes):
+ *  disc(1) status(1) btc_script_len(1) signing_approved(1) processing_slot(4) request_id(8)
+ *  requester(32) amount_sats(8) service_fee(8) total_input_sats(8) btc_script(34)
+ *  token_id(32) reserved_count(1) approved_inputs(4) _padding2(3) inputs_commitment(32).
+ *
+ *  This is a `dataSize` filter, so a stale value silently returns nothing rather than failing:
+ *  it sat at 138 — the struct's length before reserved_count/approved_inputs/inputs_commitment
+ *  were added — and matched no account on chain. `RedemptionRequest::LEN` is pinned by a test
+ *  on the program side; update both together. Field offsets below are unaffected. */
+export const REDEMPTION_REQUEST_SIZE = 178;
+
+/** NullifierRecord discriminator byte */
+export const NULLIFIER_RECORD_DISCRIMINATOR = 0x03;
+
+/** RedemptionRequest discriminator byte */
+export const REDEMPTION_REQUEST_DISCRIMINATOR = 0x04;
+
+/** Max plausible plaintext amount: 21M BTC in sats */
+const MAX_PLAINTEXT_SATS = 21_000_000n * 100_000_000n;
+
+/** Human-readable labels for nullifier operation types */
+export const OPERATION_TYPE_LABELS: Record<number, string> = {
+  0: "Full Withdrawal",
+  1: "Partial Withdrawal",
+  2: "Private Transfer",
+  3: "Transfer",
+  4: "Split",
+  5: "Join",
+};
+
+// =============================================================================
+// Types
+// =============================================================================
+
+/** Parsed deposit from indexer event data */
+export interface ExplorerDeposit {
+  pubkey: string;
+  amountSats: bigint;
+  leafIndex: bigint;
+  /** Commitment hex (from indexer events, not on-chain) */
+  commitment?: string;
+  /** Unix timestamp (from indexer events, not on-chain) */
+  createdAt?: number;
+  /** Ephemeral public key hex (from stealth announcement) */
+  ephemeralPub?: string;
+  /** Solana transaction signature */
+  txSignature?: string;
+}
+
+/** Transfer event — either a new commitment or a spent nullifier */
+export interface ExplorerTransferEvent {
+  type: "commitment" | "nullifier";
+  pubkey: string;
+  timestamp: number;
+  commitment?: string;
+  leafIndex?: bigint;
+  nullifierHash?: string;
+  operationType?: string;
+  spentBy?: string;
+}
+
+/** Parsed redemption request */
+export interface ExplorerRedemption {
+  pubkey: string;
+  requestId: bigint;
+  amountSats: bigint;
+  /** Service fee in satoshis, locked at request time */
+  serviceFee: bigint;
+  status: "Pending" | "Processing" | "Failed";
+  requester: string;
+  btcScript: string;
+  /** Slot when processing started (from PDA data[4..8]) — 0 if still Pending */
+  processingSlot: number;
+}
+
+// =============================================================================
+// Helpers
+// =============================================================================
+
+function toHex(bytes: Uint8Array): string {
+  return Array.from(bytes)
+    .map((b) => b.toString(16).padStart(2, "0"))
+    .join("");
+}
+
+function readU64LE(data: Uint8Array, offset: number): bigint {
+  const view = new DataView(data.buffer, data.byteOffset, data.byteLength);
+  return view.getBigUint64(offset, true);
+}
+
+function readI64LE(data: Uint8Array, offset: number): number {
+  const view = new DataView(data.buffer, data.byteOffset, data.byteLength);
+  return Number(view.getBigInt64(offset, true));
+}
+
+function bs58Encode(bytes: Uint8Array): string {
+  const ALPHABET = "123456789ABCDEFGHJKLMNPQRSTUVWXYZabcdefghijkmnopqrstuvwxyz";
+  let num = 0n;
+  for (const byte of bytes) {
+    num = num * 256n + BigInt(byte);
+  }
+  let encoded = "";
+  while (num > 0n) {
+    const remainder = num % 58n;
+    num = num / 58n;
+    encoded = ALPHABET[Number(remainder)] + encoded;
+  }
+  for (const byte of bytes) {
+    if (byte === 0) encoded = "1" + encoded;
+    else break;
+  }
+  return encoded || "1";
+}
+
+function decodeBase64(b64: string): Uint8Array {
+  const binary = atob(b64);
+  const bytes = new Uint8Array(binary.length);
+  for (let i = 0; i < binary.length; i++) {
+    bytes[i] = binary.charCodeAt(i);
+  }
+  return bytes;
+}
+
+// =============================================================================
+// Parsers
+// =============================================================================
+
+/** Parse a NullifierRecord account (1 byte — slim layout)
+ * Only confirms existence (discriminator = 0x03). Metadata from indexer events. */
+export function parseNullifierRecord(
+  pubkey: string,
+  _data: Uint8Array
+): ExplorerTransferEvent {
+  return {
+    type: "nullifier",
+    pubkey,
+    timestamp: 0, // metadata available from indexer
+  };
+}
+
+/** Parse a RedemptionRequest account (138 bytes, raw scriptPubKey) */
+export function parseRedemptionRequest(
+  pubkey: string,
+  data: Uint8Array
+): ExplorerRedemption {
+  const statusByte = data[1];
+  const status: ExplorerRedemption["status"] =
+    statusByte === 1 ? "Processing" : statusByte === 2 ? "Failed" : "Pending";
+  const scriptLen = data[2];
+  // data[3] = padding, data[4..8] = processing_slot (u32 LE)
+  const view = new DataView(data.buffer, data.byteOffset, data.byteLength);
+  const processingSlot = view.getUint32(4, true);
+
+  return {
+    pubkey,
+    requestId: readU64LE(data, 8),
+    amountSats: readU64LE(data, 48),
+    serviceFee: readU64LE(data, 56),
+    status,
+    requester: bs58Encode(data.slice(16, 48)),
+    // btc_script starts at offset 72 (after total_input_sats at 64..72).
+    btcScript: toHex(data.slice(72, 72 + Math.min(scriptLen, 34))),
+    processingSlot,
+  };
+}
+
+// =============================================================================
+// RPC helpers
+// =============================================================================
+
+async function fetchAccountsBySize(
+  rpc: RpcClient,
+  programId: string,
+  dataSize: number
+): Promise<{ pubkey: string; data: Uint8Array }[]> {
+  const accounts = await rpc.getProgramAccounts(programId, {
+    filters: [{ dataSize }],
+    encoding: "base64",
+  });
+
+  return accounts.map((acc) => {
+    const raw =
+      typeof acc.account.data === "string"
+        ? acc.account.data
+        : // @solana/kit returns [base64String, "base64"]
+          (acc.account.data as unknown as string[])[0];
+    return {
+      pubkey: String(acc.pubkey),
+      data: decodeBase64(raw),
+    };
+  });
+}
+
+// =============================================================================
+// Fetchers
+// =============================================================================
+
+/** Indexer leaf data for enriching explorer deposits */
+export interface IndexerLeaf {
+  leaf_index: number;
+  commitment: string; // hex
+  created_at: number; // unix timestamp
+  announcement_type?: number; // 0=deposit, 1=transfer
+  amount_sats?: number; // plaintext amount (deposits only)
+  ephemeral_pub?: string; // hex (from stealth announcement)
+  tx_signature?: string; // Solana tx signature
+}
+
+/** Fetch all deposit announcements from indexer data */
+export async function fetchExplorerDeposits(
+  _rpc: RpcClient,
+  _programId: string,
+  indexerLeaves?: IndexerLeaf[]
+): Promise<ExplorerDeposit[]> {
+  if (!indexerLeaves || indexerLeaves.length === 0) return [];
+
+  return indexerLeaves
+    .filter((leaf) => leaf.announcement_type === 0) // deposits only
+    .map((leaf) => ({
+      pubkey: "", // no PDA — data comes from events
+      amountSats: BigInt(leaf.amount_sats ?? 0),
+      leafIndex: BigInt(leaf.leaf_index),
+      commitment: leaf.commitment,
+      createdAt: leaf.created_at,
+      ephemeralPub: leaf.ephemeral_pub,
+      txSignature: leaf.tx_signature,
+    }))
+    .sort((a, b) => {
+      const aHasTime = (a.createdAt ?? 0) > 0;
+      const bHasTime = (b.createdAt ?? 0) > 0;
+      if (aHasTime && bHasTime) return (b.createdAt ?? 0) - (a.createdAt ?? 0);
+      if (aHasTime && !bHasTime) return -1;
+      if (!aHasTime && bHasTime) return 1;
+      return Number(b.leafIndex - a.leafIndex);
+    });
+}
+
+/** Fetch all transfer events from indexer data */
+export async function fetchExplorerTransfers(
+  _rpc: RpcClient,
+  _programId: string,
+  indexerLeaves?: IndexerLeaf[]
+): Promise<ExplorerTransferEvent[]> {
+  if (!indexerLeaves || indexerLeaves.length === 0) return [];
+
+  const events: ExplorerTransferEvent[] = [];
+
+  for (const leaf of indexerLeaves) {
+    if (leaf.announcement_type === 0) continue; // skip deposits
+    events.push({
+      type: "commitment",
+      pubkey: "",
+      timestamp: leaf.created_at ?? 0,
+      commitment: leaf.commitment,
+      leafIndex: BigInt(leaf.leaf_index),
+    });
+  }
+
+  // Sort by timestamp descending (most recent first); if no timestamp, by leafIndex high→low
+  events.sort((a, b) => {
+    const aHasTime = a.timestamp > 0;
+    const bHasTime = b.timestamp > 0;
+    if (aHasTime && bHasTime) return b.timestamp - a.timestamp;
+    if (aHasTime && !bHasTime) return -1;
+    if (!aHasTime && bHasTime) return 1;
+    return Number((b.leafIndex ?? 0n) - (a.leafIndex ?? 0n));
+  });
+
+  return events;
+}
+
+/** Fetch all redemption requests */
+export async function fetchExplorerRedemptions(
+  rpc: RpcClient,
+  programId: string
+): Promise<ExplorerRedemption[]> {
+  const accounts = await fetchAccountsBySize(rpc, programId, REDEMPTION_REQUEST_SIZE);
+
+  return accounts
+    .map(({ pubkey, data }) => parseRedemptionRequest(pubkey, data))
+    .sort((a, b) => Number(b.requestId - a.requestId));
+}