closes #363 closes #378 closes #381: lifecycle manager, capability discovery, production guide

[JoyAdah]

closes #363
closes #378
closes #381

Summary

closes #378 — Capability-aware metadata discovery layer

Adds packages/sdk/src/capabilityDiscovery.ts with CapabilityDiscovery and a createCapabilityDiscovery factory. The class probes Horizon and the Soroban RPC on first use, resolves ContractVersions, FeatureFlags, and BackendLimits into a typed BackendCapabilities snapshot, and caches it for a configurable TTL.

negotiate(req) lets clients declare minimum protocol versions, minimum API versions, and required feature flags; it returns { compatible, reason, capabilities } so integrations can fail fast before attempting unsupported operations.

Falls back gracefully: if Soroban RPC is unreachable sorobanEnabled = false rather than throwing. invalidateCache() forces a fresh probe. Full unit tests in packages/sdk/src/__tests__/capabilityDiscovery.test.ts.

closes #363 — Production startup/shutdown lifecycle

Adds src/lifecycle.ts with ServerLifecycle — a class that replaces the inline Server class in src/index.ts. Provides ordered startup (DB → background services → HTTP bind), graceful shutdown with a configurable drain timeout, bounded port-retry on EADDRINUSE, exponential back-off for background-service restarts, and SIGTERM/SIGINT/uncaughtException/unhandledRejection handlers.

Key improvements over the original:

• shutdown() is idempotent (guarded by isShuttingDown)
• Services stop in reverse registration order
• Drain timeout prevents indefinite hang on keep-alive connections
• registerService() / registerDataSource() fluent API decouples wiring from startup logic

closes #381 — Production-oriented integration guide

Adds packages/sdk/examples/production-integration-guide.ts covering 5 real-world scenarios:

1. Capability discovery + version negotiation before using platform features
2. Network health check + cross-chain swap simulation (plan before execute)
3. Execution with polling-based progress tracking and recovery hooks
4. Soroban contract interaction: simulate → sign → submit pattern
5. Realtime event subscription with error handling and clean unsubscribe

Test plan

• cd packages/sdk && npx jest capabilityDiscovery — all tests pass
• npx ts-node packages/sdk/examples/production-integration-guide.ts — runs to completion
• Start server with ServerLifecycle, send SIGTERM — graceful shutdown logged, process exits 0
• Start server with port already bound — retries on next port up to maxPortRetries

[drips-wave]

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