@stellar/typescript-wallet-sdk 4.0.1 → 5.0.0-beta.1788982897683

package/CHANGELOG.MD

@@ -1,3 +1,30 @@
+# Release notes - Typescript Wallet SDK - 5.0.0
+
+### BREAKING CHANGES
+* Upgraded `@stellar/stellar-sdk` from `16.2.0` to `17.0.1` — Protocol 28 support
+* Minimum Node.js version raised from 22 to 22.12.0, as required by stellar-sdk v17
+* **Minimum TypeScript 5.7** for consumers compiling against our type declarations — v17's typings use the generic `Uint8Array<ArrayBufferLike>` form, and `Uint8Array` only became generic in the TypeScript 5.7 lib
+* Byte-valued public inputs widen from `Buffer` to `Uint8Array` (`AccountService.createKeypairFromRandom`, `CustomerBinaryInfoMap`, the `Customer.add`/`update` SEP-9 binary maps). Source-compatible for existing callers, because `Buffer` is a `Uint8Array` — **but only on `@types/node` >= 20**. Against an older `@types/node`, `Buffer` is not assignable to `Uint8Array<ArrayBufferLike>` and unchanged call sites will fail to compile, so `@types/node` >= 20 is a precondition for that compatibility promise
+* **`btoa`/`atob` are now a runtime requirement for base64.** stellar-sdk v17 performs base64 through the bare `btoa` identifier (`lib/cjs/base/util/base64.js`, with no fallback), and this release removes the browser bundle's `Buffer` `ProvidePlugin` that previously serviced it — a posture change from v16, where the bundle self-served base64 from that polyfill. Hermes provides `btoa`/`atob` natively from React Native 0.74 onward (facebook/hermes#1255); React Native's own JS layer never has, so **React Native < 0.74 or a non-Hermes engine (JSC, V8) needs a polyfill** such as `base-64`. Verified: a built bundle in a Hermes-like context without `btoa` throws `ReferenceError: btoa is not defined` on any base64 operation, while hex and base32/StrKey keep working (they are pure JS)
+* **`TextEncoder`/`TextDecoder` are a runtime prerequisite for loading this bundle.** `uint8array-extras` — a direct dependency of ours and a transitive dependency of stellar-sdk — constructs both at module initialization with no fallback (unlike `@exodus/bytes`, which only uses them when natively available and otherwise decodes in pure JS), so an environment missing either one fails at load, before any of our code runs. This is a prerequisite the consumer's environment must satisfy; React Native applications commonly polyfill `TextEncoder`/`TextDecoder` already. Verified: a built bundle in a context without them throws `TypeError: globalThis.TextDecoder is not a constructor` at load
+* Removed the `base64url` dependency, replaced by `uint8array-extras`' `uint8ArrayToBase64(bytes, { urlSafe: true })`
+* `pathPay()` now requires an explicit conversion bound and throws `PathPayBoundRequiredError` when it is missing — `destMin` for a strict-send payment, `sendMax` for a strict-receive one. It previously substituted defaults (one stroop for `destMin`, the int64 maximum for `sendMax`) which left the bound inert, so the conversion was effectively unbounded. Bounds supplied by the caller are now passed through verbatim. `PathPayParams` became a discriminated union, so omitting the bound — or passing both `sendAmount` and `destAmount` — is a compile-time error, and `swap()` takes `destMin` as a required fourth argument. This brings the Wallet SDK in line with `@stellar/stellar-sdk`, which already treats both fields as required (#252)
+
+### Added
+* `PathPayBoundRequiredError`, exported via `Exceptions` (#252)
+
+### Changed
+* Byte-derived values that used to be produced with `Buffer#toString(encoding)` are now produced with `xdr.encodeBytes(bytes, "hex" | "base64")`. `Uint8Array#toString()` ignores its encoding argument, so the old idiom silently returned comma-joined decimals under v17
+* The core SDK and soroban `src` trees no longer reference the `Buffer` global at all, and the core SDK's browser bundle ships without a `buffer` polyfill. The key manager retains one sanctioned exception (`Handlers/ledger.ts`, where `@ledgerhq/hw-app-str` requires a real `Buffer`), so its browser bundle still inlines the polyfill for that one path. This boundary is enforced by ESLint (`no-restricted-globals` / `no-restricted-syntax` / `no-restricted-imports`) and by a React Native sandbox test that loads each package's built bundle with `Buffer`, `Event`, `EventTarget` and `process` absent
+
+### Fixed
+* SEP-7 signatures and transaction URIs are correctly base64-encoded. Under stellar-sdk v17 the previous `Buffer`-era code produced comma-joined decimals, which made a signed `Sep7Tx` URI unparseable
+* The SEP-10 `client_domain` integrity check compares transaction hashes correctly again — it used `Buffer#equals`, which does not exist on `Uint8Array`
+* `Watcher` treats `on_hold` as a transient status. `TransactionStatus.on_hold` documents itself as a temporary state — an anchor holding a transfer for review, after which "transaction should follow the regular flow" — but neither watcher recognised it as in progress. `watchOneTransaction` fell through to its terminal branch and invoked `onError` before stopping its poll, so a transfer merely awaiting a compliance check was reported to the caller as a failure and then abandoned; `watchAllTransactions` filed it in the ignored registry and omitted it from the first poll entirely. Both now treat it like `incomplete` and the `pending_*` statuses, so the transaction keeps being watched and surfaces through `onMessage` until it reaches a genuinely final status (#251)
+
+### Known limitations
+* SEP-12 binary upload (`Customer.add`/`update` with `sep9BinaryInfo`) is not usable on React Native. axios's `toFormData` takes a `Buffer.from(value)` path for typed-array values whenever `FormData` is not spec-compliant, which is the case on React Native. That path was already non-functional there — React Native's `FormData.append` cannot consume a `Buffer` part — so this is a change of failure mode, not of capability: with the polyfill removed it now raises `ReferenceError` instead of producing silent garbage. Browsers and Node.js are unaffected
+
 # Release notes - Typescript Wallet SDK - 4.0.1
 
 ### Changed

package/examples/sep10/sep10Server.ts

@@ -43,7 +43,7 @@ app.post("/sign", (req, res) => {
   res.set("Access-Control-Allow-Origin", "*");
   res.status(200);
   res.send({
-    transaction: transaction.toEnvelope().toXDR("base64"),
+    transaction: transaction.toEnvelope().toXdr("base64"),
     network_passphrase: network_passphrase,
   });
 });

package/examples/sep24/sep24.ts

@@ -228,7 +228,7 @@ walletSigner.signWithDomainAccount = async ({
 
   const signer = SigningKeypair.fromSecret(clientSecret);
 
-  const transaction = TransactionBuilder.fromXDR(
+  const transaction = TransactionBuilder.fromXdr(
     transactionXDR,
     networkPassphrase,
   ) as Transaction;

package/examples/tsconfig.json

@@ -1,6 +1,7 @@
 {
   "compilerOptions": {
     "esModuleInterop": true,
+    "skipLibCheck": true,
     "baseUrl": "./",
     "outDir": "lib",
     "declaration": true,

package/jest.e2e.config.js

@@ -1,11 +1,12 @@
 module.exports = {
   rootDir: "./",
   preset: "ts-jest",
-  // @stellar/stellar-sdk v16 pulls in several ESM-only packages (directly or
+  // @stellar/stellar-sdk v17 pulls in several ESM-only packages (directly or
   // transitively) that must be transformed to run under Jest's CommonJS runtime.
   transformIgnorePatterns: [
     `/node_modules/(?!${[
       "@stablelib",
+      "@exodus/bytes",
       "@noble",
       "uint8array-extras",
       "smol-toml",

package/jest.integration.config.js

@@ -1,11 +1,12 @@
 module.exports = {
   rootDir: "./",
   preset: "ts-jest",
-  // @stellar/stellar-sdk v16 pulls in several ESM-only packages (directly or
+  // @stellar/stellar-sdk v17 pulls in several ESM-only packages (directly or
   // transitively) that must be transformed to run under Jest's CommonJS runtime.
   transformIgnorePatterns: [
     `/node_modules/(?!${[
       "@stablelib",
+      "@exodus/bytes",
       "@noble",
       "uint8array-extras",
       "smol-toml",