Background service
The setup wizard can install and start a systemd service. The terminal menu controls that service; closing the menu leaves it running.
Root installation
sudo systemctl status az-vote-delegate.service
sudo journalctl -u az-vote-delegate.service -n 100 --no-pager
To restart the existing service:
sudo systemctl restart az-vote-delegate.service
To stop it:
sudo systemctl stop az-vote-delegate.service
The generated unit is installed under /etc/systemd/system.
Regular user installation
Run these as the same user that installed the application:
systemctl --user status az-vote-delegate.service
journalctl --user -u az-vote-delegate.service -n 100 --no-pager
systemctl --user restart az-vote-delegate.service
For the user service to survive logout and start at boot, enable lingering. Replace the placeholder with your node's account name:
sudo loginctl enable-linger YOUR_NODE_USER
Use systemctl --user stop az-vote-delegate.service to stop it.
If you skipped service installation
After saving setup, run this as the installation owner to install and start the service:
az-vote-delegate service-install
For root installations, prefix the command with sudo. For user installations without ~/.local/bin on PATH, use ~/.local/bin/az-vote-delegate.
If systemd is unavailable, keep the worker running in a terminal:
az-vote-delegate run
Open the menu in another terminal, with the same user and configuration. run uses your saved Dry run or Live mode. Do not start a foreground worker alongside the service.
Configuration and persistent state
By default, files are stored under ~/.config/az-vote-delegate/ for the user running the app:
| File | Purpose |
|---|---|
config.json | Node, key, delegation, copy-delay, and voting-mode settings |
producer-password | Owner-only password file created by setup |
state/state.json | Manual overrides, copy-delay observations, copied votes, and pending submissions |
An existing ./config.json is preferred for compatibility. Use --config /absolute/path/config.json to select a specific configuration. The menu and service must use the same file.
Restarts and upgrades preserve manual choices. When migrating, stop the service and preserve the configuration, password, key, and state together, keeping them private. Resolve pending transactions before changing the setup. Do not delete state to clear an error: it contains the record of submissions and manual overrides.
A state-file lock prevents two workers from using the same state. Do not create separate state files for competing instances with the same producer.
Reliability details
The service reads current votes every poll, so it does not need to observe the delegate's original vote block. It pages through all projects, using the node's 1,024-entry limit, and selects Voting projects within the 14-day window and the current Voting phase of Active projects. Reads use node time. Delegation chains work; an empty A↔B cycle produces no initial vote.
The state file tracks copy votes, explicit manual choices, external overrides, copy-delay observations, backoff and pending submissions. Saves use a 0600 temporary file, file sync, atomic rename and directory sync. Save failures stop live operation. A file lock prevents a second service from using the same state, and the private directory and mode-0600 control socket restrict control to its owner. Do not run multiple instances for the same producer using different state paths.
A signed block hash is journaled before publication. Pending sends wait for a confirmed contract receive block, then votes are reread. Preparation failures and definite rejections retry on the next poll, then back off exponentially up to 30 minutes. Ambiguous publications remain pending, including a crash between journaling and publishing. This favors avoiding duplicate votes over automatic recovery from an unknown outcome.
Missing state conservatively treats existing votes as manual. Corrupt or cross-network state is refused. After stopping the service and resolving every pending transaction, an explicit reset can discard attribution and overrides:
az-vote-delegate run --config /path/to/config.json --dry-run=false --reset-state
Existing on-chain votes remain. Resetting while a transaction might still execute is unsafe; back up and inspect the state first.
The SDK asks the node whether fused plasma is sufficient, otherwise it computes PoW. The service does not auto-fuse QSR. Logs identify PoW versus fused plasma. Reading the node's plasma requirements does not establish Dynamic Plasma compatibility; that requires a separate implementation and validation effort. Sends are sequential, so CPU work can extend a poll beyond the configured poll interval. A status preview remains available while PoW runs. SIGINT/SIGTERM cancel work and save state. WebSocket reads are interrupted on cancellation; HTTP reads have a 30-second transport timeout. Subsequent polls open a fresh connection.
The producer key is held in memory while running, as it is in znnd. Use the node host or a host with equivalent protection, and an RPC endpoint you trust. No browser server, remote control port or hosted key service is involved.