Crate nym_sdk_session 

nym-sdk-session

A provisioning facade over nym-registration-client, nym-bandwidth-controller, and the credential store. From a caller-supplied mnemonic it deposits NYM and issues + persists zk-nym WireGuard ticketbooks, selects gateways (by identity / two-letter country code / random), and registers them, returning the per-hop WireGuard configuration the dVPN datapath needs. Shared by both mixnet and dvpn modes.

Registration reuse

Registrations are persisted (client WireGuard key + assigned configuration, in registrations.json under data_path) and served back on later register_* calls against the same network/gateway/role — no gateway exchange, no ticket spent, resuming the gateway-side peer’s remaining bandwidth allowance. Cached registrations are validated by use: gate tunnel bring-up with Tunnel::await_established (in smoldvpn) and, when a hop fails to establish, call Session::invalidate_registration for it and register again (which spends a ticket and persists the fresh peer). Default-on; opt out via SessionConfig::reuse_registrations (see its doc for the privacy trade-off). The cache file holds WireGuard private keys — the same secret-sensitivity class as the credential store beside it.

Signer-failure tolerance

Unresponsive ecash signers are a normal operating condition, not an error to hang on. The session bounds every read-only global-signing-data fetch with a per-call timeout (TimeoutFetcher, DEFAULT_PUBLIC_DATA_TIMEOUT) — the deposit/issuance call is deliberately exempt — and bounds provisioning overall, surfacing SessionError::ProvisioningTimeout instead of blocking. An issued (paid-for) ticketbook is persisted even when the signing data needed to spend it cannot currently be fetched: retries never re-deposit, spends during the outage fail fast with a clear error, and everything works again the moment enough signers return.

use nym_sdk_session::{GatewaySpec, Session, SessionConfig};
use tokio_util::sync::CancellationToken;

// Provisions once and tops up a live tunnel from stored tickets; opt into background
// re-issuance with `.with_automatic_topups(..)`.
let config = SessionConfig::new(
    "..".parse()?,
    nym_network_defaults::NymNetworkDetails::new_mainnet(),
    "/tmp/dvpn".into(),
);
let session = Session::new(config, CancellationToken::new()).await?;

// Two-hop: entry in Germany, random exit.
let reg = session
    .register_two_hop(&GatewaySpec::Country("DE".into()), &GatewaySpec::Random)
    .await?;

Structs

GatewayInfo

Directory metadata for the gateway a tunnel hop terminates at.

HopConfig

Everything the datapath needs to bring up ONE WireGuard hop.

QuicBridge

QUIC bridge connection parameters for a gateway, sourced from the dVPN directory. The datapath consumes these to front the WireGuard entry leg with a QUIC bridge.

Registration

The result of registering a tunnel: one hop for single-hop, two for two-hop.

RestockPolicy

Opt-in policy for automatic chain-side ticketbook restock. Maps onto the bandwidth controller’s restock thresholds. Only in effect when set via SessionConfig::automatic_topups.

SelectedGateway

A selected, registration-ready gateway.

Session

Provisioning facade over the credential + registration machinery.

SessionConfig

Configuration for creating a [Session].

SignerTimeout

A global-signing-data fetch exceeded its per-call bound. Surfaced through the controller as a fetch failure so readiness reporting names the cause.

TimeoutFetcher

Decorator over a CredentialFetcher bounding each read-only public-data fetch with a per-call timeout (see module docs for why issuance is exempt).

Enums

GatewaySpec

How the caller names the gateway(s) to use.

SessionError

Errors produced while provisioning a dVPN session.

WgRole

Which WireGuard role a gateway must fulfil.

Constants

DEFAULT_PUBLIC_DATA_TIMEOUT

Default per-call bound for the read-only global-signing-data fetches. A healthy signer answers in well under a second; this is ~50x that, so it only ever fires on genuinely unresponsive infrastructure while turning an infinite hang into a bounded delay.