@provex/utils 1.0.16 → 1.2.4

package/dist/chain.d.ts

@@ -0,0 +1,446 @@
+/**
+ * @fileoverview Chain configuration and utilities for supported blockchain networks.
+ *
+ * This module defines the supported chains (Base, Pulsechain) and provides utilities
+ * for chain identification, name resolution, and block explorer URL generation.
+ *
+ * @remarks
+ * - Base (chainId: 8453) is the primary network for the V3 escrow contracts
+ * - Pulsechain (chainId: 369) supports both V2 and V3 contracts
+ *
+ * @see {@link contracts} for contract addresses per chain
+ */
+import { type Chain } from 'viem/chains';
+/**
+ * Supported blockchain networks for the Provex protocol.
+ * Both chains remain in the type system; UI visibility is controlled
+ * by SUPPORTED_CHAIN_IDS in ChainFilterContext.
+ */
+export declare const chains: readonly [{
+    blockExplorers: {
+        readonly default: {
+            readonly name: "PulseScan";
+            readonly url: "https://ipfs.scan.pulsechain.com";
+            readonly apiUrl: "https://api.scan.pulsechain.com/api";
+        };
+    };
+    blockTime: 10000;
+    contracts: {
+        readonly ensRegistry: {
+            readonly address: "0x00000000000C2E074eC69A0dFb2997BA6C7d2e1e";
+        };
+        readonly multicall3: {
+            readonly address: "0xca11bde05977b3631167028862be2a173976ca11";
+            readonly blockCreated: 14353601;
+        };
+    };
+    ensTlds?: readonly string[] | undefined;
+    id: 369;
+    name: "PulseChain";
+    nativeCurrency: {
+        readonly name: "Pulse";
+        readonly symbol: "PLS";
+        readonly decimals: 18;
+    };
+    experimental_preconfirmationTime?: number | undefined | undefined;
+    rpcUrls: {
+        readonly default: {
+            readonly http: readonly ["https://rpc.pulsechain.com"];
+            readonly webSocket: readonly ["wss://ws.pulsechain.com"];
+        };
+    };
+    sourceId?: number | undefined | undefined;
+    testnet: false;
+    custom?: Record<string, unknown> | undefined;
+    fees?: import("viem").ChainFees<undefined> | undefined;
+    formatters?: undefined;
+    serializers?: import("viem").ChainSerializers<undefined, import("viem").TransactionSerializable> | undefined;
+}, {
+    blockExplorers: {
+        readonly default: {
+            readonly name: "Basescan";
+            readonly url: "https://basescan.org";
+            readonly apiUrl: "https://api.basescan.org/api";
+        };
+    };
+    blockTime: 2000;
+    contracts: {
+        readonly disputeGameFactory: {
+            readonly 1: {
+                readonly address: "0x43edB88C4B80fDD2AdFF2412A7BebF9dF42cB40e";
+            };
+        };
+        readonly l2OutputOracle: {
+            readonly 1: {
+                readonly address: "0x56315b90c40730925ec5485cf004d835058518A0";
+            };
+        };
+        readonly multicall3: {
+            readonly address: "0xca11bde05977b3631167028862be2a173976ca11";
+            readonly blockCreated: 5022;
+        };
+        readonly portal: {
+            readonly 1: {
+                readonly address: "0x49048044D57e1C92A77f79988d21Fa8fAF74E97e";
+                readonly blockCreated: 17482143;
+            };
+        };
+        readonly l1StandardBridge: {
+            readonly 1: {
+                readonly address: "0x3154Cf16ccdb4C6d922629664174b904d80F2C35";
+                readonly blockCreated: 17482143;
+            };
+        };
+        readonly gasPriceOracle: {
+            readonly address: "0x420000000000000000000000000000000000000F";
+        };
+        readonly l1Block: {
+            readonly address: "0x4200000000000000000000000000000000000015";
+        };
+        readonly l2CrossDomainMessenger: {
+            readonly address: "0x4200000000000000000000000000000000000007";
+        };
+        readonly l2Erc721Bridge: {
+            readonly address: "0x4200000000000000000000000000000000000014";
+        };
+        readonly l2StandardBridge: {
+            readonly address: "0x4200000000000000000000000000000000000010";
+        };
+        readonly l2ToL1MessagePasser: {
+            readonly address: "0x4200000000000000000000000000000000000016";
+        };
+    };
+    ensTlds?: readonly string[] | undefined;
+    id: 8453;
+    name: "Base";
+    nativeCurrency: {
+        readonly name: "Ether";
+        readonly symbol: "ETH";
+        readonly decimals: 18;
+    };
+    experimental_preconfirmationTime?: number | undefined | undefined;
+    rpcUrls: {
+        readonly default: {
+            readonly http: readonly ["https://mainnet.base.org"];
+        };
+    };
+    sourceId: 1;
+    testnet?: boolean | undefined | undefined;
+    custom?: Record<string, unknown> | undefined;
+    fees?: import("viem").ChainFees<undefined> | undefined;
+    formatters: {
+        readonly block: {
+            exclude: [] | undefined;
+            format: (args: import("viem/chains").OpStackRpcBlock, action?: string | undefined) => {
+                baseFeePerGas: bigint | null;
+                blobGasUsed: bigint;
+                difficulty: bigint;
+                excessBlobGas: bigint;
+                extraData: import("viem").Hex;
+                gasLimit: bigint;
+                gasUsed: bigint;
+                hash: `0x${string}` | null;
+                logsBloom: `0x${string}` | null;
+                miner: import("viem").Address;
+                mixHash: import("viem").Hash;
+                nonce: `0x${string}` | null;
+                number: bigint | null;
+                parentBeaconBlockRoot?: `0x${string}` | undefined;
+                parentHash: import("viem").Hash;
+                receiptsRoot: import("viem").Hex;
+                sealFields: import("viem").Hex[];
+                sha3Uncles: import("viem").Hash;
+                size: bigint;
+                stateRoot: import("viem").Hash;
+                timestamp: bigint;
+                totalDifficulty: bigint | null;
+                transactions: `0x${string}`[] | import("viem/chains").OpStackTransaction<boolean>[];
+                transactionsRoot: import("viem").Hash;
+                uncles: import("viem").Hash[];
+                withdrawals?: import("viem").Withdrawal[] | undefined | undefined;
+                withdrawalsRoot?: `0x${string}` | undefined;
+            } & {};
+            type: "block";
+        };
+        readonly transaction: {
+            exclude: [] | undefined;
+            format: (args: import("viem/chains").OpStackRpcTransaction, action?: string | undefined) => ({
+                blockHash: `0x${string}` | null;
+                blockNumber: bigint | null;
+                from: import("viem").Address;
+                gas: bigint;
+                hash: import("viem").Hash;
+                input: import("viem").Hex;
+                nonce: number;
+                r: import("viem").Hex;
+                s: import("viem").Hex;
+                to: import("viem").Address | null;
+                transactionIndex: number | null;
+                typeHex: import("viem").Hex | null;
+                v: bigint;
+                value: bigint;
+                yParity: number;
+                gasPrice?: undefined | undefined;
+                maxFeePerBlobGas?: undefined | undefined;
+                maxFeePerGas: bigint;
+                maxPriorityFeePerGas: bigint;
+                isSystemTx?: boolean;
+                mint?: bigint | undefined | undefined;
+                sourceHash: import("viem").Hex;
+                type: "deposit";
+            } | {
+                r: import("viem").Hex;
+                s: import("viem").Hex;
+                v: bigint;
+                value: bigint;
+                gas: bigint;
+                to: import("viem").Address | null;
+                from: import("viem").Address;
+                nonce: number;
+                blockHash: `0x${string}` | null;
+                blockNumber: bigint | null;
+                transactionIndex: number | null;
+                hash: import("viem").Hash;
+                input: import("viem").Hex;
+                typeHex: import("viem").Hex | null;
+                accessList?: undefined | undefined;
+                authorizationList?: undefined | undefined;
+                blobVersionedHashes?: undefined | undefined;
+                chainId?: number | undefined;
+                yParity?: undefined | undefined;
+                type: "legacy";
+                gasPrice: bigint;
+                maxFeePerBlobGas?: undefined | undefined;
+                maxFeePerGas?: undefined | undefined;
+                maxPriorityFeePerGas?: undefined | undefined;
+                isSystemTx?: undefined | undefined;
+                mint?: undefined | undefined;
+                sourceHash?: undefined | undefined;
+            } | {
+                blockHash: `0x${string}` | null;
+                blockNumber: bigint | null;
+                from: import("viem").Address;
+                gas: bigint;
+                hash: import("viem").Hash;
+                input: import("viem").Hex;
+                nonce: number;
+                r: import("viem").Hex;
+                s: import("viem").Hex;
+                to: import("viem").Address | null;
+                transactionIndex: number | null;
+                typeHex: import("viem").Hex | null;
+                v: bigint;
+                value: bigint;
+                yParity: number;
+                accessList: import("viem").AccessList;
+                authorizationList?: undefined | undefined;
+                blobVersionedHashes?: undefined | undefined;
+                chainId: number;
+                type: "eip2930";
+                gasPrice: bigint;
+                maxFeePerBlobGas?: undefined | undefined;
+                maxFeePerGas?: undefined | undefined;
+                maxPriorityFeePerGas?: undefined | undefined;
+                isSystemTx?: undefined | undefined;
+                mint?: undefined | undefined;
+                sourceHash?: undefined | undefined;
+            } | {
+                blockHash: `0x${string}` | null;
+                blockNumber: bigint | null;
+                from: import("viem").Address;
+                gas: bigint;
+                hash: import("viem").Hash;
+                input: import("viem").Hex;
+                nonce: number;
+                r: import("viem").Hex;
+                s: import("viem").Hex;
+                to: import("viem").Address | null;
+                transactionIndex: number | null;
+                typeHex: import("viem").Hex | null;
+                v: bigint;
+                value: bigint;
+                yParity: number;
+                accessList: import("viem").AccessList;
+                authorizationList?: undefined | undefined;
+                blobVersionedHashes?: undefined | undefined;
+                chainId: number;
+                type: "eip1559";
+                gasPrice?: undefined | undefined;
+                maxFeePerBlobGas?: undefined | undefined;
+                maxFeePerGas: bigint;
+                maxPriorityFeePerGas: bigint;
+                isSystemTx?: undefined | undefined;
+                mint?: undefined | undefined;
+                sourceHash?: undefined | undefined;
+            } | {
+                blockHash: `0x${string}` | null;
+                blockNumber: bigint | null;
+                from: import("viem").Address;
+                gas: bigint;
+                hash: import("viem").Hash;
+                input: import("viem").Hex;
+                nonce: number;
+                r: import("viem").Hex;
+                s: import("viem").Hex;
+                to: import("viem").Address | null;
+                transactionIndex: number | null;
+                typeHex: import("viem").Hex | null;
+                v: bigint;
+                value: bigint;
+                yParity: number;
+                accessList: import("viem").AccessList;
+                authorizationList?: undefined | undefined;
+                blobVersionedHashes: readonly import("viem").Hex[];
+                chainId: number;
+                type: "eip4844";
+                gasPrice?: undefined | undefined;
+                maxFeePerBlobGas: bigint;
+                maxFeePerGas: bigint;
+                maxPriorityFeePerGas: bigint;
+                isSystemTx?: undefined | undefined;
+                mint?: undefined | undefined;
+                sourceHash?: undefined | undefined;
+            } | {
+                blockHash: `0x${string}` | null;
+                blockNumber: bigint | null;
+                from: import("viem").Address;
+                gas: bigint;
+                hash: import("viem").Hash;
+                input: import("viem").Hex;
+                nonce: number;
+                r: import("viem").Hex;
+                s: import("viem").Hex;
+                to: import("viem").Address | null;
+                transactionIndex: number | null;
+                typeHex: import("viem").Hex | null;
+                v: bigint;
+                value: bigint;
+                yParity: number;
+                accessList: import("viem").AccessList;
+                authorizationList: import("viem").SignedAuthorizationList;
+                blobVersionedHashes?: undefined | undefined;
+                chainId: number;
+                type: "eip7702";
+                gasPrice?: undefined | undefined;
+                maxFeePerBlobGas?: undefined | undefined;
+                maxFeePerGas: bigint;
+                maxPriorityFeePerGas: bigint;
+                isSystemTx?: undefined | undefined;
+                mint?: undefined | undefined;
+                sourceHash?: undefined | undefined;
+            }) & {};
+            type: "transaction";
+        };
+        readonly transactionReceipt: {
+            exclude: [] | undefined;
+            format: (args: import("viem/chains").OpStackRpcTransactionReceipt, action?: string | undefined) => {
+                blobGasPrice?: bigint | undefined;
+                blobGasUsed?: bigint | undefined;
+                blockHash: import("viem").Hash;
+                blockNumber: bigint;
+                contractAddress: import("viem").Address | null | undefined;
+                cumulativeGasUsed: bigint;
+                effectiveGasPrice: bigint;
+                from: import("viem").Address;
+                gasUsed: bigint;
+                logs: import("viem").Log<bigint, number, false>[];
+                logsBloom: import("viem").Hex;
+                root?: `0x${string}` | undefined;
+                status: "success" | "reverted";
+                to: import("viem").Address | null;
+                transactionHash: import("viem").Hash;
+                transactionIndex: number;
+                type: import("viem").TransactionType;
+                l1GasPrice: bigint | null;
+                l1GasUsed: bigint | null;
+                l1Fee: bigint | null;
+                l1FeeScalar: number | null;
+            } & {};
+            type: "transactionReceipt";
+        };
+    };
+    serializers: {
+        readonly transaction: typeof import("viem/chains").serializeTransactionOpStack;
+    };
+}];
+/**
+ * Array of supported chain IDs derived from the chains array.
+ * Currently: [369 (Pulsechain), 8453 (Base)]
+ */
+export declare const chainIds: (369 | 8453)[];
+/**
+ * Union type of all supported chain IDs.
+ * Use this type when a function accepts a chain ID parameter.
+ *
+ * @example
+ * ```ts
+ * function getContracts(chainId: ChainId) {
+ *   // chainId is guaranteed to be 369 or 8453
+ * }
+ * ```
+ */
+export type ChainId = (typeof chainIds)[number];
+/**
+ * Human-readable chain names for URL params and display.
+ * Maps chain IDs to lowercase slug-style names for URL-safe usage.
+ *
+ * @example
+ * ```ts
+ * chainNames[8453] // 'base'
+ * chainNames[369]  // 'pulsechain'
+ * ```
+ */
+export declare const chainNames: {
+    readonly 8453: "base";
+    readonly 369: "pulsechain";
+};
+export type ChainName = (typeof chainNames)[ChainId];
+/**
+ * Reverse mapping from chain name to chain ID
+ */
+export declare const chainNameToId: Record<ChainName, ChainId>;
+/**
+ * Get chain name from chain ID for URL params
+ * @param chainId - The chain ID
+ * @returns The human-readable chain name (e.g., 'base', 'pulsechain')
+ */
+export declare function getChainName(chainId: ChainId): ChainName;
+/**
+ * Get chain ID from chain name
+ * @param name - The chain name (e.g., 'base', 'pulsechain')
+ * @returns The chain ID, or null if invalid name
+ */
+export declare function getChainIdFromName(name: string): ChainId | null;
+/**
+ * Check if a string is a valid chain name
+ * @param name - The string to check
+ * @returns True if the name is a valid chain name
+ */
+export declare function isValidChainName(name: string): name is ChainName;
+/**
+ * Get the explorer URL for a given chain, type, and hash
+ * @param chain - The chain to get the explorer URL for
+ * @param type - The type of explorer to use (tx or address)
+ * @param hash - The hash to get the explorer URL for
+ * @returns The explorer URL
+ */
+export declare function getExplorerUrl(chain: Chain, type: 'tx' | 'address', hash: string): string;
+/**
+ * Map from chain ID to viem Chain object.
+ * Provides O(1) lookup of chain configuration by ID.
+ *
+ * @example
+ * ```ts
+ * const baseChain = chainIdToChain.get(8453)
+ * // baseChain.name === 'Base'
+ * ```
+ */
+export declare const chainIdToChain: Map<369 | 8453, Chain>;
+/**
+ * Target block time in milliseconds for each supported chain.
+ * Used for estimating transaction confirmation times.
+ *
+ * - Pulsechain (369): ~10 seconds per block
+ * - Base (8453): ~2 seconds per block
+ */
+export declare const chainIdToTargetBlockTime: Map<369 | 8453, number>;

