@magnaflow/merchant-utils 1.0.1

package/README.md

@@ -0,0 +1,72 @@
+# @magnaflow/merchant-utils
+
+Shared merchant-facing helpers on top of the core chain and Tron tooling.
+
+## What It Provides
+
+- Cross-chain transaction waiting and friendly error helpers
+- Tron transaction polling helpers
+- TronWeb instance creation from merchant chain config
+- EVM selector-based error formatting
+- Payout order display helpers
+- EIP-712 digest signing utility
+
+## Install
+
+```bash
+npm install @magnaflow/merchant-utils
+```
+
+## Key Exports
+
+- `waitForTransactionCrossChain`
+- `createCrossChainFriendlyErrorMessage`
+- `pollTronTransaction`
+- `pollTronTransaction2`
+- `pollTronTransactionWithBackoff`
+- `createTronWebInstance`
+- `parseEvmError`
+- `createFriendlyErrorMessage`
+- `isTronLikeChain`
+- `isBscLikeChain`
+- `signDigest`
+- `formatPayoutOrderTime`
+- `getPayoutTypeColor`
+- `getPayoutStatusColor`
+- `ORDER_TITLES`
+- `TYPE_DISPLAY_NAMES`
+
+## Example
+
+```ts
+import {
+  createCrossChainFriendlyErrorMessage,
+  waitForTransactionCrossChain,
+} from '@magnaflow/merchant-utils';
+
+const result = await waitForTransactionCrossChain({
+  chainType: 'evm',
+  hash: '0x1234...',
+  client: publicClient,
+  confirmations: 1,
+});
+
+const message = createCrossChainFriendlyErrorMessage('evm', new Error('Operation failed'));
+```
+
+## Notes
+
+- This package is intentionally a helper layer. Full merchant workflows should still live in application services.
+- `@magnaflow/tronsave` remains a separate package for Tron energy rental APIs.
+
+## Development
+
+```bash
+bunx nx run merchant-utils:lint
+bunx nx run merchant-utils:test
+bunx nx run merchant-utils:build
+```
+
+## License
+
+MIT

package/dist/cross-chain.d.ts

@@ -0,0 +1,60 @@
+import type { ChainType } from '@magnaflow/chain-provider';
+import type { TronWeb } from 'tronweb';
+/**
+ * Interface layer: minimal shape that any transaction waiting strategy
+ * (EVM / Tron / future chains) must satisfy.
+ */
+export interface CrossChainWaitResult {
+    hash: string;
+    status: 'success' | 'failed';
+    rawReceipt: unknown;
+}
+/**
+ * EVM wait strategy input (interface layer).
+ */
+export interface EvmWaitConfig {
+    chainType: 'evm';
+    hash: string;
+    client: {
+        waitForTransactionReceipt: (args: {
+            hash: `0x${string}`;
+            timeout?: number;
+            confirmations?: number;
+        }) => Promise<{
+            transactionHash: `0x${string}`;
+            status: 'success' | 'reverted' | 'pending';
+            blockNumber?: bigint;
+            blockHash?: `0x${string}`;
+            gasUsed?: bigint;
+            effectiveGasPrice?: bigint;
+        }>;
+    };
+    timeoutMs?: number;
+    confirmations?: number;
+}
+/**
+ * Tron wait strategy input (interface layer).
+ */
+export interface TronWaitConfig {
+    chainType: 'tron';
+    hash: string;
+    tronWeb: TronWeb;
+    timeoutMs?: number;
+}
+export type WaitForTransactionCrossChainParams = EvmWaitConfig | TronWaitConfig;
+/**
+ * Implementation layer: default cross-chain transaction polling helper
+ * that implements the interface defined by WaitForTransactionCrossChainParams.
+ *
+ * - EVM: delegates to viem-compatible waitForTransactionReceipt.
+ * - Tron: delegates to pollTronTransactionWithBackoff.
+ */
+export declare function waitForTransactionCrossChain(params: WaitForTransactionCrossChainParams): Promise<CrossChainWaitResult>;
+/**
+ * Create a cross-chain friendly error message for UI.
+ *
+ * - EVM: use EVM selector-based parsing.
+ * - Tron: try to extract contractResult/receipt info if present, otherwise fallback to message.
+ */
+export declare function createCrossChainFriendlyErrorMessage(chainType: ChainType, error: unknown, defaultMessage?: string): string;
+//# sourceMappingURL=cross-chain.d.ts.map

