From 7dcdccc06c2a34f15ffba33dd56fda38670bdf2e Mon Sep 17 00:00:00 2001 From: cheny0 <67916832+cheny0@users.noreply.github.com> Date: Mon, 11 May 2026 15:02:57 +0800 Subject: [PATCH] Remove stub documents (#255) --- README.md | 4 +- ...art-for-the-logos-execution-zone-wallet.md | 2 +- ...os-app-alpha-to-access-testnet-v0.1-uis.md | 175 --------------- .../run-logos-node-in-headless-mode.md | 188 ----------------- ...e-the-logos-chat-module-api-from-an-app.md | 167 --------------- ...e-logos-delivery-module-api-from-an-app.md | 199 ------------------ 6 files changed, 2 insertions(+), 733 deletions(-) delete mode 100644 docs/core/journeys/build-and-run-logos-app-alpha-to-access-testnet-v0.1-uis.md delete mode 100644 docs/core/journeys/run-logos-node-in-headless-mode.md delete mode 100644 docs/messaging/journeys/use-the-logos-chat-module-api-from-an-app.md delete mode 100644 docs/messaging/journeys/use-the-logos-delivery-module-api-from-an-app.md diff --git a/README.md b/README.md index 5d044918..f8d51522 100644 --- a/README.md +++ b/README.md @@ -40,7 +40,6 @@ The sections below link to the guides and references for what you can build and - [Build instructions](https://github.com/logos-co/logos-app?tab=readme-ov-file#how-to-build) - [Modules](https://github.com/logos-co/logos-app?tab=readme-ov-file#modules) -- [Build and run Logos App (alpha) to access Testnet v0.1 UIs](https://github.com/logos-co/logos-docs/blob/main/docs/core/journeys/build-and-run-logos-app-alpha-to-access-testnet-v0.1-uis.md) — Build and launch the Logos App alpha release to access the Testnet v0.1 user interfaces. ### Logos Execution Zone @@ -60,8 +59,7 @@ The sections below link to the guides and references for what you can build and ### Messaging -- [Use the Logos Delivery Module API from an app](https://github.com/logos-co/logos-docs/blob/main/docs/messaging/journeys/use-the-logos-delivery-module-api-from-an-app.md) — Integrate the Logos Delivery Module API into your application to send and receive messages. -- [Use the Logos Chat Module API from an app](https://github.com/logos-co/logos-docs/blob/main/docs/messaging/journeys/use-the-logos-chat-module-api-from-an-app.md) — Integrate the Logos Chat Module API into your application to enable chat functionality. +- We're working on the content. ### AnonComms diff --git a/docs/apps/wallet/journeys/quickstart-for-the-logos-execution-zone-wallet.md b/docs/apps/wallet/journeys/quickstart-for-the-logos-execution-zone-wallet.md index f8d915d0..4846ec03 100644 --- a/docs/apps/wallet/journeys/quickstart-for-the-logos-execution-zone-wallet.md +++ b/docs/apps/wallet/journeys/quickstart-for-the-logos-execution-zone-wallet.md @@ -36,7 +36,7 @@ LEZ separates account state into public (visible, on-chain) and private (hidden, > [!NOTE] > -> This quickstart covers the public wallet flow only so you can get set up quickly. Privacy-preserving transfers require local proof generation and take longer to run. For the private workflow, see [Send tokens to a private account with the LEZ wallet](../../../apps/wallet/journeys/transfer-native-tokens-on-the-logos-execution-zone.md). +> This quickstart covers the public wallet flow only so you can get set up quickly. Privacy-preserving transfers require local proof generation and take longer to run. For the private workflow, see [Transfer native tokens on the Logos Execution Zone](../../../apps/wallet/journeys/transfer-native-tokens-on-the-logos-execution-zone.md). When a transaction touches the private state, the client runs the private part locally using your private keys and local client data, producing a zero-knowledge proof (ZKP). Validators verify the proof and accept the state update (for example, updating public balances), so the network stays correct even though the private data is never published. diff --git a/docs/core/journeys/build-and-run-logos-app-alpha-to-access-testnet-v0.1-uis.md b/docs/core/journeys/build-and-run-logos-app-alpha-to-access-testnet-v0.1-uis.md deleted file mode 100644 index 0aa3a700..00000000 --- a/docs/core/journeys/build-and-run-logos-app-alpha-to-access-testnet-v0.1-uis.md +++ /dev/null @@ -1,175 +0,0 @@ -# Build and run Logos App (alpha) to access Testnet v0.1 UIs - -> [!IMPORTANT] -> -> This page is not ready to follow as a guide. Expect missing sections, incomplete steps, and placeholders. Use it only to understand what we plan to document and what is still missing. We are actively working to complete and verify this content. - -Applies to: https://github.com/logos-co/logos-app-poc@master -Runtime target: Logos testnet v0.1 (Logos App runs locally, and provides alpha UIs for v0.1 modules/apps) -Last checked: 2026-02-13 -Status: Stub -Owner: @iurimatias -Tracking: GitHub issue [#174](https://github.com/logos-co/logos-docs/issues/174) - -## Outcome + value - -- Outcome (end goal): Build and run the Logos App (alpha) locally so you can open the v0.1 “Simple App” UIs (wallets, explorer, chat, filesharing, mix push). -- Why it matters: Confirms the v0.1 module integration path works end-to-end: the Logos App can expose UI surfaces that interact with Logos Core modules/backends. - -## Audience - -- developer -- tester - -## Known gaps / Blockers - -- Doc Packet missing: - - repo@sha/tag: missing pinned commit / release tag for `logos-app-poc` - - runnable steps inside the app: exact UI clicks to open each v0.1 UI and how to connect each UI to its backend (local vs remote testnet) - - expected outputs: screenshots / success indicators for “app launched” and for each v0.1 UI - - v0.1 limits: which UIs are guaranteed to work, and what “alpha” means for user-facing behavior - - reviewer handle: UNKNOWN -- Notion/repo mapping needed: - - Confirm whether “Logos App (alpha)” for v0.1 is exclusively `logos-app-poc` or also includes other repos (for example module repos, UI repos, or “Logos Node” tooling referenced on the roadmap page). -- Backend wiring unclear: - - The v0.1 roadmap states that “Logos Node can load and start the Blockchain, Storage, and ChatSDK nodes,” but the doc packet does not explain how the Logos App triggers that (or whether this journey assumes backends are already running). - -## Prerequisites - -- OS: macOS or Linux (Windows support UNKNOWN) -- Dependencies: - - Nix (with flakes enabled, or you use the extra experimental-features flags) - - Git - - If not using Nix: CMake (>= 3.16), Ninja, pkg-config, Qt6, and various project dependencies (exact non-Nix setup steps are not documented in this journey and may be painful). -- Accounts/keys: UNKNOWN (depends on whether you run backends locally or connect to a shared testnet deployment) -- Network/chain: - - Logos testnet v0.1: endpoints / chain IDs for connecting UIs are UNKNOWN -- Other: - - If you use zsh, you must quote Nix flake targets like `'.#default'` to avoid glob expansion. - -## Hardware requirements - -- Target devices: x86_64 computer (others UNKNOWN) -- Minimum: UNKNOWN -- Recommended: UNKNOWN -- Storage profile: UNKNOWN - -## Configuration - -- Env vars: - - UNKNOWN - -- Flags: - - `nix build` - build the complete app (default target) - - `nix build '.#default'` - explicitly build the default flake target (quote it in zsh) - - `nix build '.#app'` - build only the main application target - - `nix develop` - enter a development shell with dependencies - - `nix build --extra-experimental-features 'nix-command flakes'` - use when flakes are not enabled globally - -- Config file keys: - - `~/.config/nix/nix.conf`: `experimental-features = nix-command flakes` - enable flakes globally (optional) - -- Default endpoints/ports: - - UNKNOWN (depends on which modules/backends are started and how they are configured) - -## Steps (happy path) - -1. Clone the repo: - - ```sh - git clone https://github.com/logos-co/logos-app-poc - cd logos-app-poc - ``` - -2. Build the app (recommended Nix path): - - ```sh - nix build - ``` - - Notes: - - - If you use zsh and build a specific target, quote it, for example: - - ```sh - nix build '.#default' - ``` - - - If flakes are not enabled globally, run: - - ```sh - nix build --extra-experimental-features 'nix-command flakes' - ``` - -3. Run the app: - - ```sh - ./result/bin/logos-app-poc - ``` - -4. In the Logos App, open one of the v0.1 “Simple App” UIs: - - - Blockchain Wallet (steps UNKNOWN) - - LEZ Wallet (steps UNKNOWN) - - LEZ Explorer (steps UNKNOWN) - - Simple Chat App (steps UNKNOWN) - - Simple Filesharing App (steps UNKNOWN) - - Simple Mix Push Message App (steps UNKNOWN) - - Note: The v0.1 roadmap indicates these UIs are “alpha-state” and controlled via the Logos App. Exact UX flows are not documented here. - -## Expected outputs - -- After step 2: a `result/` directory exists with an executable at `./result/bin/logos-app-poc`. -- After step 3: the Logos App window opens successfully (what you see first is UNKNOWN). -- After step 4: the selected v0.1 UI screen opens inside the Logos App (what “success” looks like for each UI is UNKNOWN). - -## Verify - -- Command: - - ```sh - ./result/bin/logos-app-poc - ``` - -- Expected: - - ```sh - - The app launches without crashing. - - At least one v0.1 UI can be opened from within the app (exact UI navigation is UNKNOWN). - ``` - -## Troubleshooting (top 3-5) - -- Symptom: `nix build '.#default'` fails or behaves oddly in zsh - Cause: zsh glob expansion on unquoted flake targets - Fix/workaround: Quote the target, for example: `nix build '.#default'`. - -- Symptom: `nix build` fails with errors about flakes / nix-command not enabled - Cause: flakes aren’t enabled in your Nix configuration - Fix/workaround: Use `--extra-experimental-features 'nix-command flakes'`, or enable globally in `~/.config/nix/nix.conf`. - -- Symptom: App launches but no data appears in a UI (wallet/explorer/chat/filesharing/etc.) - Cause: The UI likely expects a backend/module/node to be running or configured, but the required endpoints and boot sequence are not documented in this journey. - Fix/workaround: UNKNOWN (needs doc packet describing how the Logos App starts or connects to the v0.1 backends). - -- Symptom: Build is slow or fails due to missing native deps - Cause: Trying to build outside Nix or on an unsupported environment - Fix/workaround: Use the Nix build path (`nix build`) unless you have an explicit non-Nix setup guide. - -## Limits (for Testnet v0.1) - -- Not supported: - - - Stable, production-grade UX/DevEx (v0.1 explicitly prioritizes backend testing; “alpha” UIs) - - Other limitations: UNKNOWN -- Known issues/sharp edges: UNKNOWN (link issues/PRs once identified) - -## References (links) - -- Existing sources: - - - Testnet v0.1 roadmap (Logos App + list of alpha UIs; module integration focus): [https://roadmap.logos.co/testnets/v01](https://roadmap.logos.co/testnets/v01) - - logos-app-poc README (Nix build + run instructions): [https://github.com/logos-co/logos-app-poc](https://github.com/logos-co/logos-app-poc) - - Tracking issue: [https://github.com/logos-co/logos-docs/issues/174](https://github.com/logos-co/logos-docs/issues/174) - - Optional repo map (helps find related module/UI repos): [https://hackmd.io/%40logos-core/B1yfUrcLZl](https://hackmd.io/%40logos-core/B1yfUrcLZl) diff --git a/docs/core/journeys/run-logos-node-in-headless-mode.md b/docs/core/journeys/run-logos-node-in-headless-mode.md deleted file mode 100644 index 1df5b1ba..00000000 --- a/docs/core/journeys/run-logos-node-in-headless-mode.md +++ /dev/null @@ -1,188 +0,0 @@ -# Run Logos Node in headless mode - -> [!IMPORTANT] -> -> This page is not ready to follow as a guide. Expect missing sections, incomplete steps, and placeholders. Use it only to understand what we plan to document and what is still missing. We are actively working to complete and verify this content. - -## Outcome + value - -- Outcome (end goal): Run “Logos Node (Headless Mode)” so it starts the Blockchain Node module, Storage Node module, and Chat Node (ChatSDK interface) without the Logos App UI. -- Why it matters: Proves the Core “headless” runtime path works for v0.1 and can host the baseline node modules that other journeys depend on (wallet UI, filesharing app, chat app). - -## Audience - -- node operator -- developer - -## Known gaps / Blockers - -- Doc Packet missing: exact repo versions for the modules used in testnet v0.1; runnable end-to-end steps for “headless mode” (install/build/run); expected logs/health checks; required config files; module list + load order; how to join the v0.1 network; reviewer handle. (Issue is labeled blocker:needs-doc-packet.) -- Notion/repo mapping needed: - - What repository (or folder) is the authoritative “Logos Node (Headless Mode)” entry point for v0.1 (the dependency diagram names it as a component, but the runnable packaging isn’t documented here). -- Module identifiers missing: - - The exact module names to pass to `logoscore --load-modules` for “Blockchain Node”, “Storage Node”, and “Chat Node” are UNKNOWN. (The dependency diagram uses descriptive labels, not CLI identifiers.) - -## Prerequisites - -- OS: Linux or macOS (supported platforms listed for `logos-logoscore-cli`). -- Dependencies (build tools for `logos-logoscore-cli`): - - CMake (>= 3.14) - - Ninja - - pkg-config - - Qt6 (qtbase) or Qt5 (Core, RemoteObjects) - - Qt6 Remote Objects (qtremoteobjects) -- Additional dependencies observed in the Core PoC setup (may be legacy / may not apply to v0.1 packaging): - - `protobuf-compiler` - - `patchelf` -- Accounts/keys: UNKNOWN (what keys/identity are required for Blockchain/Storage/Chat nodes in headless mode is not documented in the public sources above). -- Network/chain: UNKNOWN (chain ID, bootnodes, RPC endpoints, and any “join testnet v0.1” parameters are not provided in the sources above). -- Other: - - If using Nix builds, you need Nix with flakes enabled (or pass `--extra-experimental-features 'nix-command flakes'`). - -## Hardware requirements - -- Target devices: x86_64 computer (Linux/macOS); aarch64 Linux/macOS also listed as supported by `logos-logoscore-cli`. -- Recommended: UNKNOWN -- Storage profile: UNKNOWN - -## Configuration - -- Env vars: - - UNKNOWN - -- Flags (documented for `logoscore`): - - `--modules-dir ` / `-m ` — directory to scan for modules (plugins). - - `--load-modules ` / `-l ` — comma-separated list of modules to load; dependency-based auto-loading is mentioned. - - `--call ` / `-c ` — call a module method `module.method(...)`, supports `@file` for parameters; can be repeated. - - `--help` / `-h` — show help. - - `--version` — show version. - -- Config file keys: - - UNKNOWN (no public v0.1 “headless node” config format found in the sources above) - -- Default endpoints/ports: - - UNKNOWN (the sources above do not list ports for Blockchain/Storage/Chat modules when running under `logoscore`) - -## Steps (happy path) - -> Notes: -> - The steps below only cover what is directly supported by the public sources: building and starting `logoscore`, and the mechanism for building/copying modules in the (deprecated) Core PoC repo. The exact v0.1 module set and how to connect to testnet are UNKNOWN. - -1. Get the Core runtime (`logos-logoscore-cli`): - - - Option A (Nix build, recommended in repo docs): - - ```sh - git clone https://github.com/logos-co/logos-logoscore-cli.git - cd logos-logoscore-cli - nix build '.#clid' - ``` - - This produces artifacts under `./result/`, including `./result/bin/logoscore`. - - - Option B (manual build): - - ```sh - git clone https://github.com/logos-co/logos-logoscore-cli.git - cd logos-logoscore-cli - git submodule update --init --recursive - ./scripts/compile.sh - ``` - - Expected output locations (per repo docs): libraries in `build/lib/`, binaries in `build/bin/`. - -2. Obtain/build the required node modules (Blockchain Node, Storage Node, Chat Node): - - - UNKNOWN (no public “Doc Packet” describing which repos, which versions, and which build outputs are required for v0.1 headless mode). - - - Implementation clue (legacy Core PoC approach): build modules separately and copy the resulting `*.so/*.dylib/*.dll` plugin libraries into the Core build’s modules directory (example path: `logos-logoscore-cli/build/modules`). - -3. Start Logos Node in headless mode by running `logoscore` and loading the required modules: - - - Minimal “start the runtime”: - - ```sh - ./result/bin/logoscore - ``` - - - Load modules from a specific directory and request a specific load order: - - ```sh - ./result/bin/logoscore --modules-dir /path/to/modules --load-modules MODULE_A,MODULE_B,MODULE_C - ``` - - Replace `MODULE_*` with the real module identifiers for Blockchain Node / Storage Node / Chat Node (UNKNOWN). - -4. (Optional) Invoke module methods after loading (only if the v0.1 module APIs require explicit start calls): - - ```sh - ./result/bin/logoscore -m /path/to/modules -l MODULE_A,MODULE_B \ - --call "MODULE_A.start()" \ - --call "MODULE_B.start()" - ``` - -The mechanism is supported; actual module method names are UNKNOWN. ([GitHub][1]) - -## Expected outputs - -- After building: - - - Nix build: `./result/bin/logoscore` exists. ([GitHub][1]) - - Manual build: binaries in `build/bin/` and libraries in `build/lib/`. ([GitHub][1]) -- After starting `logoscore`: - - - UNKNOWN (no public reference output/log lines for a successful “headless mode” start with Blockchain/Storage/Chat modules) - -## Verify - -- Command: - - ```sh - ./result/bin/logoscore --help - ``` - - ([GitHub][1]) - -- Expected: - - ```sh - - Help output lists flags such as --modules-dir, --load-modules, and --call. - ``` - - ([GitHub][1]) - -> NOTE: A real “node is running on testnet v0.1” verification command/output is UNKNOWN (no chain endpoints, health checks, or module-specific “ready” indicators found in the public sources above). ([GitHub][2]) - -## Troubleshooting (top 3-5) - -- Symptom: `nix build '.#clid'` fails with `#`-related target parsing in zsh. - Cause: zsh glob expansion for `#`. - Fix/workaround: Quote the target, as shown in the repo docs. ([GitHub][1]) - -- Symptom: `logoscore` starts but loads no modules / can’t find plugins. - Cause: modules directory not set correctly (or required module plugins not present). - Fix/workaround: pass `--modules-dir ` pointing to the directory containing the built plugin libraries. ([GitHub][1]) - -- Symptom: Built module `.so` loads fail due to runtime library path issues. - Cause: rpath / dynamic linker can’t resolve dependent libraries (example: Core PoC uses `patchelf` on Linux to set rpath on plugin `.so`). - Fix/workaround: ensure plugin rpath is set; the legacy Core PoC uses `patchelf --set-rpath '$ORIGIN' ` for Linux modules. ([GitHub][3]) - -- Symptom: Build fails due to missing Qt / build tooling. - Cause: missing dependencies (Qt, CMake/Ninja/pkg-config). - Fix/workaround: install the dependencies listed by `logos-logoscore-cli` (and, if following the Core PoC legacy flow, also install `protobuf-compiler` and `patchelf`). ([GitHub][1]) - -## Limits (for Testnet v0.1) - -- Not supported: UNKNOWN -- Known issues/sharp edges: UNKNOWN (no v0.1 headless-node issues/PRs linked from the public sources above) - -## References (links) - -- Journey tracker issue: [https://github.com/logos-co/logos-docs/issues/167](https://github.com/logos-co/logos-docs/issues/167) ([GitHub][2]) -- `logos-logoscore-cli` (Core runtime; provides `logoscore`): [https://github.com/logos-co/logos-logoscore-cli](https://github.com/logos-co/logos-logoscore-cli) ([GitHub][4]) -- Testnet v0.1 dependency diagram (defines “Logos Node (Headless Mode)” and its relationship to Blockchain/Storage/Chat modules): [https://roadmap.logos.co/testnets/v01_dependencies](https://roadmap.logos.co/testnets/v01_dependencies) ([roadmap.logos.co][5]) -- Legacy Core PoC scripts showing how modules were built/copied alongside `logoscore` (may not reflect v0.1 packaging, but illustrates the plugin workflow): - - - [https://github.com/logos-co/logos-core-poc](https://github.com/logos-co/logos-core-poc) (deprecated) ([GitHub][6]) - - `scripts/run_core.sh` ([GitHub][7]) - - `scripts/build_core_modules.sh` ([GitHub][3]) diff --git a/docs/messaging/journeys/use-the-logos-chat-module-api-from-an-app.md b/docs/messaging/journeys/use-the-logos-chat-module-api-from-an-app.md deleted file mode 100644 index 54afeac1..00000000 --- a/docs/messaging/journeys/use-the-logos-chat-module-api-from-an-app.md +++ /dev/null @@ -1,167 +0,0 @@ -# Use the Logos Chat module API from an app - -> [!IMPORTANT] -> -> This page is not ready to follow as a guide. Expect missing sections, incomplete steps, and placeholders. Use it only to understand what we plan to document and what is still missing. We are actively working to complete and verify this content. - -Applies to: - -- https://github.com/logos-co/logos-chat-ui@27e92b9 -- https://github.com/logos-co/logos-chat-module@bce2893 -- https://github.com/logos-co/logos-app-poc@b0b1c69 - -Runtime target: UNKNOWN -Last checked: 2026-01-28 -Status: Stub -Owner: owner needed (recent commits by @iurimatias) -Tracking: Testnet v0.1 docs in scope spreadsheet (num. 15) / Issue: [#141](https://github.com/logos-co/logos-docs/issues/141) - -## Outcome + value - -- Outcome (end goal): Run the demo chat app and confirm you can send and receive chat messages through the Logos Core + Messaging stack. -- Why it matters: Provides an end-to-end smoke test of the demo UX and the integration between the chat UI/module and the underlying messaging backend. - -## Purpose - -Provide a runnable starting point to build and launch the demo chat application for Logos Core and validate basic send/receive flows. - -## Audience - -- Developer - -## Hardware requirements - -- UNKNOWN -- Assumption: standard developer laptop/desktop (this repo set does not document Raspberry Pi / low-power targets). - -## Known gaps - -- Missing Docs Packet. -- It is unclear what exact "ChatSDK" artifacts/config are required for this journey (naming in journey vs repo naming is not mapped). -- It is unclear what messaging network/backend the demo should connect to by default (local vs testnet; which nodes; which bootstrap peers; which topics). -- No documented "success criteria" beyond "app launches"; send/receive validation steps are not documented end-to-end. - -## Prerequisites - -- Nix with flakes enabled (recommended path in repos). - - - If flakes are not enabled: enable nix-command + flakes in your Nix config (exact steps vary by distro). - -- If not using Nix (fallback / partial guidance from older repos): - - - CMake, Ninja, pkg-config - - Protobuf compiler - - patchelf - - UNKNOWN for the exact supported versions per OS. - -## Configuration - -- Env vars: UNKNOWN -- Flags: UNKNOWN -- Config file keys: UNKNOWN -- Default endpoints/ports: UNKNOWN -- Network selection (testnet/local): UNKNOWN - -## Steps - -1. Option A (recommended): Build and run the standalone chat UI app (from `logos-chat-ui`) - - ```sh - git clone https://github.com/logos-co/logos-chat-ui - cd logos-chat-ui - - # Build standalone test app - nix build '.#test-app' - - # Run - ./result/bin/chat-app - ``` - -Notes: - -- If you use zsh, you may need to quote the target (same command, different quoting): - - - `nix build '.#test-app'` - -- The README indicates the standalone app "automatically loads required modules and the chat_ui plugin". - -2. Option B: Build and run Logos App POC (which includes a `logos_dapps/chat_ui` area) - - ```sh - git clone --recurse-submodules https://github.com/logos-co/logos-app-poc - cd logos-app-poc - - nix build '.#app' - ./result/bin/logos-app-poc - ``` - - Notes: - - - The README indicates the app will load required modules/plugins. - - It’s unclear (without SME confirmation) what exact UI flow corresponds to "send and receive messages" in this build. - -3. (Optional / deeper) Build the chat module artifact directly (from `logos-chat-module`) - - ```sh - git clone https://github.com/logos-co/logos-chat-module - cd logos-chat-module - - nix build '.#build_module' - ``` - - Expected artifact location (per README): - - - `result/modules/chat_module` - -## Expected outputs - -- After the Nix build: - - - A `result/` symlink should be created in the repo root. - - Binaries should be available under `result/bin/...` (exact names depend on the option you built). - -- After running the app: - - - A GUI application window should open. - - Terminal logs may show module/plugin loading messages. - -- Send/receive UX: - - - UNKNOWN: no documented UI steps, accounts, peers, or test vectors. - -## Verify - -- Verification command: UNKNOWN -- Manual verification (best available with current info): - - - Launch the app and confirm it loads without fatal errors. - - Attempt to send a message and confirm it appears in the conversation history (requires SMEs to confirm the correct network/backends and UI flow). - -- Expected: UNKNOWN - -## Troubleshooting - -- Nix flakes errors: - - - Symptom: "experimental feature ‘nix-command’ is disabled" or "flakes" errors -> Fix: enable `nix-command` and `flakes` in your Nix configuration. - -- zsh target parsing: - - - Symptom: `nix build .#test-app` fails in zsh -> Fix: quote the attribute: `nix build '.#test-app'`. - -- Qt/C++ build failures (non-Nix path): - - - Symptom: missing Qt/CMake/Ninja/protobuf headers/tools -> Fix: install the required build deps for your OS (exact list/version: UNKNOWN). - -## Limits (v0.1) - -- This journey is not fully specified for v0.1 (network, backends, and success criteria are undocumented here). -- The older `logos-core-poc` repo is marked as deprecated; avoid basing v0.1 work exclusively on it. - -## References - -- [https://github.com/logos-co/logos-chat-ui](https://github.com/logos-co/logos-chat-ui) -- [https://github.com/logos-co/logos-chat-module](https://github.com/logos-co/logos-chat-module) -- [https://github.com/logos-co/logos-app-poc](https://github.com/logos-co/logos-app-poc) -- (Legacy / context) [https://github.com/logos-co/logos-core-poc](https://github.com/logos-co/logos-core-poc) (deprecated) -- (Messaging background, per spreadsheet) [https://github.com/logos-messaging](https://github.com/logos-messaging) diff --git a/docs/messaging/journeys/use-the-logos-delivery-module-api-from-an-app.md b/docs/messaging/journeys/use-the-logos-delivery-module-api-from-an-app.md deleted file mode 100644 index 18077664..00000000 --- a/docs/messaging/journeys/use-the-logos-delivery-module-api-from-an-app.md +++ /dev/null @@ -1,199 +0,0 @@ -# Use the Logos Delivery Module API from an app - -> [!IMPORTANT] -> -> This page is not ready to follow as a guide. Expect missing sections, incomplete steps, and placeholders. Use it only to understand what we plan to document and what is still missing. We are actively working to complete and verify this content. - -Applies to: - -- https://github.com/logos-messaging/nwaku -- https://github.com/logos-messaging/logos-messaging-nim-compose - -Runtime target: local -Last checked: 2026-01-28 -Status: Stub -Owner: Owner needed -Tracking: GitHub issue [#145](https://github.com/logos-co/logos-docs/issues/145) - -## Outcome + value - -- Outcome (end goal): An external developer can publish and retrieve a test message by calling the Logos Messaging (nwaku) REST API. -- Why it matters: Proves the messaging backend is reachable and can be exercised via an API surface for v0.1. - -## Audience - -- developers - -## Known gaps - -- Doc Packet missing -- Logos testnet specifics missing: which network endpoints/bootstraps to use, whether RLN is required, and what "success" means for v0.1 beyond basic API calls. - -## Prerequisites - -- OS: Linux/macOS/Windows (UNKNOWN - not validated; Docker required) - -- Dependencies: - - - git - - Docker + Docker Compose - - curl - - base64 (or an equivalent encoder) - -- Accounts/keys: - - - Linea Sepolia RPC endpoint (required by the provided Docker Compose quickstart for RLN-related setup; provider/account details: UNKNOWN) - - If RLN registration is required: EVM wallet/private key + testnet funds: UNKNOWN (not confirmed for Logos v0.1) -- Network/chain: - - Local node exposes REST API on localhost (default: 8645) - - "Logos testnet v0.1" chain/network identifiers and endpoints: UNKNOWN - -- Other: - - - If you use the provided compose stack, it may include Store + RLN by default (exact toggles: UNKNOWN without the .env.example contents) - -## Hardware requirements - -- Target devices: x86_64 computer -- Minimum: Relay-only node: RAM ~0.5 GB -- Recommended: RAM ~2 GB (especially if WSS is enabled) -- Storage profile: UNKNOWN - -## Configuration - -- Env vars: - - - UNKNOWN (see `.env.example` in the compose repo). At minimum, you must provide a Linea Sepolia RPC endpoint per the quickstart docs, but the exact variable name is UNKNOWN. - - Other RLN/Store-related env vars: UNKNOWN - -- Flags: - - - UNKNOWN (Docker Compose setup; direct `nwaku` flags not captured for this journey) - -- Config file keys: - - - UNKNOWN - -- Default endpoints/ports: - - - 8645/tcp - REST API (examples: `/health`, `/debug/v1/version`, `/store/v1/messages`, `/relay/v1/auto/messages`) - - 3000/tcp - Grafana (when using the Docker Compose stack) - - Other ports (web UI, p2p, metrics): UNKNOWN - -## Steps (happy path) - -1. Clone the Docker Compose deployment repo: - - ```sh - git clone https://github.com/waku-org/nwaku-compose - cd nwaku-compose - ``` - -2. Create your local environment file: - - ```sh - cp .env.example .env - ``` - -3. Edit `.env` with your settings (RPC endpoint and any other required values): - - ```sh - # Use your editor of choice - $EDITOR .env - ``` - -4. Start the stack: - - ```sh - docker compose up -d - ``` - -5. Check the node is up: - - ```sh - curl -i http://127.0.0.1:8645/health - ``` - -6. Check API responds with version info: - - ```sh - curl -s http://127.0.0.1:8645/debug/v1/version - ``` - -7. Publish a test message (Relay API): - - ```sh - curl -X POST "http://127.0.0.1:8645/relay/v1/auto/messages" \ - -H "content-type: application/json" \ - -d '{"payload":"ZXhhbXBsZQ==","contentTopic":"/test/0/ephemeral/proto","version":0,"timestamp":1714373499732887000}' - ``` - -8. Try retrieving messages from Store (may depend on Store config and which Relay endpoint you used): - - ```sh - curl -s "http://127.0.0.1:8645/store/v1/messages?contentTopics=%2Ftest%2F0%2Fephemeral%2Fproto&pageSize=10&ascending=true" \ - -H "accept: application/json" - ``` - -## Expected outputs - -- After step 4: `docker compose ps` shows containers running (exact service names: UNKNOWN). -- After step 5: HTTP 200 response from `/health` (response body: UNKNOWN). -- After step 6: JSON output from `/debug/v1/version` containing version information (exact fields: UNKNOWN). -- After step 7: Successful publish response (commonly "OK"; exact response/body: UNKNOWN). -- After step 8: JSON response from Store query; may be empty depending on Store configuration and publish method. - -## Verify - -- Command: - - ```sh - curl -i http://127.0.0.1:8645/debug/v1/version - ``` - -- Expected: - - ```sh - - HTTP 200 - - JSON payload with version information (exact schema: UNKNOWN) - ``` - -## Troubleshooting (top 3-5) - -- Symptom: POST `/relay/v1/auto/messages` returns `400 Bad Request` with decode/deserialization error. - Cause: Body includes fields not recognized by the running nwaku version (example: `ephemeral`). - Fix/workaround: Remove unsupported fields from the JSON body, or upgrade nwaku to a version that supports them. - -- Symptom: Messages published via `/relay/v1/auto/messages` do not appear when querying Store (`/store/v1/messages`). - Cause: Known behavior/issue: `/relay/v1/auto/messages` may not store messages, while `/relay/v1/messages/{pubsub}` may (implementation-dependent). - Fix/workaround: If you need Store retrieval, use the Store-compatible publish endpoint (if available in your build) and confirm Store is enabled. - -- Symptom: POST publish returns `500 Internal Server Error` and logs mention RLN proof / membership problems. - Cause: RLN membership not registered/loaded, or incorrect RLN credential configuration. - Fix/workaround: Ensure RLN membership setup steps/scripts (if used by the compose stack) were completed and `.env` contains the required RLN-related values (exact keys: UNKNOWN). - -- Symptom: `/health` or `/debug/v1/version` is unreachable (connection refused / timeout). - Cause: Stack not running, REST API not exposed, port conflict, or container failed to start. - Fix/workaround: Check `docker compose ps` and `docker compose logs `; confirm port 8645 is free; restart the stack. - -## Limits (for Testnet v0.1) - -- Not supported: Logos testnet-specific instructions (bootstraps, endpoints, chain IDs, expected v0.1 behavior) are UNKNOWN. -- Known issues/sharp edges: - - - REST API reference link in upstream docs appears broken/outdated (some references point to a 404). - - `/relay/v1/auto/messages` vs Store persistence behavior may be surprising; confirm expected behavior for v0.1 with SMEs. - -## References (links) - -- Existing sources: - - - Inventory spreadsheet points to: [https://docs.waku.org/](https://docs.waku.org/) and [https://github.com/logos-messaging/nwaku](https://github.com/logos-messaging/nwaku) - - Run a Waku Node (nwaku quickstart + system requirements + health check): [https://docs.waku.org/run-node/](https://docs.waku.org/run-node/) - - Run nwaku with Docker Compose (interaction + store query examples): [https://docs.waku.org/guides/nwaku/run-docker-compose](https://docs.waku.org/guides/nwaku/run-docker-compose) - - Compose deployment repo (nwaku-compose fork used by Logos Messaging): [https://github.com/logos-messaging/logos-messaging-nim-compose](https://github.com/logos-messaging/logos-messaging-nim-compose) - - Example publish request + deserialization behavior (`/relay/v1/auto/messages`): [https://github.com/waku-org/nwaku/issues/2643](https://github.com/waku-org/nwaku/issues/2643) - - Store persistence behavior note (`/relay/v1/auto/messages` vs `/relay/v1/messages/{pubsub}`): [https://github.com/waku-org/nwaku/issues/3362](https://github.com/waku-org/nwaku/issues/3362) -- Optional: - - - REST API reference: some upstream links point to [https://waku-org.github.io/waku-rest-api/](https://waku-org.github.io/waku-rest-api/) but availability/version for Logos v0.1 is UNKNOWN