4.0.0

This release contains everything from 4.0.0-beta0, plus the changes made since. Below is the changelog since 3.1.0.

Breaking changes

• refactor: redesign Auth.Signer to natively support custom account contracts (BLS, WebAuthn / secp256r1, threshold, policy contracts, ...). (#806)

  • Auth.Signer.sign now returns the signature SCVal accepted by the account contract at the credential node being signed — the default Stellar Account shape for a G... account, or whatever a custom account contract's __check_auth expects — instead of an Auth.Signature. The returned value is attached verbatim. This also unlocks signing a custom-contract delegate node of a SOROBAN_CREDENTIALS_ADDRESS_WITH_DELEGATES entry (CAP-71-01).
  • Auth.Signature has been removed.
  • Client-side ed25519 signature verification inside authorizeEntry is removed; the network performs the authoritative check via the account contract's __check_auth (a null return from a Signer is still rejected).
  • Auth.authorizeInvocation(Signer, ...): the publicKey parameter is renamed to address (it already accepted C... contract addresses).
  • New Auth.authorizationPayloadHash(HashIDPreimage) returns the 32-byte payload an account contract receives in __check_auth.
  • New Auth.defaultAccountSignatureScVal builds the default Stellar Account signature shape (Vec<Map{public_key, signature}>), the building block for ed25519 Signers that sign via an HSM or remote service. Two overloads accept either the raw byte[] ed25519 public key or a G... accountId. The KeyPair overloads are unchanged and produce byte-identical output.

  Migration for a custom (non-KeyPair) Signer targeting a classic G... account:

  // before
  Auth.Signer signer =
      preimage -> {
        byte[] payload = Util.hash(preimage.toXdrByteArray());
        return new Auth.Signature(accountId, signRemotely(payload));
      };
  
  // after
  Auth.Signer signer =
      preimage ->
          Auth.defaultAccountSignatureScVal(
              accountId, signRemotely(Auth.authorizationPayloadHash(preimage)));

Update

• feat: add CAP-0071 (Protocol 27) Soroban authorization support. (#804)
  • New credential types (from the Protocol 27 XDR):
    • SOROBAN_CREDENTIALS_ADDRESS_V2 (CAP-71-02) — same fields as the legacy ADDRESS, but the signed payload is bound to the signer's address.
    • SOROBAN_CREDENTIALS_ADDRESS_WITH_DELEGATES (CAP-71-01) — delegated / multi-party signing via a (possibly nested) tree of delegate signatures.
  • Auth.authorizeEntry:
    • Signs all three address-based credential types, selecting the signature payload from the credential type: legacy ADDRESS keeps the non-address-bound preimage; ADDRESS_V2 and ADDRESS_WITH_DELEGATES sign the new address-bound ENVELOPE_TYPE_SOROBAN_AUTHORIZATION_WITH_ADDRESS preimage.
    • Gains an optional forAddress parameter that writes the signature into a specific (possibly nested) delegate node. All signers of one delegated entry sign the same payload, bound to the top-level address.
  • Auth.authorizeInvocation:
    • Still builds legacy ADDRESS entries by default, so its output stays valid on every network regardless of protocol 27 activation.
    • New credentialsType overloads opt in to ADDRESS_V2. The default will flip to V2 once Protocol 28 makes it mandatory.
  • New helpers in Auth:
    • buildAuthorizationEntryPreimage — builds the exact payload a signer must sign for a given entry.
    • buildWithDelegatesEntry / Auth.DelegateSignature — wrap an ADDRESS/ADDRESS_V2 entry together with delegate signers, sorting each delegates level by address and rejecting duplicates, as the protocol requires.
    • getAddressCredentials — extracts the inner SorobanAddressCredentials from any address-based credential type.
  • AssembledTransaction: signAuthEntries and needsNonInvokerSigningBy handle all address-based credential types.
  • SEP-45 (Sep45Challenge):
    • Challenge parsing and building accept ADDRESS_V2 entries in addition to the legacy type; delegated entries are rejected.
    • Challenge building fails fast on unsupported credential types instead of passing the entries through unsigned.
• feat: add useUpgradedAuth to SorobanServer.simulateTransaction, mapping to the useUpgradedAuth flag from Stellar RPC v27.1.0 to opt simulation into recording ADDRESS_V2 (CAP-71) auth credentials. Best-effort and transitional; older RPC servers ignore it. (#807)
• chore: upgrade generated XDR definitions to Protocol 27. (#800)
• chore: update dependencies and build tooling to the latest compatible versions (Gradle 9.6.1, Kotlin 2.4.0, Spotless plugin 8.7.0, Lombok plugin 9.5.0, NMCP plugin 1.6.0, Gson 2.14.0, Commons Codec 1.22.0). (#808)

4.0.0-beta0

Update

• chore: upgrade generated XDR definitions to Protocol 27. (#800)
• feat: add CAP-0071 (Protocol 27) Soroban authorization support. (#804)
  • New credential types (from the Protocol 27 XDR):
    • SOROBAN_CREDENTIALS_ADDRESS_V2 (CAP-71-02) — same fields as the legacy ADDRESS, but the signed payload is bound to the signer's address.
    • SOROBAN_CREDENTIALS_ADDRESS_WITH_DELEGATES (CAP-71-01) — delegated / multi-party signing via a (possibly nested) tree of delegate signatures.
  • Auth.authorizeEntry:
    • Signs all three address-based credential types, selecting the signature payload from the credential type: legacy ADDRESS keeps the non-address-bound preimage; ADDRESS_V2 and ADDRESS_WITH_DELEGATES sign the new address-bound ENVELOPE_TYPE_SOROBAN_AUTHORIZATION_WITH_ADDRESS preimage.
    • Gains an optional forAddress parameter that writes the signature into a specific (possibly nested) delegate node. All signers of one delegated entry sign the same payload, bound to the top-level address.
  • Auth.authorizeInvocation:
    • Still builds legacy ADDRESS entries by default, so its output stays valid on every network regardless of protocol 27 activation.
    • New credentialsType overloads opt in to ADDRESS_V2. The default will flip to V2 once Protocol 28 makes it mandatory.
  • New helpers in Auth:
    • buildAuthorizationEntryPreimage — builds the exact payload a signer must sign for a given entry.
    • buildWithDelegatesEntry / Auth.DelegateSignature — wrap an ADDRESS/ADDRESS_V2 entry together with delegate signers, sorting each delegates level by address and rejecting duplicates, as the protocol requires.
    • getAddressCredentials — extracts the inner SorobanAddressCredentials from any address-based credential type.
  • AssembledTransaction: signAuthEntries and needsNonInvokerSigningBy handle all address-based credential types.
  • SEP-45 (Sep45Challenge):
    • Challenge parsing and building accept ADDRESS_V2 entries in addition to the legacy type; delegated entries are rejected.
    • Challenge building fails fast on unsupported credential types instead of passing the entries through unsigned.

3.1.0

Update

• fix: make RootRequestBuilder request the Horizon root endpoint as / instead of the percent-encoded /%2F path. (#801)
• fix: make Horizon request builder URL generation idempotent so repeated buildUri() or execute() calls on the same builder do not duplicate path segments. (#798)
• docs: add an Agent Skill for the Java Stellar SDK under skills/, plus Claude Code plugin manifests in .claude-plugin/. The skill gives AI coding agents concise, Stellar-specific guidance (transactions, operations, Horizon, Soroban, XDR/SCVal, and SEP protocols) when generating application code with stellar-sdk. (#797)
• feat: add SEP-0046, SEP-0047, and SEP-0048 contract introspection support. New ContractMeta, ContractSpec, and ContractInfo wrappers under org.stellar.sdk.contract parse contract Wasm metadata and interface specs locally. SorobanServer adds getContractWasm, getContractWasmByHash, getContractMeta, getContractSpec, and getContractInfo for RPC-backed retrieval. (#796)

3.0.0

This release contains the exact same content as 3.0.0-beta1. Below is the changelog since 2.2.3.

Update

• fix: use OkHttp's public SSE factory for Horizon streams and force SSE requests to bypass caches. (#791)
• feat: sort ScMap entries by key in Scv.toMap following Soroban runtime ordering rules, as the network requires ScMap keys to be in ascending order. Scv.toMap now accepts Map<SCVal, SCVal>; the previous toMap(LinkedHashMap<SCVal, SCVal>) overload is deprecated. (#766)
• feat: add SEP-0051 support. (#774)
• feat: add closeTime, headerXdr, and metadataXdr to GetLatestLedgerResponse. (#768)
• chore: update various dependencies to the latest compatible versions. (#786, #790)
• docs: add more detailed API and XDR generator documentation. (#783, #784)
• chore: building the project from source now requires JDK 21 and Gradle 9.4.1. Published SDK artifacts still target Java 8 bytecode. (#788, #789)
• chore: bump generated XDR definitions to stellar-xdr v26.0, including the v25.0 changes introduced earlier in this release cycle. (#769, #781)

Breaking changes

• refactor!: remove deprecated StrKey helpers encodeEd25519PublicKey(AccountID), encodeMuxedAccount(MuxedAccount), decodeMuxedAccount(String), encodeToXDRAccountId(String), and encodeToXDRMuxedAccount(String); use StrKey.encodeEd25519PublicKey(byte[]), org.stellar.sdk.MuxedAccount, and KeyPair#getXdrAccountId() instead. (#779)

3.0.0-beta1

Update

• chore: re-release of 3.0.0-beta0; no SDK changes. The prior tag failed to reach Maven Central because the release workflow still invoked the old publishAggregationToCentralPortal task name after the nmcp plugin switch.

3.0.0-beta0

Update

• fix: use OkHttp's public SSE factory for Horizon streams and force SSE requests to bypass caches. (#791)
• feat: sort ScMap entries by key in Scv.toMap following Soroban runtime ordering rules, as the network requires ScMap keys to be in ascending order. Scv.toMap now accepts Map<SCVal, SCVal>; the previous toMap(LinkedHashMap<SCVal, SCVal>) overload is deprecated. (#766)
• feat: add SEP-0051 support. (#774)
• feat: add closeTime, headerXdr, and metadataXdr to GetLatestLedgerResponse. (#768)
• chore: update various dependencies to the latest compatible versions. (#786, #790)
• docs: add more detailed API and XDR generator documentation. (#783, #784)
• chore: building the project from source now requires JDK 21 and Gradle 9.4.1. Published SDK artifacts still target Java 8 bytecode. (#788, #789)
• chore: bump generated XDR definitions to stellar-xdr v26.0, including the v25.0 changes introduced earlier in this release cycle. (#769, #781)

Breaking changes

• refactor!: remove deprecated StrKey helpers encodeEd25519PublicKey(AccountID), encodeMuxedAccount(MuxedAccount), decodeMuxedAccount(String), encodeToXDRAccountId(String), and encodeToXDRMuxedAccount(String); use StrKey.encodeEd25519PublicKey(byte[]), org.stellar.sdk.MuxedAccount, and KeyPair#getXdrAccountId() instead. (#779)

2.2.3

Update

• fix: replace commons-codec Hex with pure-Java implementation in Util to fix NoSuchMethodError crash on Android API 24-27. (#763)
• refactor!: remove InvokeHostFunctionOperation.createStellarAssetContractOperationBuilder(Address, byte[]), use InvokeHostFunctionOperation.createContractOperationBuilder instead. (#764)

2.2.2

Update

• fix: add stricter validation for Ed25519 Signed Payload. (#751)
• fix: replace assert statements with explicit null checks in Federation class to ensure validation is not bypassed when assertions are disabled. (#752)
• fix: add overflow check in TimeBounds.expiresAfter() to prevent integer overflow when timeout is too large. (#753)
• fix: add validation for ManageDataOperation value length to ensure it does not exceed 64 bytes. (#754)
• fix: use StandardCharsets.UTF_8 explicitly when converting byte arrays to strings to ensure consistent behavior across different platforms. (#756)
• refactor: use static initialization for GsonSingleton to ensure thread safety. (#757)
• fix: use commons-codec for hex encoding/decoding in Util class to properly validate input and throw clear exceptions for invalid hex strings. (#758)
• fix: improve XDR decoding security and correctness. (#759)
  • Add decoding depth limit to prevent stack overflow (default: 200)
  • Add input length tracking to prevent DoS via oversized allocations
  • Validate variable-length array/opaque/string sizes before allocation
  • Validate variable-length types don't exceed declared max size
  • Validate fixed-length opaque/array sizes match declared size
  • Fix short read handling for opaque/string with proper padding
  • Remove incorrect auto-padding from read(byte[], int, int)
  • Reject unknown union discriminant values when no default arm
  • Validate boolean/optional flags are strictly 0 or 1 per RFC 4506
  • Fix EOF handling in single-byte read
  • Deprecate unsafe readIntArray/readFloatArray/readDoubleArray methods
• fix: prevent DoS attacks in Federation by limiting stellar.toml and federation response sizes to 100KB, adding proper timeouts, and handling UTF-8 BOM. (#760)

2.2.1

Update:

• fix: KeyPair.fromPublicKey now accepts any 32-byte public key, even if it is not a valid Ed25519 public key point (e.g., all zeros like GAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAWHF). Such keypairs can still be used for address representation but will throw IllegalStateException when attempting to verify signatures.

2.2.0

Update:

• feat: add AUTH_CLAWBACK_ENABLED_FLAG to AccountFlag. (#743)
• fix: remove diagnosticEventsXdr from org.stellar.sdk.responses.sorobanrpc.Events. Use GetTransactionResponse.diagnosticEventsXdr and GetTransactionsResponse.Transaction.diagnosticEventsXdr instead. (#744)
• feat: add SEP-45 (Stellar Web Authentication for Contract Accounts) support. Check Sep45Challenge class for more details. (#746)
• chore: update outdated documentation.