From b06b1d82ef529c367e75303949619199372b8a4b Mon Sep 17 00:00:00 2001 From: Luiz Gustavo Abou Hatem de Liz Date: Thu, 9 Jul 2026 19:25:31 -0300 Subject: [PATCH 1/2] =?UTF-8?q?docs:=20stale-reference=20sweep=20=E2=80=94?= =?UTF-8?q?=20engine=20rename,=20Dockerfile,=20ADR-0007=20errata=20(#123,?= =?UTF-8?q?=20#108,=20#62)?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - deployment.md: replace the "planned for M5" Dockerfile sketch with a pointer to the real Dockerfile + docker.md; update nexum-runtime log directive examples - qa-signoff.md: nexum-engine → nexum-runtime in crate-dependency row - adr/0007: add errata noting the nexum-engine → nexum-runtime rename and the [patch.crates-io] retirement now that cowprotocol 0.1.0 is on crates.io --- .../0007-upstream-protocol-logic-to-cow-rs.md | 2 ++ docs/deployment.md | 29 +++++++------------ docs/qa-signoff.md | 2 +- 3 files changed, 14 insertions(+), 19 deletions(-) diff --git a/docs/adr/0007-upstream-protocol-logic-to-cow-rs.md b/docs/adr/0007-upstream-protocol-logic-to-cow-rs.md index 3a828f5e..1f28bb2a 100644 --- a/docs/adr/0007-upstream-protocol-logic-to-cow-rs.md +++ b/docs/adr/0007-upstream-protocol-logic-to-cow-rs.md @@ -44,3 +44,5 @@ Lower-priority follow-ons (`OrderUid::from_slice`, retry middleware on `OrderBoo - Guest modules consume `cowprotocol` types directly (gated on the wasm32 feature in item 3). The `shepherd-sdk` crate in M3 may add ergonomic wrappers on top, but those live on the guest side, not behind a WIT boundary. - A follow-on Bleu module - the Rust-side equivalent of `cowprotocol/refunder` (permissionless `invalidateOrder` triggering for expired EthFlow orders) - becomes natural to ship once an ethflow-watcher module lands. Out of scope for M2 but explicitly enabled by the same primitives. - TWAP polling logic (decode `ConditionalOrderCreated`, eth_call `getTradeableOrderWithSignature`, decode return, build `OrderCreation`) and EthFlow event decoding stay entirely in guest module code. The `cowprotocol` crate provides only the types and the orderbook client; the strategy is the module's. + +_Errata: `crates/nexum-engine` was renamed to `crates/nexum-runtime` + `crates/nexum-cli` in the 0.2 refactor. The `[patch.crates-io]` rev-bump mechanism was retired once `cowprotocol 0.1.0` published to crates.io; the workspace now pins it as a normal registry dependency with no git override._ diff --git a/docs/deployment.md b/docs/deployment.md index 2525e2f9..955e0d96 100644 --- a/docs/deployment.md +++ b/docs/deployment.md @@ -151,26 +151,19 @@ For systemd-style production runs, see `docs/production.md`. ## Docker -A reference Dockerfile + Compose file is planned for M5. -Until that lands, build manually: - -```dockerfile -# (sketch — full Dockerfile is planned for M5) -FROM rust:1.91 as build -COPY . /src -WORKDIR /src -RUN cargo build --release -p nexum-cli -RUN rustup target add wasm32-wasip2 \ - && cargo build --target wasm32-wasip2 --release \ - -p twap-monitor -p ethflow-watcher - -FROM gcr.io/distroless/cc-debian12 -COPY --from=build /src/target/release/nexum /usr/local/bin/ -COPY --from=build /src/target/wasm32-wasip2/release/*.wasm /modules/ -COPY engine.toml /etc/shepherd/engine.toml -ENTRYPOINT ["/usr/local/bin/nexum"] +A `Dockerfile` + `docker-compose.yml` ship at the repo root. See +[`docs/deployment/docker.md`](deployment/docker.md) for the full +container workflow. The quick start: + +```sh +cp .env.example .env +$EDITOR .env # paste wss:// RPC URLs +docker compose up -d ``` +The image is published to +`ghcr.io/nullislabs/shepherd:` on every merged commit to `main`. + Mount the `state_dir` as a volume so the redb file survives container restarts. diff --git a/docs/qa-signoff.md b/docs/qa-signoff.md index 808d03e6..8953a78b 100644 --- a/docs/qa-signoff.md +++ b/docs/qa-signoff.md @@ -12,7 +12,7 @@ | `cargo test --workspace` | ✅ | 145 host tests + 1 doctest passing. | | Em-dashes in `crates/`, `modules/`, `docs/` | ✅ | 0. One was in `price-alert/strategy.rs:4` (mine), fixed. | | Em-dashes in `wit/**.wit` | ⚠ | 3 in mfw78's M1 prose. Intentionally left alone; flag for him in upstream review. | -| `warn(unused_crate_dependencies)` on every crate root | ✅ | sdk, sdk-test, nexum-engine, twap, ethflow, price-alert, balance-tracker, stop-loss. | +| `warn(unused_crate_dependencies)` on every crate root | ✅ | sdk, sdk-test, nexum-runtime, twap, ethflow, price-alert, balance-tracker, stop-loss. | | WASM build (`wasm32-wasip2 --release`) | ✅ | All 5 modules build. Sizes: twap 314 KB, ethflow 282 KB, stop-loss 311 KB, price-alert 215 KB, balance-tracker 102 KB. | | String-wrapped errors outside WIT boundary | ✅ | All hits in `crates/nexum-runtime/src/host/impls/*` (FFI boundary - exception per rust-idiomatic skill). No leaks in SDK or modules. | From 9daa3be85bf179ddd13537256c9026e0c25962bd Mon Sep 17 00:00:00 2001 From: Luiz Gustavo Abou Hatem de Liz Date: Fri, 10 Jul 2026 16:28:28 -0300 Subject: [PATCH 2/2] docs: fix the sweep's own stale claims - cowprotocol override, production.md 3.1 Review catches on the stale-reference sweep itself: - ADR-0007 errata and sdk.md Versioning both claimed cowprotocol is a clean 0.1.0 registry dependency "with no git override". The branch's own Cargo.toml pins 0.2.0 WITH an active [patch.crates-io] override to nullislabs/cow-rs (pending the hash-only OrderCreationAppData constructor release). Both now describe that state and point at the patch-block comment as the source of truth. - production.md 3.1 still shipped the "interim" hand-rolled Dockerfile recipe issue #123 flagged; replaced with a pointer to the real root Dockerfile and docs/deployment/docker.md. - 02-modules-events-packaging.md: un-garble the parenthetical the earlier rename made self-contradictory ("was module.toml in earlier drafts" -> "was nexum.toml"). --- docs/02-modules-events-packaging.md | 2 +- .../0007-upstream-protocol-logic-to-cow-rs.md | 2 +- docs/production.md | 47 ++++--------------- docs/sdk.md | 11 +++-- 4 files changed, 17 insertions(+), 45 deletions(-) diff --git a/docs/02-modules-events-packaging.md b/docs/02-modules-events-packaging.md index 430d4114..dc8dfb87 100755 --- a/docs/02-modules-events-packaging.md +++ b/docs/02-modules-events-packaging.md @@ -6,7 +6,7 @@ A module is distributed as a **bundle** - a WASM component plus a manifest that ### Manifest (`module.toml`) -Every module ships with a manifest. The file is named `module.toml` in 0.2 (was `module.toml` in earlier drafts; per [ADR-0001](adr/0001-engine-toml-separate-from-nexum-toml.md) the operator/module split is now explicit). +Every module ships with a manifest. The file is named `module.toml` in 0.2 (was `nexum.toml` in earlier drafts; per [ADR-0001](adr/0001-engine-toml-separate-from-nexum-toml.md) the operator/module split is now explicit). ```toml [module] diff --git a/docs/adr/0007-upstream-protocol-logic-to-cow-rs.md b/docs/adr/0007-upstream-protocol-logic-to-cow-rs.md index 1f28bb2a..9ff06fa3 100644 --- a/docs/adr/0007-upstream-protocol-logic-to-cow-rs.md +++ b/docs/adr/0007-upstream-protocol-logic-to-cow-rs.md @@ -45,4 +45,4 @@ Lower-priority follow-ons (`OrderUid::from_slice`, retry middleware on `OrderBoo - A follow-on Bleu module - the Rust-side equivalent of `cowprotocol/refunder` (permissionless `invalidateOrder` triggering for expired EthFlow orders) - becomes natural to ship once an ethflow-watcher module lands. Out of scope for M2 but explicitly enabled by the same primitives. - TWAP polling logic (decode `ConditionalOrderCreated`, eth_call `getTradeableOrderWithSignature`, decode return, build `OrderCreation`) and EthFlow event decoding stay entirely in guest module code. The `cowprotocol` crate provides only the types and the orderbook client; the strategy is the module's. -_Errata: `crates/nexum-engine` was renamed to `crates/nexum-runtime` + `crates/nexum-cli` in the 0.2 refactor. The `[patch.crates-io]` rev-bump mechanism was retired once `cowprotocol 0.1.0` published to crates.io; the workspace now pins it as a normal registry dependency with no git override._ +_Errata: `crates/nexum-engine` was renamed to `crates/nexum-runtime` + `crates/nexum-cli` in the 0.2 refactor. The `cowprotocol` crate now publishes to crates.io (the workspace pins `0.2.0`), so the PR-#5-head consumption model above is historical; a `[patch.crates-io]` git override to `nullislabs/cow-rs` remains active pending a release with the hash-only `OrderCreationAppData` constructor - see the comment above the patch block in the root `Cargo.toml` for the current state._ diff --git a/docs/production.md b/docs/production.md index c2b22499..f845f80a 100644 --- a/docs/production.md +++ b/docs/production.md @@ -140,45 +140,14 @@ journalctl -u shepherd -f --output=json | jq '.MESSAGE | fromjson?' ## 3. Container deploy: Docker Compose -> **Status note:** the official Dockerfile is tracked as a -> separate issue. Until it lands, build the image locally with -> the multi-stage recipe below; the Compose file is forward- -> compatible with the eventual published image. - -### 3.1 Dockerfile (interim) - -```dockerfile -# syntax=docker/dockerfile:1.6 -FROM rust:1.86-slim-bookworm AS build -WORKDIR /src -RUN apt-get update && apt-get install -y --no-install-recommends \ - pkg-config libssl-dev cmake clang \ - && rm -rf /var/lib/apt/lists/* -RUN rustup target add wasm32-wasip2 -COPY . . -RUN cargo build -p nexum-cli --release -# Build all 5 modules. Add yours here. -RUN cargo build -p twap-monitor --target wasm32-wasip2 --release \ - && cargo build -p ethflow-watcher --target wasm32-wasip2 --release \ - && cargo build -p price-alert --target wasm32-wasip2 --release \ - && cargo build -p balance-tracker --target wasm32-wasip2 --release \ - && cargo build -p stop-loss --target wasm32-wasip2 --release - -FROM debian:bookworm-slim AS runtime -RUN apt-get update && apt-get install -y --no-install-recommends \ - ca-certificates tini \ - && rm -rf /var/lib/apt/lists/* \ - && useradd -r -s /usr/sbin/nologin -d /var/lib/shepherd shepherd \ - && install -d -o shepherd -g shepherd /var/lib/shepherd -COPY --from=build /src/target/release/nexum /usr/local/bin/ -COPY --from=build /src/target/wasm32-wasip2/release/*.wasm /opt/shepherd/modules/ -COPY --from=build /src/modules /opt/shepherd/manifests -USER shepherd -WORKDIR /var/lib/shepherd -EXPOSE 9100 -ENTRYPOINT ["/usr/bin/tini", "--", "nexum"] -CMD ["--engine-config", "/etc/shepherd/engine.toml"] -``` +### 3.1 Dockerfile + +The official multi-stage `Dockerfile` ships at the repo root - it +builds the `nexum` binary, compiles all five module wasms, and runs as +a non-root user under `tini`. Build it with `docker build -t shepherd .` +or let the root `docker-compose.yml` build it for you. The full image +reference (published tags, pinning, .env wiring) is in +[`docs/deployment/docker.md`](deployment/docker.md). ### 3.2 docker-compose.yml diff --git a/docs/sdk.md b/docs/sdk.md index c8ee0f65..14d21da7 100644 --- a/docs/sdk.md +++ b/docs/sdk.md @@ -124,7 +124,10 @@ The SDK crates are currently `0.1.0` and live at `crates/nexum-sdk/` and `crates/shepherd-sdk/` in the shepherd monorepo. They are not yet published to crates.io; modules depend on them via workspace paths. -The `cowprotocol` crate is published to crates.io at `0.1.0`; the -workspace declares `cowprotocol = "0.1.0"` in `[workspace.dependencies]` -with no `[patch.crates-io]` or git overrides. Module Cargo.toml files -that inherit from the workspace pick it up automatically. +The `cowprotocol` crate is published to crates.io; the workspace +declares `cowprotocol = "0.2.0"` in `[workspace.dependencies]`, with a +temporary `[patch.crates-io]` git override to `nullislabs/cow-rs` +pending a release that ships the hash-only `OrderCreationAppData` +constructor (see the comment above the patch block in the root +`Cargo.toml`). Module Cargo.toml files that inherit from the workspace +pick it up automatically.