Add core-side synthetic destination for swap-to-address

[j0ntz]

Technical Design Document

stealth-send-swap.md

CHANGELOG

Does this branch warrant an entry to the CHANGELOG?

• Yes
• No

Dependencies

none

Description

Asana task

The core half of swap-to-address, which is what lets a swap target a pasted destination instead of a wallet the user holds. EdgeSwapRequest accepts an optional toAddressInfo descriptor as an alternative to toWallet, exactly one of the two required; the core builds a synthetic, bridgified destination wallet from it, backed by the real currencyConfig, so swap plugins receive an EdgeCurrencyWallet unchanged. Nothing Houdini-specific lives here: the same mechanism powers provider-agnostic send-to-any-asset, verified in-app with a ChangeNOW-routed cross-chain send.

Judgement calls, with their alternates:

• Slim descriptor. EdgeSwapToAddressInfo carries only toPluginId, toAddress, and optional toMemos. toPluginId selects the currencyConfig and is not derivable from the request; toAddress is the payload; the destination token comes from the request's own toTokenId. A descriptor also carrying toTokenId was rejected as a two-sources-of-truth hazard.
• Destination memos ride getMemos on the synthetic wallet. For memo-required payout chains such as an XRP destination tag, the descriptor's toMemos is only the GUI-to-core transport; plugins never read the descriptor. The synthetic wallet exposes getMemos() (EdgeSyntheticDestinationWallet), so the plugin-facing mechanism stays wallet-shaped and plugins keep one code path. Plugins reading a tag field off the descriptor was rejected to keep the plugin interface generic. A no-descriptor design is not available: the value has to cross the GUI-core bridge somewhere, and the descriptor is the plain-data channel that crosses yaob cleanly.
• EdgeTxActionSwap.payoutWalletId and EdgeTxSwap.payoutWalletId are both optional. A swap-to-address destination has no payout wallet; payoutAddress carries the destination. Making only the action type optional left a latent inconsistency in EdgeTxSwap. Keeping them required and writing the synthetic://<pluginId> id was rejected: it embeds fake wallet ids in persistent transaction metadata.
• EdgeTxActionSwap.swapType (swapSend, stealthSend, stealthSwapSend) names the send-shaped flows so a UI can title a transaction by the flow the user ran instead of inferring it. These stay swaps to every existing consumer, which a separate actionType would not; absent for a normal wallet-to-wallet swap.
• EdgeSwapRequest.privacy. 'required' restricts a quote to routes that keep the sender unlinkable from the recipient, and a plugin that cannot offer one must decline rather than answer with a transparent route. A quote carries no route type back to the caller, so a silent downgrade would be undetectable; making the caller state its requirement puts the decision where the intent lives.
• EdgeSwapRequestOptions.forceEnabled lets a caller query named plugins the user switched off in their swap settings, because a private send is a send feature that happens to be powered by a swap provider. An explicit disabled entry still wins, so a caller that disables everything except one provider cannot have that restriction defeated.
• Log privacy. Both swap-quote logging paths redact the pasted destination address and the memo values, since a deposit tag can identify the recipient's exchange account.
• The synthetic wallet is released by reference count. It is bridgified, so yaob holds it in the account's object table until something closes it, and the caller reaches it through quote.request.toWallet. One wallet is built per fetchSwapQuotes call and shared by every quote that call returns, so it closes when the last of them closes, and immediately when none survives or all reject. Without that, every quote refresh on a swap-to-address screen left another wallet in the table for the life of the account. Closing it with the first quote was rejected: the other quotes from the same call still carry it. A quote's close releases its share even when the plugin's own close throws.
• EdgeCurrencyConfig.parseUri reaches the plugin's currency tools the same way importKey does, so a caller with no wallet on the destination chain (a send to a pasted address) still gets that chain's own URI parsing, destination tag included. It runs the same post-processing as EdgeCurrencyWallet.parseUri through one shared helper: the account's custom tokens go to the plugin, and a currencyCode in the result is upgraded to a tokenId. EdgeParsedUri.addressTypes lets a chain with several address formats say which getAddresses labels a parsed address matches. Reimplementing URI parsing in the GUI was rejected: it would drift from the plugins that already own each chain's format.

The plugin-selection rule that forceEnabled and disabled encode is a named predicate (isSwapPluginQueryable) rather than an inline condition inside fetchSwapQuotes, with its full truth table under test. The corner that matters is exactly what a stealth send does in one call: every other plugin disabled, this one force-enabled.

Testing. 188 mocha tests pass (1 pending) on the branch rebased onto current master, tsc and eslint clean, verify-repo.sh PASSED. 18 of those tests are new: the yaob bridge-crossing proof covers descriptor-only construction, plugin-faithful reads, memo round-trip through getMemos, and the synthetic wallet surviving the wire format back to the GUI; the plugin-selection truth table covers all eight flag combinations; two more cover the synthetic wallet's release, including a double-close that must not free it twice. In-app, linked into edge-react-gui with the Stealth Send UI: a real cross-chain send-to-address executed on the iOS simulator through this mechanism, deposit broadcast on chain, swap success scene reached.

