feat: improve contract performance, storage migrations, and SDK reliability

[yours-anjikon]

Summary

This PR improves the ILN protocol across three major areas:

• Smart contract performance
• Upgrade infrastructure
• SDK reliability and developer experience

It implements efficient top-payer selection, introduces a storage migration framework, adds comprehensive SDK error handling, and enables historical event replay with automatic ledger catch-up.

Closes #550

Closes #551

Closes #552

Closes #553

---

Overview

This contribution focuses on protocol scalability and long-term maintainability.

The improvements include:

• optimized contract algorithms
• safe storage upgrade support
• robust SDK error handling
• reliable historical event synchronization

These changes improve developer experience while preparing the protocol for future upgrades and larger production deployments.

---

Issue #550 — Optimize Top Payers Heap

Problem

The existing get_top_payers implementation performs O(n²) selection, which becomes increasingly expensive as the payer set grows.

For large liquidity pools this increases dashboard query latency.

---

Solution

Replaced the quadratic selection logic with an efficient top-k algorithm.

Improvements include:

• significantly reduced computational complexity
• reduced allocations
• better scalability
• deterministic ordering
• preserved existing API behavior

---

Performance

Benchmarked before and after implementation.

Observed improvements include:

• lower execution time
• reduced CPU usage
• improved scalability for large payer sets
• faster dashboard loading

No functional behavior changed.

---

Issue #551 — Storage Migration Framework

Problem

Future contract upgrades may introduce storage schema changes.

Without a migration framework upgrades become risky and difficult to validate.

---

Solution

Implemented a reusable migration framework.

Features include:

• migration interface
• version tracking
• migration execution
• validation
• rollback support
• migration state verification

---

Migration Safety

Framework now supports:

• pre-migration validation
• execution checkpoints
• rollback on failure
• migration completion verification
• upgrade compatibility

---

Documentation

Added documentation describing:

• migration lifecycle
• writing migrations
• rollback procedures
• upgrade workflow

---

Issue #552 — Comprehensive SDK Error Handling

Problem

Contract failures currently expose limited information to SDK consumers.

Developers receive generic failures with little guidance.

---

Solution

Implemented typed SDK errors mapped to contract error codes.

Examples include:

• ValidationError
• AuthorizationError
• InvoiceNotFoundError
• InvalidStateError
• NetworkError
• ContractExecutionError

---

Error Context

Errors now include additional metadata when available:

• transaction hash
• ledger number
• contract ID
• original contract error code

This significantly improves debugging.

---

Retry Guidance

Transient errors now include retry recommendations.

Examples:

• RPC timeout
• temporary network interruption
• ledger synchronization delay

Permanent contract failures do not recommend retry.

---

Issue #553 — Event Replay & Catch-up

Problem

Applications cannot reliably recover historical events after downtime.

Restarting applications risks missing ledger events.

---

Solution

Added historical replay support.

New functionality:

replay(fromLedger)

allows applications to replay events beginning at any ledger.

---

Catch-up Support

Subscription logic now:

• detects ledger gaps
• replays missing events
• resumes live streaming
• avoids duplicate event delivery
• maintains ledger continuity

This significantly improves SDK reliability.

---

Files Updated

Smart Contract

contracts/invoice_liquidity/src/top_payers.rs

---

Storage

scripts/migrate-v1-v2.ts

docs/upgrade-guide.md

---

SDK

sdk/src/errors.ts

sdk/src/events/subscribe.ts

sdk/src/events/

sdk/tests/

---

Testing

Added comprehensive tests covering:

Contract

• top-k correctness
• benchmark validation
• large heap performance

---

Storage

• migration execution
• migration rollback
• version validation
• repeated migration protection

---

SDK Errors

• contract error mapping
• retry guidance
• contextual metadata
• typed exceptions

---

Event Replay

• replay from arbitrary ledger
• ledger gap recovery
• duplicate prevention
• transition to live subscriptions

---

Validation

Executed:

cargo test

cargo bench

pnpm test

pnpm lint

pnpm build

Verified:

• contract functionality unchanged
• performance improved
• migrations execute safely
• rollback works correctly
• SDK exposes typed errors
• replay starts from requested ledger
• ledger gaps recover automatically
• all tests pass

---

Result

This PR strengthens the ILN ecosystem by improving smart contract scalability, enabling safe protocol upgrades, and making the SDK significantly more reliable for production applications.

The changes remain backward compatible while laying the foundation for future protocol evolution.

[drips-wave]

@yours-anjikon 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