feat(soroban): add automated ABI binding generator for type-safe contract invocation

[ayomidearegbeshola29-dev]

Summary

Implements an automated ABI binding generator that parses Soroban contract spec entries and generates TypeScript type-safe wrapper functions for each contract entry point (#771).

Changes

• abi-binding-generator.ts: New module (513 lines) with:

  • xdrTypeToTypeScript() — recursive XDR type → TypeScript type mapping for all 25+ ScSpecTypeDef variants
  • parseContractAbi() — parses ScSpecEntry[] into structured ParsedContractAbi with functions and UDTs
  • generateBinding() — generates complete TypeScript source code with:
    • TypeScript interfaces for all contract UDTs (structs, unions, enums)
    • Argument interfaces for each contract function
    • InvokeCallback type alias for abstracting RPC calls
    • Factory function returning type-safe async methods for each entry point
    • Lazy ContractSpec singleton for efficient runtime type conversion
  • Full XDR type mapping: primitives (bool → boolean, u32 → number, i128 → bigint, etc.), compound types (option, vec, map, tuple, result), and UDT references

• index.ts: Added export for the new module

• abi-binding-generator.test.ts: Comprehensive tests (41 tests) covering:

  • All 19 primitive XDR → TypeScript type mappings
  • All 6 compound type mappings (option, vec, map, tuple, result, udt)
  • Recursion depth safety
  • Spec parsing from both ScSpecEntry[] and base64 string[]
  • UDT struct interface generation
  • Argument interface generation
  • Factory function generation with async methods
  • Generated code structure verification

Testing

✓ src/abi-binding-generator.test.ts  (41 tests)

Usage

import { ContractSpec } from 'stellar-sdk';
import { generateBinding } from '@craft/stellar';

// From spec entries
const entries = new ContractSpec(specXdrStrings).entries;
const source = generateBinding(entries, 'Token');
fs.writeFileSync('token-binding.ts', source);

The generated token-binding.ts exposes:

• createToken(contractId) → factory with type-safe methods
• TypeScript interfaces for all UDTs and function args
• Works with TypeScript strict mode

Closes #771

[drips-wave]

@ayomidearegbeshola29-dev Great news! 🎉 Based on an automated assessment of this PR, the linked Wave issue(s) no longer count against your application limits.

You can now already apply to more issues while waiting for a review of this PR. Keep up the great work! 🚀

Learn more about application limits