@mysten/docs 0.1.1

package/dist/sui/cryptography/keypairs.md

@@ -0,0 +1,267 @@
+# Key pairs
+
+> Create and manage Ed25519, Secp256k1, and Secp256r1 keypairs
+
+The Sui TypeScript SDK provides `Keypair` classes that handle logic for signing and verification
+using the cryptographic key pairs associated with a Sui address.
+
+The Sui TypeScript SDK supports three signing schemes:
+
+| Sign scheme     | Class name         | Import folder                    |
+| --------------- | ------------------ | -------------------------------- |
+| Ed25519         | `Ed25519Keypair`   | `@mysten/sui/keypairs/ed25519`   |
+| ECDSA Secp256k1 | `Secp256k1Keypair` | `@mysten/sui/keypairs/secp256k1` |
+| ECDSA Secp256r1 | `Secp256r1Keypair` | `@mysten/sui/keypairs/secp256r1` |
+
+For information on these schemes, see the
+[Signatures](https://docs.sui.io/concepts/cryptography/transaction-auth/signatures) topic.
+
+To use, import the key pair class your project uses from the `@mysten/sui/keypairs` folder. For
+example, to use the Ed25519 scheme, import the `Ed25519Keypair` class from
+`@mysten/sui/keypairs/ed25519`.
+
+```typescript
+
+```
+
+To create a random key pair (which identifies a Sui address), instantiate a new `Keypair` class. To
+reference a key pair from an existing secret key, pass the secret to the `fromSecretKey` function.
+
+```typescript
+// random Keypair
+const keypair = new Ed25519Keypair();
+// Keypair from an existing secret key (Uint8Array)
+const keypair = Ed25519Keypair.fromSecretKey(secretKey);
+```
+
+With your key pair created, you can reference it when performing actions on the network. For
+example, you can use it to sign transactions, like the following code that creates and signs a
+personal message using the public key from the key pair created in the previous code:
+
+```typescript
+const publicKey = keypair.getPublicKey();
+const message = new TextEncoder().encode('hello world');
+
+const { signature } = await keypair.signPersonalMessage(message);
+const isValid = await publicKey.verifyPersonalMessage(message, signature);
+```
+
+## Public keys
+
+Each `Keypair` has an associated `PublicKey` class. You use the public key to verify signatures or
+to retrieve its associated Sui address. You can access a `Keypair` from its `PublicKey` or construct
+it from the bytes (as a `Uint8Array`) of the `PublicKey`, as in the following code:
+
+```typescript
+
+const keypair = new Ed25519Keypair();
+
+// method 1
+const bytes = keypair.getPublicKey().toRawBytes();
+const publicKey = new Ed25519PublicKey(bytes);
+const address = publicKey.toSuiAddress();
+
+// method 2
+const address = keypair.getPublicKey().toSuiAddress();
+// or use `toSuiAddress()` directly
+const address = keypair.toSuiAddress();
+```
+
+## Verifying signatures without a key pair
+
+When you have an existing public key, you can use it to verify a signature. Verification ensures the
+signature is valid for the provided message and is signed with the appropriate secret key.
+
+The following code creates a key pair in the Ed25519 scheme, creates and signs a message with it,
+then verifies the message to retrieve the public key. The code then uses `toSuiAddress()` to check
+if the address associated with the public key matches the address that the key pair defines.
+
+```typescript
+
+const keypair = new Ed25519Keypair();
+const message = new TextEncoder().encode('hello world');
+const { signature } = await keypair.signPersonalMessage(message);
+
+const publicKey = await verifyPersonalMessageSignature(message, signature);
+
+if (!publicKey.verifyAddress(keypair.toSuiAddress())) {
+	throw new Error('Signature was valid, but was signed by a different key pair');
+}
+```
+
+## Verifying that a signature is valid for a specific address
+
+`verifyPersonalMessageSignature` and `verifyTransactionSignature` accept an optional `address`, and
+will throw an error if the signature is not valid for the provided address.
+
+```typescript
+
+const keypair = new Ed25519Keypair();
+const message = new TextEncoder().encode('hello world');
+const { signature } = await keypair.signPersonalMessage(message);
+
+await verifyPersonalMessageSignature(message, signature, {
+	address: keypair.toSuiAddress(),
+});
+```
+
+## Verifying transaction signatures
+
+Verifying transaction signatures is similar to personal message signature verification, except you
+use `verifyTransactionSignature`:
+
+```typescript
+// import SuiGrpcClient to create a network client
+
+// create a client connected to testnet
+const client = new SuiGrpcClient({
+	network: 'testnet',
+	baseUrl: 'https://fullnode.testnet.sui.io:443',
+});
+const tx = new Transaction();
+// ... add some transactions...
+const bytes = await tx.build({ client });
+
+const keypair = new Ed25519Keypair();
+const { signature } = await keypair.signTransaction(bytes);
+
+await verifyTransactionSignature(bytes, signature, {
+	// optionally verify that the signature is valid for a specific address
+	address: keypair.toSuiAddress(),
+});
+```
+
+## Verifying zkLogin signatures
+
+ZkLogin signatures can't be verified purely on the client. When verifying a zkLogin signature, the
+SDK uses the GraphQL API to verify the signature. This will work for mainnet signatures without any
+additional configuration.
+
+For testnet signatures, you will need to provide a testnet GraphQL Client:
+
+```typescript
+
+const publicKey = await verifyPersonalMessageSignature(message, zkSignature, {
+	client: new SuiGraphQLClient({
+		url: 'https://graphql.testnet.sui.io/graphql',
+	}),
+});
+```
+
+For some zklogin accounts, there are 2 valid addresses for a given set of inputs. This means you may
+run into issues if you try to compare the address returned by `publicKey.toSuiAddress()` directly
+with an expected address.
+
+Instead, you can either pass in the expected address during verification, or use the
+`publicKey.verifyAddress(address)` method:
+
+```typescript
+
+const publicKey = await verifyPersonalMessageSignature(message, zkSignature, {
+	client: new SuiGraphQLClient({
+		url: 'https://graphql.testnet.sui.io/graphql',
+	}),
+	// Pass in the expected address, and the verification method will throw an error if the signature is not valid for the provided address
+	address: '0x...expectedAddress',
+});
+// or
+
+if (!publicKey.verifyAddress('0x...expectedAddress')) {
+	throw new Error('Signature was valid, but was signed by a different key pair');
+}
+```
+
+Both of these methods will check the signature against both the standard and
+[legacy versions of the zklogin address](https://sdk.mystenlabs.com/sui/zklogin#legacy-addresses).
+
+## Deriving a key pair from a mnemonic
+
+The Sui TypeScript SDK supports deriving a key pair from a mnemonic phrase. This can be useful when
+building wallets or other tools that allow a user to import their private keys.
+
+```typescript
+const exampleMnemonic = 'result crisp session latin ...';
+
+const keyPair = Ed25519Keypair.deriveKeypair(exampleMnemonic);
+```
+
+## Deriving a `Keypair` from a Bech32 encoded secret key
+
+If you know the Keypair scheme for your secret key, you can use the `fromSecretKey` method of the
+appropriate `Keypair` class to derive the keypair from the secret key.
+
+```typescript
+
+// Example bech32 encoded secret key (which always starts with 'suiprivkey')
+const secretKey = 'suiprivkey1qzse89atw7d3zum8ujep76d2cxmgduyuast0y9fu23xcl0mpafgkktllhyc';
+
+const keypair = Ed25519Keypair.fromSecretKey(secretKey);
+```
+
+You can also use the `decodeSuiPrivateKey` function to decode the secret key and determine the
+keyScheme, and get the keypairs private key bytes, which can be used to instantiate the appropriate
+`Keypair` class.
+
+```typescript
+
+const { scheme, secretKey } = decodeSuiPrivateKey(encoded);
+
+// use scheme to choose the correct key pair
+switch (scheme) {
+	case 'ED25519':
+		keypair = Ed25519Keypair.fromSecretKey(secretKey);
+		break;
+	case 'Secp256r1':
+		keypair = Secp256r1Keypair.fromSecretKey(secretKey);
+		break;
+	case 'Secp256k1':
+		keypair = Secp256k1Keypair.fromSecretKey(secretKey);
+		break;
+	default:
+		throw new Error(`Unsupported key pair scheme: ${scheme}`);
+}
+```
+
+See [SIP-15](https://github.com/sui-foundation/sips/blob/main/sips/sip-15.md) for additional context
+and motivation.
+
+If you know your keypair scheme, you can use the `fromSecretKey` method of the appropriate keypair
+to directly derive the keypair from the secret key.
+
+```typescript
+const secretKey = 'suiprivkey1qzse89atw7d3zum8ujep76d2cxmgduyuast0y9fu23xcl0mpafgkktllhyc';
+
+const keypair = Ed25519Keypair.fromSecretKey(secretKey);
+```
+
+You can also export a keypair to a Bech32 encoded secret key using the `getSecretKey` method.
+
+```typescript
+const secretKey = keypair.getSecretKey();
+```
+
+If you have only the raw private key bytes for your keypair, you can encode to the Bech32 format
+using the `encodeSuiPrivateKey` function.
+
+```typescript
+
+const encoded = encodeSuiPrivateKey(
+	new Uint8Array([
+		59, 148, 11, 85, 134, 130, 61, 253, 2, 174, 59, 70, 27, 180, 51, 107, 94, 203, 174, 253, 102,
+		39, 170, 146, 46, 252, 4, 143, 236, 12, 136, 28,
+	]),
+	'ED25519',
+);
+```
+
+## Deriving a `Keypair` from a hex encoded secret key
+
+If you have an existing secret key formatted as a hex encoded string, you can derive a `Keypair` by
+converting the secret key to a `Uint8Array` and passing it to the `fromSecretKey` method of a
+`Keypair` class.
+
+```typescript
+
+const secret = '0x...';
+const keypair = Ed25519Keypair.fromSecretKey(fromHex(secret));
+```

package/dist/sui/cryptography/multisig.md

@@ -0,0 +1,194 @@
+# Multi-Signature Transactions
+
+> Create multi-signature transactions with multiple signers
+
+The Sui TypeScript SDK provides a `MultiSigPublicKey` class to support
+[Multi-Signature](https://docs.sui.io/concepts/cryptography/transaction-auth/multisig) (MultiSig)
+transaction and personal message signing.
+
+This class implements the same interface as the `PublicKey` classes that [Keypairs](./keypairs) uses
+and you call the same methods to verify signatures for `PersonalMessages` and `Transactions`.
+
+## Creating a MultiSigPublicKey
+
+To create a `MultiSigPublicKey`, you provide a `threshold`(u16) value and an array of objects that
+contain `publicKey` and `weight`(u8) values. If the combined weight of valid signatures for a
+transaction is equal to or greater than the threshold value, then the Sui network considers the
+transdaction valid.
+
+```typescript
+
+const kp1 = new Ed25519Keypair();
+const kp2 = new Ed25519Keypair();
+const kp3 = new Ed25519Keypair();
+
+const multiSigPublicKey = MultiSigPublicKey.fromPublicKeys({
+	threshold: 2,
+	publicKeys: [
+		{
+			publicKey: kp1.getPublicKey(),
+			weight: 1,
+		},
+		{
+			publicKey: kp2.getPublicKey(),
+			weight: 1,
+		},
+		{
+			publicKey: kp3.getPublicKey(),
+			weight: 2,
+		},
+	],
+});
+
+const multisigAddress = multiSigPublicKey.toSuiAddress();
+```
+
+The `multiSigPublicKey` in the preceding code enables you to verify that signatures have a combined
+weight of at least `2`. A signature signed with only `kp1` or `kp2` is not valid, but a signature
+signed with both `kp1` and `kp2`, or just `kp3` is valid.
+
+## Combining signatures with a MultiSigPublicKey
+
+To sign a message or transaction for a MultiSig address, you must collect signatures from the
+individual key pairs, and then combine them into a signature using the `MultiSigPublicKey` class for
+the address.
+
+```typescript
+// This example uses the same imports, key pairs, and multiSigPublicKey from the previous example
+const message = new TextEncoder().encode('hello world');
+
+const signature1 = (await kp1.signPersonalMessage(message)).signature;
+const signature2 = (await kp2.signPersonalMessage(message)).signature;
+
+const combinedSignature = multiSigPublicKey.combinePartialSignatures([signature1, signature2]);
+
+const isValid = await multiSigPublicKey.verifyPersonalMessage(message, combinedSignature);
+```
+
+## Creating a MultiSigSigner
+
+The `MultiSigSigner` class allows you to create a Signer that can be used to sign personal messages
+and Transactions like any other keypair or signer class. This is often easier than manually
+combining signatures, since many methods accept Signers and handle signing directly.
+
+A `MultiSigSigner` is created by providing the underlying Signers to the `getSigner` method on the
+`MultiSigPublicKey`. You can provide a subset of the Signers that make up the public key, so long as
+their combined weight is equal to or greater than the threshold.
+
+```typescript
+
+const kp1 = new Ed25519Keypair();
+const kp2 = new Ed25519Keypair();
+
+const multiSigPublicKey = MultiSigPublicKey.fromPublicKeys({
+	threshold: 1,
+	publicKeys: [
+		{
+			publicKey: kp1.getPublicKey(),
+			weight: 1,
+		},
+		{
+			publicKey: kp2.getPublicKey(),
+			weight: 1,
+		},
+	],
+});
+
+const signer = multiSigPublicKey.getSigner(kp1);
+
+const message = new TextEncoder().encode('hello world');
+const { signature } = await signer.signPersonalMessage(message);
+const isValid = await multiSigPublicKey.verifyPersonalMessage(message, signature);
+```
+
+## Multisig with zkLogin
+
+You can use zkLogin to participate in multisig just like keys for other signature schemes. Unlike
+other keys that come with a public key, you define a public identifier for zkLogin.
+
+For example, the following example creates a 1-out-of-2 multisig with a single key and a zkLogin
+public identifier:
+
+```typescript
+// a single Ed25519 keypair and its public key.
+const kp1 = new Ed25519Keypair();
+const pkSingle = kp1.getPublicKey();
+
+// compute the address seed based on user salt and jwt token values.
+const decodedJWT = decodeJwt('a valid jwt token here');
+const userSalt = BigInt('123'); // a valid user salt
+const addressSeed = genAddressSeed(userSalt, 'sub', decodedJwt.sub, decodedJwt.aud).toString();
+
+// a zkLogin public identifier derived from an address seed and an iss string.
+let pkZklogin = toZkLoginPublicIdentifier(addressSeed, decodedJwt.iss);
+
+// derive multisig address from multisig public key defined by the single key and zkLogin public
+// identifier with weight and threshold.
+const multiSigPublicKey = MultiSigPublicKey.fromPublicKeys({
+	threshold: 1,
+	publicKeys: [
+		{ publicKey: pkSingle, weight: 1 },
+		{ publicKey: pkZklogin, weight: 1 },
+	],
+});
+
+// this is the sender of any transactions from this multisig account.
+const multisigAddress = multiSigPublicKey.toSuiAddress();
+
+// create a regular zklogin signature from the zkproof and ephemeral signature for zkLogin.
+// see zklogin-integration.mdx for more details.
+const zkLoginSig = getZkLoginSignature({
+	inputs: zkLoginInputs,
+	maxEpoch: '2',
+	userSignature: fromBase64(ephemeralSig),
+});
+
+// a valid multisig with just the zklogin signature.
+const multisig = multiSigPublicKey.combinePartialSignatures([zkLoginSig]);
+```
+
+### Benefits and Design for zkLogin in Multisig
+
+Because zkLogin assumes the application client ID and its issuer (such as Google) liveliness, using
+zkLogin with multisig provides improved recoverability to a zkLogin account. In the previous example
+of 1-out-of-2 multisig, users can use zkLogin in their regular wallet flow, but if the application
+or the issuer is deprecated, the user can still use the regular private key account to access funds
+in the multisig wallet.
+
+This also opens the door to design multisig across any number of zkLogin accounts and of different
+providers (max number is capped at 10 accounts) with customizable weights and thresholds. For
+example, you can set up a multisig address with threshold of 2, where the public keys or identifiers
+are defined as:
+
+1. Charlie's own Google account with weight 2
+2. Charlie's friend Alice's Apple account with weight 1
+3. Charlie's friend Bob's Facebook account with weight 1
+
+In this case, Charlie can always use their Google account for transactions out of the multisig
+address for the threshold. At the same time, Charlie still has access to his account by combining
+partial signatures from Alice and Bob.
+
+## Multisig with Passkey
+
+You can use a `PasskeyKeypair` (a `Keypair`) and `PasskeyPublicKey` (a `PublicKey`) as components in
+a Multisig setup. Once initialized, they support both Multisig address derivation and transaction
+signing.
+
+```typescript
+const passkeyKeypair = await PasskeyKeypair.getPasskeyInstance(
+	new BrowserPasskeyProvider('Sui Passkey Example', {
+		rpName: 'Sui Passkey Example',
+		rpId: window.location.hostname,
+	} as BrowserPasswordProviderOptions),
+);
+
+const passkeyPublicKey = passkeyKeypair.getPublicKey();
+
+const multiSigPublicKey = MultiSigPublicKey.fromPublicKeys({
+	threshold: 1,
+	publicKeys: [
+		{ publicKey: passkeyPublicKey, weight: 1 },
+		// other keys
+	],
+});
+```

package/dist/sui/cryptography/passkey.md

@@ -0,0 +1,111 @@
+# Passkey
+
+> Use WebAuthn passkeys for Sui transaction signing
+
+Similar to other Keypair classes, the Sui TypeScript SDK provides the `PasskeyKeypair` that handles
+communication with the passkey device and signing with it. This SDK defines the address and
+signatures according to [SIP-9](https://github.com/sui-foundation/sips/blob/main/sips/sip-9.md).
+
+To use, import the `PasskeyKeypair` class from `@mysten/sui/keypairs/passkey`.
+
+```typescript
+
+	BrowserPasskeyProvider,
+	BrowserPasswordProviderOptions,
+	PasskeyKeypair,
+} from '@mysten/sui/keypairs/passkey';
+```
+
+## Create a new passkey
+
+To create a new passkey with the passkey device, and initialize a `PasskeyKeypair`, you can use the
+`PasskeyProvider` and provide the `rpName`, `rpId` and additional options. Note that
+`getPasskeyInstance` call will initialize a new passkey wallet for the origin.
+
+```typescript
+const keypair = await PasskeyKeypair.getPasskeyInstance(
+	new BrowserPasskeyProvider('Sui Passkey Example', {
+		rpName: 'Sui Passkey Example',
+		rpId: window.location.hostname,
+		authenticatorSelection: {
+			authenticatorAttachment: 'cross-platform', // or "platform"
+		},
+	} as BrowserPasswordProviderOptions),
+);
+```
+
+You can optionally specify the `authenticatorSelection` parameter when creating a passkey instance:
+
+- `cross-platform`: Use this for authenticators that work across devices, such as hardware security
+  keys or mobile phones.
+- `platform`: Use this for authenticators tied to a specific device, such as Touch ID, Face ID, or
+  Windows Hello.
+
+Because a passkey device will only return the public key upon creation, but not upon signing, it is
+recommended for the frontend to always cache the `PasskeyKeypair` instance that contains the public
+key in the wallet. When a user tries to sign a transaction, it will just call signTransaction on the
+same instance and the public key is available when constructing the passkey signature.
+
+It is recommended that the user should only be allowed to create a passkey wallet once per origin.
+If the user ended up with multiple passkeys for the same origin, the passkey UI would show a list of
+all passkeys of the same origin and the user can choose which one to use. This can be a confusing
+experience since they do not remember which passkey is the way that the wallet was created for.
+
+## Recover a passkey
+
+However, if the user is logged out or uses a different browser or device, or the `PasskeyKeypair`
+instance is no longer present for any reason, the user should be prompt to recover the public key
+(e.g. "Log in to existing passkey wallet") to be able to use the passkey wallet again. If the user
+is prompted to create a new key in passkey device, a fresh new wallet with new address will be
+created.
+
+One can recover the unique public key with exactly two passkey signatures on two messages. This
+means that if the user is asked to sign two messages, the developer can recover an unique public key
+and its Sui address.
+
+```typescript
+let provider = new BrowserPasskeyProvider('Sui Passkey Example', {
+	rpName: 'Sui Passkey Example',
+	rpId: window.location.hostname,
+} as BrowserPasswordProviderOptions);
+
+const testMessage = new TextEncoder().encode('Hello world!');
+const possiblePks = await PasskeyKeypair.signAndRecover(provider, testMessage);
+
+const testMessage2 = new TextEncoder().encode('Hello world 2!');
+const possiblePks2 = await PasskeyKeypair.signAndRecover(provider, testMessage2);
+
+const commonPk = findCommonPublicKey(possiblePks, possiblePks2);
+const keypair = new PasskeyKeypair(commonPk.toRawBytes(), provider);
+```
+
+Alternatively, the developer can choose to ask the user to only sign one personal message that
+returns two possible public keys. Then the frontend may derive the addresses for both, and check
+onchain for the unique address that contains assets. Or the frontend may retrieve additional
+signatures from past transaction history for the given address. This may a preferred user experience
+since the user is only prompted to sign one message, but the frontend needs to do extra work.
+
+## Usage
+
+The usage for a passkey keypair is the same as any other keypair. You can derive the public key,
+derive the address, sign personal messages, sign transactions and verify signatures. See the
+[Key pairs](./keypairs) documentation for more details.
+
+```typescript
+const publicKey = keypair.getPublicKey();
+const address = publicKey.toSuiAddress();
+
+const message = new TextEncoder().encode('hello world');
+const { signature } = await keypair.signPersonalMessage(message);
+
+const txSignature = await passkey.signTransaction(txBytes);
+```
+
+An example implemention can be found [here](https://github.com/MystenLabs/passkey-example).
+
+## Supported Platforms
+
+Sui supports passkey wallets on any device that complies with the WebAuthn standard. This includes
+most modern browsers and operating systems across desktop and mobile. To check which platforms and
+authenticators are compatible, see the
+[Passkeys.dev device support list](https://passkeys.dev/device-support/).

package/dist/sui/cryptography/webcrypto-signer.md

@@ -0,0 +1,81 @@
+# Web Crypto Signer
+
+> Sign transactions using the Web Crypto API
+
+For cases where you need to create keypairs directly within client dapps, we recommend using the Web
+Crypto Signer. This signer leverages the
+[Web Crypto API](https://developer.mozilla.org/en-US/docs/Web/API/Web_Crypto_API) to provide a
+secure and efficient way to generate and manage cryptographic keys in the browser. The generated
+keys are `Secp256r1` keys which can be persisted between sessions, and are not extractable by
+client-side code (including extensions).
+
+Common use cases for the Web Crypto Signer include:
+
+- zkLogin ephemeral keypairs
+- Session-based keypairs
+
+## Installation
+
+To use the Web Crypto Signer, you need to install the `@mysten/signers` package.
+
+```sh npm2yarn
+npm i @mysten/signers
+```
+
+You can then import the `WebCryptoSigner` class from the package:
+
+```typescript
+
+```
+
+## Create a new signer
+
+To generate a new signer, you can invoke the `generate()` static method on the `WebCryptoSigner`
+class.
+
+```typescript
+const keypair = await WebCryptoSigner.generate();
+```
+
+## Persisting and recovering the keypair
+
+The private key for the signer is not extractable, but you can persist the keypair using the
+browser's IndexedDB storage. To streamline this process, the keypair provides an `export()` method
+which returns an object containing the public key and a reference to the private key:
+
+```typescript
+// Get the exported keypair:
+const exported = keypair.export();
+
+// Write the keypair to IndexedDB.
+// This method does not exist, you need to implement it yourself. We recommend `idb-keyval` for simplicity.
+await writeToIndexedDB('keypair', exported);
+```
+
+You can then recover the keypair by reading it from IndexedDB and passing it to the `import()`
+method.
+
+```typescript
+// Read the keypair from IndexedDB.
+const exported = await readFromIndexedDB('keypair');
+
+const keypair = await WebCryptoSigner.import(exported);
+```
+
+> **Warning:** Ensure that you do not call `JSON.stringify` on the exported keypair before persisting it to
+> IndexedDB, as it will throw an error and fail to persist.
+
+## Usage
+
+The usage for a Web Crypto signer is the same as any other keypair. You can derive the public key,
+derive the address, sign personal messages, sign transactions and verify signatures. See the
+[Key pairs](./keypairs) documentation for more details.
+
+```typescript
+const publicKey = keypair.getPublicKey();
+const address = publicKey.toSuiAddress();
+
+const message = new TextEncoder().encode('hello world');
+await keypair.signPersonalMessage(message);
+await keypair.signTransaction(txBytes);
+```