[devbackend513-ux]

Summary

Adds four end-to-end walkthroughs under testnet/examples/ for the integration paths that integrators actually build against. Each one is written from the contract source, not the API summary, so it covers the behaviour you cannot infer from signatures alone.

Doc	Path covered
signed-sweep-walkthrough.md	SweepController::execute_sweep() — the primary sweep path, and the only one with real Ed25519 verification
gas-free-claim-walkthrough.md	SweepController::claim() — recipient signs a Soroban auth entry, relayer submits
multi-asset-sweep.md	Multi-asset record_payment → sweep, and reading SweepExecutedMulti.payments
expiry-and-recovery.md	Short-expiry account → lapse → expire()/recover() → recovery verification

Why these need to exist as prose

A few behaviours in this codebase are actively misleading if you only read the function signatures:

• EphemeralAccount::sweep() takes an auth_signature and ignores it. All three walkthroughs route through SweepController and say why, since this is the easiest way to convince yourself signature checking works when it does not. This is called out in more detail in testnet/security/unverified-signature-path-warning.md: a testnet-facing callout that EphemeralAccount::sweep()'s signature isn't checked #651.
• The signed message commits to nothing about the payment set. A signature at nonce 7 authorises whatever account state exists at nonce 7. Documented explicitly in the multi-asset doc so nobody treats a signed sweep as approval of a specific amount.
• SweepCompleted.amount is a sum across assets and is not a meaningful monetary figure. The walkthroughs point at SweepExecutedMulti.payments instead and cover the i128 → string decoding trap.
• The nonce is shared between execute_sweep() and claim(), and on the shared testnet controller it is consumed by other integrators too — so the race is real, not theoretical.
• AccountExpired does not move tokens in the current implementation. expire()/recover() set state and emit events; there is no TokenClient::transfer() anywhere in ephemeral_account. The expiry doc has a dedicated "What the event does and does not prove" section, because treating that event as a funds-received signal is the most damaging misreading available today.
• Expiry is >=, not >, and is ledger-based, so the boundary ledger is already expired.
• record_payment() has no status or expiry guard — entries can still be appended to an account that can no longer be swept.

Scope

• Documentation only. No contract, script, or tool changes.
• tools/sweep-signer is referenced contextually and not modified, per testnet/examples/signed-sweep-walkthrough.md: worked example of constructing and submitting a signed sweep via SweepController #634's constraint.
• Forward-references two sibling docs from other issues in this batch (testnet/examples/create-and-fund-ephemeral-account.md, testnet/runbooks/expired-account-recovery-check.md) and flags the fallback path inline where they may not be present yet, so no doc is a dead end on its own.
• Error codes, event topics, and on-chain ordering are all checked against contracts/ephemeral_account/src/lib.rs, contracts/sweep_controller/src/, and contracts/shared/src/types.rs rather than restated from docs/api-reference.md.

Closes #634
Closes #635
Closes #636
Closes #637

[drips-wave]

@devbackend513-ux 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