package/dist/cross-chain.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"cross-chain.d.ts","sourceRoot":"","sources":["../src/cross-chain.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,2BAA2B,CAAC;AAG3D,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,SAAS,CAAC;AAEvC;;;GAGG;AACH,MAAM,WAAW,oBAAoB;IACnC,IAAI,EAAE,MAAM,CAAC;IACb,MAAM,EAAE,SAAS,GAAG,QAAQ,CAAC;IAC7B,UAAU,EAAE,OAAO,CAAC;CACrB;AAED;;GAEG;AACH,MAAM,WAAW,aAAa;IAC5B,SAAS,EAAE,KAAK,CAAC;IACjB,IAAI,EAAE,MAAM,CAAC;IACb,MAAM,EAAE;QACN,yBAAyB,EAAE,CAAC,IAAI,EAAE;YAChC,IAAI,EAAE,KAAK,MAAM,EAAE,CAAC;YACpB,OAAO,CAAC,EAAE,MAAM,CAAC;YACjB,aAAa,CAAC,EAAE,MAAM,CAAC;SACxB,KAAK,OAAO,CAAC;YACZ,eAAe,EAAE,KAAK,MAAM,EAAE,CAAC;YAC/B,MAAM,EAAE,SAAS,GAAG,UAAU,GAAG,SAAS,CAAC;YAC3C,WAAW,CAAC,EAAE,MAAM,CAAC;YACrB,SAAS,CAAC,EAAE,KAAK,MAAM,EAAE,CAAC;YAC1B,OAAO,CAAC,EAAE,MAAM,CAAC;YACjB,iBAAiB,CAAC,EAAE,MAAM,CAAC;SAC5B,CAAC,CAAC;KACJ,CAAC;IACF,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,aAAa,CAAC,EAAE,MAAM,CAAC;CACxB;AAED;;GAEG;AACH,MAAM,WAAW,cAAc;IAC7B,SAAS,EAAE,MAAM,CAAC;IAClB,IAAI,EAAE,MAAM,CAAC;IACb,OAAO,EAAE,OAAO,CAAC;IACjB,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB;AAED,MAAM,MAAM,kCAAkC,GAAG,aAAa,GAAG,cAAc,CAAC;AAEhF;;;;;;GAMG;AACH,wBAAsB,4BAA4B,CAChD,MAAM,EAAE,kCAAkC,GACzC,OAAO,CAAC,oBAAoB,CAAC,CA4B/B;AAED;;;;;GAKG;AACH,wBAAgB,oCAAoC,CAClD,SAAS,EAAE,SAAS,EACpB,KAAK,EAAE,OAAO,EACd,cAAc,GAAE,MAA2B,GAC1C,MAAM,CAmBR"}

package/dist/cross-chain.js

@@ -0,0 +1,56 @@
+import { createFriendlyErrorMessage as createEvmFriendlyErrorMessage } from './evm-error';
+import { pollTronTransactionWithBackoff } from './tron';
+/**
+ * Implementation layer: default cross-chain transaction polling helper
+ * that implements the interface defined by WaitForTransactionCrossChainParams.
+ *
+ * - EVM: delegates to viem-compatible waitForTransactionReceipt.
+ * - Tron: delegates to pollTronTransactionWithBackoff.
+ */
+export async function waitForTransactionCrossChain(params) {
+    if (params.chainType === 'evm') {
+        const { client, hash, timeoutMs, confirmations } = params;
+        const receipt = await client.waitForTransactionReceipt({
+            hash: hash,
+            timeout: timeoutMs,
+            confirmations,
+        });
+        return {
+            hash: receipt.transactionHash,
+            status: receipt.status === 'success' ? 'success' : 'failed',
+            rawReceipt: receipt,
+        };
+    }
+    const { tronWeb, hash, timeoutMs } = params;
+    const receipt = await pollTronTransactionWithBackoff(tronWeb, hash, {
+        timeout: timeoutMs,
+    });
+    const status = receipt?.receipt?.result === 'SUCCESS' && receipt.blockNumber ? 'success' : 'failed';
+    return {
+        hash,
+        status,
+        rawReceipt: receipt,
+    };
+}
+/**
+ * Create a cross-chain friendly error message for UI.
+ *
+ * - EVM: use EVM selector-based parsing.
+ * - Tron: try to extract contractResult/receipt info if present, otherwise fallback to message.
+ */
+export function createCrossChainFriendlyErrorMessage(chainType, error, defaultMessage = 'Operation failed') {
+    if (chainType === 'evm') {
+        return createEvmFriendlyErrorMessage(error, defaultMessage);
+    }
+    const err = error;
+    // Try to use Tron-style receipt/contractResult information when available
+    if (err && err.receipt && Array.isArray(err.contractResult)) {
+        const contractRet = err.receipt;
+        const base = contractRet.result ? String(contractRet.result) : defaultMessage;
+        return `${base}`;
+    }
+    if (err && typeof err.message === 'string') {
+        return err.message;
+    }
+    return defaultMessage;
+}

package/dist/eip712-signature.d.ts

@@ -0,0 +1,9 @@
+/**
+ * Sign a digest (bytes32)
+ *
+ * @param digest 0x-prefixed bytes32
+ * @param privateKey 0x-prefixed private key
+ * @returns 65-byte signature hex (r + s + v)
+ */
+export declare function signDigest(digest: string, privateKey: string): Promise<`0x${string}`>;
+//# sourceMappingURL=eip712-signature.d.ts.map

package/dist/eip712-signature.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"eip712-signature.d.ts","sourceRoot":"","sources":["../src/eip712-signature.ts"],"names":[],"mappings":"AAGA;;;;;;GAMG;AACH,wBAAsB,UAAU,CAAC,MAAM,EAAE,MAAM,EAAE,UAAU,EAAE,MAAM,GAAG,OAAO,CAAC,KAAK,MAAM,EAAE,CAAC,CAc3F"}

package/dist/eip712-signature.js

@@ -0,0 +1,22 @@
+import { sign } from 'viem/accounts';
+import { bytesToHex, concatHex } from 'viem';
+/**
+ * Sign a digest (bytes32)
+ *
+ * @param digest 0x-prefixed bytes32
+ * @param privateKey 0x-prefixed private key
+ * @returns 65-byte signature hex (r + s + v)
+ */
+export async function signDigest(digest, privateKey) {
+    const digestHex = digest.startsWith('0x') ? digest : `0x${digest}`;
+    const pk = privateKey.startsWith('0x') ? privateKey : `0x${privateKey}`;
+    const signature = await sign({
+        hash: digestHex,
+        privateKey: pk,
+    });
+    let v = Number(signature.v ?? 0);
+    if (v < 27) {
+        v = v + 27;
+    }
+    return concatHex([signature.r, signature.s, bytesToHex(Uint8Array.of(v))]);
+}

