@yodlpay/payment-decoder 1.2.0 → 1.3.0

package/README.md

@@ -38,6 +38,23 @@ Decode a Yodl payment transaction into a structured `YodlPayment` object.
 - `chainId` - Chain ID where the transaction was executed
 - `clients` - Map of chainId → PublicClient (must include all chains needed for bridges)
 
+### `detectChain(hash, clients)`
+
+Auto-detect which chain a transaction belongs to by trying all configured chains in parallel. Useful when the chain ID is unknown.
+
+- `hash` - Transaction hash to look up
+- `clients` - Map of chainId → PublicClient
+
+Returns `{ chainId, receipt }` — the receipt is included so it can be passed to `decodePayment` / `decodeYodlPayment` to avoid a duplicate RPC call.
+
+```ts
+import { detectChain, decodeYodlPayment, createClients } from "@yodlpay/payment-decoder";
+
+const clients = createClients();
+const { chainId, receipt } = await detectChain("0x1234...abcd", clients);
+const payment = await decodeYodlPayment("0x1234...abcd", chainId, clients, receipt);
+```
+
 ### `ChainClients`
 
 Type alias for the clients map: `Record<number, PublicClient>`
@@ -47,18 +64,22 @@ Type alias for the clients map: `Record<number, PublicClient>`
 Decode a transaction directly from the command line. Outputs JSON to stdout.
 
 ```bash
-bun run decode <txHash> <chainId>
+bun run decode <txHash> [chainId]
 ```
 
 **Arguments:**
 
 - `txHash` - The transaction hash (64 hex characters with `0x` prefix)
-- `chainId` - The chain ID where the transaction occurred (e.g., `8453` for Base, `42161` for Arbitrum)
+- `chainId` *(optional)* - The chain ID where the transaction occurred (e.g., `8453` for Base, `42161` for Arbitrum). If omitted, the chain is auto-detected.
 
-**Example:**
+**Examples:**
 
 ```bash
+# With explicit chain ID
 bun run decode 0xe7ecad85dcfb6b4e25c833fa3617a45cf34df505cb698e04ad7d75a39032158f 42161
+
+# Auto-detect chain
+bun run decode 0xe7ecad85dcfb6b4e25c833fa3617a45cf34df505cb698e04ad7d75a39032158f
 ```
 
 The CLI uses public RPC endpoints. For production use, configure your own RPC URLs via the library API.

package/dist/index.d.ts

@@ -1,8 +1,16 @@
-import { PublicClient, Address, Hex, Log } from 'viem';
+import { PublicClient, Hex, TransactionReceipt, Address, Log } from 'viem';
 import { TokenInfo } from '@yodlpay/tokenlists';
 
 type ChainClients = Record<number, PublicClient>;
 declare function createClients(): ChainClients;
