From 57cd8158959a47255b690def5900a1278332d441 Mon Sep 17 00:00:00 2001
From: init4samwise <samwise@init4.technology>
Date: Mon, 16 Feb 2026 03:06:09 +0000
Subject: [PATCH] feat: add OrderEvent, FilledEvent, SweepEvent type exports

Add typed event result interfaces for RollupOrders contract events
to improve DX for indexers using viem's parseEventLogs.

- Create src/types/events.ts with OrderEvent, FilledEvent, SweepEvent
- Export types from src/types/index.ts and main src/index.ts
- Document viem parseEventLogs usage pattern in README
- Update CHANGELOG.md

Closes ENG-1893
---
 CHANGELOG.md        |  1 +
 README.md           | 50 +++++++++++++++++++++++++++++++++++++++++++++
 src/index.ts        |  3 +++
 src/types/events.ts | 39 +++++++++++++++++++++++++++++++++++
 src/types/index.ts  |  2 ++
 5 files changed, 95 insertions(+)
 create mode 100644 src/types/events.ts

diff --git a/CHANGELOG.md b/CHANGELOG.md
index 3ff8c12..67cc825 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -13,6 +13,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 - `tokenDecimals` field on `SignetSystemConstants` for testnet overrides
 - PARMIGIANA now includes `tokenDecimals: { WUSD: 18 }` override
 - `Flow` type export (`"passage"` | `"orders"`)
+- `OrderEvent`, `FilledEvent`, `SweepEvent` typed event result interfaces for `parseEventLogs` DX
 - RPC Patterns documentation section in README
 
 ### Changed
diff --git a/README.md b/README.md
index 14d8591..68c5d7d 100644
--- a/README.md
+++ b/README.md
@@ -280,6 +280,53 @@ const serialized = serializeCallBundle(callBundle);
 // Use with signet_callBundle RPC method
 ```
 
+### Parsing RollupOrders Events
+
+Use viem's `parseEventLogs` with the SDK's ABI and event types for typed event indexing:
+
+```typescript
+import { createPublicClient, http, parseEventLogs } from "viem";
+import {
+  rollupOrdersAbi,
+  MAINNET,
+  type OrderEvent,
+  type FilledEvent,
+  type SweepEvent,
+} from "@signet-sh/sdk";
+
+const client = createPublicClient({ chain, transport: http(rpcUrl) });
+
+// Fetch logs from a block range
+const logs = await client.getLogs({
+  address: MAINNET.rollupOrders,
+  fromBlock: 100n,
+  toBlock: 200n,
+});
+
+// Parse all RollupOrders events with full type safety
+const events = parseEventLogs({ abi: rollupOrdersAbi, logs });
+
+for (const event of events) {
+  switch (event.eventName) {
+    case "Order": {
+      const { deadline, inputs, outputs } = event.args as OrderEvent;
+      console.log(`Order with ${inputs.length} inputs, deadline ${deadline}`);
+      break;
+    }
+    case "Filled": {
+      const { outputs } = event.args as FilledEvent;
+      console.log(`Filled ${outputs.length} outputs`);
+      break;
+    }
+    case "Sweep": {
+      const { recipient, token, amount } = event.args as SweepEvent;
+      console.log(`Sweep ${amount} of ${token} to ${recipient}`);
+      break;
+    }
+  }
+}
+```
+
 ## RPC Patterns
 
 The SDK exports ABIs and token utilities. Use viem directly for RPC operations.
@@ -386,6 +433,9 @@ const balances = await Promise.all(
 - `Permit2Batch` - Permit2 batch transfer data
 - `Output` - Order output specification
 - `TokenPermissions` - Token permission for Permit2
+- `OrderEvent` - Parsed args from an `Order` event
+- `FilledEvent` - Parsed args from a `Filled` event
+- `SweepEvent` - Parsed args from a `Sweep` event
 - `Flow` - Entry mechanism type: `"passage"` or `"orders"`
 - `TokenSymbol` - Supported token symbols
 
diff --git a/src/index.ts b/src/index.ts
index 33be13b..7b181d0 100644
--- a/src/index.ts
+++ b/src/index.ts
@@ -58,8 +58,10 @@ export type {
   Bytes,
   CallBundleTransactionResult,
   ChainConfig,
+  FilledEvent,
   Hex,
   Input,
+  OrderEvent,
   Output,
   Permit2Batch,
   PermitBatchTransferFrom,
@@ -73,6 +75,7 @@ export type {
   SignetCallBundle,
   SignetCallBundleResponse,
   SignetEthBundle,
+  SweepEvent,
   TokenPermissions,
   UnsignedOrderParams,
 } from "./types/index.js";
diff --git a/src/types/events.ts b/src/types/events.ts
new file mode 100644
index 0000000..ee9421c
--- /dev/null
+++ b/src/types/events.ts
@@ -0,0 +1,39 @@
+/**
+ * Event result types for RollupOrders contract events.
+ * These types represent the `args` returned by viem's `parseEventLogs`.
+ */
+import type { Address } from "viem";
+
+import type { Input, Output } from "./primitives.js";
+
+/**
+ * Parsed args from an `Order` event emitted when an order is initiated.
+ */
+export interface OrderEvent {
+  /** Order expiration deadline (unix timestamp) */
+  readonly deadline: bigint;
+  /** Tokens offered by the user */
+  readonly inputs: readonly Input[];
+  /** Tokens the user wants to receive */
+  readonly outputs: readonly Output[];
+}
+
+/**
+ * Parsed args from a `Filled` event emitted when outputs are filled.
+ */
+export interface FilledEvent {
+  /** Outputs that were filled */
+  readonly outputs: readonly Output[];
+}
+
+/**
+ * Parsed args from a `Sweep` event emitted when tokens are swept.
+ */
+export interface SweepEvent {
+  /** Recipient of the swept tokens */
+  readonly recipient: Address;
+  /** Token contract address */
+  readonly token: Address;
+  /** Amount swept */
+  readonly amount: bigint;
+}
diff --git a/src/types/index.ts b/src/types/index.ts
index 33d2c2a..b9c4f0a 100644
--- a/src/types/index.ts
+++ b/src/types/index.ts
@@ -22,6 +22,8 @@ export type {
 
 export type { SignedFill } from "./fill.js";
 
+export type { FilledEvent, OrderEvent, SweepEvent } from "./events.js";
+
 export {
   OUTPUT_WITNESS_TYPE_STRING,
   PERMIT_BATCH_WITNESS_TRANSFER_FROM_TYPES,