package/dist/evm-error.d.ts

@@ -0,0 +1,14 @@
+/**
+ * Parse error information from ethers error
+ * @param error ethers error object
+ * @returns Parsed error message
+ */
+export declare function parseEvmError(error: any): string;
+/**
+ * Create a friendly error message
+ * @param error Original error
+ * @param defaultMessage Default error message
+ * @returns Friendly error message
+ */
+export declare function createFriendlyErrorMessage(error: any, defaultMessage?: string): string;
+//# sourceMappingURL=evm-error.d.ts.map

package/dist/evm-error.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"evm-error.d.ts","sourceRoot":"","sources":["../src/evm-error.ts"],"names":[],"mappings":"AAoBA;;;;GAIG;AACH,wBAAgB,aAAa,CAAC,KAAK,EAAE,GAAG,GAAG,MAAM,CAwDhD;AAED;;;;;GAKG;AACH,wBAAgB,0BAA0B,CACxC,KAAK,EAAE,GAAG,EACV,cAAc,GAAE,MAA2B,GAC1C,MAAM,CAUR"}

package/dist/evm-error.js

@@ -0,0 +1,92 @@
+/**
+ * EVM Contract Error Selector Mapping
+ * Error selector = first 4 bytes of keccak256("ErrorName()")
+ */
+const ERROR_SELECTORS = {
+    '0x7db491eb': 'InvalidInputLength - Input length mismatch (array length inconsistent or empty)',
+    '0x9c358fad': 'FundTransferFailed - Transfer failed (insufficient balance or allowance)',
+    '0xf4d678b8': 'InsufficientBalance - Insufficient balance',
+    '0x599989d2': 'InsufficientMerchantBalance - Insufficient merchant balance (cannot pay fee)',
+    '0x4b692736': 'InvalidEd25519PublicKey - Invalid Ed25519 public key',
+    '0x3a81d6fc': 'AlreadyRegistered - Already registered',
+    '0x8baa579f': 'InvalidSignature - Signature verification failed',
+    '0x56d69198': 'InvalidFeeRate - Invalid fee rate',
+    '0x2c5211c6': 'InvalidAmount - Invalid amount',
+    '0xe6f2de87': 'InvalidStableCoin - Not a stablecoin',
+    '0x9c8d2cd2': 'InvalidRecipient - Invalid recipient address',
+    '0xb89fe006': 'InvalidWhitelist - Not in whitelist',
+    '0xc0b6c919': 'InvalidMerchant - Invalid merchant address',
+};
+/**
+ * Parse error information from ethers error
+ * @param error ethers error object
+ * @returns Parsed error message
+ */
+export function parseEvmError(error) {
+    if (!error) {
+        return 'Unknown error';
+    }
+    // Try to extract error selector from error.data
+    let errorSelector = null;
+    // ethers v6 error format: error.data may be a string
+    if (error.data) {
+        if (typeof error.data === 'string') {
+            errorSelector = error.data;
+        }
+        else if (error.data.error?.data) {
+            // In some cases error data is in error.data.error.data
+            errorSelector = error.data.error.data;
+        }
+        else if (error.data.originalError?.data) {
+            // In some cases error data is in error.data.originalError.data
+            errorSelector = error.data.originalError.data;
+        }
+    }
+    // If error.data is a string, extract error selector (first 4 bytes = 10 characters)
+    if (errorSelector) {
+        // Ensure 0x prefix exists
+        let selector;
+        if (errorSelector.startsWith('0x')) {
+            // If length >= 10, take first 10 characters; otherwise use full string
+            selector = errorSelector.length >= 10 ? errorSelector.slice(0, 10) : errorSelector;
+        }
+        else {
+            // If no 0x prefix, add it and take first 8 characters
+            selector = `0x${errorSelector.slice(0, 8)}`;
+        }
+        if (ERROR_SELECTORS[selector]) {
+            return ERROR_SELECTORS[selector];
+        }
+    }
+    // Try to extract error selector from error message
+    if (error.message) {
+        // Look for pattern like "0x..." (8 hex characters)
+        const match = error.message.match(/0x[a-fA-F0-9]{8}/);
+        if (match) {
+            const selector = match[0];
+            if (ERROR_SELECTORS[selector]) {
+                return ERROR_SELECTORS[selector];
+            }
+        }
+    }
+    // If cannot parse, return original error message or default message
+    if (error.message) {
+        return error.message;
+    }
+    return 'Unknown error';
+}
+/**
+ * Create a friendly error message
+ * @param error Original error
+ * @param defaultMessage Default error message
+ * @returns Friendly error message
+ */
+export function createFriendlyErrorMessage(error, defaultMessage = 'Operation failed') {
+    const parsedError = parseEvmError(error);
+    // If parsed error differs from default message, use parsed error
+    if (parsedError !== 'Unknown error' && parsedError !== error.message) {
+        return `${defaultMessage}: ${parsedError}`;
+    }
+    // Otherwise use original error message or default message
+    return error?.message || defaultMessage;
+}

package/dist/index.d.ts

