@msafe/sui3-sdk 1.0.20 → 1.0.22

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@msafe/sui3-sdk",
-  "version": "1.0.20",
+  "version": "1.0.22",
   "description": "SDK for MSafe SUI V3",
   "type": "module",
   "module": "./dist/index.js",

package/src/core/MSafeAccount.ts

@@ -25,9 +25,9 @@ import { OwnedCoin } from '@/types/assets';
 import { Pagination, PendingTx, SimulationResult } from '@/types/msafe';
 import { CoinHelper } from '@/utils';
 import { HexToUint8Array } from '@/utils/buffer';
-import { prepareGasFunding } from '@/utils/gasFunding';
+import { parkedPayloadHex, prepareGasFunding } from '@/utils/gasFunding';
 import { BatchObjectOptions, getAllOwnedObjects, type OwnedObjectData } from '@/utils/iter/object';
-import { toSuiTransaction } from '@/utils/transaction';
+import { getIntentionContent, toSuiTransaction, transactionFromContent } from '@/utils/transaction';
 
 export class MSafeAccount {
   public multiSig: MultiSigAccount;
@@ -138,34 +138,18 @@ export class MSafeAccount {
   async simulateIntention(
     request: Omit<IProposeIntentionRequest, 'msafeAddress' | 'signature'> & {
       txb?: Transaction;
+      preferAddressBalance?: boolean;
+      excludeObjectIds?: Iterable<string>;
     },
   ) {
-    let txb: Transaction;
-    if (request.txb) {
-      txb = request.txb;
-    } else {
-      const appHelper = appHelpers.getAppHelper(request.application);
-      if (!appHelper) {
-        throw new Error(`Can't find app helper for application ${request.application}`);
-      }
-      txb = toSuiTransaction(
-        await appHelper.build({
-          network: this.globals.config.network,
-          intentionData: request.intention,
-          txType: request.txType,
-          txSubType: request.txSubType,
-          clientUrl: this.globals.config.suiClient.url,
-          account: {
-            address: this.address,
-            publicKey: fromHex(this.address),
-            chains: [SUI_MAINNET_CHAIN, SUI_TESTNET_CHAIN],
-            features: [],
-          },
-        }),
-      );
-    }
+    const txb = await this.buildTxFromIntention(request);
     txb.setSender(this.address);
-    return this.simulator.simulate({ txb, sender: this.address });
+    return this.simulator.simulate({
+      txb,
+      sender: this.address,
+      preferAddressBalance: request.preferAddressBalance,
+      excludeObjectIds: request.excludeObjectIds,
+    });
   }
 
   async proposeIntention(input: Omit<IProposeIntentionRequest, 'signature' | 'msafeAddress'>) {
@@ -188,32 +172,11 @@ export class MSafeAccount {
   async proposeIntentionAndBuildVote(
     input: Omit<IProposeIntentionAndBuildAndVoteRequest, 'signature' | 'msafeAddress' | 'payload' | 'digest'> & {
       txb?: Transaction;
+      preferAddressBalance?: boolean;
+      excludeObjectIds?: Iterable<string>;
     },
   ): Promise<void> {
-    let txb: Transaction;
-    if (input.txb) {
-      txb = input.txb;
-    } else {
-      const appHelper = appHelpers.getAppHelper(input.application);
-      if (!appHelper) {
-        throw new Error(`Can't find app helper for application ${input.application}`);
-      }
-      txb = toSuiTransaction(
-        await appHelper.build({
-          network: this.globals.config.network,
-          intentionData: input.intention,
-          txType: input.txType,
-          txSubType: input.txSubType,
-          clientUrl: this.globals.config.suiClient.url,
-          account: {
-            address: this.address,
-            publicKey: fromHex(this.address),
-            chains: [SUI_MAINNET_CHAIN, SUI_TESTNET_CHAIN],
-            features: [],
-          },
-        }),
-      );
-    }
+    const txb = await this.buildTxFromIntention(input);
     txb.setGasPrice(input.gasPrice);
     txb.setSender(this.address);
     await prepareGasFunding({
@@ -222,14 +185,20 @@ export class MSafeAccount {
       owner: this.address,
       gasPrice: input.gasPrice,
       gasBudget: input.gasBudget,
+      preferAddressBalance: input.preferAddressBalance,
+      excludeObjectIds: input.excludeObjectIds,
     });
     const payload = await txb.build({ client: this.globals.suiClient });
     const digest = await txb.getDigest({ client: this.globals.suiClient });
 
     const signature = await this.wallet.signTransactionBlock({ transactionBlock: payload });
 
+    const apiInput = { ...input };
+    delete apiInput.txb;
+    delete apiInput.preferAddressBalance;
+    delete apiInput.excludeObjectIds;
     return this.backend.proposeIntentionAndBuildVote({
-      ...input,
+      ...apiInput,
       payload: toHex(payload),
       digest,
       msafeAddress: this.address,
@@ -356,25 +325,16 @@ export class MSafeAccount {
 
   async simulateBuildTransaction(): Promise<SimulationResult> {
     const intention = await this.backend.getNextIntention({ msafeAddress: this.address });
-    const appHelper = appHelpers.getAppHelper(intention.application);
-    if (!appHelper) {
-      throw new Error(`Can't find app helper for application ${intention.application}`);
+    const parked = parkedPayloadHex(intention.intention);
+    if (parked) {
+      return this.simulator.simulateBuilt(fromHex(parked));
     }
-    const txb = toSuiTransaction(
-      await appHelper.build({
-        network: this.globals.config.network,
-        intentionData: intention.intention,
-        txType: intention.txType as TransactionType,
-        txSubType: intention.txSubType,
-        clientUrl: this.globals.config.suiClient.url,
-        account: {
-          address: this.address,
-          publicKey: fromHex(this.address),
-          chains: [SUI_MAINNET_CHAIN, SUI_TESTNET_CHAIN],
-          features: [],
-        },
-      }),
-    );
+    const txb = await this.buildTxFromIntention({
+      application: intention.application,
+      intention: intention.intention,
+      txType: intention.txType as TransactionType,
+      txSubType: intention.txSubType,
+    });
     txb.setSender(this.address);
     return this.simulator.simulate({ txb, sender: this.address });
   }
@@ -427,6 +387,56 @@ export class MSafeAccount {
     });
   }
 
+  /**
+   * Resolve a Transaction from propose/simulate input.
+   * 1. Caller-supplied `txb` (generic store path — do not rebuild).
+   * 2. Registered app helper `build`.
+   * 3. Unregistered app: restore from `intention.content` (JSON or hex).
+   */
+  private async buildTxFromIntention(input: {
+    application: string;
+    txType: TransactionType;
+    txSubType: string;
+    intention: unknown;
+    txb?: Transaction;
+  }): Promise<Transaction> {
+    if (input.txb) {
+      return input.txb;
+    }
+
+    let appHelper: ReturnType<typeof appHelpers.getAppHelper> | undefined;
+    try {
+      appHelper = appHelpers.getAppHelper(input.application);
+    } catch {
+      appHelper = undefined;
+    }
+
+    if (appHelper) {
+      return toSuiTransaction(
+        await appHelper.build({
+          network: this.globals.config.network,
+          intentionData: input.intention,
+          txType: input.txType,
+          txSubType: input.txSubType,
+          clientUrl: this.globals.config.suiClient.url,
+          account: {
+            address: this.address,
+            publicKey: fromHex(this.address),
+            chains: [SUI_MAINNET_CHAIN, SUI_TESTNET_CHAIN],
+            features: [],
+          },
+        }),
+      );
+    }
+
+    const content = getIntentionContent(input.intention);
+    if (content != null) {
+      return transactionFromContent(content);
+    }
+
+    throw new Error(`Can't find app helper for application ${input.application}`);
+  }
+
   private calculateWeightFromVotes(votes: { userAddress: string }[]) {
     return this.calculateWeight(votes.map((vote) => vote.userAddress));
   }

package/src/simulate/simulator.ts

@@ -23,7 +23,12 @@ function gasObjectToReference(gas: SuiClientTypes.ChangedObject | null | undefin
 export class Simulator {
   constructor(private globals: MSafeGlobals) {}
 
-  public async simulate(input: { txb: Transaction; sender: string }): Promise<SimulationResult> {
+  public async simulate(input: {
+    txb: Transaction;
+    sender: string;
+    preferAddressBalance?: boolean;
+    excludeObjectIds?: Iterable<string>;
+  }): Promise<SimulationResult> {
     const tx = this.copyTransaction(input.txb);
 
     const { suiClient } = this.globals;
@@ -40,6 +45,8 @@ export class Simulator {
         suiClient,
         owner: input.sender,
         gasPrice,
+        preferAddressBalance: input.preferAddressBalance,
+        excludeObjectIds: input.excludeObjectIds,
       });
     } catch (e: unknown) {
       const message = e instanceof Error ? e.message : String(e);
@@ -62,9 +69,19 @@ export class Simulator {
       };
     }
 
+    return this.inspectBuilt(built, gasPrice);
+  }
+
+  /** Dry-run a frozen payload without re-selecting gas. */
+  public async simulateBuilt(built: Uint8Array): Promise<SimulationResult> {
+    const gasPrice = await this.getGasPrice();
+    return this.inspectBuilt(built, gasPrice);
+  }
+
+  private async inspectBuilt(built: Uint8Array, gasPrice: bigint): Promise<SimulationResult> {
     let inspectResult: SimulateDryRunResponse;
     try {
-      inspectResult = await suiClient.simulateTransaction({
+      inspectResult = await this.globals.suiClient.simulateTransaction({
         transaction: built,
         include: {
           effects: true,

package/src/utils/gasFunding.ts

@@ -1,7 +1,7 @@
 import type { SuiClientTypes } from '@mysten/sui/client';
 import type { SuiGrpcClient } from '@mysten/sui/grpc';
 import { Transaction } from '@mysten/sui/transactions';
-import { normalizeStructTag, normalizeSuiObjectId } from '@mysten/sui/utils';
+import { fromHex, normalizeStructTag, normalizeSuiObjectId } from '@mysten/sui/utils';
 
 import { createCoinReservationRef } from '@/utils/coinReservation';
 import { getAllCoins, SUI_COIN } from '@/utils/sui';
@@ -59,18 +59,81 @@ interface SuiGasFunding {
 }
 
 function collectUsedObjectIds(tx: Transaction): Set<string> {
-  return tx.getData().inputs.reduce<Set<string>>((used, input) => {
+  const used = tx.getData().inputs.reduce<Set<string>>((acc, input) => {
     const immOrOwned = input.Object?.ImmOrOwnedObject?.objectId;
     if (immOrOwned) {
-      used.add(normalizeSuiObjectId(immOrOwned));
-      return used;
+      acc.add(normalizeSuiObjectId(immOrOwned));
+      return acc;
     }
     const unresolved = input.UnresolvedObject?.objectId;
     if (unresolved) {
-      used.add(normalizeSuiObjectId(unresolved));
+      acc.add(normalizeSuiObjectId(unresolved));
     }
-    return used;
+    return acc;
   }, new Set<string>());
+
+  (tx.getData().gasData.payment ?? []).forEach((payment) => {
+    if (payment.objectId) {
+      used.add(normalizeSuiObjectId(payment.objectId));
+    }
+  });
+  return used;
+}
+
+function addExcludeObjectIds(used: Set<string>, excludeObjectIds?: Iterable<string>) {
+  Array.from(excludeObjectIds ?? [], (id) => used.add(normalizeSuiObjectId(id)));
+  return used;
+}
+
+function payloadToTransaction(payload: string | Uint8Array): Transaction {
+  if (typeof payload !== 'string') {
+    return Transaction.from(payload);
+  }
+  if (/^[0-9a-fA-F]+$/.test(payload) && payload.length % 2 === 0) {
+    return Transaction.from(fromHex(payload));
+  }
+  return Transaction.from(payload);
+}
+
+/** Object IDs a built payload already pins (inputs + gas payment). */
+export function collectPayloadObjectIds(payload: string | Uint8Array): string[] {
+  return [...collectUsedObjectIds(payloadToTransaction(payload))];
+}
+
+/**
+ * Parked queue item: intention was saved with a built hex payload + digest
+ * so build-next can promote it without rebuilding.
+ */
+export function parkedPayloadHex(intention: unknown): string | undefined {
+  if (!intention || typeof intention !== 'object') {
+    return undefined;
+  }
+  const { content, digest } = intention as { content?: unknown; digest?: unknown };
+  if (typeof content !== 'string' || typeof digest !== 'string' || !digest) {
+    return undefined;
+  }
+  if (!/^[0-9a-fA-F]+$/.test(content) || content.length < 64) {
+    return undefined;
+  }
+  return content;
+}
+
+/** Coins already pinned by the current pending tx and any parked future payloads. */
+export function collectQueueExcludeObjectIds(input: {
+  pendingPayload?: string;
+  parkedPayloads?: Array<string | undefined>;
+}): string[] {
+  const ids = new Set<string>();
+  if (input.pendingPayload) {
+    collectPayloadObjectIds(input.pendingPayload).forEach((id) => ids.add(id));
+  }
+  (input.parkedPayloads ?? []).forEach((payload) => {
+    if (!payload) {
+      return;
+    }
+    collectPayloadObjectIds(payload).forEach((id) => ids.add(id));
+  });
+  return [...ids];
 }
 
 /**
@@ -96,8 +159,13 @@ function txConsumesOwnedSuiCoins(tx: Transaction): boolean {
   });
 }
 
-async function loadSuiGasFunding(suiClient: SuiGrpcClient, owner: string, tx: Transaction): Promise<SuiGasFunding> {
-  const usedObjectIds = collectUsedObjectIds(tx);
+async function loadSuiGasFunding(
+  suiClient: SuiGrpcClient,
+  owner: string,
+  tx: Transaction,
+  excludeObjectIds?: Iterable<string>,
+): Promise<SuiGasFunding> {
+  const usedObjectIds = addExcludeObjectIds(collectUsedObjectIds(tx), excludeObjectIds);
   const [coins, balanceRes] = await Promise.all([
     getAllCoins({ suiClient, owner, coinType: SUI_COIN }),
     suiClient.getBalance({ owner, coinType: SUI_COIN }),
@@ -186,6 +254,7 @@ export async function selectGasFunding(input: {
   suiClient: SuiGrpcClient;
   owner: string;
   gasBudget: bigint;
+  excludeObjectIds?: Iterable<string>;
 }): Promise<GasFundingResult> {
   const { tx, suiClient, owner, gasBudget } = input;
   const { payment } = tx.getData().gasData;
@@ -196,7 +265,7 @@ export async function selectGasFunding(input: {
   // skips re-selection and fails InsufficientGas under a tight budget.
   // Selection below always overwrites payment via setGasPayment(...).
   if (payment != null && payment.length > 0) {
-    const funding = await loadSuiGasFunding(suiClient, owner, tx);
+    const funding = await loadSuiGasFunding(suiClient, owner, tx, input.excludeObjectIds);
     return {
       mode: 'classic',
       gasBudget,
@@ -205,7 +274,7 @@ export async function selectGasFunding(input: {
     };
   }
 
-  const funding = await loadSuiGasFunding(suiClient, owner, tx);
+  const funding = await loadSuiGasFunding(suiClient, owner, tx, input.excludeObjectIds);
   const { paymentCoins, coinBalance, addressBalance, total } = funding;
 
   if (total < gasBudget) {
@@ -289,13 +358,21 @@ export async function estimateGasBudget(input: {
   suiClient: SuiGrpcClient;
   owner: string;
   gasPrice: bigint;
+  excludeObjectIds?: Iterable<string>;
+  preferAddressBalance?: boolean;
 }): Promise<bigint> {
   const { tx, suiClient, owner, gasPrice } = input;
-  const funding = await loadSuiGasFunding(suiClient, owner, tx);
-  if (funding.total <= 0n) {
+  const funding = input.preferAddressBalance
+    ? {
+        ...(await loadSuiGasFunding(suiClient, owner, tx, input.excludeObjectIds)),
+        paymentCoins: [] as PaymentCoinRef[],
+        coinBalance: 0n,
+      }
+    : await loadSuiGasFunding(suiClient, owner, tx, input.excludeObjectIds);
+  const fundingTotal = input.preferAddressBalance ? funding.addressBalance : funding.total;
+  if (fundingTotal <= 0n) {
     throw new InsufficientGasFundsError(0n, funding.coinBalance, funding.addressBalance);
   }
-
   const { budget, payment } = tx.getData().gasData;
   // app-store / Mysten pre-build can leave payment:[] with budget "0".
   // Mysten's setGasBudget skips when budget is the string "0" (truthy), so clear first.
@@ -341,8 +418,18 @@ export async function prepareGasFunding(input: {
   owner: string;
   gasPrice: bigint;
   gasBudget?: bigint;
+  /**
+   * Force Address Balance gas (`payment: []`). Prefer {@link excludeObjectIds}
+   * for queue-behind-pending so unused SUI coins can still pay.
+   */
+  preferAddressBalance?: boolean;
+  /**
+   * Queue-behind-pending: do not pick coins the current pending / parked
+   * payloads already pin. Those versions will change when the earlier tx executes.
+   */
+  excludeObjectIds?: Iterable<string>;
 }): Promise<GasFundingResult> {
-  const { tx, suiClient, owner, gasPrice } = input;
+  const { tx, suiClient, owner, gasPrice, excludeObjectIds } = input;
   const { payment, budget: existingBudget } = tx.getData().gasData;
   const bakedAddressBalanceGas = payment != null && payment.length === 0;
 
@@ -358,7 +445,14 @@ export async function prepareGasFunding(input: {
 
   if (gasBudget == null) {
     if (bakedAddressBalanceGas || existingPositive == null) {
-      gasBudget = await estimateGasBudget({ tx, suiClient, owner, gasPrice });
+      gasBudget = await estimateGasBudget({
+        tx,
+        suiClient,
+        owner,
+        gasPrice,
+        excludeObjectIds,
+        preferAddressBalance: input.preferAddressBalance,
+      });
     } else {
       gasBudget = existingPositive;
     }
@@ -370,7 +464,22 @@ export async function prepareGasFunding(input: {
   if (bakedAddressBalanceGas) {
     tx.setExpiration(null);
   }
-  return selectGasFunding({ tx, suiClient, owner, gasBudget });
+
+  if (input.preferAddressBalance) {
+    const funding = await loadSuiGasFunding(suiClient, owner, tx, excludeObjectIds);
+    if (funding.addressBalance < gasBudget) {
+      throw new InsufficientGasFundsError(gasBudget, funding.coinBalance, funding.addressBalance);
+    }
+    tx.setGasPayment([]);
+    return {
+      mode: 'addressBalance',
+      gasBudget,
+      coinBalance: funding.coinBalance,
+      addressBalance: funding.addressBalance,
+    };
+  }
+
+  return selectGasFunding({ tx, suiClient, owner, gasBudget, excludeObjectIds });
 }
 
 /**

package/src/utils/transaction.ts

@@ -1,4 +1,5 @@
 import { Transaction, isTransaction } from '@mysten/sui/transactions';
+import { fromHex } from '@mysten/sui/utils';
 
 /**
  * Normalize a transaction value to {@link Transaction}.
@@ -23,3 +24,34 @@ export function toSuiTransaction(txb: Transaction | unknown): Transaction {
 
   throw new Error('Unsupported transaction value for toSuiTransaction');
 }
+
+function isHex(str: string): boolean {
+  return /^[0-9a-fA-F]+$/.test(str);
+}
+
+export function getIntentionContent(intention: unknown): unknown {
+  if (intention && typeof intention === 'object' && 'content' in intention) {
+    return (intention as { content: unknown }).content;
+  }
+  return undefined;
+}
+
+/**
+ * Restore a Transaction from plain-tx `intention.content`.
+ * Accepts V2 JSON (`tx.toJSON()`), hex BCS bytes, or a JSON object.
+ */
+export function transactionFromContent(content: unknown): Transaction {
+  if (content instanceof Uint8Array) {
+    return Transaction.from(content);
+  }
+  if (typeof content === 'string') {
+    if (isHex(content)) {
+      return Transaction.from(fromHex(content));
+    }
+    return Transaction.from(content);
+  }
+  if (content && typeof content === 'object') {
+    return Transaction.from(JSON.stringify(content));
+  }
+  throw new Error('Invalid transaction content');
+}