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

[MaximusHaximus]

Why

@maticnetwork/maticjs 3.9.x accumulated a decade of abstraction debt with concrete failure modes: the plugin model mutated module globals (utils.Web3Client = X), making multi-tenant use unsafe; the lazy ITransactionWriteResult conflated "submitted" vs "confirmed" (a caller assuming getTransactionHash() was idempotent caused a production double-broadcast); the BaseToken → POSToken → ERC20 chain forced non-token contracts to extend a token base; ABIs loaded from a single CDN at runtime (a global SPOF); BaseBigNumber predated native bigint; and 27 : any + 50 as casts left consumers with no compile-time safety.

Scope: PoS only

This rewrite covers the PoS bridge. The zkEVM bridge is intentionally not ported — the zkEVM chain is winding down, so consumers using ZkEvmClient stay on @maticnetwork/maticjs (the two install side by side during the window) rather than migrating twice. Details in MIGRATION.md.

What we got

Construction — static, tree-shakeable adapter factories. Consumers wrap their existing client with a per-library factory imported from a subpath and pass it to POSClient.init:

import { POSClient } from '@polygonlabs/pos-sdk';
import { viemAdapter } from '@polygonlabs/pos-sdk/viem';   // or /ethers-v5, /ethers-v6
const pos = await POSClient.init({
  network: 'amoy',
  parent: viemAdapter({ public: parentPublic, wallet: parentWallet }),
  child:  viemAdapter({ public: childPublic,  wallet: childWallet  }),
});

The main entry imports no web3 library; you ship only the one you use. No plugin, no global state, no kind discriminator.

Cross-environment. Zero Buffer, zero node:*, zero dynamic import() — runs unchanged in Node ≥20 and modern browsers. The byte code (RLP / merkle / proofs) uses Uint8Array + ethereum-cryptography; byte-pinning tests prove parity. A Vite+Playwright test-app package loads the bundle in a real browser to keep it honest.

Type safety. 0 : any, 0 as any. The remaining as unknown as casts (all at the viem/ethers boundary in src/adapters/) are now fenced by a path-scoped ESLint rule that bans the double-assertion everywhere else. as const ABIs give viem-typed inference at every internal call site.

Correctness / capability (driven by a parity audit against the old SDK).

• Fast exits actually work: optional proofGenerationApiUrl (opt-in, no default — matches 0.x setProofApi) wires an internal client to the real proof-generation-api routes, fixing a 0.x mainnet-only network hardcode. The earlier rewrite accepted the URL but silently no-op'd it — a blocker the audit caught.
• Restored lost capabilities: pos.buildExitPayloads (← buildMultiplePayloadsForExit), pos.isDeposited (state-sync deposit confirmation), exposed flat alongside buildExitPayload, isCheckpointed, isWithdrawn, getBlockProof, getPredicateAddress — the non-token surface proof-generation-api and similar consumers rely on.
• Reorg-safe checkpoint reads default to the 'safe' block tag (rootChainDefaultBlock to tune), restoring a guarantee the rewrite had dropped (it read at latest).
• Mintable ERC-1155 predicate wired through init (was always throwing).

API ergonomics.

• TxResult = { hash, confirmed() } — observe-only, idempotent.
• prepareXxx sibling on every write returns unsigned { to, data, value? } for smart wallets (Safe / Sequence / AA bundlers), batching, and offline signing.
• parent / child namespaces replace the invertible isParent: boolean.
• Escape hatch (replaces 0.x .method(...)): pos.getAddresses() surfaces the resolved bridge addresses (via the SWR cache) and the vendored as const ABIs export at @polygonlabs/pos-sdk/abi — pair them with your own client to call any unwrapped contract method, fully typed by your library.
• Native bigint throughout; method renames (startWithdraw, completeWithdraw[Fast], soliditySha3).

Errors. POSBridgeError extends VError (Joyent verror's TS-first, browser-friendly port — findCauseByName / info / fullStack, zero deps). Closed 27-code discriminator union; codes match the 0.x ErrorHelper keys so existing dashboards keep matching. The vague BRIDGE_ADAPTER_NOT_FOUND and the now-unreachable UNSUPPORTED_PROVIDER were removed; CONTRACT_NOT_AVAILABLE_ON_NETWORK added for honest network-capability conditions.

Cleanup. webpack 4 → tsup (ESM + CJS + DTS; index + three adapter subpath entries, libraries externalized). abstracts/, implementation/, enums/ deleted. Source ~3,900 lines (from 5,674).

Commits

1. chore(workspace) — tooling, CI (incl. test secrets + nightly e2e), the as unknown as lint ban, plan docs.
2. refactor(pos-sdk)! — the SDK + examples + README + MIGRATION + the major changeset.
3. test(test-app) — the browser smoke test.

Test plan

• Add repo secrets POS_SDK_TEST_PARENT_RPC, POS_SDK_TEST_CHILD_RPC, POS_SDK_TEST_PRIVATE_KEY so PR CI runs the integration tier (skips cleanly without them)
• Verify PR CI green: lint, typecheck, unit, integration, browser smoke (Playwright installs the browser in CI)
• Verify nightly CI green at least once (gated 4h deposit-withdraw cycle per adapter)
• 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 with pnpm exec changeset publish on the merge commit
• Migrate proof-generation-api to pos.buildExitPayload/buildExitPayloads/isCheckpointed/getBlockProof; audit portal and staking-ui for legacy pos.client.parent.X calls per MIGRATION.md
• Record real burn-tx fixtures for tests/integration/exit-payload.test.ts; verify test-token addresses in tests/fixtures/networks.ts
• After merge: deprecate @maticnetwork/maticjs on npm (PoS users → @polygonlabs/pos-sdk; zkEVM users stay until chain shutdown)