From 3a2caa94de17f0c081876c033afd111713126d19 Mon Sep 17 00:00:00 2001 From: ksr Date: Tue, 30 Jun 2026 19:29:36 +0200 Subject: [PATCH] add: testnet note operator guide --- content/testnets/logos-node-operator-guide.md | 473 ++++++++++++++++++ content/testnets/overview.md | 5 +- content/testnets/v02-release.md | 103 ++++ content/testnets/v02.md | 3 +- 4 files changed, 581 insertions(+), 3 deletions(-) create mode 100644 content/testnets/logos-node-operator-guide.md create mode 100644 content/testnets/v02-release.md diff --git a/content/testnets/logos-node-operator-guide.md b/content/testnets/logos-node-operator-guide.md new file mode 100644 index 000000000..349b5b9ac --- /dev/null +++ b/content/testnets/logos-node-operator-guide.md @@ -0,0 +1,473 @@ +--- +title: "Testnet version 0.2: Node Operator Guide" +tags: testnet +--- + +## Overview + +Run one Logos node with one `logoscore` daemon and one shared modules directory. + +This guide starts these modules: + +| Module | Package | Public ports | +|--------|---------|--------------| +| Blockchain | `blockchain_module` | `3000/udp` | +| Storage | `storage_module` | `8090/udp`, `8091/tcp` | +| Delivery | `delivery_module` | `9000/udp`, `30303/tcp` | + + +Commands assume a Linux host and these default paths: + +```text +/usr/local/bin/logoscore +/usr/local/bin/lgpd +/usr/local/bin/lgpm +/opt/logos-node/modules +/opt/logos-node/packages +/var/lib/logos-node +``` + +Replace `` with the public IPv4 address of the node. +Run the module commands as the same OS user that owns `/var/lib/logos-node`. + +## Install Runtime Tools + +Install `curl`, `jq`, and FUSE support for AppImage binaries. + +```sh +apt-get update +apt-get install -y curl jq wget fuse3 +``` + +Download the Linux release assets from each repository's Releases page: + +| Tool | Repository | +|------|------------| +| `logoscore` | `https://github.com/logos-co/logos-logoscore-cli` | +| `lgpd` | `https://github.com/logos-co/logos-package-downloader` | +| `lgpm` | `https://github.com/logos-co/logos-package-manager` | + +For x86_64 Linux, these were the current download URLs on 2026-06-25: + +```sh +wget https://github.com/logos-co/logos-logoscore-cli/releases/download/v3/logoscore-x86_64-linux.AppImage +wget https://github.com/logos-co/logos-package-downloader/releases/download/pre-release-99d70db-7/lgpd-x86_64-linux.tar.gz +wget https://github.com/logos-co/logos-package-manager/releases/download/pre-release-05b2cf8-7/lgpm-x86_64-linux.tar.gz +``` + +Install the tools under `/usr/local/bin` with the expected command names: + +```sh +install -m755 logoscore-x86_64-linux.AppImage /usr/local/bin/logoscore +tar -xzf lgpd-x86_64-linux.tar.gz +install -m755 lgpd-x86_64.AppImage /usr/local/bin/lgpd +tar -xzf lgpm-x86_64-linux.tar.gz +install -m755 lgpm-x86_64.AppImage /usr/local/bin/lgpm +``` + +Verify: + +```sh +logoscore --help +lgpd --help +lgpm --help +``` + +## Prepare The Host + +Create the runtime user and directories: + +```sh +useradd --system --home /var/lib/logos-node --create-home --shell /usr/sbin/nologin logos +mkdir -p /opt/logos-node/modules /opt/logos-node/packages +mkdir -p /var/lib/logos-node/blockchain-module-devnet +mkdir -p /var/lib/logos-node/storage-module +mkdir -p /var/lib/logos-node/delivery-module +chown -R logos:logos /var/lib/logos-node +``` + +Open these ports on the host firewall: + +```text +3000/udp +8090/udp +8091/tcp +9000/udp +30303/tcp +``` + +## Install Modules + +`lgpd download` downloads the version published in the configured module catalog. +It does not automatically build or fetch the newest commit from the module repositories. +For a testnet, publish the intended module versions in the catalog before operators run these commands. + +Download the module packages from the configured module catalog: + +```sh +lgpd download blockchain_module --output /opt/logos-node/packages +lgpd download storage_module --output /opt/logos-node/packages +lgpd download delivery_module --output /opt/logos-node/packages +``` + +Install all three packages into the shared modules directory: + +```sh +lgpm --modules-dir /opt/logos-node/modules install --file /opt/logos-node/packages/blockchain_module-0.2.0.lgx +lgpm --modules-dir /opt/logos-node/modules install --file /opt/logos-node/packages/storage_module-*.lgx +lgpm --modules-dir /opt/logos-node/modules install --file /opt/logos-node/packages/delivery_module-*.lgx +``` + +Check installed versions: + +```sh +jq -r '.name + " " + .version' /opt/logos-node/modules/*/manifest.json +``` + +## Start Logos Core + +For a first manual run, +start `logoscore` in the foreground with the shared modules directory: + +```sh +cd /var/lib/logos-node +logoscore -m /opt/logos-node/modules +``` + +Keep that terminal open. +Use another terminal for module commands. + +For a detached manual run, +start `logoscore` in daemon mode with `-D`: + +```sh +cd /var/lib/logos-node +logoscore -m /opt/logos-node/modules -D +``` + +For unattended operation, +prefer a systemd service over a manually started daemon. + +Check: + +```sh +logoscore status +``` + +## Blockchain + +Create the blockchain peer file: + +```sh +cd /var/lib/logos-node/blockchain-module-devnet +cat > peers.json <` before running this command. + +```sh +cd /var/lib/logos-node/storage-module +mkdir -p storage-data +cat > config.json <", + "network": "logos.test" +} +EOF +``` + +Fields: + +| Field | Purpose | +|-------|---------| +| `data-dir` | Storage repository path | +| `log-level` | Log verbosity | +| `listen-ip` | Local TCP bind address | +| `listen-port` | Public TCP libp2p port | +| `disc-port` | Public UDP discovery port | +| `nat` | Public IP advertisement mode | +| `network` | Storage network preset | + +The `logos.test` network preset provides the storage bootstrap settings. + +Use fixed `listen-port` and `disc-port`. +Do not leave public nodes on random ports. + +### Optional: Mix Support And Private Queries + +To run storage with mix support, +generate the storage config from the current published mix bootstrap data. +This replaces the basic `config.json` above. + +```sh +cd /var/lib/logos-node/storage-module +cat > make-mix-storage-config.sh <<'EOF' +#!/usr/bin/env bash +set -e + +data_dir=${1:-"./logos-storage-data"} +udp_spr_json=$(curl -s https://logos-storage-network.fra1.digitaloceanspaces.com/v0.2/udp-sprs.json) +tcp_spr_json=$(curl -s https://logos-storage-network.fra1.digitaloceanspaces.com/v0.2/tcp-sprs.json) + +wget https://logos-storage-network.fra1.digitaloceanspaces.com/v0.2/mix-pool.json +mp_path=$(realpath "./mix-pool.json") + +cat < config.json +``` + +Start storage with that config: + +```sh +logoscore load-module storage_module +logoscore call storage_module init @config.json +logoscore call storage_module start +logoscore call storage_module togglePrivateQueries true +``` + +Privately query a known test object: + +```sh +logoscore call storage_module downloadToUrl zDvZRwzkzrrYB6sS1rRpRLt4gBhc1pWoyTSjkfszfmj1seaYYLCZ ./farewell-to-westphalia.pdf false 65536 +``` + +Start: + +```sh +cd /var/lib/logos-node/storage-module +logoscore load-module storage_module +logoscore call storage_module init @config.json +logoscore call storage_module start +``` + +## Delivery + +Create the delivery config: + +Replace `` before running this command. + +```sh +cd /var/lib/logos-node/delivery-module +cat > config.json <" +} +EOF +``` + +Fields: + +| Field | Purpose | +|-------|---------| +| `preset` | Network preset | +| `mode` | Delivery node mode | +| `logLevel` | Log verbosity | +| `tcpPort` | Public TCP P2P port | +| `discv5UdpPort` | Public UDP discovery port | +| `discv5Discovery` | Enable discv5 discovery | +| `nat` | Public IP advertisement mode | + +The `logos.test` preset provides the delivery network bootstrap settings. +`extMultiaddrs` is usually not needed when `nat` advertises the public address. + +Use fixed `tcpPort` and `discv5UdpPort`. +Do not leave public nodes on random ports. + +Start: + +```sh +cd /var/lib/logos-node/delivery-module +logoscore load-module delivery_module +logoscore call delivery_module createNode @config.json +logoscore call delivery_module start +``` + +Check: + +```sh +logoscore call delivery_module getNodeInfo Version +logoscore call delivery_module getNodeInfo MyBoundPorts +``` + +## Health Checks + +Check daemon and modules: + +```sh +logoscore status --json +``` + +Expected modules: + +```text +storage_module +blockchain_module +delivery_module +capability_module +``` + +Check listeners: + +```sh +ss -lntup | egrep '(:3000|:8090|:8091|:9000|:30303|:8080)' +``` + +Expected: + +```text +0.0.0.0:3000/udp +0.0.0.0:8090/udp +0.0.0.0:8091/tcp +0.0.0.0:9000/udp +0.0.0.0:30303/tcp +127.0.0.1:8080/tcp +``` + +Check blockchain: + +```sh +logoscore call blockchain_module get_cryptarchia_info | jq -r .result.value | jq . +``` + +Check delivery: + +```sh +logoscore call delivery_module getNodeInfo MyBoundPorts +``` + +## Optional: Systemd + +For unattended operation, use systemd. + +Recommended pattern: + +- one service for `logoscore`; +- one separate bootstrap service or script for module startup; +- journald output with retention limits. + +Do not start modules from `ExecStartPost` in the `logoscore` service. +If module startup is slow or returns an error, systemd may kill the daemon. + +The daemon service should do only this: + +```ini +[Unit] +Description=Logos Node +After=network-online.target +Wants=network-online.target + +[Service] +User=logos +Group=logos +WorkingDirectory=/var/lib/logos-node +Environment=HOME=/var/lib/logos-node +ExecStart=/usr/local/bin/logoscore -m /opt/logos-node/modules -D +Restart=always +RestartSec=10 +StandardOutput=journal +StandardError=journal + +[Install] +WantedBy=multi-user.target +``` + +The bootstrap script should: + +1. wait for `logoscore status`; +2. load and start storage; +3. load and start blockchain; +4. load and start delivery; +5. tolerate already-loaded modules and slow module starts. + +Cap journal usage: + +```ini +[Journal] +SystemMaxUse=200M +SystemKeepFree=1G +MaxRetentionSec=7day +MaxFileSec=1day +``` + +Prefer `INFO` logs for unattended operation. +Use `DEBUG` only for short troubleshooting windows. diff --git a/content/testnets/overview.md b/content/testnets/overview.md index 54e425f92..a8abb8eca 100644 --- a/content/testnets/overview.md +++ b/content/testnets/overview.md @@ -3,7 +3,7 @@ tags: testnets title: Logos Testnets --- -This page outlines the high-level deliverables available for testing in upcoming Logos testnets. +This page outlines the high-level deliverables available for testing in upcoming Logos testnets. It also includes release notes for released testnets and node operator guides. > [!NOTE] This page mainly lists the public-facing, testable modules and apps. Logos includes substantial R&D critical for launch and enabling these deliverables, beyond what's listed here. @@ -15,3 +15,6 @@ See individual component team roadmaps for full details. ## Testnet Release Notes - [[v02-release|Testnet v0.2 release notes]] + +## Node Operator Guides +- [[logos-node-operator-guide|Testnet v0.2 node operator guide]] diff --git a/content/testnets/v02-release.md b/content/testnets/v02-release.md new file mode 100644 index 000000000..26ad35532 --- /dev/null +++ b/content/testnets/v02-release.md @@ -0,0 +1,103 @@ +--- +title: "Testnet version 0.2: release notes" +tags: testnet +--- + + +## Blockchain + +### Logos Execution Zone + +- LEZ module: other Logos modules can prove and sign arbitrary LEZ transactions. +- LEZ indexer module: any `logoscore` module can follow LEZ state without relying on centralized sequencers. +- LEZ Explorer Basecamp module: inspect LEZ blocks and account state in Basecamp. +- Bridging: move funds between the base layer and LEZ. +- Private transfers: privately receive funds to a well-known key. +- Generalized cross-program calls: invoke programs during execution, supporting flows such as DEX flash swaps. +- Multi-owner accounts: accounts can be controlled by a group. + +### Blockchain + +- Blend Network: network-level protection for block proposers, completing a major part of the PPoS implementation. +- Bridging: support for depositing to and withdrawing from channels, exposed through the Zone SDK. +- Decentralized sequencing: multi-writer channels with built-in conflict management, exposed through the Zone SDK. +- Logos Core migration: the blockchain node can now run through `logoscore` and Basecamp. + +## Storage + +- Anonymity-preserving DHT queries over mix. +- More efficient block protocol. +- Logos Storage module: + - deployed to testnet + - with OpenMetrics support + +## Messaging + +### Delivery + +- Unified library: Delivery is now a single `liblogosdelivery` library with a tiered API: Kernel, Messaging API, and Reliable Channels. +- Messaging API: integration tests, stabilization, and bug fixes. +- Reliable Channel API: new in v0.2 as a developer preview. + - API spec and shape landed. + - First SDS repair implementation added in `nim-sds`. + - SDS wired into Reliable Channels. + - Persistence layer added. +- QUIC transport support added. +- Logos Delivery module: + - deployed to testnet + - with OpenMetrics support, bug fixes, API cleanup, and an updated Delivery dependency. + +### Chat + +- Group chats: de-MLS-backed group messaging without a central delivery service. +- One-to-one chat rebuilt on groups: a two-person MLS group gives multi-device support. +- Key exchange: KeyPackage registry removes the need for out-of-band key-bundle exchange. +- Persistence: identity and conversation state are now persisted. +- Reliability: causal-history gap detection improves synchronization. +- Logos Chat module: + - rebuilt on `logos-rust-sdk`. + - Chat and Delivery modules integrated. + - Chat UI rewritten in QML. + - end-to-end tests added. + +## Basecamp and Apps + +- App Manager: easier entry point for users to install and run core apps. +- Package Manager UI: refreshed install, update, remove, and repository-management flows, including multi-uninstall and clearer upgrade-state handling. +- Module publishing path: easier integration with module release repositories and release indexes that can be loaded into Package Manager UI. +- Process isolation: UI apps load their Qt plugins in separate processes, with improved shutdown and persistence behavior. +- QML packaging: loading and cache behavior cleaned up to make new releases install more reliably. +- Sandbox and auth: hardened QML sandbox and corrected auth-token handling for UI backends. +- App store model: clearer abstraction over apps, plugins, and modules. +- OpenMetrics module: exposes module metrics to Prometheus-compatible systems. + +### LEZ Programs + +- Oracle program (deployed on LEZ) +- Token program (deployed on LEZ) +- DEX program (deployed on LEZ) + +## Logos Core + +### logoscore-cli + +- Daemon/client split. +- Remote client/daemon communication over TCP. +- Python wrapper: `logoscore-py`. + +### Backend + +- Module consumer/provider logic extracted to the C API and wrapped by `cpp-sdk` and `rust-sdk`. +- Restricted module API access through token exchange and caller allow lists. + +### Developer Experience + +- Code generation gives module and UI developers type-safe access to module APIs and generated boilerplate. +- `logos-modules-release-base` gives developers a standard way to build and publish modules and UI plugins for Basecamp and package-management tooling. + +## P2P Module + +- Peerstore management exposed. +- Capability discovery exposed. +- Custom protocol registration supported. +- Modules can be notified when data is available on custom protocol streams. diff --git a/content/testnets/v02.md b/content/testnets/v02.md index ca1c0ffa4..269bcb874 100644 --- a/content/testnets/v02.md +++ b/content/testnets/v02.md @@ -1,5 +1,5 @@ --- -title: Testnet version 0.2: planned scope +title: "Testnet version 0.2: planned scope" tags: testnet --- @@ -75,4 +75,3 @@ tags: testnet ## keycard * public-account LEZ transactions (incl pub to priv) work; with PQ resistance -