mfahampshire
7c890ea0c5
* First sweep packages + some minor tweaking * Second sweep * Regenerate lockfile + package.json mods * Regenerate lockfile again * Fix CI * Fix CI again * All building properly * unblock * Tweak examples * Comments + readme + fix rotten unit test * First pass docs * Big pass * Massive pass on new docs * Update integrations.md w mobile * Partial overhaul review * new playground + big pass * new fix lychee err * IPR notice tweak
59 lines
2.7 KiB
Plaintext
59 lines
2.7 KiB
Plaintext
---
|
|
title: "mix-tunnel guides"
|
|
description: "Configure the shared mixnet tunnel and read its connection state."
|
|
schemaType: "TechArticle"
|
|
section: "Developers"
|
|
lastUpdated: "2026-06-05"
|
|
---
|
|
|
|
import { Callout } from 'nextra/components'
|
|
|
|
# Reference
|
|
|
|
## Configuration
|
|
|
|
`setupMixTunnel(opts)` accepts the full smolmix-wasm `SetupOpts` surface plus one TS-layer addition (`debug`). Pass any subset; every field has a default (listed in [`SetupMixTunnelOpts`](/developers/mix-tunnel/api/interfaces/SetupMixTunnelOpts)).
|
|
|
|
```ts
|
|
await setupMixTunnel({
|
|
// Pin a specific IPR (otherwise auto-discovered from the topology).
|
|
preferredIpr: 'D1rrUqJY9pesL3pTaMaxLnpZGGYQ4ZpZwpQXCqaeBXTW.6PpFkRvF...',
|
|
|
|
// Cover traffic and Poisson timing are ON by default. Setting these disables
|
|
// them for lower latency and bandwidth, at the cost of traffic-analysis
|
|
// resistance (it drops timing-correlation resistance at the entry and exit).
|
|
disableCoverTraffic: true,
|
|
disablePoissonTraffic: true,
|
|
|
|
// Verbose console tracing from smolmix-wasm. Useful while integrating.
|
|
debug: true,
|
|
});
|
|
```
|
|
|
|
The complete option surface (IPR pinning, SURB budgets, DNS server overrides, TCP/connect timeouts, gateway selection) is documented in the [`SetupMixTunnelOpts` type reference](/developers/mix-tunnel/api/interfaces/SetupMixTunnelOpts).
|
|
|
|
<Callout type="info">
|
|
Call `setupMixTunnel` once. The WASM tunnel is one-shot per page: the first call brings it up, and a second call rejects with `tunnel already initialised`. Because the feature packages share that one tunnel, calling it from `mix-fetch` is enough for `mix-dns` and `mix-websocket` too. If more than one call site might invoke it, guard with `getTunnelState()` and skip setup when the state is already `ready`.
|
|
</Callout>
|
|
|
|
## Tunnel state
|
|
|
|
`getTunnelState()` returns a tagged state for surfacing connection status in the UI. The five states are:
|
|
|
|
| State | Meaning |
|
|
|---|---|
|
|
| `connecting` | Default before `setupMixTunnel()` completes. |
|
|
| `ready` | Tunnel is up. Feature packages can issue requests. |
|
|
| `shutting_down` | `disconnectMixTunnel()` in progress. |
|
|
| `shutdown` | Cleanly torn down. The WASM is no longer usable. |
|
|
| `failed` | Setup or runtime error. The `reason` field carries a human-readable cause. |
|
|
|
|
```ts
|
|
const { state, reason } = await getTunnelState();
|
|
if (state === 'failed') {
|
|
console.error('Tunnel failed:', reason);
|
|
}
|
|
```
|
|
|
|
`await setupMixTunnel()` resolves only once the tunnel is `ready`, so most apps never need to read the state. Poll `getTunnelState()` only to drive a separate status indicator. The transitions are coarse (no progress percentage during `connecting`); the underlying connection events are visible via `debug: true` in the console.
|