Docs/stellar tx simulation

[baedboibidex-cmyk]

PR Message: Stellar transaction simulation guide (#39)

Summary

Adds guides/stellar-tx-simulation.mdx — a complete guide for using Soroban simulateTransaction as a pre-flight check before signing and submitting stealth payment transactions.

What changed

• ** New page:** guides/stellar-tx-simulation.mdx covering:
  • What simulation returns (footprint, resource estimates, return values, events, fees, errors)
  • When to simulate (always for Soroban contract calls; especially before multisig or offline signing)
  • prepareTransaction SDK helper — the standard path with automatic simulation
  • Raw simulateTransaction RPC patterns for full result inspection
  • Decoding return values (scValToNative), events (DiagnosticEvent XDR), and fee breakdowns
  • Handling simulation failures: decoding contract errors, actionable user-facing messages
  • End-to-end worked example: simulating a stealth-announcer announcement on futurenet
• ** docs.json** — page registered under Guides → Operations
• ** sdk/chains/stellar.mdx** — See Also cross-link added
• ** guides/privacy-best-practices.mdx** — See Also cross-link added

Acceptance criteria

• Page committed
• Working code snippet end-to-end — full simulateAndSendAnnouncement function targeting futurenet with expected console output shown
• Linked from SDK Stellar page
• Linked from privacy best practices (Security overview)

Design decisions

• Primary vs. Secondary Path: Used prepareTransaction as the primary recommended path (it wraps simulation internally) and documented raw simulateTransaction as the secondary path for advanced inspection — this matches how the Soroban SDK is intended to be used.
• Type Guards Over Raw Strings: isSimulationError and isSimulationRestore type guards from SorobanRpc.Api used throughout — avoids raw error string checks which are fragile across SDK versions.
• User-Facing Error Messages: User-facing error message helper included — stealth flows surface errors to non-technical users, so actionable strings matter more than raw XDR.

Follow-ups

• Add simulation examples for stealth-registry and stealth-sender contracts once their ABIs are documented
• Update resource fee estimates once mainnet contract footprints are measured

Closes #39

[drips-wave]

@baedboibidex-cmyk 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

[truthixify]

Other docs PRs are landing one by one, which means most of them now conflict on docs.json (because each registers its new page there) and sometimes guides/privacy-best-practices.mdx. Quick rebase clears it:

git fetch origin
git rebase origin/develop
# in docs.json: keep all entries from both sides
# in privacy-best-practices.mdx: keep both your addition and develop's
git push --force-with-lease

Content of the PR itself is clean — this is just the registration ordering.

[truthixify]

Sorry @baedboibidex-cmyk — #53 just landed which means the same docs.json cascade hits again. One more rebase:

git fetch origin
git rebase origin/develop
# docs.json: keep both sides (the merge marker will be in the same section)
# privacy-best-practices.mdx: keep both your addition and the new one from #53
git push --force-with-lease

Your remaining PRs (#55, #58, #63) all need this same step. After this round they'll all merge in sequence.