initia-appchain-dev

What this skill does

# Initia Appchain Dev

Deliver practical guidance for full-stack Initia development: contracts, frontend integration, and appchain operations.

Command examples in this file assume the working directory is `skill/`; use `scripts/...` paths accordingly.

## Intake Questions (Ask First)

Collect missing inputs before implementation:

1. Which VM is required (`evm`, `move`, `wasm`)?
2. Which network is targeted (`testnet` or `mainnet`)?
3. Is this a fresh rollup launch or operation/debug on an existing rollup?
4. For frontend work, is this an EVM JSON-RPC app or an InterwovenKit wallet/bridge app?
5. What chain-specific values are known (`chain_id`, RPC URL, deployed contract address, denom)?

If critical values are missing, ask concise follow-up questions before generating final code/config.

If `chain_id`/endpoints/VM are missing, run the discovery flow in `references/runtime-discovery.md` before assuming defaults.

If `weave` is installed but fails with shell-level errors, continue discovery
with `~/.minitia/artifacts/config.json` and direct `minitiad` commands instead
of blocking on `weave`.

Then ask a context-specific confirmation:
- Frontend task: "I found a local rollup config/runtime. Should I use this rollup for frontend integration?"
- Non-frontend task: "I found local runtime values (VM, chain ID, endpoints). Should I use these for this task?"

## Environment Setup Workflow (One-Prompt Setup)

When the user asks to "set up my environment for the [Track] track" (Step 5), execute this sequence:

### 1. Identify Track Requirements & Prerequisites
- **[MOVE] Track:** `minimove` repo -> `minitiad`. Requires `go`.
- **[EVM] Track:** `minievm` repo -> `minitiad`. Requires `go`, `foundry`.
- **[WASM] Track:** `miniwasm` repo -> `minitiad`. Requires `go`, `rust/cargo`.

### 2. Check System Prerequisites
Check prerequisites by selected track (always check `docker` for tool installer compatibility):
- **[MOVE] Track:** `go`, `docker`
- **[EVM] Track:** `go`, `docker`, `foundry`
- **[WASM] Track:** `go`, `docker`, `cargo`

For each required tool in the selected track:
- If **missing**: Inform the user and **propose** the installation command (e.g., "I see you're missing Cargo. Would you like me to install it for you using `rustup`?").
- If **present**: Proceed silently.

### 3. Install Core Initia Tools
Run `scripts/install-tools.sh` to install `jq`, `weave`, and `initiad` (L1).
- **Security**: If the script requires `sudo`, explain this to the user before running.
- If the required tools are already present, prefer verifying versions over reinstalling. Pinned installer versions may lag behind what is already installed on the machine.

### 4. Build VM-Specific Binary (`minitiad`)
Clone, build, and **clean up** the relevant VM from source.

Run the build from the repository directory itself. Do not rely on shell-chained `cd ... && make install` examples if your execution environment manages working directories separately.

- **[MOVE]:**
  ```sh
  git clone --depth 1 https://github.com/initia-labs/minimove.git /tmp/minimove
  cd /tmp/minimove
  make install
  rm -rf /tmp/minimove
  ```
- **[EVM]:**
  ```sh
  git clone --depth 1 https://github.com/initia-labs/minievm.git /tmp/minievm
  cd /tmp/minievm
  make install
  rm -rf /tmp/minievm
  ```
- **[WASM]:**
  ```sh
  git clone --depth 1 https://github.com/initia-labs/miniwasm.git /tmp/miniwasm
  cd /tmp/miniwasm
  make install
  rm -rf /tmp/miniwasm
  ```

### 5. Configure PATH
- Ensure `~/go/bin` is in the user's `PATH`.
- Check shell config files (`.zshrc`, `.bashrc`) and suggest the `export` command if missing.
- After updating shell config, tell the user to run `source ~/.zshrc` (or open a new terminal) to apply changes in their current shell.
- For verification, you may run `zsh -lc 'source ~/.zshrc && <command>'` in a single command; this does not persist across separate assistant commands.

### 6. Final Verification
Run:
- `weave version`
- `initiad version`
- `minitiad version --long | rg '^(name|server_name|version|commit):'`