@@ -0,0 +1,7 @@
+export * from './eip712-signature';
+export * from './tron';
+export * from './tronweb-manager';
+export * from './evm-error';
+export * from './payout-order-utils';
+export * from './cross-chain';
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,cAAc,oBAAoB,CAAC;AACnC,cAAc,QAAQ,CAAC;AACvB,cAAc,mBAAmB,CAAC;AAClC,cAAc,aAAa,CAAC;AAC5B,cAAc,sBAAsB,CAAC;AACrC,cAAc,eAAe,CAAC"}

package/dist/index.js

@@ -0,0 +1,6 @@
+export * from './eip712-signature';
+export * from './tron';
+export * from './tronweb-manager';
+export * from './evm-error';
+export * from './payout-order-utils';
+export * from './cross-chain';

package/dist/payout-order-utils.d.ts

@@ -0,0 +1,34 @@
+import type { PayoutOrderType } from '@/types/merchant';
+/**
+ * Check if the chain is Tron-like
+ */
+export declare const isTronLikeChain: (chain?: string) => boolean;
+/**
+ * Check if the chain is BSC-like
+ */
+export declare const isBscLikeChain: (chain?: string) => boolean;
+/**
+ * Format order creation time
+ */
+export declare const formatPayoutOrderTime: (timestamp: string | number) => string;
+/**
+ * Chip color type (consistent with UI component library literal values)
+ */
+export type PayoutChipColor = 'default' | 'primary' | 'secondary' | 'success' | 'warning' | 'danger';
+/**
+ * Get Chip color for display based on order type
+ */
+export declare const getPayoutTypeColor: (type: string) => PayoutChipColor;
+/**
+ * Get Chip color for display based on internal status
+ */
+export declare const getPayoutStatusColor: (status: string) => PayoutChipColor;
+/**
+ * Order title mapping
+ */
+export declare const ORDER_TITLES: Record<PayoutOrderType, string>;
+/**
+ * Order type display name mapping
+ */
+export declare const TYPE_DISPLAY_NAMES: Record<PayoutOrderType, string>;
+//# sourceMappingURL=payout-order-utils.d.ts.map

package/dist/payout-order-utils.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"payout-order-utils.d.ts","sourceRoot":"","sources":["../src/payout-order-utils.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,kBAAkB,CAAC;AAcxD;;GAEG;AACH,eAAO,MAAM,eAAe,WATjB,MAAM,KAAG,OASoD,CAAC;AAEzE;;GAEG;AACH,eAAO,MAAM,cAAc,WAdhB,MAAM,KAAG,OAc2C,CAAC;AAMhE;;GAEG;AACH,eAAO,MAAM,qBAAqB,GAAI,WAAW,MAAM,GAAG,MAAM,WAE/D,CAAC;AAEF;;GAEG;AACH,MAAM,MAAM,eAAe,GACvB,SAAS,GACT,SAAS,GACT,WAAW,GACX,SAAS,GACT,SAAS,GACT,QAAQ,CAAC;AAEb;;GAEG;AACH,eAAO,MAAM,kBAAkB,GAAI,MAAM,MAAM,KAAG,eA8BjD,CAAC;AAEF;;GAEG;AACH,eAAO,MAAM,oBAAoB,GAAI,QAAQ,MAAM,KAAG,eAWrD,CAAC;AAMF;;GAEG;AACH,eAAO,MAAM,YAAY,EAAE,MAAM,CAAC,eAAe,EAAE,MAAM,CAIxD,CAAC;AAEF;;GAEG;AACH,eAAO,MAAM,kBAAkB,EAAE,MAAM,CAAC,eAAe,EAAE,MAAM,CAI9D,CAAC"}

package/dist/payout-order-utils.js

@@ -0,0 +1,98 @@
+// ------------------------------
+// Chain helpers
+// ------------------------------
+const createChainPrefixChecker = (prefixes) => (chain) => {
+    if (!chain)
+        return false;
+    const lower = chain.toLowerCase();
+    return prefixes.some((p) => lower.startsWith(p));
+};
+/**
+ * Check if the chain is Tron-like
+ */
+export const isTronLikeChain = createChainPrefixChecker(['tron', 'trx']);
+/**
+ * Check if the chain is BSC-like
+ */
+export const isBscLikeChain = createChainPrefixChecker(['bsc']);
+// ------------------------------
+// Payout Order formatting and display utility functions
+// ------------------------------
+/**
+ * Format order creation time
+ */
+export const formatPayoutOrderTime = (timestamp) => {
+    return new Date(timestamp).toLocaleString();
+};
+/**
+ * Get Chip color for display based on order type
+ */
+export const getPayoutTypeColor = (type) => {
+    const map = {
+        payout: 'primary',
+        collection: 'secondary',
+        recharge: 'danger',
+        confirmed: 'success',
+        pending: 'warning',
+    };
+    if (type in map) {
+        return map[type];
+    }
+    else {
+        const lowerType = type.toLowerCase();
+        if (lowerType.includes('danger') ||
+            lowerType.includes('error') ||
+            lowerType.includes('failed')) {
+            return 'danger';
+        }
+        else if (lowerType.includes('warning')) {
+            return 'warning';
+        }
+        else if (lowerType.includes('success')) {
+            return 'success';
+        }
+        else if (lowerType.includes('primary')) {
+            return 'primary';
+        }
+        else if (lowerType.includes('secondary')) {
+            return 'secondary';
+        }
+        else {
+            return 'primary';
+        }
+    }
+};
+/**
+ * Get Chip color for display based on internal status
+ */
+export const getPayoutStatusColor = (status) => {
+    const map = {
+        success: 'success',
+        failed: 'danger',
+        processing: 'warning',
+        pending: 'warning',
+        confirmed: 'success',
+        rejected: 'danger',
+        urgent: 'danger',
+    };
+    return map[status] ?? 'default';
+};
+// ------------------------------
+// Payout Order constants definition
+// ------------------------------
+/**
+ * Order title mapping
+ */
+export const ORDER_TITLES = {
+    payout: 'Payout Order',
+    collection: 'Collection Order',
+    recharge: 'Recharge Order',
+};
+/**
+ * Order type display name mapping
+ */
+export const TYPE_DISPLAY_NAMES = {
+    payout: 'Regular',
+    collection: 'Collection',
+    recharge: 'Recharge',
+};

