Repository Public
1# Adding a swap provider (contract for implementers)23SP Wallet moves real funds. In this phase a provider adapter does **price discovery only**: it returns real quotes from the4provider's public API, strictly validated, and documents how execution would work. It never builds, signs or sends anything.56## Read first7- `packages/swap/src/types.ts` — `SwapProvider`, `SwapQuote`, `RouteStep`, `FeeItem`, `Executability`, `ProviderContext`.8- `packages/swap/src/aggregator.ts` (`checkQuote`: what gets a quote dropped), `risk.ts`, `router.ts`, `graph.ts`.9- `packages/swap/test/router.test.ts` — how providers are exercised.10- `packages/core/src/networks.ts` and `tokens.ts` — the wallet's verified registry. **Only assets in that registry may appear in a11 quote**; resolve with `resolveAsset()` and never invent decimals or addresses.1213## Deliver141. `packages/swap/src/providers/<id>.ts` exporting `create<Id>Provider(env): SwapProvider`:15 - `capabilities()`: the wallet network ids the provider really serves (checked against its current official docs/API, not16 assumed), `needsKey`/`configured`, link to the docs you used. API base URL and version are constants in the file (pinned).17 - `supportsPair()`: local, no network.18 - `quote()`: one HTTP round (use `ctx.http`, pass `ctx.signal`), response parsed with a **zod schema**; anything unexpected19 throws `ProviderError(id, 'schema', …)`. Map amounts with `BigInt` from strings — never through a JS number. Fill every20 `SwapQuote` field from the provider's answer: `amountOut`, `minAmountOut` (apply the requested slippage exactly as the21 provider defines it; if the provider returns its own guaranteed minimum use that), every fee it reports as a `FeeItem`22 with the right `includedInOutput`, `estimatedSeconds` (null when the provider gives none), `priceImpactBps` (null when23 unknown), `expiresAt` (the provider's validity, else a conservative 30 s), `steps` with the contracts/programs/vaults24 the provider names, `atomic`, `refundable`, and `raw` = the validated provider payload.25 - `executability`: `{ class: 'quote_only', reason }` unless you can show the signer could rebuild and verify every26 value-moving field itself (then say exactly how in the dossier); aggregator calldata is `'opaque'` at best.27 - "No route" is an empty array; provider failures throw. Never fabricate a route, a rate or a duration.282. Register the factory in `packages/swap/src/providers/index.ts` (`createProviders`).293. Tests in `packages/swap/test/<id>.test.ts`, with **real responses recorded from the live API** saved under30 `packages/swap/test/fixtures/<id>/` (several pairs, a no-route case, an error case): exact field mapping, decimals,31 slippage arithmetic, fee classification, schema rejection of malformed/hostile answers (wrong token address, float or32 negative amounts, missing fields, output for another recipient), timeout/abort handling.334. `scripts/smoke-swap-<id>.mts`: live, read-only — prints real quotes for at least four realistic pairs/amounts (small, e.g.34 20–50 USD worth) with latency, and compares the quoted rate with a market reference (CoinGecko) to within a sane band.35 Include the output in your report.365. `docs/swap/providers/<id>.md` — execution dossier for the next phase, from the provider's official documentation:37 transaction shape per chain, the exact contracts/programs/vaults involved **with their official source URLs**, token38 approvals needed, how the recipient and minimum output are encoded (and therefore what an isolated signer could verify39 by itself), status/tracking API, refund behaviour, fees, rate limits, key requirements, terms-of-use constraints.4041## Rules42- Keyless public endpoints only. If the provider requires a key, implement the adapter against its documented schema, test it43 with documented examples, mark it `needsKey`, and say so — do not sign up for anything.44- No new runtime dependency unless unavoidable (zod is available). Pin exact versions.45- `pnpm install`, `pnpm typecheck`, `npx vitest run` must pass. Do not touch the signer, the API or the web app.46- Branch from local `main` (`git checkout -b v2-<id> main`), commit there, do not push, do not deploy.47- Report: networks/pairs actually served, measured latency, what is and is not verified, anything the contract does not fit.48