@trustswap/teamfinance-chain-config

@trustswap/teamfinance-chain-config

Package that contains list of supported chains by Team Finance, as well as various public, up-to-date contract addresses provided by Team Finance/TrustSwap. This is meant to be shared among our codebase.

It is the successor of teamfinance-chains package.

Installation

Using npm

npm i @trustswap/teamfinance-chain-config

or yarn

yarn add @trustswap/teamfinance-chain-config

Bump version

# edit version of `package.json`
npm i
# commit files

Usage

There are several exported modules from this library, main ones are chains and contracts. Their sample usage is as below:

chains.evmMainnetChainsMap.ethereum

Testing

The package has a test suite of 440 tests under tests/, run with Node's built-in test runner, plus seven mutation harnesses:

npm test        # 440 tests: 439 pass, 1 skipped, 0 fail — on a bare checkout, which is what CI runs
npm run mutants # 238 mutations; every one must print CAUGHT, and every edit must apply

It is a required CI check (.github/workflows/generated-in-sync.yml), which also regenerates src/generated and fails the build if the committed output has drifted from what src/build.mts currently produces, and it now gates the npm publish (.github/workflows/auto-publish.yml).

Every test runs everywhere. Exactly one can skip — "the committed captures still match the sibling sources" — and it gates nothing: it re-parses the sibling repositories when a checkout is present, to confirm the committed captures are still current. On a machine that has them the same suite reports 440 pass and 0 skipped: the total never depends on what else is on the machine, and only that one line of the split does. Everything those siblings verify runs regardless, against captures under tests/fixtures/:

capture	source
workerPlatform.json	teamfinance-experimantal: chains.yaml, chains.gcp.yaml, and chain-clients.ts as of 44d76642
indexerProcessors.json	teamfinance-subsquid-multichain-indexer: the 24 per-chain processors as of dd691ff^
chainsIdHexOrder.json, productLists.json, newChainIds.json	teamfinance-frontend, captured before it began deriving these from this package
coingeckoAssetPlatforms.json	CoinGecko /api/v3/asset_platforms, filtered to this package's chain ids

Refresh the two sibling captures with node tests/support/capture-sibling-fixtures.mjs; each records the resolved commit id of every file it read.

Two of those structures no longer exist at their sibling's HEAD — the worker platform's inline defineChain blocks became toViemChain() calls into this package, and the indexer collapsed its per-chain processors into one — which is why those captures are pinned to a revision instead of read live. The frontend ones are frozen for the same reason in a different form: once a consumer derives a value from this package, asserting this package matches that consumer is a tautology no mutation can fail. See the comment at the top of tests/derived-views.test.mjs.

These captures are bounded-life guards, not living contracts. A deliberate change on either side makes them stale on purpose, and whoever makes it must re-capture in the same commit.

Recent changelog

1.7.0

• Added optional indexing, ops, and presentation schema blocks to IEvmChainType/ IChainType, plus their supporting interfaces IChainIndexing, IChainOps, IChainPresentation, IChainPrices, and IChainProducts.

• Added four new exports derived from the chain data: chainsInDisplayOrder, displayOrderChainIds, chainsByProduct, and newBadgeChainIds.

• Widened IChainType.rpcUrls from a one-element tuple ([string]) to string[], and added an optional blockExplorerName field, both transcribed from the worker platform's config.

• Backfilled the new indexing/ops fields for every chain the worker platform or the indexer actually runs: subsquid gateway URLs, the LockToken ABI variant, RPC env-var names, processor rate-limit/finality/batch-size tuning, the block explorer API base, Uniswap V3 deployment addresses, multicall3 presence, and the per-environment subgraph provider.

• Added rpcFallbackUrls, the app's ordered read-failover list, for the 23 chains that have one. It is deliberately separate from rpcUrls, which is wallet-facing.

• Changed published data. Sixteen values, every one of them consumer-visible. Diff your own usage before upgrading if you read any of these fields:

  Native currency — symbol reaches wallet_addEthereumChain exactly as name does, so both are rendered to users by their wallet:

  • arbitrum.nativeCurrency.symbol: "ARB" → "ETH" (ARB is a governance token; gas is ETH).
  • blast.nativeCurrency.symbol: "BLAST" → "ETH".
  • sepoliaTestnet.nativeCurrency.symbol: "SEP" → "ETH" (SEP was never a real symbol).
  • autheo.nativeCurrency.name: "THEO" (its own symbol, not a name) → "Autheo".
  • velas.nativeCurrency.name: "Velas-Mainnet" → "Velas".

  Chain identity and links:

  • zkSync.name: "zkSync" → "zkSync Era" (the post-rebrand name).
  • velas.blockExplorerUrls[0]: "https://evmexplorer.velas.com/rpc" (an RPC endpoint) → "https://evmexplorer.velas.com".

  Contracts:

  • nftLockContracts["0xaa36a7"]: the zero address → the deployed 0x962f07445ED033f7A8815ec349D9Eceb77F5C3c2 (startBlock 3463391). Sepolia's NFT lock was recorded as undeployed; it is live. presentation.products.liquidityNFT stays false — a deployed contract and a listed product are independent facts here.

  Price-service ids — the six coingeckoPlatform values below were GeckoTerminal network ids, which are a different namespace: every CoinGecko route built from them returns 404. Verified against /api/v3/asset_platforms, joined on the response's chain_identifier:

  • cronos: "cro" → "cronos"; fantom: "ftm" → "fantom"; ethClassic: "ethereum_classic" → "ethereum-classic"; flare: "flare" → "flare-network"; kaia: "kaia" → "klay-token"; unichain: "eth" → "unichain".
  • autheo.coingeckoPlatform: "autheo" → removed. CoinGecko lists no asset platform for chain id 2127; the old value was the chain's name, not an id from anywhere.
  • unichain.geckoTerminalIdentifier: "eth" → "unichain". "eth" is Ethereum on GeckoTerminal, so this one resolved and returned another chain's data.

• Added a CI check that fails when src/generated is out of sync with src/build.mts, and gated the npm publish on the test suite.

• Added a test suite (see "Testing" above).

Contributing

• This package is written in TypeScript to make sure type-safe nature of the codebases, therefore no any is allowed.
• Please don't add anything sensitive (api keys, secrets,...) into the codebase as it is publicly available on npm. After deployment, it is available on the web and anyone can see those.
• The package is automatically published to NPM upon these conditions (both):
  • A new commit on main branch
  • The version field in package.json is different from any of the published versions on NPM.
• On contract addresses object, consider using the chain ID as the key, since each chain has unique chain ID and we can make use of functions in Object prototype of Javascript itself.
• The chain IDs in the objects should be in hex format, and in lower case.