@mysten/docs 0.1.40 → 0.1.43

package/dist/sui/clients/core.md

@@ -439,6 +439,115 @@ const finalResult = await client.core.waitForTransaction({
 });
 ```
 
+## Query methods
+
+Query methods return pages of transactions or events. They expose the same filters, pagination, and
+results on every transport, and share a common set of options. A few transport-specific caveats
+(page-size caps, gRPC scan-limited pages, generic event types and missing event checkpoints on the
+deprecated JSON-RPC transport, and GraphQL's per-transaction event limit) are documented on the
+corresponding option and response types in `SuiClientTypes`.
+
+| Option   | Type                               | Description                                           |
+| -------- | ---------------------------------- | ----------------------------------------------------- |
+| `filter` | `TransactionFilter \| EventFilter` | Filter to apply (transactions and events)             |
+| `limit`  | `number`                           | Maximum number of items to return (defaults to 50)    |
+| `after`  | `string \| null`                   | Return items strictly after this cursor (ascending)   |
+| `before` | `string \| null`                   | Return items strictly before this cursor (descending) |
+| `order`  | `'ascending' \| 'descending'`      | Order of results (defaults to `ascending`)            |
+
+A filter specifies exactly one predicate. MVR names in `function` and `eventType` predicates are
+resolved automatically.
+
+`after` and `before` are exclusive ledger-position bounds, and each page reports the positions of
+its first and last items as `startCursor` and `endCursor`. You can provide at most one bound per
+query, and the bound implies the traversal direction (`after` reads ascending, `before` reads
+descending), so a feed of recent activity can page in both directions from any point:
+
+```typescript
+// Fetch the most recent transactions
+const latest = await client.core.listTransactions({
+	filter: { sender: '0xabc...' },
+	order: 'descending',
+	limit: 10,
+});
+
+// Load older transactions
+const older = await client.core.listTransactions({
+	filter: { sender: '0xabc...' },
+	before: latest.endCursor,
+	limit: 10,
+});
+
+// Poll for transactions executed since
+const newer = await client.core.listTransactions({
+	filter: { sender: '0xabc...' },
+	after: latest.startCursor,
+});
+```
+
+> **Note:** Richer filtering (combined predicates, additional predicates like affected addresses and objects,
+> and checkpoint ranges on transaction and event queries) is available through the [raw gRPC ledger
+> service](/sui/clients/grpc#ledger-service) and [raw GraphQL queries](/sui/clients/graphql).
+
+### `listTransactions`
+
+Query transactions matching a filter. Results support the same `include` options as
+[`getTransaction`](#gettransaction).
+
+```typescript
+const result = await client.core.listTransactions({
+	filter: { function: '0x2::coin::transfer' },
+	limit: 10,
+	include: { effects: true },
+});
+
+for (const tx of result.transactions) {
+	const transaction = tx.Transaction ?? tx.FailedTransaction;
+	console.log(transaction.digest, tx.$kind);
+}
+
+// Paginate
+if (result.hasNextPage) {
+	const nextPage = await client.core.listTransactions({
+		filter: { function: '0x2::coin::transfer' },
+		after: result.endCursor,
+	});
+}
+```
+
+Transaction filters support one of the following predicates:
+
+| Predicate  | Description                                                                 |
+| ---------- | --------------------------------------------------------------------------- |
+| `sender`   | Transactions sent by an address                                             |
+| `function` | Transactions calling a Move function (`pkg`, `pkg::mod`, or `pkg::mod::fn`) |
+
+### `listEvents`
+
+Query events matching a filter. Each event includes its position in the ledger (`transactionDigest`
+and `eventIndex`, plus `checkpoint` on transports that can provide it; `checkpoint` is `null` on
+JSON-RPC).
+
+```typescript
+const result = await client.core.listEvents({
+	filter: { eventType: '0x2::coin::CoinCreated' },
+	order: 'descending',
+	limit: 10,
+});
+
+for (const event of result.events) {
+	console.log(event.eventType, event.transactionDigest, event.json);
+}
+```
+
+Event filters support one of the following predicates:
+
+| Predicate    | Description                                                                       |
+| ------------ | --------------------------------------------------------------------------------- |
+| `sender`     | Events from transactions sent by an address                                       |
+| `emitModule` | Events emitted by a module (`pkg::mod`)                                           |
+| `eventType`  | Events with types defined in a module (`pkg::mod`) or a fully qualified type name |
+
 ## System methods
 
 ### `getReferenceGasPrice`
@@ -591,6 +700,9 @@ const options: SuiClientTypes.GetObjectOptions<{ content: true }> = {
 | `TransactionResult`    | Success or failure result from execution    |
 | `TransactionEffects`   | Detailed effects from transaction execution |
 | `Event`                | Emitted event from a transaction            |
+| `EventEntry`           | Queried event with its ledger position      |
+| `TransactionFilter`    | Filter for transaction queries              |
+| `EventFilter`          | Filter for event queries                    |
 | `ObjectOwner`          | Union of all owner types                    |
 | `ExecutionStatus`      | Success/failure status with error details   |
 | `DynamicFieldName`     | Name identifier for dynamic fields          |
@@ -620,4 +732,6 @@ const options: SuiClientTypes.GetObjectOptions<{ content: true }> = {
 | `SimulateTransactionOptions`       | Options for `simulateTransaction`       |
 | `SignAndExecuteTransactionOptions` | Options for `signAndExecuteTransaction` |
 | `GetTransactionOptions`            | Options for `getTransaction`            |
-| `WaitForTransactionOptions`        | Options for `waitForTransaction`        |
+| `WaitForTransactionOptions`        | Options for `waitForTransaction`        |
+| `ListTransactionsOptions`          | Options for `listTransactions`          |
+| `ListEventsOptions`                | Options for `listEvents`                |

package/dist/sui/clients/grpc.md

@@ -157,6 +157,74 @@ const { response } = await grpcClient.ledgerService.getTransaction({
 const { response: epochInfo } = await grpcClient.ledgerService.getEpoch({});
 ```
 
