@gzeoneth/gov-tracker 0.1.0 → 0.1.1-0

package/README.md

@@ -1,16 +1,9 @@
 # @gzeoneth/gov-tracker
 
-Track and execute Arbitrum DAO governance proposal lifecycle stages.
-
-## Terminology
+[![npm version](https://img.shields.io/npm/v/@gzeoneth/gov-tracker.svg)](https://www.npmjs.com/package/@gzeoneth/gov-tracker)
+[![License](https://img.shields.io/badge/License-Apache_2.0-blue.svg)](https://opensource.org/licenses/Apache-2.0)
 
-The SDK uses terminology aligned with [Arbitrum governance documentation](https://docs.arbitrum.foundation/concepts/lifecycle-anatomy-aip-proposal):
-
-| SDK Term | Description |
-|----------|-------------|
-| Constitutional | Core proposals requiring L1 round-trip (8-day L2 timelock) |
-| Non-Constitutional | Treasury proposals, L2-only execution (3-day L2 timelock) |
-| Election | Security Council election proposals |
+Track and execute Arbitrum DAO governance proposal lifecycle stages.
 
 ## Installation
 
@@ -36,24 +29,21 @@ for (const stage of result.stages) {
   console.log(`${stage.type}: ${stage.status}`);
 }
 
-// Track from timelock operation
-const result = await tracker.trackFromTimelock(timelockAddress, { operationId: "0x..." });
-
 // Track from transaction hash
 const results = await tracker.trackByTxHash("0x...");
 ```
 
 ## Stages
 
-| # | StageType             | Description                                      |
-|---|---------------------- | ------------------------------------------------ |
-| 1 | `PROPOSAL_CREATED`    | Proposal submitted on-chain                      |
-| 2 | `VOTING_ACTIVE`       | Voting period (~14-16 days)                      |
-| 3 | `PROPOSAL_QUEUED`     | Queued in L2 timelock                            |
-| 4 | `L2_TIMELOCK`         | L2 timelock delay + execution (3-8 days)         |
-| 5 | `L2_TO_L1_MESSAGE`    | Cross-chain message + challenge (~6.4 days)      |
-| 6 | `L1_TIMELOCK`         | L1 timelock delay + execution (3 days)           |
-| 7 | `RETRYABLE_EXECUTED`  | Retryable tickets redeemed on L2                 |
+| # | StageType             | Description                                 |
+|---|---------------------- | ------------------------------------------- |
+| 1 | `PROPOSAL_CREATED`    | Proposal submitted on-chain                 |
+| 2 | `VOTING_ACTIVE`       | Voting period (~14-16 days)                 |
+| 3 | `PROPOSAL_QUEUED`     | Queued in L2 timelock                       |
+| 4 | `L2_TIMELOCK`         | L2 timelock delay + execution (3-8 days)    |
+| 5 | `L2_TO_L1_MESSAGE`    | Cross-chain message + challenge (~6.4 days) |
+| 6 | `L1_TIMELOCK`         | L1 timelock delay + execution (3 days)      |
+| 7 | `RETRYABLE_EXECUTED`  | Retryable tickets redeemed on L2            |
 
 Statuses: `NOT_STARTED`, `PENDING`, `READY`, `COMPLETED`, `FAILED`, `SKIPPED`
 
@@ -73,34 +63,56 @@ if (readyStage) {
 }
 ```
 
-## CLI
+## Calldata Decoding & Simulation
 
-The package includes a CLI tool for monitoring and executing governance proposals:
+Decode proposal calldata and prepare simulation data for Tenderly, Foundry, or other tools.
+
+```typescript
+import {
+  decodeCalldata,
+  extractAllSimulationsFromDecoded,
+  getAddressLabel
+} from "@gzeoneth/gov-tracker";
+
+// Decode proposal actions
+const stage = result.stages[0]; // PROPOSAL_CREATED
+const { calldatas, targets } = stage.data;
+
+for (let i = 0; i < calldatas.length; i++) {
+  const decoded = await decodeCalldata(calldatas[i], targets[i], 0, "arb1");
+
+  console.log(`${decoded.functionName}`);
+  console.log(`Target: ${getAddressLabel(targets[i], "arb1")}`);
+
+  // Extract simulation data
+  const sims = extractAllSimulationsFromDecoded(decoded, "arb1");
+  for (const sim of sims) {
+    console.log(`Network: ${sim.simulation.networkId}`);
+    console.log(`From: ${sim.simulation.from}`);
+    console.log(`To: ${sim.simulation.to}`);
+  }
+}
+```
+
+See [Examples](./docs/EXAMPLES.md#calldata-decoding--simulation) for Tenderly and Foundry integration.
+
+## CLI
 
 ```bash
-# After installation, you can use the CLI directly
+# Track a proposal by transaction hash
 npx @gzeoneth/gov-tracker track --tx 0x...
 
-# Or if installed globally
-gov-tracker track --tx 0x...
+# Decode and inspect calldata
+npx @gzeoneth/gov-tracker track --tx 0x... --inspect-only
+
+# Show simulation data for Tenderly/Foundry integration
+npx @gzeoneth/gov-tracker track --tx 0x... --show-simulation
 
 # Execute ready stages
-gov-tracker track --tx 0x... --write --private-key $PRIVATE_KEY
+npx @gzeoneth/gov-tracker track --tx 0x... --write --private-key $PRIVATE_KEY
 
 # Discover and track all proposals
-gov-tracker run
-
-# Run with custom chunk sizes for log searches
-gov-tracker run --l1-chunk-size 500000 --l2-chunk-size 5000000
-
-# Run with concurrent tracking (faster for many proposals)
-gov-tracker run --concurrency 4
-```
-
-For development, you can also use:
-```bash
-yarn monitor:track --tx 0x...
-yarn monitor:run
+npx @gzeoneth/gov-tracker run
 ```
 
 ## Environment
@@ -112,90 +124,34 @@ NOVA_RPC=https://nova.arbitrum.io/rpc
 PRIVATE_KEY=0x...  # For execution
 ```
 
-## Testing
-
-```bash
-yarn test              # Utils tests (~1.5s, pre-commit)
-yarn test:unit         # Smoke tests (~45s, quick CI)
-yarn test:integration  # Full RPC tests (~10min)
-```
-
-## Publishing to npm
-
-This section is for maintainers publishing new versions of the package.
-
-### Prerequisites
-
-1. **npm account**: You must have an npm account with publish access to the `@gzeoneth` scope
-2. **Authentication**: Log in to npm locally:
-   ```bash
-   npm login
-   ```
-3. **Clean state**: Ensure your working directory is clean (no uncommitted changes)
-
-### Publishing Steps
-
-1. **Update version**: Bump the version number in `package.json` using npm's version command:
-   ```bash
-   # Patch release (0.1.0 -> 0.1.1)
-   npm version patch
-
-   # Minor release (0.1.0 -> 0.2.0)
-   npm version minor
+## Documentation
 
-   # Major release (0.1.0 -> 1.0.0)
-   npm version major
-   ```
-   This will automatically update `package.json` and create a git commit + tag.
+- [Getting Started](./docs/GETTING_STARTED.md) - Installation and basic usage
+- [API Reference](./docs/API.md) - Complete API documentation
+- [Examples](./docs/EXAMPLES.md) - Common patterns and use cases
+- [Architecture](./docs/ARCHITECTURE.md) - SDK internals and design
 
-2. **Run tests**: Ensure all tests pass before publishing:
-   ```bash
-   yarn test:all
-   ```
+## Development
 
-3. **Dry run**: Preview what will be published without actually publishing:
-   ```bash
-   npm publish --dry-run
-   ```
-   Review the output to ensure all necessary files are included and no unexpected files are being published.
-
-4. **Publish to npm**:
-   ```bash
-   npm publish --access public
-   ```
-   Note: The `--access public` flag is required for scoped packages to be publicly accessible.
-
-   The `prepublishOnly` hook will automatically run linting, format checking, and build before publishing.
-
-5. **Push to GitHub**: Push the version commit and tag to the repository:
-   ```bash
-   git push && git push --tags
-   ```
-
-### Verification
+```bash
+yarn build              # Compile TypeScript
+yarn test               # Run fast tests (no RPC)
+yarn test:coverage      # Run tests with coverage
+yarn lint               # Run ESLint
+```
 
-After publishing, verify the package:
+See [CONTRIBUTING.md](./CONTRIBUTING.md) for development workflow and publishing instructions.
 
-1. **Check npm registry**:
-   ```bash
-   npm view @gzeoneth/gov-tracker
-   ```
+## Terminology
 
-2. **Test installation** in a separate directory:
-   ```bash
-   mkdir test-install && cd test-install
-   npm init -y
-   npm install @gzeoneth/gov-tracker
-   ```
+| SDK Term | Description |
+|----------|-------------|
+| Constitutional | Core proposals requiring L1 round-trip (8-day L2 timelock) |
+| Non-Constitutional | Treasury proposals, L2-only execution (3-day L2 timelock) |
+| Election | Security Council election proposals |
 
-3. **Verify CLI** is available:
-   ```bash
-   npx @gzeoneth/gov-tracker --help
-   ```
+See [Arbitrum governance docs](https://docs.arbitrum.foundation/concepts/lifecycle-anatomy-aip-proposal) for more details.
 
-### Troubleshooting
+## License
 
-- **403 Forbidden**: You don't have publish access to the `@gzeoneth` scope. Contact the package owner.
-- **Version already exists**: The version in `package.json` has already been published. Bump the version number.
-- **Build failures**: The `prepublishOnly` hook will fail if linting, formatting, or build fails. Fix the errors and try again.
-- **Missing files**: Check the `files` array in `package.json` includes all necessary files (currently set to `["dist"]`).
+Apache-2.0

package/dist/calldata/address-utils.d.ts

@@ -0,0 +1,22 @@
+/**
+ * Address Utilities
+ *
+ * Chain-aware address labeling for known governance contracts.
+ */
+import type { ChainContext, KnownAddress } from "../types/calldata";
+/**
+ * Get known address label
+ *
+ * @param address - Contract address
+ * @param chain - Chain context
+ * @returns Label if known, undefined otherwise
+ */
+export declare function getAddressLabel(address: string, chain: ChainContext): string | undefined;
+/**
+ * Get all known addresses for a chain
+ *
+ * @param chain - Chain context
+ * @returns Array of known address entries
+ */
+export declare function getKnownAddresses(chain: ChainContext): KnownAddress[];
+//# sourceMappingURL=address-utils.d.ts.map

package/dist/calldata/address-utils.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"address-utils.d.ts","sourceRoot":"","sources":["../../src/calldata/address-utils.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,KAAK,EAAE,YAAY,EAAE,YAAY,EAAE,MAAM,mBAAmB,CAAC;AAiDpE;;;;;;GAMG;AACH,wBAAgB,eAAe,CAAC,OAAO,EAAE,MAAM,EAAE,KAAK,EAAE,YAAY,GAAG,MAAM,GAAG,SAAS,CAaxF;AAED;;;;;GAKG;AACH,wBAAgB,iBAAiB,CAAC,KAAK,EAAE,YAAY,GAAG,YAAY,EAAE,CASrE"}

package/dist/calldata/address-utils.js

@@ -0,0 +1,84 @@
+"use strict";
+/**
+ * Address Utilities
+ *
+ * Chain-aware address labeling for known governance contracts.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.getAddressLabel = getAddressLabel;
+exports.getKnownAddresses = getKnownAddresses;
+/**
+ * Known addresses registry organized by chain
+ */
+const KNOWN_ADDRESSES = {
+    arb1: {
+        // Governors
+        "0xf07DeD9dC292157749B6Fd268E37DF6EA38395B9": "Core Governor",
+        "0x789fC99093B09aD01C34DC7251D0C89ce743e5a4": "Treasury Governor",
+        "0x8a1cDA8dee421cD06023470608605934c16A05a0": "Nominee Election Governor",
+        "0x467923B9AE90BDB36BA88eCA11604D45F13b712C": "Member Election Governor",
+        // Timelocks
+        "0x34d45e99f7D8c45ed05B5cA72D54bbD1fb3F98f0": "L2 Core Timelock",
+        "0xbFc1FECa8B09A5c5D3EFfE7429eBE24b9c09EF58": "L2 Treasury Timelock",
+        // Other contracts
+        "0x912CE59144191C1204E64559FE8253a0e49E6548": "ARB Token",
+        "0xCF57572261c7c2BCF21ffD220ea7d1a27D40A827": "Arb1 UpgradeExecutor",
+        "0xD509E5f5aEe2A205F554f36E8a7d56094494eDFC": "Security Council Manager",
+        // Precompiles
+        "0x0000000000000000000000000000000000000064": "ArbSys",
+        "0x000000000000000000000000000000000000006E": "ArbRetryableTx",
+    },
+    nova: {
+        "0x86a02dD71363c440b21F4c0E5B2Ad01Ffe1A7482": "Nova UpgradeExecutor",
+    },
+    ethereum: {
+        // Timelock
+        "0xE6841D92B0C345144506576eC13ECf5103aC7f49": "L1 Timelock",
+        // UpgradeExecutor
+        "0x3ffFbAdAF827559da092217e474760E2b2c3CeDd": "L1 UpgradeExecutor",
+        // Delayed Inboxes
+        "0x4Dbd4fc535Ac27206064B68FfCf827b0A60BAB3f": "Arb1 Delayed Inbox",
+        "0xc4448b71118c9071Bcb9734A0EAc55D18A153949": "Nova Delayed Inbox",
+        // Special addresses
+        "0xa723C008e76E379c55599D2E4d93879BeaFDa79C": "Retryable Ticket Magic",
+        // Outboxes
+        "0x0B9857ae2D4A3DBe74ffE1d7DF045bb7F96E4840": "Arb1 Outbox",
+        "0xD4B80C3D7240325D18E645B49e6535A3Bf95cc58": "Nova Outbox",
+    },
+};
+/**
+ * Get known address label
+ *
+ * @param address - Contract address
+ * @param chain - Chain context
+ * @returns Label if known, undefined otherwise
+ */
+function getAddressLabel(address, chain) {
+    const chainAddresses = KNOWN_ADDRESSES[chain];
+    if (!chainAddresses)
+        return undefined;
+    const lowerAddress = address.toLowerCase();
+    for (const [addr, label] of Object.entries(chainAddresses)) {
+        if (addr.toLowerCase() === lowerAddress) {
+            return label;
+        }
+    }
+    return undefined;
+}
+/**
+ * Get all known addresses for a chain
+ *
+ * @param chain - Chain context
+ * @returns Array of known address entries
+ */
+function getKnownAddresses(chain) {
+    const chainAddresses = KNOWN_ADDRESSES[chain];
+    if (!chainAddresses)
+        return [];
+    return Object.entries(chainAddresses).map(([address, label]) => ({
+        address,
+        label,
+        chain,
+    }));
+}
+//# sourceMappingURL=address-utils.js.map

package/dist/calldata/address-utils.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"address-utils.js","sourceRoot":"","sources":["../../src/calldata/address-utils.ts"],"names":[],"mappings":";AAAA;;;;GAIG;;AA0DH,0CAaC;AAQD,8CASC;AApFD;;GAEG;AACH,MAAM,eAAe,GAAiD;IACpE,IAAI,EAAE;QACJ,YAAY;QACZ,4CAA4C,EAAE,eAAe;QAC7D,4CAA4C,EAAE,mBAAmB;QACjE,4CAA4C,EAAE,2BAA2B;QACzE,4CAA4C,EAAE,0BAA0B;QAExE,YAAY;QACZ,4CAA4C,EAAE,kBAAkB;QAChE,4CAA4C,EAAE,sBAAsB;QAEpE,kBAAkB;QAClB,4CAA4C,EAAE,WAAW;QACzD,4CAA4C,EAAE,sBAAsB;QACpE,4CAA4C,EAAE,0BAA0B;QAExE,cAAc;QACd,4CAA4C,EAAE,QAAQ;QACtD,4CAA4C,EAAE,gBAAgB;KAC/D;IACD,IAAI,EAAE;QACJ,4CAA4C,EAAE,sBAAsB;KACrE;IACD,QAAQ,EAAE;QACR,WAAW;QACX,4CAA4C,EAAE,aAAa;QAE3D,kBAAkB;QAClB,4CAA4C,EAAE,oBAAoB;QAElE,kBAAkB;QAClB,4CAA4C,EAAE,oBAAoB;QAClE,4CAA4C,EAAE,oBAAoB;QAElE,oBAAoB;QACpB,4CAA4C,EAAE,wBAAwB;QAEtE,WAAW;QACX,4CAA4C,EAAE,aAAa;QAC3D,4CAA4C,EAAE,aAAa;KAC5D;CACF,CAAC;AAEF;;;;;;GAMG;AACH,SAAgB,eAAe,CAAC,OAAe,EAAE,KAAmB;IAClE,MAAM,cAAc,GAAG,eAAe,CAAC,KAAK,CAAC,CAAC;IAC9C,IAAI,CAAC,cAAc;QAAE,OAAO,SAAS,CAAC;IAEtC,MAAM,YAAY,GAAG,OAAO,CAAC,WAAW,EAAE,CAAC;IAE3C,KAAK,MAAM,CAAC,IAAI,EAAE,KAAK,CAAC,IAAI,MAAM,CAAC,OAAO,CAAC,cAAc,CAAC,EAAE,CAAC;QAC3D,IAAI,IAAI,CAAC,WAAW,EAAE,KAAK,YAAY,EAAE,CAAC;YACxC,OAAO,KAAK,CAAC;QACf,CAAC;IACH,CAAC;IAED,OAAO,SAAS,CAAC;AACnB,CAAC;AAED;;;;;GAKG;AACH,SAAgB,iBAAiB,CAAC,KAAmB;IACnD,MAAM,cAAc,GAAG,eAAe,CAAC,KAAK,CAAC,CAAC;IAC9C,IAAI,CAAC,cAAc;QAAE,OAAO,EAAE,CAAC;IAE/B,OAAO,MAAM,CAAC,OAAO,CAAC,cAAc,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,OAAO,EAAE,KAAK,CAAC,EAAE,EAAE,CAAC,CAAC;QAC/D,OAAO;QACP,KAAK;QACL,KAAK;KACN,CAAC,CAAC,CAAC;AACN,CAAC"}

package/dist/calldata/decoder.d.ts

@@ -0,0 +1,27 @@
+/**
+ * Calldata Decoder
+ *
+ * Main decoder that orchestrates recursive calldata decoding with
+ * nested call handling and retryable ticket detection.
+ */
+import type { ChainContext, DecodedCalldata } from "../types/calldata";
+/**
+ * Decode calldata with recursive nested decoding support
+ *
+ * @param calldata - Hex-encoded calldata string
+ * @param targetAddress - Optional target contract (for context)
+ * @param depth - Current recursion depth (internal, default: 0)
+ * @param chainContext - Chain for address resolution (default: "arb1")
+ * @returns Decoded calldata with nested calls
+ */
+export declare function decodeCalldata(calldata: string, targetAddress?: string, depth?: number, chainContext?: ChainContext): Promise<DecodedCalldata>;
+/**
+ * Decode multiple calldatas with their targets
+ *
+ * @param calldatas - Array of calldata hex strings
+ * @param targets - Array of target addresses (same length as calldatas)
+ * @param chainContext - Chain for address resolution
+ * @returns Array of decoded calldata results
+ */
+export declare function decodeCalldataArray(calldatas: string[], targets: string[], chainContext?: ChainContext): Promise<DecodedCalldata[]>;
+//# sourceMappingURL=decoder.d.ts.map

package/dist/calldata/decoder.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"decoder.d.ts","sourceRoot":"","sources":["../../src/calldata/decoder.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAGH,OAAO,KAAK,EAAE,YAAY,EAAE,eAAe,EAAoB,MAAM,mBAAmB,CAAC;AAuBzF;;;;;;;;GAQG;AACH,wBAAsB,cAAc,CAClC,QAAQ,EAAE,MAAM,EAChB,aAAa,CAAC,EAAE,MAAM,EACtB,KAAK,SAAI,EACT,YAAY,GAAE,YAAqB,GAClC,OAAO,CAAC,eAAe,CAAC,CAgF1B;AA2ID;;;;;;;GAOG;AACH,wBAAsB,mBAAmB,CACvC,SAAS,EAAE,MAAM,EAAE,EACnB,OAAO,EAAE,MAAM,EAAE,EACjB,YAAY,GAAE,YAAqB,GAClC,OAAO,CAAC,eAAe,EAAE,CAAC,CAS5B"}

package/dist/calldata/decoder.js

@@ -0,0 +1,238 @@
+"use strict";
+/**
+ * Calldata Decoder
+ *
+ * Main decoder that orchestrates recursive calldata decoding with
+ * nested call handling and retryable ticket detection.
+ */
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.decodeCalldata = decodeCalldata;
+exports.decodeCalldataArray = decodeCalldataArray;
+const debug_1 = __importDefault(require("debug"));
+const signature_lookup_1 = require("./signature-lookup");
+const parameter_decoder_1 = require("./parameter-decoder");
+const retryable_ticket_1 = require("./retryable-ticket");
+const address_utils_1 = require("./address-utils");
+const debug = (0, debug_1.default)("gov-tracker:calldata");
+/**
+ * Maximum recursion depth for nested calldata decoding
+ */
+const MAX_DEPTH = 3;
+/**
+ * Selector for sendTxToL1 - indicates L2→L1 message, nested content is on L1
+ */
+const SEND_TX_TO_L1_SELECTOR = "0x928c169a";
+/**
+ * Decode calldata with recursive nested decoding support
+ *
+ * @param calldata - Hex-encoded calldata string
+ * @param targetAddress - Optional target contract (for context)
+ * @param depth - Current recursion depth (internal, default: 0)
+ * @param chainContext - Chain for address resolution (default: "arb1")
+ * @returns Decoded calldata with nested calls
+ */
+async function decodeCalldata(calldata, targetAddress, depth = 0, chainContext = "arb1") {
+    // Handle empty or invalid calldata
+    if (!calldata || calldata === "0x" || calldata.length < 10) {
+        return {
+            selector: "",
+            functionName: null,
+            signature: null,
+            parameters: null,
+            raw: calldata || "0x",
+            decodingSource: "failed",
+            chainContext,
+        };
+    }
+    // Extract selector (first 4 bytes = 10 chars including 0x)
+    const selector = calldata.slice(0, 10).toLowerCase();
+    // Lookup signature
+    const { signature, source } = await (0, signature_lookup_1.lookupSignature)(selector);
+    if (!signature) {
+        debug("Unknown signature for selector: %s", selector);
+        return {
+            selector,
+            functionName: null,
+            signature: null,
+            parameters: null,
+            raw: calldata,
+            decodingSource: "failed",
+            chainContext,
+        };
+    }
+    const functionName = (0, signature_lookup_1.extractFunctionName)(signature);
+    // Determine chain context for nested content
+    // sendTxToL1 means nested content is on L1
+    const isSendTxToL1 = selector === SEND_TX_TO_L1_SELECTOR;
+    const nestedContext = isSendTxToL1 ? "ethereum" : chainContext;
+    // Decode parameters
+    const decoded = (0, parameter_decoder_1.decodeParameters)(calldata, signature, chainContext);
+    if (!decoded) {
+        debug("Failed to decode parameters for: %s", signature);
+        return {
+            selector,
+            functionName,
+            signature,
+            parameters: null,
+            raw: calldata,
+            decodingSource: source,
+            chainContext,
+        };
+    }
+    const { params, decoded: rawDecoded } = decoded;
+    // For sendTxToL1, fix first param (target address) to use L1 context
+    if (isSendTxToL1 && params[0]?.type === "address") {
+        const addr = String(rawDecoded[0]);
+        const label = (0, address_utils_1.getAddressLabel)(addr, "ethereum");
+        if (label)
+            params[0].addressLabel = label;
+    }
+    // Process nested content if not at max depth
+    if (depth < MAX_DEPTH) {
+        await processNestedParams(params, Array.from(rawDecoded), nestedContext, depth);
+    }
+    return {
+        selector,
+        functionName,
+        signature,
+        parameters: params,
+        raw: calldata,
+        decodingSource: source,
+        decodingTarget: targetAddress,
+        chainContext,
+    };
+}
+/**
+ * Process parameters to decode nested calldata
+ */
+async function processNestedParams(params, rawDecoded, chainContext, depth) {
+    // Find address[] parameter (for batch operations, provides targets)
+    const addressArrayParam = params.find((p) => p.type === "address[]");
+    let targets = [];
+    if (addressArrayParam) {
+        const rawValue = rawDecoded[params.indexOf(addressArrayParam)];
+        if (Array.isArray(rawValue)) {
+            targets = rawValue.map((a) => String(a));
+        }
+    }
+    // Find preceding address parameter for simple forwarding (e.g. sendTxToL1(address, bytes))
+    // We'll update this as we iterate
+    let lastAddressValue;
+    for (let paramIdx = 0; paramIdx < params.length; paramIdx++) {
+        const param = params[paramIdx];
+        const rawValue = rawDecoded[paramIdx];
+        // Capture address for context propagation to subsequent bytes params
+        if (param.type === "address") {
+            lastAddressValue = String(rawValue);
+        }
+        // Handle bytes[] array (e.g., scheduleBatch calldatas)
+        if (param.type === "bytes[]" && param._rawBytesArray) {
+            const nestedArray = [];
+            for (let i = 0; i < param._rawBytesArray.length; i++) {
+                const bytesItem = param._rawBytesArray[i];
+                const target = targets[i]; // Use target from parallel array
+                // Check for retryable ticket magic
+                if (target && (0, retryable_ticket_1.isRetryableTicketMagic)(target)) {
+                    const retryable = (0, retryable_ticket_1.decodeRetryableTicket)(bytesItem);
+                    if (retryable) {
+                        const l2Chain = (0, retryable_ticket_1.retryableChainToContext)(retryable.chain);
+                        const chainName = (0, retryable_ticket_1.getRetryableChainName)(retryable.chain);
+                        // Decode l2Calldata with L2 chain context
+                        let nestedL2Call;
+                        if ((0, parameter_decoder_1.isLikelyCalldata)(retryable.l2Calldata)) {
+                            nestedL2Call = await decodeCalldata(retryable.l2Calldata, retryable.l2Target, depth + 1, l2Chain);
+                        }
+                        // Create retryable structure with decoded L2 call
+                        const retryableDecoded = {
+                            selector: "",
+                            functionName: `Retryable Ticket → ${chainName}`,
+                            signature: null,
+                            parameters: [
+                                {
+                                    name: "inbox",
+                                    type: "address",
+                                    value: retryable.targetInbox,
+                                    isNested: false,
+                                    addressLabel: (0, address_utils_1.getAddressLabel)(retryable.targetInbox, "ethereum"),
+                                },
+                                {
+                                    name: "l2Target",
+                                    type: "address",
+                                    value: retryable.l2Target,
+                                    isNested: false,
+                                    addressLabel: (0, address_utils_1.getAddressLabel)(retryable.l2Target, l2Chain),
+                                },
+                                {
+                                    name: "l2Value",
+                                    type: "uint256",
+                                    value: retryable.l2Value,
+                                    isNested: false,
+                                },
+                                {
+                                    name: "gasLimit",
+                                    type: "uint256",
+                                    value: retryable.gasLimit,
+                                    isNested: false,
+                                },
+                                {
+                                    name: "maxFeePerGas",
+                                    type: "uint256",
+                                    value: retryable.maxFeePerGas,
+                                    isNested: false,
+                                },
+                                {
+                                    name: "l2Calldata",
+                                    type: "bytes",
+                                    value: retryable.l2Calldata,
+                                    isNested: !!nestedL2Call,
+                                    nested: nestedL2Call,
+                                },
+                            ],
+                            raw: bytesItem,
+                            decodingSource: "local",
+                            chainContext: "ethereum", // Retryable tickets are created on L1
+                        };
+                        nestedArray.push(retryableDecoded);
+                        continue;
+                    }
+                }
+                // Normal calldata decoding
+                if ((0, parameter_decoder_1.isLikelyCalldata)(bytesItem)) {
+                    const decodedItem = await decodeCalldata(bytesItem, target, depth + 1, chainContext);
+                    nestedArray.push(decodedItem);
+                }
+            }
+            if (nestedArray.length > 0) {
+                param.nestedArray = nestedArray;
+            }
+        }
+        // Handle single bytes parameter
+        else if (param.type === "bytes" && param.isNested) {
+            const rawBytes = String(rawValue);
+            if ((0, parameter_decoder_1.isLikelyCalldata)(rawBytes)) {
+                // Use lastAddressValue as target if available
+                param.nested = await decodeCalldata(rawBytes, lastAddressValue, depth + 1, chainContext);
+            }
+        }
+    }
+}
+/**
+ * Decode multiple calldatas with their targets
+ *
+ * @param calldatas - Array of calldata hex strings
+ * @param targets - Array of target addresses (same length as calldatas)
+ * @param chainContext - Chain for address resolution
+ * @returns Array of decoded calldata results
+ */
+async function decodeCalldataArray(calldatas, targets, chainContext = "arb1") {
+    const results = [];
+    for (let i = 0; i < calldatas.length; i++) {
+        const decoded = await decodeCalldata(calldatas[i], targets[i], 0, chainContext);
+        results.push(decoded);
+    }
+    return results;
+}
+//# sourceMappingURL=decoder.js.map

package/dist/calldata/decoder.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"decoder.js","sourceRoot":"","sources":["../../src/calldata/decoder.ts"],"names":[],"mappings":"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"}

package/dist/calldata/index.d.ts

@@ -0,0 +1,13 @@
+/**
+ * Calldata Decoding Module
+ *
+ * Exports for recursive calldata decoding, signature lookup,
+ * and address utilities.
+ */
+export { decodeCalldata, decodeCalldataArray } from "./decoder";
+export { lookupSignature, lookupLocalSignature, lookup4byteDirectory, extractFunctionName, clearSignatureCache, } from "./signature-lookup";
+export { parseParamTypes, isLikelyCalldata, formatDecodedValue, decodeParameters, } from "./parameter-decoder";
+export { getAddressLabel, getKnownAddresses } from "./address-utils";
+export { getAddressExplorerUrl, getTxExplorerUrl, getChainLabel } from "../utils/urls";
+export { RETRYABLE_TICKET_MAGIC, ARB1_DELAYED_INBOX, NOVA_DELAYED_INBOX, isRetryableTicketMagic, detectChainFromInbox, decodeRetryableTicket, getRetryableChainName, retryableChainToContext, } from "./retryable-ticket";
+//# sourceMappingURL=index.d.ts.map

package/dist/calldata/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/calldata/index.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAGH,OAAO,EAAE,cAAc,EAAE,mBAAmB,EAAE,MAAM,WAAW,CAAC;AAGhE,OAAO,EACL,eAAe,EACf,oBAAoB,EACpB,oBAAoB,EACpB,mBAAmB,EACnB,mBAAmB,GACpB,MAAM,oBAAoB,CAAC;AAG5B,OAAO,EACL,eAAe,EACf,gBAAgB,EAChB,kBAAkB,EAClB,gBAAgB,GACjB,MAAM,qBAAqB,CAAC;AAG7B,OAAO,EAAE,eAAe,EAAE,iBAAiB,EAAE,MAAM,iBAAiB,CAAC;AAGrE,OAAO,EAAE,qBAAqB,EAAE,gBAAgB,EAAE,aAAa,EAAE,MAAM,eAAe,CAAC;AAGvF,OAAO,EACL,sBAAsB,EACtB,kBAAkB,EAClB,kBAAkB,EAClB,sBAAsB,EACtB,oBAAoB,EACpB,qBAAqB,EACrB,qBAAqB,EACrB,uBAAuB,GACxB,MAAM,oBAAoB,CAAC"}