Rewrite transaction docs for address balances and tx.coin/tx.balance by hayes-mysten · Pull Request #897 · MystenLabs/ts-sdks

hayes-mysten · 2026-02-25T22:20:57Z

Description

Rewrites the transaction documentation to cover the new address balance system and the tx.coin()/tx.balance() APIs added in #963.

Changes

New documentation section: transactions/ — replaces the old transaction-building/ directory with a reorganized set of pages:

basics.mdx — Building transactions from scratch: creating transactions, sending SUI/tokens, Move calls, codegen, chaining commands, batch transfers, thunks, serialization
coins-and-balances.mdx — Dedicated page for the coin/balance dual system: tx.coin(), tx.balance(), coinWithBalance, resolution paths (Path 1: all-balance direct withdrawal, Path 2: merge-and-split), manual coin operations, address balance withdrawals/deposits, getBalance/listCoins
signing-and-execution.mdx — Simulation, keypair signing, dApp Kit hooks, manual execution, result observation, waitForTransaction, gas configuration (defaults, explicit settings, address balance gas, tx.gas), sponsored transactions (coin-based and address-balance flows)
reference.mdx — Complete reference for all commands (splitCoins, mergeCoins, transferObjects, moveCall, makeMoveVec, publish, upgrade) and input types (pure values, vectors/options, BCS, object references, object helpers, withdrawals)
offline.mdx — Offline building with shared/party objects and address balances, owned object inputs, expiration configuration, serialization

Other doc updates:

Removes old transaction-building/ pages (basics, gas, sponsored-transactions, offline, intents)
Updates sui/meta.json to point to new transactions section, removes pages that no longer exist (install, llm-docs, hello-sui, faucet)
Minor fixes to other package docs (dapp-kit, bcs, zksend, kiosk, codegen index pages)

Test plan

Verified docs build with pnpm --filter @mysten/docs build
Reviewed all code examples for accuracy against the current tx.coin()/tx.balance() API and resolver implementation
Checked cross-links between pages

AI Assistance Notice

Please disclose the usage of AI. This is primarily to help inform reviewers of how careful they need to review PRs, and to keep track of AI usage across our team. Please fill this out accurately, and do not modify the content or heading for this section!

This PR was primarily written by AI.
I used AI for docs / tests, but manually wrote the source code.
I used AI to understand the problem space / repository.
I did not use AI for this PR.

vercel · 2026-02-25T22:21:01Z

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Actions	Updated (UTC)
sui-typescript-docs	Ready	Preview, Comment	Apr 10, 2026 6:18pm

github-actions · 2026-02-25T22:21:50Z

⚠️ 🦋 Changesets Warning: This PR has changes to public npm packages, but does not contain a changeset. You can create a changeset easily by running pnpm changeset in the root of the Sui repo, and following the prompts. If your change does not need a changeset (e.g. a documentation-only change), you can ignore this message. This warning will be removed when a changeset is added to this pull request.

Learn more about Changesets.

hayes-mysten · 2026-02-25T22:49:27Z

+Run it:
+
+```sh
+node balance.js


we should probably use ts for our examples

hayes-mysten · 2026-03-28T05:22:33Z

@jessiemongeon1 this PR rewrites a big chunk of the docs to be more inline with how we want people to create transactions and updates everything to use address balances (where appropriate)

jessiemongeon1

Reviewed for style guide compliance, page structure/IA will be addressed in the docs audit we do in a few weeks

jessiemongeon1 · 2026-04-10T14:52:43Z

+Every interaction with the Sui network goes through a transaction. Sui transactions are
+[programmable transaction blocks (PTBs)](https://docs.sui.io/guides/developer/transactions/prog-txn-blocks)
+— a sequence of commands that execute on inputs to produce a result. Commands within a transaction
+can call Move functions, transfer objects, split and merge coins, and more. You can chain the result
+of one command into a subsequent command, composing complex operations in a single transaction.
+
+All commands in a transaction execute atomically: if any command fails, the entire transaction is
+rolled back and none of its effects are applied.


Suggested change

Every interaction with the Sui network goes through a transaction. Sui transactions are

[programmable transaction blocks (PTBs)](https://docs.sui.io/guides/developer/transactions/prog-txn-blocks)

— a sequence of commands that execute on inputs to produce a result. Commands within a transaction

can call Move functions, transfer objects, split and merge coins, and more. You can chain the result

of one command into a subsequent command, composing complex operations in a single transaction.

All commands in a transaction execute atomically: if any command fails, the entire transaction is

rolled back and none of its effects are applied.

Every interaction with the Sui network goes through a transaction. Sui transactions are a sequence of commands called [programmable transaction blocks (PTBs)](https://docs.sui.io/guides/developer/transactions/prog-txn-blocks) that execute on inputs to produce a result. Commands within a transaction can call Move functions, transfer objects, split and merge coins, and more. You can chain the result

of one command into a subsequent command, composing complex operations in a single transaction.

All commands in a transaction execute atomically. If any command fails, the entire transaction is

rolled back and none of its effects are applied.

jessiemongeon1 · 2026-04-10T14:53:00Z

+All commands in a transaction execute atomically: if any command fails, the entire transaction is
+rolled back and none of its effects are applied.
+
+For a deeper look at the transaction model, see the


Suggested change

For a deeper look at the transaction model, see the

For more information on transaction model, see the

jessiemongeon1 · 2026-04-10T14:53:21Z

+
+## Sending SUI
+
+The preferred way to send SUI is with `tx.balance()` and `balance::send_funds`, which deposits


Suggested change

The preferred way to send SUI is with `tx.balance()` and `balance::send_funds`, which deposits

It is recommended to send SUI is with `tx.balance()` and `balance::send_funds`, which deposits

jessiemongeon1 · 2026-04-10T14:53:37Z

+tx.transferObjects([tx.coin({ balance: 1n * MIST_PER_SUI })], '0xRecipientAddress');
+```
+
+Both `tx.balance()` and `tx.coin()` automatically draw from your coin objects and address balances —


