refactor: rewrite & modernization - @polygonlabs/pos-sdk@1.0.0

[MaximusHaximus]

Why

@maticnetwork/maticjs 3.9.x has accumulated a decade of abstraction debt that actively obstructs both consumers and maintainers. These are concrete failure modes, not cosmetic concerns:

• The plugin model mutates module-level globals (utils.Web3Client = X). Constructing two POSClient instances against different networks in the same process — a routine pattern in indexers and multi-tenant API services — cross-contaminates them. We have hit this in production.
• The lazy ITransactionWriteResult shape conflates "submitted" and "confirmed". getTransactionHash() initiates a send rather than observing one, and consumers consistently mis-use it. A caller assuming getTransactionHash() was idempotent caused a production outage by double-broadcasting a transaction.
• The BaseToken → POSToken → ERC20 inheritance chain forces every contract wrapper — including RootChainManager and GasSwapper, which are not tokens — to extend a class named BaseToken. Adding a new contract wrapper requires inheriting bridge-specific predicate logic that does not apply to it. This has blocked otherwise-trivial feature work multiple times.
• ABIs are loaded at runtime from a single CDN. If static.polygon.technology moves, every running consumer breaks. This is a single point of failure for the entire SDK.
• BaseBigNumber predates native bigint by half a decade and now adds boilerplate without value. Consumers convert from their library's native type into BaseBigNumber only to have the SDK convert it back internally.
• Type safety is poor. 27 : any types and 50 as casts on the public surface, including 5 as any casts that erase the entire client config type. Consumer code has no compile-time signal that it is misusing the SDK.

Scope: PoS only — zkEVM stays on the legacy package

@maticnetwork/maticjs shipped both the PoS bridge and the zkEVM bridge surfaces. This rewrite covers only the PoS side. The zkEVM chain is on a wind-down schedule; rewriting and shipping a @polygonlabs/zkevm-sdk would put consumers through a migration twice — once now, once when the package is sunset alongside the chain. Skipping the intermediate step is cleaner:

• PoS-only consumers migrate to @polygonlabs/pos-sdk per MIGRATION.md.
• zkEVM-only consumers stay on @maticnetwork/maticjs and drop the package when the chain is shut down.
• Mixed consumers install both packages side by side during the window — they have non-overlapping public surfaces.

What we got

Correctness and determinism

• Multi-tenancy safe. No more utils.Web3Client = X global mutation. Multiple POSClient instances against different networks coexist in one process without cross-contamination.
• Tx-result foot-gun fixed. TxResult = { hash, confirmed() } is observe-only — no method call has hidden side effects. The hash is populated synchronously the moment the RPC accepts the broadcast; confirmed() waits for the receipt and is idempotent.
• ABIs cannot drift from the code. Vendored at SDK build time as as const TypeScript files, so the SDK's compiled call sites and the bundled ABIs are guaranteed to match. The CDN dependency for ABIs is gone.
• Long-running services pick up contract redeployments without restart. Addresses are still dynamic (the RootChainManager and predicate addresses change occasionally and we do not want to ship a new SDK each time), but the AddressFetcher uses stale-while-revalidate semantics on a 1h TTL — every individual call serves the cached value at near-zero cost, and the next call after the TTL window kicks off a background refresh.
• No Boolean traps. pos.parent.erc20(addr) and pos.child.erc20(addr) namespaces eliminate the easily-inverted isParent: boolean parameter.
• No silent ABI version pinning. The legacy version config field that let consumers pin to stale contract metadata is gone — there is one canonical ABI per release.

Type safety

• All 27 : any types eliminated. The four load-bearing ones (provider: any, abi: any) are now typed via the Adapter interface and as const ABIs respectively.
• All 50 as casts pruned. The 5 as any casts on the legacy Web3SideChainClient config disappeared entirely with the class.
• TYPE_AMOUNT (legacy BaseBigNumber | string | number union) replaced with native bigint on 27+ method signatures.
• as const ABIs give viem-typed inference at every internal call site — method names, argument shapes, and return types are compile-time-checked.
• POSBridgeError's 28-code discriminator union enables exhaustive switch narrowing in consumer error handlers — TypeScript fails the consumer's build the moment a new failure mode is added without a corresponding case.

Capability — keeping the tools consumers actually rely on

A migration audit across repositories/ (portal, proof-generation-api, staking-ui, bridge-indexer, etc.) surfaced two real consumer use cases the initial rewrite cut too aggressively. Both are addressed in this PR:

• Unsigned transactions for smart wallets. Every public write now has a prepareXxx sibling (prepareApprove, prepareDeposit, prepareCompleteWithdraw, …) that returns { to, data, value? } instead of broadcasting. Closes the gap for Safe / Sequence / account-abstraction bundlers, batched multicall flows, pre-flight inspection, and offline signing. Replaces the legacy option.returnTransaction foot-gun (same return type meaning two different things depending on a boolean) with two distinct, statically-typed methods.
• Bridge helpers exposed flat on POSClient. proof-generation-api (and any other consumer building exit payloads outside the standard token flows — sync block events, custom bridge events, plasma exits) used pos.client.exitUtil.{buildPayloadForExit, isCheckPointed, getBlockProof, …} directly. The 1.0 SDK exposes those as pos.buildExitPayload, pos.isCheckpointed, pos.getBlockProof, pos.isWithdrawn, pos.isWithdrawnOnIndex, pos.getPredicateAddress, pos.buildExitPayloadOnIndex. The token classes still wrap them for the 95% case.

Errors extend VError

