@mysten/docs 0.1.33 → 0.1.34

package/dist/sponsor/validators.md

@@ -0,0 +1,198 @@
+# Validation
+
+> Compose built-in and custom validation analyzers for sponsorship policy
+
+A validator is an analyzer used for policy checks. Create one with `createAnalyzer(...)`, return the
+issues it found, and pass it to `createSponsor({ validate })`. It declares the analyzers it reads
+through `dependencies` and reports one of three outcomes:
+
+- **pass**: `{ result: null }` (or `{ result: [] }`);
+- **reject**: `{ result: [{ code, message }] }`: the transaction is well-formed but violates policy
+  (`POLICY_REJECTED`);
+- **couldn't analyze**: `{ issues: [{ message }] }` or `throw`: the analyzer itself couldn't decide
+  (a failed lookup, an unreachable service), producing `ANALYSIS_FAILED`. This is the analyzer
+  framework's own channel, so it propagates, and dependents don't run.
+
+Reporting findings as the `result` (rather than through `issues`) is what keeps "violates policy"
+distinct from "couldn't be checked". There's no built-in "the sponsor must be paid" rule, because
+value-flow policy is app-specific, so write it over the built-in `balanceFlows` analyzer (signed
+per-address deltas: **negative = value left the owner, positive = arrived**):
+
+```ts
+
+const USDC = '0x...::usdc::USDC';
+
+const requireSponsorPayment = createAnalyzer({
+	dependencies: { balanceFlows: analyzers.balanceFlows },
+	analyze:
+		() =>
+		({ balanceFlows }) => {
+			const received =
+				balanceFlows.sponsor
+					?.filter((flow) => flow.coinType === USDC)
+					.reduce((sum, flow) => sum + flow.amount, 0n) ?? 0n;
+
+			return received < 10_000n
+				? { result: [{ code: 'UNDERPAID', message: `Sponsor received ${received}, needs 10000.` }] }
+				: { result: null };
+		},
+});
+```
+
+The most useful shared analyzer is **`data`**, the parsed transaction (sender, gas data, commands,
+expiration), which most validators read. Alongside it: `balanceFlows` (signed value deltas),
+`transactionResponse` (the dry-run, including effects), `commands`, `moveFunctions`, `objects`,
+`coins`, `inputs`, and `bytes`, plus the sponsor's `currentEpoch`, and any others the analyzer
+package adds (see [`@mysten/wallet-sdk`](https://www.npmjs.com/package/@mysten/wallet-sdk) for the
+full set). All are re-exported as `analyzers` (with `currentEpoch` and `createAnalyzer` alongside).
+A failed analyzer never reaches your `analyze`: it short-circuits to an `ANALYSIS_FAILED` rejection.
+
+## Loading data, and sharing it across validators
+
+An analyzer receives the same `options` the sponsor passes to `analyze` (including **`client`**), so
+it can load onchain data. And because the framework runs each analyzer once and shares its result,
+several validators read it for the cost of one fetch:
+
+```ts
+
+// Loads the *sponsor's* SUI balance via options.client (the gas owner is the sponsor)…
+const sponsorBalance = createAnalyzer({
+	dependencies: { data: analyzers.data },
+	analyze:
+		(options) =>
+		async ({ data }) => {
+			const { balance } = await options.client.core.getBalance({ owner: data.gasData.owner! });
+			return { result: BigInt(balance.balance) };
+		},
+});
+
+// …read by two validators; the `getBalance` call still runs only once.
+const sponsorCanCoverGas = createAnalyzer({
+	dependencies: { sponsorBalance, data: analyzers.data },
+	analyze:
+		() =>
+		({ sponsorBalance, data }) =>
+			sponsorBalance >= BigInt(data.gasData.budget ?? 0)
+				? { result: null }
+				: {
+						result: [{ code: 'SPONSOR_UNDERFUNDED', message: 'Sponsor balance cannot cover gas.' }],
+					},
+});
+const sponsorKeepsReserve = createAnalyzer({
+	dependencies: { sponsorBalance },
+	analyze:
+		() =>
+		({ sponsorBalance }) =>
+			sponsorBalance >= 1_000_000_000n
+				? { result: null }
+				: { result: [{ code: 'RESERVE_LOW', message: 'Sponsor reserve below 1 SUI.' }] },
+});
+
+createSponsor({ signer, client, validate: [sponsorCanCoverGas, sponsorKeepsReserve] });
+```
+
+## Request-scoped options
+
+A validator reads request inputs (an auth token, a tenant id) straight off `options`.
+`createSponsor` **infers** them and requires them, typed, under `validationOptions` on sponsor calls
+(required only when the option itself is required), without an untyped metadata bag:
+
+```ts
+const authChecked = createAnalyzer({
+	analyze: (options: { authToken: string }) => () =>
+		isValidToken(options.authToken)
+			? { result: null }
+			: { result: [{ code: 'BAD_AUTH', message: 'Invalid auth token.' }] },
+});
+
+const sponsor = createSponsor({ signer, client, validate: [authChecked] });
+
+// `validationOptions.authToken` is now a required, typed argument:
+await sponsor.signAndExecuteTransaction({
+	transaction,
+	userSignature,
+	validationOptions: { authToken },
+});
+```
+
+## How it runs
+
+`createSponsor` makes every validator a dependency of **`sponsor.analyzer`**, and validation is just
+`analyze({ check: sponsor.analyzer }, { transaction, client })`. The analyzer framework then
+handles:
+
+- **Lazy**: only analyzers some validator depends on run, so cost tracks your policy. `defaults()`
+  includes `simulationSucceeds`, so the default config _does_ dry-run; drop it (or use only
+  validators that read `data`) and the sponsor **never simulates**. There's no "offline phase" to
+  declare, because it falls out of the dependency graph.
+- **Deduped**: `data` and `balanceFlows` and so on resolve once even when many validators (and a
+  host graph) depend on them.
+- **Propagated**: a failed analyzer becomes an `ANALYSIS_FAILED` rejection rather than reaching a
+  validator with a broken value.
+
+When validation fails, the sponsor never signs and the method **returns**
+`{ $kind: 'Rejected', issues, reason }`, where `issues` lists every reason, and `reason` is
+`'POLICY_REJECTED'` or `'ANALYSIS_FAILED'`. To turn a rejection into a thrown error, the exported
+`SponsorValidationError` class takes `(issues, reason)`.
+
+**`sponsor.analyzer`** is also the composable handle: drop it into any other `analyze()` graph and
+it contributes `SponsorRejection | null`, deduping its analyzers with that graph.
+
+## Built-in validation analyzers
+
+| Validator                      | Reads                  | Rejects when…                                             |
+| ------------------------------ | ---------------------- | --------------------------------------------------------- |
+| `validSender()`                | `data`                 | the sender is unset, or is the gas owner (sponsor)        |
+| `onlyAddressBalanceGas()`      | `data`                 | the gas payment isn't empty (`[]`)†                       |
+| `gasCoinNotUsed()`             | `data`                 | a command uses the gas coin (`tx.gas`)                    |
+| `onlySenderWithdrawals()`      | `data`                 | a `FundsWithdrawal` input isn't the sender's              |
+| `userSignatureMatchesSender()` | `bytes`, `data`        | a supplied user signature isn't a valid sender signature‡ |
+| `gasBudget({ min?, max? })`    | `data`                 | the gas budget is unset or outside the range              |
+| `allowedPackages([...])`       | `data`                 | a MoveCall targets a package outside the allowlist        |
+| `allowedFunctions([...])`      | `data`                 | a MoveCall targets a function outside the allowlist       |
+| `simulationSucceeds()`         | `transactionResponse`  | the dry-run succeeds but the transaction would abort\*    |
+| `boundedExpiration()`          | `data`, `currentEpoch` | the expiration is missing or beyond the next epoch        |
+
+\* The dry-run itself _succeeding_ but reporting an aborting transaction is a **policy** rejection
+(`TRANSACTION_WOULD_FAIL`): the bytes are executable and would still cost the sponsor gas (landing a
+failed transaction with a digest) if submitted. The dry-run _failing to run at all_ (an unreachable
+node, unresolvable objects) is instead surfaced as `ANALYSIS_FAILED`, with the underlying error
+detail.
+
+† Address-balance gas (an empty payment) is how the sponsor pays from its own balance rather than
+from nominated gas coins; the sponsor-builds flow always sets this, so this validator mainly guards
+user-supplied bytes.
+
+‡ Verifies (through `@mysten/sui`'s `isValidTransactionSignature`) that **every** supplied user
+signature is cryptographically valid over the bytes **and** resolves to the sender, caught before
+the sponsor co-signs, rather than only at execution (all supplied signatures are attached to
+execution, so one that isn't the sender's would be rejected onchain after the sponsor signed). A
+malformed, invalid, or wrong-signer signature is rejected as `USER_SIGNATURE_INVALID`; the sender
+match is key-type aware (a zkLogin key matches either its legacy or current address). An
+_environmental_ failure during verification (for example, a zkLogin JWK or epoch lookup throwing)
+isn't a validation result; it surfaces as `ANALYSIS_FAILED`, so a network blip is never reported as
+a bad signature. Passes when no user signature was supplied (the sponsor-builds flow). The signature
+is read from the request, not from `validationOptions`.
+
+`defaults()` bundles `validSender()` + `onlyAddressBalanceGas()` + `gasCoinNotUsed()` +
+`onlySenderWithdrawals()` + `simulationSucceeds()` + `boundedExpiration()`.
+
+## Timing-attack mitigation
+
+Optionally insert random delays to reduce timing manipulation of onchain state between signing and
+execution:
+
+```ts
+createSponsor({
+	signer,
+	client,
+	delay: {
+		beforeSimulate: { min: 50, max: 200 }, // ms (or a fixed number) before the analysis is resolved
+		beforeExecute: { min: 50, max: 200 }, // before executing
+		// random: () => 0.5,                 // override the RNG (e.g. in tests)
+	},
+});
+```
+
+This is mitigation, not prevention. `beforeSimulate` runs once before the analysis resolves (where
+simulation, if any, happens). Default is off.

package/dist/sui/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/dist/sui/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();