Add SDK destination account validation strategy#244
Merged
Conversation
…ion account validation strategy for payment flows.
5 tasks
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
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.
Closes #241
Implementation Summary
A complete validation module with clear local/network boundaries:
Local Validation (synchronous, no network calls):
Address format validation (G... public key shape)
Address checksum validation (Ed25519 verification)
Self-payment detection
Asset specification format validation
Network Validation (asynchronous, Horizon queries):
Account existence check (funded status)
Account status verification (active/inactive)
Trustline verification for issued assets
Trustline authorization status
Trustline capacity checks (when amount provided)
2. Validation Functions
validateDestinationLocal() - Fast synchronous validation
validateDestinationNetwork() - Comprehensive network validation
validateDestinationComplete() - Combined validation with level control
validateDestinationOrThrow() - Throwing helper for integration
Safe wrappers: safeValidateDestination(), safeValidateDestinationLocal(), safeValidateDestinationNetwork()
3. Type Definitions
DestinationValidationLevel - 'local' | 'network' | 'complete'
DestinationValidationStatus - 11 status codes for different outcomes
DestinationValidationOptions - Configurable validation options
DestinationValidationResult - Structured result with metadata
4. Integration
Exported all validation functions and types from index.ts for public API access.
Test coverage includes:
Local validation scenarios (valid/invalid addresses, self-payment, asset formats)
Network validation scenarios (account existence, trustline checks, capacity limits)
Complete validation with level control
Error handling and edge cases
Safe wrapper behavior
6. Documentation (destination-validation.md)
Complete guide covering:
Validation strategy overview
Usage examples for all functions
Validation status codes reference
Error handling patterns
Best practices
Integration with payment flows
Key Features
✅ Clear Boundaries - Local validation is fast and synchronous; network validation is comprehensive but requires Horizon queries
✅ Flexible Levels - Choose 'local', 'network', or 'complete' validation based on your use case
✅ Rich Metadata - Results include sequence numbers, balances, trustline limits, and capacity information
✅ Error Codes - Machine-readable error codes for programmatic handling
✅ Safe Wrappers - Non-throwing variants for error-safe integration
✅ Trustline Support - Full support for issued asset trustline validation including authorization and capacity checks