v16.0.0-rc.1: Protocol 27

There are a few major updates in this release detailed in the migration guide:

• JS Stellar Base (@stellar/stellar-base) was rewritten
  in TypeScript, which provides proper type definitions and fixes
  inconsistencies caused by manual type declarations. ([#1399])
• JS Stellar Base is now merged into the JS Stellar SDK. Everything lives in one
  place now. ([#1399])
• The JS SDK now has better tree-shaking, which should result in a lighter
  bundle size. ([#1397])
• Protocol 27 support: the XDR was regenerated for CAP-71, and the Soroban
  authorization helpers now build and sign the new address-bound
  (SOROBAN_CREDENTIALS_ADDRESS_V2) and delegated
  (SOROBAN_CREDENTIALS_ADDRESS_WITH_DELEGATES) credential types. ([#1429])

1. Breaking Changes

These break code, builds, or installs until you change something.

Install & runtime

• Drop @stellar/stellar-base from your dependencies if you were importing
  it manually. It is now bundled into @stellar/stellar-sdk. Remove the package
  and switch all imports from @stellar/stellar-base to @stellar/stellar-sdk.
  ([#1399])

• Upgrade to Node 22 or later. engines.node is now >=22.0.0; CI tests
  against [22, 24]. ([#1408])

• Stop using the default import.
  import StellarBase from '@stellar/stellar-sdk' no longer works. Use
  import * as StellarBase or named imports. ([#1396])

• Adjust deep lib/ imports. Library output paths moved:

  • ESM at lib/esm/,
  • CJS at lib/cjs/,
  • axios variants at lib/axios/esm/ and lib/axios/cjs/,
  • type declarations alongside the ESM output at lib/esm/ (e.g.
    lib/esm/index.d.ts).

  The dist/ UMD bundle filenames are unchanged. ([#1397])

• The package.json browser field and browser export conditions were
  removed. Bundlers no longer auto-substitute the prebuilt UMD bundle for the
  package entry — they bundle the ESM/CJS source directly. Load the UMD build
  from its explicit dist/ path if you need it. ([#1396], [#1397])

HTTP client

• Default HTTP client switched from axios to fetch. If you rely on axios
  behavior (interceptors, adapters, regression fallback), import from the
  alternative entry point @stellar/stellar-sdk/axios instead. ([#1394])
• The no-eventsource build variant is gone. eventsource was upgraded to
  v4, which uses fetch internally and works in every supported runtime (Node
  22+, browsers, Deno, Bun, workerd). Remove any no-eventsource
  build/import; the default build covers all environments. ([#1395])
• The /no-axios and /minimal subpath exports are removed, along with
  their /contract and /rpc variants. Axios is now opt-in through the
  @stellar/stellar-sdk/axios family (/axios, /axios/contract,
  /axios/rpc, and @stellar/stellar-sdk/http-client/axios); the minimal build
  no longer exists. ([#1394])
• Horizon.Server.serverURL and rpc.Server.serverURL are now native URL
  objects (and readonly) instead of urijs URI instances. Code that called
  urijs methods on them (server.serverURL.protocol(), .clone(), .segment(),
  .query()) must move to the WHATWG URL API (e.g.
  serverURL.protocol === "https:", serverURL.hostname). ([#1402])

Transaction & TransactionBuilder

• Transaction.minAccountSequenceAge is now bigint. The underlying XDR
  type is 64-bit; consuming code must switch from number to native bigint
  (the runtime value is no longer an xdr.UnsignedHyper object either). ([#1399])

• TransactionBuilder.setMinAccountSequenceAge requires bigint. Pass
  60n instead of 60. TransactionBuilderOptions.minAccountSequenceAge is
  also bigint. ([#1399])

• Transaction.extraSigners is now xdr.SignerKey[]. It always was at
  runtime — only the type was wrong. Use SignerKey.encodeSignerKey() to get
  StrKey strings. ([#1399])

• Transaction is no longer generic. Remove <TMemo, TOps> parameters
  (e.g., Transaction<Memo<MemoType.Text>> no longer compiles). ([#1399])

• Operation.isValidAmount(), Operation.constructAmountRequirementsError(),
  and Operation.setSourceAccount() are no longer on the runtime Operation
  class. JavaScript callers that reached for these need to drop them — they
  remain only as internal helpers in src/base/util/operations.ts. ([#1399])

• Revoke-sponsorship operation type is split into seven strings.
  "revokeSponsorship" is replaced by "revokeAccountSponsorship",
  "revokeTrustlineSponsorship", "revokeOfferSponsorship",
  "revokeDataSponsorship", "revokeClaimableBalanceSponsorship",
  "revokeLiquidityPoolSponsorship", "revokeSignerSponsorship". The runtime
  always returned the specific strings; consumers that switched on type should
  update their cases. ([#1399])

Asset, Keypair, signing helpers

• Asset.code and Asset.issuer are now readonly. Stop mutating them in
  place — construct a new Asset instead. ([#1399])
• Asset.issuer is typed as string | undefined. Native assets have no
  issuer; add nullish checks. ([#1399])
• FastSigning constant removed. Signing now goes through
  @noble/ed25519 exclusively — drop the import. ([#1401])
• TransactionI removed. Use TransactionBase instead. ([#1399])
• authorizeInvocation() takes a single object parameter. Switch from
  authorizeInvocation(signer, validUntilLedgerSeq, invocation, publicKey, networkPassphrase)
  to
  authorizeInvocation({ signer, validUntilLedgerSeq, invocation, networkPassphrase, publicKey }).
  ([#1399])
• authorizeEntry() no longer defaults networkPassphrase to
  Networks.FUTURENET. Pass the network passphrase explicitly at every call
  site. ([#1399])

2. Should know (type-only or behavior changes that may surface)

Won't fail at install. May fail at compile time, or change behavior at runtime,
depending on how you use the API.

TypeScript-only

• CreateInvocation.token renamed to CreateInvocation.asset in the type
  declarations — runtime was already .asset. ([#1399])
• ScIntType adds 'timepoint' and 'duration'. Exhaustive switches on
  ScIntType need new cases. ([#1399])
• XdrLargeInt.getType() returns ScIntType | undefined instead of a raw
  lowercased string; non-integer types yield undefined. ([#1399])
• SorobanDataBuilder.fromXDR return type corrected to
  xdr.SorobanTransactionData. Runtime always returned this — only the type was
  wrong. ([#1399])
• SetOptions.clearFlags / setFlags accept arbitrary numeric bitmasks.
  The type was widened from AuthFlag to AuthFlags (AuthFlag | (number & {})),
  so you can now pass combined flag values without a cast. This is a widening —
  existing code keeps compiling. ([#1399])
• supportMuxing parameter removed from decodeAddressToMuxedAccount /
  encodeMuxedAccountToAddress type declarations. It was silently ignored at
  runtime. ([#1399])

Runtime behavior

• Keypair.rawSecretKey() throws on public-key-only instances with
  Error("no secret seed available") instead of returning undefined. ([#1399])
• TransactionBase.tx returns a defensive copy. External mutation no longer
  affects the transaction that will be signed or serialized. If you were
  intentionally mutating tx, you'll need a different approach. ([#1399])
• TransactionBuilder constructor preserves 0n for
  minAccountSequenceAge instead of coercing falsy values to null. This may
  flip hasV2Preconditions() to true when the field is set to 0n. ([#1399])
• toXDRPrice rejects more bad input earlier. Zero/negative/NaN/
  Infinity numeric prices now throw "price must be positive" before reaching
  best_r(). Zero denominators also rejected (d <= 0). ([#1399])
• Constructor and input validation now throw where the SDK was previously
  lenient. MuxedAccount validates uint64 IDs; Claimant rejects falsy
  destinations; Account rejects NaN sequences; Memo is fully immutable and
  throws on invalid types instead of returning null; Memo.id() rejects
  non-plain-digit strings; allow_trust throws when authorize is missing;
  setTrustLineFlags rejects non-boolean flag values; Asset.getAssetType()
  throws for unknown types instead of returning "unknown". (set_options also
  no longer mutates the caller's signer fields.) ([#1399])
• TransactionBuilder now validates and throws. build() throws on
  total-fee overflow past uint32 max; cloneFrom() throws on zero-operation
  inputs; the constructor rejects negative or inverted timebounds /
  ledgerbounds. ([#1399])
• Operation.setOptions() rejects malformed numeric strings. Flag, weight,
  and threshold fields (setFlags, clearFlags, masterWeight, the signer
  weight, and the *Threshold options) now reject values like "123abc" that
  parseFloat() previously accepted by reading only the leading digits. ([#1399])
• XdrLargeInt / ScInt built from an array of limbs now decode correctly.
  Passing multiple big-endian integer parts (for i128/u128/i256/u256)
  previously wrapped them in a nested array and produced wrong values; the limbs
  are now passed through correctly. ([#1399])
• Large-integer conversions reject out-of-range / malformed input.
  nativeToScVal bounds-checks u32/i32 values and rejects non-numeric
  strings like "123abc"; XdrLargeInt.toI128() / toI256() reject unsigned
  values exceeding the signed range instead of silently flipping the sign bit.
  ([#1399])
• **bignumber.js upgraded to v11; v9's DEBUG guar...

v15.1.0

Fixed

• Security: FederationServer.createForDomain and the FederationServer constructor now validate domains per RFC 1035, rejecting malformed domains before issuing federation or stellar.toml requests. Port numbers are also accepted (#1393).
• RpcServer.pollTransaction off-by-one: the polling loop used < instead of <=, causing one fewer attempt than configured(#1373).
• requestAirdrop error path: fixed incorrect property access (error.response.detail instead of error.response.data.detail) when checking for createAccountAlreadyExist (#1373).
• Spec.typeRef now properly handles scSpecTypeResult by returning the JSON schema for the okType, instead of silently breaking out of the switch (#1373).
• structToJsonSchema now places additionalProperties: false on the schema object itself rather than incorrectly nesting it inside properties (#1373).
• Fixed bigint-to-U32/I32 conversion in Spec using Number(val) instead of val as number (a no-op for bigints) (#1373).
• WASM custom section parser: when a section was skipped (invalid name length), the offset was not advanced, causing an infinite loop or incorrect parsing of subsequent sections (#1373).
• FederationServer URL mutation: resolveAddress, resolveAccountId, and resolveTransactionId mutated the shared serverURL by appending query params on each call. Fixed by cloning the URL before modifying (#1373).
• CallBuilder.stream() URL mutation: stream() mutated the shared this.url by adding query params, corrupting the builder for subsequent calls. Fixed by cloning the URL (#1373).
• AssembledTransaction restore path: when buildWithOp was used and automatic state restoration was needed, the rebuild incorrectly reconstructed the operation via contract.call() instead of reusing the original operation (#1373).
• SERVER_TIME_MAP port collision: the Horizon time-sync cache keyed entries by hostname only, so two servers on different ports of the same host shared a cache entry. Fixed by including the port in the key (#1373).
• Spec.funcResToNative now correctly returns an Err instance when a contract function with a Result return type returns an error, instead of throwing while decoding it as the Ok type (#1373).
• SEP-10: verifyChallengeTxSigners now rejects challenges signed only by the server and client_domain key with no actual client signer, instead of returning an empty signers list (#1372).
• getAssetBalance used incorrect flag bitmask constants (AuthRequiredFlag, AuthRevocableFlag, AuthClawbackEnabledFlag) which are account-level flags, not trustline-level flags. Replaced with the correct trustline flag bitmasks (0x1, 0x2, 0x4) (#1372).
• AssembledTransaction.simulate did not clear this.built before re-simulating after a state restoration rebuild, causing it to assemble stale transaction data (#1372).
• AssembledTransaction.signAndSend mutated the shared this.options.submit flag to prevent double submission. Replaced with a wrapper around signTransaction that injects submit: false without mutating shared state (#1372).
• Fetch HTTP client: async request interceptors were not awaited — the synchronous try/catch loop passed unresolved promise objects as the config. Replaced with a proper .then() chain matching Axios interceptor semantics (#1372).
• Fetch HTTP client: cancellation now preserves custom cancel reasons and isCancel no longer depends on exact error-message text (#1390).
• Fetch HTTP client: instance default headers and params now merge correctly with per-request overrides on the no-axios / minimal builds, including requests that use bounded options (#1390).
• Fetch HTTP client: maxRedirects and maxContentLength were silently ignored on the no-axios / minimal builds, turning SDK-set SSRF and DoS guards (StellarToml.Resolver.resolve, FederationServer) into no-ops. A new bounded adapter activates when either option is set, refusing redirects past maxRedirects and streaming the response body with a running-total check so oversized responses abort mid-stream (#1390).
• Fetch HTTP client: the no-axios bounded path now more closely matches Axios behavior for object request bodies, baseURL, timeout errors, redirect method/body handling, and stripping credential-bearing headers on cross-origin redirects (#1390).
• src/bindings/config.ts imported ../../package.json with a relative path that resolved incorrectly for the lib/no-axios/ and lib/minimal/ build outputs, making those libs unloadable. Replaced with the __PACKAGE_VERSION__ compile-time define (#1390).
• Updated the production axios dependency from 1.14.0 to 1.15.0 (#1381).

Added

• AccountResponse constructor now uses explicit field-by-field assignment instead of Object.entries dynamic assignment for type safety (#1373).
• Added transactions collection to Api.AccountRecord and AccountResponse (#1373).
• Added range checks for U32/I32 values in Spec: bigint values are now validated against min/max bounds before conversion, throwing a RangeError instead of silently truncating (#1373).
• rpc.Server.getLatestLedger() now includes closeTime, headerXdr, and metadataXdr in the typed response, with headerXdr/metadataXdr parsed into XDR objects instead of raw base64 strings (#1389).

Deprecated

• BalanceResponse.revocable is deprecated in favor of authorizedToMaintainLiabilities, which correctly reflects the trustline flag semantics (#1372).

Full Changelog: v15.0.1...v15.1.0

v15.0.1: Protocol 26

Breaking Changes

• XDR has been upgraded to support Protocol 26, please refer to the @stellar/stellar-base release notes for details and other breaking changes.

Fixed

• Sanitize identifiers and escape string literals in generated TypeScript bindings to prevent code injection via malicious contract spec names. sanitizeIdentifier now strips non-identifier characters, and a new escapeStringLiteral helper escapes quotes and newlines in string contexts (#1345).
• AssembledTransaction.fromXDR() and fromJSON() now validate that the deserialized transaction targets the expected contract, rejecting mismatched contract IDs and non-invokeContract operations. (#1349).
• Pin exact version on axios dependency (#1365)

Contributors

• @quietbits, @Ryang-21, @Shaptic

Full Changelog: v14.6.1...v15.0.1

v14.6.1

Fixed

• Fix assembleTransaction double-counting the resource fee when the input transaction already has Soroban data attached (e.g. when re-assembling a previously simulated transaction) (#1343).
• Removed adding resourceFee in rpc.assembleTransaction as it's now handled by TransactionBuilder.build() (#1343).

Full Changelog: v14.6.0...v14.6.1

v14.6.0

Added

• Upgraded underlying @stellar/stellar-base library to include its new features and fixes (release notes).

Full Changelog: v14.5.0...v14.6.0

v14.5.0

Added

• Introduced CLI functionality for generating smart contract bindings (#1287).
• Added BindingGeneration class for parsing contract specs into fully typed TypeScript libraries for calling contract methods (#1287).
• Introduced rpc.Server.fundAddress that supports funding contract and account addresses via Friendbot (#1314).
• Updated the StellarToml interface with SEP 45 fields WEB_AUTH_FOR_CONTRACTS_ENDPOINT and WEB_AUTH_CONTRACT_ID (#1326).

Fixed

• X-App-Name and X-App-Version headers are now included when using CallBuilder.stream() (#1317).
• CallBuilder now correctly uses the configured server URL for all requests, including pagination and linked resources. Previously, URLs returned by Horizon in _links would bypass reverse proxies (#1318).

Deprecated

• rpc.Server.requestAirdrop is deprecated in favor of rpc.Server.fundAddress (#1314).

Contributors

@ElliotFriend, @leighmcculloch, @Ryang-21, @wpalmeri made their first contribution in #1321, and @joaquinsoza made their first contribution in #1314

Full Changelog: v14.4.3...v14.5.0

v14.4.3

Fixed

• Upgraded underlying @stellar/stellar-base library to include its fixes (release notes).

v14.4.2

Fixed

• Fixed package installation for Windows environments (#1306)

Full Changelog: v14.4.1...v14.4.2

v14.4.1

Fixed

• Set Api.GetEventsRequest.endLedger to be optional to align with RPC behavior (#1304)
• Added back Typepoint and marked it deprecated in favor of Timepoint (#1303)

Contributors

• @mootz12 , @Ryang-21

Full Changelog: v14.4.0...v14.4.1

v14.4.0

Added

• Introduced an rpc.Server.getAssetBalance() helper to fetch asset balances both for contracts and accounts (#1286).
• rpc.Api.BalanceResponse now can include a revocable field in its balanceEntry for when trustlines are fetched (#1286).
• Added Timepoint and Duration support to Spec (#1288)
• Api.GetHealthResponse interface now includes latestLedger, ledgerRetentionWindow, and oldestLedger fields (#1297).
• Added publicKey, signTransaction, and signAuthEntry as optional fields to contract.MethodOptions (#1293).

Fixed

• Api.RawEventResponse.topics is now optional to reflect topicless events (#1292).
• parseRawEvents correctly checks if Api.RawEventResponse.topics is undefined (#1292).
• Remove WebAssembly usage in favor of manual wasm parsing (#1300).
• Fixed URL contamination in Horizon.Server methods (#1296).

Contributors

• @chadoh, @corymsmith, @Shaptic, @Ryang-2, @mootz12 made their first contribution in #1288

Full Changelog: v14.3.3...v14.4.0