+The ledger service also provides streaming `listCheckpoints`, `listTransactions`, and `listEvents`
+RPCs. For most use cases, prefer the corresponding
+[core API query methods](/sui/clients/core#query-methods) (`listTransactions` and `listEvents`),
+which handle pagination and filter construction for you. The raw RPCs additionally support DNF
+filters (combined, negated, and additional predicates like `affected_address` and `package_write`)
+and checkpoint range bounds that the core API does not expose:
+
+```typescript
+// Transactions that affected an address but were not sent by it:
+const stream = grpcClient.ledgerService.listTransactions({
+	filter: {
+		terms: [
+			{
+				literals: [
+					{
+						negated: false,
+						predicate: {
+							oneofKind: 'affectedAddress',
+							affectedAddress: { address: '0xabc...' },
+						},
+					},
+					{
+						negated: true,
+						predicate: { oneofKind: 'sender', sender: { address: '0xabc...' } },
+					},
+				],
+			},
+		],
+	},
+	readMask: { paths: ['digest'] },
+});
+
+for await (const frame of stream.responses) {
+	if (frame.transaction) {
+		console.log(frame.transaction.digest);
+	}
+}
+```
+
+### Subscription service
+
+Subscribe to filtered, real-time streams of checkpoints, transactions, or events. Streams begin at
+the current tip of the chain:
+
+```typescript
+const stream = grpcClient.subscriptionService.subscribeTransactions({
+	filter: {
+		terms: [
+			{
+				literals: [
+					{
+						negated: false,
+						predicate: { oneofKind: 'sender', sender: { address: '0xabc...' } },
+					},
+				],
+			},
+		],
+	},
+	readMask: { paths: ['digest', 'effects.status'] },
+});
+
+for await (const frame of stream.responses) {
+	if (frame.transaction) {
+		console.log(frame.transaction.digest);
+	}
+}
+```
+
 ### State service
 
 ```typescript

package/dist/sui/migrations/sui-2.0/json-rpc-migration.md

@@ -5,15 +5,16 @@
 This guide covers migrating from `SuiJsonRpcClient` to the new client APIs. The JSON-RPC API is
 being deprecated in favor of `SuiGrpcClient` and `SuiGraphQLClient`.
 
-> **Note:** We recommend using `SuiGrpcClient` for most operations and `SuiGraphQLClient` for complex queries
-> like filtering transactions and events.
+> **Note:** Use `SuiGrpcClient` for most operations, including filtering transactions and events with the core
+> query API. `SuiGraphQLClient` remains useful for complex queries that aren't covered by the core
+> API.
 
 ## Choosing a client
 
-| Client             | Best For                                                        |
-| ------------------ | --------------------------------------------------------------- |
-| `SuiGrpcClient`    | Most operations, SDK integrations, real-time data               |
-| `SuiGraphQLClient` | Complex queries, filtering transactions/events, historical data |
+| Client             | Best For                                                             |
+| ------------------ | -------------------------------------------------------------------- |
+| `SuiGrpcClient`    | Most operations, SDK integrations, queries, real-time data           |
+| `SuiGraphQLClient` | Complex queries not covered by the core API, like historical objects |
 
 ## Quick migration to gRPC
 
@@ -58,6 +59,58 @@ These JSON-RPC methods have direct replacements in the core API:
 | `dryRunTransactionBlock`     | `simulateTransaction`                             |
 | `getNormalizedMoveFunction`  | `getMoveFunction`                                 |
 | `getMoveFunctionArgTypes`    | `getMoveFunction`                                 |
+| `queryTransactionBlocks`     | `listTransactions`                                |
+| `queryEvents`                | `listEvents`                                      |
+
+> **Note:** The query methods (`listTransactions` and `listEvents`) behave identically on every client,
+> including `SuiJsonRpcClient`. See [Core API query methods](/sui/clients/core#query-methods) for
+> details.
+
+### Example: Migrating queryTransactionBlocks
+
+```diff
+- const result = await jsonRpcClient.queryTransactionBlocks({
+-   filter: { FromAddress: '0xabc...' },
+-   options: { showEffects: true },
+-   limit: 10,
+- });
+- const digests = result.data.map((tx) => tx.digest);
++ const result = await client.core.listTransactions({
++   filter: { sender: '0xabc...' },
++   include: { effects: true },
++   limit: 10,
++ });
++ const digests = result.transactions.map(
++   (tx) => (tx.Transaction ?? tx.FailedTransaction).digest,
++ );
+```
+
+The core API filters map to the JSON-RPC `TransactionFilter` variants:
+
+| JSON-RPC filter                                                      | Core API filter predicate                                                                                       |
+| -------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------- |
+| `FromAddress`                                                        | `sender`                                                                                                        |
+| `MoveFunction`                                                       | `function`                                                                                                      |
+| `ToAddress` / `FromOrToAddress` / `ChangedObject` / `AffectedObject` | No core equivalent. Use raw [gRPC](/sui/clients/grpc#ledger-service) or [GraphQL](/sui/clients/graphql) queries |
+
+### Example: Migrating queryEvents
+
+```diff
+- const result = await jsonRpcClient.queryEvents({
+-   query: { MoveEventType: '0x2::coin::CoinCreated' },
+-   limit: 10,
+-   order: 'descending',
+- });
++ const result = await client.core.listEvents({
++   filter: { eventType: '0x2::coin::CoinCreated' },
++   limit: 10,
++   order: 'descending',
++ });
+```
+
+The JSON-RPC `EventFilter` variants map to `sender`, `emitModule` (replaces `MoveModule` /
+`MoveEventModule`), and `eventType` (replaces `MoveEventType`). Each returned event includes its
+ledger position (`checkpoint`, `transactionDigest`, and `eventIndex`).
 
 ### Example: Migrating devInspectTransactionBlock
 
@@ -95,6 +148,7 @@ These JSON-RPC methods can be replaced by calling gRPC service clients directly:
 | JSON-RPC Method                     | gRPC Service Replacement                                         |
 | ----------------------------------- | ---------------------------------------------------------------- |
 | `getCheckpoint`                     | `ledgerService.getCheckpoint`                                    |
+| `getCheckpoints`                    | `ledgerService.listCheckpoints`                                  |
 | `getLatestCheckpointSequenceNumber` | `ledgerService.getServiceInfo` (read `checkpointHeight`)         |
 | `getCurrentEpoch`                   | `ledgerService.getEpoch` (omit `epoch` for the current)          |
 | `getLatestSuiSystemState`           | `ledgerService.getEpoch` with `system_state` in the read mask    |
@@ -108,10 +162,10 @@ These JSON-RPC methods can be replaced by calling gRPC service clients directly:
 | `resolveNameServiceAddress`         | `nameService.lookupName`                                         |
 | `resolveNameServiceNames`           | `nameService.reverseLookupName`                                  |
 
-> **Warning:** `getCheckpoints` and `getEpochs` (paginated listings) have no gRPC equivalent — use the
-> `checkpoints` / `epochs` GraphQL queries instead. `getValidatorsApy` also has no replacement:
-> there is no canonical definition of validator APY, so it must be computed client-side from
-> validator exchange rates (see [Validator APY](#validator-apy) below).
+> **Warning:** `getEpochs` (paginated listing) has no gRPC equivalent. Use the `epochs` GraphQL query instead.
+> `getValidatorsApy` also has no replacement: there is no canonical definition of validator APY, so
+> it must be computed client-side from validator exchange rates (see [Validator APY](#validator-apy)
+> below).
 
 ### Example: using gRPC service clients
 
@@ -167,16 +221,53 @@ const { response: address } = await client.nameService.lookupName({
 });
 ```
 
+## Methods replaced by gRPC subscriptions
+
+Replace the deprecated JSON-RPC websocket subscriptions with the gRPC `subscriptionService`, which
+provides filtered, real-time streams:
+
+| JSON-RPC Method        | gRPC Service Replacement                    |
+| ---------------------- | ------------------------------------------- |
+| `subscribeTransaction` | `subscriptionService.subscribeTransactions` |
+| `subscribeEvent`       | `subscriptionService.subscribeEvents`       |
+
+```typescript
+const stream = client.subscriptionService.subscribeEvents({
+	filter: {
+		terms: [
+			{
+				literals: [
+					{
+						negated: false,
+						predicate: {
+							oneofKind: 'eventType',
+							eventType: { eventType: '0x2::coin::CoinCreated' },
+						},
+					},
+				],
+			},
+		],
+	},
+	readMask: { paths: ['event_type', 'contents', 'json', 'checkpoint', 'transaction_digest'] },
+});
+
+for await (const frame of stream.responses) {
+	if (frame.event) {
+		console.log(frame.event.eventType, frame.event.json);
+	}
+}
+```
+
+Subscriptions always begin at the current tip of the chain. To recover events you missed between
+subscriptions, replay the gap with `client.core.listEvents` using the same filter.
+
 ## Methods requiring GraphQL
 
 Some JSON-RPC methods don't have gRPC equivalents and require using `SuiGraphQLClient` instead:
 
 | JSON-RPC Method             | GraphQL Alternative                                       |
 | --------------------------- | --------------------------------------------------------- |
-| `queryTransactionBlocks`    | `transactions` query                                      |
 | `multiGetTransactionBlocks` | `multiGetTransactionEffects` query                        |
-| `queryEvents`               | `events` query                                            |
-| `getCheckpoints`            | `checkpoints` query                                       |
 | `getEpochs`                 | `epochs` query                                            |
 | `getCoinMetadata`           | `coinMetadata` query (or gRPC `stateService.getCoinInfo`) |
 | `getTotalSupply`            | `coinMetadata` query (or gRPC `stateService.getCoinInfo`) |
@@ -197,94 +288,6 @@ const graphqlClient = new SuiGraphQLClient({
 });
 ```
 
-### Querying transactions
-
-Replace `queryTransactionBlocks` with a GraphQL query:
-
-```typescript
-const result = await graphqlClient.query({
-	query: `
-    query QueryTransactions($sender: SuiAddress, $first: Int, $after: String) {
-      transactions(
-        first: $first
-        after: $after
-        filter: { sentAddress: $sender }
-      ) {
-        pageInfo {
-          hasNextPage
-          endCursor
-        }
-        nodes {
-          digest
-          effects {
-            status
-            epoch { epochId }
-          }
-        }
-      }
-    }
-  `,
-	variables: {
-		sender: '0xabc...',
-		first: 10,
-	},
-});
-```
-
-**Available transaction filters:**
-
-- `sentAddress`: Filter by sender address
-- `affectedAddress`: Filter by any address involved in the transaction
-- `affectedObject`: Filter by object ID that was affected
-- `function`: Filter by Move function called (for example, `0x2::coin::transfer`)
-- `kind`: Filter by transaction kind (`SYSTEM` or `PROGRAMMABLE`)
-- `atCheckpoint` / `beforeCheckpoint` / `afterCheckpoint` - Filter by checkpoint
-
-### Querying events
-
-Replace `queryEvents` with a GraphQL query:
-
-```typescript
-const result = await graphqlClient.query({
-	query: `
-    query QueryEvents($type: String, $first: Int, $after: String) {
-      events(
-        first: $first
-        after: $after
-        filter: { type: $type }
-      ) {
-        pageInfo {
-          hasNextPage
-          endCursor
-        }
-        nodes {
-          transactionModule {
-            package { address }
-            name
-          }
-          sender { address }
-          contents {
-            type { repr }
-            bcs
-          }
-        }
-      }
-    }
-  `,
-	variables: {
-		type: '0x2::coin::CoinCreated',
-		first: 10,
-	},
-});
-```
-
-**Available event filters:**
-
-- `type`: Filter by event type (package, package::module, or full type)
-- `module`: Filter by emitting module
-- `sender`: Filter by transaction sender
-- `atCheckpoint` / `beforeCheckpoint` / `afterCheckpoint`: Filter by checkpoint
-
 ### Fetching multiple transactions
 
 Replace `multiGetTransactionBlocks` with a GraphQL query:

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mysten/docs",
-  "version": "0.1.40",
+  "version": "0.1.43",
   "description": "LLM-friendly documentation for the Sui TypeScript SDK ecosystem",
   "license": "Apache-2.0",
   "repository": {
@@ -25,31 +25,31 @@
     "fumadocs-mdx": "15.0.12",
     "fumadocs-typescript": "^5.2.6",
     "fumadocs-ui": "16.10.2",
-    "next": "^16.2.9",
+    "next": "^16.2.12",
     "react": "^19.2.7",
     "react-dom": "^19.2.7",
-    "@mysten/aws-kms-signer": "0.3.6",
+    "@mysten/aws-kms-signer": "0.3.9",
     "@mysten/bcs": "2.1.0",
-    "@mysten/dapp-kit": "1.1.9",
-    "@mysten/dapp-kit-core": "1.6.9",
-    "@mysten/dapp-kit-react": "2.1.11",
-    "@mysten/enoki": "1.2.7",
-    "@mysten/deepbook-v3": "1.5.9",
-    "@mysten/enoki-connect": "1.1.9",
-    "@mysten/gcp-kms-signer": "0.2.9",
-    "@mysten/kiosk": "1.3.9",
-    "@mysten/ledger-signer": "0.2.9",
-    "@mysten/seal": "1.3.4",
-    "@mysten/signers": "1.1.9",
-    "@mysten/slush-wallet": "1.1.9",
-    "@mysten/sui": "2.22.1",
-    "@mysten/suins": "1.2.9",
-    "@mysten/wallet-standard": "0.21.9",
-    "@mysten/payment-kit": "0.2.9",
-    "@mysten/walrus": "1.2.9",
-    "@mysten/webcrypto-signer": "0.2.9",
+    "@mysten/dapp-kit-core": "1.6.12",
+    "@mysten/dapp-kit": "1.1.12",
+    "@mysten/dapp-kit-react": "2.1.14",
+    "@mysten/enoki-connect": "1.1.12",
+    "@mysten/deepbook-v3": "1.6.2",
+    "@mysten/kiosk": "1.3.12",
+    "@mysten/gcp-kms-signer": "0.2.12",
+    "@mysten/ledger-signer": "0.2.12",
+    "@mysten/enoki": "1.2.10",
+    "@mysten/seal": "1.3.7",
+    "@mysten/signers": "1.1.12",
+    "@mysten/slush-wallet": "1.1.12",
+    "@mysten/payment-kit": "0.2.12",
+    "@mysten/sui": "2.23.1",
+    "@mysten/suins": "1.2.12",
     "@mysten/utils": "0.4.0",
-    "@mysten/zksend": "1.2.9"
+    "@mysten/wallet-standard": "0.21.12",
+    "@mysten/webcrypto-signer": "0.2.12",
+    "@mysten/zksend": "1.2.12",
+    "@mysten/walrus": "1.2.12"
   },
   "devDependencies": {
     "@tailwindcss/postcss": "^4.3.1",
@@ -57,7 +57,7 @@
     "@types/node": "^25.9.3",
     "@types/react": "^19.2.17",
     "@types/react-dom": "^19.2.3",
-    "postcss": ">=8.5.10",
+    "postcss": "^8.5.23",
     "tailwindcss": "^4.3.1",
     "typedoc": "^0.28.19",
     "typedoc-plugin-mermaid": "^1.12.0",