feat(sdk-coin-xlm): add accountConfig and authorizeTrustline support

[prajwalu142]

Problem

XLM was missing support for three critical transaction types required for account management: setOptions (accountConfig), setTrustLineFlags (authorizeTrustline), and clawback. These operations enable issuers to configure account flags, authorize trustlines, and reclaim assets respectively.

Goal

Add complete support for accountConfig, authorizeTrustline, and clawback transaction types in the XLM coin implementation, including parsing, verification, and explanation logic.

Fix

• Added TypeScript interfaces: AccountFlags, TrustlineAuthEntry, ClawbackEntry, and verify-param types for each operation
• Extended TransactionOperation with fields for setOptions (setFlags/clearFlags), setTrustLineFlags (trustor/authorized), and clawback (from/amount)
• Updated getExtraPrebuildParams to return empty recipients for non-payment types (accountConfig, authorizeTrustline, clawback)
• Implemented three verify methods: verifyAccountConfigOperations, verifyAuthorizeTrustlineOperations, verifyClawbackOperations
• verifyAccountConfigOperations rejects transactions with more than one setOptions operation to prevent silently unverified ops
• Replaced unsafe as unknown as casts with typed type guard functions (isAccountConfigVerifyParams, isAuthorizeTrustlineVerifyParams, isClawbackVerifyParams) that validate required field shapes at runtime
• Updated verifyTransaction to dispatch via type guards
• Updated explainTransaction to parse Stellar setOptions, setTrustLineFlags, and clawback operations
• Extended BuildParams codec with top-level fields: flags, clearFlags, trustlineAuths, clawbacks so params are forwarded in prebuild API requests

Testing

• 18 test cases covering getExtraPrebuildParams for all three new types plus payment fallback
• 16 verifyTransaction tests covering successful verifications and error cases (count mismatch, field mismatch, missing operations, multiple setOptions, type guard rejection for missing required arrays)
• 3 explainTransaction tests verifying operation parsing from Stellar XDR
• All tests use Stellar TESTNET and construct valid XDR transactions

Ticket: CSHLD-1089
🤖 Generated with Claude Code

[linear-code]

CSHLD-1089

[kisslove-dewangan]

codeowner's files lgtm, just take your team's approval

[prajwalu142]

@claude perform a thorough review and identify any regressions, call out only potential improvements and provide verdict at the end

[github-actions]

Claude finished @prajwalu142's task —— View job

---

Code Review - XLM accountConfig and authorizeTrustline Support

I have conducted a thorough review of the PR changes. Here's my detailed analysis:

Summary of Changes

This PR adds support for accountConfig and authorizeTrustline operations in the XLM SDK, enabling account flag management and trustline authorization flows with proper verification.

✅ Strengths & Quality

1. Comprehensive Verification Logic: The new verification functions (verifyAccountConfigOperations, verifyAuthorizeTrustlineOperations) properly validate that prebuilt transactions match client intent:

   • xlm.ts:1147-1154: Account config verification correctly uses bitwise operations to validate setFlags/clearFlags match expected bitmasks
   • xlm.ts:1180-1197: Trustline authorization verification validates trustor, token, and authorization state

2. Excellent Test Coverage: 95 tests pass with comprehensive coverage including error paths:

   • xlm.ts:1300-1349: 4 accountConfig tests cover valid setFlags/clearFlags and error cases
   • xlm.ts:1351-1433: 5 authorizeTrustline tests verify operation matching and mismatches
   • Tests validate specific error messages and edge cases

3. Proper Parameter Forwarding: BuildParams.ts:108-109 correctly whitelists new parameters for API forwarding

4. Consistent Architecture: New operations follow existing patterns (similar to trustline and clawback verification)

🔍 Potential Issues & Improvements

1. Type Safety Concern (xlm.ts:1366-1368):

   this.verifyAccountConfigOperations(tx.operations, txParams as unknown as AccountConfigVerifyParams);

   The as unknown as casting bypasses TypeScript's type checking. Consider using proper type guards or union types instead.

2. Single Operation Assumption (xlm.ts:1145):

   const setOptionsOp = setOptionsOps[0];

   The code assumes only the first setOptions operation matters, but doesn't validate this constraint. Consider either:

   • Explicitly rejecting transactions with multiple setOptions operations, or
   • Iterating through all operations for verification

3. BuildParams Naming Inconsistency (BuildParams.ts:109):

   authorizeTrustlines: t.unknown,

   The parameter is named authorizeTrustlines (plural) in BuildParams but used as authorizeTrustline (singular) elsewhere in the code.

4. Error Message Clarity: Some error messages could be more user-friendly:

   • xlm.ts:1152: Consider adding context about what the flags represent
   • xlm.ts:1176-1178: The count mismatch error could suggest the expected corrective action

🔒 Security Analysis

• No Security Concerns: The verification logic properly validates all critical fields (addresses, amounts, flags)
• Proper Input Validation: All parameters are validated against expected values before operations
• Safe Flag Operations: Bitwise operations use proper Stellar SDK constants, preventing flag manipulation

📝 Addressing Existing Review Comment

Regarding @mukeshsp's question about making coin optional in RecoveryTransaction interface (xlm.ts:77):

This change appears to be appropriate because:

• It's in the RecoveryTransaction interface, not a core parameter interface
• The coin field is conditionally set only when needed (xlm.ts:808)
• Making it optional prevents potential undefined assignment issues
• It maintains backward compatibility

🚀 No Regressions Identified

