@octaflowlabs/onchain-sdk 1.4.2 → 1.4.4

package/README.md

@@ -72,6 +72,7 @@ import {
 | `formattedAmountForDisplay` | `(amount, decimals, options?) => string` | Locale-aware formatting with group separators, scientific notation for large numbers, and threshold display for tiny amounts. |
 | `parsedAmount` | `(amount: string, decimals: number) => bigint` | Parse a human-readable amount string into its smallest-unit `bigint`. |
 | `normalizeAddress` | `(address: string) => string` | Validate and checksum an Ethereum address. |
+| `normalizeEvmAddress` | `(address: string \| null \| undefined) => string \| null` | Validate, trim, and lowercase an EVM address, returning `null` for empty or invalid values. |
 | `getShortenTransactionHashOrAddress` | `(value, first?, last?) => string` | Shorten a tx hash or address (e.g. `0xAbCd…1234`). |
 | `getShortenData` | `(data, first?, last?) => string` | Shorten arbitrary hex data. |
 | `transformBigInt` | `(obj: ContractTransaction) => object` | Convert all `bigint` properties to strings for JSON serialization. |
@@ -103,11 +104,26 @@ Each `NetworkField` entry includes `id`, `name`, `chainId`, `rpcUrl`, optional `
 |---|---|
 | `BASIC_TOKENS_BY_CHAIN` | Hardcoded ERC-20 token metadata (USDC, USDT, etc.) grouped by chain ID for Ethereum, BSC, Polygon, and Arbitrum. |
 
+### Stablecoin registry
+
+| Export | Description |
+|---|---|
+| `STABLECOIN_CONTRACTS_BY_CHAIN_ID` | Allowlisted USDC, USDT, and OSC test stablecoin contracts grouped by chain ID. |
+| `getStablecoinContractsByChainId` | `(chainId) => readonly StablecoinContractData[]` — return allowlisted stablecoin metadata for one chain. |
+| `getStablecoinContractBySymbolAndChainId` | `(symbol, chainId) => StablecoinContractData \| null` — resolve one allowlisted stablecoin contract by symbol and chain ID. |
+| `isAllowedStablecoinContract` | `(chainId, contractAddress) => boolean` — normalize and check whether a contract is an allowlisted stablecoin on a chain. |
+
+### Alchemy webhooks
+
+| Export | Description |
+|---|---|
+| `extractPoolInboundStablecoinEvents` | `(payload, poolAddress) => PoolInboundStablecoinEvent[]` — extract inbound token transfers to a pool when the token contract is an allowlisted stablecoin. |
+
 ### Types
 
 All interfaces and type aliases are exported for consumer use:
 
-`BroadcastTransactionOptions`, `BuildMaxNativeTransferTxOptions`, `BuildUnsignedTransferTxOptions`, `BuildBaseUnsignedTransferTxParams`, `EstimateGasLimitFromProviderProps`, `GasEstimateResult`, `EstimateTransactionOptions`, `EstimateTransactionResult`, `PrepareTransactionParams`, `PrepareTransactionResult`, `TxStatusOptions`, `TxStatusResponse`, `FormatAmountOptions`, `TransactionRequest`, `GetBalanceParams`, `GetBalancesParams`, `GetBalancesChainRequest`, `GetBalanceResult`, `ChainBalances`, `TokenBalance`, `ChainGroup`, `NetworkField`, `NetworkId`, `NetworkCategory`, `BasicTokenData`, `BasicTokenSymbol`, `ChainTokenDataMap`, `EvmGeneratedWallet`, `EvmDerivedWallet`, `EntropySource`.
+`BroadcastTransactionOptions`, `BuildMaxNativeTransferTxOptions`, `BuildUnsignedTransferTxOptions`, `BuildBaseUnsignedTransferTxParams`, `EstimateGasLimitFromProviderProps`, `GasEstimateResult`, `EstimateTransactionOptions`, `EstimateTransactionResult`, `PrepareTransactionParams`, `PrepareTransactionResult`, `TxStatusOptions`, `TxStatusResponse`, `FormatAmountOptions`, `TransactionRequest`, `GetBalanceParams`, `GetBalancesParams`, `GetBalancesChainRequest`, `GetBalanceResult`, `ChainBalances`, `TokenBalance`, `ChainGroup`, `NetworkField`, `NetworkId`, `NetworkCategory`, `BasicTokenData`, `BasicTokenSymbol`, `ChainTokenDataMap`, `StablecoinContractData`, `StablecoinContractsByChainId`, `StablecoinSymbol`, `EvmGeneratedWallet`, `EvmDerivedWallet`, `EntropySource`.
 
 ## Design notes
 

package/dist/cjs/constants/STABLECOINS_REGISTRY.d.ts

@@ -0,0 +1,13 @@
+export type StablecoinSymbol = 'USDC' | 'USDT' | 'OSC';
+export interface StablecoinContractData {
+    chainId: number;
+    symbol: StablecoinSymbol;
+    name: string;
+    address: string;
+    decimals: number;
+}
+export type StablecoinContractsByChainId = Readonly<Record<number, readonly StablecoinContractData[]>>;
+export declare const STABLECOIN_CONTRACTS_BY_CHAIN_ID: StablecoinContractsByChainId;
+export declare const getStablecoinContractsByChainId: (chainId: number | null | undefined) => readonly StablecoinContractData[];
+export declare const getStablecoinContractBySymbolAndChainId: (symbol: StablecoinSymbol, chainId: number | null | undefined) => StablecoinContractData | null;
+export declare const isAllowedStablecoinContract: (chainId: number | null | undefined, contractAddress: string | null | undefined) => boolean;

package/dist/cjs/constants/STABLECOINS_REGISTRY.js

@@ -0,0 +1,101 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.isAllowedStablecoinContract = exports.getStablecoinContractBySymbolAndChainId = exports.getStablecoinContractsByChainId = exports.STABLECOIN_CONTRACTS_BY_CHAIN_ID = void 0;
+/** local imports */
+const normalizeAddress_1 = require("../utils/normalizeAddress");
+exports.STABLECOIN_CONTRACTS_BY_CHAIN_ID = {
+    1: [
+        {
+            chainId: 1,
+            symbol: 'USDC',
+            name: 'USD Coin',
+            address: '0xa0b86991c6218b36c1d19d4a2e9eb0ce3606eb48',
+            decimals: 6,
+        },
+        {
+            chainId: 1,
+            symbol: 'USDT',
+            name: 'Tether USD',
+            address: '0xdac17f958d2ee523a2206206994597c13d831ec7',
+            decimals: 6,
+        },
+    ],
+    56: [
+        {
+            chainId: 56,
+            symbol: 'USDC',
+            name: 'USD Coin',
+            address: '0x8ac76a51cc950d9822d68b83fe1ad97b32cd580d',
+            decimals: 18,
+        },
+        {
+            chainId: 56,
+            symbol: 'USDT',
+            name: 'Tether USD',
+            address: '0x55d398326f99059ff775485246999027b3197955',
+            decimals: 18,
+        },
+    ],
+    137: [
+        {
+            chainId: 137,
+            symbol: 'USDC',
+            name: 'USD Coin Bridged',
+            address: '0x2791bca1f2de4661ed88a30c99a7a9449aa84174',
+            decimals: 6,
+        },
+        {
+            chainId: 137,
+            symbol: 'USDC',
+            name: 'USD Coin',
+            address: '0x3c499c542cef5e3811e1192ce70d8cc03d5c3359',
+            decimals: 6,
+        },
+        {
+            chainId: 137,
+            symbol: 'USDT',
+            name: 'Tether USD',
+            address: '0xc2132d05d31c914a87c6611c10748aeb04b58e8f',
+            decimals: 6,
+        },
+    ],
+    11155111: [
+        {
+            chainId: 11155111,
+            symbol: 'USDC',
+            name: 'Sepolia USDC',
+            address: '0x1c7d4b196cb0c7b01d743fbc6116a902379c7238',
+            decimals: 6,
+        },
+        {
+            chainId: 11155111,
+            symbol: 'OSC',
+            name: 'OSC Test Stablecoin',
+            address: '0x4357555de1c8ed60218dd42b0b4f404e31b6d744',
+            decimals: 6,
+        },
+    ],
+};
+const getStablecoinContractsByChainId = (chainId) => {
+    if (chainId == null)
+        return [];
+    return exports.STABLECOIN_CONTRACTS_BY_CHAIN_ID[chainId] || [];
+};
+exports.getStablecoinContractsByChainId = getStablecoinContractsByChainId;
+const getStablecoinContractBySymbolAndChainId = (symbol, chainId) => {
+    const contracts = (0, exports.getStablecoinContractsByChainId)(chainId);
+    return contracts.find((contract) => contract.symbol === symbol) || null;
+};
+exports.getStablecoinContractBySymbolAndChainId = getStablecoinContractBySymbolAndChainId;
+const isAllowedStablecoinContract = (chainId, contractAddress) => {
+    if (chainId == null)
+        return false;
+    const normalizedAddress = (0, normalizeAddress_1.normalizeEvmAddress)(contractAddress);
+    if (!normalizedAddress)
+        return false;
+    const allowedContracts = (0, exports.getStablecoinContractsByChainId)(chainId);
+    if (!allowedContracts.length)
+        return false;
+    return allowedContracts.some((contract) => contract.address === normalizedAddress);
+};
+exports.isAllowedStablecoinContract = isAllowedStablecoinContract;

package/dist/cjs/index.d.ts

@@ -5,6 +5,7 @@ export { ERC20_TOKEN_CONTRACT_ABI };
 export { GAS_LIMIT_PER_TX_TYPE, MULTICALL3_ADDRESS } from './constants/constants';
 export { NetworkField, NetworkRegistry, NETWORKS_REGISTRY } from './constants/NETWORKS_REGISTRY';
 export { BASIC_TOKENS_BY_CHAIN, BasicTokenData, BasicTokenSymbol, ChainTokenDataMap, } from './constants/BASIC_TOKENS_REGISTRY';
+export { STABLECOIN_CONTRACTS_BY_CHAIN_ID, getStablecoinContractBySymbolAndChainId, getStablecoinContractsByChainId, isAllowedStablecoinContract, StablecoinContractData, StablecoinContractsByChainId, StablecoinSymbol, } from './constants/STABLECOINS_REGISTRY';
 /** basic blockchain exports */
 export { buildBaseUnsignedTransferTx, buildMaxNativeTransferTx, buildUnsignedTransferTx, } from './blockchain/buildUnsignedTransferTx';
 export { broadcastTransaction } from './blockchain/broadcastTransaction';
@@ -26,8 +27,10 @@ import NATIVE_TOKENS from './utils/tokens';
 export { NATIVE_TOKENS };
 export { formattedAmountForDisplay, parsedAmount } from './utils/formatAmount';
 export { handleErrorMessages, errorMessagesForBroadcast, errorMessagesForGasLimitEstimation, } from './utils/handleErrorMessages';
-export { normalizeAddress } from './utils/normalizeAddress';
+export { normalizeAddress, normalizeEvmAddress } from './utils/normalizeAddress';
 export { toGwei, tryParseGweiToWei, parseGasLimit } from './utils/parseGasFees';
 export { getFeePresets, calcReserve, estimateSeconds, getBlockTime, BLOCK_TIME_BY_CHAIN, } from './utils/feePresets';
+/** webhook exports */
+export { extractPoolInboundStablecoinEvents } from './webhooks/alchemyAddressActivity';
 /** types exports */
 export { BroadcastTransactionOptions, BuildMaxNativeTransferTxOptions, BuildUnsignedTransferTxOptions, EstimateGasLimitFromProviderProps, GasEstimateResult, TxStatusOptions, BuildBaseUnsignedTransferTxParams, TxStatusResponse, EstimateTransactionOptions, EstimateTransactionResult, PrepareTransactionParams, PrepareTransactionResult, FormatAmountOptions, TransactionRequest, GetBalanceParams, GetBalancesParams, GetBalancesChainRequest, GetBalanceResult, ChainBalances, TokenBalance, ChainGroup, FeePreset, FeePresetLabel, FeeEstimateSeconds, ResolvedFees, EIP1559Fees, LegacyFees, FeeModel, FeeHistoryData, FeeDataInput, } from './types/common';

package/dist/cjs/index.js

@@ -3,7 +3,7 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
     return (mod && mod.__esModule) ? mod : { "default": mod };
 };
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.BLOCK_TIME_BY_CHAIN = exports.getBlockTime = exports.estimateSeconds = exports.calcReserve = exports.getFeePresets = exports.parseGasLimit = exports.tryParseGweiToWei = exports.toGwei = exports.normalizeAddress = exports.errorMessagesForGasLimitEstimation = exports.errorMessagesForBroadcast = exports.handleErrorMessages = exports.parsedAmount = exports.formattedAmountForDisplay = exports.NATIVE_TOKENS = exports.transformBigInt = exports.getShortenData = exports.getShortenTransactionHashOrAddress = exports.signTransaction = exports.signMessage = exports.createWallet = exports.EvmWalletService = exports.fetchFeeSnapshot = exports.prepareTransaction = exports.estimateTransaction = exports.getBalances = exports.getBalance = exports.txStatus = exports.getProvider = exports.estimateGasLimitFromProvider = exports.broadcastTransaction = exports.buildUnsignedTransferTx = exports.buildMaxNativeTransferTx = exports.buildBaseUnsignedTransferTx = exports.BASIC_TOKENS_BY_CHAIN = exports.NETWORKS_REGISTRY = exports.MULTICALL3_ADDRESS = exports.GAS_LIMIT_PER_TX_TYPE = exports.ERC20_TOKEN_CONTRACT_ABI = void 0;
+exports.extractPoolInboundStablecoinEvents = exports.BLOCK_TIME_BY_CHAIN = exports.getBlockTime = exports.estimateSeconds = exports.calcReserve = exports.getFeePresets = exports.parseGasLimit = exports.tryParseGweiToWei = exports.toGwei = exports.normalizeEvmAddress = exports.normalizeAddress = exports.errorMessagesForGasLimitEstimation = exports.errorMessagesForBroadcast = exports.handleErrorMessages = exports.parsedAmount = exports.formattedAmountForDisplay = exports.NATIVE_TOKENS = exports.transformBigInt = exports.getShortenData = exports.getShortenTransactionHashOrAddress = exports.signTransaction = exports.signMessage = exports.createWallet = exports.EvmWalletService = exports.fetchFeeSnapshot = exports.prepareTransaction = exports.estimateTransaction = exports.getBalances = exports.getBalance = exports.txStatus = exports.getProvider = exports.estimateGasLimitFromProvider = exports.broadcastTransaction = exports.buildUnsignedTransferTx = exports.buildMaxNativeTransferTx = exports.buildBaseUnsignedTransferTx = exports.isAllowedStablecoinContract = exports.getStablecoinContractsByChainId = exports.getStablecoinContractBySymbolAndChainId = exports.STABLECOIN_CONTRACTS_BY_CHAIN_ID = exports.BASIC_TOKENS_BY_CHAIN = exports.NETWORKS_REGISTRY = exports.MULTICALL3_ADDRESS = exports.GAS_LIMIT_PER_TX_TYPE = exports.ERC20_TOKEN_CONTRACT_ABI = void 0;
 /** ABIs exports */
 const ERC20_TOKEN_CONTRACT_ABI_1 = __importDefault(require("./ABIs/ERC20_TOKEN_CONTRACT_ABI"));
 exports.ERC20_TOKEN_CONTRACT_ABI = ERC20_TOKEN_CONTRACT_ABI_1.default;
@@ -15,6 +15,11 @@ var NETWORKS_REGISTRY_1 = require("./constants/NETWORKS_REGISTRY");
 Object.defineProperty(exports, "NETWORKS_REGISTRY", { enumerable: true, get: function () { return NETWORKS_REGISTRY_1.NETWORKS_REGISTRY; } });
 var BASIC_TOKENS_REGISTRY_1 = require("./constants/BASIC_TOKENS_REGISTRY");
 Object.defineProperty(exports, "BASIC_TOKENS_BY_CHAIN", { enumerable: true, get: function () { return BASIC_TOKENS_REGISTRY_1.BASIC_TOKENS_BY_CHAIN; } });
+var STABLECOINS_REGISTRY_1 = require("./constants/STABLECOINS_REGISTRY");
+Object.defineProperty(exports, "STABLECOIN_CONTRACTS_BY_CHAIN_ID", { enumerable: true, get: function () { return STABLECOINS_REGISTRY_1.STABLECOIN_CONTRACTS_BY_CHAIN_ID; } });
+Object.defineProperty(exports, "getStablecoinContractBySymbolAndChainId", { enumerable: true, get: function () { return STABLECOINS_REGISTRY_1.getStablecoinContractBySymbolAndChainId; } });
+Object.defineProperty(exports, "getStablecoinContractsByChainId", { enumerable: true, get: function () { return STABLECOINS_REGISTRY_1.getStablecoinContractsByChainId; } });
+Object.defineProperty(exports, "isAllowedStablecoinContract", { enumerable: true, get: function () { return STABLECOINS_REGISTRY_1.isAllowedStablecoinContract; } });
 /** basic blockchain exports */
 var buildUnsignedTransferTx_1 = require("./blockchain/buildUnsignedTransferTx");
 Object.defineProperty(exports, "buildBaseUnsignedTransferTx", { enumerable: true, get: function () { return buildUnsignedTransferTx_1.buildBaseUnsignedTransferTx; } });
@@ -61,6 +66,7 @@ Object.defineProperty(exports, "errorMessagesForBroadcast", { enumerable: true,
 Object.defineProperty(exports, "errorMessagesForGasLimitEstimation", { enumerable: true, get: function () { return handleErrorMessages_1.errorMessagesForGasLimitEstimation; } });
 var normalizeAddress_1 = require("./utils/normalizeAddress");
 Object.defineProperty(exports, "normalizeAddress", { enumerable: true, get: function () { return normalizeAddress_1.normalizeAddress; } });
+Object.defineProperty(exports, "normalizeEvmAddress", { enumerable: true, get: function () { return normalizeAddress_1.normalizeEvmAddress; } });
 var parseGasFees_1 = require("./utils/parseGasFees");
 Object.defineProperty(exports, "toGwei", { enumerable: true, get: function () { return parseGasFees_1.toGwei; } });
 Object.defineProperty(exports, "tryParseGweiToWei", { enumerable: true, get: function () { return parseGasFees_1.tryParseGweiToWei; } });
@@ -71,3 +77,6 @@ Object.defineProperty(exports, "calcReserve", { enumerable: true, get: function
 Object.defineProperty(exports, "estimateSeconds", { enumerable: true, get: function () { return feePresets_1.estimateSeconds; } });
 Object.defineProperty(exports, "getBlockTime", { enumerable: true, get: function () { return feePresets_1.getBlockTime; } });
 Object.defineProperty(exports, "BLOCK_TIME_BY_CHAIN", { enumerable: true, get: function () { return feePresets_1.BLOCK_TIME_BY_CHAIN; } });
+/** webhook exports */
+var alchemyAddressActivity_1 = require("./webhooks/alchemyAddressActivity");
+Object.defineProperty(exports, "extractPoolInboundStablecoinEvents", { enumerable: true, get: function () { return alchemyAddressActivity_1.extractPoolInboundStablecoinEvents; } });

package/dist/cjs/utils/activityDedupe.d.ts

@@ -0,0 +1,7 @@
+export interface TransactionActivityDedupeInput {
+    hash?: string | null;
+    log?: {
+        logIndex?: string | null;
+    } | null;
+}
+export declare const getTransactionActivityDedupeKey: (activity: TransactionActivityDedupeInput) => string | null;

package/dist/cjs/utils/activityDedupe.js

@@ -0,0 +1,11 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.getTransactionActivityDedupeKey = void 0;
+const getTransactionActivityDedupeKey = (activity) => {
+    const hash = activity.hash?.trim();
+    if (!hash)
+        return null;
+    const logIndex = activity.log?.logIndex?.trim();
+    return logIndex ? `${hash}:${logIndex}` : hash;
+};
+exports.getTransactionActivityDedupeKey = getTransactionActivityDedupeKey;

package/dist/cjs/utils/normalizeAddress.d.ts

@@ -1 +1,2 @@
 export declare const normalizeAddress: (address: string) => string;
+export declare const normalizeEvmAddress: (address: string | null | undefined) => string | null;

package/dist/cjs/utils/normalizeAddress.js

@@ -1,6 +1,6 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.normalizeAddress = void 0;
+exports.normalizeEvmAddress = exports.normalizeAddress = void 0;
 /** npm imports */
 const ethers_1 = require("ethers");
 const normalizeAddress = (address) => {
@@ -13,3 +13,14 @@ const normalizeAddress = (address) => {
     }
 };
 exports.normalizeAddress = normalizeAddress;
+const normalizeEvmAddress = (address) => {
+    if (!address || typeof address !== 'string')
+        return null;
+    try {
+        return (0, exports.normalizeAddress)(address.trim()).toLowerCase();
+    }
+    catch {
+        return null;
+    }
+};
+exports.normalizeEvmAddress = normalizeEvmAddress;

package/dist/cjs/webhooks/alchemyAddressActivity.d.ts

@@ -0,0 +1,39 @@
+export interface AlchemyAddressActivity {
+    category?: string;
+    asset?: string;
+    value?: number | null;
+    fromAddress?: string | null;
+    toAddress?: string | null;
+    hash?: string | null;
+    erc721TokenId?: string | number | null;
+    rawContract?: {
+        address?: string | null;
+    } | null;
+    log?: {
+        removed?: boolean;
+        logIndex?: string | null;
+    } | null;
+}
+export interface AlchemyAddressActivityPayload {
+    id?: string;
+    webhookId?: string;
+    type?: string;
+    event?: {
+        network?: string;
+        activity?: AlchemyAddressActivity[];
+    };
+}
+export interface PoolInboundStablecoinEvent {
+    webhookDeliveryId?: string;
+    webhookId?: string;
+    alchemyNetwork: string;
+    chainId: number | null;
+    txHash: string;
+    fromAddress: string;
+    toAddress: string;
+    amount: number;
+    asset: string;
+    tokenContractAddress?: string | null;
+    dedupeKey: string;
+}
+export declare function extractPoolInboundStablecoinEvents(payload: AlchemyAddressActivityPayload, poolAddress: string | null | undefined): PoolInboundStablecoinEvent[];

package/dist/cjs/webhooks/alchemyAddressActivity.js

@@ -0,0 +1,75 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.extractPoolInboundStablecoinEvents = extractPoolInboundStablecoinEvents;
+/** local imports */
+const STABLECOINS_REGISTRY_1 = require("../constants/STABLECOINS_REGISTRY");
+const activityDedupe_1 = require("../utils/activityDedupe");
+const normalizeAddress_1 = require("../utils/normalizeAddress");
+const CHAIN_ID_TO_ALCHEMY_NETWORK = {
+    1: 'ETH_MAINNET',
+    56: 'BNB_MAINNET',
+    137: 'MATIC_MAINNET',
+    11155111: 'ETH_SEPOLIA',
+};
+const ALCHEMY_NETWORK_TO_CHAIN_ID = Object.fromEntries(Object.entries(CHAIN_ID_TO_ALCHEMY_NETWORK).map(([chainId, network]) => [
+    network,
+    Number(chainId),
+]));
+function chainIdFromAlchemyNetwork(network) {
+    if (!network)
+        return null;
+    const chainId = ALCHEMY_NETWORK_TO_CHAIN_ID[network];
+    return chainId === undefined ? null : chainId;
+}
+function extractPoolInboundStablecoinEvents(payload, poolAddress) {
+    const poolAddressLower = (0, normalizeAddress_1.normalizeEvmAddress)(poolAddress);
+    if (!poolAddressLower)
+        return [];
+    if (payload.type !== 'ADDRESS_ACTIVITY')
+        return [];
+    const network = payload.event?.network;
+    const chainId = chainIdFromAlchemyNetwork(network);
+    const activity = payload.event?.activity;
+    if (!activity?.length)
+        return [];
+    const out = [];
+    for (const item of activity) {
+        if (item.category !== 'token')
+            continue;
+        if (item.log?.removed === true)
+            continue;
+        if (item.erc721TokenId != null && item.erc721TokenId !== '')
+            continue;
+        if (!(0, STABLECOINS_REGISTRY_1.isAllowedStablecoinContract)(chainId, item.rawContract?.address))
+            continue;
+        const value = item.value;
+        if (value === undefined || value === null || typeof value !== 'number' || !(value > 0))
+            continue;
+        const to = (0, normalizeAddress_1.normalizeEvmAddress)(item.toAddress);
+        const from = (0, normalizeAddress_1.normalizeEvmAddress)(item.fromAddress);
+        if (!to || !from)
+            continue;
+        if (to !== poolAddressLower)
+            continue;
+        const txHash = item.hash?.trim();
+        if (!txHash)
+            continue;
+        const dedupeKey = (0, activityDedupe_1.getTransactionActivityDedupeKey)(item);
+        if (!dedupeKey)
+            continue;
+        out.push({
+            webhookDeliveryId: payload.id,
+            webhookId: payload.webhookId,
+            alchemyNetwork: network || 'UNKNOWN',
+            chainId,
+            txHash,
+            fromAddress: from,
+            toAddress: to,
+            amount: value,
+            asset: item.asset || '',
+            tokenContractAddress: item.rawContract?.address,
+            dedupeKey,
+        });
+    }
+    return out;
+}

package/dist/constants/STABLECOINS_REGISTRY.d.ts

@@ -0,0 +1,13 @@
+export type StablecoinSymbol = 'USDC' | 'USDT' | 'OSC';
+export interface StablecoinContractData {
+    chainId: number;
+    symbol: StablecoinSymbol;
+    name: string;
+    address: string;
+    decimals: number;
+}
+export type StablecoinContractsByChainId = Readonly<Record<number, readonly StablecoinContractData[]>>;
+export declare const STABLECOIN_CONTRACTS_BY_CHAIN_ID: StablecoinContractsByChainId;
+export declare const getStablecoinContractsByChainId: (chainId: number | null | undefined) => readonly StablecoinContractData[];
+export declare const getStablecoinContractBySymbolAndChainId: (symbol: StablecoinSymbol, chainId: number | null | undefined) => StablecoinContractData | null;
+export declare const isAllowedStablecoinContract: (chainId: number | null | undefined, contractAddress: string | null | undefined) => boolean;

package/dist/constants/STABLECOINS_REGISTRY.js

@@ -0,0 +1,95 @@
+/** local imports */
+import { normalizeEvmAddress } from '../utils/normalizeAddress';
+export const STABLECOIN_CONTRACTS_BY_CHAIN_ID = {
+    1: [
+        {
+            chainId: 1,
+            symbol: 'USDC',
+            name: 'USD Coin',
+            address: '0xa0b86991c6218b36c1d19d4a2e9eb0ce3606eb48',
+            decimals: 6,
+        },
+        {
+            chainId: 1,
+            symbol: 'USDT',
+            name: 'Tether USD',
+            address: '0xdac17f958d2ee523a2206206994597c13d831ec7',
+            decimals: 6,
+        },
+    ],
+    56: [
+        {
+            chainId: 56,
+            symbol: 'USDC',
+            name: 'USD Coin',
+            address: '0x8ac76a51cc950d9822d68b83fe1ad97b32cd580d',
+            decimals: 18,
+        },
+        {
+            chainId: 56,
+            symbol: 'USDT',
+            name: 'Tether USD',
+            address: '0x55d398326f99059ff775485246999027b3197955',
+            decimals: 18,
+        },
+    ],
+    137: [
+        {
+            chainId: 137,
+            symbol: 'USDC',
+            name: 'USD Coin Bridged',
+            address: '0x2791bca1f2de4661ed88a30c99a7a9449aa84174',
+            decimals: 6,
+        },
+        {
+            chainId: 137,
+            symbol: 'USDC',
+            name: 'USD Coin',
+            address: '0x3c499c542cef5e3811e1192ce70d8cc03d5c3359',
+            decimals: 6,
+        },
+        {
+            chainId: 137,
+            symbol: 'USDT',
+            name: 'Tether USD',
+            address: '0xc2132d05d31c914a87c6611c10748aeb04b58e8f',
+            decimals: 6,
+        },
+    ],
+    11155111: [
+        {
+            chainId: 11155111,
+            symbol: 'USDC',
+            name: 'Sepolia USDC',
+            address: '0x1c7d4b196cb0c7b01d743fbc6116a902379c7238',
+            decimals: 6,
+        },
+        {
+            chainId: 11155111,
+            symbol: 'OSC',
+            name: 'OSC Test Stablecoin',
+            address: '0x4357555de1c8ed60218dd42b0b4f404e31b6d744',
+            decimals: 6,
+        },
+    ],
+};
+export const getStablecoinContractsByChainId = (chainId) => {
+    if (chainId == null)
+        return [];
+    return STABLECOIN_CONTRACTS_BY_CHAIN_ID[chainId] || [];
+};
+export const getStablecoinContractBySymbolAndChainId = (symbol, chainId) => {
+    const contracts = getStablecoinContractsByChainId(chainId);
+    return contracts.find((contract) => contract.symbol === symbol) || null;
+};
+export const isAllowedStablecoinContract = (chainId, contractAddress) => {
+    if (chainId == null)
+        return false;
+    const normalizedAddress = normalizeEvmAddress(contractAddress);
+    if (!normalizedAddress)
+        return false;
+    const allowedContracts = getStablecoinContractsByChainId(chainId);
+    if (!allowedContracts.length)
+        return false;
+    return allowedContracts.some((contract) => contract.address === normalizedAddress);
+};

package/dist/index.d.ts

@@ -5,6 +5,7 @@ export { ERC20_TOKEN_CONTRACT_ABI };
 export { GAS_LIMIT_PER_TX_TYPE, MULTICALL3_ADDRESS } from './constants/constants';
 export { NetworkField, NetworkRegistry, NETWORKS_REGISTRY } from './constants/NETWORKS_REGISTRY';
 export { BASIC_TOKENS_BY_CHAIN, BasicTokenData, BasicTokenSymbol, ChainTokenDataMap, } from './constants/BASIC_TOKENS_REGISTRY';
+export { STABLECOIN_CONTRACTS_BY_CHAIN_ID, getStablecoinContractBySymbolAndChainId, getStablecoinContractsByChainId, isAllowedStablecoinContract, StablecoinContractData, StablecoinContractsByChainId, StablecoinSymbol, } from './constants/STABLECOINS_REGISTRY';
 /** basic blockchain exports */
 export { buildBaseUnsignedTransferTx, buildMaxNativeTransferTx, buildUnsignedTransferTx, } from './blockchain/buildUnsignedTransferTx';
 export { broadcastTransaction } from './blockchain/broadcastTransaction';
@@ -26,8 +27,10 @@ import NATIVE_TOKENS from './utils/tokens';
 export { NATIVE_TOKENS };
 export { formattedAmountForDisplay, parsedAmount } from './utils/formatAmount';
 export { handleErrorMessages, errorMessagesForBroadcast, errorMessagesForGasLimitEstimation, } from './utils/handleErrorMessages';
-export { normalizeAddress } from './utils/normalizeAddress';
+export { normalizeAddress, normalizeEvmAddress } from './utils/normalizeAddress';
 export { toGwei, tryParseGweiToWei, parseGasLimit } from './utils/parseGasFees';
 export { getFeePresets, calcReserve, estimateSeconds, getBlockTime, BLOCK_TIME_BY_CHAIN, } from './utils/feePresets';
+/** webhook exports */
+export { extractPoolInboundStablecoinEvents } from './webhooks/alchemyAddressActivity';
 /** types exports */
 export { BroadcastTransactionOptions, BuildMaxNativeTransferTxOptions, BuildUnsignedTransferTxOptions, EstimateGasLimitFromProviderProps, GasEstimateResult, TxStatusOptions, BuildBaseUnsignedTransferTxParams, TxStatusResponse, EstimateTransactionOptions, EstimateTransactionResult, PrepareTransactionParams, PrepareTransactionResult, FormatAmountOptions, TransactionRequest, GetBalanceParams, GetBalancesParams, GetBalancesChainRequest, GetBalanceResult, ChainBalances, TokenBalance, ChainGroup, FeePreset, FeePresetLabel, FeeEstimateSeconds, ResolvedFees, EIP1559Fees, LegacyFees, FeeModel, FeeHistoryData, FeeDataInput, } from './types/common';

package/dist/index.js

@@ -5,6 +5,7 @@ export { ERC20_TOKEN_CONTRACT_ABI };
 export { GAS_LIMIT_PER_TX_TYPE, MULTICALL3_ADDRESS } from './constants/constants';
 export { NETWORKS_REGISTRY } from './constants/NETWORKS_REGISTRY';
 export { BASIC_TOKENS_BY_CHAIN, } from './constants/BASIC_TOKENS_REGISTRY';
+export { STABLECOIN_CONTRACTS_BY_CHAIN_ID, getStablecoinContractBySymbolAndChainId, getStablecoinContractsByChainId, isAllowedStablecoinContract, } from './constants/STABLECOINS_REGISTRY';
 /** basic blockchain exports */
 export { buildBaseUnsignedTransferTx, buildMaxNativeTransferTx, buildUnsignedTransferTx, } from './blockchain/buildUnsignedTransferTx';
 export { broadcastTransaction } from './blockchain/broadcastTransaction';
@@ -25,6 +26,8 @@ import NATIVE_TOKENS from './utils/tokens';
 export { NATIVE_TOKENS };
 export { formattedAmountForDisplay, parsedAmount } from './utils/formatAmount';
 export { handleErrorMessages, errorMessagesForBroadcast, errorMessagesForGasLimitEstimation, } from './utils/handleErrorMessages';
-export { normalizeAddress } from './utils/normalizeAddress';
+export { normalizeAddress, normalizeEvmAddress } from './utils/normalizeAddress';
 export { toGwei, tryParseGweiToWei, parseGasLimit } from './utils/parseGasFees';
 export { getFeePresets, calcReserve, estimateSeconds, getBlockTime, BLOCK_TIME_BY_CHAIN, } from './utils/feePresets';
+/** webhook exports */
+export { extractPoolInboundStablecoinEvents } from './webhooks/alchemyAddressActivity';

package/dist/utils/activityDedupe.d.ts

@@ -0,0 +1,7 @@
+export interface TransactionActivityDedupeInput {
+    hash?: string | null;
+    log?: {
+        logIndex?: string | null;
+    } | null;
+}
+export declare const getTransactionActivityDedupeKey: (activity: TransactionActivityDedupeInput) => string | null;

package/dist/utils/activityDedupe.js

@@ -0,0 +1,7 @@
+export const getTransactionActivityDedupeKey = (activity) => {
+    const hash = activity.hash?.trim();
+    if (!hash)
+        return null;
+    const logIndex = activity.log?.logIndex?.trim();
+    return logIndex ? `${hash}:${logIndex}` : hash;
+};

package/dist/utils/normalizeAddress.d.ts

@@ -1 +1,2 @@
 export declare const normalizeAddress: (address: string) => string;
+export declare const normalizeEvmAddress: (address: string | null | undefined) => string | null;

package/dist/utils/normalizeAddress.js

@@ -9,3 +9,13 @@ export const normalizeAddress = (address) => {
         throw new Error('Error normalizing address: ' + (e instanceof Error ? e.message : String(e)));
     }
 };
+export const normalizeEvmAddress = (address) => {
+    if (!address || typeof address !== 'string')
+        return null;
+    try {
+        return normalizeAddress(address.trim()).toLowerCase();
+    }
+    catch {
+        return null;
+    }
+};

package/dist/webhooks/alchemyAddressActivity.d.ts

@@ -0,0 +1,39 @@
+export interface AlchemyAddressActivity {
+    category?: string;
+    asset?: string;
+    value?: number | null;
+    fromAddress?: string | null;
+    toAddress?: string | null;
+    hash?: string | null;
+    erc721TokenId?: string | number | null;
+    rawContract?: {
+        address?: string | null;
+    } | null;
+    log?: {
+        removed?: boolean;
+        logIndex?: string | null;
+    } | null;
+}
+export interface AlchemyAddressActivityPayload {
+    id?: string;
+    webhookId?: string;
+    type?: string;
+    event?: {
+        network?: string;
+        activity?: AlchemyAddressActivity[];
+    };
+}
+export interface PoolInboundStablecoinEvent {
+    webhookDeliveryId?: string;
+    webhookId?: string;
+    alchemyNetwork: string;
+    chainId: number | null;
+    txHash: string;
+    fromAddress: string;
+    toAddress: string;
+    amount: number;
+    asset: string;
+    tokenContractAddress?: string | null;
+    dedupeKey: string;
+}
+export declare function extractPoolInboundStablecoinEvents(payload: AlchemyAddressActivityPayload, poolAddress: string | null | undefined): PoolInboundStablecoinEvent[];

package/dist/webhooks/alchemyAddressActivity.js

@@ -0,0 +1,72 @@
+/** local imports */
+import { isAllowedStablecoinContract } from '../constants/STABLECOINS_REGISTRY';
+import { getTransactionActivityDedupeKey } from '../utils/activityDedupe';
+import { normalizeEvmAddress } from '../utils/normalizeAddress';
+const CHAIN_ID_TO_ALCHEMY_NETWORK = {
+    1: 'ETH_MAINNET',
+    56: 'BNB_MAINNET',
+    137: 'MATIC_MAINNET',
+    11155111: 'ETH_SEPOLIA',
+};
+const ALCHEMY_NETWORK_TO_CHAIN_ID = Object.fromEntries(Object.entries(CHAIN_ID_TO_ALCHEMY_NETWORK).map(([chainId, network]) => [
+    network,
+    Number(chainId),
+]));
+function chainIdFromAlchemyNetwork(network) {
+    if (!network)
+        return null;
+    const chainId = ALCHEMY_NETWORK_TO_CHAIN_ID[network];
+    return chainId === undefined ? null : chainId;
+}
+export function extractPoolInboundStablecoinEvents(payload, poolAddress) {
+    const poolAddressLower = normalizeEvmAddress(poolAddress);
+    if (!poolAddressLower)
+        return [];
+    if (payload.type !== 'ADDRESS_ACTIVITY')
+        return [];
+    const network = payload.event?.network;
+    const chainId = chainIdFromAlchemyNetwork(network);
+    const activity = payload.event?.activity;
+    if (!activity?.length)
+        return [];
+    const out = [];
+    for (const item of activity) {
+        if (item.category !== 'token')
+            continue;
+        if (item.log?.removed === true)
+            continue;
+        if (item.erc721TokenId != null && item.erc721TokenId !== '')
+            continue;
+        if (!isAllowedStablecoinContract(chainId, item.rawContract?.address))
+            continue;
+        const value = item.value;
+        if (value === undefined || value === null || typeof value !== 'number' || !(value > 0))
+            continue;
+        const to = normalizeEvmAddress(item.toAddress);
+        const from = normalizeEvmAddress(item.fromAddress);
+        if (!to || !from)
+            continue;
+        if (to !== poolAddressLower)
+            continue;
+        const txHash = item.hash?.trim();
+        if (!txHash)
+            continue;
+        const dedupeKey = getTransactionActivityDedupeKey(item);
+        if (!dedupeKey)
+            continue;
+        out.push({
+            webhookDeliveryId: payload.id,
+            webhookId: payload.webhookId,
+            alchemyNetwork: network || 'UNKNOWN',
+            chainId,
+            txHash,
+            fromAddress: from,
+            toAddress: to,
+            amount: value,
+            asset: item.asset || '',
+            tokenContractAddress: item.rawContract?.address,
+            dedupeKey,
+        });
+    }
+    return out;
+}

package/package.json

@@ -1,8 +1,11 @@
 {
   "name": "@octaflowlabs/onchain-sdk",
-  "version": "1.4.2",
+  "version": "1.4.4",
   "description": "onchain methods for web3",
-  "repository": {"type": "git", "url": "git+https://github.com/octaflowlabs/onchain-sdk.git"},
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/octaflowlabs/onchain-sdk.git"
+  },
   "license": "MIT",
   "main": "dist/cjs/index.js",
   "module": "dist/index.js",