TypeScript SDK for the Polygon PoS bridge and PoS staking. Drives ERC-20,
ERC-721, ERC-1155 and native-ETH deposits, child-chain withdrawals, and
exit proofs against RootChainManager, and — from
@polygonlabs/maticjs/staking — validator and delegator staking against
StakeManager and the per-validator ValidatorShare contracts. Works with
viem, ethers v5, and ethers v6 — pick whichever you already have; the
SDK adapts.
This repository is the home of @polygonlabs/maticjs (4.0+) — the
continuation of maticjs under the @polygonlabs npm scope. Versions
up to 3.x remain published as @maticnetwork/maticjs; see the
migration guide if you are coming from
there.
pnpm add @polygonlabs/maticjs viem # or
pnpm add @polygonlabs/maticjs ethers # v5 or v6viem and ethers are optional peer dependencies; install only the one
you actually use. Static imports of either library are kept type-only
inside the SDK so the absent peer never crashes module load.
import { createPublicClient, createWalletClient, http } from 'viem';
import { sepolia } from 'viem/chains';
import { privateKeyToAccount } from 'viem/accounts';
import { POSClient } from '@polygonlabs/maticjs';
import { viemAdapter } from '@polygonlabs/maticjs/viem';
const account = privateKeyToAccount(process.env.PRIVATE_KEY as `0x${string}`);
const parentPublic = createPublicClient({ chain: sepolia, transport: http(process.env.PARENT_RPC) });
const parentWallet = createWalletClient({ account, chain: sepolia, transport: http(process.env.PARENT_RPC) });
const childPublic = createPublicClient({ transport: http(process.env.CHILD_RPC) });
const childWallet = createWalletClient({ account, transport: http(process.env.CHILD_RPC) });
const pos = await POSClient.init({
network: 'amoy',
parent: viemAdapter({ public: parentPublic, wallet: parentWallet }),
child: viemAdapter({ public: childPublic, wallet: childWallet })
});
// Read: balance of the bridged ERC-20 on the parent chain.
const erc20 = pos.parent.erc20(process.env.PARENT_TOKEN as `0x${string}`);
const balance = await erc20.getBalance(account.address);
// Write: approve the bridge predicate, then wait for inclusion.
const approve = await erc20.approve(1_000_000n);
console.log('approve hash:', approve.hash);
const receipt = await approve.confirmed();
console.log('approve mined in block:', receipt.blockNumber);Two things worth flagging in that snippet:
-
TxResult.confirmed(). Every write returns aTxResultwith the hash already populated. The receipt is fetched lazily by calling.confirmed(), and the result is memoised — call it twice and you get equivalent receipts without polling the chain twice. This separation replaces the legacygetTransactionHash()/getReceipt()pattern, which conflated "submitted" and "mined" in a single awaitable. -
No address constants.
POSClient.initvalidates configuration by fetching the active address index fornetworkfrom the Polygon CDN (https://static.polygon.technology/network/<network>/v1/index.json), caches it for one hour, and serves cached values stale-while- revalidate. Long-running services pick up Polygon contract redeployments without a restart. Override the cache TTL or supply pre-resolved addresses viaaddresses?: NetworkAddressesfor air-gapped deployments — seePOSClientConfiginsrc/pos-client.ts.
Runnable scripts for all three peer-dep flavours live in
examples/:
viem.ts— quickstart with viemethers-v5.ts— same flow with ethers v5ethers-v6.ts— same flow with ethers v6
See examples/README.md for the env vars each
script needs.
If you are upgrading a service from the 0.x / 3.x line, read
packages/maticjs/MIGRATION.md. The
4.0 release moves the package to the @polygonlabs scope, drops the
plugin layer, switches
amounts to native bigint, and renames a handful of methods —
nothing that requires a deep rethink, but everything is a breaking
change at the type level.
This is a pnpm monorepo. The published package lives in
packages/maticjs/; examples/ and manual/ (if present) are
standalone, intentionally not part of the workspace.
pnpm install # bootstrap
pnpm run lint # ESLint across the workspace
pnpm run typecheck # tsc --noEmit
pnpm --filter @polygonlabs/maticjs run build
pnpm --filter @polygonlabs/maticjs run testThe end-to-end tier runs the SDK's bridge and staking writes against a local
Polygon PoS devnet. It is opt-in and not part of pnpm test: boot the devnet,
then run pnpm run e2e. See packages/e2e/README.md.
Releases are managed via changesets.
The release workflow publishes automatically on merge to master.
Reach the team on Discord or file an issue at https://github.com/0xPolygon/matic.js/issues.
MIT.