POSBridgeError extends VError from @polygonlabs/verror — a TypeScript-first, browser-friendly port of Joyent's canonical Node verror library. Consumers get the standard cause-chain helpers (findCauseByName, findCauseByType, info(err), fullStack(err)) matching Joyent's documented API, plus a typed code discriminator on top. info is an own enumerable property, so any logger that serializes own properties on Error instances picks up the structured payload. Zero runtime dependencies and ESM-only — bundles cleanly for both Node and browser.

Performance and resource use

• Per-contract ABI fetches eliminated — ~70 KB across many round trips replaced by a single ~7 KB index.json fetch for addresses.
• Web3SideChainClient singleton removed; per-instance state reduces memory pressure in multi-tenant deployments.
• Address cache keyed by ${baseUrl}/${network}, not just network — survives POSClient instance churn and stays multi-tenant-safe.
• p-limit (battle-tested 10 KB dep) replaces ~80 lines of custom mapPromise with cleaner concurrency semantics and proper first-failure rejection.

Observability

• POSBridgeError exposes a stable discriminator code consumers can route on (error.code === 'BURN_TX_NOT_CHECKPOINTED'). The 28 codes match the legacy ErrorHelper.throw(code, ...) keys verbatim, so existing consumer dashboards and alert queries continue to fire after the rewrite.
• RPC token sanitisation (regex strip of ?token=... / &token=...) applied at the SDK boundary before errors reach consumer loggers — protects services using non-sanitising loggers from leaking RPC credentials.
• Structural Logger interface (pino-shaped) lets consumers plug in their own structured logger (pino, bunyan, custom) without the SDK taking a runtime dep on any specific implementation. The default is noopLogger — the SDK no longer writes to stdout.

Browser compatibility

A new @polygonlabs/pos-sdk-test-app workspace package (packages/test-app/) bundles the SDK through Vite and exercises the public surface in a real browser via Playwright. Catches any case where the SDK accidentally relies on Node built-ins, polyfills, or non-browser-safe APIs that Vitest's Node-mode tests would miss. The Playwright spec runs in chromium and asserts the bundle loads cleanly, every public symbol is callable, and no console.error occurs. pnpm -r run test auto-skips the spec gracefully when Playwright browsers aren't installed.

The smoke test surfaced a real long-term hazard worth tracking: pos-sdk's dist transitively imports Node's events (via @ethereumjs/util's asyncEventEmitter) and buffer (via readable-stream / safe-buffer) — 60 Buffer references in dist/, behind method-call gates so the happy path doesn't trip them.

Testability

• ContractCaller and POSBridgeHelpers are independently mockable services because they were extracted as composition, not inheritance. Unit testing the bridge logic no longer requires instantiating the full client.
• Pure functions — proof building, Merkle tree construction, RLP encoding — are now independently testable without spinning up a chain.
• Adapter parity tests run the same suite three times (viem, ethers v5, ethers v6) to catch translation bugs at PR time.
• Historical burn-tx fixtures let exit-payload byte-snapshot tests run in seconds without waiting for a fresh checkpoint cycle.

Architectural cleanup

• BaseToken → POSToken → ERC20 chain dismantled in favour of two composed services: ContractCaller (transaction plumbing) and POSBridgeHelpers (predicates, exit payloads). Adding a new contract wrapper now means writing a class that uses a ContractCaller, not one that inherits 3 levels of bridge logic that does not apply.
• The abstracts/, implementation/, and enums/ directories are deleted entirely.
• 11 utility files deleted; all circular dependencies between utils/index.ts ↔ abstracts/index.ts ↔ subpaths broken.
• Webpack 4 → tsup (single config, ESM + CJS + DTS, target: es2023).
• Final source tree: ~3,900 lines (down from 5,674), structurally clearer.

Test plan

• Add repo secrets POS_SDK_TEST_PARENT_RPC, POS_SDK_TEST_CHILD_RPC, POS_SDK_TEST_PRIVATE_KEY so PR-trigger CI runs the full integration suite (without them, the integration tier skips cleanly via describe.skipIf(!HAS_CREDS))
• Verify PR CI green: lint, typecheck, unit, integration, browser smoke (Playwright)
• Verify nightly CI green at least once (runs the gated 4h deposit-withdraw cycle test on each adapter via .github/workflows/ci-nightly.yml)
• Verify the auto-generated changeset-release/master PR appears after merge
• First-publish bootstrap: if CI publish 403s on the initial @polygonlabs/pos-sdk release, recover locally with pnpm exec changeset publish on the merge commit
• Migrate proof-generation-api to use pos.buildExitPayload, pos.isCheckpointed, pos.getBlockProof in place of maticClient.exitUtil.X (full mapping in MIGRATION.md)
• Audit portal and staking-ui for legacy pos.client.parent.X calls (signTypedData, etheriumSha3, encode, sendRPCRequest) and migrate per MIGRATION.md's replacement table
• Confirm any consumers using the legacy ZkEvmClient understand they keep @maticnetwork/maticjs installed alongside @polygonlabs/pos-sdk (or only) until the zkEVM chain is shut down
• Record real burn-tx triples for tests/integration/exit-payload.test.ts (one per ERC-20/721/1155); recording procedure in packages/pos-sdk/tests/README.md
• Verify test-token contract addresses in tests/fixtures/networks.ts against currently-deployed mintable testnet tokens
• Reduce pos-sdk's transitive Node-built-in deps (Buffer, events) so the test-app's stub layer can be removed — track as a follow-up, not a blocker for 1.0
• After merge: deprecate @maticnetwork/maticjs on npm with a message pointing PoS users at @polygonlabs/pos-sdk and zkEVM users at the chain's wind-down notice
• After merge: update internal services consuming @maticnetwork/maticjs per packages/pos-sdk/MIGRATION.md