refactor xdr strings to be represented soley via bytes with a dx friendly XdrString wrapper class

Author: Ryang-21

src/base/memo.ts

@@ -44,7 +44,7 @@ export type MemoType =
   | MemoTypeReturn
   | MemoTypeText;
 
-export type MemoValue = Buffer | string | null;
+export type MemoValue = Buffer | string | null | Uint8Array;
 
 type MemoValueMap = {
   [MemoNone]: null;
@@ -235,10 +235,11 @@ export class Memo<T extends MemoType = MemoType> {
   /**
    * Creates and returns a `MemoText` memo.
    *
-   * @param text - memo text
+   * @param text - memo text. A JS string is UTF-8 encoded on the wire;
+   *   pass a `Buffer`/`Uint8Array` for byte-exact content.
    */
-  static text(text: string): Memo<MemoTypeText> {
-    return new Memo(MemoText, text);
+  static text(text: string | Buffer | Uint8Array): Memo<MemoTypeText> {
+    return new Memo(MemoText, text as MemoValue);
   }
 
   /**
@@ -305,7 +306,7 @@ export class Memo<T extends MemoType = MemoType> {
       case "memoId":
         return Memo.id(object.value.toString());
       case "memoText":
-        return Memo.text(object.value as string);
+        return Memo.text(Buffer.from(object.text.bytes));
       case "memoHash":
         return Memo.hash(Buffer.from(object.value.toBytes()));
       case "memoReturn":

src/base/operation.ts

@@ -233,7 +233,7 @@ export class Operation {
         result.highThreshold = attrs.highThreshold ?? undefined;
         // home_domain is checked by iscntrl in stellar-core
         result.homeDomain =
-          attrs.homeDomain === null ? undefined : attrs.homeDomain;
+          attrs.homeDomain === null ? undefined : attrs.homeDomain.toString();
 
         if (attrs.signer) {
           const signer: Record<string, unknown> = {};
@@ -301,7 +301,7 @@ export class Operation {
       case "manageData": {
         result.type = "manageData";
         // manage_data.name is checked by iscntrl in stellar-core
-        result.name = attrs.dataName;
+        result.name = attrs.dataName.toString();
         result.value =
           attrs.dataValue === null
             ? undefined
@@ -524,7 +524,7 @@ function extractRevokeSponshipDetails(
         case "data": {
           result.type = "revokeDataSponsorship";
           result.account = accountIdtoAddress(ledgerKey.data.accountId);
-          result.name = ledgerKey.data.dataName;
+          result.name = ledgerKey.data.dataName.toString();
           break;
         }
         case "claimableBalance": {

src/base/scval.ts

@@ -425,34 +425,13 @@ export function scValToNative(scv: ScVal): any {
     // Note that we assume a utf8 encoding (ascii-compatible). For other
     // encodings, you should probably use bytes anyway. If it cannot be decoded,
     // the raw bytes are returned.
-    case "scvSymbol": {
-      const v = scv.value;
-      if (
-        Buffer.isBuffer(v) ||
-        (ArrayBuffer.isView(v) && typeof v !== "string")
-      ) {
-        try {
-          return new TextDecoder().decode(v);
-        } catch {
-          return new Uint8Array((v as ArrayBufferView).buffer); // copy of bytes
-        }
-      }
-      return v; // string already
-    }
-    case "scvString": {
-      const v = scv.value;
-      if (
-        Buffer.isBuffer(v) ||
-        (ArrayBuffer.isView(v) && typeof v !== "string")
-      ) {
-        try {
-          return new TextDecoder().decode(v);
-        } catch {
-          return new Uint8Array((v as ArrayBufferView).buffer); // copy of bytes
-        }
-      }
-      return v; // string already
-    }
+    case "scvSymbol":
+      // Reach the raw XdrString wrapper (the `.value` getter would do a
+      // strict UTF-8 decode that throws on invalid bytes; we want a best-
+      // effort decode that falls back to raw bytes for binary content).
+      return scv.sym.asStringOrBytes();
+    case "scvString":
+      return scv.str.asStringOrBytes();
 
     // these can be converted to bigint
     case "scvTimepoint":

src/contract/assembled_transaction.ts

@@ -417,7 +417,7 @@ export class AssembledTransaction<T> {
 
     try {
       contractAddress = invokeContractArgs.contractAddress;
-      functionName = invokeContractArgs.functionName;
+      functionName = invokeContractArgs.functionName.toString();
     } catch {
       throw new Error(
         "Could not extract contract address or method name from the transaction envelope.",
@@ -463,7 +463,7 @@ export class AssembledTransaction<T> {
       options.contractId,
     );
 
-    const xdrMethod = invokeContractArgs.functionName;
+    const xdrMethod = invokeContractArgs.functionName.toString();
 
     if (xdrMethod !== options.method) {
       throw new Error(
@@ -518,7 +518,7 @@ export class AssembledTransaction<T> {
       options.contractId,
     );
 
-    const method = invokeContractArgs.functionName;
+    const method = invokeContractArgs.functionName.toString();
     const txn = new AssembledTransaction({
       ...options,
       method,

src/contract/spec.ts

@@ -28,6 +28,7 @@ import {
   ScVal,
   Uint32,
   Uint64,
+  XdrString,
 } from "../xdr/index.js";
 
 export interface Union<T> {
@@ -349,7 +350,7 @@ function isRequired(typeDef: ScSpecTypeDef): boolean {
   return typeDef.type !== "scSpecTypeOption";
 }
 
-function argsAndRequired(input: { type: ScSpecTypeDef; name: string }[]): {
+function argsAndRequired(input: { type: ScSpecTypeDef; name: XdrString }[]): {
   properties: object;
   required?: string[];
 } {
@@ -660,9 +661,7 @@ export class Spec {
         return e.value.name.toString() === name;
       }
       // For UDT entries (struct/union/enum/errorEnum/eventV0), value has .name
-      return (
-        (e.value as { name: string | Uint8Array }).name.toString() === name
-      );
+      return (e.value as { name: XdrString }).name.toString() === name;
     });
     if (!entry) {
       throw new Error(`no such entry: ${name}`);

src/xdr/generated/account-entry.ts

@@ -2,10 +2,10 @@ import { struct } from "../types/struct.js";
 import { int64 } from "../types/int64.js";
 import { uint32 } from "../types/uint32.js";
 import { option } from "../types/option.js";
-import { string as string_ } from "../types/string.js";
 import { array } from "../types/array.js";
 import { UNBOUNDED_MAX_LENGTH, type XdrType } from "../core/xdr-type.js";
 import { XdrValue } from "../values/xdr-value.js";
+import { XdrString, xdrString } from "../values/xdr-string.js";
 import { PublicKey, type PublicKeyWire } from "./public-key.js";
 import { Thresholds, type ThresholdsWire } from "./thresholds.js";
 import { Signer, type SignerWire } from "./signer.js";
@@ -21,7 +21,7 @@ export interface AccountEntryWire {
   numSubEntries: number;
   inflationDest: PublicKeyWire | null;
   flags: number;
-  homeDomain: string;
+  homeDomain: XdrString;
   thresholds: ThresholdsWire;
   signers: SignerWire[];
   ext: AccountEntryExtWire;
@@ -66,7 +66,7 @@ export class AccountEntry extends XdrValue {
   readonly numSubEntries: number;
   readonly inflationDest: PublicKey | null;
   readonly flags: number;
-  readonly homeDomain: string;
+  readonly homeDomain: XdrString;
   readonly thresholds: Thresholds;
   readonly signers: Signer[];
   readonly ext: AccountEntryExt;
@@ -78,7 +78,7 @@ export class AccountEntry extends XdrValue {
     numSubEntries: uint32(),
     inflationDest: option(PublicKey.schema),
     flags: uint32(),
-    homeDomain: string_(32),
+    homeDomain: xdrString(32),
     thresholds: Thresholds.schema,
     signers: array(Signer.schema, UNBOUNDED_MAX_LENGTH),
     ext: AccountEntryExt.schema,
@@ -91,7 +91,7 @@ export class AccountEntry extends XdrValue {
     numSubEntries: number;
     inflationDest: PublicKey | null;
     flags: number;
-    homeDomain: Uint8Array | string;
+    homeDomain: XdrString | string | Uint8Array;
     thresholds: Thresholds | Uint8Array | string;
     signers: Signer[];
     ext: AccountEntryExt;
@@ -104,9 +104,9 @@ export class AccountEntry extends XdrValue {
     this.inflationDest = input.inflationDest;
     this.flags = input.flags;
     this.homeDomain =
-      input.homeDomain instanceof Uint8Array
-        ? new TextDecoder("latin1").decode(input.homeDomain)
-        : input.homeDomain;
+      input.homeDomain instanceof XdrString
+        ? input.homeDomain
+        : new XdrString(input.homeDomain);
     this.thresholds =
       input.thresholds instanceof Thresholds
         ? input.thresholds

src/xdr/generated/data-entry.ts

@@ -1,14 +1,14 @@
 import { struct } from "../types/struct.js";
-import { string as string_ } from "../types/string.js";
 import type { XdrType } from "../core/xdr-type.js";
 import { XdrValue } from "../values/xdr-value.js";
+import { XdrString, xdrString } from "../values/xdr-string.js";
 import { PublicKey, type PublicKeyWire } from "./public-key.js";
 import { DataValue, type DataValueWire } from "./data-value.js";
 import { DataEntryExt, type DataEntryExtWire } from "./data-entry-ext.js";
 
 export interface DataEntryWire {
   accountId: PublicKeyWire;
-  dataName: string;
+  dataName: XdrString;
   dataValue: DataValueWire;
   ext: DataEntryExtWire;
 }
@@ -33,29 +33,29 @@ export interface DataEntryWire {
  */
 export class DataEntry extends XdrValue {
   readonly accountId: PublicKey;
-  readonly dataName: string;
+  readonly dataName: XdrString;
   readonly dataValue: DataValue;
   readonly ext: DataEntryExt;
 
   static readonly schema: XdrType<DataEntryWire> = struct("DataEntry", {
     accountId: PublicKey.schema,
-    dataName: string_(64),
+    dataName: xdrString(64),
     dataValue: DataValue.schema,
     ext: DataEntryExt.schema,
   });
 
   constructor(input: {
     accountId: PublicKey;
-    dataName: Uint8Array | string;
+    dataName: XdrString | string | Uint8Array;
     dataValue: DataValue | Uint8Array | string;
     ext: DataEntryExt;
   }) {
     super();
     this.accountId = input.accountId;
     this.dataName =
-      input.dataName instanceof Uint8Array
-        ? new TextDecoder("latin1").decode(input.dataName)
-        : input.dataName;
+      input.dataName instanceof XdrString
+        ? input.dataName
+        : new XdrString(input.dataName);
     this.dataValue =
       input.dataValue instanceof DataValue
         ? input.dataValue

src/xdr/generated/error.ts

@@ -1,12 +1,12 @@
 import { struct } from "../types/struct.js";
-import { string as string_ } from "../types/string.js";
 import type { XdrType } from "../core/xdr-type.js";
 import { XdrValue } from "../values/xdr-value.js";
+import { XdrString, xdrString } from "../values/xdr-string.js";
 import { ErrorCode, type ErrorCodeWire } from "./error-code.js";
 
 export interface ErrorWire {
   code: ErrorCodeWire;
-  msg: string;
+  msg: XdrString;
 }
 
 /**
@@ -20,20 +20,21 @@ export interface ErrorWire {
  */
 export class Error extends XdrValue {
   readonly code: ErrorCode;
-  readonly msg: string;
+  readonly msg: XdrString;
 
   static readonly schema: XdrType<ErrorWire> = struct("Error", {
     code: ErrorCode.schema,
-    msg: string_(100),
+    msg: xdrString(100),
   });
 
-  constructor(input: { code: ErrorCode; msg: Uint8Array | string }) {
+  constructor(input: {
+    code: ErrorCode;
+    msg: XdrString | string | Uint8Array;
+  }) {
     super();
     this.code = input.code;
     this.msg =
-      input.msg instanceof Uint8Array
-        ? new TextDecoder("latin1").decode(input.msg)
-        : input.msg;
+      input.msg instanceof XdrString ? input.msg : new XdrString(input.msg);
   }
 
   toXdrObject(): ErrorWire {

src/xdr/generated/hello.ts

@@ -1,10 +1,10 @@
 import { struct } from "../types/struct.js";
 import { uint32 } from "../types/uint32.js";
-import { string as string_ } from "../types/string.js";
 import { int32 } from "../types/int32.js";
 import { opaque } from "../types/opaque.js";
 import type { XdrType } from "../core/xdr-type.js";
 import { XdrValue } from "../values/xdr-value.js";
+import { XdrString, xdrString } from "../values/xdr-string.js";
 import { Hash, type HashWire } from "./hash.js";
 import { PublicKey, type PublicKeyWire } from "./public-key.js";
 import { AuthCert, type AuthCertWire } from "./auth-cert.js";
@@ -14,7 +14,7 @@ export interface HelloWire {
   overlayVersion: number;
   overlayMinVersion: number;
   networkId: HashWire;
-  versionStr: string;
+  versionStr: XdrString;
   listeningPort: number;
   peerId: PublicKeyWire;
   cert: AuthCertWire;
@@ -42,7 +42,7 @@ export class Hello extends XdrValue {
   readonly overlayVersion: number;
   readonly overlayMinVersion: number;
   readonly networkId: Hash;
-  readonly versionStr: string;
+  readonly versionStr: XdrString;
   readonly listeningPort: number;
   readonly peerId: PublicKey;
   readonly cert: AuthCert;
@@ -53,7 +53,7 @@ export class Hello extends XdrValue {
     overlayVersion: uint32(),
     overlayMinVersion: uint32(),
     networkId: Hash.schema,
-    versionStr: string_(100),
+    versionStr: xdrString(100),
     listeningPort: int32(),
     peerId: PublicKey.schema,
     cert: AuthCert.schema,
@@ -65,7 +65,7 @@ export class Hello extends XdrValue {
     overlayVersion: number;
     overlayMinVersion: number;
     networkId: Hash | Uint8Array | string;
-    versionStr: Uint8Array | string;
+    versionStr: XdrString | string | Uint8Array;
     listeningPort: number;
     peerId: PublicKey;
     cert: AuthCert;
@@ -80,9 +80,9 @@ export class Hello extends XdrValue {
         ? input.networkId
         : new Hash(input.networkId);
     this.versionStr =
-      input.versionStr instanceof Uint8Array
-        ? new TextDecoder("latin1").decode(input.versionStr)
-        : input.versionStr;
+      input.versionStr instanceof XdrString
+        ? input.versionStr
+        : new XdrString(input.versionStr);
     this.listeningPort = input.listeningPort;
     this.peerId = input.peerId;
     this.cert = input.cert;