---

Note

High Risk
Changes swap quoting, bridged object lifetimes, and public swap/URI types used for send and stealth flows; mistakes could leak destinations, leave yaob leaks, or quote wrong providers.

Overview
Adds swap-to-address: fetchSwapQuote / fetchSwapQuotes now accept an EdgeSwapSendRequest (destination plugin, addresses, optional memos) in addition to wallet-to-wallet swaps. The core resolves send requests into a normal EdgeSwapRequest by building a bridgified synthetic destination wallet (makeSyntheticDestinationWallet) backed by the account’s real currencyConfig, so plugins still read payout data from toWallet. One synthetic wallet is shared per quote batch and released when the last wrapped quote closes, including when all quotes fail or a plugin close throws.

Also extends swap quoting with EdgeSwapRequest.privacy?: 'required' (plugins must decline if they cannot offer an unlinkable route) and EdgeSwapRequestOptions.forceEnabled plus isSwapPluginQueryable (explicit disabled still wins over user-off + force-on).

Transaction metadata gains EdgeTxActionSwapSend (swapSend) with validation in cleaners. EdgeCurrencyConfig.parseUri exposes chain URI parsing without a wallet via shared parseCurrencyUri (custom tokens + currencyCode → tokenId upgrade); wallet parseUri delegates to the same helper. EdgeParsedUri.addressTypes is added for multi-format addresses.

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

Test evidence

24613ad Add swap route-privacy and force-enabled request options

agent proof 1216251688512498 03 send to any quote

agent proof 1216251688512498 04 send to any success

[cursor]

Bugbot is paused — on-demand spend limit reached

Bugbot uses usage-based billing for this team and has hit its on-demand spend limit.

A team admin can raise the spend limit in the Cursor dashboard, or wait for the next billing cycle to continue.

[j0ntz]

bugbot run

[cursor]

Stale Bugbot comment from a previous run.

[peachbits]

The synthetic destination wallet is the right seam: plugins receive a normal toWallet and need no changes. The account-facing types are where the design leaks, and the fixes are type-level rather than a rewrite. Three requests, detailed inline and below:

1. Keep EdgeSwapRequest.toWallet required and add a second request shape, EdgeSwapSendRequest, for send-to-address. The core already resolves every request to one with a toWallet before plugins or quote.request see it, so the optionality only exists at this boundary, and the GUI pays for it with requireDestinationWallet in five places.
2. Give send-to-address transactions their own action type (swapSend), written by the plugin at quote time, instead of swapType? stamped by the GUI after broadcast plus payoutWalletId? on two types. The plugin has every input it needs now that privacy is on the request.
3. Add parseUri to EdgeCurrencyConfig, loading tools on demand the way importKey and getTokenDetails already do. That gives the GUI the plugins' own parsers for chains the user holds no wallet on.

privacy: 'required' on the request and forceEnabled on the options are fine as they are.

---

src/types/types.ts:1781 (EdgeCurrencyConfig)

Request: add parseUri to EdgeCurrencyConfig, loading tools on demand through getCurrencyTools the way importKey (line 1810) and getTokenDetails already do on this object.

readonly parseUri: (
  uri: string,
  currencyCode?: string,
  customTokens?: EdgeMetaToken[]
) => Promise<EdgeParsedUri>

Today parseUri exists only on EdgeCurrencyWallet, so a chain the user holds no wallet on has no reachable parser. The GUI PR fills that gap with a hand-written BIP-21/EIP-681 splitter plus a table of provider-supplied regexes, four of which had to be corrected. The plugins already implement all of it: BIP-21, EIP-681 pay- and @chainId, cashaddr and legacy forms, checksums, memos as uniqueIdentifier, amounts in native units. Tools are cached per session, so the cost is one constructor per chain the user pastes for.

Send-to-any is the immediate consumer. Two existing GUI paths could use the same method later, and don't have to now: the payment deep-link handler, which loops loaded wallets and falls back to a five-row scheme table to offer wallet creation, and the scan flow, which can only parse with the scene's wallet.

src/types/types.ts:888 (EdgeParsedUri)

Suggested optional field, so the label source for toAddresses has somewhere to live once currency plugins implement it:

/** Every `getAddresses` label that applies to `publicAddress`, for chains with more than one address format. Absent means `publicAddress` only. */
addressTypes?: string[]

The plugin that validated the address is the one that knows its format: UTXO has verifyAddress and guessAddressTypeFromAddress in its keymanager, Zcash can go by prefix or the SDK's per-type validators. Nothing needs to implement it in this PR; the field lets the send flow drop the Houdini special case later without another core change.

[j0ntz]

All three requests are in: EdgeSwapSendRequest beside a wallet request with a required toWallet, the swapSend action written by the plugin, and EdgeCurrencyConfig.parseUri loading tools on demand. EdgeParsedUri.addressTypes is declared as suggested, with no implementation yet.

[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 default 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 a32a644. Configure here.}