Release 16.0.0-beta

16.0.0-beta0

Pre-release. First beta of the 16.0 line — a large major release. It upgrades the XDR layer to Protocol 27 (CAP-71 Soroban auth), adds SEP-45 (web authentication for contract accounts), overhauls HTTP retry, and tightens System.Text.Json and XDR binary decoding. Because of the breaking changes below, the next stable release is a major version bump. Please test against Testnet/Futurenet and report issues before stable 16.0.0.

Breaking Changes

• Soroban credential API reshaped for CAP-71 (part of Protocol 27, #187):
  • SorobanCredentials.ToXdr() is now abstract (was a concrete method that switched on the runtime type). Any external subclass of SorobanCredentials must now override ToXdr().
  • Removed SorobanSourceAccountCredentials.ToSorobanCredentialsXdr() and SorobanAddressCredentials.ToSorobanCredentialsXdr(). Call ToXdr() instead — it produces the same XDR via the new abstract/override pair.
  • SorobanCredentials, SorobanSourceAccountCredentials, and SorobanAddressCredentials moved from InvokeHostFunctionOperation.cs into a new SorobanCredentials.cs. They stay in the StellarDotnetSdk.Operations namespace, so using-based and fully-qualified references are unaffected.
• HTTP retry overhaul (#184):
  • ForSorobanPolling() is deprecated — it is now an [Obsolete] alias for the new ForSoroban(). Rename your call sites.
  • ForSoroban() and the new ForHorizon() presets now retry transient HTTP status codes (408/429/500/502/503/504) on POST — including Stellar RPC JSON-RPC calls and Horizon SubmitTransaction() — not just connection failures as before. This is safe because Stellar submission is idempotent (each envelope is keyed by transaction hash + source-account sequence, so a resubmit returns the cached result or fails with tx_bad_seq). The Retry-After header is honored, capped by MaxRetryAfterDelay (default 1 minute).
  • New typed exceptions TooManyRequestsException (HTTP 429) and ServiceUnavailableException (HTTP 503) are now thrown for those responses — update any code that previously caught the generic HTTP exception for 429/503.
  • New HttpResilienceOptions knobs: RetryHttpStatusCodes, RetryHttpMethods (defaults to the safe methods GET/HEAD/OPTIONS — add HttpMethod.Post to retry POST), RespectRetryAfter, and MaxRetryAfterDelay.
  • Do not wire the Soroban/Horizon presets into SEP service clients — SEP-10 POST /auth, SEP-24 interactive POSTs, and SEP-6 are non-idempotent. Use WithConnectionRetries() or a custom HttpResilienceOptions limited to safe methods there.
• Stricter XDR binary decoding (#189, addresses #165): XdrDataInputStream scalar reads now throw EndOfStreamException (was IndexOutOfRangeException) on truncated input. Update any catch clauses that relied on the old exception type.
• Duplicate JSON properties are now rejected (#181, addresses #166): JsonSerializerOptions.AllowDuplicateProperties is set to false, so a payload containing duplicate property names now throws a JsonException instead of silently keeping the last value. Well-formed Horizon/RPC responses are unaffected; this hardens parsing against ambiguous / parser-differential input.
• Shared JsonSerializerOptions are now read-only (#183, addresses #168): the SDK's shared serializer options are frozen via JsonSerializerOptions.MakeReadOnly(). If you mutated those shared options at runtime (e.g. adding a converter to the SDK's instance), that now throws InvalidOperationException — clone the options before modifying.

Features

• Protocol 27 (CAP-71) Soroban authorization (#187, implements #186):
  • XDR upgraded to the Protocol 27 schema (stellar-xdr@68fa1ac).
  • New address-bound credential types:
    • SorobanAddressCredentialsV2 — SOROBAN_CREDENTIALS_ADDRESS_V2 (CAP-71-02). Same fields as the legacy ADDRESS, but the signature is computed over the new ENVELOPE_TYPE_SOROBAN_AUTHORIZATION_WITH_ADDRESS preimage, binding the credential to the signer's address and preventing cross-account signature replay.
    • SorobanAddressCredentialsWithDelegates, SorobanDelegateSignature, and SorobanDelegatedRoot — SOROBAN_CREDENTIALS_ADDRESS_WITH_DELEGATES (CAP-71-01) for delegated / multi-party signing via a (possibly nested) tree of delegate signatures.
  • Signing helpers on SorobanAuthorization: AuthorizeEntry, AuthorizeEntryWithDelegates, BuildWithDelegatesEntry, BuildAuthorizationEntryPreimageHash, plus the lower-level BuildAuthPreimageHash / BuildAddressAuthPreimageHash. The preimage is selected from the credential type — legacy ADDRESS keeps the non-address-bound preimage; ADDRESS_V2 and delegated entries sign the address-bound preimage.
  • ISorobanEntrySigner abstraction with a built-in KeyPairEntrySigner (classic Ed25519), so custom-account (__check_auth) signers can be plugged in.
  • SorobanCredentialsVersion (Preserve / V1 / V2) controls the emitted credential type. It defaults to Preserve (keeps the entry's existing variant), so output stays valid on pre-Protocol-27 networks; opt in to V2 explicitly. The default is expected to flip to V2 once Protocol 28 makes it mandatory.
  • Delegated entries sort each delegate level by address and reject duplicates, as the protocol requires.
  • Signing output is verified byte-for-byte against @stellar/stellar-sdk@16.0.0-rc.1 via known-answer vectors (StellarDotnetSdk.Tests/TestData/generate-p27-auth-kat.mjs).
  • Not included: the simulateTransaction authV2 RPC flag from the original Protocol 27 plan is intentionally deferred — that RPC change is unconfirmed upstream (see #188).
• SEP-45: Web Authentication for Contract Accounts (#190, implements #160):
  • ClientWebAuthContract — end-to-end client flow for authenticating a contract (C…) account: FromDomainAsync (discover the web-auth contract from a home domain) → GetChallengeAsync → ValidateChallenge → SignAuthorizationEntriesAsync → SendSignedChallengeAsync → JwtTokenAsync.
  • Sep45Challenge — static helpers to parse, validate, verify, and build challenges, including the web_auth_verify invocation hash that signers sign.
  • Hardened against hostile servers: the challenge decoder caps input size (MaxChallengeXdrBytes, 64 KiB) and entry count to bound decode-time allocation.
  • Typed validation exceptions (InvalidServerSignatureException, InvalidNonceException, InvalidWebAuthDomainException, InvalidClientDomainException, …) for precise failure handling.

Bug Fixes

• Handle contract_credited / contract_debited effects in responses (#179, fixes #172) — these effect types previously had no response mapping.
• Fix the documentation build (#178).

Documentation

• Add SEP compatibility matrices (#191).

Maintenance

• Enable RespectNullableAnnotations for JSON deserialization (#182, addresses #167) — non-nullable reference-type properties are now enforced during deserialization, surfacing malformed payloads earlier.
• Use FrozenDictionary for static lookup tables in the JSON converters (#180, addresses #164) — faster, allocation-free lookups on the JSON hot path. Internal; no API change.
• Add an integration test suite, phase 1 (#185) — new Testnet-backed StellarDotnetSdk.IntegrationTests project. Development-only; not shipped in the NuGet package.

Full Changelog: 15.1.0...16.0.0-beta0

Release 15.1.0

Changes

Features

• feat: add SDK types for v26 frozen ledger keys and trustline-frozen results @cuongph87 (#177)
• feat: migrate XDR generator from xdrgen @cuongph87 (#169)

Maintenance

• chore: bump stellar-xdr to v26 @cuongph87 (#176)
• chore: regenerate XDR classes using the latest XDR generator @cuongph87 (#170)

Contributors

@cuongph87 and @jopmiddelkamp

Release 15.1.0-beta

Changes

Features

• feat: add SDK types for v26 frozen ledger keys and trustline-frozen results @cuongph87 (#177)
• feat: migrate XDR generator from xdrgen @cuongph87 (#169)

Maintenance

• chore: bump stellar-xdr to v26 @cuongph87 (#176)
• chore: regenerate XDR classes using the latest XDR generator @cuongph87 (#170)

Contributors

@cuongph87 and @jopmiddelkamp

Release 15.0.0

Changes

Breaking Changes

• feature!: improve Operation response classes @cuongph87 (#119)
• feature!: improve Effect response classes @cuongph87 (#117)
• fix!: TransactionResponse class @cuongph87 (#103)
• fix!: ClaimableBalanceResponse class @cuongph87 (#102)
• fix!: TradeAggregationResponse class @cuongph87 (#101)
• fix!: LedgerResponse class @cuongph87 (#100)
• Convert Json.NET to System.Text.Json @cuongph87 (#20)

Features

• feature: SEP-24 @jopmiddelkamp (#134)
• feature: SEP-6 @jopmiddelkamp (#133)
• feature: SEP-10 @jopmiddelkamp (#132)
• feature: SEP-9 @jopmiddelkamp (#131)
• feature: SEP-1 @jopmiddelkamp (#129)
• feature!: improve Operation response classes @cuongph87 (#119)
• feature!: improve Effect response classes @cuongph87 (#117)
• feature: issue #82 retry @jopmiddelkamp (#89)
• Convert Json.NET to System.Text.Json @cuongph87 (#20)

Bug Fixes

• fix: typos @cuongph87 (#149)
• fix: missing XML docs for HealthRequestBuilder @cuongph87 (#147)
• fix: Price type inconsistencies @cuongph87 (#111)
• fix: TradeResponse class @cuongph87 (#108)
• fix: RootResponse class @cuongph87 (#107)
• fix: type inconsistencies for muxed_id properties @cuongph87 (#113)
• fix: type inconsistencies for date time properties @cuongph87 (#115)
• fix: LiquidityPoolResponse class @cuongph87 (#106)
• fix: AccountResponse class @cuongph87 (#104)

Documentation

• docs: added missing docs @jopmiddelkamp (#144)

Maintenance

• chore: version bump workflow action @cuongph87 (#154)
• chore: improve release labeler @cuongph87 (#152)
• chore: extend example app @cuongph87 (#150)
• refactor: unit tests @cuongph87 (#148)
• chore: improve release drafter @cuongph87 (#146)
• chore: add pull request autolabeler @cuongph87 (#145)
• chore: complete Horizon matrix parity @cuongph87 (#139)
• chore: rename Soroban RPC to Stellar RPC @cuongph87 (#143)
• chore: complete RPC matrix parity @cuongph87 (#140)
• chore: update urls @cuongph87 (#142)
• chore: update public API XML docs @cuongph87 (#141)
• chore: response results unit test coverage @jopmiddelkamp (#128)
• chore: request unit test coverage @jopmiddelkamp (#126)
• chore: operations unit test coverage @jopmiddelkamp (#125)
• chore: operations unit test coverage @jopmiddelkamp (#124)
• chore: unit test naming and docs @jopmiddelkamp (#122)
• chore: added unit test coverage for assets @jopmiddelkamp (#121)
• chore: add Soroban examples @cuongph87 (#120)

Contributors

@cuongph87 and @jopmiddelkamp

Full Changelog: 14.0.1...15.0.0

Release 14.0.1

fix: use meta.V4.SorobanMeta?.ReturnValue instead of V3 in TransactionInfo

Release 14.0.0

This release adds support for Protocol 23.

Update:

• feat: add support for Muxed_Ed25519 public keys, liquidity pools and claimable balances to StrKey (#71)
• feat: add support for PreAuthTx and SHA256 hashes to StrKey (#71)
• feat: add new variants of ScAddress including muxed accounts, liquidity pools and claimable balances (#72)
• feat: add IsValid* functions to StrKey to help with checking the validity of the corresponding key types (#71)
• feat: add DestinationMuxedId and DestinationMuxedIdType to InvokeHostFunctionOperationResponse.AssetContractBalanceChange (#65)
• feat: update SorobanServer#SimulateTransaction to add support for non-root authorization (#68)
• feat: update LedgerEntryChange to support the new LEDGER_ENTRY_RESTORED variant (#75)
• feat: add support for TransactionMetaV4, OperationMetaV2, SorobanTransactionMetaV2, TransactionEvent (#77)
• feat: add OldestLedger, LatestLedgerCloseTime and OldestLedgerCloseTime fields to GetEventsResponse (#69)
• feat: add TransactionIndex and OperationIndex fields to GetEventsResponse.EventInfo (#69)
• refactor: add Events field to TransactionInfo (#67)
• feat: add new variants of LedgerEntryConfigSetting: (#70)
  • ConfigSettingContractLedgerCostExtV0
  • ConfigSettingContractParallelComputeV0
  • ConfigSettingScpTiming
• feat: add utility class ClaimableBalanceIdUtils with functions to handle claimable balance ID conversion between formats (#78)
• feat: add support for retrieving related referencing a given liquidity pool in OperationsRequestBuilder.

Breaking changes:

• chore: update XDR definitions for Protocol 23 (#63)
• refactor: rename SorobanResources.ReadBytes to DiskReadBytes (#64)
• refactor: remove the deprecated field GetEventsResponse.EventInfo.PagingToken (#69)
• refactor: mark GetEventsResponse.EventInfo.InSuccessfulContractCall field as deprecated. It will be removed in the next release (#69)
• refactor: rename the following SCAddress to follow standard naming conventions:
  • SCAddress to ScAddress
  • SCAccountId to ScAccountId
  • SCContractId to ScContractId
• chore: remove ConfigSettingBucketListSizeWindow (#70)
• refactor: mark the following functions in StrKey as deprecated, they will be removed in the next major release. Please refer to the documentation for each function to see the corresponding replacement functions: (#71)
  • StrKey#EncodeStellarAccountId(byte[])
  • StrKey#EncodeStellarSecretSeed(byte[])
  • StrKey#EncodeStellarMuxedAccount(MuxedAccount)
  • StrKey#DecodeStellarAccountId(string)
  • StrKey#DecodeStellarSecretSeed(string)
  • StrKey#DecodeStellarMuxedAccount(string)
  • StrKey#IsValidMuxedAccount(string)
• refactor: mark TransactionInfo.DiagnosticEventsXdr field as deprecated. It will be removed in Stellar RPC soon. Use TransactionInfo.Events.DiagnosticEventsXdr instead (#67)
• refactor: move ContractEvent.Topics and ContractEvent.Data fields to ContractEvent.ContractEventV0 field to align with the XDR version and improve future-proofing (#77)
• refactor: change the type of TransactionInfo.TransactionMeta from TransactionMetaV3 to TransactionMeta to align with the XDR version and improve future-proofing (#77)
• refactor: update the following claimable balance related classes and fields for better ID handling:
  • Type changes:
    • Change LedgerEntryClaimableBalance.BalanceId field from byte[] to string
    • Change LedgerKeyClaimableBalance.BalanceId field from byte[] to string
    • Change CreateClaimableBalanceSuccess constructor to accept string instead of byte[]
  • Behavior changes:
    • CreateClaimableBalanceSuccess.BalanceId now returns a complete claimable balance ID
    • The following functions now correctly accept complete claimable balance IDs (0000...) instead of V0 IDs (without leading zeroes):
    • LedgerKeyClaimableBalance(string) constructor
    • LedgerKey#ClaimableBalance(string)
    • RevokeLedgerEntrySponsorshipOperation.ForClaimableBalance(string)
  • Removals:
    • Remove ClaimClaimableBalanceOperation.BalanceIdInBytes field
    • Remove ClawbackClaimableBalanceOperation.BalanceIdInBytes field
    • Remove LedgerKey#ClaimableBalance(byte[]) method
    • Remove LedgerKeyClaimableBalance(byte[]) constructor

Full Changelog: 13.2.1...14.0.0

14.0.0-beta

Update:

• feat: add support for Muxed_Ed25519 public keys, liquidity pools and claimable balances to StrKey (#71)
• feat: add support for PreAuthTx and SHA256 hashes to StrKey (#71)
• feat: add new variants of ScAddress including muxed accounts, liquidity pools and claimable balances (#72)
• feat: add IsValid* functions to StrKey to help with checking the validity of the corresponding key types (#71)
• feat: add DestinationMuxedId and DestinationMuxedIdType to InvokeHostFunctionOperationResponse.AssetContractBalanceChange (#65)
• feat: update SorobanServer#SimulateTransaction to add support for non-root authorization (#68)
• feat: update LedgerEntryChange to support the new LEDGER_ENTRY_RESTORED variant (#75)
• feat: add support for TransactionMetaV4, OperationMetaV2, SorobanTransactionMetaV2, TransactionEvent (#77)
• feat: add OldestLedger, LatestLedgerCloseTime and OldestLedgerCloseTime fields to GetEventsResponse (#69)
• feat: add TransactionIndex and OperationIndex fields to GetEventsResponse.EventInfo (#69)
• refactor: add Events field to TransactionInfo (#67)
• feat: add new variants of LedgerEntryConfigSetting: (#70)
  • ConfigSettingContractLedgerCostExtV0
  • ConfigSettingContractParallelComputeV0
  • ConfigSettingScpTiming
• feat: add utility class ClaimableBalanceIdUtils with functions to handle claimable balance ID conversion between formats (#78)
• feat: add support for retrieving related referencing a given liquidity pool in OperationsRequestBuilder.

Breaking changes:

• chore: update XDR definitions for Protocol 23 (#63)
• refactor: rename SorobanResources.ReadBytes to DiskReadBytes (#64)
• refactor: remove the deprecated field GetEventsResponse.EventInfo.PagingToken (#69)
• refactor: mark GetEventsResponse.EventInfo.InSuccessfulContractCall field as deprecated. It will be removed in the next release (#69)
• refactor: rename the following SCAddress to follow standard naming conventions:
  • SCAddress to ScAddress
  • SCAccountId to ScAccountId
  • SCContractId to ScContractId
• chore: remove ConfigSettingBucketListSizeWindow (#70)
• refactor: mark the following functions in StrKey as deprecated, they will be removed in the next major release. Please refer to the documentation for each function to see the corresponding replacement functions: (#71)
  • StrKey#EncodeStellarAccountId(byte[])
  • StrKey#EncodeStellarSecretSeed(byte[])
  • StrKey#EncodeStellarMuxedAccount(MuxedAccount)
  • StrKey#DecodeStellarAccountId(string)
  • StrKey#DecodeStellarSecretSeed(string)
  • StrKey#DecodeStellarMuxedAccount(string)
  • StrKey#IsValidMuxedAccount(string)
• refactor: mark TransactionInfo.DiagnosticEventsXdr field as deprecated. It will be removed in Stellar RPC soon. Use TransactionInfo.Events.DiagnosticEventsXdr instead (#67)
• refactor: move ContractEvent.Topics and ContractEvent.Data fields to ContractEvent.ContractEventV0 field to align with the XDR version and improve future-proofing (#77)
• refactor: change the type of TransactionInfo.TransactionMeta from TransactionMetaV3 to TransactionMeta to align with the XDR version and improve future-proofing (#77)
• refactor: update the following claimable balance related classes and fields for better ID handling:
  • Type changes:
    • Change LedgerEntryClaimableBalance.BalanceId field from byte[] to string
    • Change LedgerKeyClaimableBalance.BalanceId field from byte[] to string
    • Change CreateClaimableBalanceSuccess constructor to accept string instead of byte[]
  • Behavior changes:
    • CreateClaimableBalanceSuccess.BalanceId now returns a complete claimable balance ID
    • The following functions now correctly accept complete claimable balance IDs (0000...) instead of V0 IDs (without leading zeroes):
    • LedgerKeyClaimableBalance(string) constructor
    • LedgerKey#ClaimableBalance(string)
    • RevokeLedgerEntrySponsorshipOperation.ForClaimableBalance(string)
  • Removals:
    • Remove ClaimClaimableBalanceOperation.BalanceIdInBytes field
    • Remove ClawbackClaimableBalanceOperation.BalanceIdInBytes field
    • Remove LedgerKey#ClaimableBalance(byte[]) method
    • Remove LedgerKeyClaimableBalance(byte[]) constructor

Full Changelog: 13.2.0...14.0.0

Release 13.2.1

What's Changed

• fix: SubmitTransactionAsync throwing exception for valid HTTP 201 responses #61 by @cuongph87 in #76

Full Changelog: 13.2.0...13.2.1

Release 13.2.0

Changes

• Improve WebAuthentication: @cuongph87 (#60)
  • Better naming and extracted helper methods for clearer logic flow and better readability
  • Removed unnecessary operations and improved variable usage for improved performance
  • Replaced obsoleted RandomGenerator with the recommended RandomNumberGenerator
  • Time-bounds verification now uses UTC by default
  • ReadChallengeTransaction, VerifyChallengeTransactionSigners and related helpers will evaluate the TimeBounds window against DateTimeOffset.UtcNow when the now argument is not supplied.
    This eliminates false positives/negatives on hosts with a mis-configured time-zone or during DST transitions.
    If your application intentionally needs to evaluate the window against local wall-clock time, pass DateTimeOffset.Now explicitly.
• Correct paths to example classes @cuongph87 (#58)

Release 13.1.4

Changes

• Update .NET SDK version in global.json @cuongph87 (#57)