@magnaflow/chain-provider

Chain provider abstractions for unified EVM and Tron operations.

What It Provides

• A shared ChainProvider interface for balances, transfers, receipts, and gas estimation
• EvmProvider backed by viem
• TronProvider backed by tronweb
• Factory helpers for creating providers from backend chain configuration

Install

npm install @magnaflow/chain-provider

Key Exports

• createChainProvider
• createEvmProvider
• createTronProvider
• getChainType
• EvmProvider
• TronProvider
• createViemChainFromConfig

Example

import { createChainProvider } from '@magnaflow/chain-provider';

const provider = createChainProvider(
  {
    name: 'BSC Mainnet',
    chain: 'bsc',
    rpc_url: 'https://bsc-dataseed.binance.org',
    rest_url: 'https://bsc-dataseed.binance.org',
    payout_contract: '0x0000000000000000000000000000000000000000',
  },
  process.env.MNEMONIC,
);

const balances = await provider.getBalances('0x1234...', [
  '0x55d398326f99059fF775485246999027B3197955',
]);

Notes

Polygon Mainnet

Only the exact polygon_mainnet key enables Polygon (137 / 0x89, POL / 18, Polygonscan). Aliases and Polygon testnets are not supported. Supply runtime configuration from the API; the provider does not supply token or payout addresses.

const polygonConfig = apiChainConfigs.find((config) => config.chain === 'polygon_mainnet');
if (!polygonConfig) throw new Error('Polygon is not enabled');
const polygonProvider = createChainProvider(polygonConfig);
const nativeBaseUnits = await polygonProvider.getNativeBalance(merchantAddress);

Polygon uses nonempty rpc_url, falling back to rest_url only when empty. Optional chain_id and chainId must both identify 137 when supplied. A supplied native symbol must be POL, not MATIC. Public and wallet transports validate eth_chainId, including direct client access and a fresh check before broadcasting. Existing chains retain their RPC and fallback behavior. Balances remain raw base units; consumers use runtime token decimals and POL's 18 native decimals.

Polygon support starts in @magnaflow/[email protected]. Keep application dependencies, Bun overrides and lockfiles aligned with that release for CI installs.

For unreleased changes, build this workspace and pack/link this package locally.

For the current Kit checkout, its Bun overrides select the registry version even after a link. Install the built tarball into that checkout's existing node_modules for local integration, leaving its manifest and lockfile unchanged. Start in the SDK repository root, with the Kit checkout in a sibling directory:

polygon_pack_dir=$(mktemp -d "${TMPDIR:-/tmp}/polygon-provider-pack.XXXXXX")
bunx nx run chain-provider:build
cd packages/chain-provider
polygon_provider_version=$(bun -p 'require("./package.json").version')
bun pm pack --destination "$polygon_pack_dir"

cd ../../../merchant-tools-v2
polygon_backup=$(mktemp -d "${TMPDIR:-/tmp}/polygon-provider-backup.XXXXXX")
cp -R node_modules/@magnaflow/chain-provider "$polygon_backup/chain-provider"
tar -xzf "$polygon_pack_dir/magnaflow-chain-provider-$polygon_provider_version.tgz" --strip-components=1 -C node_modules/@magnaflow/chain-provider
bun -e 'import {createViemChainFromConfig} from "@magnaflow/chain-provider"; const chain = createViemChainFromConfig({chain:"polygon_mainnet",rpc_url:"https://rpc.example",rest_url:""}); console.log(chain.id, chain.nativeCurrency.symbol);'
bun run validate
bun run build

The check prints 137 POL. This package uses the workspace's bundler-style ESM output; run this check with Bun, as used by Kit. A later dependency install can replace the local package, so repeat the unpack and resolution check afterward. The rpc.example value only verifies resolution and makes no network request.

• The default EVM chain resolver is currently tuned for BSC and BSC testnet style configs.
• TronProvider supports native transfers and balance queries. Advanced Tron contract interaction lives outside this package.

Development

bunx nx run chain-provider:lint
bunx nx run chain-provider:test
bunx nx run chain-provider:build

License

This package is part of the merchant-v2-sdk monorepo and is covered by the root MIT license.

See ../../LICENSE for details.