feat: try big endian patch for solana verifyTransacion

pranavjain97 · pranavjain97 · commit af2865983da7 · 2025-10-08T16:58:36.000-04:00
Ticket: WP-6284
diff --git a/S390X_SOLANA_FIX_README.md b/S390X_SOLANA_FIX_README.md
@@ -0,0 +1,109 @@
+# s390x Solana Endianness Fix
+
+## Problem
+
+On s390x (big-endian) architecture, the Solana SDK incorrectly parses transaction amounts in `explainTransaction()`.
+
+**Example:**
+
+- Expected amount: 500000 lamports (0.0005 SOL)
+- Parsed amount: 2351168177045504000 (garbage value)
+
+## Root Cause
+
+Solana stores transaction data (including amounts) in little-endian format in Buffers. On big-endian architectures like s390x, Node.js Buffer methods (`readBigUInt64LE`, `readUInt32LE`, etc.) do not correctly swap bytes when reading little-endian data, causing incorrect values to be read from the transaction buffers.
+
+The issue occurs in:
+
+- `@bitgo-beta/sdk-coin-sol/src/sol.ts:255` - `explainTransaction()` method
+- Specifically when reading `instruction.params.amount` from the transaction buffer
+
+## Solution
+
+The `s390x-solana-endianness-fix.js` file monkey-patches Node.js Buffer prototype methods to correctly handle little-endian reads on big-endian systems by manually swapping bytes.
+
+## Integration
+
+### Method 1: Load at Application Startup (Recommended)
+
+Edit `bin/advanced-wallet-manager` to load the fix before any other modules:
+
+```javascript
+#!/usr/bin/env node
+
+// Load s390x fix FIRST, before any other imports
+require('../s390x-solana-endianness-fix');
+
+process.on('unhandledRejection', (reason, promise) => {
+  console.error('----- Unhandled Rejection at -----');
+  console.error(promise);
+  console.error('----- Reason -----');
+  console.error(reason);
+});
+
+const { init } = require('../dist/src/app');
+
+if (require.main === module) {
+  init().catch((err) => {
+    console.log(`Fatal error: ${err.message}`);
+    console.log(err.stack);
+  });
+}
+```
+
+### Method 2: Load via NODE_OPTIONS
+
+Set the environment variable to preload the fix:
+
+```bash
+NODE_OPTIONS="--require ./s390x-solana-endianness-fix.js" npm start
+```
+
+### Method 3: Load in Docker
+
+Add to your `Dockerfile`:
+
+```dockerfile
+# Copy the fix file
+COPY s390x-solana-endianness-fix.js /app/
+
+# Set NODE_OPTIONS to preload it
+ENV NODE_OPTIONS="--require /app/s390x-solana-endianness-fix.js"
+```
+
+## Verification
+
+When the fix is loaded successfully, you should see this console output:
+
+```
+🔧 Applying s390x Solana endianness fix...
+✅ s390x Solana endianness fix applied successfully
+   Patched methods: readBigUInt64LE, readBigInt64LE, readUInt32LE, readInt32LE, readUInt16LE, readInt16LE
+```
+
+On non-s390x architectures, you'll see:
+
+```
+ℹ️  s390x Solana endianness fix: Not needed on x64
+```
+
+## Testing
+
+After applying the fix, test with a Solana transaction to verify amounts are parsed correctly:
+
+```bash
+# The amount should now be parsed correctly as 500000 instead of 2351168177045504000
+```
+
+## Technical Details
+
+The fix patches these Buffer methods:
+
+- `readBigUInt64LE` - Used for Solana amounts (u64/lamports)
+- `readBigInt64LE` - Used for signed 64-bit values
+- `readUInt32LE` - Used for 32-bit values in transaction data
+- `readInt32LE` - Used for signed 32-bit values
+- `readUInt16LE` - Used for 16-bit values
+- `readInt16LE` - Used for signed 16-bit values
+
+Each patched method manually reads bytes in little-endian order and constructs the correct value, effectively reversing the byte order that the big-endian system would naturally use.
diff --git a/bin/advanced-wallet-manager b/bin/advanced-wallet-manager
@@ -1,5 +1,9 @@
 #!/usr/bin/env node
 
