Escrow funding event, resumable SDK batches, endpoint health, and worker donation dry-run

[ykargeee-bit]

Summary

Four open issues, one branch: an additive escrow funding event, a resumable
batch checkpoint for the SDK, actionable endpoint health + error
classification, and a worker donation dry-run. All changes are additive where
they touch existing APIs.

#978 — Emit an escrow funding event (and audit the transitions)

An artist had no way to learn when an escrow was funded short of polling. The
existing escrow/created event only carries (commission_id, amount), and its
payload is indexed downstream, so it is left untouched.

• create_escrow also emits the additive topic escrow/funded with
  (commission_id, funder, amount, asset, ledger) — enough to notify without a
  follow-up read.
• finalize_atomic_commit emits escrow/settled, so a client watching the
  four-step atomic-commit flow is not forced to poll get_atomic_commit.
• Every escrow transition is audited and the events documented in
  docs/EVENTS.md (new state-transition audit table) and
  docs/event_schemas.md (EscrowFunded, EscrowSettled).
• Covered by contracts/escrow/src/funding_event_tests.rs.

#979 — Resumable batch submission

BatchBuilder::take_calls() is one-shot: a process that dies between two
submissions loses the rest of the batch.

• New sdk::batch_checkpoint: BatchCheckpoint (serde-ready), a
  caller-supplied BatchCheckpointStore trait (MemoryCheckpointStore for
  tests, FileCheckpointStore with atomic temp-write + rename), and
  ResumableBatch::submit_remaining, which persists after every call.
• Additive BatchBuilder::checkpoint / from_checkpoint; no existing method
  changed.
• The guarantee is stated plainly: submission is at-least-once, a crash
  loses at most the one in-flight call, and callers must make calls idempotent
  (deterministic per-call marker) to dedupe. This is complementary to
  retry_async, not a replacement.

#980 — Endpoint health + actionable error taxonomy

• New StellarAidError variants: EndpointUnreachable, RequestTimeout,
  BadRequest, TransactionRejected, with is_retryable() and
  from_reqwest/from_http_status. Adding variants breaks exhaustive matches;
  acceptable for an unreleased SDK and called out here.
• retry_async_classified (predicate) and retry_stellar_async — the fix that
  lets retrying stop on a non-retryable error instead of retrying it fully.
• Typed SorobanRpcClient::health() and HorizonClient::health(), bounded by a
  short HEALTH_PROBE_TIMEOUT, for setup/diagnostics only.
• Config::validate() verifies the URLs and that the passphrase matches the
  named network, so the most common integration mistake fails immediately with
  a clear message.

#981 — Worker donation dry-run

• New POST /api/donations/validate builds the same XDR as submit and simulates
  it through the real SorobanRpcClient::simulate_transaction RPC — not the
  placeholder TransactionSimulator, which returns success unconditionally
  (Fix SDK transaction_simulator.rs returning placeholder results #795). It returns valid, gas_consumed, the contract's own error, and an
  extracted error_code.
• Cheap local validation first (donor, positive amount, non-zero campaign id,
  memo length) so obvious failures cost no round trip. The route has its own
  tighter rate-limit budget; /api/donations/submit is unchanged. A stale-since-
  simulation note is included in every response.
• The success / contract-error / RPC-failure interpretation is a pure function
  (interpret_simulation), so those paths are unit-tested without a network
  round trip.
• Unit tests: valid request, invalid campaign id, zero amount, empty donor,
  over-long memo, error-code extraction, and the three simulation outcomes.

Enabling fixes (called out deliberately)

These are outside the four issues but required for the SDK/worker to build; the
issue bodies name them as prerequisites.

• stellar-strkey 0.0.2 → 0.0.8 (workspace). The SDK is written against the
  0.0.8 API (stellar_strkey::ed25519::*, stellar_strkey::Contract); 0.0.2
  exposes neither. 0.0.8 is also what stellar-xdr 21 already pulls in, so the
  duplicate 0.0.2 copy goes away. transaction_builder.rs moves from the
  nonexistent Strkey::ContractId to Strkey::Contract.
• ed25519-dalek declared in sdk (already a workspace dependency) for the
  key derivation in utils/keypair.rs and setup/token_setup.rs.
• hmac, sha2, hex declared in worker, already used by
  webhooks.rs::verify_signature.

Notes / limitations

• worker is still not a workspace member, so its integration (including
  the new tests) cannot run in CI until that is fixed. That is a separate
  prerequisite, as Add a resumable batch submission to the SDK so a large call set survives a crash #979/Add a dry-run submit to the worker that returns the XDR without submitting it #981 state.
• Cargo.lock will be refreshed by the first cargo invocation after the
  stellar-strkey bump.
• No builds or tests were run as part of preparing this branch; changes were
  reviewed by inspection against the crate APIs.

Closes #978
Closes #979
Closes #980
Closes #981

[drips-wave]

@ykargeee-bit 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

[DevMuhdishaq]

Merged after resolving merge conflicts against main.

Conflict resolutions (merge commit df9bf86):

• Cargo.toml: both sides already pinned stellar-strkey = "0.0.8"; kept the explanatory comment added by this PR.
• sdk/src/transaction_builder.rs: this branch did the Strkey::ContractId -> Strkey::Contract rename but retained the old Hash(Uint256(c.0)) wrapping, while main (via fix(sdk): secure key generation and live transaction simulation  #1020) had already renamed and dropped the Uint256 wrapper (Hash(h.0)). Kept main's form, since it is the superset and matches the current stellar_xdr API.

Everything else (escrow funding events, SDK batch paths, worker dry-run, health worker) merged cleanly. Thanks!