docs(errors): add troubleshooting guide for common HostError codes

[Demilade10]

Description

This documentation-only issue adds a symptom-first troubleshooting guide for Soroban host, authorization, storage, transaction, RPC, CLI, build, and environment failures encountered while developing or operating PayStream.

It complements the PayStream contract error catalog. It does not redefine the contract's Error enum.

Requirements and Context

Create:

docs/TROUBLESHOOTING.md

Organize each entry as:

1. Symptom / exact message pattern
2. What layer produced it
3. Likely causes
4. How to confirm the cause
5. Safe fix
6. Whether retrying is appropriate
7. Related PayStream documentation

Do not infer a cause from a numeric code alone. Verify HostError categories, transaction result codes, and SDK statuses using official Stellar/Soroban documentation and the repository's pinned tool versions.

Error-layer distinction

Begin with a short decision guide distinguishing:

• PayStream Error(Contract, #N);
• nested token/router/oracle contract errors;
• Error(Auth, ...);
• Error(Storage, ...);
• Error(WasmVm, ...);
• budget/resource/footprint failures;
• simulation/preparation failures;
• RPC transport and server failures;
• transaction-submission statuses;
• final transaction result codes;
• local Rust/Cargo/Stellar CLI failures.

Explain that Error(Contract, #N) is not automatically a PayStream error. A nested contract may use the same numeric code.

Required project-specific entries

Nested authorization and Error(Contract, #9)

Document PayStream's historical failure pattern:

• the prior design called token approve() from inside subscribe();
• that nested authorization design produced persistent HostError: Error(Contract, #9) failures in this project;
• the adopted fix requires the subscriber to call the token contract's approve directly in a separate prior transaction;
• subscribe() must not reintroduce internal approval.

Do not claim every contract error #9 is caused by nested auth. Require diagnostic context and contract provenance.

require_auth() failures

Cover missing/wrong signers, source-account versus required-authorizer confusion, incomplete authorization entries, expired authorization/time bounds, contract versus account authorization, simulation-produced auth, and stale rebuilt transactions.

Include safe confirmation steps without exposing secret keys or signed envelopes.

Submission and confirmation states

Cover exact statuses/result conditions supported by the pinned SDK/RPC, including where applicable:

• PENDING;
• TRY_AGAIN_LATER;
• DUPLICATE;
• ERROR/FAILED;
• NOT_FOUND while confirmation is propagating;
• bad sequence such as tx_bad_seq/TxBadSeq;
• expired time bounds;
• insufficient fee/resource fee;
• unknown submission outcome.

For each, explain whether to poll by hash, wait with bounded backoff, rebuild with a fresh sequence, stop, or avoid duplicate submission.

Reference keeper/retry.js, but verify the guide matches merged behavior. Never recommend blind resubmission when a prior transaction may already have succeeded.

Resource and footprint failures

Cover common symptoms for CPU/instruction budget, memory limits, transaction size/operation limits, read/write footprint mismatch, archived ledger entries, and stale simulation resource estimates.

Use exact names only after confirming them against official sources/tool output.

Storage expiration and archival

Explain persistent-storage TTL, archived/expired state symptoms, restoration requirements, RPC versus missing-state failures, and that current PayStream code may not explicitly extend TTL.

Windows MinGW crate-type issue

Document exactly:

For native tests:

crate-type = ["rlib"]

For contract builds:

crate-type = ["cdylib", "rlib"]

Explain the MinGW DLL export ordinal limitation and that contributors must restore the build configuration before producing Wasm.

Soroban SDK pin

Document:

• PayStream is pinned to soroban-sdk = "27.0.3";
• contributors must not upgrade to 27.0.5;
• the project encountered a missing soroban-ledger-snapshot dependency for 27.0.5 on crates.io;
• dependency changes require a separate verified issue/PR.

Include non-mutating commands for confirming resolved versions.

Approval expiration ledger

Document:

• approval is a separate token-contract transaction;
• expiration_ledger must not exceed current ledger plus 3,000,000;
• higher values are rejected;
• expired token approval differs from internal allowance_remaining;
• clients should query a current ledger sequence and use a bounded future value.

Token allowance versus internal allowance

Explain both independent layers:

• Subscription.allowance_remaining;
• token-contract allowance granted to PayStream.

Changing one does not change the other. Do not suggest every allowance symptom is fixed by another approval.

Commands and examples

Use PowerShell-compatible commands. Examples must use secret placeholders, never print secret keys, clearly label testnet addresses, match Stellar CLI 27.1.0 and Soroban SDK 27.0.3, and distinguish reads from state changes.

Sources and maintenance

For external errors/statuses:

• link official Stellar/Soroban documentation;
• record verification date and SDK/CLI version;
• quote sparingly;
• require re-verification when CLI, SDK, RPC API, or protocol versions change.

Discoverability

Add relative links from:

• docs/DEVELOPMENT.md;
• docs/ARCHITECTURE.md;
• docs/ERROR_CODES.md if docs(errors): build full error catalog reference #41 is merged.

Suggested Execution

• Branch name: docs/hosterror-troubleshooting-guide
• Files to touch:
  • docs/TROUBLESHOOTING.md
  • docs/DEVELOPMENT.md
  • docs/ARCHITECTURE.md
  • docs/ERROR_CODES.md only for an optional cross-link
• Example commit message: docs(errors): add HostError and build troubleshooting guide

Test and Commit Steps

1. Collect real PayStream failure patterns from history, issues, tests, and keeper behavior.
2. Verify external statuses and codes against official sources.
3. Write each symptom → layer → cause → confirmation → fix → retry entry.
4. Check commands against pinned versions where practical.
5. Search for unsafe or conflicting guidance:

rg "Error\(Contract|TRY_AGAIN_LATER|DUPLICATE|bad.seq|crate-type|27\.0\.5|3,000,000|KEEPER_SECRET" docs README.md keeper src

6. Verify links and formatting:

Test-Path "docs/TROUBLESHOOTING.md"
Select-String -Path "docs/DEVELOPMENT.md","docs/ARCHITECTURE.md" -Pattern "TROUBLESHOOTING.md"
git diff --check

7. Commit with:

git add docs/TROUBLESHOOTING.md docs/DEVELOPMENT.md docs/ARCHITECTURE.md docs/ERROR_CODES.md
git commit -m "docs(errors): add HostError and build troubleshooting guide"

Only stage docs/ERROR_CODES.md if changed.

Guidelines

• Comment with the proposed source list and real PayStream symptoms to request assignment.
• Do not start or open a PR until assigned by a maintainer.
• The PR description must include Closes #<issue-number>.
• Keep the PR documentation-only.
• Do not diagnose errors solely by numeric code.
• Do not conflate PayStream, nested-contract, host, RPC, and transaction failures.
• Do not recommend blind transaction retries.
• Preserve the separate token-approval architecture and SDK pin.
• Never expose secret keys, signatures, or signed envelopes.
• Follow Conventional Commits and repository branch conventions.

Complexity

High (200 pts)