|
2 | 2 |
|
3 | 3 | A breaking change will get clearly marked in this log. |
4 | 4 |
|
| 5 | +## [v17.0.0-rc.1](https://github.com/stellar/js-stellar-sdk/compare/v16.2.0...v17.0.0-rc.1) |
| 6 | + |
| 7 | +### Breaking Changes |
| 8 | +* Public APIs use `Uint8Array` instead of Node's `Buffer` ([#1457](https://github.com/stellar/js-stellar-sdk/issues/1457)). Methods that returned `Buffer` (e.g. `hash()`, `Keypair`'s `sign`/`rawPublicKey`/`rawSecretKey`, `StrKey.decode*`, `Transaction.hash()`, `rpc.Server.getContractWasmByHash`, `getLiquidityPoolId()`, `AuthEntrySignature.signature`, and the signing payload passed *to* a `SigningCallback`) now return a plain `Uint8Array`, so Buffer-only conveniences like `.toString("hex")` and `.equals()` on results must be replaced — see [`docs/UINT8ARRAY_MIGRATION.md`](./docs/UINT8ARRAY_MIGRATION.md) for method-by-method recipes. Byte inputs still accept `Buffer` (it's a `Uint8Array` subclass), with three exceptions: a `SigningCallback` may no longer resolve to a raw `ArrayBuffer` (wrap it in a `Uint8Array`), `SorobanDataBuilder`'s constructor no longer accepts non-`Uint8Array` typed arrays, and `Memo.text` no longer accepts a plain `number[]` (see the next entry). The `buffer` dependency is gone (`base32.js`, which needed a Buffer global, is replaced by `@exodus/bytes`), and browsers/edge runtimes need no Buffer polyfill. |
| 9 | +* `Memo.text` no longer accepts a plain `number[]`. Pass `new Uint8Array(arr)` instead ([#1457](https://github.com/stellar/js-stellar-sdk/issues/1457)). Through 16.2.0 it took a `string`, a plain array, or a `Buffer`, and rejected a bare `Uint8Array`. A `Uint8Array` is now the canonical byte input, and a plain array is the only input lost. `Memo.text([])` was a valid zero-byte memo and now throws. The error message is unchanged (`Expects string or Uint8Array, max 28 bytes`), so code that matches on it still works. See [`docs/UINT8ARRAY_MIGRATION.md`](./docs/UINT8ARRAY_MIGRATION.md) § 3. |
| 10 | +* The `xdr` namespace is rebuilt on `@stellar/js-xdr` v5, and **every XDR value now has a different API** ([#1422](https://github.com/stellar/js-stellar-sdk/pull/1422)). The wire format is unchanged: bytes and base64 written by older SDKs still decode, and vice versa. Any code that reads or builds `xdr.*` values must be updated. The main shifts: |
| 11 | + * **Start here: [`docs/XDR_MIGRATION.md`](./docs/XDR_MIGRATION.md) covers every change below with before/after examples and a quick-reference table.** |
| 12 | + * Unions are discriminated classes. `.switch()` becomes a `.type` string literal, arm getters like `.contractData()` become properties, and `new xdr.LedgerEntryData(disc, val)` becomes a factory call such as `xdr.LedgerEntryData.contractData(val)`. |
| 13 | + * Enums are singletons, not factory calls: `xdr.ContractDataDurability.persistent()` becomes `xdr.ContractDataDurability.persistent`. |
| 14 | + * Primitives are plain JS values. Integers are `number` or `bigint` instead of class wrappers, `LargeInt` subclasses are gone, byte fields are `Uint8Array`, and fields are `readonly`. |
| 15 | + * Absent optional fields decode to `null` instead of `undefined`, so `=== undefined` checks silently stop matching. Prefer `== null`. |
| 16 | + * Acronyms in method names collapse to single-initial-cap form, with no back-compat aliases (e.g. `validateXDR()` is now `validateXdr()`). This reaches beyond the `xdr` namespace to the wrapper classes: `Transaction.toXDR()`, `TransactionBuilder.fromXDR()`, `Operation.fromXDRObject()`, `Asset.toXDRObject()`, `contract.AssembledTransaction.toXDR()` and others all gained the `Xdr` spelling. |
| 17 | + * Struct field names are unchanged, but a few type names moved: `UInt128Parts` / `UInt256Parts` are now `Uint128Parts` / `Uint256Parts`, `ThresholdIndices` is now `ThresholdIndexes`, and the typedef aliases `Duration`, `TimePoint`, `SequenceNumber`, `ScVec`, `ScMap`, `LedgerEntryChanges`, `ContractCostParams`, `SorobanAuthorizationEntries`, `ScString`, `ScSymbol`, `String32`, `String64`, and `SponsorshipDescriptor` are gone in favor of what they stood for. |
| 18 | + * New: `toJson()` / `fromJson()` for [SEP-0051](https://stellar.org/protocol/sep-51) JSON, `toXdrObject()` / `fromXdrObject()` on XDR values, and `equals()` for structural comparison. Failures throw `xdr.XdrError`, which is now exported. |
| 19 | + * Removed: `Reader` and `Writer`; the v4 runtime type constructors (`Hyper`, `UnsignedHyper`, `Option`, `Opaque`, `VarOpaque`, `XDRArray`, `XDRString`, `Bool`, `SignedInt`, `UnsignedInt`), plus top-level `Hyper` / `UnsignedHyper` / `cereal`; and `xdr.scvSortedMap` (use the top-level `scvSortedMap`). |
| 20 | + * `ScInt` and `XdrLargeInt` lost their `.int` property; read `.value` (a `bigint`) instead, and note `valueOf()` now returns a `bigint`. |
| 21 | + |
| 22 | +* Rebuilding the XDR layer changed a few SDK-level behaviors that don't involve typing `xdr.` yourself. Most of these fail silently, so they won't surface as compile errors ([#1422](https://github.com/stellar/js-stellar-sdk/pull/1422)): |
| 23 | + * [`scValToNative`](https://stellar.github.io/js-stellar-sdk/reference/core-soroban-primitives/#scvaltonative) returns a `Uint8Array` for an `scvString` whose contents aren't valid UTF-8. It previously always returned a string, substituting U+FFFD — its byte-returning branch was unreachable. Guards like `typeof result === "string"` and calls like `result.startsWith(...)` are now data-dependent. (`scvSymbol` follows the same rule, but the host restricts symbols to `[_0-9A-Za-z]`, so a symbol that came off the network always decodes to a string.) The same applies to [`contract.Spec.scValToNative`](https://stellar.github.io/js-stellar-sdk/reference/contracts-client/#specscvaltonativescv-typedef) and [`contract.Spec.funcResToNative`](https://stellar.github.io/js-stellar-sdk/reference/contracts-client/#specfuncrestonativename-val_or_base64) for `Bytes` / `BytesN`, which return `Uint8Array`; those are generically typed, so TypeScript won't flag it. |
| 24 | + * [`Operation.fromXdrObject`](https://stellar.github.io/js-stellar-sdk/reference/core-transactions/#operationfromxdrobjectoperation) decodes `manageData`'s `name`, `setOptions`'s `homeDomain`, and `revokeSponsorship`'s data-entry name as UTF-8 rather than ASCII. Only bytes ≥ `0x80` decode differently, and stellar-core rejects those in all three fields, so no valid operation is affected — but snapshots taken over synthetic or forged XDR will change (`[0xC3, 0xA9]` now decodes to `"é"`, was `"C)"`). See the migration guide for the round-trip details. |
| 25 | + * `SorobanDataBuilder` still chains, and its setters still mutate the builder. What changed is one level down: because XDR fields are `readonly` now, [`setReadOnly`](https://stellar.github.io/js-stellar-sdk/reference/core-soroban-primitives/#sorobandatabuildersetreadonlyreadonly) / [`setReadWrite`](https://stellar.github.io/js-stellar-sdk/reference/core-soroban-primitives/#sorobandatabuildersetreadwritereadwrite) / [`setResources`](https://stellar.github.io/js-stellar-sdk/reference/core-soroban-primitives/#sorobandatabuildersetresourcescpuinstrs-diskreadbytes-writebytes) replace the internal data rather than edit it in place. Two consequences: a footprint you captured from [`getFootprint()`](https://stellar.github.io/js-stellar-sdk/reference/core-soroban-primitives/#sorobandatabuildergetfootprint) before one of those calls is a stale snapshot, so re-read it afterward; and you can no longer configure the builder *through* that object (`builder.getFootprint().readOnly(keys)`) — call the setters instead. |
| 26 | + * [`MuxedAccount.setId`](https://stellar.github.io/js-stellar-sdk/reference/core-transactions/#muxedaccountsetidid) no longer mutates an `xdr.MuxedAccount` you already obtained from `toXdrObject()`; call it again after `setId`. |
| 27 | + |
| 28 | +* `HorizonApi.TransactionFailedExtras`'s `result_codes.operations` is now optional (`operations?: string[]`). Horizon omits the field when a transaction fails a transaction-level check (e.g. `tx_bad_seq`) and no operations were evaluated, so the type now matches the wire format. Under `strictNullChecks`, unguarded reads of the raw response (`extras.result_codes.operations.map(...)`) no longer compile; guard them, or use `TransactionFailedError.getResultCodes()`, which normalizes the omitted field to `[]` ([#1527](https://github.com/stellar/js-stellar-sdk/issues/1527)). |
| 29 | + |
| 30 | +### Added |
| 31 | +- `rpc.Server.getExternalRefWasmHash(ref)`: resolves a CAP-85 external executable reference to the 32-byte Wasm hash it names by reading the persistent tag entry on the owner contract ([#1577](https://github.com/stellar/js-stellar-sdk/pull/1577)). |
| 32 | +- The XDR schema covers [CAP-83](https://stellar.org/protocol/cap-83) (empty transaction set values), adding a `stellarValueEmptyTxSet` arm to `xdr.StellarValueType` ([#1577](https://github.com/stellar/js-stellar-sdk/pull/1577)). |
| 33 | +- The XDR schema covers [CAP-85](https://stellar.org/protocol/cap-85) (external contract executables), adding a `contractExecutableExternalRef` arm to `xdr.ContractExecutableType` — an `executableOwner` address plus a `tag` — and an `scvExecutableTag` arm to `xdr.ScValType` ([#1577](https://github.com/stellar/js-stellar-sdk/pull/1577)). |
| 34 | + |
| 35 | +### Changed |
| 36 | +- `scValToNative` converts an `scvExecutableTag` to its tag: a string when the bytes are valid UTF-8, otherwise the raw bytes (same rule as `scvString`) ([#1577](https://github.com/stellar/js-stellar-sdk/pull/1577)). |
| 37 | +- `buildInvocationTree` renders CAP-85 external-executable creations instead of throwing. `CreateInvocation.type` gains an `"external"` case, whose details live in a new `external` field (`owner`, `tag`, `address`, `salt`, and `constructorArgs` for `CREATE_CONTRACT_V2`). `tag` is `string | Uint8Array` — an executable tag is an unbounded `SCString`, so a binary one is returned as raw bytes rather than lossily decoded ([#1577](https://github.com/stellar/js-stellar-sdk/pull/1577)). |
| 38 | +- `StrKey.decode*` and the underlying `decodeCheck` now validate the encoded string's length against the requested strkey type before decoding it. Two consequences: a long attacker-supplied string is rejected up front instead of driving a full base32 decode plus canonical re-encode, and a strkey whose payload is the wrong size for its type now throws instead of returning a mis-sized buffer (previously, a 37-byte payload encoded as an `ed25519PublicKey` strkey decoded to 37 bytes and only failed later, if at all). Inputs that were already invalid may now report a length error rather than a checksum or version-byte error ([#1583](https://github.com/stellar/js-stellar-sdk/pull/1583)). |
| 39 | +- `contract.Client.from` and `rpc.Server.getContractWasmByContractId` support contracts created from a CAP-85 external executable reference. The reference names an owner contract and a tag; the owner holds a persistent contract data entry keyed by that tag whose value is the Wasm hash, so both methods resolve that entry and then load the Wasm as usual ([#1577](https://github.com/stellar/js-stellar-sdk/pull/1577)). |
| 40 | +- `contract.Client.txFromJSON` is now `txFromJson`, and generated bindings' `fromJSON` is now `fromJson`, matching the `toJson`/`fromJson` naming used across the XDR layer. Both keep a deprecated alias, so existing calls still work ([#1422](https://github.com/stellar/js-stellar-sdk/pull/1422)). |
| 41 | + |
| 42 | +### Fixed |
| 43 | +- `StrKey.decodeSignedPayload` and `StrKey.isValidSignedPayload` now validate the framing inside a `P...` strkey: the declared payload length must be 1-64, must match the number of payload bytes present, and the padding must be zero. The three [SEP-23](https://stellar.org/protocol/sep-23) invalid signed-payload test cases — length prefix shorter than the payload, longer than the payload, and missing zero padding — were previously accepted ([#1588](https://github.com/stellar/js-stellar-sdk/pull/1588)). |
| 44 | +- `StrKey.decodeClaimableBalance` and `StrKey.isValidClaimableBalance` now validate the discriminant byte that leads a `B...` strkey. `CLAIMABLE_BALANCE_ID_TYPE_V0` (0) is the only case `ClaimableBalanceID` declares, so the XDR decoder has always refused anything else — but the strkey checksum covers whatever byte is present, so a `B...` key with an unknown discriminant was decoded and reported valid. |
| 45 | +- The published type declarations no longer reference types the package doesn't provide, so the SDK compiles under `skipLibCheck: false` with no `@types` packages installed. `@types/json-schema` moved from `devDependencies` to `dependencies`, since `contract.Spec.jsonSchema` returns a `JSONSchema7` (previously `Cannot find module 'json-schema'`); and `contract.SentTransaction.Errors`' three error classes are declared instead of inlined, which stops TypeScript emitting their inferred static side and with it a `NodeJS.CallSite` reference from `@types/node` (previously `Cannot find namespace 'NodeJS'`). No runtime or API change ([#1626](https://github.com/stellar/js-stellar-sdk/issues/1626)). |
| 46 | + |
5 | 47 | ## [v16.2.0](https://github.com/stellar/js-stellar-sdk/compare/v16.1.0...v16.2.0) |
6 | 48 |
|
7 | 49 | ### Added |
@@ -44,6 +86,7 @@ A breaking change will get clearly marked in this log. |
44 | 86 | - The UMD (`dist/`) build now sets `inlineDynamicImports` so the single-file bundle stays whole despite the SAC spec's lazy `import()` ([#1501](https://github.com/stellar/js-stellar-sdk/pull/1501)). |
45 | 87 |
|
46 | 88 | ### Fixed |
| 89 | +- `Horizon.ManageDataOperationResponse.value` is now typed as `string`, matching what Horizon actually returns (a base64 string in JSON, which the SDK never decodes). It was previously mistyped as `Buffer` ([#1564](https://github.com/stellar/js-stellar-sdk/pull/1564)). |
47 | 90 | - `Horizon.Server.submitTransaction` and `submitAsyncTransaction` now reject with |
48 | 91 | SDK error types on HTTP failures, as documented: a `TransactionFailedError` for |
49 | 92 | Horizon result codes, a `BadResponseError` otherwise. The wrapping branch used |
|
0 commit comments