feat: add StellarClaimBalanceTool for automated fund recovery

[efekrbas]

Description

I have successfully implemented the StellarClaimBalanceTool and its corresponding library helper claimF.ts. This tool allows the AI agent to discover and claim pending assets (Claimable Balances) on the Stellar network for the user account.

Technical Depth

• LangChain Integration: Utilized DynamicStructuredTool with a strictly defined Zod schema to ensure reliable agent interaction.
• Batching Logic: The tool supports both listing pending balances and claiming them. It includes logic to bundle multiple claimable balances into a single transaction to optimize network fees.
• SDK Implementation: Built using @stellar/stellar-sdk to interact with Horizon's claimableBalances endpoint and construct claim operations.
• Architecture Alignment: The implementation follows the project's existing tool patterns, ensuring full TypeScript compatibility and seamless integration into the stellarTools array.

Impact

This contribution enhances the SDK's DeFi capabilities by automating the recovery of "stuck" or pending funds. Users no longer need to manually monitor for claimable balances; the agent can now proactively manage and collect these assets.

---

Summary by cubic

Adds StellarClaimBalanceTool to list and claim Stellar claimable balances with safe batching, returning an unsigned XDR for claims. Also tightens the bridge with stricter mainnet gating, dynamic target-chain mapping, clearer params, unified XDR building, auto trustline setup with correct signing, and reorganized exports.

• New Features

  • StellarClaimBalanceTool using DynamicStructuredTool + zod; supports list and claim; added to stellarTools and exported from root.
  • lib/claimF.ts adds Horizon pagination, caps batch claims to 50 ops per tx, fixes fee handling (baseFee.toString()), and builds single/batch claim txs with @stellar/stellar-sdk.
  • Bridge updates: fromNetwork (stellar-testnet/stellar-mainnet) with env safeguard, dynamic targetChain mapping, unified XDR builder, automatic trustline setup, corrected trustline signing, and clearer toAddress param.
  • Exports: re-export everything from tools/claim_balance_tool, export agent types (StellarAssetInput, QuoteSwapParams, RouteQuote, SwapBestRouteParams, SwapBestRouteResult), and include StellarClaimBalanceTool in stellarTools.

• Migration

  • Set STELLAR_PUBLIC_KEY (required). Optional: HORIZON_URL and STELLAR_NETWORK (PUBLIC or defaults to TESTNET).
  • Mainnet bridging requires allowMainnet: true in AgentClient and ALLOW_MAINNET_BRIDGE=true in .env.
  • Bridge accepts targetChain (defaults to ethereum). Responses no longer include targetChain.
  • claim returns an unsigned XDR; submit it via your signing/broadcast flow.

^{Written for commit 1a1aa33. Summary will update on new commits.}

[cubic-dev-ai]

3 issues found across 3 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="lib/claimF.ts">

<violation number="1" location="lib/claimF.ts:4">
P1: Horizon endpoint default (Testnet) can conflict with PUBLIC network passphrase selection, causing network-mismatched transaction construction.</violation>

<violation number="2" location="lib/claimF.ts:7">
P2: `claim all` uses only the first fetched page of claimable balances, so additional balances may remain unclaimed.</violation>
</file>

<file name="tools/claim_balance_tool.ts">

<violation number="1" location="tools/claim_balance_tool.ts:15">
P2: The `claim` action is described as collecting funds, but it only builds and returns unsigned XDR without submitting on-chain, creating a misleading tool contract.</violation>
</file>

---

Since this is your first cubic review, here's how it works:

• cubic automatically reviews your code and comments on bugs and improvements
• Teach cubic by replying to its comments. cubic learns from your replies and gets better over time
• Add one-off context when rerunning by tagging @cubic-dev-ai with guidance or docs links (including llms.txt)
• Ask questions if you need clarification on any suggestion

_{Reply with feedback, questions, or to request a fix. Tag @cubic-dev-ai to re-run a review.}

[daiwikmh]

resolve conflict errors

[efekrbas]

resolve conflict errors

Hi, I've just resolved the conflicts. It should be ready for review now.

[cubic-dev-ai]

1 issue found across 2 files (changes from recent commits).

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="lib/claimF.ts">

<violation number="1" location="lib/claimF.ts:51">
P1: `claim all` builds a single transaction with unbounded operations, which can exceed Stellar transaction limits and fail for accounts with many claimable balances.</violation>
</file>

_{Reply with feedback, questions, or to request a fix. Tag @cubic-dev-ai to re-run a review.}

[efekrbas]

@daiwikmh