package/dist/tron.d.ts

@@ -0,0 +1,50 @@
+/**
+ * Tron transaction receipt interface
+ */
+export interface TronTransactionReceipt {
+    receipt?: {
+        result?: string;
+        energy_usage_total?: number;
+        net_usage?: number;
+        [key: string]: any;
+    };
+    contractResult?: string[];
+    log?: any[];
+    [key: string]: any;
+}
+/**
+ * Configuration options for polling Tron transaction status
+ */
+export interface PollTransactionOptions {
+    /** Maximum retry count, default 40 */
+    maxRetries?: number;
+    /** Retry delay (milliseconds), default 4000 */
+    retryDelay?: number;
+    /** Whether to throw an error on transaction failure, default true */
+    throwOnFailure?: boolean;
+    /** Custom timeout error message */
+    timeoutMessage?: string;
+    /** Custom failure error message */
+    failureMessage?: (txHash: string) => string;
+}
+/**
+ * Poll Tron transaction status, wait for transaction confirmation
+ * @param tronWeb TronWeb instance
+ * @param txHash Transaction hash
+ * @param options Poll configuration options
+ * @returns Transaction receipt
+ * @throws If transaction times out or fails (according to configuration)
+ */
+export declare function pollTronTransaction(tronWeb: any, txHash: string, options?: PollTransactionOptions): Promise<TronTransactionReceipt>;
+export declare function pollTronTransaction2(tronWeb: any, txHash: string, options?: PollTransactionOptions): Promise<TronTransactionReceipt>;
+export declare function pollTronTransactionWithBackoff(tronWeb: any, txHash: string, options?: {
+    baseDelay?: number;
+    maxDelay?: number;
+    timeout?: number;
+    signal?: AbortSignal;
+    /** Custom timeout error message */
+    timeoutMessage?: string;
+    /** Custom failure error message */
+    failureMessage?: (txHash: string) => string;
+}): Promise<any>;
+//# sourceMappingURL=tron.d.ts.map

package/dist/tron.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"tron.d.ts","sourceRoot":"","sources":["../src/tron.ts"],"names":[],"mappings":"AAkDA;;GAEG;AACH,MAAM,WAAW,sBAAsB;IACrC,OAAO,CAAC,EAAE;QACR,MAAM,CAAC,EAAE,MAAM,CAAC;QAChB,kBAAkB,CAAC,EAAE,MAAM,CAAC;QAC5B,SAAS,CAAC,EAAE,MAAM,CAAC;QACnB,CAAC,GAAG,EAAE,MAAM,GAAG,GAAG,CAAC;KACpB,CAAC;IACF,cAAc,CAAC,EAAE,MAAM,EAAE,CAAC;IAC1B,GAAG,CAAC,EAAE,GAAG,EAAE,CAAC;IACZ,CAAC,GAAG,EAAE,MAAM,GAAG,GAAG,CAAC;CACpB;AAED;;GAEG;AACH,MAAM,WAAW,sBAAsB;IACrC,sCAAsC;IACtC,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,+CAA+C;IAC/C,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,qEAAqE;IACrE,cAAc,CAAC,EAAE,OAAO,CAAC;IACzB,mCAAmC;IACnC,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB,mCAAmC;IACnC,cAAc,CAAC,EAAE,CAAC,MAAM,EAAE,MAAM,KAAK,MAAM,CAAC;CAC7C;AAED;;;;;;;GAOG;AACH,wBAAsB,mBAAmB,CACvC,OAAO,EAAE,GAAG,EACZ,MAAM,EAAE,MAAM,EACd,OAAO,GAAE,sBAA2B,GACnC,OAAO,CAAC,sBAAsB,CAAC,CAkFjC;AAED,wBAAsB,oBAAoB,CACxC,OAAO,EAAE,GAAG,EACZ,MAAM,EAAE,MAAM,EACd,OAAO,GAAE,sBAA2B,GACnC,OAAO,CAAC,sBAAsB,CAAC,CA0HjC;AAED,wBAAsB,8BAA8B,CAClD,OAAO,EAAE,GAAG,EACZ,MAAM,EAAE,MAAM,EACd,OAAO,GAAE;IACP,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,MAAM,CAAC,EAAE,WAAW,CAAC;IACrB,mCAAmC;IACnC,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB,mCAAmC;IACnC,cAAc,CAAC,EAAE,CAAC,MAAM,EAAE,MAAM,KAAK,MAAM,CAAC;CACxC,gBAmDP"}

package/dist/tron.js

