Claimable Balance Predicate Builder

[Kingsman-99]

Description

Creating claimable balances with complex claim predicates (time-based, unconditional, or compound AND/OR predicates) requires directly manipulating the @stellar/stellar-sdk Claimant and xdr.ClaimPredicate types, which have an unintuitive API. The SDK must expose a fluent predicate builder that makes composing time-windowed and compound predicates readable and type-safe.

Technical Context

Add src/predicateBuilder.ts. Wraps @stellar/stellar-sdk Claimant.predicateUnconditional(), predicateBeforeAbsoluteTime(), predicateBeforeRelativeTime(), predicateAnd(), and predicateOr(). Produces typed ClaimPredicate objects passed to Operation.createClaimableBalance(). Extends src/claimableBalanceFallback.ts. Adds PredicateConfig to src/types.ts.

Acceptance Criteria

• PredicateBuilder.unconditional() returns an always-claimable predicate
• PredicateBuilder.absoluteWindow(start, end) returns a predicate claimable only within the given Unix timestamp window
• PredicateBuilder.relativeWindow(secondsFromNow) returns a predicate claimable for the next N seconds
• PredicateBuilder.and(a, b) and PredicateBuilder.or(a, b) compose two predicates with logical operators
• Built predicates are passed correctly to Operation.createClaimableBalance() in src/claimableBalanceFallback.ts; integration test claims the balance within and outside the window
• All CI checks (npm test, npm run build, ESLint/TypeScript) pass and the branch has no merge conflicts

---

[Abdulrasaq1515]

@Abdulrasaq1515 has applied to work on this issue as part of the Stellar Wave Program's 7th wave.

I want to build a claimable balance predicate builder because creating claimable balances with complex claim predicates requires directly manipulating unintuitive @stellar/stellar-sdk types. The builder exposes a fluent, type-safe API for composing time-windowed and compound predicates, integrates with claimableBalanceFallback, and includes integration tests.

Relevant experience:

Predicate builders — built predicate builders for 2 Stellar SDKs; time-based, compound AND/OR

ℹ️ Repo Maintainers: To accept this application, review their application or assign @Abdulrasaq1515 to this issue.

[whisper011]

@whisper011 has applied to work on this issue as part of the Stellar Wave Program's 7th wave.

I can work on this.
please assign

ℹ️ Repo Maintainers: To accept this application, review their application or assign @whisper011 to this issue.

[drips-wave]

Congratulations, @whisper011! 🎉 Your application was accepted by the repo's maintainers, and the issue is due on July 30, 2026.

🧑‍💻 @whisper011: Please resolve the issue such that the repo's maintainers have enough time to review your contribution before the due date. You'll earn Points for completing the issue on-time, which will make you eligible for a share of the Stellar Wave Program's reward pool.

Warning

When opening a PR, please link it to this issue to ensure it gets tracked accurately. Points are awarded when this issue is marked as completed by the maintainer.

🤠 Repo maintainers: Please keep an eye on the contributor's progress and review their work before the due date. You can manage this issue, including adjusting its complexity and points, here.

🌊 Happy Wave 🌊

[drips-wave]

This issue has been completed by @whisper011 as part of the Stellar Wave Program's 7th Wave 🥳

😎 @whisper011: You earned 200 Points for completing this issue! After the current Wave ends, you'll be eligible for a percentage of the Wave's reward pool based on the percentage of total points you've earned. Learn more here. You can also Leave a review to share your experience working on this issue.

🧑‍💻 Repo maintainers: How'd the contributor do? Leave a review to share your experience working with them.