[Extension] Swap to New Token design doc#2868
Conversation
There was a problem hiding this comment.
Pull request overview
Adds a new extension-focused design document describing how to extend the Swap flow to support swapping into classic assets the user doesn’t yet hold by bundling changeTrust into an atomic swap transaction, plus associated UI/Blockaid/telemetry/testing plans (ported and adapted from the already-shipped mobile implementation).
Changes:
- Introduces a detailed “Swap to New Token” extension design doc covering UX, architecture, and implementation plan.
- Specifies destination-token discovery (Popular + verified + search), classic-only filtering, and pick-time Blockaid bulk scanning.
- Defines transaction-building changes (atomic
changeTrust+pathPaymentStrictSend, fee model, quote-freeze + expiry recovery) and outlines testing/telemetry work.
💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
|
PR Preview build is ready: https://github.com/stellar/freighter/releases/tag/untagged-e7a8e96e5813120ce3f6 (SDF collaborators only — install instructions in the release description) |
![chatgpt-codex-connector[bot]](https://avatars.githubusercontent.com/in/1144995?s=60&v=4){kind=small}
There was a problem hiding this comment.
💡 Codex Review
Here are some automated review suggestions for this pull request.
Reviewed commit: 0a133ae6c9
ℹ️ About Codex in GitHub
Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you
- Open a pull request for review
- Mark a draft as ready
- Comment "@codex review".
If Codex has suggestions, it will comment; otherwise it will react with 👍.
Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".
| | **Source picker** | Held balances only | Unchanged in content — same "Swap from" picker, **Your tokens** only ([Figma](https://www.figma.com/design/C3G0a4Gd6RQyplRBppGDsL/Freighter-Extension?node-id=8641-33048)) | | ||
| | **Trustline** | Manual, separate "Add asset" trip | **Automatic** — bundled into the swap as one atomic transaction | | ||
| | **Security** | Only held assets are Blockaid-scanned | **Every** destination candidate (held, popular, search result) is Blockaid-scanned before it is selectable, and the combined transaction XDR is scanned at review | | ||
| | **New-trustline cost** | Not surfaced | A purple **"This will add a trustline to {CODE}"** banner on review + a tappable info sheet explaining the 0.5 XLM reserve ([Figma — review](https://www.figma.com/design/C3G0a4Gd6RQyplRBppGDsL/Freighter-Extension?node-id=8641-34246), [info sheet](https://www.figma.com/design/C3G0a4Gd6RQyplRBppGDsL/Freighter-Extension?node-id=8641-34721)) | |
There was a problem hiding this comment.
We've gotten some h1 reports about only showing CODE when adding an asset so we're moving towards always showing CODE:ISSUER. We should do the same here for consistency
There was a problem hiding this comment.
@piyalbasu do you mean replacing the occurrences of AQUA on the screens below with AQUA:GBNZ...AQUA instead ?
I wonder if adding a Issuer (copy button) GBNZ...AQUA row on the first screen in between the Wallet and Rate rows would suffice for that, so we expose the information for users while keeping the copy clean. What do you think? Also adding @minkyeongshin to the loop here
There was a problem hiding this comment.
Humm well since we have 2 tokens being swapped here I guess we'd need to display the issuer for both tokens so we'd need 2 Issuer lines instead of just 1. I'll start a convo on slack for us to discuss about it.
There was a problem hiding this comment.
There was a problem hiding this comment.
Oh sorry - this is my misunderstanding. I thought we were referring to the Transaction Details view. I think as long as we show the issuer there, we should be good!
Addresses PR review: the clipboard "Paste" button was removed from all extension designs since a programmatic clipboard read needs an extra clipboardRead manifest permission + user opt-in (not worth it on web). Manual paste into the search field still works. Documents the omission as a mobile-vs-extension difference in §2.4. Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
Addresses PR review: the extension supports custom networks (mobile does not), and verified-token lists + stellar.expert exist only for Mainnet/ Testnet. Document that on custom networks the picker gracefully omits the Popular section and search degrades to held-only (held-to-held swaps still work via the network's Horizon). Covered in §3.1 + §2.3. Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
Addresses PR review: isNew was vague. requiresTrustline reads as it is used (when true, bundle a changeTrust op). Renamed everywhere including the telemetry payload field, to be kept in sync with freighter-mobile. Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
|
Closing this PR for now as the design has been approved and I'll use this same branch to implement the feature. |
The DestinationTokenDescriptor.isNew flag was vague. requiresTrustline reads as it is used: when true, the swap bundles a changeTrust op. - Rename DestinationTokenDescriptor.isNew -> requiresTrustline and all reads / literals / comments across SwapScreen + transactionService. - Rename the shouldShowXlmReservePreflight param destinationIsNew -> destinationRequiresTrustline. - Telemetry: the SWAP_DESTINATION_SELECTED payload field isNew -> requiresTrustline (wire-format change; dashboards keyed on isNew must be updated). - Update docs/swap-to-new-token-design.md to match. Keeps freighter-mobile in sync with the extension design doc (stellar/freighter#2868). Swap unit suites green (272 tests). Co-authored-by: Claude Opus 4.8 <noreply@anthropic.com>
No description provided.