End-to-end Initia development and operations guide. Use when asked to build Initia smart contracts (MoveVM/WasmVM/EVM), build React frontends (InterwovenKit or EVM direct JSON-RPC), launch or operate Interwoven Rollups with Weave CLI, or debug appchain/transaction integration across these layers.
Deliver practical guidance for full-stack Initia development: contracts, frontend integration, and appchain operations.
Collect missing inputs before implementation:
evm, move, wasm)?testnet or mainnet)?chain_id, RPC URL, module 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 runtime-discovery.md before assuming defaults.
Then ask a context-specific confirmation:
| Area | Default | Notes |
|---|---|---|
| VM | evm | Use move/wasm only when requested |
| Move Version | 2.1 | Uses minitiad move build. Note: edition = "2024.alpha" in Move.toml may trigger 'unknown field' warnings but is safe to ignore. |
| Network | testnet | Use mainnet only when explicitly requested |
| Frontend (EVM VM) | wagmi + viem direct JSON-RPC | Default for pure EVM apps |
| Frontend (Move/Wasm or bridge wallet UX) | @initia/interwovenkit-react | Use when InterwovenKit features are required |
| Frontend wallet flow (InterwovenKit path) | requestTxBlock | Prefer confirmation UX |
| Local Frontend wallet flow | requestTxSync | Use sync submission for better robustness in local dev |
| Frontend provider order (InterwovenKit path) | Wagmi -> Query -> InterwovenKit | Stable path for Initia SDKs |
| Rollup DA | INITIA | Prefer Celestia only when explicitly needed |
| Rollup moniker | operator | Override for production naming |
| Gas Station Key | gas-station | Default key name used in tutorials |
| Keyring Backend | test | Use --keyring-backend test for hackathon tools |
| EVM denom | GAS | Typical test/internal default |
| Move/Wasm denom | umin | Typical default |
username property directly from the useInterwovenKit() hook.{username ? username : shortenAddress(initiaAddress)}{message.sender === initiaAddress && username ? username : shortenAddress(message.sender)}getProfile unless the hook's property is insufficient for a specific requirement.store_tx.json, instantiate_tx.json, deploy_receipt.json, or .bin files) in the project directory after a task is complete.
> tx.json), or generate binary files for deployment (e.g., MiniBank.bin), you MUST delete these files before finishing the task.customChain (singular) property in the InterwovenKitProvider and ensure defaultChainId matches the appchain's ID.
customChain.apis object MUST include rpc, rest, AND indexer (even if indexer is a placeholder).customChain.apis MUST also include json-rpc.initiad keys export) for any reason, including for use with tools like forge create or foundry script.
minitiad tx evm create command with the --from flag. This ensures transactions are signed securely within the encrypted keyring.jq -r '.bytecode.object' <artifact.json>. Ensure the binary file contains NO 0x prefix and NO trailing newlines (use tr -d '\n' | sed 's/^0x//').minitiad tx evm create <bin_file> for the most reliable deployment. If using the --input flag, the input MUST include the 0x prefix.jq -r '.events[] | select(.type == "contract_created") | .attributes[] | select(.key == "contract") | .value'.InterwovenKit.When solving an Initia task:
run_shell_command fails with "command not found", check standard locations:
~/.cargo/bin/cargo~/.foundry/bin/forgewhich initiad or which minitiad~/.cargo/bin/cargo test).minitiad move new or npm create vite), check if a project already exists in the current directory (ls -F).Move.toml or package.json), do NOT create a new subdirectory unless explicitly asked.forge install), ensure the directory is a git repository (git init) and use --no-git to avoid submodule issues if git is not desired.index.html in the project root. If missing, create a standard Vite index.html with <div id="root"></div> and the module script pointing to src/main.jsx.@tanstack/react-query, wagmi, viem, and buffer.Board.jsx), ALWAYS verify that it is imported and rendered in App.jsx.src/main.jsx to include the customChain configuration in the InterwovenKitProvider. See frontend-interwovenkit.md for the standard local appchain config object. Ensure the chain_id and rpc/rest endpoints match the discovered appchain runtime. Additionally, you MUST ensure vite.config.js is updated with vite-plugin-node-polyfills (specifically for Buffer) as initia.js and other SDKs depend on these globals. Furthermore, ensure src/App.css exists as it is typically imported by App.jsx.main.jsx, you MUST:
Buffer and process at the TOP of the file:
import { Buffer } from 'buffer'
window.Buffer = Buffer
window.process = { env: { NODE_ENV: 'development' } }
import '@initia/interwovenkit-react/styles.css'
import { injectStyles } from '@initia/interwovenkit-react'
import InterwovenKitStyles from '@initia/interwovenkit-react/styles.js'
injectStyles(InterwovenKitStyles)
InterwovenKitProvider with WagmiProvider and QueryClientProvider in THIS EXACT ORDER:
<WagmiProvider config={wagmiConfig}>
<QueryClientProvider client={queryClient}>
{/* ALWAYS use ...TESTNET or ...MAINNET baseline even for local appchains */}
<InterwovenKitProvider
{...TESTNET}
defaultChainId="your-appchain-id"
customChain={customChain}
// enableAutoSign={true} // OPTIONAL: Include only if auto-sign functionality is requested
>
<App />
</InterwovenKitProvider>
</QueryClientProvider>
</WagmiProvider>
useAccount and useDisconnect from wagmi for wallet state, while using useInterwovenKit for initiaAddress, requestTxBlock, and openConnect.openConnect (not openModal) to open the wallet connection modal. Extract it from the useInterwovenKit hook.useInterwovenKit does NOT export a rest client. You MUST instantiate RESTClient from @initia/initia.js manually for queries.customChain.apis object MUST include rpc, rest, AND indexer (even as a placeholder like [{ address: "http://localhost:8080" }]) in apis. Additionally, metadata MUST include is_l1: false for appchains. The customChain MUST also include a fees section with fee_tokens (e.g., fees: { fee_tokens: [{ denom: "umin", fixed_min_gas_price: 0.15, ... }] }) to prevent runtime SDK errors. Always use the singular customChain prop in InterwovenKitProvider for a single local appchain.customChain.apis object MUST include a "json-rpc" entry (e.g., [{ address: "http://localhost:8545" }]). Failure to include any of these endpoints in the correct array-of-objects format will result in "URL not found" errors during frontend runtime.useInterwovenKit:
chainId in the payload to avoid "must contain at least one message" RPC errors.requestTxSync for better robustness in local development.messages for requestTxSync or msgs for requestTxBlock per SDK version expectations).MsgCall transactions on EVM appchains, the sender field MUST use the bech32 address (initiaAddress from useInterwovenKit), while the contractAddr remains hex (0x...).MsgCall, you MUST use camelCase for fields (contractAddr, accessList, authList) and include empty arrays ([]) for both lists to avoid Amino conversion errors.ethers or eth_call, you MUST convert bech32 addresses to hex using AccAddress.toHex(address) from @initia/initia.js. Ensure the resulting string has exactly one 0x prefix (e.g. const cleanHex = hex.startsWith('0x') ? hex : '0x' + hex).ethers v6. Ensure you use new ethers.Interface() and ethers.parseEther() instead of the deprecated ethers.utils patterns.MsgExecute messages via initia.js, you MUST use camelCase for fields (moduleAddress, moduleName, functionName, typeArgs). The moduleAddress MUST be in bech32 format (e.g., init1...). Using hex will result in "empty address string is not allowed" errors.minitiad tx move execute, you MUST provide exactly 3 positional arguments: [module_address] [module_name] [function_name]. Use the --args and flags for parameters. Arguments in MUST be prefixed with their Move type (e.g., ).ERRESOLVE or peer dependency warnings. These are common in the current ecosystem and should be treated as non-fatal unless the build actually fails.gas-station account for ALL transactions (L1 and L2) unless the user explicitly provides another.initiad, minitiad) generally require bech32 addresses (init1...).
0x...), use scripts/convert-address.py to get the bech32 equivalent.eth_call or evm query) requires a hex address from a bech32 address, ALWAYS use scripts/to_hex.py <bech32_address>.minitiad query evm call, you MUST provide 3 arguments: [sender_bech32] [contract_addr_hex] [input_hex_string].
input_hex_string MUST include the 0x prefix.minitiad q evm call init1... 0x... 0x70a08231...gas-station key exists in the local keychain (initiad keys show gas-station --keyring-backend test and minitiad keys show gas-station --keyring-backend test).gas-station key is missing from the keychains, run the following to import it from the Weave configuration.
SECURITY NOTE: This flow is for Hackathon/Testnet use only. NEVER auto-import keys from a JSON config if the target network is
mainnet.
MNEMONIC=$(jq -r '.common.gas_station.mnemonic' ~/.weave/config.json)
# ...
Developers need tokens in their browser wallets (e.g., Keplr or Leap) to interact with their appchain and the Initia L1.
When a user provides an address and asks for funding, you should ideally fund them on both layers:
scripts/fund-user.sh --address <init1...> --layer l2 --chain-id <l2_chain_id>)scripts/fund-user.sh --address <init1...> --layer l1)Note: fund-user.sh may fail to auto-detect the L2 chain-id. Always use verify-appchain.sh first to retrieve it and provide it explicitly if needed.
Account Existence (CRITICAL): Transactions via requestTxSync or requestTxBlock will fail with "Account does not exist" if the sender has no balance. ALWAYS ensure a user is funded on L2 before they attempt their first transaction.
Always verify the balance of the gas-station account before attempting to fund a user.
Pro Tip: Token Precision & Denoms (CRITICAL):
uinit ($10^{-6}$). When a user asks for "1 INIT", you MUST send 1000000uinit.GAS, umin, uinit). ALWAYS check minitiad q bank total to verify the native denom before funding.umin), assume they mean whole tokens and multiply by $10^6$ (Move/Wasm) or $10^{18}$ (EVM) unless they explicitly specify "base units" or "u-amount".1000000000000000000 of the base unit.fund-user.sh to handle precision or denoms automatically. Explicitly calculate the base unit amount and specify the correct denom in your commands.Pro Tip: Move Publishing (CRITICAL): When publishing Move modules, the minitiad tx move publish command does NOT support the --named-addresses flag. You MUST first build the module using minitiad move build --named-addresses name=0x... and then publish the generated .mv file. The --upgrade-policy flag value MUST be uppercase (e.g., COMPATIBLE).
Pro Tip: Wasm REST Queries (CRITICAL): When querying Wasm contract state using the RESTClient (e.g., rest.wasm.smartContractState), the query object MUST be manually Base64-encoded. The client does NOT handle this automatically.
const query = Buffer.from(JSON.stringify({ msg: {} })).toString("base64"); await rest.wasm.smartContractState(addr, query);Pro Tip: Move REST Queries (CRITICAL): When querying Move contract state using the RESTClient (e.g., rest.move.view), the module address MUST be in bech32 format. Address arguments in args MUST be converted to a 32-byte padded hex string and then Base64-encoded.
rest.move.view is a ViewResponse object; you MUST parse response.data (a JSON string) to access the actual values.const b64Addr = Buffer.from(AccAddress.toHex(addr).replace('0x', '').padStart(64, '0'), 'hex').toString('base64');
const res = await rest.move.view(mod_bech32, mod_name, func_name, [], [b64Addr]);
const data = JSON.parse(res.data); // data is ["shard_count", "relic_count"]
Pro Tip: Wasm Transaction Messages (CRITICAL): When sending a MsgExecuteContract via requestTxBlock, the msg field MUST be a Uint8Array (bytes). If using requestTxSync, ensure the messages (plural) field is used.
msg: new TextEncoder().encode(JSON.stringify({ post_message: { message } }))http://localhost:26657, but verify the actual endpoint:
~/.minitia/config/config.toml (under [rpc] laddr)minitia.config.json or ~/.minitia/artifacts/config.json.weave rollup start -d.scripts/verify-appchain.sh.scripts/verify-appchain.sh --gas-station --bots to ensure both block production and Gas Station readiness.chain_id/endpoint values are unknown, run scripts/verify-appchain.sh --gas-station --bots.--from gas-station --keyring-backend test.initiad usually looks in ~/.initia and minitiad usually looks in ~/.minitia for keys.runtime-discovery.md.scripts/scaffold-contract.sh <move|wasm|evm> <target-dir>cargo build binaries often fail WasmVM validation (e.g., "bulk memory support not enabled"). ALWAYS use the cosmwasm/optimizer Docker image to build production-ready binaries.
cosmwasm/optimizer-arm64:0.16.1 image variant for significantly better performance and compatibility.store or instantiate transaction, if the code_id or contract_address is missing from the output, query the transaction hash using minitiad q tx <hash> (note: q tx does NOT take a --chain-id flag).tx), many query commands (query or q) do NOT support the --chain-id flag. If a query fails with an "unknown flag" error, try removing the chain-id and node flags.sources/<project_name>.move) before creating your custom modules to keep the project clean.src/Example.sol and test/Example.t.sol) before creating your custom contracts.testFail is deprecated in newer versions of Foundry and WILL cause test failures in modern environments. ALWAYS use vm.expectRevert() for failure testing.forge test and forge build MUST be run from the project root (the directory containing foundry.toml). Always cd into the project directory before executing these.Addr type does NOT implement PartialEq<&str>. When writing unit tests that compare a stored address with a string literal, ALWAYS use .as_str() (e.g., assert_eq!(msg.sender.as_str(), "user1")) to avoid compilation errors.#[view], ALWAYS place the documentation comment (/// ...) AFTER the attribute to avoid compiler warnings.#[view]
/// Correct placement of doc comment
public fun my_function() { ... }
testnet/mainnet), VM, chain_id, and endpoints (RPC/REST/JSON-RPC).scripts/scaffold-frontend.sh <target-dir> to ensure correct polyfill and provider setup.l1_config.gas_prices, l2_config.denom, funded genesis balances).typeUrl and payload shape match chain/VM expectations.init1..., 0x..., celestia1...) per config field requirements.scripts/verify-appchain.sh --gas-station --bots to check health and gas station balance).init1...pxn4uh) and a clearly labeled "Disconnect" button.type="number" for token amounts, ALWAYS include CSS to hide the default browser spin buttons (up/down arrows) for a cleaner, app-like appearance.message in Rust, the CLI JSON payload and Frontend state should also use message, not content. Prefer snake_case for all JSON keys to align with standard CosmWasm/EVM/Move serialization.
message (not content) for the post content and the query name all_messages (which serializes to all_messages in JSON). For the query response, use AllMessagesResponse to maintain compatibility with the standard InterwovenKit frontend examples.PostMessage in Rust (serializing to post_message) to match the documentation and frontend scaffolds.sleep 5) between the commands. This ensures the transaction is committed to a block before the query is executed, preventing stale data results.openBridge from the useInterwovenKit hook as the primary entry point.openBridge).chainId. For tutorials/demos, default the srcChainId to a public testnet (e.g., initiation-2) to ensure the UI renders correctly.runtime-discovery.mdcontracts.mdfrontend-evm-rpc.mdfrontend-interwovenkit.mdweave-commands.mdweave-config-schema.mdtroubleshooting.mde2e-recipes.mdWhen uncertain about any Initia-specific behavior, prefer official docs:
https://docs.initia.xyzhttps://docs.initia.xyz/interwovenkitDo not guess when an authoritative answer can be confirmed from docs.
scripts/install-tools.shscripts/scaffold-contract.shscripts/scaffold-frontend.shscripts/check-provider-setup.shscripts/verify-appchain.shscripts/convert-address.pybip_utils; pass --vm <evm|move|wasm> for denom-aware defaults; mnemonics are redacted unless --include-mnemonics --output <file>): scripts/generate-system-keys.pyWhen implementing substantial changes, return:
--type-args--args'["address:init1...", "u64:100"]'useInterwovenKit hook returns an autoSign object (not individual functions). Use autoSign.isEnabledByChain[chainId] for status, and autoSign.enable(chainId) / autoSign.disable(chainId) for actions.enableAutoSign={true} is passed to the InterwovenKitProvider in main.jsx.await requestTxSync({ chainId: 'social-1', messages: [...] })