Auto-generate XDR types from canonical .x definitions

[christian-rogobete]

Summary

Replaces ~309 hand-written XDR type definitions with machine-generated PHP code produced by a Ruby-based code generator that reads Stellar's canonical .x XDR definition files. Adds 133 new XDR types not previously in the SDK (SCP, overlay, bucket, ledger close meta, exporter, survey, internal types), extracts hand-maintained helper methods into 34 wrapper classes, and adds 1,013 auto-generated round-trip unit tests covering all generated types.

• Code generator at tools/xdr-generator/ (Ruby, uses xdrgen gem)
• 13 .x definition files in xdr/ from stellar/stellar-xdr
• Generated PHP files in Soneso/StellarSDK/Xdr/

What changed

• Machine-generated XDR types: 434 generated PHP files, each with encode(), decode(), toBase64Xdr(), and fromBase64Xdr() methods. All types are produced from the canonical .x definitions via the xdrgen gem.
• Code generator: tools/xdr-generator/generator/generator.rb reads .x files via the xdrgen gem and produces PHP. Override files (name_overrides.rb, field_overrides.rb, member_overrides.rb, type_overrides.rb) preserve existing SDK naming where the hand-written code diverged from XDR spec names.
• 34 base+wrapper pairs: Types that need hand-maintained helper methods (factory methods, custom constructors, StrKey encoding, etc.) generate a *Base.php file; the hand-maintained wrapper extends the generated base class. This separates generated encode/decode logic from SDK-specific convenience methods.
• Generator infrastructure: Makefile with 9 Docker-based targets, GitHub Actions CI workflow (xdr-generator.yml) with snapshot tests, drift detection (fails if generated files differ from committed versions), and validation against .x definitions.
• Auto-generated round-trip tests: 1,013 tests in Soneso/StellarSDKTests/Unit/Xdr/Generated/ covering enums, structs, unions, and typedefs — each test includes both binary encode/decode and base64 round-trip verification.
• Enum decode validation: All generated enum decode() methods now reject unknown discriminant values with InvalidArgumentException instead of silently accepting them.

Breaking changes

This PR has breaking changes. The high-level SDK APIs (operation classes, services, SEP implementations) are unchanged, with the exception listed below. The remaining breaks are in the low-level XDR layer.

High-level API

SorobanContractInfo.envInterfaceVersion replaced by two properties

SorobanContractInfo.envInterfaceVersion: int is replaced by two properties: envMetaProtocol: int and envMetaPreRelease: int. This follows a change in the XDR spec where XdrSCEnvMetaEntryInterfaceVersion is now a struct with two uint32 fields (protocol, preRelease) instead of a single uint64.

// Before
$version = $contractInfo->envInterfaceVersion;

// After
$protocol = $contractInfo->envMetaProtocol;
$preRelease = $contractInfo->envMetaPreRelease;

Low-level XDR types

Most SDK consumers don't interact with XDR types directly — the SDK's operation classes, transaction builder, and service layer handle serialization internally. If your code does use XDR types, here is what changed.

XdrChangeTrustAsset / XdrTrustlineAsset no longer extend XdrAsset

Per the XDR spec, ChangeTrustAsset and TrustLineAsset are independent unions — they are not subtypes of Asset. The hand-written SDK had XdrChangeTrustAsset extends XdrAsset and XdrTrustlineAsset extends XdrAsset, which is incorrect.

Code that passes XdrChangeTrustAsset or XdrTrustlineAsset to Asset::fromXdr() must use the new factory methods instead:

// Before
Asset::fromXdr($changeTrustOp->getLine());  // worked because XdrChangeTrustAsset extended XdrAsset

// After
Asset::fromXdrChangeTrustAsset($changeTrustOp->getLine());  // new factory method
Asset::fromXdrTrustlineAsset($trustlineAsset);               // new factory method

AssetTypePoolShare::toXdr() now throws \RuntimeException. Use AssetTypePoolShare::toXdrChangeTrustAsset() instead.

Union constructor changes

Generated union types now take only the discriminant in their constructor. Associated values are set via public properties after construction:

// Before (some hand-written unions accepted arm values in constructor)
$result = new XdrManageOfferResult($code, $success);

// After
$result = new XdrManageOfferResult($code);
$result->success = $successValue;

Bugs fixed

The generator found and automatically fixed bugs across that were present in the previous, hand-written XDR type definitions.

Missing enum constants

• XdrLiquidityPoolDepositResultCode — missing 3 constants (LINE_FULL, BAD_PRICE, POOL_FULL)
• XdrOperationResultCode — missing constant TOO_MANY_SPONSORING
• XdrSetOptionsResultCode — missing constant AUTH_REVOCABLE_REQUIRED
• XdrContractCostType — missing 25 BLS12-381 constants

Incorrect encode output