@@ -0,0 +1,255 @@
+/**
+ * Contract error selector mapping
+ * Error selector = first 4 bytes of keccak256("ErrorName()")
+ */
+const ERROR_SELECTORS = {
+    '0x7db491eb': 'InvalidInputLength - Input length mismatch (array length mismatch or empty)',
+    '0x9c358fad': 'FundTransferFailed - Transfer failed (insufficient balance or insufficient authorization)',
+    '0xf4d678b8': 'InsufficientBalance - Insufficient balance',
+    '0x599989d2': 'InsufficientMerchantBalance - Insufficient merchant balance (cannot pay fee)',
+    '0x4b692736': 'InvalidEd25519PublicKey - Invalid Ed25519 public key',
+    '0x3a81d6fc': 'AlreadyRegistered - Already registered',
+    '0x8baa579f': 'InvalidSignature - Signature verification failed',
+    '0x56d69198': 'InvalidFeeRate - Invalid fee rate',
+    '0x2c5211c6': 'InvalidAmount - Invalid amount',
+    '0xe6f2de87': 'InvalidStableCoin - Not a stablecoin',
+    '0x9c8d2cd2': 'InvalidRecipient - Invalid recipient address',
+    '0xb89fe006': 'InvalidWhitelist - Not in whitelist',
+    '0xc0b6c919': 'InvalidMerchant - Invalid merchant address',
+};
+/**
+ * Parse error information from contract result
+ * @param contractResult The result array returned by the contract
+ * @returns Parsed error information
+ */
+function parseContractError(contractResult) {
+    if (!contractResult || contractResult.length === 0) {
+        return 'Unknown error';
+    }
+    // Contract errors typically return an error selector (4 bytes, 8 hex characters)
+    const errorSelector = Array.isArray(contractResult) ? contractResult[0] : contractResult;
+    if (typeof errorSelector === 'string') {
+        // Ensure 0x prefix exists
+        const selector = errorSelector.startsWith('0x') ? errorSelector : `0x${errorSelector}`;
+        // Check if it's a known error selector
+        if (ERROR_SELECTORS[selector]) {
+            return ERROR_SELECTORS[selector];
+        }
+        // If not a known error, return the raw selector
+        return `Unknown error: ${selector}`;
+    }
+    return 'Unable to parse error information';
+}
+/**
+ * Poll Tron transaction status, wait for transaction confirmation
+ * @param tronWeb TronWeb instance
+ * @param txHash Transaction hash
+ * @param options Poll configuration options
+ * @returns Transaction receipt
+ * @throws If transaction times out or fails (according to configuration)
+ */
+export async function pollTronTransaction(tronWeb, txHash, options = {}) {
+    if (!txHash) {
+        throw new Error('Transaction hash is empty, cannot confirm transaction status');
+    }
+    const { maxRetries = 50, retryDelay = 3000, throwOnFailure = true, timeoutMessage = 'Transaction confirmation timed out, please check transaction status', failureMessage = (hash) => `Transaction failed, transaction hash: ${hash}`, } = options;
+    let transactionReceipt = null;
+    let retryCount = 0;
+    while (retryCount < maxRetries) {
+        await new Promise((resolve) => setTimeout(resolve, retryDelay));
+        try {
+            const txInfo = await tronWeb.trx.getTransactionInfo(txHash);
+            if (txInfo?.blockNumber) {
+                transactionReceipt = txInfo;
+                break;
+            }
+        }
+        catch {
+            // Silently continue retry on error
+        }
+        retryCount++;
+    }
+    if (!transactionReceipt?.blockNumber) {
+        throw new Error(timeoutMessage);
+    }
+    const contractRet = transactionReceipt?.receipt;
+    const isSuccess = Boolean(contractRet && transactionReceipt?.blockNumber);
+    if (throwOnFailure && !isSuccess) {
+        let errorDetails = '';
+        let parsedError = '';
+        try {
+            if (contractRet) {
+                errorDetails = `Transaction status: ${contractRet}`;
+            }
+            // Check if there is contract error information
+            if (transactionReceipt?.contractResult && Array.isArray(transactionReceipt.contractResult)) {
+                const contractResult = transactionReceipt.contractResult;
+                errorDetails += `\nContract result: ${JSON.stringify(contractResult)}`;
+                // Try to parse error selector
+                parsedError = parseContractError(contractResult);
+            }
+            // Check if there is log (may contain error information)
+            if (transactionReceipt?.log && transactionReceipt.log.length > 0) {
+                errorDetails += `\nLog: ${JSON.stringify(transactionReceipt.log)}`;
+            }
+            // Add resource usage information
+            if (transactionReceipt?.receipt?.energy_usage_total) {
+                errorDetails += `\nEnergy usage: ${transactionReceipt.receipt.energy_usage_total}`;
+            }
+            if (transactionReceipt?.receipt?.net_usage) {
+                errorDetails += `\nBandwidth usage: ${transactionReceipt.receipt.net_usage}`;
+            }
+        }
+        catch {
+            // Silently ignore error extraction failure
+        }
+        // Build error message, prioritize parsed error information
+        let errorMsg = failureMessage(txHash);
+        if (parsedError) {
+            errorMsg += `\nError reason: ${parsedError}`;
+        }
+        if (errorDetails) {
+            errorMsg += `\n${errorDetails}`;
+        }
+        throw new Error(errorMsg);
+    }
+    return transactionReceipt || {};
+}
+export async function pollTronTransaction2(tronWeb, txHash, options = {}) {
+    if (!txHash) {
+        throw new Error('Transaction hash is empty, cannot confirm transaction status');
+    }
+    const { maxRetries = 50, retryDelay = 3000, throwOnFailure = true, timeoutMessage = 'Transaction confirmation timed out, please check transaction status', failureMessage = (hash) => `Transaction failed, transaction hash: ${hash}`, } = options;
+    let transactionReceipt = null;
+    let retryCount = 0;
+    // Helper function to add timeout to getTransactionInfo call
+    // Returns a promise that resolves/rejects with cleanup to prevent memory leaks
+    const getTransactionInfoWithTimeout = async (timeoutMs = 10000) => {
+        let timeoutId = null;
+        const timeoutPromise = new Promise((_, reject) => {
+            timeoutId = setTimeout(() => {
+                timeoutId = null;
+                reject(new Error(`getTransactionInfo timeout after ${timeoutMs}ms`));
+            }, timeoutMs);
+        });
+        const infoPromise = tronWeb.trx
+            .getTransactionInfo(txHash)
+            .then((result) => {
+            // Clear timeout if infoPromise resolves first
+            if (timeoutId) {
+                clearTimeout(timeoutId);
+                timeoutId = null;
+            }
+            return result;
+        })
+            .catch((error) => {
+            // Clear timeout if infoPromise rejects
+            if (timeoutId) {
+                clearTimeout(timeoutId);
+                timeoutId = null;
+            }
+            throw error;
+        });
+        return Promise.race([infoPromise, timeoutPromise]).finally(() => {
+            // Ensure cleanup in case of any edge cases
+            if (timeoutId) {
+                clearTimeout(timeoutId);
+                timeoutId = null;
+            }
+        });
+    };
+    while (retryCount < maxRetries) {
+        await new Promise((resolve) => setTimeout(resolve, retryDelay));
+        try {
+            const txInfo = await getTransactionInfoWithTimeout(10000);
+            if (txInfo?.blockNumber) {
+                transactionReceipt = txInfo;
+                break;
+            }
+        }
+        catch {
+            // Continue retry on error
+        }
+        retryCount++;
+    }
+    if (!transactionReceipt?.blockNumber) {
+        throw new Error(timeoutMessage);
+    }
+    const contractRet = transactionReceipt?.receipt;
+    const isSuccess = Boolean(contractRet && transactionReceipt?.blockNumber);
+    if (throwOnFailure && !isSuccess) {
+        let errorDetails = '';
+        let parsedError = '';
+        try {
+            if (contractRet) {
+                errorDetails = `Transaction status: ${contractRet}`;
+            }
+            // Check if there is contract error information
+            if (transactionReceipt?.contractResult && Array.isArray(transactionReceipt.contractResult)) {
+                const contractResult = transactionReceipt.contractResult;
+                errorDetails += `\nContract result: ${JSON.stringify(contractResult)}`;
+                // Try to parse error selector
+                parsedError = parseContractError(contractResult);
+            }
+            // Check if there is log (may contain error information)
+            if (transactionReceipt?.log && transactionReceipt.log.length > 0) {
+                errorDetails += `\nLog: ${JSON.stringify(transactionReceipt.log)}`;
+            }
+            // Add resource usage information
+            if (transactionReceipt?.receipt?.energy_usage_total) {
+                errorDetails += `\nEnergy usage: ${transactionReceipt.receipt.energy_usage_total}`;
+            }
+            if (transactionReceipt?.receipt?.net_usage) {
+                errorDetails += `\nBandwidth usage: ${transactionReceipt.receipt.net_usage}`;
+            }
+        }
+        catch {
+            // Silently ignore error extraction failure
+        }
+        // Build error message, prioritize parsed error information
+        let errorMsg = failureMessage(txHash);
+        if (parsedError) {
+            errorMsg += `\nError reason: ${parsedError}`;
+        }
+        if (errorDetails) {
+            errorMsg += `\n${errorDetails}`;
+        }
+        throw new Error(errorMsg);
+    }
+    return transactionReceipt || {};
+}
+export async function pollTronTransactionWithBackoff(tronWeb, txHash, options = {}) {
+    const { baseDelay = 3000, // final stable 3s
+    maxDelay = 10000, // initial 10s
+    timeout = 150000, signal, timeoutMessage = 'Transaction confirmation timed out, please check transaction status', failureMessage = (hash) => `Transaction failed, transaction hash: ${hash}`, } = options;
+    const STEP = 2000; // decrease by 2s each step
+    let attempt = 0;
+    const start = Date.now();
+    const sleep = (ms) => new Promise((resolve, reject) => {
+        const id = setTimeout(resolve, ms);
+        signal?.addEventListener('abort', () => {
+            clearTimeout(id);
+            reject(new Error('Polling aborted'));
+        });
+    });
+    while (true) {
+        if (signal?.aborted) {
+            throw new Error('Polling aborted');
+        }
+        if (Date.now() - start > timeout) {
+            throw new Error(timeoutMessage);
+        }
+        const info = await tronWeb.trx.getTransactionInfo(txHash);
+        if (info?.blockNumber) {
+            if (info.receipt) {
+                return info;
+            }
+            // explicit failure (REVERT / OUT_OF_ENERGY / etc)
+            throw new Error(failureMessage(txHash));
+        }
+        // convergent backoff (e.g. 10 → 8 → 6 → 4 → 3)
+        const delay = Math.max(maxDelay - attempt * STEP, baseDelay);
+        attempt++;
+        await sleep(delay);
+    }
+}

