@mysten/sui 2.19.0 → 2.20.1

package/docs/cryptography/index.md

@@ -0,0 +1,225 @@
+# Cryptography
+
+> Sign and verify Sui transactions and messages with keypairs and external signers
+
+A signature authorizes every transaction and personal message on Sui. The Sui TypeScript SDK exposes
+a single abstraction for producing those signatures, the `Signer`, along with several
+implementations of it, from in-process keypairs to hardware wallets and cloud key-management
+services (KMS). This page walks through the concepts shared by every signer; the subpages cover each
+implementation in detail.
+
+## Signing schemes
+
+A signer always produces a signature under a signature scheme, which determines the curve and
+signature format. Sui supports three schemes, each with a corresponding `Keypair` class:
+
+| Scheme          | Class              | Import                           |
+| --------------- | ------------------ | -------------------------------- |
+| Ed25519         | `Ed25519Keypair`   | `@mysten/sui/keypairs/ed25519`   |
+| ECDSA Secp256k1 | `Secp256k1Keypair` | `@mysten/sui/keypairs/secp256k1` |
+| ECDSA Secp256r1 | `Secp256r1Keypair` | `@mysten/sui/keypairs/secp256r1` |
+
+For background on the schemes themselves, see the
+[Signatures](https://docs.sui.io/concepts/cryptography/transaction-auth/signatures) concept topic. A
+signer's scheme determines the format of its public key and the Sui address it derives.
+
+## The Signer interface
+
+`Signer` is an abstract class exported from `@mysten/sui/cryptography`. Every signer, whether it
+holds the private key in memory, on a Ledger device, or in AWS KMS, implements the same interface,
+so the rest of your code doesn't need to know where the key lives.
+
+Implementations provide three primitives:
+
+| Method           | Description                                                        |
+| ---------------- | ------------------------------------------------------------------ |
+| `getPublicKey()` | Returns the `PublicKey` for deriving the address and verifying     |
+| `getKeyScheme()` | Returns the signature scheme (`ED25519`, `Secp256k1`, `Secp256r1`) |
+| `sign(bytes)`    | Signs raw bytes and returns the signature                          |
+
+On top of those, `Signer` provides the methods you typically call:
+
+| Method                        | Description                                      |
+| ----------------------------- | ------------------------------------------------ |
+| `toSuiAddress()`              | The Sui address derived from the public key      |
+| `signTransaction(bytes)`      | Signs transaction bytes with the correct intent  |
+| `signPersonalMessage(bytes)`  | Signs a personal message                         |
+| `signAndExecuteTransaction()` | Signs and submits a transaction through a client |
+
+There are two broad families of signer:
+
+- **Key pairs** hold the private key in process. `Keypair` extends `Signer` and adds secret-key
+  import and export (`getSecretKey`, `fromSecretKey`). This is the easiest option for scripts,
+  backends, and tests. See [Key pairs](/sui/cryptography/keypairs).
+- **External signers** keep the private key outside your application, in a KMS, on a hardware
+  wallet, or as a non-extractable browser key. They extend `Signer` directly. See
+  [Signers](/sui/cryptography/signers).
+
+Because both families share the `Signer` interface, you can pass any signer wherever the SDK accepts
+one, for example as the `signer` argument to a client's `signAndExecuteTransaction`.
+
+## Public keys and addresses
+
+Every signer exposes a `PublicKey` through `getPublicKey()`. You use the public key to derive the
+signer's Sui address and to verify signatures:
+
+```typescript
+
+const keypair = new Ed25519Keypair();
+
+// Derive the address directly from the signer...
+const address = keypair.toSuiAddress();
+
+// ...or from its public key
+const publicKey = keypair.getPublicKey();
+const sameAddress = publicKey.toSuiAddress();
+```
+
+## Signing messages and transactions
+
+The signing API is identical for every signer; only construction differs. Use `signPersonalMessage`
+to sign arbitrary bytes and `signTransaction` to sign built transaction bytes:
+
+```typescript
+const message = new TextEncoder().encode('hello world');
+const { signature } = await keypair.signPersonalMessage(message);
+```
+
+Both `signPersonalMessage` and `signTransaction` resolve to `{ bytes, signature }`, where
+`signature` is the serialized signature string used for execution and verification, and `bytes` is
+the base64 payload that the signer signed.
+
+To sign and submit a transaction in one step, 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: keypair,
+});
+
+// signAndExecuteTransaction resolves to a discriminated union, so check for failure first
+if (result.FailedTransaction) {
+	throw new Error('Transaction failed to execute');
+}
+
+console.log('Digest:', result.Transaction.digest);
+```
+
+## Verifying signatures
+
+Verification confirms a signature is valid for a given message and that the expected key produced
+it. The `@mysten/sui/verify` module verifies a signature against a message and recovers the
+`PublicKey` that produced it, without needing the original signer.
+
+```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
+throw if the signature is not valid for it:
+
+```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 works the same way, using `verifyTransactionSignature`:
+
+```typescript
+
+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
+
+You can't verify zkLogin signatures purely on the client. When verifying a zkLogin signature, the
+SDK uses the GraphQL API. This works for Mainnet signatures without any additional configuration.
+For Testnet signatures, 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 two valid addresses for a given set of inputs, so comparing the
+address from `publicKey.toSuiAddress()` directly against an expected address can fail. Instead, pass
+the expected address during verification, or use `publicKey.verifyAddress(address)`:
+
+```typescript
+
+const publicKey = await verifyPersonalMessageSignature(message, zkSignature, {
+	client: new SuiGraphQLClient({
+		url: 'https://graphql.testnet.sui.io/graphql',
+	}),
+	// Throws 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 methods check the signature against the standard and
+[legacy versions of the zkLogin address](https://sdk.mystenlabs.com/sui/zklogin#legacy-addresses).
+
+## Choosing an implementation
+
+- **[Key pairs](/sui/cryptography/keypairs)**: `Ed25519Keypair`, `Secp256k1Keypair`, and
+  `Secp256r1Keypair` hold the private key in process. The easiest option when you manage the secret
+  key yourself. Covers deriving keypairs from mnemonics and secret keys.
+- **[Signers](/sui/cryptography/signers)**: other implementations of the `Signer` interface,
+  including signer packages that keep the private key outside your application — cloud KMS
+  ([AWS](/sui/cryptography/signers/aws-kms), [GCP](/sui/cryptography/signers/gcp-kms)), a
+  [Ledger](/sui/cryptography/signers/ledger) hardware wallet, and non-extractable browser keys with
+  the [Web Crypto](/sui/cryptography/signers/webcrypto) signer — as well as
+  [passkeys](/sui/cryptography/signers/passkey) and
+  [multi-signature](/sui/cryptography/signers/multisig).
+
+If you just need to sign in a script or server and are comfortable managing the secret key yourself,
+start with [Key pairs](/sui/cryptography/keypairs). If the key must never live in your application's
+memory, use one of the external [signers](/sui/cryptography/signers).

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.