@mysten/sui 2.20.0 → 2.20.2

package/docs/cryptography/keypairs.md

@@ -1,11 +1,14 @@
 # Key pairs
 
-> Create and manage Ed25519, Secp256k1, and Secp256r1 keypairs for Sui transaction signing.
+> Create Ed25519, Secp256k1, and Secp256r1 keypairs and derive them from mnemonics and secret keys
 
-The Sui TypeScript SDK provides `Keypair` classes that handle logic for signing and verification
-using the cryptographic key pairs associated with a Sui address.
+A `Keypair` holds a Sui private key in process and signs with it. It is the easiest
+[`Signer`](/sui/cryptography) to use. It is ideal for scripts, backends, and tests where you manage
+the secret key yourself. For the signing and verification API shared by all signers, see
+[Cryptography](/sui/cryptography); this page focuses on creating keypairs and deriving them from
+mnemonics and secret keys.
 
-The Sui TypeScript SDK supports three signing schemes:
+Each signing scheme has a corresponding `Keypair` class:
 
 | Sign scheme     | Class name         | Import folder                    |
 | --------------- | ------------------ | -------------------------------- |
@@ -13,9 +16,6 @@ The Sui TypeScript SDK supports three signing schemes:
 | 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`.
@@ -24,155 +24,55 @@ example, to use the Ed25519 scheme, import the `Ed25519Keypair` class from
 
 ```
 
+## Creating a key pair
+
 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);
+// or, a Keypair from an existing secret key (Uint8Array)
+const fromSecret = Ed25519Keypair.fromSecretKey(secretKey);
 ```
 
-## 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:
+With your key pair created, you can derive its address and sign with it. The following signs a
+personal message and verifies it with the public key:
 
 ```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 publicKey = keypair.getPublicKey();
 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(),
-});
+const isValid = await publicKey.verifyPersonalMessage(message, signature);
 ```
 
-## Verifying zkLogin signatures
+See [Cryptography](/sui/cryptography) for the full signing and verification API, including
+[verifying signatures](/sui/cryptography#verifying-signatures) without the original key pair.
 
-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 works for Mainnet signatures without any
-additional configuration.
+## Public keys
 
-For Testnet signatures, you need to provide a Testnet GraphQL Client:
+Each `Keypair` has an associated `PublicKey`, which you use to verify signatures or to retrieve its
+Sui address. Access it from a `Keypair` with `getPublicKey()`. To recreate a keypair, and therefore
+its public key, from saved key material, reconstruct it from the secret key:
 
 ```typescript
 
-const publicKey = await verifyPersonalMessageSignature(message, zkSignature, {
-	client: new SuiGraphQLClient({
-		url: 'https://graphql.testnet.sui.io/graphql',
-	}),
-});
-```
-
-For some zklogin accounts, there are two valid addresses for a given set of inputs. This means you
-might 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
+// Recreate the keypair from its secret key (Uint8Array)
+const keypair = Ed25519Keypair.fromSecretKey(secretKey);
 
-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');
-}
+// Access the public key and derive the address
+const publicKey = keypair.getPublicKey();
+const address = publicKey.toSuiAddress();
+// or derive the address directly from the keypair
+const sameAddress = keypair.toSuiAddress();
 ```
 
