Skip to content

MIGRATION.md

Latest commit

 

History

History
170 lines (131 loc) · 5.97 KB

MIGRATION.md

File metadata and controls

170 lines (131 loc) · 5.97 KB

Migration: @maticnetwork/meta → @polygonlabs/meta

@polygonlabs/meta@1.0.0 replaces @maticnetwork/meta@2.4.82. The underlying ABI and address data is unchanged. The npm-package surface is significantly different; the public HTTP endpoint at https://static.polygon.technology/... continues to serve the same JSON files unchanged.

What you get

Three things, none of which existed before:

  1. Tree-shakable, deep imports per contract. import { abi } from '@polygonlabs/meta/abi/mainnet/v1/pos/AccessControl' pulls exactly one ABI; the rest of the package isn't bundled.
  2. as const literal types, so viem, wagmi, and abitype infer function names, argument types, and return types at the call site. See "Why as const" below — it's the single biggest reason to migrate.
  3. Typed network metadata under /info/* (chain IDs, RPC URLs, contract address maps), also as const.

What's unchanged

  • The static.polygon.technology HTTP endpoint keeps serving the same JSON files. If you fetch() URLs like https://static.polygon.technology/network/mainnet/v1/artifacts/pos/AccessControl.json, nothing changes for you.
  • The raw JSON path is also reachable from the npm package via import abi from '@polygonlabs/meta/network/<...>.json' with { type: 'json' }. Same file paths as @maticnetwork/meta@2.x had — only the package name changes.

What's gone

  • CommonJS require() is no longer supported. The package is ESM-only.
  • Node < 24 is no longer supported.
  • The Mumbai testnet was already dropped from the source tree. Use Amoy.

Required environment

  • Node ≥ 24
  • ESM consumer (use import, not require)

The package itself is ESM-only — we don't publish a CommonJS distribution. That doesn't lock CJS apps out: modern bundlers (esbuild, webpack 5+, Vite, Rollup, Parcel) consume ESM packages from CJS host code transparently. If you're building a bundled app and your bundler handles ESM dependencies (most do), @polygonlabs/meta works whether your own source is ESM or CJS.

The only environments where this is a hard block are Node runtimes that still load this package via require() without bundling, or older bundlers without ESM support. Those should fetch JSON from static.polygon.technology over HTTPS instead.

Import migration

Static, typed ABI access (preferred)

// Before
const RootChainABI = require('@maticnetwork/meta/network/mainnet/v1/artifacts/plasma/RootChain.json').abi
// After
import { abi as RootChainAbi } from '@polygonlabs/meta/abi/mainnet/v1/plasma/RootChain'

The new path is tree-shakable and gives you the literal as const type that viem/wagmi/abitype need.

Raw JSON access (no types)

// Before
const RootChainJson = require('@maticnetwork/meta/network/mainnet/v1/artifacts/plasma/RootChain.json')
// After — same path, just the renamed package
import RootChainJson from '@polygonlabs/meta/network/mainnet/v1/artifacts/plasma/RootChain.json' with { type: 'json' }

Network metadata

// Before
const Network = require('@maticnetwork/meta/network')
const net = new Network('mainnet', 'v1')
const chainId = net.Main.ChainId
// After (preferred — fully typed)
import { info } from '@polygonlabs/meta/info/mainnet/v1'
const chainId = info.Main.ChainId  // typed as the literal `1`

Dynamic name-based lookup

The Network class is gone. Code that previously did new Network('mainnet', 'v1').abi('RootChain') should switch to the static deep imports shown above — fully typed, sync, and tree-shakable. For runtime name → ABI lookups, build a small map at the call site:

import { abi as RootChainAbi } from '@polygonlabs/meta/abi/mainnet/v1/plasma/RootChain'
import { abi as DepositManagerAbi } from '@polygonlabs/meta/abi/mainnet/v1/plasma/DepositManager'

const ABIS = { RootChain: RootChainAbi, DepositManager: DepositManagerAbi } as const

This keeps the bundler honest: only the contracts actually referenced end up in the bundle.

Why as const

Each generated module looks like:

export const abi = [
  { type: "function", name: "hasRole", inputs: [...], outputs: [...] },
  ...
] as const;

That trailing as const is load-bearing, not stylistic. Without it, TypeScript widens the array element type to a generic { type: string; name: string; inputs: ...[] }, which means viem / wagmi / abitype cannot extract function names, argument types, or return types at the call site — the whole point of shipping typed ABIs disappears.

With as const, every string literal stays at its exact value and the array becomes a tuple, giving consumers full type-level inference:

import { abi } from '@polygonlabs/meta/abi/mainnet/v1/pos/AccessControl'
import { readContract } from 'viem'

await readContract(client, {
  abi,                          // ← needs `as const` for the next line to compile
  functionName: 'hasRole',      // ← autocompleted from the literal tuple
  args: [bytes32Role, address], // ← arg types inferred from the function's `inputs`
})

The codegen step (scripts/codegen.mjs) emits each ABI module with the trailing as const automatically. Don't hand-edit anything under src/generated/ — it's gitignored and regenerated on every build.

Path scheme

@polygonlabs/meta/abi/<chain>/<network>/<type>/<Contract>           # typed
@polygonlabs/meta/info/<chain>/<network>                            # typed
@polygonlabs/meta/info/networks                                     # typed
@polygonlabs/meta/network/<chain>/<network>/artifacts/<type>/<C>.json  # raw JSON
chain network types available
mainnet v1 pos, plasma, fx-portal, genesis
mainnet cherry zkevm
testnet amoy pos, plasma, fx-portal, genesis
testnet cardona zkevm