NXBCL is the experimental blockchain challenge launcher for NXCTF/NXCTL.

Current phase:

Phase 1
  challenge repo + docker compose + manual cloudflared/ngrok export
  NXBCL handles launcher API, PoW/session, sync, and instance records

Phase 2
  NXBCL runtime adapter starts compose, exports RPC, funds wallets, and spawns setup contracts

Phase 3
  Optional formal NXCTL blockchain_rpc service type

nxbcl/
  app.py               # Main entry point (CLI router)
  setup.sh             # Install/build helper
  requirements.txt
  config.yml           # Configuration (gitignored)

  src/
    app/
      cli/             # CLI command handlers
      api/             # FastAPI routes & static server
        static/        # Frontend build output (gitignored)
      services/        # PoW, Session, Registry, Adapter
      runtime/         # Launcher-owned Anvil/RPC/deploy runtime template
      scripts/         # Small module-level utility entrypoints
      tests/           # Backend tests
      utils/           # Config, DB, file_lock

    frontend/          # Vue 3 + Vite UI codebase

  example_chall/       # Example challenge-only repository

From the repository root:

bash nxbcl/setup.sh install

If nxbcl is not found after install:

export PATH="$HOME/.local/bin:$PATH"

Uninstall:

bash nxbcl/setup.sh uninstall

The frontend is a Vue 3 + Vite app served by FastAPI after build.

Install and build:

nxbcl build

The frontend package is pinned to a Vite/Vue toolchain that can run on older Vagrant Node.js installs, and nxbcl/src/frontend/.npmrc disables npm bin symlinks because shared folders often reject symlink creation.

Equivalent direct commands:

cd nxbcl/src/frontend
npm install
npm run build

The build output is written to:

nxbcl/src/app/api/static/

During development, run the API and Vite separately:

nxbcl serve --host 0.0.0.0 --port 8080
nxbcl frontend-dev

Install the command:

bash setup.sh install

Install dependencies and build frontend assets:

nxbcl build

Sync the configured challenge repo into nxbcl/data/chall:

nxbcl sync

Run the launcher API:

nxbcl serve --host 0.0.0.0 --port 8080

Common lifecycle commands:

nxbcl sync
nxbcl up
nxbcl serve --host 0.0.0.0 --port 8080
nxbcl down
nxbcl update
nxbcl uninstall

up brings up the shared Docker Compose stack under nxbcl/data/runtime/chall-runtime and initializes the RPC lease state used by the frontend countdown.

down stops the shared runtime. update pulls launcher updates, reinstalls dependencies, and rebuilds the frontend. uninstall removes the installed nxbcl command from $HOME/.local/bin.

Launcher UI and API docs:

http://localhost:8080/
http://localhost:8080/docs

NXBCL owns the blockchain runtime. Challenge repositories should only contain challenge source files under challenges/; compose files, RPC proxy code, deploy scripts, and generated metadata are managed by the launcher.

nxbcl sync
nxbcl serve --host 0.0.0.0 --port 8080

The launcher copies its runtime template into nxbcl/data/runtime/chall-runtime and starts Anvil/RPC from there. If you need to expose the RPC proxy manually, for example:

cloudflared tunnel --url http://localhost:8545

The public HTTPS URL becomes the RPC_URL returned to players.

If you are exposing the panel or RPC through tunnels, set these config values in config.yml under nxbcl::

nxbcl:
  rpc:
    base_ip: https://rpc.example.com

Leave them empty to keep the local localhost fallback.