logos-execution-zone-module/doctests/outputs/logos-execution-zone-runtime.md

Running This Execution-Zone Module Against logoscore

logos-execution-zone is a Logos core module that wraps the Logos execution-zone wallet library (wallet_ffi) to provide wallet lifecycle, account management, balance and block queries, transfers, pinata claiming, and account-id encoding. This doc-test exercises this execution-zone-module commit end-to-end through the headless logoscore runtime:

1. Build the logoscore CLI and the lgpm local package manager from their published flakes. logoscore is the headless frontend for logos-liblogos, so building it brings in the whole module-runtime stack (logos_host, liblogos_core, the IPC layer).
2. Build this execution-zone module as an installable .lgx package straight from its own flake's #lgx output, pinned to the commit under test — so the module you run is built from exactly what is checked out here, not the latest published release.
3. Install the .lgx into a ./modules directory with lgpm.
4. Start logoscore in daemon mode (-D), load logos_execution_zone, introspect it with module-info, and call its wallet-free methods — verifying the module actually runs and round-trips real values through wallet_ffi.

The methods exercised here — name/version and the base58 account-id codec (account_id_to_base58 / account_id_from_base58) — are the module's deterministic, offline surface: they need neither an open wallet nor a live sequencer, so a green run is reproducible in CI. The stateful operations (creating accounts, transfers, sync, pinata claims) require a running sequencer and network, and are covered by the module's unit tests (mocked wallet_ffi) and integration tests (real wallet_ffi) instead.

Because the module is built from the commit under test and then loaded and called through a real logoscore daemon, a green run is real evidence that this change keeps the execution-zone module loadable and callable.

What you'll build: This logos_execution_zone module, packaged as .lgx, installed with lgpm, and called through a logoscore daemon.

What you'll learn:

• How to build the logoscore runtime and the lgpm package manager from their flakes
• How a module's flake exposes a ready-to-install .lgx via its #lgx output
• How to install an .lgx into a modules directory with lgpm
• How to start the logoscore daemon, load a module, introspect it, and call its methods
• How to shut the daemon down and confirm it has exited

Prerequisites

• Nix with flakes enabled. Install from nixos.org, then enable flakes:

mkdir -p ~/.config/nix
echo 'experimental-features = nix-command flakes' >> ~/.config/nix/nix.conf

Verify: nix flake --help >/dev/null 2>&1 && echo "Flakes enabled"

• A Linux or macOS machine.

---

Step 1: Build logoscore

Build the logoscore CLI from its published flake. The result is symlinked to ./logos/. logoscore is the headless frontend for logos-liblogos, so this one build brings in the whole module-runtime stack the daemon needs.

1.1 Build the CLI

nix build 'github:logos-co/logos-logoscore-cli' --out-link ./logos

The build produces logos/bin/logoscore plus bundled runtime libraries and a logos/modules/ directory containing the built-in capability_module (required for the auth handshake when loading modules).

---

Step 2: Build the lgpm package manager

lgpm installs .lgx packages into a modules directory and scans what is installed. Build it from the logos-package-manager flake and link it as ./lgpm.

2.1 Build lgpm

nix build 'github:logos-co/logos-package-manager#cli' -o lgpm

The executable is at ./lgpm/bin/lgpm.

---

Step 3: Build and install this execution-zone module

Build this execution-zone module's .lgx straight from its flake's #lgx output and install it into a local ./modules directory with lgpm. Every module built with logos-module-builder exposes a ready-to-install #lgx.

The `` in the URL is what pins the build to a specific commit: the doc-test runner expands it to a concrete ref. Locally that is this checkout's HEAD (see run.sh); in CI it is the commit being tested. With no pin it falls back to the latest master.

3.1 Build the module's .lgx

Build the #lgx output and link it as ./lez-lgx. (This compiles the module and the wallet_ffi library it depends on through Nix, so the first build is slow.)

# From inside the clone this is simply: nix build '.#lgx'
nix build 'github:logos-co/logos-execution-zone-module#lgx' -o lez-lgx

The .lgx package is now under ./lez-lgx/:

ls lez-lgx/*.lgx

3.2 Seed the modules directory with the bundled capability module

logos_execution_zone is loaded through the host's capability layer, so the modules directory also needs the capability_module that ships with logoscore. Copy it across first.

mkdir -p modules
cp -RL ./logos/modules/. ./modules/

3.3 Install the .lgx with lgpm

Install the freshly-built package into ./modules. logos_execution_zone is a core module, so it goes to --modules-dir. The package is unsigned (a local dev build), so we pass --allow-unsigned.

./lgpm/bin/lgpm --modules-dir ./modules --allow-unsigned install --file lez-lgx/*.lgx

3.4 Confirm the install

Scan the directory and confirm the module landed:

./lgpm/bin/lgpm --modules-dir ./modules list

---

Step 4: Run the daemon and call the module

Start logoscore in daemon mode pointed at ./modules, then use the client subcommands to load logos_execution_zone, introspect it, and call several of its methods. Daemon output is captured in logs.txt.

4.1 Start the daemon

Start logoscore in daemon mode in the background, capturing output to logs.txt:

logoscore -D -m ./modules > logs.txt &

The -D flag starts the daemon. The client subcommands below connect to this running process via the config written under ~/.logoscore/.

sleep 3

4.2 Inspect the startup log

Review the daemon's startup output:

cat logs.txt

4.3 Check daemon status

Verify the daemon is running:

logoscore status

4.4 List discovered modules

logos_execution_zone should be visible in the scan directory:

logoscore list-modules

4.5 Load the module

Load logos_execution_zone into the running daemon:

logoscore load-module logos_execution_zone

4.6 Confirm the module is loaded

Re-run status; the module that was not_loaded before now reports loaded:

logoscore status

4.7 Introspect the module with module-info

module-info lists the methods the module exposes — the same methods you can call:

logoscore module-info logos_execution_zone

4.8 Read the module name

name returns the module's own identifier — the simplest possible round-trip through the loaded plugin over liblogos' IPC:

logoscore call logos_execution_zone name

4.9 Read the module version

version returns the module's semantic version (1.0.0), matching metadata.json:

logoscore call logos_execution_zone version

4.10 Encode an account id to base58

account_id_to_base58 takes a 32-byte account id as 64 hex characters and returns its base58 form. This is a pure encoding helper in wallet_ffi — no open wallet and no network required, so it runs entirely offline:

logoscore call logos_execution_zone account_id_to_base58 aaaaaaaa...aaaa  # 64 hex chars

4.11 Round-trip it back to hex

account_id_from_base58 is the inverse: feed it the base58 string we just produced and it returns the original 64-hex account id. Encoding then decoding the same id and recovering the input is a deterministic, end-to-end proof that the codec — and the IPC path to this module — work:

# Encode, then decode the result back — the round-trip returns the input.
B58=$(logoscore call logos_execution_zone account_id_to_base58 aaaa...aaaa)
logoscore call logos_execution_zone account_id_from_base58 "$B58"

4.12 Reject malformed base58

Decoding obvious garbage fails cleanly: account_id_from_base58 returns an empty result rather than crashing the module or the daemon:

logoscore call logos_execution_zone account_id_from_base58 '!!!not-base58!!!'

4.13 Stop the daemon

Shut the daemon down cleanly:

logoscore stop

The daemon removes its state file and exits.

sleep 2

4.14 Confirm the daemon has stopped

With no daemon running, the client reports not_running and exits non-zero, so we add || true to let the doc-test assert on the output:

logoscore status