# Payment-critical dependency pin policy

AgentPay MCP treats crypto verifier and signing dependencies as payment-critical
infrastructure. A floating semver range is not acceptable when a fresh install
can change the code path that parses a 402 challenge, derives an account, signs
a payment, verifies a receipt, or maps a chain.

## Current pin

- `viem`: pinned exactly to `2.57.4`
- `package.json` dependency: `"viem": "2.57.4"`
- root npm override: `"viem": "2.57.4"`
- reason: `agentwallet-sdk` `7.0.0` ships `viem` `2.57.4`. The pin replaces
  `2.56.0` so the x402 verifier path and the SDK share one install, and so
  the `ws` advisory that affected older `viem` trees stays cleared. Pins age:
  when the security gate flags a transitive advisory, bump the pin through
  the upgrade process below rather than relaxing it to a range.

## Libraries covered by this policy

Pin exactly, or document an explicit hard override, for any package that
touches:

- wallet/account derivation
- signature creation or verification
- x402 payment-required parsing
- receipt, transaction, or payment envelope validation
- chain metadata used to decide whether a payment can be signed
- crypto hash, curve, address, or ABI encoding paths

Today that includes `viem` and its crypto import surface. If AgentPay adds a
direct dependency on `@noble/*`, `@scure/*`, `ox`, an x402 SDK package, or a
facilitator client, that dependency must be reviewed under this policy before
release.

## Release gate

Before publishing a package that changes x402 payment paths or crypto
dependencies, run:

```bash
npm run build
npm run smoke:clean-install
```

The clean-install smoke creates a fresh temporary consumer project, installs the
packed AgentPay MCP tarball, imports `viem`, `viem/accounts`, `viem/chains`,
AgentPay's packaged `x402_pay` tool, and AgentPay's wallet client utility, then
confirms the resolved `viem` version is exactly `2.57.4`.

A release must fail if:

- the root package uses `^`, `~`, `>=`, `latest`, or any non-exact range for
  `viem`
- the root override does not match the dependency pin
- a clean install resolves the x402 verifier path to a different `viem` version
- packaged AgentPay x402 imports fail in a fresh consumer project
- a payment path silently falls back to an unsupported chain or parser

## Upgrade process

1. Open a dependency-pin issue or PR explaining the market or security signal.
2. Change the exact dependency and override together.
3. Refresh `package-lock.json`.
4. Run typecheck, tests, build, pack dry-run, and clean-install smoke.
5. Preserve proof under `ops/proofs/` before publishing.
6. Publish only after the proof shows the same exact dependency version in a
   clean consumer install.

Do not relax this policy for convenience. Payment libraries can break buyer
agents without changing AgentPay source code, so deterministic installs are part
of the product contract.