Harden the first-time swap provider implementation

[j0ntz]

CHANGELOG

Does this branch warrant an entry to the CHANGELOG?

• Yes
• No

Dependencies

none

Description

Asana: https://app.asana.com/0/1215088146871429/1217131617432935

Collects the review feedback from recent swap provider integrations, finds
what actually recurs, and fixes it at the source.

Evidence base: 80 review threads across the 8 most recent provider PRs
(#481 SimpleSwap,
#480 swaps.xyz,
#475 Swapter,
#471 Changelly,
#469 +
#462 HoudiniSwap,
#457 NYM,
#464 Xgram), from
cursor[bot], the Cursor Security Reviewer, chatgpt-codex-connector, and
human reviewers.

What the record shows

Nearly every recurring finding traces back to one file: src/swap/central/template.ts,
which docs/CREATING_AN_EXCHANGE_PLUGIN.md tells every new integration to copy
as its base. The template omits or mis-models the exact constructs reviewers then
ask for, so each new plugin inherits the gap and rediscovers the finding.

Template gap	Findings it produced
No getMaxSwappable, so no max-quote model at all	#480, #475, #471, #469, #457 (5 of 7)
No checkInvalidTokenIds call	#480, #469, #457
denominationToNative results never rounded to integers	#475, #462
Untyped catch (error)	#481, #475, #471, #457
Provider amounts drive the spend with no bound vs the request	#480 (x3, security)
depositExtraId: asOptional(asString) drops numeric memos; "" becomes an empty memo	#475 (High, fund-loss class)
isEstimate: false hardcoded	#469
Limits compared against the echoed quote amount, not the request	#457

The max-quote probe is by far the densest site. getMaxSwappable invokes the
plugin's quote function with the raw pre-fee balance, which is not discoverable
from the interface, so three separate PRs hand-rolled the same three fixes
independently: don't create an order in the probe, set skipChecks: true, and
clamp rather than throw above-limit.

Worth noting the template is already treated as the contract. On #475 a security
finding about logging was answered by citing what the template prescribes.

Changes

src/swap/central/template.ts now models each construct, with the reasoning
inline, since comments are what survive a copy. It models a real two-step
provider (getQuote prices, createOrder commits) so the max probe genuinely
creates nothing, adds fetchProbeOrder + getMaxSwappable with enforceMax and
skipChecks, calls checkInvalidTokenIds, rounds every provider amount to whole
atomic units (up for a floor, down for a ceiling), bounds the provider's source
amount by the requested amount before it becomes a signed spend, cleans memos
with asOptionalBlank(asNumberString), derives isEstimate, and enforces limits
against request.nativeAmount on the side the user pinned.

test/template.test.ts is new. Nothing exercised the template before, since
it is deliberately unregistered. Each case corresponds to a defect that reached
review on a shipped PR.

AGENTS.md and .cursor/BUGBOT.md are new. AGENTS.md indexes the
existing docs plus the two facts that are not cheaply discoverable: plugins run
inside edge-core-js's WebView where Metro's debugger cannot reach, and Edge
amounts are integer atomic units while provider APIs speak decimals. BUGBOT.md
records the conventions these reviews settled, including the two areas where
automated review has been least reliable here (chain identity claims, and the
template's prescribed error-body logging).

docs/CREATING_AN_EXCHANGE_PLUGIN.md gains the max-quote section it never
had, deeper amount and error-handling guidance, and closes with a pre-PR
checklist where every item is traceable to a finding on a shipped integration.

Scope note

getMaxSwappable's signature is unchanged and no shipped plugin is touched.
Giving the framework a first-class probe signal would be the better long-term
fix, but it is a migration across 12 live providers, so it is recorded as a
follow-up rather than bundled here.

Testing

npm run verify passes: prepare (incl. tsc), eslint, and mocha. Full suite is
74 passing, 18 of them new. Coverage of src/swap/central/template.ts is 89%
statements, 84% branch.

The new suite was checked for discriminating power rather than just green:
swapping master's template back in fails 13 of the 16 cases that existed at
that point. The ones that still pass cover behavior the old template already had
right (error ranking by priority, building orderUri from a plugin constant, and
the fixed-rate half of the isEstimate pair).

That check kept earning its keep. It caught two of my own tests asserting nothing
useful (the memo cases only checked pluginId), and reviewing the diff surfaced
a bug I had introduced where the limit-error branch read the amount field by
below-vs-above instead of by the pinned side. Bugbot then caught the biggest one:
the template claimed a quote/order split it did not have, because
asTemplateQuote required orderId and depositAddress. That is fixed at the
root (separate asTemplateQuote / asTemplateOrder, one createOrder call),
and the probe test now asserts the order endpoint was hit exactly once rather
than counting total requests.

No app-level testing applies, and that is provable rather than assumed: the built
dist/edge-exchange-plugins.js is byte-for-byte identical between this branch
and master (1aa17692cf...), because template.ts is unregistered and the rest
of the branch is docs and tests. An in-app drive would execute master's bytes.

[chatgpt-codex-connector]

You have reached your Codex usage limits for code reviews. You can see your limits in the Codex usage dashboard.

[cursor]

Cursor Bugbot has reviewed your changes using high effort and found 1 potential issue.

^{❌ Bugbot Autofix is OFF. To automatically fix reported issues with cloud agents, enable autofix in the Cursor dashboard.}

^{Reviewed by Cursor Bugbot for commit 07f5ce4. Configure here.}