@yodlpay/payment-decoder 1.2.1 → 1.3.1

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 {
@@ -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,11 +23,32 @@ 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 { tokenlist } from "@yodlpay/tokenlists";
 import {
   decodeEventLog,
-  erc20Abi,
+  erc20Abi as erc20Abi2,
+  getAddress,
   isAddressEqual
 } from "viem";
 
@@ -87,7 +115,13 @@ function isExpectedDecodeError(error) {
 }
 
 // src/utils.ts
-import { hexToString } from "viem";
+import { getTokenByAddress } from "@yodlpay/tokenlists";
+import {
+  erc20Abi,
+  getContract,
+  hexToString
+} from "viem";
+import { z } from "zod";
 function decodeMemo(memo) {
   if (!memo || memo === "0x") return "";
   try {
@@ -96,6 +130,27 @@ function decodeMemo(memo) {
     return "";
   }
 }
+var erc20String = z.string().max(64).transform((s) => s.replace(/\p{Cc}/gu, ""));
+var erc20Decimals = z.number().int().nonnegative().max(36);
+async function resolveToken(address, chainId, client) {
+  try {
+    return getTokenByAddress(address, chainId);
+  } catch {
+    const token = getContract({ address, abi: erc20Abi, client });
+    const [name, symbol, decimals] = await Promise.all([
+      token.read.name(),
+      token.read.symbol(),
+      token.read.decimals()
+    ]);
+    return {
+      chainId,
+      address,
+      name: erc20String.parse(name),
+      symbol: erc20String.parse(symbol),
+      decimals: erc20Decimals.parse(decimals)
+    };
+  }
+}
 
 // src/decode-utils.ts
 function* matchingEvents(logs, options) {
@@ -146,14 +201,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
       };
     }
   );