-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).
+See
+[Deriving a `Keypair` from a Bech32 encoded secret key](#deriving-a-keypair-from-a-bech32-encoded-secret-key)
+for working with encoded secret-key formats.
 
 ## Deriving a key pair from a mnemonic
 
@@ -199,14 +99,16 @@ 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.
+keyScheme, and get the key pair's private key bytes, which you can use to instantiate the
+appropriate `Keypair` class.
 
 ```typescript
 
+const encoded = 'suiprivkey1qzse89atw7d3zum8ujep76d2cxmgduyuast0y9fu23xcl0mpafgkktllhyc';
 const { scheme, secretKey } = decodeSuiPrivateKey(encoded);
 
 // use scheme to choose the correct key pair
+let keypair;
 switch (scheme) {
 	case 'ED25519':
 		keypair = Ed25519Keypair.fromSecretKey(secretKey);
@@ -225,16 +127,7 @@ switch (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.
+You can export a keypair to a Bech32 encoded secret key using the `getSecretKey` method.
 
 ```typescript
 const secretKey = keypair.getSecretKey();

package/docs/cryptography/signers/aws-kms.md

@@ -0,0 +1,110 @@
+# AWS KMS Signer
+
+> Sign Sui transactions with a key stored in AWS Key Management Service
+
+The `AwsKmsSigner` signs Sui transactions using a key held in
+[AWS Key Management Service](https://aws.amazon.com/kms/). The private key never leaves AWS; the
+signer sends the message to KMS and receives the signature back.
+
+AWS KMS supports the `Ed25519`, `Secp256k1`, and `Secp256r1` schemes. The curve of the KMS key
+determines the signature scheme (`ECC_NIST_EDWARDS25519` → `Ed25519`, `ECC_SECG_P256K1` →
+`Secp256k1`, `ECC_NIST_P256` → `Secp256r1`). `Ed25519` is Sui's native scheme.
+
+> **Warning:** The AWS KMS Signer requires Node.js >= 22 (the package's `engines.node` constraint) and relies on
+> the global Web Crypto API.
+
+## Installation
+
+```sh npm2yarn
+npm i @mysten/aws-kms-signer
+```
+
+## Creating a signer
+
+Construct the signer with `AwsKmsSigner.fromKeyId`, passing the KMS key ID and the AWS credentials
+and region. This is async: it fetches the public key from KMS so the signer can derive the Sui
+address.
+
+```typescript
+
+const { AWS_ACCESS_KEY_ID, AWS_SECRET_ACCESS_KEY, AWS_REGION, AWS_KMS_KEY_ID } = process.env;
+
+const signer = await AwsKmsSigner.fromKeyId(AWS_KMS_KEY_ID, {
+	region: AWS_REGION,
+	accessKeyId: AWS_ACCESS_KEY_ID,
+	secretAccessKey: AWS_SECRET_ACCESS_KEY,
+});
+```
+
+### Parameters
+
+`fromKeyId(keyId, options)`
+
+| Parameter                 | Type                    | Description                                                      |
+| ------------------------- | ----------------------- | ---------------------------------------------------------------- |
+| `keyId`                   | `string`                | The AWS KMS key ID                                               |
+| `options.region`          | `string`                | The AWS region the key lives in                                  |
+| `options.accessKeyId`     | `string`                | The AWS access key ID (omit when using `credentials`)            |
+| `options.secretAccessKey` | `string`                | The AWS secret access key (omit when using `credentials`)        |
+| `options.credentials`     | `AwsCredentialProvider` | Optional async provider resolved before each request (see below) |
+
+You must supply either static `accessKeyId`/`secretAccessKey` **or** a `credentials` provider.
+
+### Using a credential provider
+
+Instead of static keys, pass an async `credentials` provider (any function returning
+`{ accessKeyId, secretAccessKey, sessionToken? }`). This is structurally compatible with the
+providers from
+[`@aws-sdk/credential-providers`](https://docs.aws.amazon.com/sdk-for-javascript/v3/developer-guide/setting-credentials-node.html),
+so the standard AWS credential chain (SSO, IAM roles, and container/instance metadata) works out of
+the box. Credentials are resolved before each request, so temporary credentials refresh
+automatically once their session nears expiry.
+
+```typescript
+
+const signer = await AwsKmsSigner.fromKeyId(process.env.AWS_KMS_KEY_ID, {
+	region: process.env.AWS_REGION,
+	credentials: fromNodeProviderChain(),
+});
+```
+
+`@aws-sdk/credential-providers` is **not** a dependency of this package, so install it yourself if
+you want the AWS-provided resolvers. This keeps the signer lightweight for edge, browser, and Worker
+runtimes, where you can instead pass static credentials or a custom resolver.
+
+## Usage
+
+Once created, the signer behaves like any other [`Signer`](/sui/cryptography): derive the address,
+sign messages, and sign or execute transactions.
+
+```typescript
+// Derive the Sui address
+const address = signer.getPublicKey().toSuiAddress();
+
+// Sign a personal message
+const message = new TextEncoder().encode('Hello, AWS KMS Signer!');
+const { signature } = await signer.signPersonalMessage(message);
+
+// Verify the signature
+const isValid = await signer.getPublicKey().verifyPersonalMessage(message, signature);
+console.log(isValid); // true
+```
+
+To sign and submit a transaction, pass the signer to a client:
+
+```typescript
+
+const client = new SuiGrpcClient({
+	network: 'testnet',
+	baseUrl: 'https://fullnode.testnet.sui.io:443',
+});
+
+const result = await client.signAndExecuteTransaction({ transaction, signer });
+if (result.FailedTransaction) {
+	throw new Error('Transaction failed to execute');
+}
+console.log(result.Transaction.digest);
+```
+
+See [Cryptography](/sui/cryptography) for the full signing and verification API shared by all
+signers.

package/docs/cryptography/signers/gcp-kms.md

@@ -0,0 +1,91 @@
+# GCP KMS Signer
+
+> Sign Sui transactions with a key stored in Google Cloud Key Management Service
+
+The `GcpKmsSigner` signs Sui transactions using a key held in
+[Google Cloud KMS](https://cloud.google.com/kms). The private key never leaves GCP; the signer sends
+the message digest to KMS and receives the signature back.
+
+GCP KMS supports the `Secp256k1` and `Secp256r1` schemes. The curve of the KMS key determines the
+signature scheme (`EC_SIGN_SECP256K1_SHA256` → `Secp256k1`, `EC_SIGN_P256_SHA256` → `Secp256r1`).
+
+## Installation
+
+```sh npm2yarn
+npm i @mysten/gcp-kms-signer
+```
+
+## Creating a signer
+
+Construct the signer with `GcpKmsSigner.fromOptions`, identifying the key by its project, location,
+key ring, key, and version. This is async: it fetches the public key from KMS so the signer can
+derive the Sui address.
+
+```typescript
+
+const signer = await GcpKmsSigner.fromOptions({
+	projectId: 'your-google-project-id',
+	location: 'your-google-location',
+	keyRing: 'your-google-keyring',
+	cryptoKey: 'your-google-key-name',
+	cryptoKeyVersion: 'your-google-key-version',
+});
+```
+
+### Parameters
+
+`fromOptions(options)`
+
+| Parameter          | Type     | Description           |
+| ------------------ | -------- | --------------------- |
+| `projectId`        | `string` | The GCP project ID    |
+| `location`         | `string` | The GCP location      |
+| `keyRing`          | `string` | The GCP key ring name |
+| `cryptoKey`        | `string` | The GCP key name      |
+| `cryptoKeyVersion` | `string` | The GCP key version   |
+
+If you already have a fully-qualified KMS version name, construct the signer directly with
+`GcpKmsSigner.fromVersionName`:
+
+```typescript
+const signer = await GcpKmsSigner.fromVersionName(
+	'projects/p/locations/l/keyRings/r/cryptoKeys/k/cryptoKeyVersions/1',
+);
+```
+
+## Usage
+
+Once created, the signer behaves like any other [`Signer`](/sui/cryptography): derive the address,
+sign messages, and sign or execute transactions.
+
+```typescript
+// Derive the Sui address
+const address = signer.getPublicKey().toSuiAddress();
+
+// Sign a personal message
+const message = new TextEncoder().encode('Hello, GCP KMS Signer!');
+const { signature } = await signer.signPersonalMessage(message);
+
+// Verify the signature
+const isValid = await signer.getPublicKey().verifyPersonalMessage(message, signature);
+console.log(isValid); // true
+```
+
+To sign and submit a transaction, pass the signer to a client:
+
+```typescript
+
+const client = new SuiGrpcClient({
+	network: 'testnet',
+	baseUrl: 'https://fullnode.testnet.sui.io:443',
+});
+
+const result = await client.signAndExecuteTransaction({ transaction, signer });
+if (result.FailedTransaction) {
+	throw new Error('Transaction failed to execute');
+}
+console.log(result.Transaction.digest);
+```
+
+See [Cryptography](/sui/cryptography) for the full signing and verification API shared by all
+signers.

package/docs/cryptography/signers/index.md

@@ -0,0 +1,78 @@
+# Signers
+
+> Signer implementations beyond keypairs — cloud KMS, Ledger, Web Crypto, passkeys, and multisig
+
+In addition to the in-process [keypairs](/sui/cryptography/keypairs) built into `@mysten/sui`, the
+SDK ecosystem ships more implementations of the [`Signer`](/sui/cryptography) interface. Some keep
+the private key outside your application — in a cloud key-management service (KMS), on a hardware
+wallet, or as a non-extractable browser key — while others, like
+[multisig](/sui/cryptography/signers/multisig), combine several signers together. Because each one
+extends the same `Signer` base class, it works anywhere a keypair does.
+
+## External signers
+
+These signers hold the key material outside your process. Each is published as its **own package**,
+so you install only the one you need:
+
+| Signer            | Package                    | Scheme                 | Key lives in                                                    |
+| ----------------- | -------------------------- | ---------------------- | --------------------------------------------------------------- |
+| `AwsKmsSigner`    | `@mysten/aws-kms-signer`   | Secp256k1 or Secp256r1 | [AWS KMS](/sui/cryptography/signers/aws-kms)                    |
+| `GcpKmsSigner`    | `@mysten/gcp-kms-signer`   | Secp256k1 or Secp256r1 | [GCP KMS](/sui/cryptography/signers/gcp-kms)                    |
+| `LedgerSigner`    | `@mysten/ledger-signer`    | Ed25519                | [Ledger hardware wallet](/sui/cryptography/signers/ledger)      |
+| `WebCryptoSigner` | `@mysten/webcrypto-signer` | Secp256r1              | [Browser Web Crypto store](/sui/cryptography/signers/webcrypto) |
+
+For the AWS and GCP signers, the curve of the underlying KMS key determines the signature scheme
+(`ECC_NIST_P256` → `Secp256r1`, `ECC_SECG_P256K1` → `Secp256k1`).
+
+> Each signer above is its own npm package — import directly from `@mysten/aws-kms-signer`,
+> `@mysten/ledger-signer`, and so on, and depend only on the ones you use. The `@mysten/signers`
+> package is a convenience umbrella that re-exports all four under subpaths (`@mysten/signers/aws`,
+> `@mysten/signers/gcp`, `@mysten/signers/ledger`, `@mysten/signers/webcrypto`) if you would rather
+> depend on a single package. The individual pages below use the standalone packages.
+
+## Other Signer implementations
+
+Two more `Signer` implementations live in `@mysten/sui` itself rather than in a standalone package:
+
+- **[Passkey](/sui/cryptography/signers/passkey)**: sign with a WebAuthn passkey (biometric or
+  platform authenticator) through `PasskeyKeypair`.
+- **[Multi-signature](/sui/cryptography/signers/multisig)**: combine signatures from several public
+  keys under a configurable threshold with `MultiSigPublicKey`. Its `getSigner` method returns a
+  `MultiSigSigner` you can use anywhere a keypair works. The underlying keys can be keypairs, KMS
+  signers, passkeys, or zkLogin identifiers.
+
+## Shared interface
+
+Because every signer extends `Signer`, the signing API is identical regardless of where the key is
+held; only the way you construct the signer differs:
+
+```typescript
+// Derive the address
+const address = signer.getPublicKey().toSuiAddress();
+
+// Sign a personal message
+const message = new TextEncoder().encode('hello world');
+const { signature } = await signer.signPersonalMessage(message);
+
+// Sign and execute a transaction (resolves to a discriminated union)
+const result = await client.signAndExecuteTransaction({ transaction, signer });
+if (result.FailedTransaction) {
+	throw new Error('Transaction failed to execute');
+}
+console.log(result.Transaction.digest);
+```
+
+See [Cryptography](/sui/cryptography) for the full signing and verification API that all signers
+share.
+
+## Construction
+
+Each external signer exposes a static factory rather than a public constructor, because preparing
+the signer requires an async round-trip to fetch the public key from the KMS or device:
+
+- `AwsKmsSigner.fromKeyId(keyId, options)`. See [AWS KMS Signer](/sui/cryptography/signers/aws-kms).
+- `GcpKmsSigner.fromOptions(options)`. See [GCP KMS Signer](/sui/cryptography/signers/gcp-kms).
+- `LedgerSigner.fromDerivationPath(path, ledgerClient, suiClient)`. See
+  [Ledger Signer](/sui/cryptography/signers/ledger).
+- `WebCryptoSigner.generate()` and `WebCryptoSigner.import(exported)`. See
+  [Web Crypto Signer](/sui/cryptography/signers/webcrypto).

package/docs/cryptography/signers/ledger.md

@@ -0,0 +1,76 @@
+# Ledger Signer
+
+> Sign Sui transactions with a Ledger hardware wallet
+
+The `LedgerSigner` signs Sui transactions and personal messages with a
+[Ledger](https://www.ledger.com/) hardware wallet. The private key never leaves the device; you
+confirm each signature on the Ledger. The Ledger signer uses the `Ed25519` scheme.
+
+## Installation
+
+```sh npm2yarn
+npm i @mysten/ledger-signer @mysten/ledgerjs-hw-app-sui
+```
+
+You also need a
+[Ledger transport](https://github.com/LedgerHQ/ledger-live/tree/develop/libs/ledgerjs) for your
+environment, for example `@ledgerhq/hw-transport-node-hid` in Node.js or
+`@ledgerhq/hw-transport-webhid` in the browser.
+
+## Creating a signer
+
+Open a transport, wrap it in a `SuiLedgerClient`, then construct the signer with
+`LedgerSigner.fromDerivationPath`. This is async: it fetches the public key from the device so the
+signer can derive the Sui address.
+
+```typescript
+
+const transport = await Transport.open(undefined);
+const ledgerClient = new SuiLedgerClient(transport);
+const suiClient = new SuiGrpcClient({
+	network: 'testnet',
+	baseUrl: 'https://fullnode.testnet.sui.io:443',
+});
+
+const signer = await LedgerSigner.fromDerivationPath(
+	"m/44'/784'/0'/0'/0'",
+	ledgerClient,
+	suiClient,
+);
+```
+
+### Parameters
+
+`fromDerivationPath(derivationPath, ledgerClient, suiClient)`
+
+| Parameter        | Type                | Description                                           |
+| ---------------- | ------------------- | ----------------------------------------------------- |
+| `derivationPath` | `string`            | BIP-32 derivation path (Sui uses coin type `784`)     |
+| `ledgerClient`   | `SuiLedgerClient`   | A `SuiLedgerClient` wrapping an open Ledger transport |
+| `suiClient`      | `ClientWithCoreApi` | A Sui client used to resolve transaction data         |
+
+## Usage
+
+Derive the address, then sign a transaction or personal message. The user confirms each signature on
+the device.
+
+```typescript
+
+// Derive the Sui address
+const address = signer.toSuiAddress();
+
+// Build and sign a transaction
+const transaction = new Transaction();
+const transactionBytes = await transaction.build({ client: suiClient });
+const { signature } = await signer.signTransaction(transactionBytes);
+
+// Or sign a personal message
+const message = new TextEncoder().encode('Hello, Ledger Signer!');
+await signer.signPersonalMessage(message);
+```
+
+> **Warning:** The Ledger signer supports only `signTransaction` and `signPersonalMessage`. It does not support
+> the generic `sign` and `signWithIntent` methods, which throw an error because the device only
+> signs recognized transaction and message payloads.
+
+See [Cryptography](/sui/cryptography) for the signing and verification API shared by all signers.

package/docs/cryptography/{multisig.md → signers/multisig.md}

@@ -6,8 +6,8 @@ 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`.
+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
 

package/docs/cryptography/{passkey.md → signers/passkey.md}

@@ -90,7 +90,7 @@ work.
 
 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.
+[Key pairs](../keypairs) documentation for more details.
 
 ```typescript
 const publicKey = keypair.getPublicKey();

package/docs/cryptography/{webcrypto-signer.md → signers/webcrypto.md}

@@ -1,13 +1,13 @@
 # Web Crypto Signer
 
-> Sign transactions using the Web Crypto API for secure browser-based key management.
+> Sign transactions using the Web Crypto API for secure browser-based key management
 
 For cases where you need to create keypairs directly within client apps, you can use 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).
+secure and efficient way to generate and manage cryptographic keys in the browser. It generates
+`Secp256r1` keys that you can persist between sessions, and that client-side code (including
+extensions) cannot extract.
 
 Common use cases for the Web Crypto Signer include:
 
@@ -68,8 +68,8 @@ const keypair = await WebCryptoSigner.import(exported);
 ## 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.
+derive the address, sign personal messages, sign transactions, and verify signatures. See
+[Cryptography](/sui/cryptography) for more details.
 
 ```typescript
 const publicKey = keypair.getPublicKey();

package/docs/index.md

@@ -34,11 +34,10 @@ what you need to keep your code light and compact.
   with transactions.
 - [`@mysten/sui/keypairs/*`](/sui/cryptography/keypairs): Modular exports for specific KeyPair
   implementations.
-- [`@mysten/sui/verify`](/sui/cryptography/keypairs#verifying-signatures-without-a-key-pair):
-  Methods for verifying transactions and messages.
-- [`@mysten/sui/cryptography`](/sui/cryptography/keypairs): Shared types and classes for
-  cryptography.
-- [`@mysten/sui/multisig`](/sui/cryptography/multisig): Utilities for working with multisig
+- [`@mysten/sui/verify`](/sui/cryptography#verifying-signatures): Methods for verifying transactions
+  and messages.
+- [`@mysten/sui/cryptography`](/sui/cryptography): Shared types and classes for cryptography.
+- [`@mysten/sui/multisig`](/sui/cryptography/signers/multisig): Utilities for working with multisig
   signatures.
 - [`@mysten/sui/utils`](/sui/utils): Utilities for formatting and parsing various Sui types.
 - [`@mysten/sui/faucet`](#faucet): Methods for requesting SUI from a faucet.