Skip to content

sdk.md

Latest commit

 

History

History
67 lines (45 loc) · 6.32 KB

sdk.md

File metadata and controls

67 lines (45 loc) · 6.32 KB
Raw

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:

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 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:

Trait Mirrors What it does
ChainHost nexum:host/chain@0.1.0 JSON-RPC dispatch (eth_call, eth_getLogs, …)
LocalStoreHost nexum:host/local-store@0.1.0 Per-module key-value store
LoggingHost nexum:host/logging@0.1.0 Structured log lines tagged by module
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.

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

Modules

  • nexum_sdk::prelude

    • 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.

  • client - 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.

  • 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).

  • chain - eth_call 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.)

  • host - 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.

  • http - 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 module 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 nexum/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 module 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, videre-test) for the usage pattern.

Versioning

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