Skip to content

docs: trim user-facing tutorial, sdk, testing and scripts docs #602

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
mfw78 merged 3 commits into from
Jul 25, 2026
Merged

docs: trim user-facing tutorial, sdk, testing and scripts docs #602

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
3ae1339
docs: trim user-facing docs, retarget the first-module tutorial
mfw78 Jul 25, 2026
5743c6e
docs: unwrap paragraphs to one logical line for diff-friendliness
mfw78 Jul 25, 2026
abd9614
Merge remote-tracking branch 'origin/dev/m1' into docs/598-user-docs
mfw78 Jul 25, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
80 changes: 0 additions & 80 deletions docs/qa-signoff.md
View file
Open in desktop

This file was deleted.

103 changes: 18 additions & 85 deletions docs/sdk.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,45 +1,20 @@
# The module SDK: nexum-sdk + videre-sdk

`nexum-sdk` is the guest-side library every module consumes: typed
primitives, ABI helpers, an effect-trait seam for testing, the
`#[nexum_sdk::module]` attribute macro and per-module adapter macro,
and a `prelude` that keeps boilerplate out of module crates.
`videre-sdk` layers the venue surface on top: the typed venue client,
the intent-body codec, the `VenueAdapter` seam and the keeper run.
Modules that talk to a venue depend on both crates and import each
directly (nothing is re-exported between them).

This page is the entry point. The full API reference is the rustdoc
site under `target/doc/nexum_sdk/` and `target/doc/videre_sdk/`,
generated by:
`nexum-sdk` is the guest-side library every module consumes: typed primitives, ABI helpers, an effect-trait seam for testing, the `#[nexum_sdk::module]` attribute macro and per-module adapter macro, and a `prelude` that keeps boilerplate out of module crates. `videre-sdk` layers the venue surface on top: the typed venue client, the intent-body codec, the `VenueAdapter` seam and the keeper run. Modules that talk to a venue depend on both crates and import each directly (nothing is re-exported between them).

This page is the entry point. The full API reference is the rustdoc site under `target/doc/nexum_sdk/` and `target/doc/videre_sdk/`, generated by:

```sh
RUSTDOCFLAGS="-D warnings -D missing-docs" cargo doc -p nexum-sdk -p videre-sdk -p nexum-module-macros -p videre-macros --no-deps --open
```

## Authoring a module

Modules are authored with the `#[nexum_sdk::module]` attribute
(re-exported from `nexum-module-macros`). Apply it to an inherent `impl`
block whose associated functions are the named event handlers -
`init`, `on_block`, `on_chain_logs`, `on_tick`, `on_message` - each
taking its wit-bindgen payload and returning `Result<(), Fault>`.
The macro generates the rest of the per-cdylib glue: the
`wit_bindgen::generate!` call, the `bind_host_via_wit_bindgen!()`
adapter, a `Guest` impl whose `on_event` dispatches to whichever
handlers are present (absent handlers no-op), and `export!`. See
[doc 05](05-sdk-design.md#the-nexum_sdkmodule-macro) for a worked
example and the `nexum-module-macros` rustdoc for the fine print.
Modules are authored with the `#[nexum_sdk::module]` attribute (re-exported from `nexum-module-macros`). Apply it to an inherent `impl` block whose associated functions are the named event handlers - `init`, `on_block`, `on_chain_logs`, `on_tick`, `on_message` - each taking its wit-bindgen payload and returning `Result<(), Fault>`. The macro generates the rest of the per-cdylib glue: the `wit_bindgen::generate!` call, the `bind_host_via_wit_bindgen!()` adapter, a `Guest` impl whose `on_event` dispatches to whichever handlers are present (absent handlers no-op), and `export!`. See [doc 05](05-sdk-design.md#the-nexum_sdkmodule-macro) for a worked example and the `nexum-module-macros` rustdoc for the fine print.

## Supported host capabilities

The SDK is host-neutral - it does not call wit-bindgen-generated
functions directly. Instead, it exposes traits that mirror the
on-the-wire host interfaces, and modules adapt their wit-bindgen
imports to the traits at the cdylib boundary (the
`bind_host_via_wit_bindgen!` macro generates that adapter). The traits
in [`nexum_sdk::host`][host-doc] and the venue seam in
[`videre_sdk::client`][client-doc] are:
The SDK is host-neutral - it does not call wit-bindgen-generated functions directly. Instead, it exposes traits that mirror the on-the-wire host interfaces, and modules adapt their wit-bindgen imports to the traits at the cdylib boundary (the `bind_host_via_wit_bindgen!` macro generates that adapter). The traits in [`nexum_sdk::host`][host-doc] and the venue seam in [`videre_sdk::client`][client-doc] are:

| Trait | Mirrors | What it does |
|---|---|---|
Expand All @@ -49,86 +24,44 @@ in [`nexum_sdk::host`][host-doc] and the venue seam in
| `Host` | supertrait | Bundles the three core traits; blanket impl |
| `VenueTransport` (videre-sdk) | `videre:venue/client@0.1.0` | Quote, submit, observe, status and cancel against an installed venue adapter |

A module declaring `[capabilities].required = ["chain", "local-store",
"client", "logging"]` in its `module.toml` matches the host trait seam
one-for-one.
A module declaring `[capabilities].required = ["chain", "local-store", "client", "logging"]` in its `module.toml` matches the host trait seam one-for-one.

[host-doc]: ../target/doc/nexum_sdk/host/index.html
[client-doc]: ../target/doc/videre_sdk/client/index.html
[host-doc]: ../target/doc/nexum_sdk/host/index.html [client-doc]: ../target/doc/videre_sdk/client/index.html

## Modules

- [`nexum_sdk::prelude`](../target/doc/nexum_sdk/prelude/index.html)
- bulk re-exports covering the alloy primitives (`Address`, `B256`,
`Bytes`, `U256`, `keccak256`). `videre-sdk` has no prelude; it
re-exports its surface from the crate root.
`Bytes`, `U256`, `keccak256`). `videre-sdk` has no prelude; it re-exports its surface from the crate root.

- [`client`](../target/doc/videre_sdk/client/index.html) - the typed
venue seam (in `videre-sdk`): a `Venue` marker drives `VenueClient`,
which encodes through `IntentBody` before the byte-level
`VenueTransport` seam. `keeper::retry_action` folds a `VenueFault`
into a `RetryAction`.
venue seam (in `videre-sdk`): a `Venue` marker drives `VenueClient`, which encodes through `IntentBody` before the byte-level `VenueTransport` seam. `keeper::retry_action` folds a `VenueFault` into a `RetryAction`.

- CoW-specific pieces live in their own L3 crates rather than the SDK:
`cow_venue::assembly::gpv2_to_order_data` converts the on-chain
`GPv2OrderData` into the typed `OrderData` the orderbook signs
against, and `composable_cow::{Verdict, LegacyRevertAdapter}` give
typed dispatch over the five `IConditionalOrder` custom errors
(`OrderNotValid`, `PollTryNextBlock`, `PollTryAtBlock`,
`PollTryAtEpoch`, `PollNever`).
`cow_venue::assembly::gpv2_to_order_data` converts the on-chain `GPv2OrderData` into the typed `OrderData` the orderbook signs against, and `composable_cow::{Verdict, LegacyRevertAdapter}` give typed dispatch over the five `IConditionalOrder` custom errors (`OrderNotValid`, `PollTryNextBlock`, `PollTryAtBlock`, `PollTryAtEpoch`, `PollNever`).

- [`chain`](../target/doc/nexum_sdk/chain/index.html) - `eth_call`
JSON plumbing (in `nexum-sdk`):
JSON plumbing (in `nexum-sdk`):
- `chain::eth_call_params(to, data)` - build the `[{to, data},
"latest"]` params array.
- `chain::parse_eth_call_result(json)` - parse the `"0x..."` hex
response into bytes.
- `chain::chainlink::read_latest_answer` - Chainlink AggregatorV3
reader over the two helpers above.
(The CoW-specific `LegacyRevertAdapter` - the `chain-error` rpc
revert bytes to a typed `Verdict` - lives in `composable-cow`.)
(The CoW-specific `LegacyRevertAdapter` - the `chain-error` rpc revert bytes to a typed `Verdict` - lives in `composable-cow`.)

- [`host`](../target/doc/nexum_sdk/host/index.html) - host trait
seam plus the SDK's host-neutral `Fault` vocabulary (same cases
as wit-bindgen's, bridged via one-liner converters per module),
in `nexum-sdk`. `config` and `address` parsing helpers sit
alongside it.
seam plus the SDK's host-neutral `Fault` vocabulary (same cases as wit-bindgen's, bridged via one-liner converters per module), in `nexum-sdk`. `config` and `address` parsing helpers sit alongside it.