Suggested change

Both `tx.balance()` and `tx.coin()` automatically draw from your coin objects and address balances —

Both `tx.balance()` and `tx.coin()` automatically draw from your coin objects and address balances.

jessiemongeon1 · 2026-04-10T14:53:47Z

+```
+
+Both `tx.balance()` and `tx.coin()` automatically draw from your coin objects and address balances —
+you don't need to manage individual coins yourself. See [Coins and Balances](./coins-and-balances)


Suggested change

you don't need to manage individual coins yourself. See [Coins and Balances](./coins-and-balances)

You don't need to manage individual coins yourself. See [Coins and Balances](./coins-and-balances)

jessiemongeon1 · 2026-04-10T15:33:53Z

+
+## Sign without executing
+
+Sometimes you need the signature without immediately executing — for multi-sig, sponsored


Suggested change

Sometimes you need the signature without immediately executing — for multi-sig, sponsored

Sometimes you need the signature without immediately executing, such as for multi-sig, sponsored

jessiemongeon1 · 2026-04-10T15:34:16Z

+| Field            | Description                                         |
+| ---------------- | --------------------------------------------------- |
+| `transaction`    | The full transaction data (sender, commands, gas)   |
+| `effects`        | Execution effects (created/mutated/deleted objects) |


jessiemongeon1 · 2026-04-10T15:34:25Z

+
+### Checking success or failure
+
+Every transaction result is a discriminated union — always check which variant you received:


Suggested change

Every transaction result is a discriminated union — always check which variant you received:

Every transaction result is a discriminated union. Always check which variant you received:

jessiemongeon1 · 2026-04-10T15:34:45Z

+
+## Gas configuration
+
+Every Sui transaction costs gas. The SDK handles gas automatically in most cases — it sets the gas


Suggested change

Every Sui transaction costs gas. The SDK handles gas automatically in most cases — it sets the gas

Every Sui transaction costs gas. The SDK handles gas automatically in most cases. It sets the gas

jessiemongeon1 · 2026-04-10T15:35:03Z

+1. **Gas price** — uses the network's reference gas price
+2. **Gas budget** — simulates the transaction and uses the result to set an appropriate budget
+3. **Gas payment** — uses address balances, falling back to coin objects when the balance is below


Suggested change

1. **Gas price** — uses the network's reference gas price

2. **Gas budget** — simulates the transaction and uses the result to set an appropriate budget

3. **Gas payment** — uses address balances, falling back to coin objects when the balance is below

1. **Gas price**: Uses the network's reference gas price

2. **Gas budget**: Simulates the transaction and uses the result to set an appropriate budget

3. **Gas payment**: Uses address balances, falling back to coin objects when the balance is below

jessiemongeon1

Reviewed for style guide compliance, page structure/IA will be addressed in the docs audit we do in a few weeks

Move docs to new directory structure. Content rewrite follows in next commit. - basics.mdx → transactions/basics.mdx - offline.mdx → transactions/offline.mdx - intents.mdx → transactions/coins-and-balances.mdx - gas.mdx → transactions/signing-and-execution.mdx - _meta.json → transactions/meta.json - Delete sponsored-transactions.mdx (merged into signing-and-execution.mdx) Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

Rewrite all transaction documentation to cover address balances, tx.coin(), tx.balance(), and the new intent resolution system. - basics.mdx: Use tx.coin() as primary API, add codegen, thunks, serialization - coins-and-balances.mdx: Full rewrite covering dual coin/balance system, resolution paths, tx.withdrawal(), manual operations, getBalance/listCoins - signing-and-execution.mdx: Full rewrite covering simulation, keypair signing, dApp Kit, sponsored transactions (coin-based and address-balance flows), gas configuration, waitForTransaction - reference.mdx: New comprehensive command and input reference - offline.mdx: Rewrite for address balance workflows, party objects, expiration - Update other doc pages for consistency (dapp-kit, bcs, kiosk, etc.) Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

…t test - Add gasless transactions section to coins-and-balances docs aligned with Sui docs PR language and linking to upstream guides - Update sui-tools Docker image to 53de0108 (latest with arm64 support) - Fix grpc-transport e2e test to dynamically import optional native gRPC dependencies so the file loads and skips gracefully when not installed Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

- Add internal link and anchor validation to docs validation script - Add `test` script to docs package so validation runs in CI - Fix broken links: - kiosk managing.mdx: anchor → page link for kiosk-transaction - kiosk purchasing.mdx: fix anchor slug for introduction heading - migrations/0.38.mdx: fix anchor slug (#module-packages → #module-structure) - migrations/sui-1.0.mdx: fix link to removed intents page Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

hayes-mysten requested a review from a team as a code owner February 25, 2026 22:20

hayes-mysten temporarily deployed to sui-typescript-aws-kms-test-env February 25, 2026 22:21 — with GitHub Actions Inactive

hayes-mysten commented Feb 25, 2026

View reviewed changes

Comment thread packages/bcs/README.md

hayes-mysten commented Feb 25, 2026

View reviewed changes

Comment thread packages/docs/content/sui/clients/core.mdx Outdated

vercel Bot deployed to Preview February 25, 2026 22:23 View deployment

hayes-mysten force-pushed the mh--address-balance-docs branch from 42a9624 to bbdd6b6 Compare February 25, 2026 22:36

hayes-mysten had a problem deploying to sui-typescript-aws-kms-test-env February 25, 2026 22:36 — with GitHub Actions Failure

hayes-mysten force-pushed the mh--address-balance-docs branch from bbdd6b6 to a88a4e8 Compare February 25, 2026 22:36

hayes-mysten had a problem deploying to sui-typescript-aws-kms-test-env February 25, 2026 22:36 — with GitHub Actions Failure

hayes-mysten force-pushed the mh--address-balance-docs branch from a88a4e8 to 680b84a Compare February 25, 2026 22:37

hayes-mysten had a problem deploying to sui-typescript-aws-kms-test-env February 25, 2026 22:37 — with GitHub Actions Failure

vercel Bot deployed to Preview February 25, 2026 22:41 View deployment

hayes-mysten force-pushed the mh--address-balance-docs branch from 680b84a to d99280b Compare February 25, 2026 22:48

hayes-mysten had a problem deploying to sui-typescript-aws-kms-test-env February 25, 2026 22:48 — with GitHub Actions Failure

hayes-mysten commented Feb 25, 2026

View reviewed changes

vercel Bot deployed to Preview February 25, 2026 22:50 View deployment

hayes-mysten force-pushed the mh--address-balance-docs branch from d99280b to cf957a1 Compare February 25, 2026 23:27

hayes-mysten had a problem deploying to sui-typescript-aws-kms-test-env February 25, 2026 23:27 — with GitHub Actions Failure

vercel Bot deployed to Preview February 25, 2026 23:29 View deployment

hayes-mysten force-pushed the mh--address-balance-docs branch from cf957a1 to 25b1d80 Compare February 26, 2026 07:38

hayes-mysten had a problem deploying to sui-typescript-aws-kms-test-env February 26, 2026 07:38 — with GitHub Actions Failure

vercel Bot deployed to Preview February 26, 2026 07:39 View deployment

hayes-mysten temporarily deployed to sui-typescript-aws-kms-test-env March 2, 2026 18:51 — with GitHub Actions Inactive

vercel Bot deployed to Preview March 2, 2026 18:53 View deployment

hayes-mysten changed the base branch from main to mh/coin-balance-intent-rewrite March 28, 2026 04:12

hayes-mysten closed this Mar 28, 2026

hayes-mysten force-pushed the mh--address-balance-docs branch from 32545fb to 50dcbbc Compare March 28, 2026 04:17

hayes-mysten reopened this Mar 28, 2026

hayes-mysten force-pushed the mh--address-balance-docs branch from 221c623 to 120e526 Compare March 28, 2026 05:02

hayes-mysten temporarily deployed to sui-typescript-aws-kms-test-env March 28, 2026 05:02 — with GitHub Actions Inactive

vercel Bot deployed to Preview March 28, 2026 05:03 View deployment

hayes-mysten force-pushed the mh--address-balance-docs branch from 120e526 to 2f73513 Compare March 28, 2026 05:07

hayes-mysten temporarily deployed to sui-typescript-aws-kms-test-env March 28, 2026 05:07 — with GitHub Actions Inactive

vercel Bot deployed to Preview March 28, 2026 05:10 View deployment

hayes-mysten force-pushed the mh--address-balance-docs branch from 2f73513 to 9328cc4 Compare March 28, 2026 05:15

hayes-mysten temporarily deployed to sui-typescript-aws-kms-test-env March 28, 2026 05:15 — with GitHub Actions Inactive

hayes-mysten force-pushed the mh--address-balance-docs branch from 9328cc4 to 5fd1d81 Compare March 28, 2026 05:18

hayes-mysten temporarily deployed to sui-typescript-aws-kms-test-env March 28, 2026 05:18 — with GitHub Actions Inactive

hayes-mysten force-pushed the mh--address-balance-docs branch from 5fd1d81 to 7b1b356 Compare March 28, 2026 05:18

hayes-mysten temporarily deployed to sui-typescript-aws-kms-test-env March 28, 2026 05:19 — with GitHub Actions Inactive

vercel Bot deployed to Preview March 28, 2026 05:24 View deployment

hayes-mysten force-pushed the mh--address-balance-docs branch from 7b1b356 to 4caa6c6 Compare April 8, 2026 20:24

hayes-mysten temporarily deployed to sui-typescript-aws-kms-test-env April 8, 2026 20:24 — with GitHub Actions Inactive

hayes-mysten requested a review from jessiemongeon1 April 8, 2026 20:25

vercel Bot deployed to Preview April 8, 2026 20:28 View deployment

hayes-mysten temporarily deployed to sui-typescript-aws-kms-test-env April 8, 2026 21:40 — with GitHub Actions Inactive

hayes-mysten force-pushed the mh--address-balance-docs branch from f893b9d to 4b43ed4 Compare April 8, 2026 21:43

hayes-mysten temporarily deployed to sui-typescript-aws-kms-test-env April 8, 2026 21:43 — with GitHub Actions Inactive

vercel Bot deployed to Preview April 8, 2026 21:46 View deployment

jessiemongeon1 approved these changes Apr 10, 2026

View reviewed changes

hayes-mysten and others added 4 commits April 10, 2026 11:07

hayes-mysten force-pushed the mh--address-balance-docs branch from 4b43ed4 to 857cd21 Compare April 10, 2026 18:15

hayes-mysten temporarily deployed to sui-typescript-aws-kms-test-env April 10, 2026 18:15 — with GitHub Actions Inactive

	For a deeper look at the transaction model, see the
	For more information on transaction model, see the


		## Sending SUI

		The preferred way to send SUI is with `tx.balance()` and `balance::send_funds`, which deposits

	The preferred way to send SUI is with `tx.balance()` and `balance::send_funds`, which deposits
	It is recommended to send SUI is with `tx.balance()` and `balance::send_funds`, which deposits

	Both `tx.balance()` and `tx.coin()` automatically draw from your coin objects and address balances —
	Both `tx.balance()` and `tx.coin()` automatically draw from your coin objects and address balances.

	you don't need to manage individual coins yourself. See [Coins and Balances](./coins-and-balances)
	You don't need to manage individual coins yourself. See [Coins and Balances](./coins-and-balances)


		## Sign without executing

		Sometimes you need the signature without immediately executing — for multi-sig, sponsored

	\| `effects` \| Execution effects (created/mutated/deleted objects) \|
	\| `effects` \| Execution effects (created, mutated, or deleted objects) \|


		### Checking success or failure

		Every transaction result is a discriminated union — always check which variant you received:


		## Gas configuration

		Every Sui transaction costs gas. The SDK handles gas automatically in most cases — it sets the gas

Conversation

hayes-mysten commented Feb 25, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Description

Changes

Test plan

AI Assistance Notice

Uh oh!

vercel Bot commented Feb 25, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Uh oh!

github-actions Bot commented Feb 25, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

hayes-mysten commented Mar 28, 2026

Uh oh!

jessiemongeon1 left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

jessiemongeon1 left a comment

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

hayes-mysten commented Feb 25, 2026 •

edited

Loading

vercel Bot commented Feb 25, 2026 •

edited

Loading

github-actions Bot commented Feb 25, 2026 •

edited

Loading