@msafe/sui3-sdk 1.0.15 → 1.0.17

package/src/core/MSafeAccount.ts

@@ -25,6 +25,7 @@ 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 { BatchObjectOptions, getAllOwnedObjects, type OwnedObjectData } from '@/utils/iter/object';
 import { toSuiTransaction } from '@/utils/transaction';
 
@@ -214,8 +215,14 @@ export class MSafeAccount {
       );
     }
     txb.setGasPrice(input.gasPrice);
-    txb.setGasBudget(input.gasBudget);
     txb.setSender(this.address);
+    await prepareGasFunding({
+      tx: txb,
+      suiClient: this.globals.suiClient,
+      owner: this.address,
+      gasPrice: input.gasPrice,
+      gasBudget: input.gasBudget,
+    });
     const payload = await txb.build({ client: this.globals.suiClient });
     const digest = await txb.getDigest({ client: this.globals.suiClient });
 
@@ -334,6 +341,14 @@ export class MSafeAccount {
     }
 
     const rejectTxb = toSuiTransaction(buildRejectTxb(this.address));
+    rejectTxb.setGasPrice(input.gasPrice);
+    await prepareGasFunding({
+      tx: rejectTxb,
+      suiClient: this.suiClient,
+      owner: this.address,
+      gasPrice: input.gasPrice,
+      gasBudget: input.gasBudget,
+    });
     const digest = await rejectTxb.getDigest({ client: this.suiClient });
     const payload = await rejectTxb.build({ client: this.suiClient });
     const signature = await this.wallet.signTransactionBlock({ transactionBlock: payload });

package/src/simulate/simulator.ts

@@ -1,11 +1,11 @@
 import type { SuiClientTypes } from '@mysten/sui/client';
 import { Transaction } from '@mysten/sui/transactions';
 
-// Default to 120% o the reference gas price
 import { MSafeGlobals } from '@/globals/MSafeGlobals';
 import type { GasObjectReference, SimulationResult, SimulateDryRunResponse } from '@/types';
+import { computeGasBudget, prepareGasFunding } from '@/utils/gasFunding';
 
