feat(svm-sdk): add serialized versioned transaction and serialized transaction message to printed svm tx (#8402)

Author: xeno097

.changeset/unsigned-tx-serialization.md

@@ -0,0 +1,5 @@
+---
+"@hyperlane-xyz/sealevel-sdk": minor
+---
+
+Added `serializeUnsignedTransaction` to produce base58-encoded unsigned v0 transactions and messages compatible with the Rust Sealevel CLI output. `transactionToPrintableJson` now includes `transactionBase58`, `messageBase58`, and `annotation` fields alongside the existing human-readable format.

typescript/svm-sdk/src/clients/signer.ts

@@ -18,8 +18,16 @@ import { type AltVM } from '@hyperlane-xyz/provider-sdk';
 import { assert, rootLogger, strip0x } from '@hyperlane-xyz/utils';
 
 import { createRpc } from '../rpc.js';
-import { buildTransactionMessage } from '../tx.js';
-import type { SvmReceipt, SvmRpc, SvmTransaction } from '../types.js';
+import {
+  buildTransactionMessage,
+  serializeUnsignedTransaction,
+} from '../tx.js';
+import type {
+  AnnotatedSvmTransaction,
+  SvmReceipt,
+  SvmRpc,
+  SvmTransaction,
+} from '../types.js';
 
 import { SvmProvider } from './provider.js';
 import { DEFAULT_COMPUTE_UNITS } from '../constants.js';
@@ -117,15 +125,23 @@ export class SvmSigner
   }
 
   async transactionToPrintableJson(
-    transaction: SvmTransaction,
+    transaction: AnnotatedSvmTransaction,
   ): Promise<object> {
+    const { transactionBase58, messageBase58 } = serializeUnsignedTransaction(
+      transaction.instructions,
+      this.signer.address,
+    );
+
     return {
+      annotation: transaction.annotation,
       instructions: transaction.instructions.map((ix) => ({
         programAddress: ix.programAddress,
         accounts: ix.accounts,
         data: ix.data ? Buffer.from(ix.data).toString('hex') : undefined,
       })),
       computeUnits: transaction.computeUnits,
+      transaction_base58: transactionBase58,
+      message_base58: messageBase58,
     };
   }
 

typescript/svm-sdk/src/index.ts

@@ -75,7 +75,11 @@ export type {
 export { resolveProgram } from './deploy/resolve-program.js';
 
 // Transaction utilities
-export { getComputeBudgetInstructions, buildTransactionMessage } from './tx.js';
+export {
+  getComputeBudgetInstructions,
+  buildTransactionMessage,
+  serializeUnsignedTransaction,
+} from './tx.js';
 
 // PDA derivation
 export {

typescript/svm-sdk/src/tx.ts

@@ -2,9 +2,16 @@ import {
   type Address,
   type Blockhash,
   type Instruction,
+  type ReadonlyUint8Array,
   type TransactionSigner,
   appendTransactionMessageInstructions,
+  blockhash,
+  compileTransactionMessage,
   createTransactionMessage,
+  getBase58Decoder,
+  getCompiledTransactionMessageEncoder,
+  getShortU16Encoder,
+  setTransactionMessageFeePayer,
   setTransactionMessageFeePayerSigner,
   setTransactionMessageLifetimeUsingBlockhash,
 } from '@solana/kit';
@@ -92,3 +99,74 @@ export function transactionToInstructions(
   const computeBudgetIxs = getComputeBudgetInstructions(computeUnits);
   return [...computeBudgetIxs, ...tx.instructions];
 }
+
+// ---------------------------------------------------------------------------
+// Unsigned transaction serialization (Squads-compatible v0 format)
+// ---------------------------------------------------------------------------
+
+const base58Decoder = getBase58Decoder();
+const messageEncoder = getCompiledTransactionMessageEncoder();
+const shortU16Encoder = getShortU16Encoder();
+
+/** Default blockhash (32 zero bytes) that needs to be replaced at submission time */
+const DEFAULT_BLOCKHASH = blockhash('11111111111111111111111111111111');
+
+/**
+ * Builds the wire bytes of an unsigned versioned (v0) transaction.
+ * Prepends compact-u16 signature count + N zero-filled 64-byte signature
+ * slots to the compiled message bytes.
+ */
+function buildUnsignedTransactionBytes(
+  numSigners: number,
+  messageBytes: ReadonlyUint8Array,
+): Uint8Array {
+  const sigCountBytes = shortU16Encoder.encode(numSigners);
+  const sigsLen = numSigners * 64;
+  const result = new Uint8Array(
+    sigCountBytes.length + sigsLen + messageBytes.length,
+  );
+  result.set(sigCountBytes, 0);
+  // signature slots are already zero-filled by Uint8Array constructor
+  result.set(messageBytes, sigCountBytes.length + sigsLen);
+  return result;
+}
+
+/**
+ * Serializes an SvmTransaction into base58-encoded formats compatible
+ * with the Squads multisig UI.
+ *
+ * Produces two representations:
+ * - `transaction_base58`: full unsigned v0 transaction (signatures + message)
+ * - `message_base58`: compiled message only (no signature wrapper)
+ *
+ * Both use a default (all-zeros) blockhash since these are unsigned
+ * transactions intended for offline / multisig signing workflows.
+ */
+export function serializeUnsignedTransaction(
+  instructions: SvmInstruction[],
+  feePayer: Address,
+): { transactionBase58: string; messageBase58: string } {
+  const txMessage = createTransactionMessage({ version: 0 });
+  const withFeePayer = setTransactionMessageFeePayer(feePayer, txMessage);
+  const withLifetime = setTransactionMessageLifetimeUsingBlockhash(
+    { blockhash: DEFAULT_BLOCKHASH, lastValidBlockHeight: 0n },
+    withFeePayer,
+  );
+  const withInstructions = appendTransactionMessageInstructions(
+    instructions,
+    withLifetime,
+  );
+
+  const compiled = compileTransactionMessage(withInstructions);
+  const messageBytes = messageEncoder.encode(compiled);
+
+  const transactionBytes = buildUnsignedTransactionBytes(
+    compiled.header.numSignerAccounts,
+    messageBytes,
+  );
+
+  return {
+    transactionBase58: base58Decoder.decode(transactionBytes),
+    messageBase58: base58Decoder.decode(messageBytes),
+  };
+}