• Changes are additive and don't modify existing functionality
• New code paths are only triggered by new transaction types
• Existing tests continue to pass
• No breaking changes to public APIs

Final Verdict: ✅ APPROVE

This is a high-quality implementation that:

• ✅ Solves the stated problem effectively
• ✅ Includes comprehensive test coverage
• ✅ Follows established patterns and conventions
• ✅ Has proper verification logic for security
• ✅ No significant regressions or security concerns

Recommendations for improvement (non-blocking):

1. Fix the type casting to use proper type guards
2. Clarify the single operation assumption in accountConfig
3. Fix the BuildParams naming inconsistency
4. Consider enhancing error message clarity

The PR is ready for merge with these minor improvements addressed in future iterations.

---

Job Run • Branch: prajwalu142/cshld-1089-xlm-add-account-config-and-authorize-trustline-support-to

[prajwalu142]

@claude perform a thorough review and identify any regressions, call out only potential improvements and provide verdict at the end

[github-actions]

Claude finished @prajwalu142's task —— View job

---

Code Review - XLM accountConfig and authorizeTrustline Support

Review Tasks:

• Analyze PR changes and understand implementation scope
• Review code quality, security, and architecture patterns
• Check for potential regressions or breaking changes
• Evaluate test coverage and quality
• Address existing review comment about optional 'coin' field
• Provide improvement suggestions and final verdict

---

Summary of Changes

This PR adds support for three critical XLM transaction types: accountConfig (setOptions), authorizeTrustline (setTrustLineFlags), and clawback operations. The implementation includes comprehensive verification logic, proper type safety, and extensive test coverage.

✅ Strengths & Quality

1. Comprehensive Type Safety (xlm.ts:164-221):

   • Well-defined TypeScript interfaces for each operation type
   • Proper type guard functions (isAccountConfigVerifyParams, isAuthorizeTrustlineVerifyParams, isClawbackVerifyParams) that validate runtime types
   • Clear separation of concerns with specific parameter interfaces

2. Robust Verification Logic (xlm.ts:1163-1260):

   • verifyAccountConfigOperations: Correctly validates setFlags/clearFlags using bitwise operations against Stellar constants
   • verifyAuthorizeTrustlineOperations: Validates trustor, token, and authorization state matching
   • verifyClawbackOperations: Validates from address, token, and amount conversion between base/big units
   • Proper error messages with contextual information

3. Excellent Test Coverage (95 tests pass):

   • 18 tests for getExtraPrebuildParams covering all new types plus fallback behavior
   • 16 verifyTransaction tests including error cases and edge conditions
   • 3 explainTransaction tests validating XDR parsing
   • Tests use realistic Stellar TESTNET transactions with valid XDR

4. Consistent Architecture:

   • Follows existing patterns from trustline operations
   • Proper integration with existing verifyTransaction dispatch logic
   • Correct parameter forwarding in BuildParams.ts:108-111

⚠️ Potential Improvements

1. Type Safety Concern (xlm.ts:1395-1400):

   } else if (isAccountConfigVerifyParams(txParams)) {
     this.verifyAccountConfigOperations(tx.operations, txParams);

   While the type guards are properly implemented, the verification dispatch could be more explicit about which params are being used.

2. Single Operation Constraint (xlm.ts:1172-1174):

   if (setOptionsOps.length > 1) {
     throw new Error('accountConfig transaction must contain exactly one setOptions operation');
   }

   Good design: This prevents verification gaps where multiple operations could bypass checks.

3. Parameter Naming Consistency (BuildParams.ts:110):

   trustlineAuths: t.unknown,  // vs 'authorizeTrustline' elsewhere

   Minor inconsistency in naming convention (plural vs singular).

🔒 Security Analysis

• ✅ No Security Concerns: All verification logic properly validates critical fields (addresses, amounts, flags)
• ✅ Safe Flag Operations: Uses proper Stellar SDK constants preventing flag manipulation
• ✅ Input Validation: Type guards validate parameter structure at runtime
• ✅ Amount Handling: Proper conversion between base units and big units

📝 Addressing Review Comment

@mukeshsp's question about optional coin field (xlm.ts:77):

This change is appropriate because:

• The RecoveryTransaction interface is used in recovery contexts where coin may be set conditionally
• Making it optional prevents undefined assignment issues (xlm.ts:833)
• Maintains backward compatibility since existing code checks for existence before use
• Follows TypeScript best practices for optional properties

🚀 No Regressions Identified

• ✅ Changes are purely additive - no modification to existing functionality
• ✅ New code paths only triggered by new transaction types
• ✅ All existing tests continue to pass (CI shows success)
• ✅ No breaking changes to public APIs
• ✅ Proper integration with existing verification and explanation logic

Final Verdict: ✅ APPROVE

This is a high-quality implementation that:

• ✅ Solves the stated problem comprehensively
• ✅ Includes excellent test coverage (95 tests passing)
• ✅ Follows established patterns and coding standards
• ✅ Has robust verification logic for security
• ✅ No significant regressions or security concerns
• ✅ Proper TypeScript type safety with runtime validation

Minor recommendations (non-blocking):

1. Consider aligning parameter naming (trustlineAuths vs authorizeTrustline)
2. The single operation constraint in accountConfig is good defensive programming

The PR demonstrates solid engineering practices and is ready for merge.

---

Job Run • Branch: prajwalu142/cshld-1089-xlm-add-account-config-and-authorize-trustline-support-to

[kisslove-dewangan]

lgtm based on codeowner