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.