WebAssembly Plugins: ABI Reference
Files
| File | Runs on | What |
|---|---|---|
nanoconda.h (native, repo root) |
native only | The real header, untouched. |
nanoconda.h (wasm directory) |
guest | The derived guest SDK; #include this directly from your strategy. |
nanoconda_wasm_abi.h |
both | The wire contract: struct mirrors and every function crossing the host/guest boundary. Plain C, so any language targeting wasm32 can implement it. |
nanoconda_wasm_host.h |
host | Header-only wasmtime glue: imports, the admin sequence, callback forwarding. Built into nanoconda-cli's -a pluginloader, nothing to build yourself. |
example_client.cpp |
guest | Minimal strategy example (reproduced in full in Building & Running). |
The guest SDK (nanoconda.h) is a minimal-diff derivative of the real, native header: every enum, POD struct, and the listener interface are unconditional, identical source. Only dmasession, logger, and a few free functions carry small #if defined(__wasm__) sections where the implementation differs (real libnanoconda calls vs. ABI imports); all wasm-specific method bodies live together in one section at the bottom of the file, as out-of-class definitions. To see exactly what's wasm-specific: diff nanoconda.h wasm/nanoconda.h.
For the full type reference (struct fields, enum values), since these are byte-identical between native and wasm, see the native Order Entry API, Market Data API, and Algo Control API pages. This page covers only what's specific to the wasm boundary itself.
ABI versioning
NC_WASM_ABI_VERSION in nanoconda_wasm_abi.h is checked by HostRuntime::load() against the guest's own nc_abi_version() export at load time. A guest built against a different ABI version than the host expects fails to load outright, rather than running with a silently mismatched struct layout. Bump this constant on any struct or signature change to the ABI.
Adding an optional callback export does not change NC_WASM_ABI_VERSION. A guest that does not export a callback simply does not receive it, so guests built with earlier headers keep loading. For example, nc_cb_onslowconsumer (2026-11-19) is delivered only to guests built with headers that include it.
Every mirrored struct's size is additionally static_assert-checked against the real, native nanoconda.h at host build time: a struct-layout drift between the native and wasm headers is a compile-time failure on the host side, not a runtime data-corruption bug.
Linkage
Wasm import/export binding is controlled by __attribute__((import_name/export_name)), not by C++ symbol linkage, so plain C++ linkage is enough everywhere in guest code, with exactly one exception: init_nanoconda_plugin is declared extern "C" purely so it has the same language linkage as the native .so entry point of the same name, which is what lets unmodified native client code build for wasm too without any changes. Nothing else in the ABI or in guest code needs extern "C"; declare nanoconda::requestShutdown() and everything else with plain C++ linkage.
Logging
logM/logL/setLevel expand to logMessage/logMessageL/setLevelL, exactly as they do natively. Your strategy class needs one of these visible, typically by inheriting nanoconda::logger. They format locally in the guest (vsnprintf) and send the formatted result to the host's real nanoconda::logger; there is no separate stdio/printf path a guest can use instead.
nanoconda::logger() (no-arg constructor) routes to the host's default logger (handle 0, whichever file nanoconda-cli -a pluginloader's -l/--log named), so host-side and guest-side log messages land in the same file. Pass a filename to the constructor instead for a second, independent log file.
State persistence
nanoconda::saveState/loadState read and write the file given by nanoconda-cli -a pluginloader's -f/--statefile argument. This is the supported way for a guest to persist data across restarts: the wasm sandbox doesn't give a guest direct filesystem access, so this ABI call is the only path to durable state. See the example strategy for the calling convention (loadState in init_nanoconda_plugin, saveState in plugin_stop).
Admin-sequence calls: declared but no-op on the guest
registerApplication, dmasession::init, subscribe, subscribeUnderlying, start, stop, and replayTrace are all declared on the guest-side dmasession, matching native exactly (no #ifdef needed in shared client code), but their wasm-side bodies are no-ops; the host already performed the equivalent action from its own CLI arguments before your guest ran. See Admin sequence is host-driven for the full explanation of why and when this matters. listSymbols is the one exception in this group: it's genuinely host-routed and callable at runtime, for entitlements discovered after the initial call.
Host-routed calls
These guest-side calls are thin proxies to the real implementation running on the host, designed to avoid an extra copy of the data where possible; see What's different from native for the complete table. In every case the call shape (arguments, return type) matches native exactly; only where the actual work happens differs.
The data pointer passed to a callback is valid only until the callback returns. Copy anything you need to keep.
Exchange plugin timer
A .wasm exchange plugin runs only when the host calls it, so it cannot start threads to send a report later. Instead, it can ask the host to call it back at a given time, for example to send a fill some time after the order arrived, or to act while no market data or orders arrive.
| Function | Direction | Meaning |
|---|---|---|
void nc_exchange_settimer(uint64_t t) |
import | Arms the timer for time t in nanoseconds, on the clock of nanoconda::getEpoch_ns(). Call it from any callback, including nc_cb_ontimer. A new call replaces the previous time; 0 cancels it. |
void nc_cb_ontimer(void) |
export | Called once getEpoch_ns() reaches the armed time. The timer is cleared before the call; arm it again from inside the callback if more work is pending. |
- There is one timer per plugin. Keep your own list of pending actions and always arm the timer for the earliest one.
nc_cb_ontimeris never called at the same time as another callback of the plugin, so no locking is needed.- Reports sent from
nc_cb_ontimerwith thereportslistener are delivered at once. Settransactiontimeon them yourself. - The timer works with
simulator. Incmebacktesteranddbnbacktesterthe timer can be armed but is never called; report from the market data and order callbacks there. - Both functions are optional and do not change
NC_WASM_ABI_VERSION. Plugins that do not use the timer are not affected. A plugin that importsnc_exchange_settimerdoes not load in an earliernanoconda-cli. - Native (
.so) exchange plugins do not have the timer; they can report from their own threads.
C++ example: fill every order 200 microseconds after it arrives.
#include "nanoconda.h"
#include <deque>
struct pendingfill { nanoconda::order o; unsigned long long at; };
static nanoconda::listener* g_reports;
static std::deque<pendingfill> g_pending;
struct myexchange : nanoconda::listener
{
void onneworder(const nanoconda::order* o)
{
g_reports->onorderack(o);
unsigned long long at = nanoconda::getEpoch_ns() + 200000;
g_pending.push_back({*o, at});
if (g_pending.size() == 1) nc_exchange_settimer(at);
}
void onsecurity(const nanoconda::security*) { }
void onbook(const nanoconda::book*) { }
void ontrade(const nanoconda::trade*) { }
void onorderack(const nanoconda::order*) { }
void oncancelack(const nanoconda::order*) { }
void onmodifyack(const nanoconda::order*) { }
void onorderreject(const nanoconda::order*) { }
void onmodifyreject(const nanoconda::order*) { }
void oncancelreject(const nanoconda::order*) { }
void onfill(const nanoconda::order*) { }
void onout(const nanoconda::order*) { }
void onorderstatus(const nanoconda::order*) { }
};
static myexchange g_exchange;
extern "C" nanoconda::listener* init_nanoconda_exchange(int argc, char** argv, nanoconda::listener* reports)
{
g_reports = reports;
return &g_exchange;
}
void nc_cb_ontimer(void)
{
unsigned long long now = nanoconda::getEpoch_ns();
while (!g_pending.empty() && g_pending.front().at <= now)
{
nanoconda::order& f = g_pending.front().o;
f.quantityLast = f.quantity;
f.quantityFilled = f.quantity;
f.transactiontime = now;
g_reports->onfill(&f);
g_pending.pop_front();
}
if (!g_pending.empty()) nc_exchange_settimer(g_pending.front().at);
}
Rust: call nanoconda::exchange_settimer(t) and export the callback yourself.