xian-stack

xian-stack is the local runtime backend for Xian. It owns Docker images, Compose topology, monitoring assets, localnet flows, and backend validation. It is the implementation surface behind local operator workflows, not the primary operator UX itself.

Common Workflows

Validate the stack:

python3 ./scripts/backend.py validate

Run a local stack-managed node:

python3 ./scripts/backend.py start --no-service-node --dashboard --monitoring
python3 ./scripts/backend.py status --no-service-node --dashboard --monitoring
python3 ./scripts/backend.py endpoints --no-service-node --dashboard --monitoring
python3 ./scripts/backend.py health --no-service-node --dashboard --monitoring
python3 ./scripts/backend.py stop --no-service-node --dashboard --monitoring

Run the optional shielded relayer sidecar against the local node:

export XIAN_SHIELDED_RELAYER_PRIVATE_KEY=<relayer-ed25519-private-key>
python3 ./scripts/backend.py start --no-service-node --shielded-relayer
python3 ./scripts/backend.py status --no-service-node --shielded-relayer
python3 ./scripts/backend.py endpoints --no-service-node --shielded-relayer
python3 ./scripts/backend.py health --no-service-node --shielded-relayer
python3 ./scripts/backend.py stop --no-service-node --shielded-relayer

Optional relayer policy is configured through environment variables:

XIAN_SHIELDED_RELAYER_AUTH_TOKEN=<bearer-token>
XIAN_SHIELDED_RELAYER_PUBLIC_INFO=1
XIAN_SHIELDED_RELAYER_PUBLIC_QUOTE=0
XIAN_SHIELDED_RELAYER_PUBLIC_JOB_LOOKUP=0
XIAN_SHIELDED_RELAYER_ALLOWED_NOTE_CONTRACTS=con_shielded_note_token
XIAN_SHIELDED_RELAYER_ALLOWED_COMMAND_CONTRACTS=con_shielded_commands
XIAN_SHIELDED_RELAYER_ALLOWED_COMMAND_TARGETS=currency,con_token_factory
XIAN_SHIELDED_RELAYER_MIN_NOTE_RELAYER_FEE=0
XIAN_SHIELDED_RELAYER_MIN_COMMAND_RELAYER_FEE=0
XIAN_SHIELDED_RELAYER_DEFAULT_EXPIRY_SECONDS=300
XIAN_SHIELDED_RELAYER_MAX_EXPIRY_SECONDS=1800
XIAN_SHIELDED_RELAYER_METRICS_ENABLED=1
XIAN_SHIELDED_RELAYER_METRICS_PUBLIC=0
XIAN_SHIELDED_RELAYER_RATE_LIMIT_REQUESTS_PER_MINUTE=120
XIAN_SHIELDED_RELAYER_RATE_LIMIT_BURST=30
XIAN_SHIELDED_RELAYER_RATE_LIMIT_TRUST_PROXY=0
XIAN_SHIELDED_RELAYER_JOB_HISTORY_LIMIT=256
XIAN_SHIELDED_RELAYER_JOB_HISTORY_TTL_SECONDS=86400
XIAN_SHIELDED_RELAYER_LOG_REQUESTS=1

The relayer defaults to 127.0.0.1. If you bind it to a non-loopback host, you must also set XIAN_SHIELDED_RELAYER_AUTH_TOKEN.

When enabled, the relayer also exposes a Prometheus-style metrics endpoint at /metrics. The backend endpoint catalog includes that URL as shielded_relayer_metrics.

Run a localnet workload:

python3 ./scripts/backend.py localnet-init --nodes 4 --topology integrated --clean
python3 ./scripts/backend.py localnet-up --wait-for-health --rpc-timeout-seconds 120
python3 ./scripts/backend.py localnet-workload --scenario counter_basic

Run the richer 5-validator testnet-shaped governance exercise:

make localnet-validator-governance

Run the broader layered 5-validator e2e harness:

make localnet-e2e

Run the same layered harness with xian_vm_v1 in native-authority mode:

make localnet-vm-e2e

Run the tuned VM throughput sweep on a fresh 5-node localnet:

make localnet-vm-tps-bench

Run the benchmark directly against an already-running localnet:

uv run --project ../xian-py --python 3.14 python3 ./scripts/localnet-tps-bench.py \
  --scenario both \
  --ops 4000 8000 12000 \
  --wallet-count 64 \
  --submit-workers 128 \
  --receipt-timeout-seconds 120 \
  --broadcast-mode checktx

The benchmark writes JSON artifacts under .artifacts/tps-bench/. The most useful throughput numbers are:

• committed_workload_tps: workload transactions divided by the committed block window
• committed_chain_tps: all committed transactions in that same block window
• workload_tps: end-to-end client-side workload submission rate
• peak_block_tps: highest instantaneous per-block rate inside the committed window

Use committed_workload_tps as the main chain-throughput figure. workload_tps is still useful for spotting client-side admission or confirmation bottlenecks.

Inspect the current VM rollout posture and mismatch counters across the running localnet:

make localnet-vm-report
python3 ./scripts/backend.py localnet-vm-report

The localnet generator now exposes the Xian app metrics endpoint separately from the CometBFT metrics endpoint, so the VM rollout report reads the native/shadow observability data from the app-side 9108 exporter rather than the 26660 CometBFT metrics port.

When the monitoring stack is enabled, Grafana now also provisions a dedicated Xian VM Runtime dashboard, a dedicated Xian BDS Recovery dashboard, and VM summary panels on the existing overview and preset dashboards. Example Alertmanager routing is included under monitoring/alertmanager/ for the VM mismatch and BDS recovery alerts.

Export or import the standardized BDS recovery snapshot:

python3 ./scripts/backend.py bds-snapshot-export
python3 ./scripts/backend.py bds-snapshot-import

By default the archive lives at:

.cometbft/snapshots/xian-bds-snapshot.tar.gz

Plan or apply a coordinated workspace release:

python3 ./scripts/release_orchestrator.py plan
python3 ./scripts/release_orchestrator.py apply

The localnet-e2e harness now also validates direct currency.approve / transfer_from behavior and the permit_authorizer -> approve_from_authorizer path against the same 5-validator testnet-shaped network.

Principles

• xian-stack owns runtime plumbing, images, and smoke-tested local flows. User-facing lifecycle orchestration belongs in xian-cli.
• The stable machine-facing contract is scripts/backend.py. The Makefile remains the developer and debugging surface.
• Monitoring, dashboard, and BDS are optional stack layers. They should be easy to enable without becoming required to understand the core node.
• xian-intentkit can be attached as another optional stack-managed service without copying its compose topology into this repo.
• The shielded relayer is another optional stack-managed service. It exposes a proof-bound private-submission HTTP surface without changing the node runtime itself.
• Localnet and smoke flows matter as product safety nets, not just as internal convenience scripts.

Key Directories

• docker/: runtime images and container build definitions
• scripts/: backend control plane, smoke flows, and localnet tooling
• monitoring/: Prometheus, Grafana, dashboards, and alert presets
• workloads/: localnet workload fixtures and contracts
• docs/: repo-local runtime and release notes

What It Can Do

• build and run the local Xian runtime in integrated or fidelity topology
• run canonical-network nodes from pinned published xian-node release images while keeping source builds available as a local override
• expose a stable machine-facing backend command surface through scripts/backend.py
• start optional dashboard, BDS, Prometheus, and Grafana layers
• start an optional stack-managed shielded relayer for proof-bound private submission
• attach a stack-managed xian-intentkit deployment while keeping its repo and compose files independent
• run smoke checks and CLI-driven smoke flows
• initialize multi-node localnets and drive workload scenarios against them
• ship monitoring dashboards and alert rules that match the validated operator profiles

Backend Surface

The stable backend interface is scripts/backend.py. It covers:

• validate
• start, stop, and status
• endpoints and health
• bds-snapshot-export and bds-snapshot-import
• smoke and smoke-cli
• localnet-* flows

Use the Makefile directly for lower-level debugging, image builds, and developer shell access.

Use xian-cli for the human-facing operator workflows built on top of this backend contract.

Validation

make validate
make smoke
make smoke-cli

make smoke is the main repo safety net. make smoke-cli is the cross-repo operator-flow gate.

Related Docs

• AGENTS.md
• docs/ARCHITECTURE.md
• docs/BACKLOG.md
• docs/README.md