Required VM match:
- **[EVM] track:** `name: minievm`
- **[MOVE] track:** `name: minimove`
- **[WASM] track:** verify the reported `name` matches the Wasm VM you built

Do not treat a successful `minitiad version` command by itself as sufficient verification. The binary on `PATH` may still be from a different VM track.

## Opinionated Defaults

| Area | Default | Notes |
|---|---|---|
| VM | `evm` | Use `move`/`wasm` only when requested |
| Move Version | `2.1` | Uses `minitiad move build`. Prefer omitting `edition` from `Move.toml` unless a specific compiler version requires it. |
| Network | `testnet` | Use `mainnet` only when explicitly requested |
| Frontend (EVM VM) | wagmi + viem JSON-RPC | Default for pure EVM apps |
| Frontend (Move/Wasm) | `@initia/interwovenkit-react`| Use when InterwovenKit features are required |
| Tx UX | `requestTxBlock` | Prefer confirmation UX; use `requestTxSync` for local dev robustness. |
| Provider order | Wagmi -> Query -> InterwovenKit | Stable path for Initia SDKs |
| Rollup DA | `INITIA` | Prefer Celestia only when explicitly needed |
| Keys & Keyring | `gas-station` / `test` | Default key and `--keyring-backend test` for hackathon tools |
| Denoms | `GAS` (EVM) / `umin` (Move) | Typical defaults for test/internal rollups |

## Strict Constraints (NEVER VIOLATE)

### Tagging Standard
- Use VM-first tags for VM-specific guidance: `[EVM]`, `[MOVE]`, `[WASM]`, `[ALL-VM]`.
- Add optional context tags after VM: `[CLI]`, `[DEV]`, `[REST]`, `[RPC]`, `[FRONTEND]`, `[INTERWOVENKIT]`, `[BUILD]`, `[TEST]`.
- Prefer stacked tags (example: `[EVM][CLI]`) over combined tags (for example, avoid `[EVM CLI]`).
- Required workflow for any skill markdown edit: run `scripts/lint-tags.sh` before changes and run it again before handoff.

### Initia Usernames (STRICTLY OPT-IN)
- You MUST NOT implement username support in any scaffold, component, or code snippet unless explicitly requested (e.g., "add username support").
- When requested, use `useInterwovenKit().username` only for the connected wallet's own display name.
- Pattern: `{username ? username : shortenAddress(initiaAddress)}`
- For resolving usernames of arbitrary wallet addresses (for example, MemoBoard sender rows), use `useUsernameQuery(address?)` with the sender address; this requires `@initia/interwovenkit-react` `2.4.6` or newer.
- For feeds, boards, or any rendered list of messages/accounts, resolve sender usernames inside a child row component (for example `MessageRow`) and call `useUsernameQuery(address)` there. Do NOT call hooks directly inside a parent component's `.map()` callback or conditional loop body.
- Do NOT resolve via REST unless hook-based resolution is insufficient.
- `useUsernameQuery` behavior:
  - No param: resolves connected wallet address (`useAddress()` fallback).
  - With param: resolves the provided address.

### Workspace Hygiene (CRITICAL)
- You MUST NOT leave temporary files or metadata JSON files (e.g., `store_tx.json`, `tx.json`, `.bin`) in the project directory after a task.
- Delete binary files used for deployment before finishing.

### InterwovenKit Local Appchains (CRITICAL)
- When configuring a frontend for a local appchain, you MUST use BOTH the `customChain` AND `customChains: [customChain]` properties in `InterwovenKitProvider`.
- **Example Usage**:
  ```jsx
  <InterwovenKitProvider 
    {...TESTNET} 
    customChain={customChain} 
    customChains={[customChain]}
  >
    <App />
  </InterwovenKitProvider>
  ```
- **Bridge Support**: To ensure the bridge can resolve public chains (like `initiation-2`), ALWAYS spread the `{...TESTNET}` preset (imported from `@initia/interwovenkit-react`) into the `InterwovenKitProvider`: `<InterwovenKitProvider {...TESTNET} ... />`.
- **Address Prefix**: `customChain` MUST include a top-level `bech32_prefix` string (e.g., `bech32_prefix: "init"`). This is **mandatory for all appchain types**.
- **Metadata Completeness*