Skip to content

local-network.md

Latest commit

 

History

History
112 lines (79 loc) · 7.1 KB

local-network.md

File metadata and controls

112 lines (79 loc) · 7.1 KB
Raw

Connecting to a Local Network (Development Only)

This document describes how to connect Dash Evo Tool to a local Dash Platform network for development and testing. Local networks are not intended for production use. They run in regtest mode on a single machine using dashmate and are useful for rapid iteration without needing testnet or mainnet funds.

Prerequisites

  1. dashmate installed and a local network running. See the Dashmate documentation for installation requirements (Docker, Node.js) and usage instructions, or the Evonode setup guide for full server configuration details. A local network is typically set up via:

    dashmate setup local
dashmate group start

  2. Dash Evo Tool built from source (see Contributing Guide).

Configuration

Local network configuration is stored in the application .env file using the LOCAL_ prefix. If the file does not exist yet, copy .env.example to the appropriate directory and rename it to .env. The .env file location depends on the OS:

OS Path
Linux ~/.config/dash-evo-tool/.env
macOS ~/Library/Application Support/Dash-Evo-Tool/.env
Windows C:\Users\<User>\AppData\Roaming\Dash-Evo-Tool\config\.env

Required environment variables

Add (or update) these LOCAL_-prefixed variables in the .env file:

LOCAL_dapi_addresses=http://127.0.0.1:2443,http://127.0.0.1:2543,http://127.0.0.1:2643
LOCAL_core_host=127.0.0.1
LOCAL_core_rpc_port=20302
LOCAL_core_rpc_user=dashmate
LOCAL_core_rpc_password=<password>
LOCAL_core_zmq_endpoint=tcp://127.0.0.1:50298

Obtaining the RPC password

The local network RPC password is generated by dashmate during setup and is different each time. Retrieve it with:

dashmate config get core.rpc.users.dashmate.password --config=local_seed

Paste the returned value as LOCAL_core_rpc_password in the .env file.

Obtaining ports

The default ports listed above match a standard dashmate setup local configuration. If your setup differs, retrieve the correct values with:

# Core RPC port
dashmate config get core.rpc.port --config=local_seed

# DAPI ports (check each node: local_seed, local_2, local_3)
dashmate config get platform.dapi.envoy.http.port --config=local_seed
dashmate config get platform.dapi.envoy.http.port --config=local_2
dashmate config get platform.dapi.envoy.http.port --config=local_3

# ZMQ endpoint port
dashmate config get core.zmq.port --config=local_seed

Variable reference

Variable Description Example value
LOCAL_dapi_addresses Comma-separated list of DAPI HTTP endpoints http://127.0.0.1:2443,http://127.0.0.1:2543,http://127.0.0.1:2643
LOCAL_core_host Dash Core RPC host 127.0.0.1
LOCAL_core_rpc_port Dash Core RPC port 20302
LOCAL_core_rpc_user Dash Core RPC username dashmate
LOCAL_core_rpc_password Dash Core RPC password (from dashmate) (generated)
LOCAL_core_zmq_endpoint ZMQ endpoint for real-time Core events tcp://127.0.0.1:50298
LOCAL_wallet_private_key (optional) Pre-load a wallet private key WIF-encoded private key

Connecting in the UI

  1. Start Dash Evo Tool. If the LOCAL_ configuration is valid, the "Local" option appears in the network dropdown on the Network Chooser screen.

  2. Select Local from the network dropdown.

  3. If the RPC password has changed (dashmate regenerates it on each dashmate setup local), update it directly in the Local Network Password field shown below the network selector and click Save. This persists the new password to the .env file and reconnects without restarting the app.

  4. The Connection Status section shows whether Core RPC and ZMQ are reachable. Both should show as connected for full functionality.

Architecture notes

  • Internally, the local network maps to Network::Regtest from the Dash SDK.
  • Configuration is loaded via envy::prefixed("LOCAL_") in src/config.rs.
  • The AppContext for the local network is created at startup in src/app.rs and stored as local_app_context: Option<Arc<AppContext>>. If configuration is missing or invalid, this is None and the "Local" option is hidden.
  • The password-update flow in the Network Chooser (src/ui/network_chooser_screen.rs) updates the in-memory AppContext config, persists to .env, and re-initializes the Core RPC client and SDK without requiring an app restart.
  • DAPI addresses use HTTP (not HTTPS) since TLS certificates are not provisioned on local networks.

Differences from other networks

Aspect Local (Regtest) Testnet / Devnet Mainnet
Network enum Network::Regtest Network::Testnet / Network::Devnet Network::Dash
Env prefix LOCAL_ TESTNET_ / DEVNET_ MAINNET_
DAPI protocol HTTP HTTPS (testnet) / HTTP (devnet) HTTPS
Default RPC user dashmate dashrpc dashrpc
Default RPC port 20302 19998 / 29998 9998
Password management In-app editable Via .env only Via .env only

Troubleshooting

  • "Local" not in network dropdown: Verify that all required LOCAL_ variables are present in .env. Check application logs for Failed to load local configuration.
  • RPC connection fails: Confirm dashmate is running (dashmate group status) and that the password matches (dashmate config get core.rpc.users.dashmate.password --config=local_seed).
  • DAPI unreachable: Ensure Platform services are started (dashmate group status) and the ports in LOCAL_dapi_addresses match your dashmate configuration.
  • ZMQ not connecting: Verify LOCAL_core_zmq_endpoint matches the ZMQ port in your dashmate config.