Ramps deep link entry and affiliate provider priority

[j0ntz]

Technical Design Document

ramps-deeplink-provider-priority.md

Description

Gives the ramps buy/sell flow a deep link entry point and provider priority.

Part A, link-scoped flow access. New edge://buy[/<providerId>[/<paymentType>]] and edge://sell[...] links (plus the https://deep.edge.app/... form) open RampCreateScene with an optional provider and payment type pinned to the top of the quote results. The pin lives in navigation params only: no saveAccountReferral call, and ?af= attribution keeps its existing independent behavior. It is scoped to the flow the link opened, so stepping to the option list and back keeps it while leaving the tab clears it. A pin that matches no quote logs and falls back to the normal ordering, which is what /buy/moonpay/cashapp does while the info server rampQuoteFilter disables Cash App. An unrecognized payment type in a link is dropped rather than failing the link, so a stale partner URL still opens the flow.

Part B, affiliate provider priority. useRampPreferredProviders reads the existing promoCards2 pluginPromotions.preferProviders through filterInfoCards (not getDisplayInfoCards), matched against accountReferral. Reading the ungated path is what makes silent priority config work: a card with localeMessages: {} and no ctaButton never renders in the carousel but still carries its behavior payload. No info server changes.

Both inputs feed one comparator (compareRampQuotes) shared by useRampQuotes and RampSelectOptionScene, so the payment-type group order and the provider order inside each group agree. Anything that makes a claim about the RATE stays out of that ordering: the select scene's "Best Rate" badge and the create scene's exchange rate (which also feeds the light-account purchase limit) both go through getBestRateRampQuote, so a pinned link changes which option the user lands on first, never what the app reports as the market rate.

Two product decisions shape the ordering rules. The "Best Rate" badge is display-honest: it renders only beside the number it describes, so under a provider pin or an active affiliate preference the badge is deliberately absent rather than relocated (a marker pointing at a competitor works against the promotion the session exists to deliver). And the pins and preferences outrank the has-amounts tier for both links and affiliate configs: an intentional promotion wins outright, so edge://buy/libertyx visibly surfaces LibertyX's amount-less placeholder card at the top, while an unpreferred placeholder still sinks below priced quotes.

The design doc above carries both rules with worked examples: section 5.6 and decision 10.8 for the badge, decision 10.7 for the ordering tier.

The design doc above carries the paste-ready CouchDB promoCards2 blocks and the partner link instructions.

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

CHANGELOG

Does this branch warrant an entry to the CHANGELOG?

• Yes
• No

Dependencies

none

Requirements

If you have made any visual changes to the GUI. Make sure you have:

• Tested on iOS device
• Tested on Android device
• Tested on small-screen device (iPod Touch)
• Tested on large-screen device (tablet)

---

Note

Medium Risk
Touches buy/sell quote ordering and deep-link navigation for a commercially sensitive flow, but only reorders results and does not change quote fetching, payments, or auth.

Overview
Adds deep-link entry into the ramps buy/sell flow via edge://buy[/<providerId>[/<paymentType>]] and edge://sell[...] (plus https://deep.edge.app equivalents). Links can optionally pin a provider and payment type to the top of quote results for that visit only; pins live in navigation params, clear on tab blur, and degrade gracefully when nothing matches.

Also adds affiliate provider priority from existing promoCards2 pluginPromotions, via a new useRampPreferredProviders hook that reads silent (non-display) cards. Deep-link pins outrank affiliate preferences.

Both inputs feed a shared compareRampQuotes comparator used by useRampQuotes and the option list. Rate claims stay honest: the create scene exchange rate and the "Best Rate" badge use getBestRateRampQuote so promotions change landing order, not reported market rates. Under a promotion the badge is deliberately absent rather than pointing at a competitor.

^{Reviewed by Cursor Bugbot for commit 6db2b61. Bugbot is set up for automated code reviews on this repo. Configure here.}

[j0ntz]

📸 Test evidence

buy deeplink cold start

venmo pinned first

best rate badge on true best

cashapp graceful fallback

affiliate priority paybis first

unaffiliated ordering unchanged

Captured by the agent's in-app test run (build-and-test).

[chatgpt-codex-connector]

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

[j0ntz]

📸 Test evidence (after fix)

create scene shows true best rate

venmo still pinned after fix

Captured by the agent's in-app test run (build-and-test).

[j0ntz]

📸 Test evidence (pin no longer outlives the visit)

pin cleared on later visit

Captured by the agent's in-app test run (build-and-test).

[j0ntz]

📸 Test evidence (pin lifetime)

pin kept on in flow back

pin cleared after leaving tab

Captured by the agent's in-app test run (build-and-test).

[j0ntz]

📸🪓 Test evidence (after fix): option-list pin now clears on tab leave

🪓 Hack-forced evidence: the fix commit was stashed to capture the pre-fix frame; restored before committing. Temporary uncommitted edit, reverted before commit; the marked frames prove the rendering, not the trigger.

pin active after fix

pin cleared after tab leave

🪓 HACK-FORCED: pre fix pin survives tab leave

tdd mermaid renders on github

Captured by the agent's in-app test run (build-and-test).

[j0ntz]

