# Fix Client Bug

> Fix bugs or add features in the @mysten/sui client layer (gRPC, JSON-RPC, GraphQL). Ensures all three transport implementations stay in sync.

- Skill: `mystenlabs/fix-client-bug` (Agent Skill)
- Install (CLI): `npx skillmds@latest add mystenlabs/fix-client-bug`
- Raw SKILL.md: https://api.skillmd.com/api/skills/mystenlabs/fix-client-bug/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Integrations & APIs
- Author: MystenLabs (https://skillmd.com/u/mystenlabs)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/mystenlabs/fix-client-bug

---


# Fix Client Bug / Add Client Feature

Use this workflow when making changes to Core API methods in `packages/sui/src/`. The key architectural constraint is that the three transport implementations (gRPC, JSON-RPC, GraphQL) must always produce identical results for the same Core API call.

## Phase 1: Read Before Writing

1. Identify the affected Core API method(s) in `packages/sui/src/client/core.ts`.
2. Read the shared return types in `packages/sui/src/client/types.ts`.
3. Read **all three** transport implementations of the method:
   - `packages/sui/src/grpc/core.ts`
   - `packages/sui/src/jsonRpc/core.ts`
   - `packages/sui/src/graphql/core.ts`
4. If the method is implemented in the abstract `CoreClient` (not abstract), check whether the bug is in the shared logic or in a method it delegates to.

Do not stop after reading one implementation. A bug in one transport very often exists in a different form in the others.

## Phase 2: Update Types

If the change affects the return type in `src/client/types.ts`:

- Follow the existing `$kind` discriminated union pattern for any polymorphic data. Search types.ts for `$kind` to see how `ObjectOwner`, `TransactionResult`, `ExecutionError`, etc. are structured.
- Extract named types for array items rather than using inline anonymous objects.
- Use explicit return type annotations in the mapping functions (e.g., `(item): SuiClientTypes.SomeType => { ... }`) to catch type mismatches at the implementation site.

## Phase 3: Update All Three Implementations

### gRPC (`src/grpc/core.ts`)

- Check the `readMask.paths` array — fields not listed here are not returned by the server.
- Reference proto types in `src/grpc/proto/` to discover available fields.

### GraphQL (`src/graphql/core.ts`)

- If new data is needed from the API, edit the `.graphql` query file in `src/graphql/queries/`.
- Regenerate types: `pnpm --filter @mysten/sui codegen:graphql`
- This updates `src/graphql/generated/queries.ts` with new typed document nodes.

### JSON-RPC (`src/jsonRpc/core.ts`)

- JSON-RPC response shapes often differ from unified types. Check what the RPC actually returns.
- Some data must be derived rather than mapped directly. Utilities in `src/utils/` (e.g., `deriveDynamicFieldID`, `normalizeStructTag`) may be needed.

## Phase 4: Add E2E Tests

1. Add or update tests in `packages/sui/test/e2e/clients/core/`.
2. Use `testWithAllClients` to run the test across all transports.
3. Use `expectAllClientsReturnSameData` to assert identical results across clients.
4. If you need new on-chain state, add Move functions to `test/e2e/data/shared/test_data/sources/`.
5. If you add lines to Move source files, check whether existing snapshot tests reference line numbers from those files (search for the filename in test files).

## Phase 5: Verify and Changeset

1. Build: `pnpm turbo build --filter=@mysten/sui`
2. Lint: `pnpm --filter @mysten/sui oxlint:check`
3. Unit tests: `pnpm --filter @mysten/sui test`
4. Format: `pnpm prettier:check`
5. Create a changeset — use `minor` if you're adding new fields or types to the public API, `patch` for internal-only fixes.