[MaximusHaximus]

Problem

The service builds every withdrawal proof and exit payload with @maticnetwork/maticjs 3.x and its ethers plugin. That line is frozen: future bridge fixes land only in its successor, @polygonlabs/maticjs 4.0. The 3.x plugin model also forces costs on this service:

• a module-load use(Web3ClientPlugin) with CJS default-export workarounds, in the code and in the test config;
• every SDK call site typed any;
• deterministic exit errors (log not in receipt, token index out of range, not yet checkpointed) recognised by matching SDK error message text.

Solution

• Move to @polygonlabs/maticjs, pinned exactly at the 4.0.0-pre.2 prerelease. This service is the prerelease's production dogfood before 4.0.0 is declared stable.
• Build a typed POSClient per network from two ethersV5Adapters.
• Keep the client cache, static providers, 10 s RPC timeout, RPC header and receipt fan-out cap (requestConcurrency: 10 → proofConcurrency: 10) unchanged.
• block-included reads RootChain.headerBlocks through ethers directly, the SDK's documented escape hatch. Its JSON keeps the historical { "type": "BigNumber", "hex": … } fields byte-for-byte.
• Checkpoint checks use the status read getCheckpointStatus(...).checkpointed. The 4.0 boolean predicate is gone. Same branches, same errors when the burn isn't checkpointed.
• Deterministic exit errors are classified by the SDK condition, not message text: isMaticjsError plus LogNotFoundInReceiptError / IndexOutOfBoundsError / BurnTxNotCheckpointedError .has(). These are the SDK's own name-based recognisers: they walk the cause chain (public methods throw an operation error whose cause is the condition) and work across duplicate package copies, realms and JSON round-trips. The service never uses instanceof on SDK errors. The public 404 messages are unchanged, and every other condition, including ReceiptsRootMismatchError and TransactionNotFoundError, is retried as before. The thrown value goes to the classifier as-is, never normalised to an Error first. Tests cover each mapped condition bare and wrapped, JSON round-tripped errors, unmapped conditions and raw library errors, through the classifier, the log fields and the full exit-payload retry loop.
• Retry-warning log lines: errorEvent is replaced by errorType (the SDK condition's legacy 3.x type, where it has one) and errorCode. errorCode is the name of the innermost SDK condition (e.g. LogNotFoundInReceiptError), or, for raw RPC failures (which 4.0 rethrows unwrapped), the RPC library's own code as before.
• Every SDK call site that was typed any is now typed. No casts were introduced.

Known state

• The public API is unchanged except for one edge case. All fixture responses are byte-identical to the current production service (see Verification).
• The edge case: an exit-payload request for a burn that is still pending (submitted, not yet in a block) now gets an immediate 404 "Burn transaction has not been checkpointed yet", the same answer as for a mined burn awaiting its checkpoint. 4.0's checkpoint status reports a pending burn as "not checkpointed, reason: pending". On 3.x the checkpoint check didn't catch it and the request failed after exhausting retries, most likely a 502. A client polling until its exit is ready now gets the same 404 from submission to checkpoint. Tests pin both "not yet" reasons and the rejected-lookup path.
• New in 4.0: buildExitPayload refuses to return a payload whose receipts don't match the block's receiptsRoot (ReceiptsRootMismatchError). That usually means an RPC served bad receipts, so the service retries it on the next RPC like any transient failure and answers 502 only after retries are exhausted.
• Once 4.0.0 is published as stable, the exact pin moves to ^4.0.0 in a follow-up.
• Dogfood watch (daily for 7 days after deploy):
  1. Error-level log lines by err_type, against the pre-deploy baseline (about 4 per 7 days, at most 1 per 5 minutes). Any new error type is a finding.
  2. Retry warnings by errorType/errorCode: same order of magnitude as before. Any ReceiptsRootMismatchError is a finding, recorded per RPC origin.
  3. Proof-path failures (historically Invalid merkle proof created) and their 4.0 equivalents.
  4. The service's error-rate alert and capacity alert stayed quiet, or the incident is linked here.
  5. External availability and correctness probes stay green.
  6. The byte-diff smoke against the deployed service is re-run and stays identical.
  7. The OpenAPI info.version matches the released version.
  8. No new error-tracking issue types.
  9. Day 7: dependency resolution is confirmed on the deployed tag, and the result is handed over for the 4.0.0 stable decision.

Verification

• Battery: pnpm run lint green; pnpm test 59/59 (the 40 pre-existing tests unchanged and green, plus new tests). The test run makes live RPC calls on mainnet and Amoy, including the Bor state-sync receipt regression.
• Byte-diff against production: the migrated service was run locally and every test-fixture route was fetched from it and from https://proof-generator.polygon.technology. Status codes and bodies are byte-identical on 25/25 routes: health, block-included (mainnet/Amoy/404/400s), fast-merkle-proof (200 + 5 × 400), exit-payload ERC-20 (with and without index, out-of-range index 404), ERC-1155, all-exit-payloads ERC-721, Amoy state-sync, and every validation 400.
• That byte-diff was repeated against the exact 4.0.0-pre.2 tarball before it was published (25/25 identical). The published tarball's sha256 matches it, and the lockfile pins its integrity.
• Docker: image built from a fresh frozen install; the remote-mode battery passed against the container (on the pre-publish artifact; CI's docker job covers the published one). Memory flat over 200 sequential exit-payload requests.
• Independent review: every 3.x call and error code was checked against its 4.0 equivalent, including where the SDK throws each mapped code. No error moved between "deterministic 404" and "retried".
• Adversarial audit: verdict safe with fixes. Two low-severity findings were fixed on this branch:
  • b419fa4: shape-based classification now happens before any Error normalisation.
  • e451b32: a full-body test pins the block-included BigNumber wire shape on an immutable header block, since the service has no response schemas to guard it.
• The audit's SDK observations (against pre.1) are parity with 3.x, with no action:
  • POSClient.init fetches the static network index with a 1 h cache.
  • The ethers v5 adapter builds a Contract per read.
  • TRANSACTION_NOT_FOUND is retried across the RPC list before the 404.