PR for Implement Simplified Trustline Cleanup Utility - Issue #176

[gloskull]

[SDK] Implement Simplified Trustline Cleanup Utility - Issue #176

Overview

This PR introduces a lightweight set of utilities in the SDK to help users identify and remove unused Stellar trustlines with zero balances. This simplifies account maintenance and reduces unnecessary blockchain clutter.

Changes

New Exports from packages/sdk/src/trustline.ts

1. TrustlineInfo Interface

export interface TrustlineInfo {
  assetCode: string;
  assetIssuer: string;
  balance: string;
}

Represents a single trustline's essential metadata.

2. findZeroBalanceTrustlines(horizonUrl, accountId)

• Purpose: Inspects an account on the Stellar network and identifies all non-native trustlines with zero balance
• Returns: Promise<TrustlineInfo[]> - Array of trustlines ready for removal
• Usage: First step in the cleanup workflow; filters out native XLM and trustlines with non-zero balances

3. buildTrustlineRemovalOps(trustlines)

• Purpose: Converts TrustlineInfo entries into Stellar changeTrust operations that set limit to "0"
• Returns: Operation[] - Array of operations ready to be added to a TransactionBuilder
• Usage: Second step; creates the actual operations to remove trustlines from the account

Implementation Details

• Minimal, focused implementation with zero configuration required
• Leverages existing Horizon API for account inspection
• Built on top of existing hasValidStellarTrustline function
• Filters out native asset (XLM) trustlines automatically
• Returns operations compatible with Stellar SDK's TransactionBuilder

Tests

Comprehensive test suite included covering:

• ✓ Native asset handling (XLM)
• ✓ Missing trustlines detection
• ✓ Authorization flag parsing
• ✓ Zero-balance filtering
• ✓ Empty result handling
• ✓ Empty input handling

All tests pass on the current build.

Usage Example

import { findZeroBalanceTrustlines, buildTrustlineRemovalOps } from '@chenpilot-experimental/sdk';
import { TransactionBuilder, Networks, Keypair } from '@stellar/stellar-sdk';

const accountId = 'GXXXXX...';
const horizonUrl = 'https://horizon.stellar.org';

// Step 1: Find zero-balance trustlines
const zeroTrustlines = await findZeroBalanceTrustlines(horizonUrl, accountId);
console.log(`Found ${zeroTrustlines.length} unused trustlines to remove`);

// Step 2: Build removal operations
const removeOps = buildTrustlineRemovalOps(zeroTrustlines);

// Step 3: Create transaction (example)
const sourceKeypair = Keypair.fromSecret('...');
const account = await server.loadAccount(accountId);
const tx = new TransactionBuilder(account, {
  fee: 100,
  networkPassphrase: Networks.PUBLIC_STELLAR_NETWORK,
})
  .addOperation(...removeOps)
  .setBaseFee(100)
  .build();

Priority

Low - Quality of life enhancement for account management

Closes #176