@mysten/sui 2.16.1 → 2.16.3

package/docs/zklogin.md

@@ -0,0 +1,83 @@
+# ZkLogin
+
+> Zero-knowledge authentication with OAuth providers on Sui.
+
+Utilities for working with zkLogin. Currently contains functionality to create and parse zkLogin
+signatures and compute zkLogin addresses.
+
+To parse a serialized zkLogin signature
+
+```typescript
+
+const parsedSignature = await parseZkLoginSignature('BQNNMTY4NjAxMzAyO....');
+```
+
+Use `getZkLoginSignature` to serialize a zkLogin signature.
+
+```typescript
+
+const serializedSignature = await getZkLoginSignature({ inputs, maxEpoch, userSignature });
+```
+
+To compute the address for a given address seed and iss you can use `computeZkLoginAddressFromSeed`
+
+```typescript
+
+const address = computeZkLoginAddressFromSeed(0n, 'https://accounts.google.com');
+```
+
+To compute an address from jwt:
+
+```typescript
+
+const address = jwtToAddress(jwtAsString, salt);
+```
+
+To compute an address from a parsed jwt:
+
+```typescript
+
+const address = computeZkLoginAddress({
+	claimName,
+	claimValue,
+	iss,
+	aud,
+	userSalt: BigInt(salt),
+});
+```
+
+To use zkLogin inside a multisig, see the [Multisig Guide](../sui/cryptography/multisig) for more
+details.
+
+## Legacy addresses
+
+When zklogin was first introduced, there was an inconsistency in how the address seed was computed.
+For backwards compatibility reasons there are 2 valid addresses for a given set of inputs. Methods
+that produce zklogin addresses all accept a `legacyAddress` boolean flag, either as their last
+parameter, or in their options argument.
+
+```typescript
+
+	computeZkLoginAddress,
+	computeZkLoginAddressFromSeed,
+	jwtToAddress,
+	toZkLoginPublicIdentifier,
+	genAddressSeed,
+} from '@mysten/sui/zklogin';
+
+const address = jwtToAddress(jwtAsString, salt, true);
+const address = computeZkLoginAddressFromSeed(0n, 'https://accounts.google.com', true);
+const address = computeZkLoginAddress({
+	claimName,
+	claimValue,
+	iss,
+	aud,
+	userSalt: BigInt(salt),
+	legacyAddress: true,
+});
+const address = toZkLoginPublicIdentifier(
+	genAddressSeed(userSalt, claimName, claimValue, aud),
+	iss,
+	{ legacyAddress: true },
+).toSuiAddress();
+```

package/package.json

@@ -3,7 +3,7 @@
   "author": "Mysten Labs <build@mystenlabs.com>",
   "description": "Sui TypeScript API",
   "homepage": "https://sdk.mystenlabs.com",
-  "version": "2.16.1",
+  "version": "2.16.3",
   "license": "Apache-2.0",
   "sideEffects": false,
   "files": [
@@ -168,8 +168,8 @@
     "graphql": "^16.12.0",
     "poseidon-lite": "0.2.1",
     "valibot": "^1.2.0",
-    "@mysten/bcs": "^2.0.4",
-    "@mysten/utils": "^0.3.2"
+    "@mysten/bcs": "^2.0.5",
+    "@mysten/utils": "^0.3.3"
   },
   "scripts": {
     "clean": "rm -rf tsconfig.tsbuildinfo ./dist",

package/src/client/core-resolver.ts

@@ -84,7 +84,18 @@ export async function coreClientResolveTransactionPlugin(
 		}
 	}
 
