TxRepHelper

public final class TxRepHelper : Sendable

Shared utility functions for TxRep encoding and decoding.

Used by both generated and wrapper TxRep code to provide consistent parsing, formatting, and Stellar type conversion.

All methods are static; this class is never instantiated.

Show on GitHub

Parser utilities

  • Parse TxRep text into a key-value map.

    Handles blank lines, comment lines (starting with :), CRLF line endings, and lines with no colon (skipped). Splits on the first : only and trims value whitespace. Duplicate keys use the last-write-wins rule.

    Declaration

    Swift

    public static func parse(_ txRep: String) -> [String : String]

    Parameters

    txRep

    Human-readable TxRep string.

    Return Value

    Dictionary mapping keys to raw (unprocessed) value strings.

    Show on GitHub

  • Get a value from the map, stripping inline comments via removeComment(_:).

    Declaration

    Swift

    public static func getValue(_ map: [String : String], _ key: String) -> String?

    Parameters

    map

    The key-value map returned by parse(_:).
    key

    The key to look up.

    Return Value

    The trimmed value with any inline comment removed, or nil if the key is absent.

    Show on GitHub

  • Remove an inline comment from a TxRep value string.

    If the value begins with a double-quote, the method finds the closing quote (respecting backslash escapes) and returns everything up to and including it. For unquoted values, any (…) suffix is stripped and the result is trimmed.

    Declaration

    Swift

    public static func removeComment(_ value: String) -> String

    Parameters

    value

    Raw value string, possibly containing a trailing comment.

    Return Value

    Value with any inline comment removed.

    Show on GitHub

Byte / hex conversion

  • Encode bytes as a lowercase hex string.

    Returns "0" for empty input to match the SEP-0011 convention for zero-length opaque fields.

    Declaration

    Swift

    public static func bytesToHex(_ bytes: Data) -> String

    Parameters

    bytes

    Binary data to encode.

    Return Value

    Lowercase hex string, or "0" for empty data.

    Show on GitHub

  • Decode a hex string to bytes.

    "0" decodes to empty Data. Odd-length hex strings are left-padded with a zero digit (e.g., "f" becomes "0f"). Non-hex characters cause a throw.

    Throws

    TxRepError.invalidValue(key:) if hex contains non-hex characters.

    Declaration

    Swift

    public static func hexToBytes(_ hex: String) throws -> Data

    Parameters

    hex

    Hex string to decode. May be "0" or any valid hex string.

    Return Value

    Decoded Data.

    Show on GitHub

