> For the complete documentation index, see [llms.txt](https://suigar.gitbook.io/suigar-docs/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://suigar.gitbook.io/suigar-docs/migration-run-order.md).

# gRPC migration

Use this file to decide **execution order** before running any migration step. Detailed step prompts are in `docs/grpc-migration/migration-step-prompts.md`. Policy enforcement gates are in `docs/grpc-migration/policy-gates.md`.

## 0. Scope

Core track (universal):

* `@mysten/sui` 1.x -> 2.x migration
* dApp Kit -> dApp Kit React migration

Conditional track (selected by scenario):

* `@mysten/walrus` / `@mysten/suins` 0.x -> 1.x
* chain-fixed network exception (only with explicit rationale comment)
* Gate F runtime validation (only when trigger conditions are met)

This file defines scenario detection, case selection, and execution order. Workflow style contract: keep copy/paste + single-prompt execution as default.

## 1. Core Policies (must hold in every case)

* Do not introduce `SuiJsonRpcClient`.
* Do not introduce imports from `@mysten/sui/jsonRpc`.
* Legacy-detection keywords should be limited to 1.x-era symbols.
* Post-migration quality gates may inspect 2.x loader patterns.
* For digest-based transaction content loading, use a **two-stage loader** (`gRPC getTransaction` first, then GraphQL fallback with explicit error when both miss).
* For shared digest loaders, keep network caller-driven (no module-scope fixed network literals).
* In GraphQL fallback, check `errors` before reading `data`, and include network/stage in loader errors.
* In GraphQL transaction queries, treat `effects` list fields as connection types and use `nodes`/`edges` access.
* For same-flow submit confirmation (`waitForTransaction`), gRPC is allowed.
* Unresolved `BLOCKER` items are fail state (no accepted-blocker shortcut).

## 2. Conditional Policies

* If a flow is chain-fixed, hardcoded network is allowed only with explicit rationale in code comments.
* When GraphQL query fields or two-stage byte loader behavior changes, Gate F runtime validation is required.
* Walrus/SuiNS-specific checks apply only in Case B/C.

## 3. Repository/Workspace Scope (monorepo-safe)

Run this once before scenario detection:

```bash
# package manifests (single package + monorepo)
rg --files . -g "**/package.json" -g "!**/node_modules/**" -g "!.git/**"
```

All scan/gate commands in this kit should use repository root `.` with explicit include/exclude globs:

* include: `**/*.{ts,tsx,js,jsx,mjs,cjs,graphql,gql}` and `**/package.json`
* exclude: `**/node_modules/**`, `.git/**`

## 4. Scenario Detection

Run this detection command first:

```bash
rg "\"@mysten/walrus\"|\"@mysten/suins\"|new WalrusClient|new SuinsClient|\\$extend\\(walrus\\)|\\$extend\\(suins\\)" . -g "**/package.json" -g "**/*.{ts,tsx,js,jsx,mjs,cjs}" -g "!**/node_modules/**" -g "!.git/**"
```

Then inspect matched package manifests for intended `@mysten/sui` major version.

## 5. Case Selection

### Case A: Sui-only migration

Choose Case A when:

* No Walrus/SuiNS usage is detected
* You are migrating `@mysten/sui` + dApp Kit paths

Execution order:

1. Step 1
2. Step 2
3. Step 3
4. Step 4
5. Step 5
6. Optional Step E (post-migration DRY: consolidate duplicate constants and factories)

### Case B: Sui + Walrus/SuiNS together

Choose Case B when:

* Walrus/SuiNS usage is detected
* Sui core migration and Walrus/SuiNS migration are both needed

Execution order:

1. Step 1
2. Step 2
3. Step 3
4. Optional Step A
5. Optional Step B
6. Optional Step C
7. Step 3 (rerun: check that Optional A-C changes did not introduce drift in shared backend files — gRPC loader patterns, client setup, imports)
8. Step 4
9. Optional Step D
10. Step 5
11. Optional Step E (post-migration DRY: consolidate duplicate constants and factories)

### Case C: Sui 2.x already done, Walrus/SuiNS-only migration

Choose Case C when:

* `@mysten/sui` migration is already complete
* Only Walrus/SuiNS migration remains

Execution order:

1. Optional Step A
2. Optional Step B
3. Optional Step C
4. Optional Step D
5. Step 5
6. Optional Step E (post-migration DRY: consolidate duplicate constants and factories)

Post-run recommendation (all cases):

* Run Optional Step E from `docs/grpc-migration/migration-step-prompts.md` to consolidate any duplicate constants/factories.
* Run Step 6 (final audit) from `docs/grpc-migration/migration-step-prompts.md` as a separate prompt.

## 6. Integration Gates (Case B/C)

Run these checks after Optional Step C and before final validation:

```bash
rg "SuiJsonRpcClient|@mysten/sui/jsonRpc" . -g "**/*.{ts,tsx,js,jsx,mjs,cjs}" -g "!**/node_modules/**" -g "!.git/**"
rg "new WalrusClient|new SuinsClient|getFullnodeUrl|@mysten/sui/experimental" . -g "**/*.{ts,tsx,js,jsx,mjs,cjs}" -g "!**/node_modules/**" -g "!.git/**"
rg "from ['"]@mysten/sui/client['"]|require(['"]@mysten/sui/client['"])" . -g "**/*.{ts,tsx,js,jsx,mjs,cjs}" -g "!**/node_modules/**" -g "!.git/**"
```

If any match remains:

* Keep migration status as incomplete
* Add `BLOCKER` + TODO
* Continue only after explicit fix

## 7. One-Prompt Mode (Confirm-only)

Paste this into your AI agent when you want one continuous run:

```
Read docs/grpc-migration/migration-run-order.md and docs/grpc-migration/migration-step-prompts.md.

Do the migration end-to-end with minimal user interruption:
- Detect workspace/package scope first (single repo + monorepo).
- Auto-detect scenario (Case A/B/C) using the detection command in migration-run-order.md.
- Execute exact step order for that case.
- Run validation gates and per-step reports exactly as defined.
- Keep final audit (Step 6) as a separate follow-up prompt for reliability.
- Do not stop between normal steps.
- Ask for confirmation only when:
  1) command permission/escalation is required
  2) destructive action is required
  3) a true ambiguous blocker remains

Final output:
1. selected scenario + evidence
2. commands executed
3. migrated file list
4. key diffs summary
5. validation results
6. blockers/TODOs
```

## 8. Required Step Report Format (every step)

Each completed step must output:

1. step name + completion status
2. changed files or commands executed
3. verify checklist pass/fail
4. TODO/BLOCKER list
5. ready for next step: yes/no