- [`http`](../target/doc/nexum_sdk/http/index.html) - outbound
HTTP over wasi:http, in `nexum-sdk`.
`http::fetch` performs one synchronous
request from a `wasm32-wasip2` guest; requests and responses are
the standard `http` crate's `Request` / `Response` types, and the
SDK's `Fetch` trait seam, `FetchError` taxonomy, and per-phase
`FetchOptions` timeouts compile on every target for host-free
strategy tests. The module must declare the `http` capability
and list the hosts it may contact in `[capabilities.http].allow`
in its `module.toml`; an off-list host surfaces as the matchable
`FetchError::Denied`, distinct from timeouts and transport
failures. See `modules/examples/http-probe` for a complete
module.
HTTP over wasi:http, in `nexum-sdk`. `http::fetch` performs one synchronous request from a `wasm32-wasip2` guest; requests and responses are the standard `http` crate's `Request` / `Response` types, and the SDK's `Fetch` trait seam, `FetchError` taxonomy, and per-phase `FetchOptions` timeouts compile on every target for host-free strategy tests. The module must declare the `http` capability and list the hosts it may contact in `[capabilities.http].allow` in its `module.toml`; an off-list host surfaces as the matchable `FetchError::Denied`, distinct from timeouts and transport failures. See `modules/examples/http-probe` for a complete module.

## Companions: nexum-sdk-test and videre-test

Add `nexum-sdk-test` as a dev-dep on the module crate to write strategy
tests against in-memory mocks; its `MockHost` covers the chain, local
store and logging seams. `videre-test` is the venue-side kit: codec
vectors and header goldens for conformance runs, plus transport mocks
such as `MockFetch`. See the crate docs
([nexum-sdk-test](../crates/nexum-sdk-test/src/lib.rs),
[videre-test](../crates/videre-test/src/lib.rs)) for the usage
pattern.
Add `nexum-sdk-test` as a dev-dep on the module crate to write strategy tests against in-memory mocks; its `MockHost` covers the chain, local store and logging seams. `videre-test` is the venue-side kit: codec vectors and header goldens for conformance runs, plus transport mocks such as `MockFetch`. See the crate docs ([nexum-sdk-test](../crates/nexum-sdk-test/src/lib.rs), [videre-test](../crates/videre-test/src/lib.rs)) for the usage pattern.

## Versioning

The SDK crates are currently `0.1.0` and live at `crates/nexum-sdk/`
and `crates/videre-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; 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.
The SDK crates are currently `0.1.0` and live at `crates/nexum-sdk/` and `crates/videre-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; 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.
Loading
Loading