📸 Test evidence: followup test-gap closure (promo priority, expiry, af attribution, warm start, sell)

control no promo order

promo code activated

paybis first via activepromotions

future enddate pin applies

expired card reverts order

expired card prunes activepromotions

af attribution moonpay first

visible promo card cta

cta warm pin venmo first

warm openurl delivery

no af no referral write

sell moonpay pinned

Captured by the agent's in-app test run (build-and-test).

[j0ntz]

Non-visual evidence from the same run, to go with the screenshots above.

Section 6 JSON blocks against the real cleaners. Both blocks were extracted from the committed doc and run through edge-info-server's asInfoCard and asPromoCards2 (asHealingArray(asInfoCard)) in node, against edge-info-server@3.12.0 from the gui's own node_modules (byte-identical asInfoCard to the repo checkout):

PASS  asInfoCard  6.1 visible card with a deep link CTA
      promoId="moonpay" pluginPromotions=[{"pluginType":"buy","preferProviders":["moonpay"]}]
      round-trip stable: yes
PASS  asInfoCard  6.2 silent priority card
      promoId="moonpay" pluginPromotions=[{"pluginType":"buy",...},{"pluginType":"sell",...}]
      localeMessages keys=[] ctaButton=undefined
      round-trip stable: yes
PASS  asPromoCards2 (asHealingArray): 2 in -> 2 out (0 silently dropped required)
PASS  negative control: 3 in (1 missing "background") -> 2 out (drop expected)

The negative control matters because the healing array drops a malformed card silently; without it a green result proves nothing.

AC2, now runtime rather than code reading. A temporary uncommitted marker inside saveAccountReferral wrote one line per call into the app container, and CreationReason.json was hashed before and after:

Launch	saveAccountReferral calls	installerId / activePromotions	CreationReason.json
baseline, no deep link	1	undefined / []	unchanged
edge://buy/moonpay/venmo, driven to the option list	1	undefined / []	unchanged (same sha1)
https://deep.edge.app/buy/moonpay/cashapp?af=moonpay	1	undefined / ["moonpay"]	unchanged

So the pin path adds no referral write at all, while the af form does exactly one, and it lands in activePromotions rather than installerId because the referral server 404s the code. Both hacks were reverted; git status is clean of them.

One caveat worth recording, not a defect in this PR. The "Best Rate" badge is attached to getBestRateRampQuote(allQuotes), while each card renders its payment-type group's first quote. When the pinned provider is not the best-rate provider, the best-rate quote stops leading any group and the badge renders nowhere rather than moving. Visible in the Paybis-pinned screenshot. The design doc's testing section now says so.

Testing was done on a throwaway account rather than edge-funds for everything that writes account-synced state (activePromotions, attribution), so no shared roster account was dirtied. The sell drive used edge-funds because it needs a balance.

[claude]

Claude Code Review

Claude Code Review is paused for this repository. To reconnect it, an admin of this repository's GitHub organization (or the account owner, for personal repositories) who can also manage your Claude organization's Code Review settings needs to re-link GitHub in Code Review settings. This is a one-time step.

_{Tip: disable this comment in your organization's Code Review settings.}

[peachbits]

Two notes on the ordering precedence in compareRampQuotes (the group-sort comment and the amounts-tier comment below are the same root cause: the priority ranks are compared before everything else), plus one nit on the debug-log effect.

[j0ntz]

📸🪓 Test evidence (review fixes)

🪓 Hack-forced evidence: temporarily filtered ACH quotes out of RampSelectOptionScene so the globally-best quote landed inside a multi-provider group (live quotes put it in the single-provider ACH group, where a pin cannot displace it); frame 41 additionally restores the pre-fix isBestOption rule. Temporary uncommitted edit, reverted before commit; the marked frames prove the rendering, not the trigger.

unpinned control badge on ach

🪓 HACK-FORCED: before fix no badge anywhere

🪓 HACK-FORCED: after fix badge on group holding best

paybis pinned badge on ach

pin cleared after tab leave

Captured by the agent's in-app test run (build-and-test).

[peachbits]

Both fixes look right — I checked that the .some() scope badges exactly one card (each group is keyed by quote.paymentType and the predicate requires paymentType equality, so only the best quote's own group can match), and the reordered comparator is still a valid total order. Two follow-ups below: one small thing the badge fix picked up, and a question about the cost of the tier reorder.

[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 0b8eb38. Configure here.}

[j0ntz]

📸 Test evidence (product decision round: display-honest badge, promotion outranks has-amounts)

libertyx pinned placeholder top

libertyx tap opens external flow

BTC list, badge on the displayed best quote (ACH · Paybis). ACH is single-provider for BTC, so a provider pin cannot displace this badge; the displacement case is frame "before fix no badge anywhere" in the previous evidence comment, which ran this exact display-honest rule

Captured by the agent's in-app test run (build-and-test).

[claude]

Claude Code Review

Claude Code Review is paused for this repository. To reconnect it, an admin of this repository's GitHub organization (or the account owner, for personal repositories) who can also manage your Claude organization's Code Review settings needs to re-link GitHub in Code Review settings. This is a one-time step.

_{Tip: disable this comment in your organization's Code Review settings.}