feat: SEP-8 client for permissioned assets

[Ugasutun]

Closes #736

Summary

Adds a SEP-8 client to the SDK so Veil can support permissioned assets (auth_required = true) like BENJI today and tokenized equities/DTCC assets expected on Stellar from H1 2027. The wallet submits transactions to the issuer's approval server, handles all five SEP-8 outcomes, and opens the issuer's own KYC/approval flow in-browser — Veil never touches or stores identity data.

What changed

• SDK: SEP-8 client (new module)

  • submit() posts the transaction to the issuer's approval server per SEP-8.
  • Handles all five outcomes explicitly:
    • success — approved tx returned, ready to submit to the network
    • revised — issuer returned a modified transaction
    • pending — issuer needs more time; surfaces retry/timeout guidance
    • action_required — issuer returns a URL for the user to complete out-of-band (KYC, etc.)
    • rejected — surfaces the issuer's own rejection message verbatim, no reinterpretation
  • Local re-verification of revised transactions: before the user is ever prompted to sign, the client diffs the revised transaction against the original intent (same asset, same approximate amount/destination, no unexpected operations added) and rejects anything that doesn't check out. The user is never asked to sign blind.

• Wallet UI

  • An asset with auth_required = true and no existing authorized trustline shows "Requires approval from {issuer}" instead of a normal send/receive flow.
  • action_required opens the issuer's approval URL in the system/in-app browser. Veil passes the user to that flow and collects nothing — no form fields, no identity data, no KYC payload ever touches Veil's code or storage.
  • Approval state (pending/approved/rejected) is reflected in the asset row so the user isn't left guessing.

• Docs (frontend/docs)

  • New page documenting the SEP-8 flow as implemented, the five outcomes, the re-verification step on revised, and the explicit "Veil collects nothing" boundary around the issuer's approval server.

• Test suite

  • Testnet regulated asset (auth_required = true) added as a fixture, used to exercise the real approval-server round trip, not just mocks.

How it works

1. Wallet detects auth_required on the asset's issuer account and routes to the SEP-8 flow instead of a normal trustline/send flow.
2. SDK submits the transaction to the issuer's /transaction approval endpoint.
3. Response outcome branches:
   • success → submit to network as-is
   • revised → re-verify locally against original intent → only then prompt for signature
   • pending → show status, poll/retry per issuer guidance
   • action_required → open issuer URL in browser, wallet does not participate in that flow
   • rejected → show issuer's message, no retry offered
4. Nothing from the approval server's identity/KYC exchange is persisted or logged by Veil.

Testing

• success outcome — test asset approves cleanly, tx lands on testnet
• revised outcome — issuer returns modified tx, local re-verification passes, user prompted to sign, tx lands
• revised outcome, tampered — modified tx altered beyond acceptable diff (e.g. destination changed) → client rejects before signing prompt, regression test for this
• pending outcome — status surfaced correctly, retry/poll behavior tested
• action_required outcome — approval URL opens in browser, wallet state updates correctly on return
• rejected outcome — issuer's rejection message surfaced verbatim in UI
• Confirm no network calls or storage writes from Veil contain identity/KYC fields at any point in the flow
• Docs reviewed for accuracy against actual implementation

Notes / open questions

• Testnet regulated asset — confirm which issuer/asset we're using as the fixture (BENJI testnet equivalent, or a purpose-built test issuer?)
• revised re-verification rules (what counts as an acceptable diff vs. a rejection) should probably be documented explicitly in the SDK code, not just implied — worth a comment block or spec reference
• action_required UX: should Veil poll for approval completion after the browser flow returns, or require a manual "check status" action?

[vercel]

Someone is attempting to deploy a commit to the miracle656's projects Team on Vercel.

A member of the Team first needs to authorize it.

[drips-wave]

@Ugasutun Great news! 🎉 Based on an automated assessment of this PR, the linked Wave issue(s) no longer count against your application limits.

You can now already apply to more issues while waiting for a review of this PR. Keep up the great work! 🚀

Learn more about application limits

[Miracle656]

