| name | local-vara-eth-node |
| description | Run a fully local Vara.eth development environment with ethexe, switch this repository to local RPC endpoints, fetch the local router address, and prepare `.env` for local integration-test debugging. Use when the task is to reproduce test failures locally, debug contract/program flows without testnet noise, or temporarily point the repo at a local ethexe dev node. |
Local Vara.eth Node
Use this skill when local debugging is needed for Vara.eth integration tests in this repository.
Goal
Launch a fully local Vara.eth development environment using ethexe, with:
- local Anvil
- local Router deployment
- local Vara.eth RPC
- a usable Router address for CLI/tests
.env updated to local endpoints when explicitly requested
Clone Location
If the Gear repository is not already available locally for this task, clone it into:
Do not clone it into this repository workspace.
Recommended Flow
Use the built-in dev mode. It is the most reliable local setup in the current implementation.
Foundry Version Requirement
For local upload / requestCodeValidation to work reliably with the current ethexe flow, use a compatible Foundry nightly.
Known working version:
foundryup --install nightly-c07d504b4ae67754584f4e05ff0c547a43c50f7b
Why this matters:
- local
ethexe code upload uses the requestCodeValidation(...) path with sidecar_7594
- some stable Anvil / Foundry versions can fail with:
error code -32602: Failed to decode transaction
- if that happens, check
anvil --version first and switch to the known working nightly above
1. Clone The Repository
git clone https://github.com/gear-tech/gear.git /tmp/gear
cd /tmp/gear/ethexe
2. Build ethexe
In practice, before the final Rust build you may need to prepare contract artifacts used by ethexe-ethereum.
2a. Initialize submodules
From /tmp/gear:
git submodule update --init --recursive
This is required because ethexe/contracts/lib/* submodules are needed for local contract ABI artifacts.
2b. Build contract artifacts
From /tmp/gear/ethexe/contracts:
forge build
This generates out/*.json artifacts used by ethexe-ethereum. If these artifacts are missing, the Rust build can fail with missing files like:
Vault.sol/Vault.jsonVaultFactory.sol/VaultFactory.jsonOperatorRegistry.sol/OperatorRegistry.json
2c. Build the CLI binary
Build from the workspace root, not from /tmp/gear/ethexe:
cd /tmp/gear
cargo build --release -p ethexe-cli
The package name is ethexe-cli, while the resulting binary is ethexe.
Verify the binary starts:
/tmp/gear/target/release/ethexe --help
3. Start The Local Node
/tmp/gear/target/release/ethexe run \
--dev \
--tmp \
--no-network \
--rpc-port 9944
Meaning of the flags
--dev: start the local development environment automatically--tmp: use a temporary database for this run--no-network: disable P2P networking for a single-node local setup--rpc-port 9944: expose the Vara.eth RPC on port 9944
4. Expected Local Endpoints
After startup, the local environment usually exposes:
- Ethereum RPC:
ws://127.0.0.1:8545
- Vara.eth WS RPC:
ws://127.0.0.1:9944
- Vara.eth HTTP RPC:
http://127.0.0.1:9944
5. Get The Router Address
Do not hardcode the local Router address. Fetch it from the dev RPC:
curl http://127.0.0.1:9944 \
-H "Content-Type: application/json" \
-d '{"jsonrpc":"2.0","method":"routerAddress","params":[],"id":1}'
Use the returned address in local CLI commands and test .env files.
6. Verify The Node Is Running
Check Ethereum RPC:
cast block-number --rpc-url http://127.0.0.1:8545
Check Vara.eth RPC:
curl http://127.0.0.1:9944 \
-H "Content-Type: application/json" \
-d '{"jsonrpc":"2.0","method":"routerAddress","params":[],"id":1}'
7. Local Test Configuration
Typical local values:
ETHEREUM_RPC=ws://127.0.0.1:8545
VARA_ETH_RPC=ws://127.0.0.1:9944
ROUTER_ADDRESS=<value from routerAddress>
PRIVATE_KEY=0xac0974bec39a17e36ba4a6b4d238ff944bacb478cbed5efcae784d7bf4f2ff80
The private key above is the default first Anvil account.
When switching this repository to local execution:
- update
.env only for an explicit local-debugging flow
- clearly note that the repo is no longer pointed at testnet
8. Insert The Local Key Into ethexe
/tmp/gear/target/release/ethexe key insert 0xac0974bec39a17e36ba4a6b4d238ff944bacb478cbed5efcae784d7bf4f2ff80
9. Optional: Debug Logs
For narrower runtime/program logs:
RUST_LOG="ethexe=info,gwasm=debug" /tmp/gear/target/release/ethexe run \
--dev \
--tmp \
--no-network \
--rpc-port 9944
To save logs to a file:
RUST_LOG="ethexe=info,gwasm=debug" /tmp/gear/target/release/ethexe run \
--dev \
--tmp \
--no-network \
--rpc-port 9944 2>&1 | tee /tmp/ethexe.log
The current local log file path used by this repo workflow is:
10. Optional: Custom Block Time
/tmp/gear/target/release/ethexe run \
--dev \
--tmp \
--no-network \
--rpc-port 9944 \
--block-time 6
Use this carefully. In the current dev flow, larger block times may affect local behavior and timing.
11. Stop The Node
Press Ctrl+C.
12. Reset State
If you used --tmp, stopping the node is usually enough.
If you used --base <path>, remove that directory's db subfolder to reset the node state.
Common Pitfalls
ethexe tx global flags must come before the subcommand.ethexe tx query requires --rpc-url for the Vara.eth WS RPC.--dev is the preferred local flow. Manual local stack assembly is more fragile.- Do not assume a local Router address. Read it from
routerAddress.
- If the Rust build fails with missing
symbiotic-* or Vault*.json artifacts, run:
git submodule update --init --recursiveforge build inside /tmp/gear/ethexe/contracts
- The Rust package name is
ethexe-cli, not ethexe.
- On the current local stack,
ethexe tx upload may still fail with:
error code -32602: Failed to decode transaction
This means the local node is up, but code validation/upload is still blocked at the Ethereum RPC layer.
- In practice, if local
upload fails with Failed to decode transaction, a Foundry/Anvil version mismatch is a primary suspect.
Example tx query
./target/release/ethexe tx \
--ethereum-rpc "ws://127.0.0.1:8545" \
--ethereum-router "$ROUTER_ADDRESS" \
--sender "0xf39Fd6e51aad88F6F4ce6aB8827279cffFb92266" \
query \
--rpc-url "ws://127.0.0.1:9944" \
"$MIRROR_ADDRESS"