@@ -177,7 +233,7 @@ function decodeSwapFromLogs(logs) {
 function extractTokenTransfers(logs) {
   return collectEventsFromLogs(
     logs,
-    { abi: erc20Abi, eventName: "Transfer", context: "ERC20 Transfer" },
+    { abi: erc20Abi2, eventName: "Transfer", context: "ERC20 Transfer" },
     (decoded, log) => {
       const args = decoded.args;
       return {
@@ -189,13 +245,66 @@ function extractTokenTransfers(logs) {
     }
   );
 }
+function isKnownToken(address) {
+  return tokenlist.some((t) => isAddressEqual(t.address, address));
+}
+function transferSignature(t) {
+  return `${getAddress(t.from)}:${getAddress(t.to)}:${t.amount}`;
+}
+function areMirrorTransfers(a, b) {
+  if (a.length !== b.length) return false;
+  const counts = /* @__PURE__ */ new Map();
+  for (const t of a) {
+    const key = transferSignature(t);
+    counts.set(key, (counts.get(key) ?? 0) + 1);
+  }
+  for (const t of b) {
+    const key = transferSignature(t);
+    const count = counts.get(key);
+    if (!count) return false;
+    if (count === 1) counts.delete(key);
+    else counts.set(key, count - 1);
+  }
+  return counts.size === 0;
+}
+function detectMirrorTokens(allTransfers) {
+  const mirrors = /* @__PURE__ */ new Map();
+  const byToken = Map.groupBy(allTransfers, (t) => getAddress(t.token));
+  const tokens = [...byToken.keys()];
+  for (const [i, tokenA] of tokens.entries()) {
+    if (mirrors.has(tokenA)) continue;
+    const transfersA = byToken.get(tokenA) ?? [];
+    for (const tokenB of tokens.slice(i + 1)) {
+      if (mirrors.has(tokenB)) continue;
+      const transfersB = byToken.get(tokenB) ?? [];
+      if (!areMirrorTransfers(transfersA, transfersB)) continue;
+      if (isKnownToken(tokenB) && !isKnownToken(tokenA)) {
+        mirrors.set(tokenA, tokenB);
+      } else {
+        mirrors.set(tokenB, tokenA);
+      }
+    }
+  }
+  return mirrors;
+}
 function findInputTransfer(transfers, sender) {
   const fromSender = transfers.filter((t) => isAddressEqual(t.from, sender));
   if (fromSender.length === 0) return void 0;
-  const largest = fromSender.reduce(
-    (max, t) => t.amount > max.amount ? t : max
+  const maxAmount = fromSender.reduce(
+    (max, t) => t.amount > max ? t.amount : max,
+    0n
   );
-  return { token: largest.token, amount: largest.amount };
+  let candidates = fromSender.filter((t) => t.amount === maxAmount);
+  if (candidates.length > 1) {
+    const mirrors = detectMirrorTokens(transfers);
+    const filtered = candidates.filter(
+      (t) => !mirrors.has(getAddress(t.token))
+    );
+    if (filtered.length > 0) candidates = filtered;
+  }
+  const result = candidates.find((t) => isKnownToken(t.token)) ?? candidates[0];
+  if (!result) return void 0;
+  return { token: result.token, amount: result.amount };
 }
 function toBlockTimestamp(block) {
   return new Date(Number(block.timestamp) * 1e3);
@@ -218,18 +327,20 @@ import { decodeFunctionData, toFunctionSelector } from "viem";
 // src/validation.ts
 import { chains as chains2 } from "@yodlpay/tokenlists";
 import { isAddress, isHex } from "viem";
-import { z } from "zod";
+import { z as z2 } 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 = z2.string().regex(/^0x[a-fA-F0-9]{64}$/, "Invalid transaction hash").transform((val) => val);
+var chainIdSchema = z2.coerce.number().int().refine((id) => validChainIds.includes(id), {
+  message: `Chain ID must be one of: ${validChainIds.join(", ")}`
+});
+var ArgsSchema = z2.union([
+  z2.tuple([txHashSchema, chainIdSchema]),
+  z2.tuple([txHashSchema])
 ]);
-var WebhooksSchema = z.array(
-  z.object({
-    webhookAddress: z.string().refine((val) => isAddress(val)),
-    payload: z.array(z.string().refine((val) => isHex(val)))
+var WebhooksSchema = z2.array(
+  z2.object({
+    webhookAddress: z2.string().refine((val) => isAddress(val)),
+    payload: z2.array(z2.string().refine((val) => isHex(val)))
   }).transform((webhook) => ({
     ...webhook,
     memo: webhook.payload[0] ? decodeMemo(webhook.payload[0]) : ""
@@ -267,7 +378,7 @@ function extractEmbeddedParams(data) {
 }
 
 // src/relay-bridge.ts
-import { getRouter, getTokenByAddress } from "@yodlpay/tokenlists";
+import { getRouter } from "@yodlpay/tokenlists";
 import {
   decodeEventLog as decodeEventLog2,
   isAddressEqual as isAddressEqual2
@@ -301,15 +412,15 @@ async function fetchRelayRequest(hash) {
 }
 
 // src/relay-bridge.ts
-function calculateOutputAmountGross(inputAmount, inputToken, inputChainId, outputToken, outputChainId) {
-  const { decimals: inputDecimals } = getTokenByAddress(
-    inputToken,
-    inputChainId
-  );
-  const { decimals: outputDecimals } = getTokenByAddress(
-    outputToken,
-    outputChainId
-  );
+async function calculateOutputAmountGross(inputAmount, inputToken, inputChainId, outputToken, outputChainId, clients) {
+  const [{ decimals: inputDecimals }, { decimals: outputDecimals }] = await Promise.all([
+    resolveToken(inputToken, inputChainId, getClient(clients, inputChainId)),
+    resolveToken(
+      outputToken,
+      outputChainId,
+      getClient(clients, outputChainId)
+    )
+  ]);
   const decimalDiff = inputDecimals - outputDecimals;
   if (decimalDiff === 0) return inputAmount;
   if (decimalDiff > 0) return inputAmount / 10n ** BigInt(decimalDiff);
@@ -333,7 +444,7 @@ async function extractSenderFromSource(sourceReceipt, sourceProvider, sourceHash
   const sourceTx = await sourceProvider.getTransaction({ hash: sourceHash });
   return sourceTx.from;
 }
-function resolveBridgeTokens(sourceReceipt, destReceipt, yodlEvent, sender, inputAmountGross, inputChainId, outputChainId) {
+async function resolveBridgeTokens(sourceReceipt, destReceipt, yodlEvent, sender, inputAmountGross, inputChainId, outputChainId, clients) {
   const sourceTransfers = extractTokenTransfers(sourceReceipt.logs);
   const inputTransfer = findInputTransfer(sourceTransfers, sender);
   const tokenIn = inputTransfer?.token;
@@ -350,12 +461,13 @@ function resolveBridgeTokens(sourceReceipt, destReceipt, yodlEvent, sender, inpu
   if (swapEvent !== void 0) {
     tokenOutAmountGross = swapEvent.tokenOutAmount;
   } else if (inputAmountGross > 0n && tokenIn && tokenOut) {
-    tokenOutAmountGross = calculateOutputAmountGross(
+    tokenOutAmountGross = await calculateOutputAmountGross(
       inputAmountGross,
       tokenIn,
       inputChainId,
       tokenOut,
-      outputChainId
+      outputChainId,
+      clients
     );
   }
   return {
@@ -408,14 +520,15 @@ async function decodeBridgePayment(hash, clients) {
     destProvider.getTransaction({ hash: destinationTxHash }),
     extractSenderFromSource(sourceReceipt, sourceProvider, sourceTxHash)
   ]);
-  const tokens = resolveBridgeTokens(
+  const tokens = await resolveBridgeTokens(
     sourceReceipt,
     destReceipt,
     yodlEvent,
     sender,
     inputAmountGross,
     sourceChainId,
-    destinationChainId
+    destinationChainId,
+    clients
   );
   const bridge = {
     sourceChainId,
@@ -447,16 +560,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);
@@ -474,11 +588,23 @@ async function decodePayment(hash, chainId, clients) {
 }
 
 // src/yodl-payment.ts
-import { getTokenByAddress as getTokenByAddress2 } from "@yodlpay/tokenlists";
-import { formatUnits, zeroAddress } from "viem";
-function buildTokenInfo(params) {
-  const inToken = getTokenByAddress2(params.tokenIn, params.inChainId);
-  const outToken = getTokenByAddress2(params.tokenOut, params.outChainId);
+import {
+  formatUnits,
+  zeroAddress
+} from "viem";
+async function buildTokenInfo(params, clients) {
+  const [inToken, outToken] = await Promise.all([
+    resolveToken(
+      params.tokenIn,
+      params.inChainId,
+      getClient(clients, params.inChainId)
+    ),
+    resolveToken(
+      params.tokenOut,
+      params.outChainId,
+      getClient(clients, params.outChainId)
+    )
+  ]);
   return {
     tokenIn: {
       ...inToken,
@@ -500,19 +626,22 @@ function buildTokenInfo(params) {
     }
   };
 }
-function extractTokenInfo(paymentInfo, chainId, txHash) {
+async function extractTokenInfo(paymentInfo, chainId, txHash, clients) {
   switch (paymentInfo.type) {
     case "direct": {
       return {
-        ...buildTokenInfo({
-          tokenIn: paymentInfo.token,
-          tokenInAmount: paymentInfo.amount,
-          tokenOut: paymentInfo.token,
-          tokenOutAmountGross: paymentInfo.amount,
-          tokenOutAmountNet: paymentInfo.amount,
-          inChainId: chainId,
-          outChainId: chainId
-        }),
+        ...await buildTokenInfo(
+          {
+            tokenIn: paymentInfo.token,
+            tokenInAmount: paymentInfo.amount,
+            tokenOut: paymentInfo.token,
+            tokenOutAmountGross: paymentInfo.amount,
+            tokenOutAmountNet: paymentInfo.amount,
+            inChainId: chainId,
+            outChainId: chainId
+          },
+          clients
+        ),
         sourceChainId: chainId,
         sourceTxHash: txHash,
         destinationChainId: chainId,
@@ -522,15 +651,18 @@ function extractTokenInfo(paymentInfo, chainId, txHash) {
     }
     case "swap": {
       return {
-        ...buildTokenInfo({
-          tokenIn: paymentInfo.tokenIn,
-          tokenInAmount: paymentInfo.tokenInAmount,
-          tokenOut: paymentInfo.token,
-          tokenOutAmountGross: paymentInfo.tokenOutAmount,
-          tokenOutAmountNet: paymentInfo.amount,
-          inChainId: chainId,
-          outChainId: chainId
-        }),
+        ...await buildTokenInfo(
+          {
+            tokenIn: paymentInfo.tokenIn,
+            tokenInAmount: paymentInfo.tokenInAmount,
+            tokenOut: paymentInfo.token,
+            tokenOutAmountGross: paymentInfo.tokenOutAmount,
+            tokenOutAmountNet: paymentInfo.amount,
+            inChainId: chainId,
+            outChainId: chainId
+          },
+          clients
+        ),
         sourceChainId: chainId,
         sourceTxHash: txHash,
         destinationChainId: chainId,
@@ -540,15 +672,18 @@ function extractTokenInfo(paymentInfo, chainId, txHash) {
     }
     case "bridge": {
       return {
-        ...buildTokenInfo({
-          tokenIn: paymentInfo.tokenIn,
-          tokenInAmount: paymentInfo.tokenInAmount,
-          tokenOut: paymentInfo.tokenOut,
-          tokenOutAmountGross: paymentInfo.tokenOutAmountGross,
-          tokenOutAmountNet: paymentInfo.amount,
-          inChainId: paymentInfo.sourceChainId,
-          outChainId: paymentInfo.destinationChainId
-        }),
+        ...await buildTokenInfo(
+          {
+            tokenIn: paymentInfo.tokenIn,
+            tokenInAmount: paymentInfo.tokenInAmount,
+            tokenOut: paymentInfo.tokenOut,
+            tokenOutAmountGross: paymentInfo.tokenOutAmountGross,
+            tokenOutAmountNet: paymentInfo.amount,
+            inChainId: paymentInfo.sourceChainId,
+            outChainId: paymentInfo.destinationChainId
+          },
+          clients
+        ),
         sourceChainId: paymentInfo.sourceChainId,
         sourceTxHash: paymentInfo.sourceTxHash,
         destinationChainId: paymentInfo.destinationChainId,
@@ -558,12 +693,22 @@ 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 ?? "";
-  const tokenInfo = extractTokenInfo(paymentInfo, chainId, txHash);
+  const tokenInfo = await extractTokenInfo(
+    paymentInfo,
+    chainId,
+    txHash,
+    clients
+  );
   return {
     senderAddress: paymentInfo.sender,
     receiverAddress: paymentInfo.receiver,
@@ -582,5 +727,6 @@ export {
   decodeBridgePayment,
   decodePayment,
   decodeYodlFromLogs,
-  decodeYodlPayment
+  decodeYodlPayment,
+  detectChain
 };

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@yodlpay/payment-decoder",
-	"version": "1.2.1",
+	"version": "1.3.1",
 	"description": "Decode Yodl payment hashes into structured payment data",
 	"keywords": [
 		"yodl",
@@ -38,8 +38,8 @@
 		"prepublishOnly": "bun run build"
 	},
 	"devDependencies": {
-		"@biomejs/biome": "^2.3.14",
-		"@relayprotocol/relay-sdk": "^5.1.0",
+		"@biomejs/biome": "^2.4.4",
+		"@relayprotocol/relay-sdk": "^5.2.0",
 		"@semantic-release/changelog": "^6.0.3",
 		"@semantic-release/git": "^10.0.1",
 		"@types/bun": "latest",
@@ -48,7 +48,7 @@
 		"zod": "^4.3.6"
 	},
 	"dependencies": {
-		"@yodlpay/tokenlists": "^1.1.7"
+		"@yodlpay/tokenlists": "^1.1.12"
 	},
 	"peerDependencies": {
 		"typescript": "^5",