@mysten/sui 2.20.0 → 2.20.1

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.

package/docs/llms-index.md

@@ -13,10 +13,15 @@
 - [Coins and Balances](./transactions/coins-and-balances.md): Work with coin objects and address balances in transactions
 - [Commands and Inputs Reference](./transactions/reference.md): Complete reference for transaction commands and input types
 - [Building Offline](./transactions/offline.md): Build transactions without a network connection
-- [Key pairs](./cryptography/keypairs.md): Create and manage Ed25519, Secp256k1, and Secp256r1 keypairs for Sui transaction signing.
-- [Multi-Signature Transactions](./cryptography/multisig.md): Create multi-signature transactions with multiple signers on Sui.
-- [Passkey](./cryptography/passkey.md): Use WebAuthn passkeys for Sui transaction signing.
-- [Web Crypto Signer](./cryptography/webcrypto-signer.md): Sign transactions using the Web Crypto API for secure browser-based key management.
+- [Cryptography](./cryptography.md): Sign and verify Sui transactions and messages with keypairs and external signers
+- [Key pairs](./cryptography/keypairs.md): Create Ed25519, Secp256k1, and Secp256r1 keypairs and derive them from mnemonics and secret keys
+- [Signers](./cryptography/signers.md): Signer implementations beyond keypairs — cloud KMS, Ledger, Web Crypto, passkeys, and multisig
+- [AWS KMS Signer](./cryptography/signers/aws-kms.md): Sign Sui transactions with a key stored in AWS Key Management Service
+- [GCP KMS Signer](./cryptography/signers/gcp-kms.md): Sign Sui transactions with a key stored in Google Cloud Key Management Service
+- [Ledger Signer](./cryptography/signers/ledger.md): Sign Sui transactions with a Ledger hardware wallet
+- [Web Crypto Signer](./cryptography/signers/webcrypto.md): Sign transactions using the Web Crypto API for secure browser-based key management
+- [Passkey](./cryptography/signers/passkey.md): Use WebAuthn passkeys for Sui transaction signing.
+- [Multi-Signature Transactions](./cryptography/signers/multisig.md): Create multi-signature transactions with multiple signers on Sui.
 - [The `@mysten/sui/utils` package](./utils.md): Utility functions for addresses, coins, and common operations in the Sui TypeScript SDK.
 - [Derived Objects](./utils/derived_objects.md): Compute derived object IDs from parent objects for deterministic offline derivation.
 - [BCS](./bcs.md): Binary Canonical Serialization for encoding Sui Move types.

package/docs/migrations/sui-2.0/index.md

@@ -155,4 +155,17 @@ For wallet builders and SDK maintainers building on the Sui ecosystem:
 - **[Wallet builders](/sui/migrations/sui-2.0/wallet-builders):** Guide for wallet implementations
   adapting to `reportTransactionEffects` removal and new core API response format
 - **[SDK maintainers](/sui/migrations/sui-2.0/sdk-maintainers):** Guide for SDK authors migrating to
-  `ClientWithCoreApi` and the new transport-agnostic architecture
+  `ClientWithCoreApi` and the new transport-agnostic architecture
+
+## Non-existent objects
+
+When migrating from the v1 SDK to the v2 SDK, review any code paths that read objects or dynamic
+fields that may not exist.
+
+In v1, methods such as `core.getObject` and `getDynamicField` return `null` when the requested
+object or field does not exist. In v2, the same operations throw an exception instead. Applications
+that previously relied on `null` checks should be updated to handle exceptions appropriately, either
+through try/catch blocks or by validating object existence before attempting to read it.
+
+This behavioral change may require updates to error handling logic to avoid unexpected runtime
+failures after migration.

package/docs/zklogin.md

@@ -46,8 +46,8 @@ const address = computeZkLoginAddress({
 });
 ```
 
-To use zkLogin inside a multisig, see the [Multisig Guide](../sui/cryptography/multisig) for more
-details.
+To use zkLogin inside a multisig, see the [Multisig Guide](../sui/cryptography/signers/multisig) for
+more details.
 
 ## Legacy addresses
 

package/package.json

@@ -3,7 +3,7 @@
   "author": "Mysten Labs <build@mystenlabs.com>",
   "description": "Sui TypeScript API",
   "homepage": "https://sdk.mystenlabs.com",
-  "version": "2.20.0",
+  "version": "2.20.1",
   "license": "Apache-2.0",
   "sideEffects": false,
   "files": [

package/src/transactions/intents/CoinWithBalance.ts

@@ -2,7 +2,19 @@
 // SPDX-License-Identifier: Apache-2.0
 
 import type { InferInput } from 'valibot';
-import { bigint, object, optional, parse, picklist, string } from 'valibot';
+import {
+	bigint,
+	integer,
+	number,
+	object,
+	optional,
+	parse,
+	picklist,
+	pipe,
+	string,
+	transform,
+	union,
+} from 'valibot';
 
 import { bcs } from '../../bcs/index.js';
 import { normalizeStructTag } from '../../utils/sui-types.js';
@@ -87,9 +99,15 @@ export function createBalance({
 	};
 }
 
+// `balance` is a bigint in memory, but serializing a transaction to JSON converts it to a
+// string. When that JSON is deserialized with `Transaction.from`, the value stays a string
+// (the intent `data` is opaque to the transaction schema), so coerce it back to a bigint here.
 const CoinWithBalanceData = object({
 	type: string(),
-	balance: bigint(),
+	balance: pipe(
+		union([bigint(), string(), pipe(number(), integer())]),
+		transform((value) => BigInt(value)),
+	),
 	outputKind: optional(picklist(['coin', 'balance'])),
 });
 
@@ -208,10 +226,7 @@ export async function resolveCoinBalance(
 			continue;
 		}
 
-		const { type, balance } = transaction.$Intent.data as {
-			type: string;
-			balance: bigint;
-		};
+		const { type, balance } = parse(CoinWithBalanceData, transaction.$Intent.data);
 		const coinType = type === 'gas' ? SUI_TYPE : type;
 		const totalRequired = totalByType.get(type)!;
 		const addressBalance = addressBalanceByType.get(type) ?? 0n;

package/src/version.ts

@@ -3,4 +3,4 @@
 
 // This file is generated by genversion.mjs. Do not edit it directly.
 
-export const PACKAGE_VERSION = '2.20.0';
+export const PACKAGE_VERSION = '2.20.1';