Holding review on this one briefly — it's part of an accumulating stack with #873, #877, #881 and #883, and I've left the details on #873. Short version: these four each carry the ones before them, so I'll review and merge in the order #873 → #877 → #881 → #883 (each shrinking as the one below lands) unless you'd rather re-base them onto each other. There's also ~2,000 lines of process documentation riding along in all four that I've asked to have dropped. The code itself looks like real work — this is about the packaging, not the content.

[Miracle656]

Merged — along with #873 and #877, bottom-up, so all three closed their own issues (#722, #732, #736). That ordering was deliberate: this PR's body said Closes #736 only, so merging it on its own would have landed #722's and #732's code silently and left those two PRs as empty shells that never closed their issues. You'd have been paid for one issue instead of three.

#883 is the one still open. Now that the three below it have landed, its diff should collapse to just the cost-basis work (costBasis.ts, costBasisTracker.ts, YieldDisplay.tsx and the three web pages). It's currently conflicting — a rebase onto main should shrink it to roughly its real size.

What I changed on the way in

verifyRevisedTransaction is rewritten. This is the part worth reading, because the rest of the SEP-8 client is good and this one function had the whole weight on it.

SEP-8's revised outcome means the issuer's server hands back a transaction it has modified, for your user to sign. Your function compared operation types, and your own comment said as much: // a full implementation would compare operation details. Two things followed:

1. A revision that kept the operation type but changed the destination or the amount came back as safe to sign.
2. The standard SEP-8 revision — the payment sandwiched between setTrustLineFlags calls that authorise and then de-authorise the destination — was refused, because inserting an operation at the front moves the payment from index 0 to index 1 and the comparison was index-aligned. The feature would have failed closed on every real revision.

Neither was visible, and that part isn't really your fault — it's a test-design trap worth knowing about. All five tests asserted false, including the one named 'should accept identical transactions', because mockTxXdr isn't a parseable envelope. Your own comment flagged it: "mockTxXdr is not a valid XDR, so we expect false." Every case passed on the fail-closed path, so the comparison logic never ran once and both bugs were invisible behind a green suite.

The rule now is the one the spec actually states: the server may add operations, so every original operation must survive in the same relative order, byte for byte, matched as a subsequence. Byte equality covers destination, amount, asset and per-operation source at once, and won't drift as new operation types appear. Source account and memo are compared too — a memo picks the crediting account at an exchange, so changing it redirects funds without touching an operation. The fee is deliberately not compared, since more operations legitimately cost more.

Tests now build real transactions. One gotcha for next time: Keypair.random() throws under jest (no crypto randomness in that environment), which makes the suite fail at import and run zero tests. I used StrKey.encodeEd25519PublicKey(Buffer.alloc(32, n)) for deterministic valid addresses instead.

I verified it the way round that matters: restoring your original function under the new tests fails 4 — the sandwich, a bare destination swap, a changed amount, and reordering — and passes 44 with the rewrite.

Two small fixes, both of which were breaking the mobile typecheck: RegulatedAssetApproval.tsx imported the SDK as '../../sdk', which resolves to frontend/sdk and doesn't exist (the alias is @veil/sdk), and it used colors.text, which isn't on ThemeColors (textPrimary).

Two conflicts resolved to main's side, app/swap.tsx and lib/sdexSwap.ts: this branch carried #877's pre-review versions, including a per-module issuer table whose mainnet USDY address fails the StrKey checksum. The verified Ondo issuer is in ASSET_REGISTRY; sdexSwap.ts is now byte-identical to main.

The eight process-documentation files were dropped while landing #873/#877 and stay dropped — about 3,245 lines that were riding along in all four PRs.

One practical thing

#873's branch was main on your fork. Now that it's merged you'll want to move future work onto named branches, or syncing gets painful. And if you work several issues in one area, basing each branch on the previous one keeps the diffs independently reviewable — this stack was four genuinely separate features, but because none was based on the one below it, #881 showed +7,701 lines when its own contribution was about 1,850.

Verified on merge: sdk 28 suites / 344 tests, mobile 87 suites / 1036 tests, both typechecks clean.