feat(protocol-core): add version-discriminated deployment addresses to ChainConfig

[henrypalacios]

Summary

• Add an optional deployments list to ChainConfig, modelled as a union discriminated by protocol version, plus a getDeployment(chainId, version) lookup whose result narrows to the requested family.
• Add an optional chain-level multicall address, which is version-agnostic.
• Add checkDeploymentCoherence, run for every chain inside the existing pre-publish address validation, so each deployment entry targets a version its chain declares, appears once, and holds a real contract address.
• Populate deployment data for Polygon and Polygon zkEVM.

Why

ChainConfig describes chain identity — chain id, name, native and wrapped native, the protocol versions the chain runs, its stablecoins — but it has never carried contract addresses. There is no canonical home for them in the package, so every consumer keeps its own address map and its own assumptions about which contracts each protocol family deploys. Those maps drift, and nothing in the SDK can tell a caller which factory or quoter belongs to which version on a given chain.

This change puts the addresses next to the chain identity that already exists, and encodes the differences between protocol families in the type system:

• V2 pairs are fungible ERC20 tokens priced by closed-form constant-product math, so those entries carry no quoter and no position manager.
• Only the Algebra families derive pool addresses from a pool deployer rather than from the factory.

Modelling deployments as a discriminated union makes those asymmetries compile errors instead of conventions a reader has to know, and getDeployment returns the family it was asked for.

Polygon zkEVM is the case that exercises this fully: it runs Algebra v3 alongside a Uniswap-V3 fork, and those two quoters expose different ABIs. Resolving them by version is what stops a caller reaching for the wrong one.

Size

The diff is large — 495 added lines — and roughly two thirds of it is tests. Source and script changes are 165 lines across 8 files; the remaining 330 lines are test coverage, including type-level assertions now enforced by vitest type-checking.

Changes

File	Change
src/chains/types.ts	ProtocolDeployment union discriminated by version; optional deployments and multicall on ChainConfig
src/chains/deployments.ts	getDeployment(chainId, version) with a narrowing return type
src/chains/deploymentCoherence.ts	checkDeploymentCoherence(chain) — pure function returning one message per violation
src/chains/polygon.ts	Algebra v3 and v2 deployments, multicall
src/chains/zkevm.ts	Algebra v3 and Uniswap-V3-fork deployments, multicall
src/index.ts	Public exports for the new types and lookup
scripts/validate-addresses.ts	Runs the coherence check per chain inside the existing validation loop
vitest.config.ts	Enables type-checking over the test suite
src/__tests__/**	Runtime and type-level coverage for the schema, the lookup, each coherence rule, and the new chain data

Every added field is optional, so existing chain configs and every published export keep their current shape. Every address is stored in EIP-55 checksum form.

Test plan

• pnpm --filter @quickswap-defi/protocol-core test — 323 tests across 22 files pass, no type errors
• pnpm --filter @quickswap-defi/protocol-core build — CJS, ESM and declaration builds succeed
• pnpm --filter @quickswap-defi/protocol-core validate:addresses — 62 addresses validated, coherence check clean