+/**
+ * Auto-detect which chain a transaction belongs to by trying all configured
+ * chains in parallel. Returns both the chain ID and the receipt for reuse.
+ */
+declare function detectChain(hash: Hex, clients: ChainClients): Promise<{
+    chainId: number;
+    receipt: TransactionReceipt;
+}>;
 
 type ServiceProvider = "relay";
 interface Webhook {
@@ -27,8 +35,8 @@ interface SwapInfo {
     service: ServiceProvider;
 }
 interface BridgeInfo extends SwapInfo {
-    originChainId: number;
-    originTxHash: Hex;
+    sourceChainId: number;
+    sourceTxHash: Hex;
     destinationChainId: number;
     destinationTxHash: Hex;
     tokenOutAmountGross: bigint;
@@ -59,8 +67,8 @@ interface YodlPayment {
     data: Record<string, unknown>;
     tokenIn: TokenInInfo;
     tokenOut: TokenOutInfo;
-    originChainId: number;
-    originTxHash: Hex;
+    sourceChainId: number;
+    sourceTxHash: Hex;
     destinationChainId: number;
     destinationTxHash: Hex;
     solver: string | null;
@@ -77,6 +85,7 @@ interface DecodedYodlEvent {
     token: Address;
     amount: bigint;
     memo: string;
+    logIndex: number;
 }
 /**
  * Decode Yodl payment event from transaction logs.
@@ -91,7 +100,7 @@ declare class NoYodlEventError extends Error {
     constructor(message?: string);
 }
 
-declare function decodePayment(hash: Hex, chainId: number, clients: ChainClients): Promise<PaymentInfo>;
+declare function decodePayment(hash: Hex, chainId: number, clients: ChainClients, cachedReceipt?: TransactionReceipt): Promise<PaymentInfo>;
 
 /**
  * Decode a bridge transaction given any hash (source or destination).
@@ -105,6 +114,6 @@ declare function decodeBridgePayment(hash: Hex, clients: ChainClients): Promise<
     type: "bridge";
 }>>;
 
-declare function decodeYodlPayment(txHash: Hex, chainId: number, clients: ChainClients): Promise<YodlPayment>;
+declare function decodeYodlPayment(txHash: Hex, chainId: number, clients: ChainClients, cachedReceipt?: TransactionReceipt): Promise<YodlPayment>;
 
-export { type BridgeInfo, type ChainClients, type DecodedYodlEvent, NoBridgeFoundError, NoYodlEventError, type PaymentEvent, type PaymentInfo, type ServiceProvider, type SwapInfo, type TokenInInfo, type TokenOutInfo, type Webhook, type YodlPayment, createClients, decodeBridgePayment, decodePayment, decodeYodlFromLogs, decodeYodlPayment };
+export { type BridgeInfo, type ChainClients, type DecodedYodlEvent, NoBridgeFoundError, NoYodlEventError, type PaymentEvent, type PaymentInfo, type ServiceProvider, type SwapInfo, type TokenInInfo, type TokenOutInfo, type Webhook, type YodlPayment, createClients, decodeBridgePayment, decodePayment, decodeYodlFromLogs, decodeYodlPayment, detectChain };

package/dist/index.js

@@ -1,12 +1,19 @@
 // src/clients.ts
 import { chains } from "@yodlpay/tokenlists";
-import { createPublicClient, http } from "viem";
+import {
+  createPublicClient,
+  http
+} from "viem";
+var rpcOverrides = {
+  137: "https://polygon-bor-rpc.publicnode.com"
+  // polygon-rpc.com is down
+};
 function createClients() {
   const clients = {};
   for (const chain of chains) {
     clients[chain.id] = createPublicClient({
       chain,
-      transport: http()
+      transport: http(rpcOverrides[chain.id])
     });
   }
   return clients;
@@ -16,6 +23,25 @@ function getClient(clients, chainId) {
   if (!client) throw new Error(`No client configured for chain ${chainId}`);
   return client;
 }
+async function detectChain(hash, clients) {
+  const entries = Object.entries(clients).map(([id, client]) => ({
+    chainId: Number(id),
+    client
+  }));
+  const results = await Promise.allSettled(
+    entries.map(async ({ chainId, client }) => {
+      const receipt = await client.getTransactionReceipt({ hash });
+      return { chainId, receipt };
+    })
+  );
+  const found = results.find(
+    (r) => r.status === "fulfilled"
+  );
+  if (!found) {
+    throw new Error(`Transaction ${hash} not found on any configured chain`);
+  }
+  return found.value;
+}
 
 // src/decode-utils.ts
 import {
@@ -146,14 +172,15 @@ function decodeYodlFromLogs(logs, routerAddress) {
       address: routerAddress,
       context: "Yodl event"
     },
-    (decoded) => {
+    (decoded, log) => {
       const args = decoded.args;
       return {
         sender: args.sender,
         receiver: args.receiver,
         token: args.token,
         amount: args.amount,
-        memo: decodeMemo(args.memo)
+        memo: decodeMemo(args.memo),
+        logIndex: log.logIndex ?? 0
       };
     }
   );
@@ -220,11 +247,13 @@ import { chains as chains2 } from "@yodlpay/tokenlists";
 import { isAddress, isHex } from "viem";
 import { z } from "zod";
 var validChainIds = chains2.map((c) => c.id);
-var ArgsSchema = z.tuple([
-  z.string().regex(/^0x[a-fA-F0-9]{64}$/, "Invalid transaction hash").transform((val) => val),
-  z.coerce.number().int().refine((id) => validChainIds.includes(id), {
-    message: `Chain ID must be one of: ${validChainIds.join(", ")}`
-  })
+var txHashSchema = z.string().regex(/^0x[a-fA-F0-9]{64}$/, "Invalid transaction hash").transform((val) => val);
+var chainIdSchema = z.coerce.number().int().refine((id) => validChainIds.includes(id), {
+  message: `Chain ID must be one of: ${validChainIds.join(", ")}`
+});
+var ArgsSchema = z.union([
+  z.tuple([txHashSchema, chainIdSchema]),
+  z.tuple([txHashSchema])
 ]);
 var WebhooksSchema = z.array(
   z.object({
@@ -374,8 +403,8 @@ function parseRelayResponse(request) {
     throw new NoBridgeFoundError();
   }
   return {
-    originChainId: inTx.chainId,
-    originTxHash: inTx.hash,
+    sourceChainId: inTx.chainId,
+    sourceTxHash: inTx.hash,
     destinationChainId: outTx.chainId,
     destinationTxHash: outTx.hash,
     inputAmountGross: BigInt(data?.metadata?.currencyIn?.amount ?? 0)
@@ -384,18 +413,18 @@ function parseRelayResponse(request) {
 async function decodeBridgePayment(hash, clients) {
   const request = await fetchRelayRequest(hash);
   const {
-    originChainId,
-    originTxHash,
+    sourceChainId,
+    sourceTxHash,
     destinationChainId,
     destinationTxHash,
     inputAmountGross
   } = parseRelayResponse(request);
   const destProvider = getClient(clients, destinationChainId);
-  const sourceProvider = getClient(clients, originChainId);
+  const sourceProvider = getClient(clients, sourceChainId);
   const { address: routerAddress } = getRouter(destinationChainId);
   const [destReceipt, sourceReceipt] = await Promise.all([
     destProvider.getTransactionReceipt({ hash: destinationTxHash }),
-    sourceProvider.getTransactionReceipt({ hash: originTxHash })
+    sourceProvider.getTransactionReceipt({ hash: sourceTxHash })
   ]);
   const yodlEvent = decodeYodlFromLogs(destReceipt.logs, routerAddress);
   if (!yodlEvent) {
@@ -406,7 +435,7 @@ async function decodeBridgePayment(hash, clients) {
   const [destBlock, destTx, sender] = await Promise.all([
     destProvider.getBlock({ blockNumber: destReceipt.blockNumber }),
     destProvider.getTransaction({ hash: destinationTxHash }),
-    extractSenderFromSource(sourceReceipt, sourceProvider, originTxHash)
+    extractSenderFromSource(sourceReceipt, sourceProvider, sourceTxHash)
   ]);
   const tokens = resolveBridgeTokens(
     sourceReceipt,
@@ -414,12 +443,12 @@ async function decodeBridgePayment(hash, clients) {
     yodlEvent,
     sender,
     inputAmountGross,
-    originChainId,
+    sourceChainId,
     destinationChainId
   );
   const bridge = {
-    originChainId,
-    originTxHash,
+    sourceChainId,
+    sourceTxHash,
     destinationChainId,
     destinationTxHash,
     ...tokens,
@@ -447,16 +476,17 @@ async function tryDecodeBridge(hash, clients) {
     return void 0;
   }
 }
-async function decodePayment(hash, chainId, clients) {
+async function decodePayment(hash, chainId, clients, cachedReceipt) {
   const provider = getClient(clients, chainId);
-  const receipt = await provider.getTransactionReceipt({ hash });
+  const receipt = cachedReceipt ?? await provider.getTransactionReceipt({ hash });
   const { address: routerAddress } = getRouter2(chainId);
   const [block, tx] = await Promise.all([
     provider.getBlock({ blockNumber: receipt.blockNumber }),
     provider.getTransaction({ hash })
   ]);
   const yodlEvent = decodeYodlFromLogs(receipt.logs, routerAddress);
-  const swapEvent = decodeSwapFromLogs(receipt.logs);
+  const swapLogs = yodlEvent ? receipt.logs.filter((l) => (l.logIndex ?? 0) < yodlEvent.logIndex) : receipt.logs;
+  const swapEvent = decodeSwapFromLogs(swapLogs);
   if (yodlEvent) {
     const blockTimestamp = toBlockTimestamp(block);
     const webhooks = extractEmbeddedParams(tx.input);
@@ -475,7 +505,10 @@ async function decodePayment(hash, chainId, clients) {
 
 // src/yodl-payment.ts
 import { getTokenByAddress as getTokenByAddress2 } from "@yodlpay/tokenlists";
-import { formatUnits, zeroAddress } from "viem";
+import {
+  formatUnits,
+  zeroAddress
+} from "viem";
 function buildTokenInfo(params) {
   const inToken = getTokenByAddress2(params.tokenIn, params.inChainId);
   const outToken = getTokenByAddress2(params.tokenOut, params.outChainId);
@@ -513,8 +546,8 @@ function extractTokenInfo(paymentInfo, chainId, txHash) {
           inChainId: chainId,
           outChainId: chainId
         }),
-        originChainId: chainId,
-        originTxHash: txHash,
+        sourceChainId: chainId,
+        sourceTxHash: txHash,
         destinationChainId: chainId,
         destinationTxHash: txHash,
         solver: null
@@ -531,8 +564,8 @@ function extractTokenInfo(paymentInfo, chainId, txHash) {
           inChainId: chainId,
           outChainId: chainId
         }),
-        originChainId: chainId,
-        originTxHash: txHash,
+        sourceChainId: chainId,
+        sourceTxHash: txHash,
         destinationChainId: chainId,
         destinationTxHash: txHash,
         solver: paymentInfo.service ?? null
@@ -546,11 +579,11 @@ function extractTokenInfo(paymentInfo, chainId, txHash) {
           tokenOut: paymentInfo.tokenOut,
           tokenOutAmountGross: paymentInfo.tokenOutAmountGross,
           tokenOutAmountNet: paymentInfo.amount,
-          inChainId: paymentInfo.originChainId,
+          inChainId: paymentInfo.sourceChainId,
           outChainId: paymentInfo.destinationChainId
         }),
-        originChainId: paymentInfo.originChainId,
-        originTxHash: paymentInfo.originTxHash,
+        sourceChainId: paymentInfo.sourceChainId,
+        sourceTxHash: paymentInfo.sourceTxHash,
         destinationChainId: paymentInfo.destinationChainId,
         destinationTxHash: paymentInfo.destinationTxHash,
         solver: paymentInfo.service ?? null
@@ -558,8 +591,13 @@ function extractTokenInfo(paymentInfo, chainId, txHash) {
     }
   }
 }
-async function decodeYodlPayment(txHash, chainId, clients) {
-  const paymentInfo = await decodePayment(txHash, chainId, clients);
+async function decodeYodlPayment(txHash, chainId, clients, cachedReceipt) {
+  const paymentInfo = await decodePayment(
+    txHash,
+    chainId,
+    clients,
+    cachedReceipt
+  );
   const firstWebhook = paymentInfo.webhooks[0];
   const processorAddress = firstWebhook?.webhookAddress ?? zeroAddress;
   const processorMemo = firstWebhook?.memo ?? "";
@@ -582,5 +620,6 @@ export {
   decodeBridgePayment,
   decodePayment,
   decodeYodlFromLogs,
-  decodeYodlPayment
+  decodeYodlPayment,
+  detectChain
 };

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@yodlpay/payment-decoder",
-	"version": "1.2.0",
+	"version": "1.3.0",
 	"description": "Decode Yodl payment hashes into structured payment data",
 	"keywords": [
 		"yodl",