package/dist/tronweb-manager.d.ts

@@ -0,0 +1,16 @@
+import { TronWeb } from 'tronweb';
+import type { ChainConfig } from '@/types/merchant';
+export interface CreateTronWebOptions {
+    privateKey?: string;
+    defaultAddress?: string;
+    fullHostOverride?: string;
+    headers?: Record<string, string>;
+}
+/**
+ * Create a standalone TronWeb instance.
+ * @param chainConfig - Chain config
+ * @param options - Options (privateKey, headers, etc.)
+ * @returns TronWeb instance
+ */
+export declare function createTronWebInstance(chainConfig: ChainConfig, options?: CreateTronWebOptions): TronWeb;
+//# sourceMappingURL=tronweb-manager.d.ts.map

package/dist/tronweb-manager.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"tronweb-manager.d.ts","sourceRoot":"","sources":["../src/tronweb-manager.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,OAAO,EAAE,MAAM,SAAS,CAAC;AAClC,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,kBAAkB,CAAC;AAEpD,MAAM,WAAW,oBAAoB;IACnC,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB,gBAAgB,CAAC,EAAE,MAAM,CAAC;IAC1B,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;CAClC;AAED;;;;;GAKG;AACH,wBAAgB,qBAAqB,CACnC,WAAW,EAAE,WAAW,EACxB,OAAO,GAAE,oBAAyB,GACjC,OAAO,CA0CT"}

