dig-node-control-interface

The canonical client ⇄ dig-node CONTROL interface contract. One ecosystem definition of the management/query surface a client (the CLI dign, the browser extension, dig-app, hub) uses to control and query a running dig-node — status, config, cache, hosted/pinned stores, §21 sync, the peer network, subscriptions, the auto-update beacon, live log level, and control-token pairing — so the client side and the node side can never silently drift. Transport-agnostic: rides the dig-ipc-protocol local session, or loopback-mTLS + a signed control token over HTTP/WebSocket for clients that aren't on the local pipe.

• License: Apache-2.0 OR MIT
• Spec: SPEC.md (normative) — this README is the at-a-glance interface reference.

[dependencies]
dig-node-control-interface = "0.2"

Usage

Client side — build a typed request, carry it over your transport, parse the typed result:

use dig_node_control_interface::{
    params::SetCapParams,
    traits::{build_request, parse_response},
    envelope::JsonRpcResponse,
};

let call = SetCapParams { cap_bytes: 128 * 1024 * 1024 };
let request = build_request(1.into(), &call);          // → control.cache.setCap envelope
// ... send `request` over dig-ipc / loopback-mTLS, receive `response` ...
# let response = JsonRpcResponse::success(1.into(), serde_json::json!({ "cap_bytes": 134217728 }));
let result = parse_response::<SetCapParams>(response)?; // → SetCapResult { cap_bytes }
# Ok::<(), dig_node_control_interface::ControlError>(())

Node side — implement ControlHandler (one typed method per control method); the provided dispatch routes a raw request to the right method and builds the response.

Authorization

Every control.* method is token-gated unless the tables below mark it —: present the node's local control token as the X-Dig-Control-Token header (preferred) or a params._control_token field. Open today are pairing.request / pairing.poll (a token-less client uses them to obtain a scoped token after local operator approval), the wallet CHAIN READS (they need only public chain data — an address or a coin id, never a key), and control.peerCounts (two integers about this node's own connectivity). The three control.pairing.* admin methods require the MASTER token specifically.

UNAUTHORIZED from an OPEN method means the node predates it — upgrade the node. From control.wallet.broadcast it means what it says — find the token. See SPEC.md §4.2.

Full interface reference

Every control method, for LLM/agent lookup without reading code. Auth: T = requires the control token, M = requires the MASTER token, — = open. Route: how the node resolves it — own (service shell), del (engine), open (bootstrap).

Status / config / log

Cache

Hosted / pinned stores

§21 whole-store sync

Auto-update beacon (proxied to dig-updater)

Pairing (control-token lifecycle)

Peers (delegated to the engine)

Wallet chain transport (delegated to the engine)

The caller-addressed reads and the chain-position reads are OPEN; the arrival cursor and the push are token-gated. The node never signs — it reads chain state and pushes bytes somebody else signed.

Subscriptions (delegated to the engine)

Error codes

Every control error is {code:int, message:string, data:{code:SYMBOL, origin:string}}. Branch on data.code (the stable symbol), never the message.

Boundary

• dig-rpc-protocol — node ⇄ node peer wire.
• dig-ipc-protocol — app ⇄ node local session/signing envelope (the transport this catalog rides over, for local clients).
• dig-node-control-interface (this crate) — the control METHOD CATALOG carried inside that authenticated channel, or over loopback-mTLS for remote-transport clients.

See SPEC.md for the normative contract and the superproject SYSTEM.md for the wider cross-repo map.

Consumers

dig-node (server-side dispatch — implements ControlHandler), the CLI dign, dig-chrome-extension, dig-app, hub — all consuming this one control contract per epic #1110 (dig-node adoption + the dig-rpc Control-tier removal land in later tasks of the cascade).