Creating a proper type for ots_traceTransaction

Actually utilizing the OtsAddressTransactionsPage type for searchTransactionsBefore/After

Addressing 2 notes from Otterscan maintainer: the page numbers will be ascending/descending based on search direction, and updating the docstrings to note the pageSize limit is a soft limit

Author: k-thornton

src.ts/_tests/test-providers-otterscan.ts

@@ -7,6 +7,7 @@ import type {
     OtsBlockDetails,
     OtsBlockTransactionsPage,
     OtsAddressTransactionsPage,
+    OtsTraceEntry,
     OtsContractCreator
 } from "../providers/provider-otterscan.js";
 
@@ -44,7 +45,32 @@ describe("Test Otterscan Provider", function () {
                     result = "0x";
                     break;
                 case "ots_traceTransaction":
-                    result = { calls: [] };
+                    result = [
+                        {
+                            type: "CALL",
+                            depth: 0,
+                            from: "0x737d16748aa3f93d6ff1b0aefa3eca7fffca868e",
+                            to: "0x545ec8c956d307cc3bf7f9ba1e413217eff1bc7a",
+                            value: "0x0",
+                            input: "0xff02000000000000001596d80c86b939000000000000000019cfaf37a98833fed61000a72a288205ead800f1978fc2d943013f0e9f56d3a1077a294dde1b09bb078844df40758a5d0f9a27017ed0000000011e00000300000191ccf22538c30f09d14be27569c5bdb61f99b3c9f33c0bb40d1bbf6eafaaea2adfb7d2d3ebc1e49c01857e0000000000000000"
+                        },
+                        {
+                            type: "DELEGATECALL",
+                            depth: 1,
+                            from: "0x545ec8c956d307cc3bf7f9ba1e413217eff1bc7a",
+                            to: "0x998f7f745f61a910da86d8aa65db60b67a40da6d",
+                            value: null,
+                            input: "0x5697217300000000000000000000000000000000000000000000000000000000000000200000000000000000000000000000000000000000000000000000000000000036a72a288205ead800f1978fc2d943013f0e9f56d3a1077a294dde1b09bb078844df40758a5d0f9a27017ed0000000011e000003000001"
+                        },
+                        {
+                            type: "STATICCALL", 
+                            depth: 2,
+                            from: "0x545ec8c956d307cc3bf7f9ba1e413217eff1bc7a",
+                            to: "0x91ccf22538c30f09d14be27569c5bdb61f99b3c9",
+                            value: null,
+                            input: "0x0902f1ac"
+                        }
+                    ];
                     break;
                 case "ots_getBlockDetails":
                     result = {
@@ -221,8 +247,24 @@ describe("Test Otterscan Provider", function () {
     it("should trace transaction", async function () {
         const provider = createMockOtsProvider();
         const trace = await provider.traceTransaction("0x123");
-        assert(typeof trace === "object", "should return trace object");
-        assert(Array.isArray(trace.calls), "should have calls array");
+        assert(Array.isArray(trace), "should return array of trace entries");
+        assert.strictEqual(trace.length, 3, "should have three trace entries");
+
+        const firstEntry = trace[0];
+        assert.strictEqual(firstEntry.type, "CALL", "first entry should be CALL");
+        assert.strictEqual(firstEntry.depth, 0, "first entry should have depth 0");
+        assert.strictEqual(firstEntry.from, "0x737d16748aa3f93d6ff1b0aefa3eca7fffca868e", "should have correct from");
+        assert.strictEqual(firstEntry.to, "0x545ec8c956d307cc3bf7f9ba1e413217eff1bc7a", "should have correct to");
+        assert.strictEqual(firstEntry.value, "0x0", "should have correct value");
+        assert(firstEntry.input?.startsWith("0xff02"), "should have input data");
+        
+        const delegateCall = trace[1];
+        assert.strictEqual(delegateCall.type, "DELEGATECALL", "second entry should be DELEGATECALL");
+        assert.strictEqual(delegateCall.value, null, "delegatecall should have null value");
+        
+        const staticCall = trace[2];
+        assert.strictEqual(staticCall.type, "STATICCALL", "third entry should be STATICCALL");
+        assert.strictEqual(staticCall.value, null, "staticcall should have null value");
     });
 
     it("should get block details", async function () {
@@ -319,6 +361,7 @@ describe("Test Otterscan Provider", function () {
         const blockDetails: OtsBlockDetails = await provider.getBlockDetails(4096);
         const blockTxs: OtsBlockTransactionsPage = await provider.getBlockTransactions(4096, 0, 10);
         const searchResults: OtsAddressTransactionsPage = await provider.searchTransactionsBefore("0x123", 4096, 10);
+        const traceEntries: OtsTraceEntry[] = await provider.traceTransaction("0x123");
         const creator: OtsContractCreator | null = await provider.getContractCreator("0x123");
 
         // Basic type assertions
@@ -328,6 +371,7 @@ describe("Test Otterscan Provider", function () {
         assert(typeof blockDetails === "object");
         assert(typeof blockTxs === "object" && Array.isArray(blockTxs.transactions));
         assert(typeof searchResults === "object" && Array.isArray(searchResults.txs));
+        assert(Array.isArray(traceEntries));
         assert(creator === null || typeof creator === "object");
     });
 });

src.ts/ethers.ts

@@ -180,7 +180,7 @@ export type {
     MinedBlock, MinedTransactionResponse, Networkish, OrphanFilter,
     OtsTransactionReceiptParams, OtsBlockTransactionReceipt,
     OtsBlockParams, OtsInternalOp, OtsBlockDetails, OtsBlockTransactionsPage,
-    OtsAddressTransactionsPage, OtsContractCreator,
+    OtsAddressTransactionsPage, OtsTraceEntry, OtsContractCreator,
     PerformActionFilter, PerformActionRequest, PerformActionTransaction,
     PreparedTransactionRequest, ProviderEvent, Subscriber, Subscription,
     TopicFilter, TransactionReceiptParams, TransactionRequest,

src.ts/providers/index.ts

@@ -62,7 +62,7 @@ export { OtterscanProvider } from "./provider-otterscan.js";
 export type {
     OtsTransactionReceiptParams, OtsBlockTransactionReceipt,
     OtsBlockParams, OtsInternalOp, OtsBlockDetails, OtsBlockTransactionsPage,
-    OtsAddressTransactionsPage, OtsContractCreator
+    OtsAddressTransactionsPage, OtsTraceEntry, OtsContractCreator
 } from "./provider-otterscan.js";
 
 export { BrowserProvider } from "./provider-browser.js";

src.ts/providers/provider-otterscan.ts

@@ -99,6 +99,24 @@ export interface OtsAddressTransactionsPage {
     lastPage: boolean;
 }
 
+/**
+ * Trace entry from ots_traceTransaction
+ */
+export interface OtsTraceEntry {
+    /** Type of operation (CALL, DELEGATECALL, STATICCALL, CREATE, etc.) */
+    type: string;
+    /** Call depth in the execution stack */
+    depth: number;
+    /** Source address */
+    from: string;
+    /** Target address */
+    to: string;
+    /** Value transferred (hex string, null for delegate/static calls) */
+    value: string | null;
+    /** Input data for the call */
+    input?: string;
+}
+
 /**
  * Contract creator information
  */
@@ -212,9 +230,9 @@ export class OtterscanProvider extends JsonRpcProvider {
     /**
      * Get execution trace for a transaction
      * @param txHash - Transaction hash
-     * @returns Trace data
+     * @returns Array of trace entries showing call execution flow
      */
-    async traceTransaction(txHash: string): Promise<any> {
+    async traceTransaction(txHash: string): Promise<OtsTraceEntry[]> {
         return await this.send("ots_traceTransaction", [txHash]);
     }
 
@@ -243,7 +261,7 @@ export class OtterscanProvider extends JsonRpcProvider {
      * Removes verbose fields like logs from receipts to save bandwidth
      * @param blockNumber - Block number
      * @param page - Page number (0-based)
-     * @param pageSize - Number of transactions per page
+     * @param pageSize - Soft limit on transactions per page (actual results may exceed this if a block contains more transactions)
      * @returns Page of transactions and receipts (with logs removed)
      */
     async getBlockTransactions(blockNumber: number, page: number, pageSize: number): Promise<OtsBlockTransactionsPage> {
@@ -255,24 +273,19 @@ export class OtterscanProvider extends JsonRpcProvider {
      * Provides paginated transaction history with in-node search (no external indexer needed)
      * @param address - Address to search for
      * @param blockNumber - Starting block number
-     * @param pageSize - Maximum results to return
+     * @param pageSize - Soft limit on results to return (actual results may exceed this if a block contains more transactions)
      * @returns Page of transactions and receipts
      */
     async searchTransactionsBefore(
         address: string,
         blockNumber: number,
         pageSize: number
     ): Promise<OtsAddressTransactionsPage> {
-        const result = (await this.send("ots_searchTransactionsBefore", [address, blockNumber, pageSize])) as {
-            txs: any[];
-            receipts: any[];
-            firstPage: boolean;
-            lastPage: boolean;
-        };
+        const result = await this.send("ots_searchTransactionsBefore", [address, blockNumber, pageSize]) as OtsAddressTransactionsPage;
         return {
             ...result,
-            txs: result.txs.map((tx: any) => formatTransactionResponse(tx)),
-            receipts: result.receipts.map((receipt: any) => ({
+            txs: result.txs.map(tx => formatTransactionResponse(tx)),
+            receipts: result.receipts.map(receipt => ({
                 ...formatTransactionReceipt(receipt),
                 timestamp: receipt.timestamp
             }))
@@ -284,24 +297,19 @@ export class OtterscanProvider extends JsonRpcProvider {
      * Provides paginated transaction history with in-node search (no external indexer needed)
      * @param address - Address to search for
      * @param blockNumber - Starting block number
-     * @param pageSize - Maximum results to return
+     * @param pageSize - Soft limit on results to return (actual results may exceed this if a block contains more transactions)
      * @returns Page of transactions and receipts
      */
     async searchTransactionsAfter(
         address: string,
         blockNumber: number,
         pageSize: number
     ): Promise<OtsAddressTransactionsPage> {
-        const result = (await this.send("ots_searchTransactionsAfter", [address, blockNumber, pageSize])) as {
-            txs: any[];
-            receipts: any[];
-            firstPage: boolean;
-            lastPage: boolean;
-        };
+        const result = await this.send("ots_searchTransactionsAfter", [address, blockNumber, pageSize]) as OtsAddressTransactionsPage;
         return {
             ...result,
-            txs: result.txs.map((tx: any) => formatTransactionResponse(tx)),
-            receipts: result.receipts.map((receipt: any) => ({
+            txs: result.txs.map(tx => formatTransactionResponse(tx)),
+            receipts: result.receipts.map(receipt => ({
                 ...formatTransactionReceipt(receipt),
                 timestamp: receipt.timestamp
             }))
@@ -353,7 +361,7 @@ export class OtterscanProvider extends JsonRpcProvider {
      * @param address - Address to search
      * @param direction - Search direction ("before" or "after")
      * @param startBlock - Starting block number
-     * @param pageSize - Results per page (default: 500)
+     * @param pageSize - Soft limit on results per page (default: 500, actual results may exceed this if a block contains more transactions)
      * @yields Object with tx and receipt for each transaction
      */
     async *iterateAddressHistory(
@@ -379,7 +387,7 @@ export class OtterscanProvider extends JsonRpcProvider {
             }
 
             // Check if we've reached the end
-            if (page.lastPage) break;
+            if (direction === "before" ? page.lastPage : page.firstPage) break;
 
             // Update block cursor for next iteration
             const lastTx = page.txs[page.txs.length - 1];