feat(backend): close-account REST API (plan/transactions/submit) + verifiable intent#34
Merged
Conversation
Server-built unsigned XDR for account closes, consumed by both the LumenWipe front-end and third parties. Stateless with the chain as source of truth; /plan returns the full preview, /transactions returns ordered unsigned txs with a verifiable intent. Covers per-asset decisions, advisory quotes, multi-tx (all vs frontier), errors/blockers/drift, and how it maps onto the current pure tx-builder.
Bite-sized TDD plan for the /v1/{network}/close/* endpoints and the pure intent
serializer, reusing the existing tx-builder. Scopes out the client refactor and
the DeFi frontier path as follow-ups.
Thin handler over getAccountState + buildPlan + deriveDecisionPoints. Best-effort convertibility via path finding; verified end-to-end by the testnet e2e.
Builds one fused close transaction (direct destinations, phase 1) with a verifiable intent, mirroring the existing fused-close assembly. Mediator/claimable/oversized closes surface as typed errors. Verified end-to-end by the testnet e2e.
Wraps submitAndWait; accepts a signed envelope only, never a secret. Maps signature, timeout, malformed-XDR, and upstream failures to typed error responses.
Drives plan -> transactions -> local sign -> submit and asserts the source account is merged away on-chain. Adds a shared readAccountState helper (live-rescan fallback, parity with the account route) used by both handlers.
|
Preview deployment for your docs. Learn more about Mintlify Previews.
💡 Tip: Enable Workflows to automatically generate PRs for you. |
|
The latest updates on your projects. Learn more about Vercel for GitHub.
|
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
POST /v1/{network}/close/plan,POST /v1/{network}/close/transactions,POST /v1/{network}/submit.docs/plans/2026-06-21-close-account-api-design.md,docs/plans/2026-06-21-close-account-api-plan.md.What's here
types/close-api.ts— the plan / transaction / decision / intent contract.lib/stellar/intent/serialize.ts— pure XDR→intent serializer (normalized, verifiable). This is the core the future SDKverify()reuses.lib/close-api/decisions.ts— derive/resolve per-asset decision points (convert_to_xlmvsreturn_to_issuer).lib/close-api/plan-response.ts— mapbuildPlanto the API response, stableplanHash, execution breakdown.lib/close-api/build-transactions.ts— assemble the fused close (reuses the existing puretx-builder) and attach the verifiable intent.lib/close-api/read-account.ts— shared live-rescan read (parity with the account route).app/api/v1/[network]/close/{plan,transactions}andapp/api/v1/[network]/submit.Trust model
Each returned transaction carries a structured
intent(ops, merge destination, payment destinations,minXlmFromConversions). It is present from day one so the SDK can later re-decode the raw XDR and refuse to sign anything that doesn't match the declared intent and the user's decisions. The backend builds bytes but is not a blind-trust point.Phase-1 scope (follow-ups documented in the design)
mediator_destination_unsupported,claimable_balances_unsupported,too_many_operations).verify(), the DeFifrontiermulti-call path, and auth/rate-limiting are follow-ups.Verification
bun type-check+bun lintclean; 238/238 unit tests (intent serializer, decisions, plan-response mapper).tests/e2e/close-api.spec.ts: plan → transactions → local sign → submit → asserts the source is merged away on-chain. Passes (~26s).fast-path-close,single-tx-flow) timing out on on-chain confirmation during a congested 16.8m testnet run. They exercise the existing browser flow, which this PR does not touch (additive API files only). Recommend a CI re-run.Notes
main; this branch is rebased on top.Touches transaction construction (
lib/close-api/build-transactions.ts, reusestx-builder). PerCLAUDE.md, flagging for closer review. The puretx-builderis unchanged and still has no network access; the API only returns unsigned XDR.