Status: implemented — P-D1…P-D6 all landed (2026-09-11). This note remains the design rationale; see §6 for the per-phase state. Author: 2026-09-11. Thesis: every Logos module that lets a user do something should become a Muster driver, so the module is infrastructure for doing that thing with other people, securely and privately. This note works out how to think about that and a phased plan to get there.
Muster's coordination surface is already driver-generic. The pieces a "module → driver" story must fit into:
- The
Driverinterface (module/src/drivers/driver.nim) is tiny and coordination-only:describe() -> DriverDescriptor—{rounds, serializationDomain, finality, threshold}. The core routes purely on this (invariant 6): it never reads contribution bytes.canonicalize(effect) -> Materialization— the effect's deterministic signable bytes (materialization.nim, Safe's is EIP-712safeTxHash).verifyContribution(c, round) -> bool— the driver alone reads the bytes.
- Drivers register by kind (registry.nim):
newDriver("safe"|"threshold"|"frost"|"stub", config). Adding a coordination policy is onecasearm + passing conformance. - Execution is the core's job, not the driver's. The Safe driver canonicalizes to a hash;
coordinate_submitin muster_module.nim gathers the folded signatures, re-derives the hash (invariant 1), assemblesexecTransaction, and submits overlp_*. The driver describes what to sign; the core does the doing. - The card vocabulary (ui/src/qml/MusterCard.qml) is closed: address-share, intent-propose (status rail: proposed → collecting → executable → submitted → final; approval slots; the honesty caveat), receipt. A proposal card renders from the verified
coordinate_intentsfold, never from posted JSON. - The SDK already parses LIDL (logos-nim-sdk):
lidl-genturns a.lidlcontract into a provider surface and a typed consumer client per dependency, andPluginProxycalls any module by name overlp_*.
So the raw materials exist. The question is the mapping.
A Logos module method is method verb(args...) -> result. Coordinating it means the
same lifecycle Safe already runs, generalized:
module method ──► EFFECT the typed intent to call verb(args)
(LIDL) {module, method, args}
│
▼ driver.canonicalize (dCBOR, domain-separated) ── inv 5
MATERIALIZATION the exact bytes the room signs
│
▼ coordinate_propose → fold → k-of-n endorsements ── inv 4,6
EXECUTABLE the room agreed
│
▼ core re-derives (inv 1) + lp_invoke module.verb(args)
EXECUTED the module did the thing
│
▼ finality from a named completion event / receipt ── inv R-8
FINAL
The card is the render of that intent: the action verb + args (human-readable,
using the LIDL @brief/@param descriptions), the approval slots (threshold), the
status rail, and the honesty caveat / provenance. It's the existing intent-propose
card, parameterized by the effect's schema instead of hardcoded to a Safe transfer.
Reading the real delivery contract (delivery_module.lidl) makes the boundary concrete.
Mechanical (derivable from the contract):
- The effect schema — the method's typed params (
send(contentTopic: tstr, payload: bstr)→ effect{contentTopic, payload}). - A generic canonicalization — dCBOR over
{module, method, args}with a domain tagmuster.invoke.<module>.<method>.v1(invariant 5, deterministic). - The card copy — the
@briefbecomes the action label, each@paramlabels a field. LIDL descriptions are rich (doxygen-style) — real UX text, free. - The call itself — the SDK's
genClientalready emitsproxy.callSync("verb", args(...)); execution reuses it.
Not mechanical (LIDL is an API description, not a coordination spec) — three gaps:
- Which methods are coordinatable actions. Most methods are reads or infrastructure —
version(),getNodeInfo(),getAvailableConfigs(),collectOpenMetricsText()are queries;createNode/start/stopare node lifecycle. Delivery is the pipe, not a "do something with others" module at all. The interesting ones are actions others must co-authorize or want to do together (a transfer, a vote, a shared-fund spend, a group grant). LIDL doesn't mark side-effects; the signal is semantic (the@briefmentioning funds/ownership/approval/state-change) and curatorial (a human, or an annotation, says "this one is coordinatable"). Naming heuristics (get*/version= read) prune the obvious reads. - The authorization model — who may endorse and how many. LIDL is silent. Default: the room roster is the authority (k-of-n over the conversation's members, exactly like the threshold/frost drivers — the conversation is the security boundary). Some modules carry their own authority (a Safe's owners, a DAO's members); those override the default and need module-native verification.
- What "done" means.
sendreturns arequestIdand completion arrives on amessageSent/messageErrorevent — that'sfinExternalfinality tied to a named event. An on-chain call is a receipt. An in-module state change may befinImmediate. The completion signal is declared, not inferred.
The bulk of modules need no new Nim code at all. Add one driver kind, invoke,
parameterized by config discovered from the module:
newDriver("invoke", {
"module": "<name>", "method": "<verb>",
"argSchema": [...], # from LIDL, for canonicalize + card
"domain": "muster.invoke.<module>.<method>.v1",
"roster": <room members' Ed25519 keys>, # default authority
"threshold": <k>,
"finality": {"kind": "event", "event": "messageSent"} # or "immediate"/"receipt"
})
describe→{rounds: 1, threshold: k, finality, domain}.canonicalize→ dCBOR over{module, method, args}under the domain (invariant 5).verifyContribution→ an Ed25519 roster endorsement — reuse the threshold driver's verify verbatim. "We, the room, agree to make this call."- Execution → a
coordinate_submit-style path: on executable, the core re-derives (invariant 1),lp_invokesmodule.method(args)(the SDK client), and observes the declared finality signal.
This makes any module action coordinatable the moment the module is loaded,
authorized by the room, with zero per-module code. It is a threshold driver whose
materialization is a call intent and whose completion is an lp_invoke.
When a module has its own signing or authority model — Safe (EIP-712 + secp owners),
a chain tx, a module that itself checks a signature set — the generic dCBOR
materialization is wrong: the bytes must match that module's expected signed form.
This is exactly today's Safe driver, and it stays hand-written. The derivation tool
generates the effect schema + card + a driver skeleton and flags canonicalize /
verifyContribution as "implement against the module's format" (with the LIDL
description and the Safe driver as the worked example).
lidl-gen driver <contract.lidl> emits, per curated coordinatable method:
- the effect schema (params) and its dCBOR domain tag,
- a card descriptor (label + fields from
@brief/@param) the UI renders, - for Tier 0: an
invoke-driver registration recipe (config, not code), - for Tier 1: a driver skeleton to complete.
Curation is an annotation on the contract (a @coordinatable marker, or a sidecar
list) plus the read-pruning heuristic — never a silent guess.
Muster enumerates the user's loaded modules (lp_get_methods via the SDK's
methodsOf, or the host module registry), filters to coordinatable actions, and lists
them: "your modules let you do these things with others." Picking one opens the
composer for that effect → propose → the room approves → the core invokes the module.
The module is now infrastructure for doing that thing together.
- Inv 3 (plugins never sign / touch network). The driver never invokes anything — it describes and verifies. The core (
muster_module, which already calls delivery and the Safe RPC) does thelp_invoke, exactly ascoordinate_submitsubmitsexecTransactiontoday. No new network surface in the sandbox. - Inv 1 (re-derive, refuse on mismatch). Execution re-derives
canonicalize(effect)and checks it against the signed materialization before invoking. Generic dCBOR is deterministic, so re-derivation is exact. - Inv 5 (deterministic bytes). The generic canonicalize is dCBOR (muster's existing encoder) under a per-
(module, method)domain-separatedhash-input. No ad-hoc concatenation. - Inv 6 (core never interprets contributions). The
invokedriver reads the endorsement bytes; the core routes on the boolean + descriptor. A derived driver is just anotherDriver. - Inv 10 (provenance). The effect's args are proposer inputs (composer blocks); the provenance record accounts for them exactly as for a Safe transfer.
- Conformance. Every derived/registered driver must pass
checkConformance(conformance.nim) — theinvokedriver passes as a threshold-shaped driver; Tier-1 skeletons must be completed to pass. A driver that doesn't pass conformance doesn't ship.
The one genuinely new mechanism is the generic execution path — a driver-described
lp_invoke after threshold, with finality from a named event. It generalizes the Safe
submit path; it does not weaken any invariant, because "the core invokes a module after
the room agreed and the client re-derived" is precisely what Safe settle already is.
Each phase is independently useful and shippable.
- P-D1 — the generic
invokedriver + conformance. Add theinvokekind to the registry: describe/canonicalize (dCBOR call-intent)/verify (roster Ed25519). PasscheckConformance. Unit + property tests (convergence under reorder/dup, invariant 5 determinism). No UI yet. This is the foundational abstraction. - P-D2 — the generic execution path. A
coordinate_submit-style route forinvokeintents: re-derive →lp_invoke module.method(args)(SDK client) → observe finality (event/immediate). Headless test against a stub module + the local transport (never mockDriver/Transport). - P-D3 — discovery + curation. Enumerate loaded modules (
methodsOf/registry), prune reads by heuristic, honor a@coordinatableannotation, and expose the coordinatable-actions list through acoordinate_available_actionslidl method. - P-D4 — the generic action card. Generalize the intent-propose card to render an arbitrary effect schema (label + fields from LIDL descriptions), fed by the fold. qmllint + the render harness.
- P-D5 —
lidl-gen drivermode. ✅ Done (logos-nim-sdk PR #1).lidl_gen driver contract.lidl out.nim [coordinatable-csv] [tier1-csv]emits, per curated action: the effect schema + its dCBOR domain tagmuster.invoke.<module>.<method>.v1(byte-exact with the invoke driver), the intent-propose card copy (label from the LIDLdescription, fields from the params), a Tier-0 invoke-driver config, and a Tier-1Driverskeleton (block comment) to complete. Only the mechanical parts are derived; curation (coordinatable-csv) and the auth model (tier1-csv) are declared, never guessed. 28 headless tests; the emitted manifestnim checks clean. - P-D6 — a second real driver end-to-end. ✅ Done. Tier 0:
coordination_invoke_testnow coordinates a second, distinct module action (vote_module.cast) over the same generic invoke driver — different signed bytes (invariant 5), same propose→endorse→executable→execute path — proving genericity beyonddelivery.send. Tier 1:module/src/drivers/eip191.nim— an EIP-191 personal-sign driver, the worked completion of the P-D5 skeleton: a module-nativecanonicalize(the EIP-191 digest, not generic dCBOR) +verifyContribution(secpecrecoverto a configured signer set, not the Ed25519 roster). Registered (newDriver("eip191", …)), conformant (the standingconformance_testblock 9 + a dedicatedeip191_test), and compiled into the plugin. Room-native: it's a founding driver kind, anddriverForKind'seip191arm signs over the room's Safe owner set — the one secp address set every instance derives identically, so the fold converges (the Ed25519 membership roster carries no secp addresses; unioning this instance would diverge the count). An "Attest" button in the room's policy picker selects it; the in-app contribute signs the EIP-191 digest with the secp key; its executable card reads "Endorsed — nothing settles on-chain".eip191_room_testproves two owners converge on an attestation through the generic fold.
First step: P-D1 — it's self-contained, invariant-critical, and everything else builds on it. It answers the load-bearing question (can a generic call-intent be a conformant driver?) before any UI or codegen investment.
- The
@coordinatableannotation vs pure curation. Do we propose a LIDL convention (upstream) so modules self-describe their coordinatable actions, or keep a muster-side sidecar list? (Leaning: sidecar first, propose the convention once we have 2-3 real drivers to generalize from.) - Roster authority vs module authority. For Tier 0 the room is the authority — but the module then executes on the room's say-so. Which modules is that safe for? (A message send: fine. A fund movement with no on-chain owner check: the room is the only gate — is that the intended trust model, or does Tier 0 need an allowlist of "room-authorizable" actions?) This is the sharpest design question and should be answered with real modules, not in the abstract.
- Finality declaration. Where does "completion = event X" live — annotation, discovery-time heuristic from the
@returntext, or config? (Leaning: config at registration, defaulted from the description.)