-const GAS_SAFE_OVERHEAD = 1000n;
+export { computeGasBudget, InsufficientGasFundsError } from '@/utils/gasFunding';
 
 function formatExecutionError(error: SuiClientTypes.ExecutionError): string {
   return error.message;
@@ -33,6 +33,23 @@ export class Simulator {
     tx.setGasPrice(gasPrice);
     tx.setSender(input.sender);
 
+    try {
+      // Resolve budget (no storageRebate) and select classic / address-balance / mixed top-up.
+      await prepareGasFunding({
+        tx,
+        suiClient,
+        owner: input.sender,
+        gasPrice,
+      });
+    } catch (e: unknown) {
+      const message = e instanceof Error ? e.message : String(e);
+      return {
+        success: false,
+        gasPrice,
+        simulationError: message,
+      };
+    }
+
     let built: Uint8Array;
     try {
       built = await tx.build({ client: suiClient });
@@ -101,16 +118,7 @@ export class Simulator {
   }
 
   private toGasBudget(gasUsed: SuiClientTypes.GasCostSummary, gasPrice: bigint) {
-    const { computationCost, storageCost, storageRebate } = gasUsed;
-    const safeOverhead = GAS_SAFE_OVERHEAD * gasPrice;
-
-    const baseComputationCostWithOverhead = BigInt(computationCost) + safeOverhead;
-
-    // do not subtract rebate for now, because it may cause normally tx gas to be lower than empty tx gas
-    const gasBudget = baseComputationCostWithOverhead + BigInt(storageCost) - BigInt(storageRebate);
-
-    // Set the budget to max(computation, computation + storage - rebate)
-    return gasBudget > baseComputationCostWithOverhead ? gasBudget : baseComputationCostWithOverhead;
+    return computeGasBudget(gasUsed, gasPrice);
   }
 
   private copyTransaction(tx: Transaction): Transaction {

package/src/utils/coinReservation.ts

@@ -0,0 +1,65 @@
+import { bcs, TypeTagSerializer } from '@mysten/sui/bcs';
+import { deriveDynamicFieldID, fromBase58, fromHex, normalizeSuiAddress, toBase58, toHex } from '@mysten/sui/utils';
+
+/**
+ * Compatibility coin-reservation ObjectRef (Mysten gas-smashing).
+ * Reserves address-balance SUI into gas payment without a persisted Coin object.
+ * Vendored because @mysten/sui does not export createCoinReservationRef publicly.
+ */
+
+const SUI_ACCUMULATOR_ROOT_OBJECT_ID = normalizeSuiAddress('0xacc');
+const ACCUMULATOR_KEY_TYPE_TAG = TypeTagSerializer.parseFromStr(
+  '0x2::accumulator::Key<0x2::balance::Balance<0x2::sui::SUI>>',
+);
+
+export const COIN_RESERVATION_MAGIC = new Uint8Array([
+  0xac, 0xac, 0xac, 0xac, 0xac, 0xac, 0xac, 0xac, 0xac, 0xac, 0xac, 0xac, 0xac, 0xac, 0xac, 0xac, 0xac, 0xac, 0xac,
+  0xac,
+]);
+
+export function isCoinReservationDigest(digestBase58: string): boolean {
+  const digestBytes = fromBase58(digestBase58);
+  const last20Bytes = digestBytes.slice(12, 32);
+  return last20Bytes.every((byte: number, i: number) => byte === COIN_RESERVATION_MAGIC[i]);
+}
+
+function deriveReservationObjectId(owner: string, chainIdentifier: string): string {
+  const keyBcs = bcs.Address.serialize(owner).toBytes();
+  const accumulatorId = deriveDynamicFieldID(SUI_ACCUMULATOR_ROOT_OBJECT_ID, ACCUMULATOR_KEY_TYPE_TAG, keyBcs);
+
+  const accBytes = fromHex(accumulatorId.slice(2));
+  const chainBytes = fromBase58(chainIdentifier);
+  if (chainBytes.length !== 32) {
+    throw new Error(`Invalid chain identifier length: expected 32 bytes, got ${chainBytes.length}`);
+  }
+  const xored = new Uint8Array(32);
+  for (let i = 0; i < 32; i++) {
+    // XOR is required to derive the reservation object ID from accumulator + chain id.
+    // eslint-disable-next-line no-bitwise
+    xored[i] = accBytes[i] ^ chainBytes[i];
+  }
+  return `0x${toHex(xored)}`;
+}
+
+export function createCoinReservationRef(
+  reservedBalance: bigint,
+  owner: string,
+  chainIdentifier: string,
+  epoch: string,
+): { objectId: string; version: string; digest: string } {
+  const digestBytes = new Uint8Array(32);
+  const view = new DataView(digestBytes.buffer);
+  view.setBigUint64(0, reservedBalance, true);
+  const epochNum = Number(epoch);
+  if (!Number.isSafeInteger(epochNum) || epochNum < 0 || epochNum > 0xffffffff) {
+    throw new Error(`Epoch ${epoch} out of u32 range for coin reservation digest`);
+  }
+  view.setUint32(8, epochNum, true);
+  digestBytes.set(COIN_RESERVATION_MAGIC, 12);
+
+  return {
+    objectId: deriveReservationObjectId(owner, chainIdentifier),
+    version: '0',
+    digest: toBase58(digestBytes),
+  };
+}

package/src/utils/gasFunding.ts

@@ -0,0 +1,309 @@
+import type { SuiClientTypes } from '@mysten/sui/client';
+import type { SuiGrpcClient } from '@mysten/sui/grpc';
+import { Transaction } from '@mysten/sui/transactions';
+import { normalizeSuiObjectId } from '@mysten/sui/utils';
+
+import { createCoinReservationRef } from '@/utils/coinReservation';
+import { getAllCoins, SUI_COIN } from '@/utils/sui';
+
+const GAS_SAFE_OVERHEAD = 1000n;
+
+export type GasFundingMode = 'classic' | 'addressBalance' | 'mixedTopUp';
+
+export interface GasFundingResult {
+  mode: GasFundingMode;
+  gasBudget: bigint;
+  coinBalance: bigint;
+  addressBalance: bigint;
+}
+
+export class InsufficientGasFundsError extends Error {
+  readonly gasBudget: bigint;
+
+  readonly coinBalance: bigint;
+
+  readonly addressBalance: bigint;
+
+  constructor(gasBudget: bigint, coinBalance: bigint, addressBalance: bigint) {
+    const total = coinBalance + addressBalance;
+    super(
+      `Insufficient gas funds: need ${gasBudget}, have coinBalance=${coinBalance} + addressBalance=${addressBalance} = ${total}`,
+    );
+    this.name = 'InsufficientGasFundsError';
+    this.gasBudget = gasBudget;
+    this.coinBalance = coinBalance;
+    this.addressBalance = addressBalance;
+  }
+}
+
+/**
+ * Gas budget must cover pre-rebate costs (computation + storage + overhead).
+ * storageRebate is refunded after execution and must not reduce the budget.
+ */
+export function computeGasBudget(
+  gasUsed: Pick<SuiClientTypes.GasCostSummary, 'computationCost' | 'storageCost'>,
+  gasPrice: bigint,
+): bigint {
+  const { computationCost, storageCost } = gasUsed;
+  const safeOverhead = GAS_SAFE_OVERHEAD * gasPrice;
+  return BigInt(computationCost) + BigInt(storageCost) + safeOverhead;
+}
+
+type PaymentCoinRef = { objectId: string; version: string; digest: string; balance: bigint };
+
+interface SuiGasFunding {
+  paymentCoins: PaymentCoinRef[];
+  coinBalance: bigint;
+  addressBalance: bigint;
+  total: bigint;
+}
+
+function collectUsedObjectIds(tx: Transaction): Set<string> {
+  return tx.getData().inputs.reduce<Set<string>>((used, input) => {
+    const immOrOwned = input.Object?.ImmOrOwnedObject?.objectId;
+    if (immOrOwned) {
+      used.add(normalizeSuiObjectId(immOrOwned));
+      return used;
+    }
+    const unresolved = input.UnresolvedObject?.objectId;
+    if (unresolved) {
+      used.add(normalizeSuiObjectId(unresolved));
+    }
+    return used;
+  }, new Set<string>());
+}
+
+async function loadSuiGasFunding(suiClient: SuiGrpcClient, owner: string, tx: Transaction): Promise<SuiGasFunding> {
+  const usedObjectIds = collectUsedObjectIds(tx);
+  const [coins, balanceRes] = await Promise.all([
+    getAllCoins({ suiClient, owner, coinType: SUI_COIN }),
+    suiClient.getBalance({ owner, coinType: SUI_COIN }),
+  ]);
+
+  const paymentCoins = coins
+    .filter((coin) => !usedObjectIds.has(normalizeSuiObjectId(coin.objectId)) && BigInt(coin.balance) > 0n)
+    .map((coin) => ({
+      objectId: coin.objectId,
+      version: coin.version,
+      digest: coin.digest,
+      balance: BigInt(coin.balance),
+    }));
+
+  const coinBalance = paymentCoins.reduce((sum, coin) => sum + coin.balance, 0n);
+  const addressBalance = BigInt(balanceRes.balance.addressBalance);
+  return {
+    paymentCoins,
+    coinBalance,
+    addressBalance,
+    total: coinBalance + addressBalance,
+  };
+}
+
+function toObjectRefs(coins: PaymentCoinRef[]) {
+  return coins.map(({ objectId, version, digest }) => ({ objectId, version, digest }));
+}
+
+/**
+ * Top up classic gas payment from address balance via compatibility coin reservation.
+ *
+ * Protocol gas-smashing (real Coin listed first): the reservation is withdrawn from
+ * address balance into that gas coin — the gas-payment equivalent of redeem_funds +
+ * mergeCoins into the primary gas coin, and it satisfies the upfront gas-budget check.
+ * (A PTB-only redeem+merge cannot fund gasBudget > coinBalance because budget is
+ * checked against gas payment before commands execute.)
+ */
+async function applyMixedTopUp(input: {
+  tx: Transaction;
+  suiClient: SuiGrpcClient;
+  owner: string;
+  paymentCoins: PaymentCoinRef[];
+  topUpAmount: bigint;
+}): Promise<void> {
+  const { tx, suiClient, owner, paymentCoins, topUpAmount } = input;
+  if (paymentCoins.length === 0) {
+    throw new Error('mixed gas top-up requires at least one SUI coin object');
+  }
+  if (topUpAmount <= 0n) {
+    tx.setGasPayment(toObjectRefs(paymentCoins));
+    return;
+  }
+
+  const [{ chainIdentifier }, { systemState }] = await Promise.all([
+    suiClient.core.getChainIdentifier(),
+    suiClient.core.getCurrentSystemState(),
+  ]);
+
+  const reservation = createCoinReservationRef(topUpAmount, owner, chainIdentifier, systemState.epoch);
+
+  // Real Coin first so reservation is smashed into the gas coin (not into address balance).
+  tx.setGasPayment([...toObjectRefs(paymentCoins), reservation]);
+}
+
+/**
+ * Select gas funding before tx.build() according to mixed coin/addressBalance policy:
+ * 1) budget without storageRebate (caller supplies computeGasBudget result)
+ * 2-3) fail if total < budget
+ * 4) coins exist and coinBal >= budget → classic setGasPayment(coins)
+ * 5) coins exist and total >= budget → mixed top-up via coin reservation
+ * 6) no usable coins and addrBal >= budget → Address Balance gas (payment: [])
+ */
+export async function selectGasFunding(input: {
+  tx: Transaction;
+  suiClient: SuiGrpcClient;
+  owner: string;
+  gasBudget: bigint;
+}): Promise<GasFundingResult> {
+  const { tx, suiClient, owner, gasBudget } = input;
+  const { payment } = tx.getData().gasData;
+
+  // Only respect an explicit *classic* gas payment (non-empty ObjectRefs).
+  // Do NOT respect payment: [] — Mysten auto-pick and plain-tx
+  // Transaction.from(builtHex) often bake address-balance gas; respecting it
+  // 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);
+    return {
+      mode: 'classic',
+      gasBudget,
+      coinBalance: funding.coinBalance,
+      addressBalance: funding.addressBalance,
+    };
+  }
+
+  const funding = await loadSuiGasFunding(suiClient, owner, tx);
+  const { paymentCoins, coinBalance, addressBalance, total } = funding;
+
+  if (total < gasBudget) {
+    throw new InsufficientGasFundsError(gasBudget, coinBalance, addressBalance);
+  }
+
+  // Prefer classic / mixed whenever owned SUI coins exist. Pure address-balance
+  // gas (payment: []) is stricter on budget and is what Mysten auto-picks when
+  // addressBalance > 0 — avoid it unless there is no usable gas coin.
+  if (paymentCoins.length > 0 && coinBalance >= gasBudget) {
+    tx.setGasPayment(toObjectRefs(paymentCoins));
+    return { mode: 'classic', gasBudget, coinBalance, addressBalance };
+  }
+
+  if (paymentCoins.length > 0 && total >= gasBudget) {
+    const topUpAmount = gasBudget - coinBalance; // > 0 and <= addressBalance
+    await applyMixedTopUp({
+      tx,
+      suiClient,
+      owner,
+      paymentCoins,
+      topUpAmount,
+    });
+    return { mode: 'mixedTopUp', gasBudget, coinBalance, addressBalance };
+  }
+
+  if (addressBalance >= gasBudget) {
+    tx.setGasPayment([]);
+    return { mode: 'addressBalance', gasBudget, coinBalance, addressBalance };
+  }
+
+  throw new InsufficientGasFundsError(gasBudget, coinBalance, addressBalance);
+}
+
+/**
+ * Estimate gas budget (no storageRebate) using a probe build/simulate.
+ * Prefers classic coin gas when coin objects exist so the estimate matches the
+ * cheaper payment path. Budget is left unset so Mysten can dry-run with MAX_GAS
+ * overrides (avoids locking the full balance away from GasCoin splits).
+ */
+export async function estimateGasBudget(input: {
+  tx: Transaction;
+  suiClient: SuiGrpcClient;
+  owner: string;
+  gasPrice: bigint;
+}): Promise<bigint> {
+  const { tx, suiClient, owner, gasPrice } = input;
+  const funding = await loadSuiGasFunding(suiClient, owner, tx);
+  if (funding.total <= 0n) {
+    throw new InsufficientGasFundsError(0n, funding.coinBalance, funding.addressBalance);
+  }
+
+  const probe = Transaction.from(tx);
+  probe.setSender(owner);
+  probe.setGasPrice(gasPrice);
+
+  // Prefer classic coins for the probe when available (cheaper than address-balance gas).
+  if (funding.paymentCoins.length > 0) {
+    probe.setGasPayment(toObjectRefs(funding.paymentCoins));
+  }
+
+  let built: Uint8Array;
+  try {
+    built = await probe.build({ client: suiClient });
+  } catch (e: unknown) {
+    const message = e instanceof Error ? e.message : String(e);
+    throw new Error(`Failed to estimate gas budget: ${message}`);
+  }
+
+  const inspect = await suiClient.simulateTransaction({
+    transaction: built,
+    include: { effects: true },
+  });
+  const effects = (inspect.Transaction ?? inspect.FailedTransaction)?.effects;
+  if (!effects?.gasUsed) {
+    throw new Error('Failed to estimate gas budget: simulateTransaction returned no gasUsed');
+  }
+  if (effects.status.success !== true) {
+    const err = effects.status.success === false ? effects.status.error?.message : undefined;
+    throw new Error(`Failed to estimate gas budget: ${err ?? 'simulation failed'}`);
+  }
+  return computeGasBudget(effects.gasUsed, gasPrice);
+}
+
+/**
+ * Resolve gasBudget (no rebate) and apply gas funding selection before build.
+ */
+export async function prepareGasFunding(input: {
+  tx: Transaction;
+  suiClient: SuiGrpcClient;
+  owner: string;
+  gasPrice: bigint;
+  gasBudget?: bigint;
+}): Promise<GasFundingResult> {
+  const { tx, suiClient, owner, gasPrice } = input;
+  const { payment, budget: existingBudget } = tx.getData().gasData;
+  const bakedAddressBalanceGas = payment != null && payment.length === 0;
+
+  // Never trust a budget baked into plain-tx / Mysten auto AB-gas txs.
+  // Those budgets are often under-estimated for payment: [] and would skip
+  // estimateGasBudget if we kept existingBudget.
+  let { gasBudget } = input;
+  if (gasBudget == null) {
+    if (bakedAddressBalanceGas || existingBudget == null) {
+      gasBudget = await estimateGasBudget({ tx, suiClient, owner, gasPrice });
+    } else {
+      gasBudget = BigInt(existingBudget);
+    }
+  }
+
+  tx.setGasBudget(gasBudget);
+  return selectGasFunding({ tx, suiClient, owner, gasBudget });
+}
+
+/**
+ * @deprecated Use {@link prepareGasFunding} / {@link selectGasFunding}.
+ * Kept as a thin classic-only helper for callers that only want coin gas when available.
+ */
+export async function preferClassicGasPayment(input: {
+  tx: Transaction;
+  suiClient: SuiGrpcClient;
+  owner: string;
+}): Promise<boolean> {
+  const { tx, suiClient, owner } = input;
+  const { payment } = tx.getData().gasData;
+  if (payment != null) {
+    return payment.length > 0;
+  }
+  const funding = await loadSuiGasFunding(suiClient, owner, tx);
+  if (funding.paymentCoins.length === 0) {
+    return false;
+  }
+  tx.setGasPayment(toObjectRefs(funding.paymentCoins));
+  return true;
+}

package/src/utils/index.ts

@@ -3,4 +3,6 @@ export * from './crypto';
 export * from './format';
 export * from './sui';
 export * from './coin';
+export * from './coinReservation';
+export * from './gasFunding';
 export * from './transaction';

package/src/utils/transaction.ts

@@ -1,12 +1,25 @@
 import { Transaction, isTransaction } from '@mysten/sui/transactions';
 
 /**
- * Normalize a transaction value to {@link Transaction} (handles plain Transaction or serialized legacy shapes).
+ * Normalize a transaction value to {@link Transaction}.
+ * Prefer V2 restore paths — avoid deprecated V1 serialize() when possible
+ * (V1 drops CallArg::FundsWithdrawal).
  */
 export function toSuiTransaction(txb: Transaction | unknown): Transaction {
   if (isTransaction(txb)) {
     return txb as Transaction;
   }
-  const legacy = txb as { serialize: () => string };
-  return Transaction.from(legacy.serialize()) as Transaction;
+
+  if (typeof txb === 'string' || txb instanceof Uint8Array) {
+    return Transaction.from(txb);
+  }
+
+  // Last resort for true legacy TransactionBlock (pre-Transaction API).
+  // Modern Transaction instances are handled by isTransaction above.
+  const legacy = txb as { serialize?: () => string };
+  if (typeof legacy?.serialize === 'function') {
+    return Transaction.from(legacy.serialize()) as Transaction;
+  }
+
+  throw new Error('Unsupported transaction value for toSuiTransaction');
 }