feat(xdr): add validateXdr static to every generated type (#1597)

* feat(xdr): add validateXdr static to every generated type

* docs(xdr): file validateXdr under renames, not removals

Author: Ryang-21

CHANGELOG.md

@@ -11,10 +11,10 @@ A breaking change will get clearly marked in this log.
   * Enums are singletons, not factory calls: `xdr.ContractDataDurability.persistent()` becomes `xdr.ContractDataDurability.persistent`.
   * 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`.
   * Absent optional fields decode to `null` instead of `undefined`, so `=== undefined` checks silently stop matching. Prefer `== null`.
-  * Acronyms in method names collapse to single-initial-cap form, with no back-compat aliases. 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.
+  * 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.
   * 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.
   * 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.
-  * 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`; the `validateXDR()` static on every type (use `try`/`catch` around `fromXdr`); and `xdr.scvSortedMap` (use the top-level `scvSortedMap`).
+  * 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`).
   * `ScInt` and `XdrLargeInt` lost their `.int` property; read `.value` (a `bigint`) instead, and note `valueOf()` now returns a `bigint`.
 
   [`docs/XDR_MIGRATION.md`](./docs/XDR_MIGRATION.md) covers every change with before/after examples and a quick-reference table.

docs/XDR_MIGRATION.md

@@ -34,6 +34,7 @@ error; `TypeError: … is not a function` in plain JavaScript):
 | -------------------------------- | -------------------------------- |
 | `value.toXDR()`                  | `value.toXdr()`                  |
 | `Class.fromXDR(…)`               | `Class.fromXdr(…)`               |
+| `Class.validateXDR(…)`           | `Class.validateXdr(…)`           |
 | `value.toXDRObject()`            | `value.toXdrObject()`            |
 | `Class.fromXDRObject(…)`         | `Class.fromXdrObject(…)`         |
 | `asset.toChangeTrustXDRObject()` | `asset.toChangeTrustXdrObject()` |
@@ -531,6 +532,7 @@ new xdr.Int32(v)             →   Number(v)
 .toXDR()                     →   .toXdr()
 .toXDR().toString("base64")  →   .toXdr("base64")
 .fromXDR(buf, "base64")      →   .fromXdr(buf, "base64")
+.validateXDR(s, "base64")    →   .validateXdr(s, "base64")
 
 // ============== METHODS (new — no legacy equivalent) ==============
                                  .toXdrObject() / .fromXdrObject(wire)
@@ -565,7 +567,6 @@ scInt.int / xli.int          →   scInt.value / xli.value  (bigint) — `.int`
 x === undefined              →   x == null    // decoded absent = null now
 
 // ============== REMOVED (§ 13) ==============
-Type.validateXDR(s, "base64") →  try { Type.fromXdr(s, "base64") } catch {}
 xdr.scvSortedMap(entries)    →   scvSortedMap(entries)   // top-level export
 xdr.Hyper / xdr.Option / xdr.Opaque / xdr.XDRString / …  →  (gone; see § 13)
 Hyper, UnsignedHyper, cereal →   (gone from top-level)
@@ -832,22 +833,19 @@ them; the schema builders behind them are internal.
 ### `validateXDR` and `xdr.scvSortedMap`
 
 - **`validateXDR(input, format)`** was a static on every generated type — a
-  cheap "is this decodable?" check. It has no replacement; wrap `fromXdr` in a
-  `try`/`catch` instead (§ 15).
+  "is this decodable?" check. It survives as **`validateXdr`** (casing now
+  matches `fromXdr`/`toXdr`): `Uint8Array` input, or a string with
+  `"hex" | "base64"`. As with `fromXdr`, the optional `"raw"` format argument
+  is gone — pass bytes alone (§ 7). It does a full decode and returns a
+  boolean; it never throws. When you need the failure reason, call `fromXdr`
+  in a `try`/`catch` instead (§ 15).
 
   ```ts
   // Before
   if (xdr.TransactionEnvelope.validateXDR(str, "base64")) { … }
 
   // After
-  function isValid(str: string): boolean {
-    try {
-      xdr.TransactionEnvelope.fromXdr(str, "base64");
-      return true;
-    } catch {
-      return false;
-    }
-  }
+  if (xdr.TransactionEnvelope.validateXdr(str, "base64")) { … }
   ```
 
 - **`xdr.scvSortedMap()`** is gone. The legacy SDK monkey-patched it onto the
@@ -943,7 +941,8 @@ consume (`"source buffer not entirely consumed"`), which is now
 fixed-size fields, out-of-range integers, unknown union discriminants, and
 unknown enum values all throw as before, with new wording.
 
-There is no `validateXDR` any more — see § 13 for the try/catch replacement.
+`validateXDR` survives as `validateXdr` (casing matches `fromXdr`/`toXdr`) —
+see § 13. It returns a bare boolean; decode directly when you need the error.
 
 ### Enum lookup
 

src/xdr/values/xdr-value.ts

@@ -38,7 +38,8 @@ export interface XdrValueConstructor<Wire, Instance extends XdrValue> {
  *   - `static fromXdrObject(wire: Wire): InstanceType` going the other way
  *   - `toJson(): JsonValue`
  *
- * Inherited helpers (`toXdr`, `fromXdr`, `toString`, `equals`) handle the rest.
+ * Inherited helpers (`toXdr`, `fromXdr`, `validateXdr`, `toString`, `equals`)
+ * handle the rest.
  */
 export abstract class XdrValue {
   abstract toXdrObject(): unknown;
@@ -107,6 +108,35 @@ export abstract class XdrValue {
     return this.fromXdrObject(this.schema.decode(bytes));
   }
 
+  /**
+   * Check whether `input` decodes as this type — {@link XdrValue.fromXdr}
+   * without the throw. Returns `false` on any failure (bad hex/base64, wrong
+   * shape, trailing bytes) and discards the error detail; decode directly
+   * when you need the reason.
+   */
+  static validateXdr<Wire, Instance extends XdrValue>(
+    this: XdrValueConstructor<Wire, Instance>,
+    input: Uint8Array,
+  ): boolean;
+  static validateXdr<Wire, Instance extends XdrValue>(
+    this: XdrValueConstructor<Wire, Instance>,
+    input: string,
+    format: "hex" | "base64",
+  ): boolean;
+  static validateXdr<Wire, Instance extends XdrValue>(
+    this: XdrValueConstructor<Wire, Instance>,
+    input: Uint8Array | string,
+    format?: "hex" | "base64",
+  ): boolean {
+    let bytes: Uint8Array;
+    try {
+      bytes = decodeBytes(input, format);
+    } catch {
+      return false;
+    }
+    return this.schema.validateXdr(bytes);
+  }
+
   static fromJson<Wire, Instance extends XdrValue>(
     this: XdrValueConstructor<Wire, Instance>,
     json: JsonValue,

test/unit/xdr/validate_xdr.test.ts

@@ -0,0 +1,48 @@
+import { describe, it, expect } from "vitest";
+
+import {
+  Price,
+  ScVal,
+  TransactionEnvelope,
+  AssetType,
+} from "../../../src/xdr/index.js";
+
+describe("validateXdr", () => {
+  it("returns true for valid raw bytes", () => {
+    const bytes = new Price({ n: 1, d: 2 }).toXdr();
+    expect(Price.validateXdr(bytes)).toBe(true);
+  });
+
+  it("returns true for valid base64 and hex strings", () => {
+    const val = ScVal.scvSymbol("hi");
+    expect(ScVal.validateXdr(val.toXdr("base64"), "base64")).toBe(true);
+    expect(ScVal.validateXdr(val.toXdr("hex"), "hex")).toBe(true);
+  });
+
+  it("works on enums", () => {
+    const bytes = AssetType.assetTypeNative.toXdr();
+    expect(AssetType.validateXdr(bytes)).toBe(true);
+    expect(AssetType.validateXdr(new Uint8Array([0, 0, 0, 99]))).toBe(false);
+  });
+
+  it("returns false for bytes of the wrong type", () => {
+    const bytes = new Price({ n: 1, d: 2 }).toXdr();
+    expect(TransactionEnvelope.validateXdr(bytes)).toBe(false);
+  });
+
+  it("returns false for trailing bytes", () => {
+    const bytes = new Price({ n: 1, d: 2 }).toXdr();
+    const padded = new Uint8Array([...bytes, 0, 0, 0, 0]);
+    expect(Price.validateXdr(padded)).toBe(false);
+  });
+
+  it("returns false for truncated input", () => {
+    const bytes = new Price({ n: 1, d: 2 }).toXdr().slice(0, -1);
+    expect(Price.validateXdr(bytes)).toBe(false);
+  });
+
+  it("returns false (not a throw) on malformed base64 and hex", () => {
+    expect(ScVal.validateXdr("not base64!!!", "base64")).toBe(false);
+    expect(ScVal.validateXdr("zz-not-hex", "hex")).toBe(false);
+  });
+});