feat(stellar): deterministic contract address derivation, type-safe i…

[Darkdante9]

…nvocation, Horizon failover, storage key collision detection

#613 — Deterministic contract address derivation

• Add deriveContractAddress(deployerPublicKey, salt, wasmHash) to soroban.ts Derives the Soroban contract address from deployer, 32-byte salt, and WASM hash using the HashIDPreimage/CONTRACT_ID XDR preimage algorithm, matching the address the Soroban host assigns at deployment time.
• Add verifyContractAddress() to assert a derived address matches a deployed one.
• Add soroban-address-derivation.test.ts with determinism, input-sensitivity, Buffer/hex parity, and validation tests.

#614 — Type-safe contract invocation wrapper with error boundary

• Add invokeContract<TArgs, TReturn>(options, parse) to soroban.ts. Generic wrapper that accepts typed args and a parse function for the return value; all RPC errors are caught and mapped through parseStellarError so raw RPC details never reach callers.
• Maps rate-limit errors to status 429 and endpoint-unreachable to 503.
• Add soroban-typesafe-invocation.test.ts covering success, RPC failure, rate-limit status mapping, and error boundary (no raw leak).

#615 — Horizon multi-endpoint failover

• Add createHorizonFailover(config) to config.ts. Returns a stateful HorizonFailover manager with selectEndpoint(), markUnhealthy(url), and markHealthy(url). Unhealthy endpoints are skipped for recoveryMs (default 30 s); primary is returned as last resort when all endpoints are unhealthy.
• Export HorizonFailoverConfig, HorizonFailover interfaces and HORIZON_FAILOVER_ENDPOINTS per-network defaults.
• Add config-failover.test.ts covering primary preference, failover, time-based recovery, full-unhealthy fallback, markHealthy, and single-endpoint.

#616 — Storage key namespace collision detection

• Add detectStorageKeyCollisions(entries) and assertNoStorageKeyCollisions(entries) to soroban.ts. Statically analyses { owner, key } pairs before deployment and surfaces a StorageKeyCollisionError naming every colliding key and its owners.
• Add soroban-storage-collision.test.ts covering no-collision, single collision, multi-collision, three-way collision, empty input, and error message content.

Documentation

• Expand packages/stellar/README.md with algorithm description, parameter tables, and usage examples for all four new APIs.

Closes #613
Closes #614
Closes #615
Closes #616

[drips-wave]

@Darkdante9 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