Link

Cryptographically secure, trust minimised WebSocket link layer for the Edge network.

Edge Link (@edge/link) is a cryptographically authenticated session layer for secure peer-to-peer coordination. It establishes a thin, trust-minimised relay layer over raw or TLS WebSockets, ensuring identity, integrity, and session continuity. Designed for distributed systems with strong cryptographic guarantees, it forms the connective substrate for blockchain-adjacent applications that require lightweight, verifiable communication.

Key Features

Link is designed to be simple to use and understand, with a focus on security and ease of use.

• Designed for humans Small surface area, zero config defaults, and a dev experience that gets out of your way.
• Cryptographic authentication Peers use XE wallets to establish identity and session integrity with no shared secrets or passwords.
• Plug-and-play wallet identity Bring your own XE wallet or generate one on the fly — identity is first-class and seamless.
• Instant secure server Launch a cryptographically-authenticated WebSocket server in under 10 lines — no boilerplate, no fuss.
• Protocol minimalism Only two handshake messages are required to establish mutual trust; everything after is just JSON.

Additional Features

It also includes many additional features, such as:

• Heartbeat & liveness Automatic ping/pong exchange ensures active connections and gives you real-time latency feedback.
• Auto‑reconnect Exponential back-off and capped retries provide graceful recovery from network hiccups.
• Timeout guards Unauthenticated sockets and stale clients are actively removed, keeping your server lean and clean.
• TLS optional Add a cert and key, and you instantly upgrade to encrypted wss:// with no config gymnastics required.

More features will be added in the future.

Usage

npm install @edge/link

Node ≥ 20 recommended.

1 · Spin up a server

import { Server } from '@edge/link'

const server = new Server({ port: 3793 })

server.on('authenticated', c => console.log('✅  client', c.address))
server.on('message', (c, msg) => console.log('⬅️  ', c.address, msg))
server.listen(() => console.log('Server listening on', server.port))

2 · Connect a client

import { Client } from '@edge/link'

const client = new Client()

client.on('authenticated', addr => {
  console.log('We are', client.address, '↔', addr)
  client.send({ type: 'hello', msg: 'Hi from ' + client.address })
})

client.connect()

Full working demos live in examples/simple‑server and examples/simple‑client.

API Reference

new Server(options)

Creates a new authenticated Link server.

Options

| Name | Type | Default | Description | | ----------------------- | ------- | ------- | ------------------------------------------------- | | port | number | 3793 | Port to bind the HTTP/TLS server to | | key | string | null | Optional path to TLS key for wss:// | | cert | string | null | Optional path to TLS cert for wss:// | | authTimeout | number | 5000 | Max time (ms) to wait for authentication | | authCheckInterval | number | 1000 | Interval (ms) to sweep unauthenticated sockets | | heartbeatInterval | number | 1000 | Interval (ms) between server-to-client pings | | clientTimeout | number | 5000 | Inactivity timeout (ms) for authenticated clients | | clientTimeoutInterval | number | 1000 | Interval (ms) to check for idle clients | | replaceExisting | boolean | true | Replace existing client on new connection with same address | | wallet | object | null | Optional XE wallet object | | privateKey | string | null | Optional hex string; overrides wallet | | whitelist | array | null | Optional array of whitelisted addresses |

These options are passed to the constructor and become fields on the server instance.

Note: whitelist is converted to a Set<string>.

Note: replaceExisting controls whether the server will replace an existing client with the same address on a new connection. If false, the new connection will be rejected with a 409 Conflict response. Beware that this can cause clients to ping/pong if they share the same wallet.

Events

• connected(client)
• authenticated(client)
• message(client, message)
• heartbeat(client, data)
• disconnected(client)
• error(error)
• close()

Methods

• server.listen(cb) – Starts listening on the configured port. Accepts optional callback.
• server.close() – Shuts down the server and clears internal timers.
• server.clients() – Returns an array of all connected clients.
• server.client(id) – Returns the client with the given ID.
• server.broadcast(msg) – Sends a message to all connected clients.
• server.send(id, msg) – Sends a message to the client with the given ID.

On the ConnectedClient object:

• client.send(msg) – Send a JSON-serializable object to this client
• client.close() – Closes the connection

Note: this is the server-side client instance, not the Client class.

new Client(options)

Creates a new authenticated Link client.

Options

| Name | Type | Default | Description | | ---------------------- | ------- | ------------- | ------------------------------------------- | | host | string | 'localhost' | Server hostname | | port | number | 3793 | Server port | | tls | boolean | false | Use TLS (wss://) instead of raw (ws://) | | wallet | object | null | Optional XE wallet (auto-generated if null) | | maxReconnectAttempts | number | 5 | Max auto-reconnect attempts | | reconnectDelay | number | 1000 | Base delay (ms) between reconnects |

Events

• connected()
• authenticated(serverAddress)
• message(message)
• heartbeat(data)
• disconnected()
• reconnecting(attempt, delay)
• error(error)

Methods

• client.connect() – Opens the connection and begins the authentication handshake.
• client.disconnect() – Gracefully closes the connection without triggering reconnect.
• client.send(msg) – Sends a JSON-serializable object to the connected server. msg must be an object

Message format is subject to change in future versions. Future versions may support raw frames. Currently messages should be objects with a type field. Reserved message types: authenticate, heartbeat, disconnect, error.

Contributing

Interested in contributing to the project? Amazing! Before you do, please have a quick look at our Contributor Guidelines where we've got a few tips to help you get started.

License

Edge is the infrastructure of Web3. A peer-to-peer network and blockchain providing high performance decentralised web services, powered by the spare capacity all around us.

Copyright notice (C) 2025 Edge Network Technologies Limited [email protected] All rights reserved

This product is part of Edge. Edge is free software: you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation, either version 3 of the License, or (at your option) any later version ("the GPL").

If you wish to use Edge outside the scope of the GPL, please contact us at [email protected] for details of alternative license arrangements.

This product may be distributed alongside other components available under different licenses (which may not be GPL). See those components themselves, or the documentation accompanying them, to determine what licenses are applicable.

Edge is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details.

The GNU General Public License (GPL) is available at: https://www.gnu.org/licenses/gpl-3.0.en.html A copy can be found in the file GPL.md distributed with these files.

This copyright notice MUST APPEAR in all copies of the product!