package/dist/tronweb-manager.js

@@ -0,0 +1,44 @@
+import { TronWeb } from 'tronweb';
+/**
+ * Create a standalone TronWeb instance.
+ * @param chainConfig - Chain config
+ * @param options - Options (privateKey, headers, etc.)
+ * @returns TronWeb instance
+ */
+export function createTronWebInstance(chainConfig, options = {}) {
+    // 1. Normalize host URL (strip trailing slash and /jsonrpc)
+    let fullHost = options.fullHostOverride ?? chainConfig.rest_url;
+    if (typeof fullHost === 'string') {
+        fullHost = fullHost.replace(/\/+$/, '').replace(/\/jsonrpc$/i, '');
+    }
+    // 2. Create instance
+    const tronWeb = new TronWeb({
+        fullHost,
+        headers: options.headers,
+    });
+    // 3. Set private key (TronWeb will derive address from it)
+    if (options.privateKey) {
+        try {
+            tronWeb.setPrivateKey(options.privateKey);
+        }
+        catch (error) {
+            console.error('[TronWeb] Invalid private key format:', error);
+        }
+    }
+    // 4. Set default address: options.defaultAddress > (if no key) payout_contract
+    const targetAddress = options.defaultAddress
+        ? options.defaultAddress
+        : !options.privateKey
+            ? chainConfig.payout_contract
+            : undefined;
+    if (targetAddress && TronWeb.isAddress(targetAddress)) {
+        try {
+            // TronWeb may throw if address does not match private key
+            tronWeb.setAddress(targetAddress);
+        }
+        catch {
+            console.warn('[TronWeb] Could not set default address (may not match private key or invalid format):', targetAddress);
+        }
+    }
+    return tronWeb;
+}

package/dist/types/merchant.d.ts

@@ -0,0 +1,14 @@
+/**
+ * Local types for merchant-utils (used when @/types/merchant is not provided by app)
+ */
+export type PayoutOrderType = 'payout' | 'collection' | 'recharge';
+export interface ChainConfig {
+    name?: string;
+    chain?: string;
+    rpc_url?: string;
+    rest_url?: string;
+    payout_contract?: string;
+    scan_url?: string;
+    [key: string]: unknown;
+}
+//# sourceMappingURL=merchant.d.ts.map

package/dist/types/merchant.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"merchant.d.ts","sourceRoot":"","sources":["../../src/types/merchant.ts"],"names":[],"mappings":"AAAA;;GAEG;AACH,MAAM,MAAM,eAAe,GAAG,QAAQ,GAAG,YAAY,GAAG,UAAU,CAAC;AAEnE,MAAM,WAAW,WAAW;IAC1B,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,eAAe,CAAC,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC;CACxB"}

package/dist/types/merchant.js

@@ -0,0 +1 @@
+export {};

package/package.json

@@ -0,0 +1,54 @@
+{
+  "name": "@magnaflow/merchant-utils",
+  "version": "1.0.1",
+  "description": "Merchant shared utilities",
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js",
+      "default": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist",
+    "README.md"
+  ],
+  "scripts": {
+    "build": "tsc",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "test:coverage": "vitest run --coverage",
+    "dev": "tsc --watch",
+    "clean": "rm -rf dist",
+    "prepublishOnly": "node ../../scripts/verify-package-dist.cjs"
+  },
+  "keywords": [
+    "merchant",
+    "utils",
+    "tron",
+    "evm"
+  ],
+  "author": "",
+  "license": "MIT",
+  "publishConfig": {
+    "access": "public"
+  },
+  "dependencies": {
+    "@magnaflow/chain-provider": "workspace:*",
+    "tronweb": "^6.1.0",
+    "viem": "^2.39.2"
+  },
+  "devDependencies": {
+    "typescript": "~5.9.3",
+    "vitest": "^2.1.9",
+    "@vitest/coverage-v8": "^2.1.9"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/magnaflowlabs/merchant-v2-sdk.git",
+    "directory": "packages/merchant-utils"
+  }
+}