-	const needsSystemState = needsGasPrice || (needsPayment && usesGasCoin);
+	// `setGasBudget` simulates with `payment: []` whenever it has to compute a
+	// budget (i.e. one wasn't preset). The validator's replay-protection check
+	// then requires either a `ValidDuring` expiration or at least one
+	// "address-owned" input — an `ImmOrOwnedMoveObject` whose owner is
+	// `AddressOwner`, which we can't tell from `Immutable` without owner info we
+	// don't track. Provide a simulate-only `ValidDuring` whenever we'll actually
+	// simulate and one isn't user-set.
+	const needsSimulateExpiration =
+		!options.onlyTransactionKind && !transactionData.expiration && !transactionData.gasData.budget;
+	const needsSystemState =
+		needsGasPrice || (needsPayment && usesGasCoin) || needsSimulateExpiration;
+	const needsChainId = (needsPayment && usesGasCoin) || needsSimulateExpiration;
 	const [, systemStateResult, balanceResult, coinsResult, chainIdResult] = await Promise.all([
 		normalizeInputs(transactionData, client),
 		needsSystemState ? client.core.getCurrentSystemState() : null,
@@ -92,19 +103,25 @@ export async function coreClientResolveTransactionPlugin(
 		needsPayment && gasPayer
 			? client.core.listCoins({ owner: gasPayer, coinType: SUI_TYPE_ARG })
 			: null,
-		needsPayment && usesGasCoin ? client.core.getChainIdentifier() : null,
+		needsChainId ? client.core.getChainIdentifier() : null,
 	]);
 
 	await resolveObjectReferences(transactionData, client);
 
 	if (!options.onlyTransactionKind) {
 		const systemState = systemStateResult?.systemState ?? null;
+		const chainIdentifier = chainIdResult?.chainIdentifier ?? null;
 
 		if (systemState && !transactionData.gasData.price) {
 			transactionData.gasData.price = systemState.referenceGasPrice;
 		}
 
-		await setGasBudget(transactionData, client);
+		const simulateExpiration =
+			needsSimulateExpiration && systemState && chainIdentifier
+				? buildValidDuringExpiration(systemState, chainIdentifier)
+				: undefined;
+
+		await setGasBudget(transactionData, client, simulateExpiration);
 
 		if (needsPayment) {
 			if (!balanceResult || !coinsResult) {
@@ -119,25 +136,24 @@ export async function coreClientResolveTransactionPlugin(
 				usesGasCoin,
 				withdrawals,
 				gasPayer: gasPayer!,
-				chainIdentifier: chainIdResult?.chainIdentifier ?? null,
+				chainIdentifier,
 				epoch: systemState?.epoch ?? null,
 			});
 		}
 
 		if (!transactionData.expiration && transactionData.gasData.payment?.length === 0) {
-			await setExpiration(
-				transactionData,
-				client,
-				systemState,
-				chainIdResult?.chainIdentifier ?? null,
-			);
+			await setExpiration(transactionData, client, systemState, chainIdentifier);
 		}
 	}
 
 	return await next();
 }
 
-async function setGasBudget(transactionData: TransactionDataBuilder, client: ClientWithCoreApi) {
+async function setGasBudget(
+	transactionData: TransactionDataBuilder,
+	client: ClientWithCoreApi,
+	simulateExpiration?: ValidDuringExpiration,
+) {
 	if (transactionData.gasData.budget) {
 		return;
 	}
@@ -149,6 +165,7 @@ async function setGasBudget(transactionData: TransactionDataBuilder, client: Cli
 					budget: String(MAX_GAS),
 					payment: [],
 				},
+				...(simulateExpiration && { expiration: simulateExpiration }),
 			},
 		}),
 		include: { effects: true },
@@ -243,9 +260,27 @@ async function setExpiration(
 		existingChainIdentifier ?? client.core.getChainIdentifier().then((r) => r.chainIdentifier),
 		systemState ?? client.core.getCurrentSystemState().then((r) => r.systemState),
 	]);
-	const currentEpoch = BigInt(resolvedSystemState.epoch);
+	transactionData.expiration = buildValidDuringExpiration(resolvedSystemState, chainIdentifier);
+}
 
-	transactionData.expiration = {
+type ValidDuringExpiration = {
+	$kind: 'ValidDuring';
+	ValidDuring: {
+		minEpoch: string;
+		maxEpoch: string;
+		minTimestamp: null;
+		maxTimestamp: null;
+		chain: string;
+		nonce: number;
+	};
+};
+
+function buildValidDuringExpiration(
+	systemState: SystemStateData,
+	chainIdentifier: string,
+): ValidDuringExpiration {
+	const currentEpoch = BigInt(systemState.epoch);
+	return {
 		$kind: 'ValidDuring',
 		ValidDuring: {
 			minEpoch: String(currentEpoch),

package/src/version.ts

@@ -3,4 +3,4 @@
 
 // This file is generated by genversion.mjs. Do not edit it directly.
 
-export const PACKAGE_VERSION = '2.16.1';
+export const PACKAGE_VERSION = '2.16.3';