docs: point the Uint8Array migration guide at SDK byte helpers (#1661)

* fix(xdr): add per-format overloads and jsdoc to encodeBytes/decodeBytes

Author: Ryang-21

docs/UINT8ARRAY_MIGRATION.md

@@ -23,28 +23,48 @@ etc. on an SDK result, that code needs updating.
 
 ## 1. Recipes: replacing Buffer methods on SDK results
 
-The [`uint8array-extras`](https://github.com/sindresorhus/uint8array-extras)
-package (which the SDK itself uses) covers most of these; plain `DataView`
-covers the rest. In Node you can also just wrap the result:
-`Buffer.from(bytes.buffer, bytes.byteOffset, bytes.byteLength)`.
+The SDK ships the hex and base64 conversions itself: `xdr.encodeBytes` and
+`xdr.decodeBytes` (the same functions behind every `toXdr` / `fromXdr` call).
+XDR values need no helper at all, since `toXdr` takes a format directly. Cases
+the SDK does not cover (`equals`, `concat`, `compare`, UTF-8) are handled by
+[`uint8array-extras`](https://github.com/sindresorhus/uint8array-extras) or
+plain `DataView`, as noted per row.
+
+```ts
+import { xdr } from "@stellar/stellar-sdk";
+
+xdr.encodeBytes(tx.hash(), "hex");          // "deadbeef…"
+xdr.encodeBytes(keypair.sign(data), "base64");
+xdr.decodeBytes("deadbeef", "hex");         // Uint8Array
+
+// XDR values encode directly — no helper needed:
+scVal.toXdr("hex");
+entry.toXdr("base64");
+```
 
 | Before (Buffer)                    | After (Uint8Array)                                          |
 | ---------------------------------- | ----------------------------------------------------------- |
-| `buf.toString("hex")`              | `uint8ArrayToHex(bytes)`                                    |
-| `buf.toString("base64")`           | `uint8ArrayToBase64(bytes)`                                 |
-| `buf.toString("utf8")` / `.toString()` | `uint8ArrayToString(bytes)`                             |
-| `Buffer.from(hex, "hex")`          | `hexToUint8Array(hex)`                                      |
-| `Buffer.from(b64, "base64")`       | `base64ToUint8Array(b64)`                                   |
-| `Buffer.from(str)` (UTF-8)         | `stringToUint8Array(str)`                                   |
-| `Buffer.concat([a, b])`            | `concatUint8Arrays([a, b])`                                 |
-| `a.equals(b)`                      | `areUint8ArraysEqual(a, b)`                                 |
-| `a.compare(b)`                     | `compareUint8Arrays(a, b)`                                  |
+| `xdrVal.toXDR("hex")` / `("base64")` | `xdrVal.toXdr("hex")` / `("base64")` — returns `string`, no helper needed |
+| `buf.toString("hex")`              | `xdr.encodeBytes(bytes, "hex")`                             |
+| `buf.toString("base64")`           | `xdr.encodeBytes(bytes, "base64")`                          |
+| `Buffer.from(hex, "hex")`          | `xdr.decodeBytes(hex, "hex")`                               |
+| `Buffer.from(b64, "base64")`       | `xdr.decodeBytes(b64, "base64")`                            |
+| `buf.toString("utf8")` / `.toString()` | `uint8ArrayToString(bytes)` (`uint8array-extras`)       |
+| `Buffer.from(str)` (UTF-8)         | `stringToUint8Array(str)` (`uint8array-extras`)             |
+| `Buffer.concat([a, b])`            | `concatUint8Arrays([a, b])` (`uint8array-extras`)           |
+| `a.equals(b)`                      | `areUint8ArraysEqual(a, b)` (`uint8array-extras`)           |
+| `a.compare(b)`                     | `compareUint8Arrays(a, b)` (`uint8array-extras`)            |
 | `Buffer.alloc(n)`                  | `new Uint8Array(n)`                                         |
 | `Buffer.isBuffer(x)`               | `x instanceof Uint8Array`                                   |
 | `buf.readUInt32BE(o)`              | `new DataView(bytes.buffer, bytes.byteOffset, bytes.byteLength).getUint32(o)` |
 | `buf.readBigUInt64BE(o)`           | `…same DataView….getBigUint64(o)`                           |
 | `buf.slice(a, b)` (view)           | `bytes.subarray(a, b)`. Note that `Uint8Array.prototype.slice` **copies**, while `Buffer.prototype.slice` returned a view |
 
+As a stopgap in Node you can wrap a result back into a Buffer:
+`Buffer.from(bytes.buffer, bytes.byteOffset, bytes.byteLength)`. Treat that as
+temporary; it reintroduces the Buffer dependency v17 removed, and it does not
+work in browsers without a polyfill.
+
 Three semantic traps to check for:
 
 - `.toString("hex")` fails silently. `Uint8Array.prototype.toString` ignores its
@@ -62,7 +82,7 @@ Three semantic traps to check for:
   result. Normalize one side, or compare encodings:
 
   ```ts
-  expect(uint8ArrayToHex(actual)).toBe(expectedHex); // preferred
+  expect(xdr.encodeBytes(actual, "hex")).toBe(expectedHex); // preferred
   expect(Array.from(actual)).toEqual(Array.from(expectedBuffer));
   ```
 

src/xdr/values/xdr-value.ts

@@ -281,6 +281,33 @@ function splitArrayArgs(
     : [undefined, formatOrOptions ?? maybeOptions ?? {}];
 }
 
+/**
+ * Encode raw bytes into the requested {@link XdrFormat}: the bytes themselves
+ * for `"raw"`, or a `"hex"` / `"base64"` string. This is the encoder behind
+ * every `toXdr(format)` call, exported so consumers can format any
+ * `Uint8Array` the SDK hands back (hashes, signatures, raw keys) without a
+ * helper library.
+ *
+ * ```ts
+ * encodeBytes(new Uint8Array([0xde, 0xad, 0xbe, 0xef]), "hex");    // "deadbeef"
+ * encodeBytes(new Uint8Array([0xde, 0xad, 0xbe, 0xef]), "base64"); // "3q2+7w=="
+ * ```
+ *
+ * @param bytes - the bytes to encode
+ * @param format - `"raw"` returns `bytes` unchanged; `"hex"` and `"base64"`
+ *   return a string
+ * @throws an {@link XdrError} on an unknown format
+ * @see {@link decodeBytes} for the reverse direction
+ */
+export function encodeBytes(bytes: Uint8Array, format: "raw"): Uint8Array;
+export function encodeBytes(
+  bytes: Uint8Array,
+  format: "hex" | "base64",
+): string;
+export function encodeBytes(
+  bytes: Uint8Array,
+  format: XdrFormat,
+): Uint8Array | string;
 export function encodeBytes(
   bytes: Uint8Array,
   format: XdrFormat,
@@ -299,6 +326,26 @@ export function encodeBytes(
   }
 }
 
+/**
+ * Decode a `"hex"` or `"base64"` string into bytes; a `Uint8Array` input
+ * passes through unchanged. This is the decoder behind every
+ * `fromXdr(input, format)` call, exported so consumers can parse encoded
+ * byte strings without a helper library.
+ *
+ * ```ts
+ * decodeBytes("deadbeef", "hex");  // Uint8Array [0xde, 0xad, 0xbe, 0xef]
+ * decodeBytes("3q2+7w==", "base64");
+ * ```
+ *
+ * Decoding is strict: malformed input throws instead of being silently
+ * truncated the way `Buffer.from(str, "hex")` was.
+ *
+ * @param input - the bytes or encoded string to decode
+ * @param format - required when `input` is a string; ignored for `Uint8Array`
+ * @throws an {@link XdrError} when a string arrives without a `"hex"` /
+ *   `"base64"` format, or the format is unknown
+ * @see {@link encodeBytes} for the reverse direction
+ */
 export function decodeBytes(
   input: Uint8Array | string,
   format: "raw" | "hex" | "base64" | undefined,