Custom WebSocket client

Overview

Protocol traffic between your app and the cloud peers flows through a NetworkClient — a small transport contract the SDK drives to run each MPC step. The SDK ships a WebSocket implementation, TrioNetworkClient, and uses it automatically when you pass a WebsocketConfig to trioInitiator. You only need this guide if you want to customize that transport.

The NetworkClient contract is a fixed rhythm the session repeats for every protocol step (every method is async throws):

Method	Responsibility
connect(action:params:)	Open a channel for one step. action carries the routing (which operation, which algorithm); params is optional detail such as a keyId.
send(bytes:) / send(text:)	Send one framed message to the peer.
read()	Suspend until the next message arrives, and return its Data.
disconnect()	Close the channel. The client stays reusable for the next connect.

TrioNetworkClient implements this contract over URLSessionWebSocketTask. On connect it:

• opens a task at wss://<host>/v3/{path}/{action} — for example /v3/trio/keygen;
• negotiates the step's WebSocket subprotocol (trio for keygen);
• sends WebsocketConfig.authenticationToken as the first message, if you set one.

The underlying URLSession is created on connect and released on disconnect, so an idle client holds no transport resources.

Three ways to provide a transport

trioInitiator has three overloads, from zero-config to full control. Pick the one that matches how much of the transport you need to own.

#	Approach	When to use
1	WebsocketConfig	The default. The SDK builds and owns the WebSocket client.
2	Subclass TrioNetworkClient	Keep the WebSocket transport, but hook connect / send / read — logging, headers, retry, or route rewriting.
3	Custom NetworkClient + TrioNetworkActionProvider	Route protocol traffic over a different transport entirely.

1. Default WebSocket — pass a WebsocketConfig

Give the factory a WebsocketConfig and the SDK builds and owns the default TrioNetworkClient. There is nothing to implement — this is the standard path used in the session setup.

Example.swift

// The default transport. Pass a WebsocketConfig and the SDK builds and owns the
// default TrioNetworkClient (a URLSession WebSocket client) for you — nothing to implement.
let websocketConfig = WebsocketConfig(url: "wss://your-server.example.com")

let trioSession = SilentShard.ECDSA.trioInitiator(
    messageSigner: messageSigner,
    cloudVerifyingKey: cloudPublicKey,
    websocketConfig: websocketConfig,
    storageClient: storageClient
)

2. Customize the WebSocket — subclass TrioNetworkClient

Subclass TrioNetworkClient and override connect (or send / read) to add logging, inject headers, add retry/back-off, or rewrite a route — while reusing the default framing, /v3/{path}/{action} routing, subprotocol negotiation, and session lifecycle. Pass your subclass to the trioInitiator overload that accepts a TrioNetworkClient.

TrioNetworkClient and the TrioNetworkAction types are exported from the trio module (import trio).

CustomNetworkClient.swift

import trio

// Subclass the default client to hook connect / send / read while reusing its framing
// and /v3/{path}/{action} routing. Here we rewrite the keygen route as an example
// and delegate every other action unchanged; you could just as easily log, add headers,
// or wrap the call in retry/back-off before calling super.
class CustomNetworkClient: TrioNetworkClient {

    override func connect(websocketAction: TrioNetworkAction, params: String?) async throws {
        let routed: TrioNetworkAction
        switch websocketAction {
        case is TrioAction.ECDSA.Keygen:
            routed = TrioAction.ECDSA.Keygen(path: "custom-path-for-keygen")
        default:
            routed = websocketAction
        }
        try await super.connect(websocketAction: routed, params: params)
    }
}

// Pass your subclass to the TrioNetworkClient overload of trioInitiator.
let trioSession = SilentShard.ECDSA.trioInitiator(
    messageSigner: messageSigner,
    cloudVerifyingKey: cloudPublicKey,
    networkClient: CustomNetworkClient(websocketConfig: websocketConfig),
    storageClient: storageClient
)

3. Bring your own transport — implement NetworkClient

The most control: carry protocol traffic over any channel you like. Because the transport only has to move framed bytes between the parties, this can be a shared app socket, a native bridge, or an already-open host connection — or a peer-to-peer link such as Bluetooth Low Energy (BLE), mapping connect / send / read / disconnect onto GATT characteristic writes and notifications.

A custom transport has two halves, and you supply both to the trioInitiator overload that accepts a NetworkClient + TrioNetworkActionProvider.

