@yodlpay/payment-decoder

Decode Yodl payment transaction hashes into structured payment data. Supports direct payments, swaps, and cross-chain bridges.

Installation

npm install @yodlpay/payment-decoder

Usage

import { decodeYodlPayment, type ChainClients } from "@yodlpay/payment-decoder";
import { createPublicClient, http } from "viem";
import { arbitrum, base, bsc } from "viem/chains";

// Create a map of chain clients with your RPC URLs
const clients = {
  [arbitrum.id]: createPublicClient({ chain: arbitrum, transport: http("https://your-arbitrum-rpc.com") }),
  [base.id]: createPublicClient({ chain: base, transport: http("https://your-base-rpc.com") }),
  [bsc.id]: createPublicClient({ chain: bsc, transport: http("https://your-bsc-rpc.com") }),
} as ChainClients;

const payment = await decodeYodlPayment("0x1234...abcd", base.id, clients);

console.log(payment.senderAddress, "→", payment.receiverAddress);
console.log("Net:", payment.tokenOutAmountNet, "Gross:", payment.tokenOutAmountGross);

API

decodeYodlPayment(hash, chainId, clients)

Decode a Yodl payment transaction into a structured YodlPayment object.

• hash - Transaction hash to decode
• 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.

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>

CLI

Decode a transaction directly from the command line. Outputs JSON to stdout.

bun run decode <txHash> [chainId]

Arguments:

• txHash - The transaction hash (64 hex characters with 0x prefix)
• chainId (optional) - The chain ID where the transaction occurred (e.g., 8453 for Base, 42161 for Arbitrum). If omitted, the chain is auto-detected.

Examples:

# 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.

Understanding Amounts

When a payment involves a swap or bridge, there are two output amounts:

• tokenOutAmountGross - Total output from the swap/bridge (before fees and rebates)
• tokenOutAmountNet - What the receiver actually received

The difference is the Relay fee, which covers execution costs, swap costs, and Relay's service fee:

Swap output: 172,403 USDT  (tokenOutAmountGross)
├── Receiver gets: 169,492 USDT  (tokenOutAmountNet)
└── Relay fee:      2,911 USDT

For direct payments (no swap), both values are equal.

Always use tokenOutAmountNet when you need to know how much the receiver got paid.

Errors

• NoYodlEventError - No Yodl payment event found in the transaction
• NoBridgeFoundError - No bridge transaction found for the given hash

License

See license in LICENSE.md