feat: Add comprehensive Transaction Tracking System with real-time monitoring by nishant-uxs · Pull Request #25 · Stellar-Tools/Stellar-AgentKit

nishant-uxs · 2026-03-14T09:19:40Z

🎯 Overview

This PR adds a comprehensive Transaction Tracking System to Stellar AgentKit, enabling developers to monitor and manage transaction status across all Stellar operations.

✨ Key Features

✅ Real-time transaction monitoring with automatic retry logic
✅ Monitor multiple transactions simultaneously
✅ Filter transactions by operation type
✅ Detailed status information (ledger, timestamps, return values)
✅ Support for all operation types (swap, bridge, LP, payment, stake)
✅ Full testnet and mainnet support

📝 Changes

New Files (5)

lib/transactionTracker.ts - Core implementation (400+ lines)
tests/transactionTracker.test.ts - Test suite (250+ lines)
docs/TRANSACTION_TRACKING.md - Documentation (600+ lines)
examples/transaction-tracking-example.ts - Examples (320+ lines)

Modified Files (8)

agent.ts - Integrated tracker into AgentClient
index.ts - Exported tracking types
README.md - Added Transaction Tracking section
tools/bridge.ts - Fixed syntax error

💡 Usage Example

import { AgentClient, OperationType, TransactionStatus } from "stellartools";

const agent = new AgentClient({
  network: "testnet",
  publicKey: process.env.STELLAR_PUBLIC_KEY,
  enableTracking: true,
});

const result = await agent.swap({
  to: "recipient_address",
  buyA: true,
  out: "100",
  inMax: "110"
});

const status = await agent.waitForConfirmation(result.hash, OperationType.SWAP);

if (status.status === TransactionStatus.SUCCESS) {
  console.log("✅ Transaction confirmed!");
}

📊 Statistics

Total Changes: 3,093 insertions, 103 deletions
New Code: 1,500+ lines
Tests: 15+ test cases
Documentation: 600+ lines

✅ Checklist

🎯 Impact

This feature significantly enhances the SDK by providing robust transaction monitoring capabilities for all Stellar operations.

Summary by cubic

Adds a real-time Transaction Tracking System with a unified transaction builder and AgentClient integration to monitor swaps, bridge, LP, payments, and staking. Updates error handling to default unknown RPC errors to PENDING for safe retries, with timeouts ensuring eventual completion.

New Features
- TransactionTracker with retries, timeouts, detailed status, multi-transaction tracking, and OperationType filtering.
- AgentClient integration via enableTracking and waitForConfirmation(hash, operationType).
- Unified buildTransaction used across contract, stake, and bridge for consistent fee/timeout/memo handling.
- Exports: TransactionTracker, TransactionStatus, OperationType, createTransactionTracker (plus typed responses); docs include design note on unknown RPC error handling; added examples and tests.
Bug Fixes
- Error handling: explicit retryable patterns; more non-retryable cases; unknown errors default to PENDING; case-insensitive matching.
- Enforced tracking: getTransactionStatus requires a tracked hash.
- Bridge: network-specific Soroban RPC URLs with mainnet fallback (incl. legacy SRB_PROVIDER_URL) and proper SDK network configuration.
- Cleanup and docs: standardized stellartools imports; removed dotenv import-time side effects; safer env/test cleanup.

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

- Implement TransactionTracker class with real-time monitoring - Add automatic retry logic with configurable timeouts - Support for monitoring multiple transactions simultaneously - Filter transactions by operation type (swap, bridge, LP, payment, stake) - Detailed status information including ledger, timestamps, and return values - Integration with AgentClient for seamless tracking - Comprehensive test suite with 15+ test cases - Full documentation with examples and best practices - Export all tracking types and utilities in index.ts This feature significantly enhances the SDK by providing robust transaction monitoring capabilities for all Stellar operations.

cubic-dev-ai

10 issues found across 19 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="README.md">

<violation number="1" location="README.md:303">
P2: README uses conflicting package import names (`stellartools` vs `stellar-agentkit`), causing likely module-not-found errors for users following the documented install step.</violation>
</file>

<file name="tests/transactionTracker.test.ts">

<violation number="1" location="tests/transactionTracker.test.ts:53">
P2: Test cleanup restores `process.env` incorrectly; assigning possibly `undefined` can leak `SRB_PROVIDER_URL` into later tests and create order-dependent behavior.</violation>

<violation number="2" location="tests/transactionTracker.test.ts:242">
P2: Network-error unit test depends on real external RPC/DNS failure instead of mocking, making it flaky and environment-dependent.</violation>
</file>

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

<violation number="1" location="tools/bridge.ts:31">
P1: `fromNetwork` only changes XDR signing passphrase; SDK RPC/core network config remains static, which can cause testnet/mainnet mismatch in bridge transaction creation/submission.</violation>
</file>

<file name="docs/TRANSACTION_TRACKING.md">

<violation number="1" location="docs/TRANSACTION_TRACKING.md:377">
P2: Documentation claims cross-network persistence in a way that is misleading: previously tracked transactions may be queried on the wrong network after `updateNetwork()` because status lookups use the tracker’s current global network/server.</violation>

<violation number="2" location="docs/TRANSACTION_TRACKING.md:485">
P2: Cleanup example mutates a copied Map from `getTrackedTransactions()`, so deletions do not affect tracker state.</violation>
</file>

<file name="lib/transactionTracker.ts">

<violation number="1" location="lib/transactionTracker.ts:4">
P2: Library module performs import-time dotenv initialization, causing global process.env side effects for consumers.</violation>

<violation number="2" location="lib/transactionTracker.ts:138">
P2: `getTransactionStatus` misclassifies untracked transactions by defaulting `operationType` to `PAYMENT`, causing incorrect response metadata.</violation>

<violation number="3" location="lib/transactionTracker.ts:249">
P1: RPC/query exceptions are incorrectly marked as terminal FAILED, causing `waitForConfirmation()` to stop retrying after transient errors.</violation>
</file>

<file name="examples/transaction-tracking-example.ts">

<violation number="1" location="examples/transaction-tracking-example.ts:119">
P2: Mixed-type transaction example incorrectly monitors all hashes as `SWAP`, overwriting previously tracked operation types.</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