String escaping

  • Escape a string for the TxRep double-quoted format.

    The output is wrapped in double quotes. Inside the quotes:

    • \ is encoded as \\
    • " is encoded as \"
    • \n (LF) is encoded as \n
    • \r (CR) is encoded as \r
    • \t (HT) is encoded as \t
    • Bytes 0x00–0x1F (excluding the above), 0x7F, and 0x80–0xFF are encoded as \xNN where NN is two lowercase hex digits per UTF-8 byte.

    • Printable ASCII 0x20–0x7E (excluding \ and ") is passed through.

    Declaration

    Swift

    public static func escapeString(_ s: String) -> String

    Parameters

    s

    The string to escape.

    Return Value

    Escaped, double-quoted string.

    Show on GitHub

  • Unescape a TxRep string value.

    If the input is enclosed in double quotes they are stripped first. Handles \", \\, \n, \r, \t, \xNN (hex), and \NNN (octal) escape sequences. If the input is not quoted it is returned as-is (no unescaping is attempted).

    Throws

    TxRepError.invalidValue(key:) if the string is quoted but unterminated, or if a \xNN sequence contains invalid hex digits.

    Declaration

    Swift

    public static func unescapeString(_ s: String) throws -> String

    Parameters

    s

    The possibly-quoted string to unescape.

    Return Value

    Unescaped string.

    Show on GitHub

Numeric parsing

  • Parse a string to Int32, supporting decimal and 0x/0X hex prefixes.

    Leading - is accepted for negative values. Hex input may also be negative (e.g., -0x1). Throws on overflow or invalid characters.

    Throws

    TxRepError.invalidValue(key:) on parse failure or overflow.

    Declaration

    Swift

    public static func parseInt(_ s: String) throws -> Int32

    Parameters

    s

    String to parse.

    Return Value

    Parsed Int32 value.

    Show on GitHub

  • Parse a string to Int64, supporting decimal and 0x/0X hex prefixes.

    Leading - is accepted for negative values. Throws on overflow or invalid characters.

    Throws

    TxRepError.invalidValue(key:) on parse failure or overflow.

    Declaration

    Swift

    public static func parseInt64(_ s: String) throws -> Int64

    Parameters

    s

    String to parse.

    Return Value

    Parsed Int64 value.

    Show on GitHub

  • Parse a string to UInt64, supporting decimal and 0x/0X hex prefixes.

    Does not accept a leading -. Throws on invalid characters or if the value exceeds UInt64.max.

    Throws

    TxRepError.invalidValue(key:) on parse failure.

    Declaration

    Swift

    public static func parseUInt64(_ s: String) throws -> UInt64

    Parameters

    s

    String to parse.

    Return Value

    Parsed UInt64 value.

    Show on GitHub

Stellar type formatters

  • Convert a PublicKey to its G-address StrKey string.

    Declaration

    Swift

    public static func formatAccountId(_ key: PublicKey) -> String

    Parameters

    key

    The Stellar Ed25519 public key.

    Return Value

    G-address (e.g., GBZX...).

    Show on GitHub

  • Parse a G-address StrKey string to a PublicKey.

    Throws

    TxRepError.invalidValue(key:) if the address is not a valid G-address.

    Declaration

    Swift

    public static func parseAccountId(_ strKey: String) throws -> PublicKey

    Parameters

    strKey

    G-address string.

    Return Value

    PublicKey value.

    Show on GitHub

  • Convert a MuxedAccountXDR to its canonical StrKey string.

    Returns a G-address for plain Ed25519 accounts and an M-address for muxed accounts.

    Throws

    TxRepError.invalidValue(key:) if encoding fails.

    Declaration

    Swift

    public static func formatMuxedAccount(_ mux: MuxedAccountXDR) throws -> String

    Parameters

    mux

    The muxed account XDR value.

    Return Value

    G- or M-address string.

    Show on GitHub

  • Parse a G- or M-address StrKey string to a MuxedAccountXDR.

    Throws

    TxRepError.invalidValue(key:) if the string is not a valid account address.

    Declaration

    Swift

    public static func parseMuxedAccount(_ strKey: String) throws -> MuxedAccountXDR

    Parameters

    strKey

    G-address or M-address string.

    Return Value

    MuxedAccountXDR value.

    Show on GitHub

  • Format an AssetXDR as a TxRep asset string.

    Returns "XLM" for native assets and "CODE:ISSUER" for credit assets.

    Declaration

    Swift

    public static func formatAsset(_ asset: AssetXDR) -> String

    Parameters

    asset

    The asset XDR value.

    Return Value

    TxRep asset string.

    Show on GitHub

  • Parse a TxRep asset string to an AssetXDR.

    Accepts "XLM" or "native" for native, and "CODE:ISSUER" for credit assets. Asset codes of 1–4 characters produce alphanum4; 5–12 produce alphanum12.

    Throws

    TxRepError.invalidValue(key:) if the string cannot be parsed.

    Declaration

    Swift

    public static func parseAsset(_ value: String) throws -> AssetXDR

    Parameters

    value

    TxRep asset string.

    Return Value

    AssetXDR value.

    Show on GitHub

  • Format a ChangeTrustAssetXDR as a TxRep string.

    Returns "XLM" for native, "CODE:ISSUER" for credit assets. Pool-share assets cannot be represented as a single compact string (they are serialized field-by-field by the caller) and cause a throw.

    Throws

    TxRepError.invalidValue(key:) for pool-share or unknown asset types.

    Declaration

    Swift

    public static func formatChangeTrustAsset(_ asset: ChangeTrustAssetXDR) throws -> String

    Parameters

    asset

    The change-trust asset XDR value.

    Return Value

    TxRep asset string.

    Show on GitHub

  • Parse a TxRep string to a ChangeTrustAssetXDR.

    Handles "XLM" / "native" and "CODE:ISSUER" formats. Pool-share assets must be constructed separately from their constituent fields.

    Throws

    TxRepError.invalidValue(key:) if the string cannot be parsed.

    Declaration

    Swift

    public static func parseChangeTrustAsset(_ value: String) throws -> ChangeTrustAssetXDR

    Parameters

    value

    TxRep asset string.

    Return Value

    ChangeTrustAssetXDR value.

    Show on GitHub

  • Format a TrustlineAssetXDR as a TxRep string.

    Returns "XLM" for native, "CODE:ISSUER" for credit assets, and a 64-character lowercase hex string for pool-share assets (the 32-byte liquidity pool ID).

    Throws

    TxRepError.invalidValue(key:) for unknown asset types.

    Declaration

    Swift

    public static func formatTrustlineAsset(_ asset: TrustlineAssetXDR) throws -> String

    Parameters

    asset

    The trustline asset XDR value.

    Return Value

    TxRep asset string.

    Show on GitHub

  • Parse a TxRep string to a TrustlineAssetXDR.

    Accepts "XLM" / "native", "CODE:ISSUER", and a 64-character hex string (pool-share liquidity pool ID).

    Throws

    TxRepError.invalidValue(key:) if the string cannot be parsed.

    Declaration

    Swift

    public static func parseTrustlineAsset(_ value: String) throws -> TrustlineAssetXDR

    Parameters

    value

    TxRep asset string.

    Return Value

    TrustlineAssetXDR value.

    Show on GitHub

  • Format a SignerKeyXDR as its canonical StrKey string.

    • ed25519 → G-address
    • preAuthTx → T-address
    • hashX → X-address

    • signedPayload → P-address

    Throws

    TxRepError.invalidValue(key:) if encoding fails.

    Declaration

    Swift

    public static func formatSignerKey(_ key: SignerKeyXDR) throws -> String

    Parameters

    key

    The signer key XDR value.

    Return Value

    StrKey-encoded signer key.

    Show on GitHub

  • Parse a StrKey string to a SignerKeyXDR.

    The key type is inferred from the leading character:

    • G → ed25519
    • T → preAuthTx
    • X → hashX

    • P → signedPayload

    Throws

    TxRepError.invalidValue(key:) if the string cannot be decoded.

    Declaration

    Swift

    public static func parseSignerKey(_ value: String) throws -> SignerKeyXDR

    Parameters

    value

    StrKey-encoded signer key string.

    Return Value

    SignerKeyXDR value.

    Show on GitHub

  • Format an AllowTrustOpAssetXDR as a compact asset code string.

    Trailing null bytes are stripped from the fixed-length code arrays.

    Throws

    TxRepError.invalidValue(key:) for unknown asset types.

    Declaration

    Swift

    public static func formatAllowTrustAsset(_ asset: AllowTrustOpAssetXDR) throws -> String

    Parameters

    asset

    The allow-trust asset XDR value.

    Return Value

    Asset code string (e.g., "USDC").

    Show on GitHub

  • Parse an asset code string to an AllowTrustOpAssetXDR.

    Codes of 1–4 characters produce alphanum4; 5–12 produce alphanum12.

    Throws

    TxRepError.invalidValue(key:) if the code is empty or longer than 12 characters.

    Declaration

    Swift

    public static func parseAllowTrustAsset(_ code: String) throws -> AllowTrustOpAssetXDR

    Parameters

    code

    Asset code string.

    Return Value

    AllowTrustOpAssetXDR value.

    Show on GitHub

Memo text legacy encoding

  • Encode a MEMO_TEXT string in SEP-0011 C-style escape format.

    Per SEP-0011 (and the reference stc implementation), non-printable and non-ASCII bytes are escaped as \xNN over the raw UTF-8 byte sequence — NOT as \uNNNN Unicode code points. Delegates to escapeString(_:) which implements that format.

    decodeMemoText(_:) accepts both the SEP-0011 \xNN format and the legacy JSON \uNNNN format produced by older iOS SDK builds (and other SDKs that have the same historical bug), so previously written TxRep data continues to parse.

    Declaration

    Swift

    public static func encodeMemoText(_ s: String) -> String

    Parameters

    s

    The raw memo text string (at most 28 bytes in UTF-8).

    Return Value

    Quoted SEP-0011-escaped string, e.g. "Hello" or "caf\xc3\xa9".

    Show on GitHub

  • Decode a MEMO_TEXT value from TxRep, supporting both the legacy JSON-encoded format and the newer \xNN escape format.

    Tries JSON decoding first (for interoperability with older iOS SDK output and other SDKs that write JSON string literals). Falls back to unescapeString(_:) for \xNN-escaped strings.

    Throws

    TxRepError.invalidValue(key:) if neither decoder succeeds.

    Declaration

    Swift

    public static func decodeMemoText(_ s: String) throws -> String

    Parameters

    s

    Raw value string from the TxRep key-value map.

    Return Value

    The decoded memo text.

    Show on GitHub

Required-field helpers (throw missingValue when absent)

  • Require a hex-encoded binary field from the map.

    Throws missingValue when the key is absent. Re-throws any hex-decoding error as invalidValue(key:) using the field key, not the raw value string, so that error messages contain the TxRep field name.

    Throws

    TxRepError.missingValue(key:) / TxRepError.invalidValue(key:).

    Declaration

    Swift

    public static func requireHex(_ map: [String : String], _ key: String) throws -> Data

    Parameters

    map

    Key-value map from parse(_:).
    key

    The TxRep field key, e.g. "signatures[0].hint".

    Return Value

    Decoded binary Data.

    Show on GitHub

  • Require a hex-encoded field and wrap the result in a WrappedData4.

    Declaration

    Swift

    public static func requireWrappedData4(_ map: [String : String], _ key: String) throws -> WrappedData4
    Show on GitHub

  • Require a hex-encoded field and wrap the result in a WrappedData12.

    Declaration

    Swift

    public static func requireWrappedData12(_ map: [String : String], _ key: String) throws -> WrappedData12
    Show on GitHub

  • Require a hex-encoded field and wrap the result in a WrappedData32.

    Declaration

    Swift

    public static func requireWrappedData32(_ map: [String : String], _ key: String) throws -> WrappedData32
    Show on GitHub

  • Require a quoted/escaped string field from the map.

    Throws missingValue when absent, invalidValue (with the field key) when the string cannot be unescaped.

    Declaration

    Swift

    public static func requireString(_ map: [String : String], _ key: String) throws -> String
    Show on GitHub

  • Require an Int64 field from the map.

    Declaration

    Swift

    public static func requireInt64(_ map: [String : String], _ key: String) throws -> Int64
    Show on GitHub

  • Require a UInt64 field from the map.

    Declaration

    Swift

    public static func requireUInt64(_ map: [String : String], _ key: String) throws -> UInt64
    Show on GitHub

  • Require a MuxedAccountXDR field from the map.

    Throws missingValue when absent, invalidValue(key: <field key>) when invalid.

    Declaration

    Swift

    public static func requireMuxedAccount(_ map: [String : String], _ key: String) throws -> MuxedAccountXDR
    Show on GitHub

  • Require a PublicKey (account ID) field from the map.

    Declaration

    Swift

    public static func requireAccountId(_ map: [String : String], _ key: String) throws -> PublicKey
    Show on GitHub

  • Require an AssetXDR field from the map (compact single-line format).

    Declaration

    Swift

    public static func requireAsset(_ map: [String : String], _ key: String) throws -> AssetXDR
    Show on GitHub

  • Require a SignerKeyXDR field from the map.

    Declaration

    Swift

    public static func requireSignerKey(_ map: [String : String], _ key: String) throws -> SignerKeyXDR
    Show on GitHub

  • Require an AllowTrustOpAssetXDR field from the map.

    Declaration

    Swift

    public static func requireAllowTrustAsset(_ map: [String : String], _ key: String) throws -> AllowTrustOpAssetXDR
    Show on GitHub

  • Require a liquidity pool ID field from the map, accepting either a 64-character lowercase hex string or an L-address StrKey (as used by SEP-0011 and the original hand-written TxRep serialiser).

    Throws

    TxRepError.missingValue(key:) if the key is absent, TxRepError.invalidValue(key:) if the value is neither valid hex nor a valid L-address.

    Declaration

    Swift

    public static func requireLiquidityPoolId(_ map: [String : String], _ key: String) throws -> WrappedData32

    Parameters

    map

    Key-value map from parse(_:).
    key

    The TxRep field key.

    Return Value

    The liquidity pool ID as a WrappedData32.

    Show on GitHub

  • Parse a liquidity pool ID from a string, accepting either a 64-character hex string or an L-address StrKey.

    Throws

    TxRepError.invalidValue(key:) if the value cannot be parsed.

    Declaration

    Swift

    public static func parseLiquidityPoolId(_ value: String) throws -> WrappedData32

    Parameters

    value

    Hex-64 or L-address StrKey string.

    Return Value

    Decoded WrappedData32.

    Show on GitHub