@mysten/sui 2.6.0 → 2.8.0

package/docs/zklogin.md

@@ -0,0 +1,78 @@
+# 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.6.0",
+  "version": "2.8.0",
   "license": "Apache-2.0",
   "sideEffects": false,
   "files": [
@@ -15,6 +15,7 @@
     "client",
     "cryptography",
     "dist",
+    "docs",
     "experimental",
     "faucet",
     "graphql",
@@ -168,8 +169,8 @@
     "graphql": "^16.12.0",
     "poseidon-lite": "0.2.1",
     "valibot": "^1.2.0",
-    "@mysten/bcs": "^2.0.2",
-    "@mysten/utils": "^0.3.1"
+    "@mysten/utils": "^0.3.1",
+    "@mysten/bcs": "^2.0.3"
   },
   "scripts": {
     "clean": "rm -rf tsconfig.tsbuildinfo ./dist",
@@ -182,6 +183,7 @@
     "codegen:grpc-header": "find src/grpc/proto -type f -exec sh -c 'echo \"// Copyright (c) Mysten Labs, Inc.\\n// SPDX-License-Identifier: Apache-2.0\\n\" | cat - {} > temp && mv temp {}' \\;",
     "codegen:grpc-extensions": "find src/grpc/proto -name '*.ts' | xargs sed -i '' -E 's/from \"(\\.[^\"]+)\"/from \"\\1.js\"/g'",
     "build": "rm -rf dist && node genversion.mjs && tsc --noEmit && tsdown",
+    "build:docs": "tsx ../docs/scripts/build-docs.ts",
     "vitest": "vitest",
     "test": "pnpm test:typecheck && pnpm test:unit",
     "test:typecheck": "tsc -p ./test",

package/src/client/types.ts

@@ -85,6 +85,13 @@ export namespace SuiClientTypes {
 		 * use the `content` field and parse the BCS data directly.
 		 */
 		json?: boolean;
+		/**
+		 * Include the Display v2 rendered output for the object.
+		 *
+		 * Returns a map of display field names to their rendered string values.
+		 * Returns `null` if the object's type does not have an associated Display template.
+		 */
+		display?: boolean;
 	}
 
 	export interface GetObjectsOptions<
@@ -169,6 +176,15 @@ export namespace SuiClientTypes {
 		 * the `content` field and parse the BCS data directly.
 		 */
 		json: Include extends { json: true } ? Record<string, unknown> | null : undefined;
+		/** Display rendered output. `null` if the type has no Display template. */
+		display: Include extends { display: true } ? Display | null : undefined;
+	}
+
+	export interface Display {
+		/** Successfully rendered display field values, keyed by field name. */
+		output: Record<string, string> | null;
+		/** Per-field rendering errors, keyed by field name. `null` if all fields succeeded. */
+		errors: Record<string, string> | null;
 	}
 
 	export interface Coin {

package/src/graphql/core.ts

@@ -100,6 +100,7 @@ export class GraphQLCoreClient extends CoreClient {
 						includePreviousTransaction: options.include?.previousTransaction ?? false,
 						includeObjectBcs: options.include?.objectBcs ?? false,
 						includeJson: options.include?.json ?? false,
+						includeDisplay: options.include?.display ?? false,
 					},
 				},
 				(result) => result.multiGetObjects,
@@ -139,6 +140,11 @@ export class GraphQLCoreClient extends CoreClient {
 								: null
 							: undefined;
 
+						const displayData = mapDisplay(
+							options.include?.display,
+							obj.asMoveObject?.contents?.display,
+						);
+
 						return {
 							objectId: obj.address,
 							version: obj.version?.toString()!,
@@ -150,6 +156,7 @@ export class GraphQLCoreClient extends CoreClient {
 								undefined) as SuiClientTypes.Object<Include>['previousTransaction'],
 							objectBcs: objectBcs as SuiClientTypes.Object<Include>['objectBcs'],
 							json: jsonContent as SuiClientTypes.Object<Include>['json'],
+							display: displayData as SuiClientTypes.Object<Include>['display'],
 						};
 					}),
 			);
@@ -176,6 +183,7 @@ export class GraphQLCoreClient extends CoreClient {
 					includePreviousTransaction: options.include?.previousTransaction ?? false,
 					includeObjectBcs: options.include?.objectBcs ?? false,
 					includeJson: options.include?.json ?? false,
+					includeDisplay: options.include?.display ?? false,
 				},
 			},
 			(result) => result.address?.objects,
@@ -202,6 +210,10 @@ export class GraphQLCoreClient extends CoreClient {
 							? (obj.contents.json as Record<string, unknown>)
 							: null
 						: undefined) as SuiClientTypes.Object<Include>['json'],
+					display: mapDisplay(
+						options.include?.display,
+						obj.contents?.display,
+					) as SuiClientTypes.Object<Include>['display'],
 				}),
 			),
 			hasNextPage: objects.pageInfo.hasNextPage,
@@ -556,22 +568,19 @@ export class GraphQLCoreClient extends CoreClient {
 				? ZkLoginIntentScope.TransactionData
 				: ZkLoginIntentScope.PersonalMessage;
 
-		const result = await this.#graphqlQuery(
-			{
-				query: VerifyZkLoginSignatureDocument,
-				variables: {
-					bytes: options.bytes,
-					signature: options.signature,
-					intentScope,
-					author: options.address,
-				},
+		const { data } = await this.#graphqlClient.query({
+			query: VerifyZkLoginSignatureDocument,
+			variables: {
+				bytes: options.bytes,
+				signature: options.signature,
+				intentScope,
+				author: options.address,
 			},
-			(result) => result.verifyZkLoginSignature,
-		);
+		});
 
 		return {
-			success: result.success ?? false,
-			errors: result.error ? [result.error] : [],
+			success: data?.verifyZkLoginSignature?.success ?? false,
+			errors: [],
 		};
 	}
 
@@ -748,6 +757,18 @@ export type GraphQLResponseErrors = Array<{
 	path?: (string | number)[];
 }>;
 
+function mapDisplay(
+	include: boolean | undefined,
+	display: { output?: unknown | null; errors?: unknown | null } | null | undefined,
+): SuiClientTypes.Display | null | undefined {
+	if (!include) return undefined;
+	if (!display) return null;
+	return {
+		output: (display.output as Record<string, string> | null) ?? null,
+		errors: (display.errors as Record<string, string> | null) ?? null,
+	};
+}
+
 function handleGraphQLErrors(errors: GraphQLResponseErrors | undefined): void {
 	if (!errors || errors.length === 0) return;