feat: add Claimable Balance support across lib, AgentClient, and Lang…#76
Open
nishant-uxs wants to merge 2 commits into
Open
feat: add Claimable Balance support across lib, AgentClient, and Lang…#76nishant-uxs wants to merge 2 commits into
nishant-uxs wants to merge 2 commits into
Conversation
…Chain tool
Introduces first-class Stellar Claimable Balance support — a unique Stellar
primitive for conditional / time-locked payments (escrow, vesting, scheduled
payouts) that was previously absent from the kit. Particularly valuable for
AI-agent workflows that need to release funds only when a predicate is
satisfied.
What's new
----------
* lib/claimableBalance.ts
- createClaimableBalance, claimClaimableBalance, listClaimableBalances
- buildPredicate helper for the friendly tagged-union ClaimPredicate
(unconditional / beforeRelativeTime / beforeAbsoluteTime / not / and / or)
- extractBalanceIdsFromTransactionResult for deterministic balance-id parsing
- All Stellar protocol limits exported as named constants:
MAX_CLAIMANTS_PER_BALANCE = 10
MAX_OPERATIONS_PER_TRANSACTION = 100
MAX_PREDICATE_DEPTH = 5
DEFAULT_TRANSACTION_TIMEOUT_SECONDS = 180
- Per-call options to override caps (maxOperationsPerTransaction,
maxPredicateDepth, transactionTimeoutSeconds, baseFee) — no magic numbers
locked into user code
* tools/claimableBalance.ts
- StellarClaimableBalanceTool — LangChain DynamicStructuredTool exposing
create / claim / list to AI agents
- Recursive zod schema for nested compound predicates
- Always returns JSON ({ ok, ... }) for deterministic agent parsing
- Auto-included in the exported stellarTools array
* agent.ts
- agent.claimable.{create,claim,list} on AgentClient
- Public types re-exported from agent.ts and index.ts
* examples/claimable-balance-example.ts
- Runnable end-to-end testnet example demonstrating composite predicate
(and + not + beforeRelativeTime + beforeAbsoluteTime), list, and claim
* tests
- tests/unit/lib/claimableBalance.test.ts (21 tests):
constants, predicate validation/depth/overrides, XDR robustness,
create flow (input validation, op-shape, signing, large batches,
custom caps, Horizon failure propagation), claim flow, list flow
- tests/unit/tools/claimableBalance.test.ts (7 tests):
LangChain tool surface, JSON contract for create/claim/list,
missing-secret handling
* README
- New 'Claimable Balances' section with API, predicate table, defaults &
overrides, and LangChain-tool documentation
Verification
------------
* 87/87 tests pass (28 new + 59 existing)
* tsc --noEmit clean
![cubic-dev-ai[bot]](https://avatars.githubusercontent.com/in/1082092?s=60&v=4){kind=small}
There was a problem hiding this comment.
1 issue found across 8 files
Prompt for AI agents (unresolved issues)
Check if these issues are valid — if so, understand the root cause of each and fix them. If appropriate, use sub-agents to investigate and fix each issue separately.
<file name="examples/claimable-balance-example.ts">
<violation number="1" location="examples/claimable-balance-example.ts:29">
P2: Example is not runnable as written because it generates new unfunded accounts each run and immediately uses them for create/claim without any funding or reuse mechanism.</violation>
</file>
Reply with feedback, questions, or to request a fix. Tag @cubic-dev-ai to re-run a review.
Address Cubic AI review (PR Stellar-Tools#76): the example previously generated fresh random keypairs each run and immediately invoked create/claim against unfunded testnet accounts, so it would always fail with account-not-found. Changes ------- * resolveAccount() helper: - Reads EXAMPLE_SOURCE_SECRET / EXAMPLE_RECIPIENT_SECRET when set (preferred for repeated runs) - Otherwise generates a fresh keypair and auto-funds it via the Friendbot faucet (https://friendbot.stellar.org), then verifies the account exists on-chain before returning - Prints the freshly-funded secrets so the user can re-export them for subsequent runs (avoids hammering Friendbot) * Wait for the predicate window to open before claiming, so the claim step now succeeds end-to-end on a clean run * Updated header docs to describe both modes (env-var reuse vs Friendbot) Verification ------------ * tsc --noEmit clean * 87/87 tests pass
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
feat: add Claimable Balance support across lib, AgentClient, and LangChain tool
What
First-class support for Stellar Claimable Balances — a unique Stellar
primitive for conditional / time-locked payments (escrow, vesting,
scheduled payouts). Previously absent from the kit. Particularly valuable
for AI-agent workflows that release funds only when a predicate is
satisfied.
Why
Every existing kit feature (bridge, swap, stake, payment, balance) ships a
LangChain
DynamicStructuredTooland is bundled intostellarTools.Claimable balances unlock new agentic use-cases (escrow, vesting, retry
deadlines) that none of the existing tools cover.
Surfaces
agent.claimable.{create,claim,list}on AgentClientStellarClaimableBalanceTool, auto-included instellarToolslib/claimableBalance(functions + buildPredicate + constants)Highlights
/ beforeAbsoluteTime / not / and / or) with input validation, depth guard,
and amount/issuer checks
per-call
options(no magic numbers){ ok, ... }) for deterministic agent parsingTests
tsc --noEmitcleanFiles
claimablenamespace + type re-exports)stellarTools)