• XdrInvokeHostFunctionResult — double concatenation ($bytes .= $bytes .= ...) doubled the encoded output for SUCCESS arms
• XdrSCError — 9 union arms incorrectly treated as void, silently dropping the SCErrorCode value
• XdrSorobanTransactionMeta — copy-paste bug: diagnosticEvents array encoded $this->events instead of $this->diagnosticEvents
• XdrInnerTransactionResultResult — encode() always wrote operations array regardless of result code

Other

• XdrInnerTransactionResultPair — $$transactionHashBytes variable-variable typo; fromBase64Xdr() returned wrong type

New infrastructure

Component	Description
Makefile	9 targets: xdr-generate, xdr-clean-generated, xdr-clean-all, xdr-update, xdr-compare, xdr-generator-test, xdr-generator-update-snapshots, xdr-validate, xdr-generate-tests
.github/workflows/xdr-generator.yml	CI: snapshot tests + drift detection (fails if generated files are stale) + validation
.gitattributes	Marks generated files as linguist-generated=true, excludes wrappers and infrastructure
tools/xdr-generator/test/generator_snapshot_test.rb	11 Minitest tests, 8 golden snapshot files covering all generator patterns
tools/xdr-generator/test/generate_tests.rb	Generates 1,013 round-trip encode/decode + base64 unit tests for all XDR types
tools/xdr-generator/test/validate_generated_types.rb	Validates all 434 generated types against .x definitions (field names, enum constants, union arms)

Test plan

• ./vendor/bin/phpunit --testsuite unit — 3,374 tests pass (including 1,013 auto-generated XDR round-trip tests)
• make xdr-generator-test — 11/11 snapshot tests pass
• make xdr-validate — 434 types validated, 0 errors
• make xdr-update — clean regeneration matches committed files
• All integration tests pass

[codecov]

Codecov Report

❌ Patch coverage is 85.31130% with 729 lines in your changes missing coverage. Please review.
✅ Project coverage is 85.90%. Comparing base (9cffb2c) to head (5b88dbd).
⚠️ Report is 53 commits behind head on main.

Files with missing lines	Patch %	Lines
Soneso/StellarSDK/Xdr/XdrHostFunctionBase.php	42.59%	31 Missing ⚠️
Soneso/StellarSDK/Xdr/XdrContractCodeEntryV1.php	0.00%	22 Missing ⚠️
Soneso/StellarSDK/Xdr/XdrContractEventBodyV0.php	0.00%	21 Missing ⚠️
Soneso/StellarSDK/Xdr/XdrLedgerCloseMeta.php	59.57%	19 Missing ⚠️
Soneso/StellarSDK/Xdr/XdrConfigSettingEntry.php	78.57%	18 Missing ⚠️
Soneso/StellarSDK/Xdr/XdrLedgerCloseMetaV1.php	81.60%	16 Missing ⚠️
Soneso/StellarSDK/Xdr/XdrBucketEntry.php	62.50%	15 Missing ⚠️
Soneso/StellarSDK/Xdr/XdrHotArchiveBucketEntry.php	62.50%	15 Missing ⚠️
Soneso/StellarSDK/Xdr/XdrLedgerCloseMetaV2.php	82.89%	13 Missing ⚠️
Soneso/StellarSDK/Xdr/XdrLedgerEntryChange.php	51.85%	13 Missing ⚠️
... and 177 more

Additional details and impacted files

@@             Coverage Diff              @@
##               main      #72      +/-   ##
============================================
+ Coverage     83.89%   85.90%   +2.01%     
- Complexity    10289    15245    +4956     
============================================
  Files           811      982     +171     
  Lines         25263    32772    +7509     
============================================
+ Hits          21194    28153    +6959     
- Misses         4069     4619     +550     

Files with missing lines	Coverage Δ
Soneso/StellarSDK/AssetTypeCreditAlphanum12.php	92.85% <ø> (ø)
Soneso/StellarSDK/AssetTypeCreditAlphanum4.php	92.85% <ø> (ø)
Soneso/StellarSDK/BumpSequenceOperation.php	100.00% <100.00%> (ø)
Soneso/StellarSDK/ChangeTrustOperation.php	100.00% <100.00%> (ø)
Soneso/StellarSDK/FeeBumpTransaction.php	85.71% <100.00%> (+0.42%)	⬆️
Soneso/StellarSDK/Memo.php	98.75% <100.00%> (ø)
Soneso/StellarSDK/SEP/WebAuth/WebAuth.php	85.54% <100.00%> (ø)
Soneso/StellarSDK/Soroban/Address.php	86.11% <100.00%> (ø)
Soneso/StellarSDK/Soroban/SorobanContractInfo.php	96.49% <100.00%> (+0.06%)	⬆️
...oneso/StellarSDK/Soroban/SorobanContractParser.php	71.60% <100.00%> (+0.71%)	⬆️
... and 285 more

... and 198 files with indirect coverage changes

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.

[ngybnc]

Reviewed looks correct.