@mysten/sui 2.24.0 → 2.25.0

package/docs/clients/executing.md

@@ -0,0 +1,113 @@
+# Executing Transactions
+
+> Simulate, execute, and wait for transactions with any Sui client
+
+Executing a transaction is a client operation, and every client exposes the same four methods for
+it. Building transactions is covered in [Building transactions](/sui/transactions/basics), and the
+ways to obtain a signature (keypairs, wallets, sponsorship) in
+[Signing and execution](/sui/transactions/signing-and-execution).
+
+## `signAndExecuteTransaction`
+
+Signs with the given signer and executes, in one call:
+
+```typescript
+
+const client = new SuiGrpcClient({
+	network: 'mainnet',
+	baseUrl: 'https://fullnode.mainnet.sui.io:443',
+});
+
+const result = await client.signAndExecuteTransaction({
+	transaction: tx,
+	signer: keypair,
+	include: { effects: true },
+});
+```
+
+The signer can be any `Signer`, such as a keypair or a KMS or Ledger signer. Pass
+`additionalSignatures` for transactions needing more than one, such as a sponsored transaction the
+sponsor has already signed.
+
+## `executeTransaction`
+
+When you already have signed bytes, execute them directly:
+
+```typescript
+const result = await client.executeTransaction({
+	transaction: bytes, // Uint8Array
+	signatures: [signature], // string[]
+	include: { effects: true, events: true },
+});
+```
+
+Both methods return a discriminated union rather than throwing on failure: a transaction that
+executed but aborted onchain comes back as `FailedTransaction`.
+
+```typescript
+const transaction = result.Transaction ?? result.FailedTransaction;
+
+console.log(transaction.digest, transaction.status.success);
+```
+
+A resolved promise means the network executed the transaction, which is not the same as it having
+succeeded. See
+[checking success or failure](/sui/transactions/signing-and-execution#checking-success-or-failure)
+for handling both outcomes.
+
+## Include options
+
+Execution, simulation, and [`getTransaction`](/sui/clients/querying#gettransaction) share one set of
+`include` options. Everything is off by default, and a field that you did not request is typed
+`undefined`:
+
+| Option           | Description                                                        |
+| ---------------- | ------------------------------------------------------------------ |
+| `effects`        | Execution effects: created, mutated, and deleted objects, gas used |
+| `events`         | Move events emitted during execution                               |
+| `transaction`    | The full transaction data (sender, gas config, inputs, commands)   |
+| `balanceChanges` | Balance changes for each affected address and coin type            |
+| `objectTypes`    | Map of object ID to type for all changed objects                   |
+| `bcs`            | Raw BCS-encoded transaction bytes                                  |
+
+## `waitForTransaction`
+
+Reads are served from indexed state, which trails execution slightly. Wait before reading a
+transaction's effects back, or before submitting a transaction that depends on objects it touched:
+
+```typescript
+const result = await client.signAndExecuteTransaction({ transaction: tx, signer: keypair });
+
+await client.waitForTransaction({ result });
+
+// Reads now reflect the transaction's effects
+const { balance } = await client.getBalance({ owner: myAddress });
+```
+
+It also accepts a `digest` instead of a result, along with `timeout` and a `pollSchedule` array of
+backoff delays.
+
+## `simulateTransaction`
+
+Dry-run a transaction without executing it, to estimate gas, inspect return values, or validate it
+before asking anyone to sign:
+
+```typescript
+const result = await client.simulateTransaction({
+	transaction: tx,
+	include: {
+		effects: true,
+		balanceChanges: true,
+		commandResults: true,
+	},
+});
+```
+
+Simulation takes the same include options plus `commandResults`, which returns each command's return
+values and mutated references as BCS-encoded bytes for you to decode with the [BCS library](/bcs).
+Two further options change how the node runs the simulation:
+
+| Option           | Effect                                                                                                                 |
+| ---------------- | ---------------------------------------------------------------------------------------------------------------------- |
+| `checksEnabled`  | Set `false` to skip transaction validation, so non-public and non-entry functions can be inspected. Defaults to `true` |
+| `doGasSelection` | Overrides whether the server selects gas payment during the simulation                                                 |

package/docs/clients/graphql.md

@@ -1,19 +1,10 @@
 # SuiGraphQLClient
 
-> Connect to Sui through GraphQL with SuiGraphQLClient
+> Connect to Sui over GraphQL and write type-safe custom queries
 
-The `SuiGraphQLClient` enables type-safe GraphQL queries against the Sui GraphQL API.
-
-For more details on the Sui GraphQL API, see the
-[GraphQL reference](https://docs.sui.io/references/sui-graphql).
-
-Use `SuiGraphQLClient` when an app needs indexed GraphQL data, historical queries, or custom
-selection sets that are not exposed by the gRPC top-level API.
-
-## Using top-level methods
-
-`SuiGraphQLClient` exposes top-level methods for the same common operations as the
-[Core API](/sui/clients/core). Use them directly in application code:
+`SuiGraphQLClient` talks to the Sui GraphQL API. It implements the same client API as
+`SuiGrpcClient`, so anything on [Querying data](/sui/clients/querying) and
+[Signing and execution](/sui/transactions/signing-and-execution) works here unchanged:
 
 ```typescript
 
@@ -26,70 +17,45 @@ const { object } = await client.getObject({
 	objectId: '0x...',
 	include: { content: true },
 });
-
-const txs = await client.listTransactions({
-	filter: { sender: '0x...' },
-	order: 'descending',
-	limit: 10,
-});
 ```
 
-The same methods are available through `client.core` when SDK code needs the transport-agnostic
-`ClientWithCoreApi` contract.
-
-Common top-level methods:
-
-| Category       | Methods                                                                                                           |
-| -------------- | ----------------------------------------------------------------------------------------------------------------- |
-| Objects        | `getObject`, `getObjects`, `listOwnedObjects`, `listDynamicFields`, `getDynamicField`                             |
-| Coins          | `listCoins`, `getBalance`, `listBalances`, `getCoinMetadata`                                                      |
-| Transactions   | `getTransaction`, `executeTransaction`, `signAndExecuteTransaction`, `waitForTransaction`                         |
-| Simulation     | `simulateTransaction`                                                                                             |
-| Queries        | `listTransactions`, `listEvents`                                                                                  |
-| Move and names | `getMoveFunction`, `resolveNameServiceAddress`, `defaultNameServiceName`, `mvr.resolvePackage`, `mvr.resolveType` |
-| Verification   | `verifyZkLoginSignature`                                                                                          |
+Beyond that shared surface, the client can run any query the schema supports, typed from the schema
+itself. The rest of this page covers writing those queries; see the
+[GraphQL reference](https://docs.sui.io/references/sui-graphql) for the schema.
 
-GraphQL-specific top-level options include `doGasSelection` on `simulateTransaction` and
-`include: { value: true }` on `listDynamicFields`.
+The constructor takes:
 
-## Custom GraphQL queries
+| Option    | Description                                                    |
+| --------- | -------------------------------------------------------------- |
+| `url`     | GraphQL endpoint                                               |
+| `network` | Network the endpoint serves, used for caching and MVR defaults |
+| `headers` | Extra headers sent with every request, such as an API key      |
+| `fetch`   | Custom `fetch` implementation                                  |
+| `queries` | Named documents callable through [`execute`](#named-queries)   |
+| `mvr`     | Move Registry overrides                                        |
 
-To query anything not in the top-level API, use the `query` method to execute custom GraphQL
-queries.
+## Writing queries
 
-We'll start by creating our client, and executing a very basic query:
+Use `query` to run any GraphQL document against the endpoint:
 
 ```typescript
 
-const gqlClient = new SuiGraphQLClient({
-	url: 'https://graphql.testnet.sui.io/graphql',
-	network: 'testnet',
-});
-
 const chainIdentifierQuery = graphql(`
 	query {
 		chainIdentifier
 	}
 `);
 
-async function getChainIdentifier() {
-	const result = await gqlClient.query({
-		query: chainIdentifierQuery,
-	});
+const result = await client.query({ query: chainIdentifierQuery });
 
-	return result.data?.chainIdentifier;
-}
+console.log(result.data?.chainIdentifier);
 ```
 
-## Type-safety for GraphQL queries
-
-You might have noticed the example above does not include any type definitions for the query. The
-`graphql` function used in the example is powered by [`gql.tada`](https://gql-tada.0no.co/) and will
-automatically provide the required type information to ensure that your queries are properly typed
-when executed through `SuiGraphQLClient`.
+### Type safety
 
-The `graphql` function detects variables used by your query, and will ensure that the variables
-passed to your query are properly typed.
+The `graphql` function is powered by [`gql.tada`](https://gql-tada.0no.co/), which types results and
+variables from the schema itself, with no code generation step and no hand-written result types.
+Fields you did not select are not on the result type, and variables are checked against the query:
 
 ```typescript
 const getSuinsName = graphql(`
@@ -103,24 +69,22 @@ const getSuinsName = graphql(`
 `);
 
 async function getDefaultSuinsName(address: string) {
-	const result = await gqlClient.query({
+	const result = await client.query({
 		query: getSuinsName,
-		variables: {
-			address,
-		},
+		variables: { address },
 	});
 
 	return result.data?.address?.defaultNameRecord?.domain;
 }
 ```
 
-## Using typed GraphQL queries with other GraphQL clients
+### Using typed documents with other clients
 
-The `graphql` function returns document nodes that implement the
-[`TypedDocumentNode`](https://github.com/dotansimha/graphql-typed-document-node) standard, and will
-work with the majority of popular GraphQL clients to provide queries that are automatically typed.
+The `graphql` function returns document nodes implementing the
+[`TypedDocumentNode`](https://github.com/dotansimha/graphql-typed-document-node) standard, so the
+same typed documents work with most GraphQL clients:
 
-```typescript
+```tsx
 
 const chainIdentifierQuery = graphql(`
 	query {
@@ -129,8 +93,54 @@ const chainIdentifierQuery = graphql(`
 `);
 
 function ChainIdentifier() {
-	const { loading, error, data } = useQuery(chainIdentifierQuery);
+	// Result types flow through the other client's own hooks and methods
+	const { data } = useQuery(chainIdentifierQuery);
 
-	return <div>{data?.chainIdentifier}</div>;
+	return <span>{data?.chainIdentifier}</span>;
 }
-```
+```
+
+### Handling errors
+
+`query` returns `{ data, errors }` rather than throwing on GraphQL errors, because a response can be
+partially successful, where some fields resolve and others fail. Check `errors` before trusting
+`data`:
+
+```typescript
+const { data, errors } = await client.query({ query: chainIdentifierQuery });
+
+if (errors?.length) {
+	throw new AggregateError(errors.map((error) => new Error(error.message)));
+}
+```
+
+A transport-level failure (a non-2xx response) throws `SuiGraphQLRequestError` instead.
+
+### Named queries
+
+Pass a `queries` map when constructing the client and call them by name with `execute`. This keeps
+query documents in one place instead of threading them through your call sites:
+
+```typescript
+const client = new SuiGraphQLClient({
+	url: 'https://graphql.mainnet.sui.io/graphql',
+	network: 'mainnet',
+	queries: {
+		getSuinsName,
+		chainIdentifier: chainIdentifierQuery,
+	},
+});
+
+const result = await client.execute('getSuinsName', {
+	variables: { address: '0xabc...' },
+});
+```
+
+Results and variables stay typed from the document the name resolves to.
+
+## Reading your own writes
+
+GraphQL reads an index that trails execution slightly, so a transaction `executeTransaction` has
+already returned might not appear in a query for a moment. Use
+[`waitForTransaction`](/sui/clients/executing#waitfortransaction) before reading back a
+transaction's effects.