feat(core): add webhook events, custom asset pair pricing, configurable operation timeouts, and wallet adapter integration tests

[Johnsmichael150]

Summary

This PR enhances the Sorokit SDK by introducing webhook support for transaction lifecycle events, configurable per-operation request timeouts, custom asset pair pricing utilities, and a comprehensive integration test suite for supported wallet adapters.

These improvements increase the SDK's flexibility, reliability, and developer experience while strengthening test coverage for critical components.

Related Issues

• Close Add integration tests for all wallet adapters #198
• Close Add request timeout configuration per operation #207
• Close Implement webhook support for transaction events #208
• Close Add support for custom asset pair trading logic #209

---

What's Changed

🔔 Transaction Webhook Support (#208)

Problem

Applications currently have to poll the SDK to determine whether a transaction has been submitted, confirmed, or failed.

Solution

Added webhook registration support for transaction lifecycle events.

New API:

registerWebhook(event, url, secret)

Supported events:

• submitted
• confirmed
• failed

Features include:

• HMAC-SHA256 payload signing
• Secure secret handling
• Automatic retry with exponential backoff (up to 3 attempts)
• Consistent webhook payload schema
• Documentation for webhook verification

Result

• Real-time transaction notifications.
• Reduced polling overhead.
• Secure webhook delivery with signature verification.

Files

• src/transaction/*

---

💱 Custom Asset Pair Pricing (#209)

Problem

The SDK lacked built-in utilities for working with custom asset pairs and pricing routes across decentralized exchange liquidity pools.

Solution

Added helper utilities for creating asset pairs and retrieving market prices.

New APIs:

• createAssetPair(asset1, asset2)
• getPairPrice(pair, amount)

Capabilities include:

• Standard asset pair creation
• Multi-hop route discovery
• Market price estimation
• Graceful handling of insufficient liquidity
• Consistent pricing interface across supported assets

Result

• Easier implementation of custom trading strategies.
• Support for non-standard asset combinations.
• Improved DEX integration capabilities.

Files

• Trading and pricing modules

---

⏱️ Configurable Request Timeouts (#207)

Problem

A single global timeout was applied to every SDK operation, despite different operations having very different latency requirements.

Solution

Introduced configurable timeout settings throughout the SDK.

Enhancements include:

• Optional timeoutMs parameter on public APIs
• Per-operation default timeout values
• Global timeout overrides through createSorokitClient()
• Backwards-compatible defaults for existing consumers

Examples:

• Fast account lookups
• Longer-running contract simulations
• Custom overrides when needed

Result

• Greater flexibility across different workloads.
• Improved control over network behavior.
• No breaking API changes.

Files

• src/shared/config.ts
• Public SDK APIs

---

🧪 Wallet Adapter Integration Tests (#198)

Problem

Wallet adapter functionality lacked comprehensive integration testing across supported wallet providers and failure scenarios.

Solution

Added a dedicated integration test suite covering supported wallet adapters.

Coverage includes:

Freighter

• Connect
• Disconnect
• Successful signing
• User rejection
• Request timeout

Ledger

• Connection
• Transaction signing
• Multiple transaction types

Additional scenarios:

• Network failures
• Mock responses matching real wallet behavior
• Error propagation
• Timeout handling

The suite uses mocked wallet interactions and avoids communication with production wallet services.

Result

• Improved confidence in wallet integrations.
• Better regression protection.
• Higher adapter test coverage.

Files

• src/tests/integration/

---

Testing

Verified that:

• Webhooks are registered and delivered for all supported transaction events.
• Payload signatures validate correctly using HMAC-SHA256.
• Failed webhook deliveries retry with exponential backoff.
• Asset pair pricing returns expected values across supported routes.
• No-liquidity scenarios return structured errors.
• Per-operation timeout overrides work correctly.
• Global timeout configuration applies to newly created clients.
• Wallet adapter integration tests pass across all supported scenarios.
• Test suite completes within the expected execution time.

---

Benefits

Developer Experience

• Real-time transaction notifications.
• Flexible timeout configuration.
• Simplified custom asset pricing.
• Reliable wallet integration testing.

Security

• Signed webhook payloads.
• Secure secret management.
• Verified webhook authenticity.

Reliability

• Retry logic for webhook delivery.
• Configurable network behavior.
• Comprehensive integration testing.

Maintainability

• Centralized timeout configuration.
• Reusable asset pair utilities.
• Expanded automated test coverage.

---

Acceptance Criteria

#198

• Freighter adapter integration tests implemented.
• Ledger adapter integration tests implemented.
• Success and failure scenarios covered.
• Mocked wallet behavior closely matches production.
• High adapter test coverage achieved.

#207

• Optional timeoutMs parameter added to public APIs.
• Per-operation timeout defaults defined.
• Global override supported via createSorokitClient().
• Existing API remains backwards compatible.

#208

• registerWebhook(event, url, secret) implemented.
• Supports submitted, confirmed, and failed events.
• Payloads signed using HMAC-SHA256.
• Failed deliveries retry with exponential backoff.
• Webhook format documented.

#209

• createAssetPair() helper added.
• getPairPrice() implemented.
• Multi-hop pricing supported.
• No-liquidity scenarios handled gracefully.
• Asset pair functionality covered by automated tests.

[drips-wave]

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