@mysten/sui 2.12.1 → 2.13.0

package/dist/zklogin/jwt-utils.d.mts

@@ -1,7 +1,6 @@
 import { JwtPayload } from "./jwt-decode.mjs";
 
 //#region src/zklogin/jwt-utils.d.ts
-
 declare function decodeJwt(jwt: string): Omit<JwtPayload, 'iss' | 'aud' | 'sub'> & {
   iss: string;
   aud: string;

package/dist/zklogin/jwt-utils.d.mts.map

@@ -1 +1 @@
-{"version":3,"file":"jwt-utils.d.mts","names":[],"sources":["../../src/zklogin/jwt-utils.ts"],"sourcesContent":[],"mappings":";;;;iBAsHgB,SAAA,eAAwB,KAAK"}
+{"version":3,"file":"jwt-utils.d.mts","names":[],"sources":["../../src/zklogin/jwt-utils.ts"],"mappings":";;;iBAsHgB,SAAA,CAAU,GAAA,WAAc,IAAA,CAAK,UAAA;EAC5C,GAAA;EACA,GAAA;EACA,GAAA;EACA,MAAA;AAAA"}

package/dist/zklogin/nonce.d.mts.map

@@ -1 +1 @@
-{"version":3,"file":"nonce.d.mts","names":[],"sources":["../../src/zklogin/nonce.ts"],"sourcesContent":[],"mappings":";;;iBAqBgB,kBAAA,CAAA;AAAA,iBAKA,aAAA,CALkB,SAAA,EAKO,SALP,EAAA,QAAA,EAAA,MAAA,EAAA,UAAA,EAAA,MAAA,GAAA,MAAA,CAAA,EAAA,MAAA"}
+{"version":3,"file":"nonce.d.mts","names":[],"sources":["../../src/zklogin/nonce.ts"],"mappings":";;;iBAqBgB,kBAAA,CAAA;AAAA,iBAKA,aAAA,CAAc,SAAA,EAAW,SAAA,EAAW,QAAA,UAAkB,UAAA"}

package/dist/zklogin/poseidon.d.mts.map

@@ -1 +1 @@
-{"version":3,"file":"poseidon.d.mts","names":[],"sources":["../../src/zklogin/poseidon.ts"],"sourcesContent":[],"mappings":";AA4CgB,iBAAA,YAAA,CAAY,MAAA,EAAA,CAAA,MAAA,GAAA,MAAA,GAAA,MAAA,CAAA,EAAA,CAAA,EAAA,MAAA"}
+{"version":3,"file":"poseidon.d.mts","names":[],"sources":["../../src/zklogin/poseidon.ts"],"mappings":";iBA4CgB,YAAA,CAAa,MAAA"}

package/dist/zklogin/publickey.d.mts

@@ -3,7 +3,6 @@ import { ClientWithCoreApi } from "../client/core.mjs";
 import { ZkLoginSignatureInputs } from "./bcs.mjs";
 
 //#region src/zklogin/publickey.d.ts
-
 /**
  * A zkLogin public identifier
  */

package/dist/zklogin/publickey.d.mts.map

@@ -1 +1 @@
-{"version":3,"file":"publickey.d.mts","names":[],"sources":["../../src/zklogin/publickey.ts"],"sourcesContent":[],"mappings":";;;;;;;AAoBA;;AASyC,cAT5B,uBAAA,SAAgC,SAAA,CASJ;EAAqB,CAAA,OAAA;EAoBrD;;;;EAKO,WAAA,CAAA,KAAA,EAzBI,iBAyBJ,EAAA;IAAA;EAmC0B,CAAA,CAnC1B,EAAA;IAAmE,MAAA,CAAA,EAzBrB,iBAyBqB;EAmCzC,CAAA;EAAsB,OAAA,SAAA,CAAA,KAAA,EAxCvD,UAwCuD,EAAA;IAAA,MAAA;IAAA,OAAA;IAAA;EAiExC,CAAA,CAjEwC,EAAA;IA0BpC,MAAA,CAAA,EA7DZ,iBA6DY;IAyBF,OAAA,CAAA,EAAA,MAAA;IAAX,aAAA,CAAA,EAAA,OAAA;EAcS,CAAA,CAAA,EApG2D,uBAoG3D;EAAwB,OAAA,SAAA,CAAA,OAAA,EAAA,MAAA,EAAA,KAAA,EAjEN,sBAiEM,CAAA,EAjEgB,uBAiEhB;EAAsB;;;EAOO,MAAA,CAAA,SAAA,EA9CjD,uBA8CiD,CAAA,EAAA,OAAA;EAgB7C,YAAA,CAAA,CAAA,EAAA,MAAA;EAAuB;;;EA7JD,UAAA,CAAA,CAAA,EAwHvC,UAxHuC,CAwH5B,WAxH4B,CAAA;EAkLtC;;;;;;;mBA5CQ,wBAAwB,sBAAsB;;;;iCAOtC,uBAAuB,sBAAsB;;;;iCAgB7C,uBAAuB,sBAAsB;;;;;;iBAqB7D,yBAAA;WAGK;;IAClB"}
+{"version":3,"file":"publickey.d.mts","names":[],"sources":["../../src/zklogin/publickey.ts"],"mappings":";;;;;;AAoBA;;cAAa,uBAAA,SAAgC,SAAA;EAAA;EASJ;;;;cAA5B,KAAA,EAAO,iBAAA;IAAqB;EAAA;IAAY,MAAA,GAAS,iBAAA;EAAA;EAAA,OAmBtD,SAAA,CACN,KAAA,EAAO,UAAA;IAEN,MAAA;IACA,OAAA;IACA;EAAA;IACI,MAAA,GAAS,iBAAA;IAAmB,OAAA;IAAkB,aAAA;EAAA,IAA8B,uBAAA;EAAA,OAmC3E,SAAA,CAAU,OAAA,UAAiB,KAAA,EAAO,sBAAA,GAAsB,uBAAA;EAiExC;;;EAvCd,MAAA,CAAO,SAAA,EAAW,uBAAA;EAIlB,YAAA,CAAA;EA0CmE;;;EArB5E,UAAA,CAAA,GAAc,UAAA,CAAW,WAAA;EAxHmB;;;EA+H5C,IAAA,CAAA;;;;EAOM,MAAA,CAAO,QAAA,EAAU,UAAA,EAAY,UAAA,EAAY,UAAA,YAAsB,OAAA;EA7H7B;;;EAoIxC,qBAAA,CAAsB,OAAA,EAAS,UAAA,EAAY,SAAA,EAAW,UAAA,YAAsB,OAAA;EAjHrE;;;EAiIP,iBAAA,CAAkB,WAAA,EAAa,UAAA,EAAY,SAAA,EAAW,UAAA,YAAsB,OAAA;EA9H1E;;;EA6IO,aAAA,CAAc,OAAA;AAAA;AAAA,iBAMR,yBAAA,CACf,WAAA,UACA,GAAA,UACA,OAAA;EAAW,MAAA,GAAS,iBAAA;EAAmB,aAAA;AAAA,IACrC,uBAAA"}

package/dist/zklogin/signature.d.mts.map

@@ -1 +1 @@
-{"version":3,"file":"signature.d.mts","names":[],"sources":["../../src/zklogin/signature.ts"],"sourcesContent":[],"mappings":";;;UASU,wBAAA,SAAiC,KAAK;0BACvB;AAJwB;AAGD,iBAkBhC,mBAAA,CAlBgC;EAAA,MAAA;EAAA,QAAA;EAAA;AAAA,CAAA,EAkByB,wBAlBzB,CAAA,EAAA,MAAA;AACvB,iBAyBT,qBAAA,CAzBS,SAAA,EAAA,MAAA,GAyBiC,UAzBjC,CAAA,EAAA;EADkB,MAAA,EAAA;IAAI,WAAA,EAAA;MAkB/B,CAAA,EAAA,MAAA,EAAA;MAAsB,CAAA,EAAA,MAAA,EAAA,EAAA;MAAQ,CAAA,EAAA,MAAA,EAAA;IAAU,CAAA;IAAiB,gBAAA,EAAA;MAAwB,KAAA,EAAA,MAAA;MAQjF,SAAA,EAAA,MAAqB;IAAqB,CAAA"}
+{"version":3,"file":"signature.d.mts","names":[],"sources":["../../src/zklogin/signature.ts"],"mappings":";;;UASU,wBAAA,SAAiC,IAAA,CAAK,gBAAA;EAC/C,aAAA,WAAwB,gBAAA;AAAA;AAAA,iBAiBT,mBAAA,CAAA;EAAsB,MAAA;EAAQ,QAAA;EAAU;AAAA,GAAiB,wBAAA;AAAA,iBAQzD,qBAAA,CAAsB,SAAA,WAAoB,UAAA"}

package/dist/zklogin/utils.d.mts.map

@@ -1 +1 @@
-{"version":3,"file":"utils.d.mts","names":[],"sources":["../../src/zklogin/utils.ts"],"sourcesContent":[],"mappings":";;;iBAwBgB,sBAAA,8BAAoD;iBAMpD,gBAAA,8BAA8C;AAN9C,iBAkBA,6BAAA,CAlB8D,SAAA,EAkBrB,SAlBqB,CAAA,EAAA,MAAA;iBAgD9D,mBAAA;iBAiBA,cAAA"}
+{"version":3,"file":"utils.d.mts","names":[],"sources":["../../src/zklogin/utils.ts"],"mappings":";;;iBAwBgB,sBAAA,CAAuB,GAAA,UAAa,KAAA,WAAgB,UAAA;AAAA,iBAMpD,gBAAA,CAAiB,GAAA,UAAa,KAAA,WAAgB,UAAA;AAAA,iBAY9C,6BAAA,CAA8B,SAAA,EAAW,SAAA;AAAA,iBA8BzC,mBAAA,CAAoB,GAAA,UAAa,OAAA;AAAA,iBAiBjC,cAAA,CACf,IAAA,mBACA,IAAA,UACA,KAAA,UACA,GAAA,UACA,eAAA,WACA,gBAAA,WACA,cAAA"}

package/package.json

@@ -3,7 +3,7 @@
   "author": "Mysten Labs <build@mystenlabs.com>",
   "description": "Sui TypeScript API",
   "homepage": "https://sdk.mystenlabs.com",
-  "version": "2.12.1",
+  "version": "2.13.0",
   "license": "Apache-2.0",
   "sideEffects": false,
   "files": [

package/src/client/core-resolver.ts

@@ -1,11 +1,14 @@
 // Copyright (c) Mysten Labs, Inc.
 // SPDX-License-Identifier: Apache-2.0
 
-import { parse } from 'valibot';
-
-import { normalizeSuiAddress, normalizeSuiObjectId, SUI_TYPE_ARG } from '../utils/index.js';
+import {
+	normalizeSuiAddress,
+	normalizeSuiObjectId,
+	normalizeStructTag,
+	SUI_TYPE_ARG,
+} from '../utils/index.js';
+import { createCoinReservationRef } from '../utils/coin-reservation.js';
 import type { ClientWithCoreApi } from './core.js';
-import { ObjectRefSchema } from '../transactions/data/internal.js';
 import type { CallArg, Command } from '../transactions/data/internal.js';
 import type { SuiClientTypes } from './types.js';
 import { SimulationError } from './errors.js';
@@ -38,36 +41,89 @@ export async function coreClientResolveTransactionPlugin(
 ) {
 	const client = getClient(options);
 
-	await normalizeInputs(transactionData, client);
-	await resolveObjectReferences(transactionData, client);
+	const needsGasPrice = !options.onlyTransactionKind && !transactionData.gasData.price;
+	const needsPayment = !options.onlyTransactionKind && !transactionData.gasData.payment;
+	const gasPayer = transactionData.gasData.owner ?? transactionData.sender;
 
-	if (!options.onlyTransactionKind) {
-		await setGasData(transactionData, client);
+	let usesGasCoin = false;
+	let withdrawals = 0n;
+
+	transactionData.mapArguments((arg) => {
+		if (arg.$kind === 'GasCoin') usesGasCoin = true;
+		return arg;
+	});
+
+	const normalizedGasPayer = gasPayer ? normalizeSuiAddress(gasPayer) : null;
+	for (const input of transactionData.inputs) {
+		if (input.$kind !== 'FundsWithdrawal' || !normalizedGasPayer) continue;
+		if (normalizeStructTag(input.FundsWithdrawal.typeArg.Balance) !== SUI_TYPE_ARG) continue;
+
+		const withdrawalOwner = input.FundsWithdrawal.withdrawFrom.Sender
+			? transactionData.sender
+			: gasPayer;
+		if (
+			withdrawalOwner &&
+			normalizeSuiAddress(withdrawalOwner) === normalizedGasPayer &&
+			input.FundsWithdrawal.reservation.$kind === 'MaxAmountU64'
+		) {
+			withdrawals += BigInt(input.FundsWithdrawal.reservation.MaxAmountU64);
+		}
 	}
 
-	return await next();
-}
+	const needsSystemState = needsGasPrice || (needsPayment && usesGasCoin);
+	const [, systemStateResult, balanceResult, coinsResult, protocolConfigResult, chainIdResult] =
+		await Promise.all([
+			normalizeInputs(transactionData, client),
+			needsSystemState ? client.core.getCurrentSystemState() : null,
+			needsPayment && gasPayer ? client.core.getBalance({ owner: gasPayer }) : null,
+			needsPayment && gasPayer
+				? client.core.listCoins({ owner: gasPayer, coinType: SUI_TYPE_ARG })
+				: null,
+			needsPayment && usesGasCoin ? client.core.getProtocolConfig() : null,
+			needsPayment && usesGasCoin ? client.core.getChainIdentifier() : null,
+		]);
 
-interface SystemStateData {
-	epoch: string;
-	referenceGasPrice: string;
-}
+	await resolveObjectReferences(transactionData, client);
 
-async function setGasData(transactionData: TransactionDataBuilder, client: ClientWithCoreApi) {
-	let systemState: SystemStateData | null = null;
+	if (!options.onlyTransactionKind) {
+		const systemState = systemStateResult?.systemState ?? null;
 
-	if (!transactionData.gasData.price) {
-		const response = await client.core.getCurrentSystemState();
-		systemState = response.systemState;
-		transactionData.gasData.price = systemState.referenceGasPrice;
-	}
+		if (systemState && !transactionData.gasData.price) {
+			transactionData.gasData.price = systemState.referenceGasPrice;
+		}
 
-	await setGasBudget(transactionData, client);
-	await setGasPayment(transactionData, client);
+		await setGasBudget(transactionData, client);
+
+		if (needsPayment) {
+			if (!balanceResult || !coinsResult) {
+				throw new Error(
+					'Could not resolve gas payment: a gas owner or sender must be set to fetch balance and coins.',
+				);
+			}
+			setGasPayment({
+				transactionData,
+				balance: balanceResult,
+				coins: coinsResult,
+				usesGasCoin,
+				withdrawals,
+				protocolConfig: protocolConfigResult?.protocolConfig,
+				gasPayer: gasPayer!,
+				chainIdentifier: chainIdResult?.chainIdentifier ?? null,
+				epoch: systemState?.epoch ?? null,
+			});
+		}
 
-	if (!transactionData.expiration) {
-		await setExpiration(transactionData, client, systemState);
+		if (!transactionData.expiration && transactionData.gasData.payment?.length === 0) {
+			await setExpiration(
+				transactionData,
+				client,
+				systemState,
+				chainIdResult?.chainIdentifier ?? null,
+			);
+		}
 	}
+
+	return await next();
 }
 
 async function setGasBudget(transactionData: TransactionDataBuilder, client: ClientWithCoreApi) {
@@ -109,100 +165,89 @@ async function setGasBudget(transactionData: TransactionDataBuilder, client: Cli
 	);
 }
 
-// The current default is just picking _all_ coins we can which may not be ideal.
-async function setGasPayment(transactionData: TransactionDataBuilder, client: ClientWithCoreApi) {
-	if (!transactionData.gasData.payment) {
-		const gasPayer = transactionData.gasData.owner ?? transactionData.sender;
-		if (!gasPayer) {
-			throw new Error('Either a gas owner or sender must be set to determine gas payment.');
-		}
+function setGasPayment({
+	transactionData,
+	balance,
+	coins,
+	usesGasCoin,
+	withdrawals,
+	protocolConfig,
+	gasPayer,
+	chainIdentifier,
+	epoch,
+}: {
+	transactionData: TransactionDataBuilder;
+	balance: SuiClientTypes.GetBalanceResponse;
+	coins: SuiClientTypes.ListCoinsResponse;
+	usesGasCoin: boolean;
+	withdrawals: bigint;
+	protocolConfig: SuiClientTypes.ProtocolConfig | undefined;
+	gasPayer: string;
+	chainIdentifier: string | null;
+	epoch: string | null;
+}) {
+	const budget = BigInt(transactionData.gasData.budget!);
+	const addressBalance = BigInt(balance.balance.addressBalance);
+
+	if (budget === 0n || (!usesGasCoin && addressBalance >= budget + withdrawals)) {
+		transactionData.gasData.payment = [];
+		return;
+	}
 
-		const normalizedGasPayer = normalizeSuiAddress(gasPayer);
-		let usesGasCoin = false;
-		let withdrawals = 0n;
-
-		transactionData.mapArguments((arg) => {
-			if (arg.$kind === 'GasCoin') {
-				usesGasCoin = true;
-			} else if (arg.$kind === 'Input') {
-				const input = transactionData.inputs[arg.Input];
-
-				if (input.$kind === 'FundsWithdrawal') {
-					const withdrawalOwner = input.FundsWithdrawal.withdrawFrom.Sender
-						? transactionData.sender
-						: gasPayer;
-
-					if (withdrawalOwner && normalizeSuiAddress(withdrawalOwner) === normalizedGasPayer) {
-						if (input.FundsWithdrawal.reservation.$kind === 'MaxAmountU64') {
-							withdrawals += BigInt(input.FundsWithdrawal.reservation.MaxAmountU64);
-						}
-					}
-				}
+	const filteredCoins = coins.objects.filter((coin) => {
+		const matchingInput = transactionData.inputs.find((input) => {
+			if (input.Object?.ImmOrOwnedObject) {
+				return coin.objectId === input.Object.ImmOrOwnedObject.objectId;
 			}
 
-			return arg;
+			return false;
 		});
 
-		const [suiBalance, coins] = await Promise.all([
-			usesGasCoin ? null : client.core.getBalance({ owner: gasPayer }),
-			client.core.listCoins({
-				owner: gasPayer,
-				coinType: SUI_TYPE_ARG,
-			}),
-		]);
-
-		if (
-			suiBalance?.balance.addressBalance &&
-			BigInt(suiBalance.balance.addressBalance) >=
-				BigInt(transactionData.gasData.budget || '0') + withdrawals
-		) {
-			transactionData.gasData.payment = [];
-			return;
-		}
-
-		const paymentCoins = coins.objects
-			// Filter out coins that are also used as input:
-			.filter((coin) => {
-				const matchingInput = transactionData.inputs.find((input) => {
-					if (input.Object?.ImmOrOwnedObject) {
-						return coin.objectId === input.Object.ImmOrOwnedObject.objectId;
-					}
-
-					return false;
-				});
-
-				return !matchingInput;
-			})
-			.map((coin) =>
-				parse(ObjectRefSchema, {
-					objectId: coin.objectId,
-					digest: coin.digest,
-					version: coin.version,
-				}),
-			);
-
-		if (!paymentCoins.length) {
-			throw new Error('No valid gas coins found for the transaction.');
-		}
+		return !matchingInput;
+	});
 
+	const paymentCoins = filteredCoins.map((coin) => ({
+		objectId: coin.objectId,
+		digest: coin.digest,
+		version: coin.version,
+	}));
+
+	const reservationAmount = addressBalance - withdrawals;
+
+	if (
+		usesGasCoin &&
+		reservationAmount > 0n &&
+		protocolConfig?.featureFlags?.['enable_coin_reservation_obj_refs'] &&
+		chainIdentifier &&
+		epoch
+	) {
+		transactionData.gasData.payment = [
+			createCoinReservationRef(reservationAmount, gasPayer, chainIdentifier, epoch),
+			...paymentCoins,
+		];
+	} else if (!filteredCoins.length) {
+		throw new Error('No valid gas coins found for the transaction.');
+	} else {
 		transactionData.gasData.payment = paymentCoins;
 	}
 }
 
+interface SystemStateData {
+	epoch: string;
+	referenceGasPrice: string;
+}
+
 async function setExpiration(
 	transactionData: TransactionDataBuilder,
 	client: ClientWithCoreApi,
-	existingSystemState: SystemStateData | null,
+	systemState: SystemStateData | null,
+	existingChainIdentifier: string | null = null,
 ) {
-	if (transactionData.expiration || hasVersionedInputs(transactionData)) {
-		return;
-	}
-
-	const [systemState, { chainIdentifier }] = await Promise.all([
-		existingSystemState ?? client.core.getCurrentSystemState().then((r) => r.systemState),
-		client.core.getChainIdentifier(),
+	const [chainIdentifier, resolvedSystemState] = await Promise.all([
+		existingChainIdentifier ?? client.core.getChainIdentifier().then((r) => r.chainIdentifier),
+		systemState ?? client.core.getCurrentSystemState().then((r) => r.systemState),
 	]);
-	const currentEpoch = BigInt(systemState.epoch);
+	const currentEpoch = BigInt(resolvedSystemState.epoch);
 
 	transactionData.expiration = {
 		$kind: 'ValidDuring',
@@ -217,17 +262,6 @@ async function setExpiration(
 	};
 }
 
-function hasVersionedInputs(transactionData: TransactionDataBuilder): boolean {
-	if (transactionData.gasData.payment?.length) {
-		return true;
-	}
-
-	return transactionData.inputs.some(
-		(input) =>
-			input.Object?.ImmOrOwnedObject || (input.UnresolvedObject && input.UnresolvedObject.version),
-	);
-}
-
 async function resolveObjectReferences(
 	transactionData: TransactionDataBuilder,
 	client: ClientWithCoreApi,

package/src/jsonRpc/client.ts

@@ -5,6 +5,7 @@ import { fromBase58, toBase64, toHex } from '@mysten/bcs';
 import type { Signer } from '../cryptography/index.js';
 import { BaseClient } from '../client/client.js';
 import type { SuiClientTypes } from '../client/types.js';
+import { isCoinReservationDigest } from '../utils/coin-reservation.js';
 import type { Transaction } from '../transactions/Transaction.js';
 import { isTransaction } from '../transactions/Transaction.js';
 import {
@@ -128,25 +129,6 @@ type NetworkOrTransport =
 
 const SUI_CLIENT_BRAND = Symbol.for('@mysten/SuiJsonRpcClient') as never;
 
-// Magic number used to identify fake address balance coins (last 20 bytes of the digest)
-// See: sui/crates/sui-types/src/coin_reservation.rs
-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,
-]);
-
-/**
- * Checks if a digest indicates a fake address balance coin.
- * These "coins" are created by the JSON RPC to represent address balances
- * and should be filtered out from coin listings.
- */
-function isCoinReservationDigest(digestBase58: string): boolean {
-	const digestBytes = fromBase58(digestBase58);
-	// Check if the last 20 bytes match the magic number
-	const last20Bytes = digestBytes.slice(12, 32);
-	return last20Bytes.every((byte, i) => byte === COIN_RESERVATION_MAGIC[i]);
-}
-
 export function isSuiJsonRpcClient(client: unknown): client is SuiJsonRpcClient {
 	return (
 		typeof client === 'object' && client !== null && (client as any)[SUI_CLIENT_BRAND] === true

package/src/transactions/Transaction.ts

@@ -31,7 +31,12 @@ import { createPure } from './pure.js';
 import { TransactionDataBuilder } from './TransactionData.js';
 import { getIdFromCallArg } from './utils.js';
 import { namedPackagesPlugin } from './plugins/NamedPackagesPlugin.js';
-import { COIN_WITH_BALANCE, resolveCoinBalance } from './intents/CoinWithBalance.js';
+import {
+	COIN_WITH_BALANCE,
+	resolveCoinBalance,
+	coinWithBalance,
+	createBalance,
+} from './intents/CoinWithBalance.js';
 import type { ClientWithCoreApi } from '../client/core.js';
 
 export type TransactionObjectArgument =
@@ -307,6 +312,38 @@ export class Transaction {
 		return { $kind: 'GasCoin' as const, GasCoin: true as const };
 	}
 
+	/**
+	 * Creates a coin of the specified type and balance.
+	 * Sourced from address balance when available, falling back to owned coins.
+	 */
+	coin({
+		type,
+		balance,
+		useGasCoin,
+	}: {
+		balance: bigint | number;
+		type?: string;
+		useGasCoin?: boolean;
+	}): TransactionResult {
+		return this.add(coinWithBalance({ type, balance, useGasCoin }));
+	}
+
+	/**
+	 * Creates a Balance object of the specified type and balance.
+	 * Sourced from address balance when available, falling back to owned coins.
+	 */
+	balance({
+		type,
+		balance,
+		useGasCoin,
+	}: {
+		balance: bigint | number;
+		type?: string;
+		useGasCoin?: boolean;
+	}): TransactionResult {
+		return this.add(createBalance({ type, balance, useGasCoin }));
+	}
+
 	/**
 	 * Add a new object input to the transaction.
 	 */