package/dist/chain.js

@@ -0,0 +1,98 @@
+/**
+ * @fileoverview Chain configuration and utilities for supported blockchain networks.
+ *
+ * This module defines the supported chains (Base, Pulsechain) and provides utilities
+ * for chain identification, name resolution, and block explorer URL generation.
+ *
+ * @remarks
+ * - Base (chainId: 8453) is the primary network for the V3 escrow contracts
+ * - Pulsechain (chainId: 369) supports both V2 and V3 contracts
+ *
+ * @see {@link contracts} for contract addresses per chain
+ */
+import { base, pulsechain } from 'viem/chains';
+/**
+ * Supported blockchain networks for the Provex protocol.
+ * Both chains remain in the type system; UI visibility is controlled
+ * by SUPPORTED_CHAIN_IDS in ChainFilterContext.
+ */
+export const chains = [pulsechain, base];
+/**
+ * Array of supported chain IDs derived from the chains array.
+ * Currently: [369 (Pulsechain), 8453 (Base)]
+ */
+export const chainIds = chains.map((chain) => chain.id);
+/**
+ * Human-readable chain names for URL params and display.
+ * Maps chain IDs to lowercase slug-style names for URL-safe usage.
+ *
+ * @example
+ * ```ts
+ * chainNames[8453] // 'base'
+ * chainNames[369]  // 'pulsechain'
+ * ```
+ */
+export const chainNames = {
+    [base.id]: 'base',
+    [pulsechain.id]: 'pulsechain',
+};
+/**
+ * Reverse mapping from chain name to chain ID
+ */
+export const chainNameToId = Object.fromEntries(Object.entries(chainNames).map(([id, name]) => [name, Number(id)]));
+/**
+ * Get chain name from chain ID for URL params
+ * @param chainId - The chain ID
+ * @returns The human-readable chain name (e.g., 'base', 'pulsechain')
+ */
+export function getChainName(chainId) {
+    return chainNames[chainId];
+}
+/**
+ * Get chain ID from chain name
+ * @param name - The chain name (e.g., 'base', 'pulsechain')
+ * @returns The chain ID, or null if invalid name
+ */
+export function getChainIdFromName(name) {
+    return chainNameToId[name] ?? null;
+}
+/**
+ * Check if a string is a valid chain name
+ * @param name - The string to check
+ * @returns True if the name is a valid chain name
+ */
+export function isValidChainName(name) {
+    return name in chainNameToId;
+}
+/**
+ * Get the explorer URL for a given chain, type, and hash
+ * @param chain - The chain to get the explorer URL for
+ * @param type - The type of explorer to use (tx or address)
+ * @param hash - The hash to get the explorer URL for
+ * @returns The explorer URL
+ */
+export function getExplorerUrl(chain, type, hash) {
+    return `${chain.blockExplorers?.default.url}/${type}/${hash}`;
+}
+/**
+ * Map from chain ID to viem Chain object.
+ * Provides O(1) lookup of chain configuration by ID.
+ *
+ * @example
+ * ```ts
+ * const baseChain = chainIdToChain.get(8453)
+ * // baseChain.name === 'Base'
+ * ```
+ */
+export const chainIdToChain = new Map(chains.map((chain) => [chain.id, chain]));
+/**
+ * Target block time in milliseconds for each supported chain.
+ * Used for estimating transaction confirmation times.
+ *
+ * - Pulsechain (369): ~10 seconds per block
+ * - Base (8453): ~2 seconds per block
+ */
+export const chainIdToTargetBlockTime = new Map([
+    [369, 10_000],
+    [8453, 2_000],
+]);