+// Load s390x Solana endianness fix FIRST, before any other imports
+// This patches Buffer methods to correctly handle little-endian data on big-endian architectures
+require('../s390x-solana-endianness-fix');
+
 // TODO: Remove this unhandledRejection hook once BG-49996 is implemented.
 process.on('unhandledRejection', (reason, promise) => {
   console.error('----- Unhandled Rejection at -----');
diff --git a/s390x-solana-endianness-fix.js b/s390x-solana-endianness-fix.js
@@ -0,0 +1,162 @@
+/**
+ * Solana s390x Big-Endian Fix
+ *
+ * Problem:
+ * On s390x (big-endian) architecture, the Solana SDK incorrectly parses transaction amounts.
+ * When parsing Solana transactions in explainTransaction(), the amount field reads garbage values
+ * instead of the correct lamport amounts (e.g., reads 2351168177045504000 instead of 500000).
+ *
+ * Root Cause:
+ * Solana stores transaction data (including amounts) in little-endian format in Buffers.
+ * On big-endian architectures like s390x, Node.js Buffer methods (readBigUInt64LE, readUInt32LE, etc.)
+ * do not correctly swap bytes when reading little-endian data.
+ *
+ * Solution:
+ * This patch monkey-patches Buffer.prototype methods to correctly handle little-endian reads
+ * on big-endian systems by manually swapping bytes in the correct order.
+ *
+ * Usage:
+ * Load this file BEFORE initializing the Solana SDK:
+ *   require('./s390x-solana-endianness-fix');
+ */
+
+// Only apply patch on s390x architecture
+if (process.arch === 's390x') {
+  console.log('🔧 Applying s390x Solana endianness fix...');
+
+  // Store original methods
+  const originalReadBigUInt64LE = Buffer.prototype.readBigUInt64LE;
+  const originalReadBigInt64LE = Buffer.prototype.readBigInt64LE;
+  const originalReadUInt32LE = Buffer.prototype.readUInt32LE;
+  const originalReadInt32LE = Buffer.prototype.readInt32LE;
+  const originalReadUInt16LE = Buffer.prototype.readUInt16LE;
+  const originalReadInt16LE = Buffer.prototype.readInt16LE;
+
+  /**
+   * Manually read little-endian BigUInt64 by swapping bytes
+   * Solana amounts are stored as u64 (8-byte unsigned integers)
+   */
+  function readBigUInt64LEFixed(offset = 0) {
+    // Read 8 bytes and construct BigInt in little-endian order
+    let result = 0n;
+    for (let i = 7; i >= 0; i--) {
+      result = (result << 8n) | BigInt(this[offset + i]);
+    }
+    return result;
+  }
+
+  /**
+   * Manually read little-endian BigInt64 by swapping bytes
+   */
+  function readBigInt64LEFixed(offset = 0) {
+    let result = 0n;
+    for (let i = 7; i >= 0; i--) {
+      result = (result << 8n) | BigInt(this[offset + i]);
+    }
+    // Handle two's complement for signed values
+    if (result >= 0x8000000000000000n) {
+      result = result - 0x10000000000000000n;
+    }
+    return result;
+  }
+
+  /**
+   * Manually read little-endian UInt32 by swapping bytes
+   */
+  function readUInt32LEFixed(offset = 0) {
+    return (
+      this[offset] |
+      (this[offset + 1] << 8) |
+      (this[offset + 2] << 16) |
+      (this[offset + 3] * 0x1000000) // Use multiplication to avoid signed int issues
+    );
+  }
+
+  /**
+   * Manually read little-endian Int32 by swapping bytes
+   */
+  function readInt32LEFixed(offset = 0) {
+    const value =
+      this[offset] | (this[offset + 1] << 8) | (this[offset + 2] << 16) | (this[offset + 3] << 24);
+    return value;
+  }
+
+  /**
+   * Manually read little-endian UInt16 by swapping bytes
+   */
+  function readUInt16LEFixed(offset = 0) {
+    return this[offset] | (this[offset + 1] << 8);
+  }
+
+  /**
+   * Manually read little-endian Int16 by swapping bytes
+   */
+  function readInt16LEFixed(offset = 0) {
+    const value = this[offset] | (this[offset + 1] << 8);
+    return value & 0x8000 ? value | 0xffff0000 : value;
+  }
+
+  // Apply patches
+  Buffer.prototype.readBigUInt64LE = function (offset = 0) {
+    try {
+      return readBigUInt64LEFixed.call(this, offset);
+    } catch (err) {
+      console.error('s390x readBigUInt64LE error:', err);
+      return originalReadBigUInt64LE.call(this, offset);
+    }
+  };
+
+  Buffer.prototype.readBigInt64LE = function (offset = 0) {
+    try {
+      return readBigInt64LEFixed.call(this, offset);
+    } catch (err) {
+      console.error('s390x readBigInt64LE error:', err);
+      return originalReadBigInt64LE.call(this, offset);
+    }
+  };
+
+  Buffer.prototype.readUInt32LE = function (offset = 0) {
+    try {
+      return readUInt32LEFixed.call(this, offset);
+    } catch (err) {
+      console.error('s390x readUInt32LE error:', err);
+      return originalReadUInt32LE.call(this, offset);
+    }
+  };
+
+  Buffer.prototype.readInt32LE = function (offset = 0) {
+    try {
+      return readInt32LEFixed.call(this, offset);
+    } catch (err) {
+      console.error('s390x readInt32LE error:', err);
+      return originalReadInt32LE.call(this, offset);
+    }
+  };
+
+  Buffer.prototype.readUInt16LE = function (offset = 0) {
+    try {
+      return readUInt16LEFixed.call(this, offset);
+    } catch (err) {
+      console.error('s390x readUInt16LE error:', err);
+      return originalReadUInt16LE.call(this, offset);
+    }
+  };
+
+  Buffer.prototype.readInt16LE = function (offset = 0) {
+    try {
+      return readInt16LEFixed.call(this, offset);
+    } catch (err) {
+      console.error('s390x readInt16LE error:', err);
+      return originalReadInt16LE.call(this, offset);
+    }
+  };
+
+  console.log('✅ s390x Solana endianness fix applied successfully');
+  console.log(
+    '   Patched methods: readBigUInt64LE, readBigInt64LE, readUInt32LE, readInt32LE, readUInt16LE, readInt16LE',
+  );
+} else {
+  console.log('ℹ️  s390x Solana endianness fix: Not needed on', process.arch);
+}
+
+module.exports = {};