a. The transport — implement NetworkClient

How bytes move. The SDK drives your client with connect → send/read → disconnect for each step; the action it hands connect is the step your routing selected.

CustomTransport.swift

import trio

// How bytes move. The SDK drives your client with the same rhythm for every step:
// connect → send/read → disconnect. `action` is the concrete step your routing selected.
class CustomTransport: NetworkClient {
    func connect(action: NetworkAction, params: String?) async throws {
        // `action` is the step the provider chose; `params` may carry a keyId.
        // Open a channel for it over your transport (WebSocket, app socket, BLE, …).
    }

    func send(bytes: Data) async throws { /* send framed bytes to the peer */ }
    func send(text: String) async throws { /* send framed text to the peer */ }
    func read() async throws -> Data { Data() /* suspend until the next peer message, then return its bytes */ }
    func disconnect() async throws { /* close the channel; stay reusable for the next connect */ }
    // sendPostRequest has a default that throws .postRequestUnsupported; implement it only
    // if your transport supports pre-signatures (trio runs preSignFinal over HTTP POST).
}

b. The routing — implement TrioNetworkActionProvider

How each step is addressed. It exposes one NetworkAction per operation (keygen, reconcile, refresh, hardDerivation, sign, preSign, preSignFinal, recover, export, import) — hardDerivation is ECDSA-only — and the action it supplies is exactly what your client's connect receives. Take the built-in .ecdsa / .eddsa provider for the standard /v3/{path}/{action} routing, or implement it yourself — every TrioNetworkAction lets you override path / action / protocol / algorithm.

CustomActions.swift

import trio

// How each step is addressed. Every TrioAction.ECDSA.* initializer takes
// path / action / protocol / algorithm — override whichever fields you want: pass one,
// spell them all out, or take the defaults, per step.
struct CustomActions: TrioNetworkActionProvider {
    // Override a single field (here, the route's `path`).
    let keygen: NetworkAction = TrioAction.ECDSA.Keygen(path: "my-keygen-route")

    // Spell out every field explicitly.
    let reconcile: NetworkAction = TrioAction.ECDSA.Reconcile(
        path: "trio", action: "reconcile", protocol: "-no-reconcile", algorithm: "ecdsa"
    )

    // Override the WebSocket subprotocol negotiated on connect.
    let refresh: NetworkAction = TrioAction.ECDSA.KeyRefresh(protocol: "my-trio-subprotocol")

    // Override the `action` segment of the route.
    let sign: NetworkAction = TrioAction.ECDSA.Signature(action: "signature")

    // Pre-signatures: preSign runs over the WebSocket, preSignFinal over HTTP POST.
    let preSign: NetworkAction = TrioAction.ECDSA.PreSignature()
    let preSignFinal: NetworkAction = TrioAction.ECDSA.PreSignatureFinal()

    // hardDerivation is ECDSA-only.
    let hardDerivation: NetworkAction = TrioAction.ECDSA.HardDerivation()

    // …or just take the stock routing.
    let recover: NetworkAction = TrioAction.ECDSA.Recovery()
    let export: NetworkAction = TrioAction.ECDSA.Export()
    let `import`: NetworkAction = TrioAction.ECDSA.Import()
}

// Note: `path` + `action` form the /v3/{path}/{action} route (EdDSA inserts an /eddsa
// segment) and also the HTTP POST URL that pre-signatures use; `protocol` is the
// Sec-WebSocket-Protocol header. Change these only to match your own server, and keep
// `path` + `action` valid so requests still reach the cluster.

c. Wire the two halves into trioInitiator

Example.swift

// Pass both halves — your transport and your routing — to the custom-transport
// overload of trioInitiator.
let trioSession = SilentShard.ECDSA.trioInitiator(
    messageSigner: messageSigner,
    cloudVerifyingKey: cloudPublicKey,
    storageClient: storageClient,
    networkClient: CustomTransport(),
    actionProvider: CustomActions() // or .ecdsa
)

Most protocol steps run over the open WebSocket; a few request-response steps run over HTTP POST (sendPostRequest). Trio's pre-signature flow finalizes over that POST path (preSignFinal), so a fully custom trio transport must implement sendPostRequest if it supports pre-signatures — its default reports the step unsupported (postRequestUnsupported). A transport that never issues pre-signatures can leave the default in place.