package/dist/chain.test.js

@@ -0,0 +1,112 @@
+import { describe, it } from 'node:test';
+import assert from 'node:assert/strict';
+import { base, pulsechain } from 'viem/chains';
+import { chains, chainIds, chainNames, chainNameToId, getChainName, getChainIdFromName, isValidChainName, getExplorerUrl, chainIdToChain, chainIdToTargetBlockTime, } from './chain.js';
+describe('chain', () => {
+    describe('chains', () => {
+        it('should include pulsechain and base', () => {
+            assert.ok(chains.includes(pulsechain));
+            assert.ok(chains.includes(base));
+        });
+        it('should have exactly 2 chains', () => {
+            assert.equal(chains.length, 2);
+        });
+    });
+    describe('chainIds', () => {
+        it('should include correct chain IDs', () => {
+            assert.ok(chainIds.includes(369)); // Pulsechain
+            assert.ok(chainIds.includes(8453)); // Base
+        });
+        it('should have same length as chains', () => {
+            assert.equal(chainIds.length, chains.length);
+        });
+    });
+    describe('chainNames', () => {
+        it('should map base chain ID to "base"', () => {
+            assert.equal(chainNames[8453], 'base');
+        });
+        it('should map pulsechain chain ID to "pulsechain"', () => {
+            assert.equal(chainNames[369], 'pulsechain');
+        });
+    });
+    describe('chainNameToId', () => {
+        it('should map "base" to base chain ID', () => {
+            assert.equal(chainNameToId['base'], 8453);
+        });
+        it('should map "pulsechain" to pulsechain chain ID', () => {
+            assert.equal(chainNameToId['pulsechain'], 369);
+        });
+    });
+    describe('getChainName', () => {
+        it('should return "base" for base chain ID', () => {
+            assert.equal(getChainName(8453), 'base');
+        });
+        it('should return "pulsechain" for pulsechain chain ID', () => {
+            assert.equal(getChainName(369), 'pulsechain');
+        });
+    });
+    describe('getChainIdFromName', () => {
+        it('should return base chain ID for "base"', () => {
+            assert.equal(getChainIdFromName('base'), 8453);
+        });
+        it('should return pulsechain chain ID for "pulsechain"', () => {
+            assert.equal(getChainIdFromName('pulsechain'), 369);
+        });
+        it('should return null for invalid chain name', () => {
+            assert.equal(getChainIdFromName('ethereum'), null);
+            assert.equal(getChainIdFromName('invalid'), null);
+            assert.equal(getChainIdFromName(''), null);
+        });
+    });
+    describe('isValidChainName', () => {
+        it('should return true for valid chain names', () => {
+            assert.equal(isValidChainName('base'), true);
+            assert.equal(isValidChainName('pulsechain'), true);
+        });
+        it('should return false for invalid chain names', () => {
+            assert.equal(isValidChainName('ethereum'), false);
+            assert.equal(isValidChainName('invalid'), false);
+            assert.equal(isValidChainName(''), false);
+            assert.equal(isValidChainName('BASE'), false); // Case sensitive
+        });
+    });
+    describe('getExplorerUrl', () => {
+        it('should generate correct tx URL for base', () => {
+            const url = getExplorerUrl(base, 'tx', '0x123');
+            assert.ok(url.includes('basescan'));
+            assert.ok(url.includes('/tx/0x123'));
+        });
+        it('should generate correct address URL for base', () => {
+            const url = getExplorerUrl(base, 'address', '0xabc');
+            assert.ok(url.includes('basescan'));
+            assert.ok(url.includes('/address/0xabc'));
+        });
+        it('should generate correct tx URL for pulsechain', () => {
+            const url = getExplorerUrl(pulsechain, 'tx', '0x456');
+            assert.ok(url.includes('/tx/0x456'));
+        });
+        it('should generate correct address URL for pulsechain', () => {
+            const url = getExplorerUrl(pulsechain, 'address', '0xdef');
+            assert.ok(url.includes('/address/0xdef'));
+        });
+    });
+    describe('chainIdToChain', () => {
+        it('should map base chain ID to base chain', () => {
+            assert.equal(chainIdToChain.get(8453), base);
+        });
+        it('should map pulsechain chain ID to pulsechain chain', () => {
+            assert.equal(chainIdToChain.get(369), pulsechain);
+        });
+        it('should return undefined for unknown chain ID', () => {
+            assert.equal(chainIdToChain.get(1), undefined);
+        });
+    });
+    describe('chainIdToTargetBlockTime', () => {
+        it('should have correct block time for pulsechain (10s)', () => {
+            assert.equal(chainIdToTargetBlockTime.get(369), 10_000);
+        });
+        it('should have correct block time for base (2s)', () => {
+            assert.equal(chainIdToTargetBlockTime.get(8453), 2_000);
+        });
+    });
+});