Add address balance support to CoinWithBalance and core API (#773)

* Add address balance support to CoinWithBalance and core API

* Add json rpc address balances

* change expiration default

* Add transction resolution for graphql

* add graphql address balances

Author: hayes-mysten

.changeset/default-transaction-expiration.md

@@ -0,0 +1,5 @@
+---
+'@mysten/sui': minor
+---
+
+Transactions now default the expiration to the current epoch + 1 using `ValidDuring`

packages/dapp-kit-next/packages/dapp-kit-core/src/utils/transaction-result.ts

@@ -11,6 +11,7 @@ import {
 export type TransactionResultWithEffects = SuiClientTypes.TransactionResult<{
 	effects: true;
 	transaction: true;
+	bcs: true;
 }>;
 
 export function buildTransactionResult(
@@ -30,7 +31,7 @@ export function buildTransactionResult(
 		);
 	}
 
-	const txResult: SuiClientTypes.Transaction<{ effects: true; transaction: true }> = {
+	const txResult: SuiClientTypes.Transaction<{ effects: true; transaction: true; bcs: true }> = {
 		digest,
 		signatures: [signature],
 		epoch: null,
@@ -40,6 +41,7 @@ export function buildTransactionResult(
 		balanceChanges: undefined,
 		events: undefined,
 		objectTypes: undefined,
+		bcs: transactionBytes,
 	};
 
 	return status.success

packages/docs/content/sui/clients/core.mdx

@@ -260,17 +260,30 @@ console.log('Digest:', result.Transaction.digest);
 Fetch a transaction by digest.
 
 ```typescript
-const tx = await client.core.getTransaction({
+const result = await client.core.getTransaction({
 	digest: 'ABC123...',
 	include: {
 		effects: true,
 		events: true,
-		input: true,
+		transaction: true,
 	},
 });
 
-console.log(tx.Transaction?.digest);
-console.log(tx.Transaction?.effects);
+console.log(result.Transaction?.digest);
+console.log(result.Transaction?.effects);
+console.log(result.Transaction?.transaction?.sender);
+```
+
+You can also fetch raw BCS-encoded transaction bytes:
+
+```typescript
+const result = await client.core.getTransaction({
+	digest: 'ABC123...',
+	include: { bcs: true },
+});
+
+// Raw BCS bytes for the transaction
+console.log(result.Transaction?.bcs); // Uint8Array
 ```
 
 ### waitForTransaction
@@ -391,11 +404,12 @@ Most methods accept an `include` parameter to control what data is returned:
 
 ```typescript
 {
-  effects: boolean,        // Transaction effects
+  effects: boolean,        // Transaction effects (BCS-encoded)
   events: boolean,         // Emitted events
-  input: boolean,          // Transaction input data
+  transaction: boolean,    // Parsed transaction data (sender, gas, inputs, commands)
   balanceChanges: boolean, // Balance changes
-  objectChanges: boolean,  // Object changes
+  objectTypes: boolean,    // Map of object IDs to their types for changed objects
+  bcs: boolean,            // Raw BCS-encoded transaction bytes
 }
 ```
 

packages/docs/content/sui/migrations/sui-2.0/sui.mdx

@@ -326,3 +326,16 @@ The `legacyAddress` parameter is now **required** for all zkLogin address comput
 - toZkLoginPublicIdentifier(addressSeed, iss)
 + toZkLoginPublicIdentifier(addressSeed, iss, { legacyAddress: false })
 ```
+
+## Default Transaction Expiration
+
+Transactions now default the expiration to the current epoch + 1 using `ValidDuring` when built with
+a client. This provides replay protection for all transactions without requiring explicit
+configuration.
+
+**To preserve the old behavior** (no expiration), explicitly set the expiration to `None`:
+
+```typescript
+const tx = new Transaction();
+tx.setExpiration({ None: true });
+```

packages/docs/content/sui/transaction-building/offline.mdx

@@ -3,19 +3,73 @@ title: Building Offline
 ---
 
 To build a transaction offline (with no `client` required), you need to fully define all of your
-input values and gas configuration (see the following example). For pure values, you can provide a
-`Uint8Array` which is used directly in the transaction. For objects, you can use the `Inputs` helper
-to construct an object reference.
+inputs, gas configuration, and expiration.
+
+## Required Configuration
+
+When building offline, you must set the following:
+
+- **Sender address** - The address that will execute the transaction
+- **Gas price** - The price per gas unit (can be obtained from the network beforehand)
+- **Gas budget** - The maximum gas to spend on this transaction
+- **Gas payment** - One or more coin object references to use for gas, or an empty array for Address
+  Balances
+- **Expiration** - Only needed when using address balances for gas
 
 ```tsx
-import { Inputs } from '@mysten/sui/transactions';
+import { Transaction } from '@mysten/sui/transactions';
 
-// for owned or immutable objects
-tx.object(Inputs.ObjectRef({ digest, objectId, version }));
+const { referenceGasPrice } = await client.getReferenceGasPrice();
 
-// for shared objects
-tx.object(Inputs.SharedObjectRef({ objectId, initialSharedVersion, mutable }));
+const tx = new Transaction();
+
+tx.setSender('0x<your-address>');
+tx.setGasPrice(referenceGasPrice);
+tx.setGasBudget(50_000_000);
+tx.setGasPayment([
+	{
+		objectId: '0x<gas-coin-object-id>',
+		version: '<object-version>',
+		digest: '<object-digest>',
+	},
+]);
+
+// Build the transaction without a client
+const bytes = await tx.build();
 ```
 
-You can then omit the `client` object when calling `build` on the transaction. Any required data
-that is missing throws an error.
+## Object References
+
+For objects used in your transaction, you must provide full object references using the `Inputs`
+helper:
+
+```tsx
+import { Inputs } from '@mysten/sui/transactions';
+
+// For owned or immutable objects
+tx.object(
+	Inputs.ObjectRef({
+		objectId: '0x<object-id>',
+		version: '<object-version>',
+		digest: '<object-digest>',
+	}),
+);
+
+// For shared objects
+tx.object(
+	Inputs.SharedObjectRef({
+		objectId: '0x<object-id>',
+		initialSharedVersion: '<initial-shared-version>',
+		mutable: true,
+	}),
+);
+
+// For receiving objects (objects being received by another object)
+tx.object(
+	Inputs.ReceivingRef({
+		objectId: '0x<object-id>',
+		version: '<object-version>',
+		digest: '<object-digest>',
+	}),
+);
+```

packages/kiosk/test/e2e/globalSetup.ts

@@ -17,8 +17,8 @@ declare module 'vitest' {
 const SUI_TOOLS_TAG =
 	process.env.SUI_TOOLS_TAG ||
 	(process.arch === 'arm64'
-		? '62eeb2716b43d1248efcf19c208086840f5a0695-arm64'
-		: '62eeb2716b43d1248efcf19c208086840f5a0695');
+		? 'cc8e624a969eed2066ff5f25c64c42a34143b0a6-arm64'
+		: 'cc8e624a969eed2066ff5f25c64c42a34143b0a6');
 
 export default async function setup(project: TestProject) {
 	console.log('Starting test containers');

packages/sui/src/client/core-resolver.ts

@@ -112,11 +112,53 @@ 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 coins = await client.core.listCoins({
-			owner: transactionData.gasData.owner || transactionData.sender!,
-			coinType: SUI_TYPE_ARG,
+		const gasPayer = transactionData.gasData.owner ?? transactionData.sender!;
+		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 === gasPayer) {
+						if (input.FundsWithdrawal.reservation.$kind === 'MaxAmountU64') {
+							withdrawals += BigInt(input.FundsWithdrawal.reservation.MaxAmountU64);
+						}
+					}
+				}
+			}
+
+			return arg;
 		});
 
+		const [suiBalance, coins] = await Promise.all([
+			usesGasCoin || !transactionData.gasData.owner
+				? null
+				: client.core.getBalance({
+						owner: transactionData.gasData.owner,
+					}),
+			client.core.listCoins({
+				owner: transactionData.gasData.owner || transactionData.sender!,
+				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) => {
@@ -130,19 +172,19 @@ async function setGasPayment(transactionData: TransactionDataBuilder, client: Cl
 
 				return !matchingInput;
 			})
-			.map((coin) => ({
-				objectId: coin.objectId,
-				digest: coin.digest,
-				version: coin.version,
-			}));
+			.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.');
 		}
 
-		transactionData.gasData.payment = paymentCoins.map((payment) =>
-			parse(ObjectRefSchema, payment),
-		);
+		transactionData.gasData.payment = paymentCoins;
 	}
 }
 
@@ -151,17 +193,6 @@ async function setExpiration(
 	client: ClientWithCoreApi,
 	existingSystemState: SystemStateData | null,
 ) {
-	const hasOwnedInputs = transactionData.inputs.some((input) => {
-		return input.Object?.ImmOrOwnedObject || input.Object?.Receiving;
-	});
-
-	const hasGasPayment =
-		transactionData.gasData.payment && transactionData.gasData.payment.length > 0;
-
-	if (hasOwnedInputs || hasGasPayment) {
-		return;
-	}
-
 	const [systemState, { chainIdentifier }] = await Promise.all([
 		existingSystemState ?? client.core.getCurrentSystemState().then((r) => r.systemState),
 		client.core.getChainIdentifier(),