feat: use logos-delivery-module journey

[igor-sirotin]

Closes #145

[fryorcraken]

• returned values are not checked
• no version of delivery module is provided (so doc would break with a breaking change).

[fryorcraken]

Critical issue:

1. docs only reference to master HEAD
2. the "released" module in basecamp is not tagged in github
3. API is different between master HEAD and what was released in basecamp (LogosResult vs Bool return value)

[danisharora099]

Hi team, are there any updates on the docs? I'm considering a pre-dogfooding but since this PR is in progress, I can hold off until there is an update on docs here and perhaps do a dogfooding instead.
@igor-sirotin

[igor-sirotin]

Hi team, are there any updates on the docs? I'm considering a pre-dogfooding but since this PR is in progress, I can hold off until there is an update on docs here and perhaps do a dogfooding instead.

Hey @danisharora099! Thanks for looking into it.

I was busy with some stuff and also waiting for some fixes to land into delivery module.
Let me update the doc and dogfood it myself, should be ready in a few days then. I'll ping you

[igor-sirotin]

@danisharora099 @fryorcraken

1. I've updated the doc
2. I've implemented https://github.com/logos-co/logos-delivery-demo according to the doc. Works.

Issues to be resolved

• Running multiple instances (Support external override of all listening ports via environment variables logos-delivery-module#18) — the simplest workaround with portsShift is mentioned in this docpacket. Proper fix is still on the way.
• Payload should be QByteArray, not base64-encoded QString logos-delivery-module#27
• Inconsistent timestamp format across events: messageReceived uses ns-since-epoch, all other events use local ISO-8601 logos-delivery-module#26

I think the docpacket is good to go as is anyway, workarounds are mentioned. As soon as fixes are ready, I'll update the doc. So I'm opening the PR for review now.

[danisharora099]

I'm currently dogfooding this doc. Share updates soon

[jzaki]

Do we need to store api as suggested here, or safe to not?

[danisharora099]

Non-blocking review — used this journey end-to-end while wiring logos-delivery-module v0.1.1 into logos-co/eth-lez-atomic-swaps. Got us from zero to a working downstream module + UI pair on bin-macos-app Basecamp. Feedback below is tracked as separate issues so this PR doesn't need to carry it.

Things that worked straight off the doc:

• Step 2 config flow (getAvailableConfigs → pick default → createNode / start / stop) — no surprises.
• Step 3 events 1–3 (messageReceived, connectionStateChanged, subscribe(contentTopic)) — copy-paste into swap_delivery_adapter.cpp worked first try.
• messageSent / messagePropagated / messageError fired with the documented payload shape on every send path we exercised.

Doc-side follow-ups, consolidated into #270:

• A5 — late-subscriber drain pattern for topic-per-session content topics.
• A7 — subscribe / unsubscribe idempotency contract.
• B3 — macOS XDG_RUNTIME_DIR 104-byte sun_path budget; bites any <repo>/.basecamp/<name>/run layout under /Users/<user>/Developer/….
• B4 — --user-dir for multi-instance testing; prefer over LOGOS_DATA_DIR because the latter appends Dev in non-portable builds.
• C1 — named-module qmldir over relative import "."; the relative form silently produces undefined singleton bindings in bin-macos-app.
• C2 — src = ./. in flake.nix only sees git-tracked files; newly created qmldir / generated resources have to be git add-ed or they silently omit from the LGX.
• C3 — rebuild → reinstall LGX into every --user-dir → restart Basecamp; source rebuild alone isn't enough.

API-side, separate from this PR:

• logos-co/logos-delivery-module#36 — first-class peer count / structured getStatus(). Today we parse the Prometheus text from getNodeInfo("Metrics").
• logos-co/logos-delivery-module#34 — getSubscriptions() or subscribeIfNot(). Today consumers mirror subscription state in-process.
• logos-co/logos-delivery-module#35 — document the subscribe / unsubscribe idempotency contract. Small Doxygen note; also covered doc-side in #270.
• logos-co/logos-delivery-module#37 — publish binary-cache substitutes for zerokit-*, liblogosdelivery-dev, logos-delivery_module-module-lib* on Logos Cachix. Currently 404 for aarch64-darwin + x86_64-linux + x86_64-darwin, so new contributors take the cold-build hit.

Packaging / host side, separate repos:

• logos-co/logos-basecamp#190 — module-proxy logs every Q_INVOKABLE arg verbatim at INFO; needs opt-in redaction.
• logos-co/logos-package-manager#12 + logos-co/logos-basecamp#191 — LGPM_PORTABLE_BUILD variant mismatch. lgpm install rejects the <host> variant bin-macos-app actually loads, and bin-macos-app silently drops the <host>-dev variant lgpm install actually writes. No log line on the silent drop.

Fine to merge as-is.

[igor-sirotin]

Thanks @danisharora099 @jzaki for testing!

I agree there're things that could be improved and I like the approach of having them listed as separate ticket.
But if there's not blocking issues, I'd like to get this merged. Let's iterate.

I'm planning to get a v0.1.2 version published soon with a bunch of fixes, I'll update this doc accordingly then, but I'd ideally avoid postponing this PR even more.

@fryorcraken whose approval do I need to get it?

cc @cheny0 @kashepavadan

[fryorcraken]

@fryorcraken whose approval do I need to get it?

The doc team will take over your PR and takes it from there.

[fryorcraken]

Cross-checked the doc against logos-delivery-demo (the demo this doc is modeled on). Most of the doc is faithful — these are the gaps I found.

Real divergences (will trip up devs)

• Payload encoding is missing. Doc says messageReceived data[2] is the payload as QByteArray. The demo receives it base64-encoded over the QString event channel and decodes it before use (logos_delivery_demo_plugin.cpp:47). A dev following the doc literally will see "binary garbage" payloads and assume the SDK is broken.

APIs the demo relies on but the doc doesn't mention

• getNodeInfo("Metrics") — the demo uses this to render a live libp2p_peers gauge in its status panel (logos_delivery_demo_plugin.cpp:128–138). Useful for any UI that wants to show real connectivity rather than just "started"; worth a "see also" pointer.

Config asymmetry

• Doc presents createNode(cfg) as a runtime input and shows the full JSON schema. The demo hardcodes mode="Core", preset="logos.dev" and a random portsShift (logos_delivery_demo_plugin.cpp:84,89). Either the demo should expose config and become a closer-to-real reference, or the doc should note that hardcoding is the current norm and config-via-host is aspirational.

Aligned (no action needed, noting for completeness)

• Lifecycle methods, event names, v0.1.1 pin, portsShift workaround (issue Docs Standards initial files and folders layout #18), messageReceived timestamp inconsistency (issue Configure roadmap views (Gantt charts) #26), logos-module-builder scaffolding pattern — all match the demo.

cc @igor-sirotin

[igor-sirotin]

Thanks @fryorcraken

Funny enough, I've noticed all exactly the same thing as you mention, but before seeing your comment 😄

https://github.com/logos-co/logos-delivery-demo now points to logos-delivery 0.1.2 and resolves all of the points that you mention. Do you think it makes sense to update this doc to 0.1.2 then, or do it in a separate PR?

[fryorcraken]

Thanks for this journey doc — it matches the integration path we followed in logos-witness (declare delivery_module in metadata.json.dependencies + matching flake.nix input, then call the typed m_logos->delivery_module.* accessor). Two questions where the doc leaves a gap for anyone wiring this into CI:

1. Is compiling the whole module the only way to get the typed accessor?

Step 2 notes that logos-module-builder "automatically generates the typed delivery_module wrapper at build time." In practice, mkLogosModule resolves the declared dependency to its packages.<system>.default and realizes it to extract delivery_module_api.h into the consumer's generated_code/. We verified that even the headers-only output (#include → …-module-headers) build-depends on …-module-lib.drv, so there's no way to obtain the accessor header without compiling the full module — which transitively builds librln/zerokit (the arkworks zk-SNARK chain).

Is that intended? Is there (or could there be) a headers-only / interface-only output so a consumer can generate the typed wrapper without building the entire messaging/RLN stack? Our core never links delivery's .so (it's a separate process at runtime over QtRO) — it only needs the header at build time.

2. What's the intended way to build the delivery dependency in CI?

Following Steps 2/4 verbatim, a cold CI build (GitHub Actions) compiles zerokit, whose cargo-vendor step fetches arkworks crates (ark-snark, criterion, …) from crates.io at build time and gets HTTP 403 on the runner. The exact same zerokit derivation builds fine locally (it's cached) and built green in our CI ~a week ago — so it's a crates.io reachability/rate-limit issue on the runner, not a broken lib.

The doc's "Estimated time" note says build time "depends on your machine and cache state," which suggests a binary cache is assumed — but the doc names no substituter, and the worked example (logos-delivery-demo) has no CI workflow to follow.

Is there a public nix/cachix substituter that hosts the prebuilt delivery_module (+ zerokit/librln) closure that consumers should add to their CI? If not, what's the recommended pattern for building a delivery_module consumer in CI without depending on crates.io reachability? A one-line "add this substituter" in the journey (or a CI snippet in logos-delivery-demo) would close the gap.

Happy to contribute a CI example back if that's useful.

[igor-sirotin]

1. Is compiling the whole module the only way to get the typed accessor?

I'm afraid Logos Core doesn't provide such an option at the moment.
But CDDL will allow this in the future.

2. What's the intended way to build the delivery dependency in CI?

A public cache will be setup soon and can be used by downstream developers:

• https://github.com/status-im/infra-ci/issues/263

But I believe this is out of scope of this journey. CI integration is the same for all modules, so I'd rather have a separate journey (written by Logos Core team I guess). And actually I'd love to use it myself, because at the moment we're just copy-pasting the CI around different modules. But in theory we could even publish a Github Action for Logos modules building

cc @fryorcraken