mirror of
https://github.com/logos-blockchain/logos-execution-zone-module.git
synced 2026-07-08 19:49:26 +00:00
delete output
This commit is contained in:
Iuri Matias
parent
8b42129fb9
commit
45d437656f
@ -1,302 +0,0 @@
|
||||
# Running This Execution-Zone Module Against logoscore
|
||||
|
||||
`logos-execution-zone` is a Logos `core` module that wraps the
|
||||
[Logos execution-zone wallet library](https://github.com/logos-blockchain/lssa)
|
||||
(`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](https://nixos.org/download.html), then enable flakes:
|
||||
|
||||
```bash
|
||||
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
|
||||
|
||||
```bash
|
||||
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
|
||||
|
||||
```bash
|
||||
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`](https://github.com/logos-co/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.)
|
||||
|
||||
```bash
|
||||
# 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/`:
|
||||
|
||||
```bash
|
||||
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.
|
||||
|
||||
```bash
|
||||
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`.
|
||||
|
||||
```bash
|
||||
./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:
|
||||
|
||||
```bash
|
||||
./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`:
|
||||
|
||||
```bash
|
||||
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/`.
|
||||
|
||||
```bash
|
||||
sleep 3
|
||||
```
|
||||
|
||||
### 4.2 Inspect the startup log
|
||||
|
||||
Review the daemon's startup output:
|
||||
|
||||
```bash
|
||||
cat logs.txt
|
||||
```
|
||||
|
||||
### 4.3 Check daemon status
|
||||
|
||||
Verify the daemon is running:
|
||||
|
||||
```bash
|
||||
logoscore status
|
||||
```
|
||||
|
||||
### 4.4 List discovered modules
|
||||
|
||||
`logos_execution_zone` should be visible in the scan directory:
|
||||
|
||||
```bash
|
||||
logoscore list-modules
|
||||
```
|
||||
|
||||
### 4.5 Load the module
|
||||
|
||||
Load `logos_execution_zone` into the running daemon:
|
||||
|
||||
```bash
|
||||
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`:
|
||||
|
||||
```bash
|
||||
logoscore status
|
||||
```
|
||||
|
||||
### 4.7 Introspect the module with module-info
|
||||
|
||||
`module-info` lists the methods the module exposes — the same methods you
|
||||
can `call`:
|
||||
|
||||
```bash
|
||||
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:
|
||||
|
||||
```bash
|
||||
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`:
|
||||
|
||||
```bash
|
||||
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:
|
||||
|
||||
```bash
|
||||
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:
|
||||
|
||||
```bash
|
||||
# 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:
|
||||
|
||||
```bash
|
||||
logoscore call logos_execution_zone account_id_from_base58 '!!!not-base58!!!'
|
||||
```
|
||||
|
||||
### 4.13 Stop the daemon
|
||||
|
||||
Shut the daemon down cleanly:
|
||||
|
||||
```bash
|
||||
logoscore stop
|
||||
```
|
||||
|
||||
The daemon removes its state file and exits.
|
||||
|
||||
```bash
|
||||
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:
|
||||
|
||||
```bash
|
||||
logoscore status
|
||||
```
|
||||
Loading…
x
Reference in New Issue
Block a user