Skip to content

docs: add Stellar offline transaction signing guide#54

Merged
truthixify merged 1 commit into
wraith-protocol:developfrom
baedboibidex-cmyk:docs/stellar-offline-signing
Jun 25, 2026
Merged

docs: add Stellar offline transaction signing guide#54
truthixify merged 1 commit into
wraith-protocol:developfrom
baedboibidex-cmyk:docs/stellar-offline-signing

Conversation

@baedboibidex-cmyk

Copy link
Copy Markdown
Contributor

PR Message: Stellar offline transaction signing guide (#40)

Summary

Adds guides/stellar-offline-signing.mdx — a complete guide for building Stellar transactions online, signing them on an air-gapped machine, and submitting them without the private key ever touching an internet-connected device.

What changed

  • ** New page:** guides/stellar-offline-signing.mdx covering:
    • Threat model: what offline signing mitigates and what it does not
    • Three-step workflow: build offline → sign offline → submit online (with full TypeScript examples)
    • Transaction inspection before signing (inspectTransaction pattern)
    • QR code transfer patterns (generate, scan, return signed XDR)
    • USB drive fallback for camera-restricted environments
    • Hardware wallet integration (Ledger) with honest current limitations
    • Stealth withdrawal specific guidance: viewing key vs. spending key separation, re-deriving the stealth scalar fully offline
  • ** 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
  • End-to-end workflow demonstrated (build → QR/USB transfer → inspect → sign → transfer back → submit)
  • Hardware wallet section honest about current limitations — explicit <Warning> block states that Ledger/Trezor cannot yet derive Wraith stealth scalars; documents what hardware wallets CAN do today (sign with regular Stellar keypair as a multisig signer)
  • Linked from SDK Stellar page
  • Linked from Security overview (privacy-best-practices)

Design decisions

  • SDK Primitives vs. Helpers: prepareOfflineStellarTransaction not yet in SDK — the issue notes "SDK is gaining" this helper. Documented the pattern using existing Stellar SDK primitives (TransactionBuilder, Transaction, xdr.DecoratedSignature) and added a <Note> block indicating the helper is coming as a drop-in replacement.
  • QR Code Tooling: No single standard exists; used qrcode (most common npm package) for generation and zbarcam for scanning, with a USB fallback section for camera-restricted environments. Avoided prescribing a single mandatory tool.
  • Viewing Key Online, Spending Key Offline: The guide explicitly shows how to run the announcement scanner with only the viewing key on the online machine, keeping the spending key and derived scalar fully air-gapped.

Follow-ups

  • Update SDK helper section once prepareOfflineStellarTransaction ships
  • Add hardware wallet stealth scalar derivation section once firmware support lands
  • Consider a companion guide for multi-device QR workflows (phone as QR bridge between two desktops)

Closes #40

- Add guides/stellar-offline-signing.mdx covering threat model,
  three-step build-offline/sign-offline/submit-online workflow,
  SDK primitives usage, QR code and USB transfer patterns,
  hardware wallet integration with honest current limitations,
  and stealth-specific air-gap guidance for spending keys
- Register page in docs.json under Guides > Operations
- Add cross-link from sdk/chains/stellar.mdx See Also section
- Add cross-link from guides/privacy-best-practices.mdx See Also section

Closes wraith-protocol#40
@drips-wave

drips-wave Bot commented Jun 25, 2026

Copy link
Copy Markdown

@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

Copy link
Copy Markdown
Contributor

Clean merge. 585-line offline signing guide with airgap workflow + verification path is solid. Thanks @baedboibidex-cmyk.

@truthixify truthixify merged commit 12a9015 into wraith-protocol:develop Jun 25, 2026
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

Stellar offline transaction signing guide for cold storage

2 participants