diodejs 0.4.1 → 0.4.2

package/README.md

@@ -64,6 +64,27 @@ async function main() {
 main();
 ```
 
+Fleet contract selection is configured on the manager:
+```javascript
+const { DiodeClientManager } = require('diodejs');
+
+async function main() {
+  const client = new DiodeClientManager({
+    keyLocation: './db/keys.json',
+    fleetContract: '0x1111111111111111111111111111111111111111',
+  });
+
+  await client.connect();
+
+  // Applies on the next ticket generated by each active relay connection.
+  client.setFleetContract('0x2222222222222222222222222222222222222222');
+}
+
+main();
+```
+
+If `fleetContract` is omitted, tickets continue using the default contract `0x6000000000000000000000000000000000000000`.
+
 ### Multi-Relay Connections (Recommended)
 
 You can connect to multiple Diode relays and automatically route binds to the relay where the target device is connected.
@@ -305,9 +326,11 @@ async function main() {
   
   // Option 2: Object with port configurations for public/private access control
   const publishedPortsWithConfig = {
-    8080: { mode: 'public' },  // Public port, accessible by any device
+    8080: { mode: 'public' },  // Public port on 127.0.0.1, accessible by any device
+    8081: { mode: 'public', host: '192.168.1.10' }, // Forward to another reachable host
     3000: { 
       mode: 'private',  
+      host: 'backend.internal',
       whitelist: ['0x1234abcd5678...', '0x9876fedc5432...'] // Only these devices can connect
     }
   };
@@ -330,6 +353,7 @@ main();
   - `options.port` (number, optional): Port to use when `options.host` has no port. Defaults to `41046`.
   - `options.hosts` (string[] or comma-separated string, optional): Explicit relay list.
   - `options.keyLocation` (string, optional): Key storage path (default: `./db/keys.json`).
+  - `options.fleetContract` (string, optional): Fleet contract used for relay tickets. Must be a 20-byte EVM address hex string. Defaults to `0x6000000000000000000000000000000000000000`.
   - `options.deviceCacheTtlMs` (number, optional): Cache TTL for device relay resolution (default: `30000`).
   - `options.relaySelection` (object, optional): Relay ranking and probing options.
     - `enabled` (boolean, optional): Enables smart relay ranking. Defaults to `true`.
@@ -365,6 +389,7 @@ main();
 
 - **Methods**:
   - `connect()`: Probes the required initial relays, merges provider and optional `dio_network` candidates, ranks the successful relays by latency, trims the warm relay set, and returns a promise. In live network discovery mode this starts from a region-diverse seed bootstrap subset plus the bounded discovery sample, then continues probing the remaining seeds in the background.
+  - `setFleetContract(address)`: Updates the fleet contract used for future ticket generation on managed connections. Accepts a 20-byte EVM address hex string and returns the manager instance.
   - `getNearestConnection()`: Returns the preferred connected relay. With relay selection enabled, this is the lowest-latency scored relay.
   - `getConnectionForDevice(deviceId)`: Resolves and returns a relay connection for the device. Returns a promise.
   - `getConnections()`: Returns a list of active connections.
@@ -428,13 +453,14 @@ Connections returned by `getConnections()` or `getConnectionForDevice()` emit `r
   - `connection` (DiodeClientManager): An instance of `DiodeClientManager`.
   - `publishedPorts` (array|object): Either:
     - An array of ports to publish (all public mode)
-    - An object mapping ports to their configuration: `{ port: { mode: 'public'|'private', whitelist: ['0x123...'] } }`
+    - An object mapping ports to their configuration: `{ port: { mode: 'public'|'private', whitelist: ['0x123...'], host: '127.0.0.1' } }`
   - `_certPath` (string): Has no functionality and maintained for backward compatibility.
 
 - **Methods**:
   - `addPort(port, config)`: Adds a new port to publish. Config is optional and defaults to public mode.
     - `port` (number): The port number to publish.
-    - `config` (object): Optional configuration with `mode` ('public'|'private') and `whitelist` array.
+    - `config` (object): Optional configuration with `mode` ('public'|'private'), `whitelist` array, and `host` string.
+      - `host` (string, optional): Target IP or hostname for the published service. Defaults to `127.0.0.1`.
   - `removePort(port)`: Removes a published port.
     - `port` (number): The port number to remove.
   - `addPorts(ports)`: Adds multiple ports at once (equivalent to the constructor's publishedPorts parameter).

package/clientManager.js

@@ -6,6 +6,7 @@ const DiodeConnection = require('./connection');
 const DiodeRPC = require('./rpc');
 const { fetchNetworkDirectory } = require('./networkDiscoveryClient');
 const logger = require('./logger');
+const { DEFAULT_FLEET_CONTRACT, normalizeFleetContractAddress } = require('./utils');
 
 const DEFAULT_DIODE_ADDRS = [
   'as1.prenet.diode.io:41046',
@@ -176,11 +177,29 @@ class DiodeClientManager extends EventEmitter {
     this._startupCoverageComplete = false;
     this._lastNetworkDiscoveryStats = null;
     this._lastDeviceResolutionTrace = null;
+    this.fleetContract = DEFAULT_FLEET_CONTRACT;
+
+    if (options.fleetContract !== undefined) {
+      this.setFleetContract(options.fleetContract);
+    }
 
     this.initialHosts = this._buildInitialHosts(options);
     this._loadRelayScores();
   }
 
+  setFleetContract(address) {
+    const normalizedFleetContract = normalizeFleetContractAddress(address);
+    this.fleetContract = normalizedFleetContract;
+
+    for (const connection of this.connections) {
+      if (connection && typeof connection.setFleetContract === 'function') {
+        connection.setFleetContract(normalizedFleetContract);
+      }
+    }
+
+    return this;
+  }
+
   _buildRelaySelectionOptions(options = {}) {
     const relaySelection = options && typeof options === 'object' ? options : {};
     const legacyWarmConnections = parsePositiveInteger(relaySelection.desiredWarmConnections, NaN);
@@ -1157,6 +1176,9 @@ class DiodeClientManager extends EventEmitter {
     connection._managerHostKey = hostKey;
     this.connections.push(connection);
     this.connectionByHost.set(hostKey, connection);
+    if (typeof connection.setFleetContract === 'function') {
+      connection.setFleetContract(this.fleetContract);
+    }
     if (typeof connection.setLocalAddressProvider === 'function') {
       connection.setLocalAddressProvider(() => this._localAddressHintFor(connection));
     }

package/connection.js

@@ -3,7 +3,19 @@ const tls = require('tls');
 const fs = require('fs');
 const { RLP } = require('@ethereumjs/rlp');
 const EventEmitter = require('events');
-const { makeReadable, parseRequestId, parseResponseType, parseReason, parseUInt, generateCert, ensureDirectoryExistence, loadOrGenerateKeyPair, toBufferView } = require('./utils');
+const {
+  makeReadable,
+  parseRequestId,
+  parseResponseType,
+  parseReason,
+  parseUInt,
+  generateCert,
+  ensureDirectoryExistence,
+  loadOrGenerateKeyPair,
+  toBufferView,
+  DEFAULT_FLEET_CONTRACT,
+  normalizeFleetContractAddress,
+} = require('./utils');
 const { Buffer } = require('buffer'); // Import Buffer
 const asn1 = require('asn1.js');
 const secp256k1 = require('secp256k1');
@@ -48,6 +60,8 @@ class DiodeConnection extends EventEmitter {
     this.certPem = null;
     this._serverEthAddress = null; // cache after first read
     this.localAddressProvider = null;
+    this.fleetContractHex = DEFAULT_FLEET_CONTRACT;
+    this.fleetContract = Buffer.from(DEFAULT_FLEET_CONTRACT.slice(2), 'hex');
     // Load or generate keypair
     this.keyPair = loadOrGenerateKeyPair(this.keyLocation);
     
@@ -283,6 +297,13 @@ class DiodeConnection extends EventEmitter {
     return this;
   }
 
+  setFleetContract(fleetContract) {
+    const normalizedFleetContract = normalizeFleetContractAddress(fleetContract);
+    this.fleetContractHex = normalizedFleetContract;
+    this.fleetContract = Buffer.from(normalizedFleetContract.slice(2), 'hex');
+    return this;
+  }
+
   // Update close method to prevent reconnection when intentionally closing
   close() {
     if (this.ticketUpdateTimer) {
@@ -592,7 +613,7 @@ class DiodeConnection extends EventEmitter {
 
   async createTicketSignature(serverIdBuffer, totalConnections, totalBytes, localAddress, epoch) { 
     const chainId = 1284;
-    const fleetContractBuffer = ethUtil.toBuffer('0x6000000000000000000000000000000000000000'); // 20-byte Buffer
+    const fleetContractBuffer = this.fleetContract;
   
     const localAddressBytes = Buffer.isBuffer(localAddress) || localAddress instanceof Uint8Array
       ? toBufferView(localAddress)
@@ -637,7 +658,7 @@ class DiodeConnection extends EventEmitter {
 
   async createTicketCommand() {
     const chainId = 1284;
-    const fleetContract = ethUtil.toBuffer('0x6000000000000000000000000000000000000000')
+    const fleetContract = this.fleetContract;
     let localAddress = '';
     if (typeof this.localAddressProvider === 'function') {
       try {

package/examples/RPCTest.js

@@ -3,8 +3,13 @@ const { makeReadable } = require('../utils');
 
 async function main() {
   const keyLocation = './db/keys.json';
+  const fleetContract = process.env.DIODE_FLEET_CONTRACT;
+  const nextFleetContract = process.env.DIODE_NEXT_FLEET_CONTRACT;
 
-  const client = new DiodeClientManager({ keyLocation });
+  const client = new DiodeClientManager({
+    keyLocation,
+    ...(fleetContract ? { fleetContract } : {}),
+  });
   await client.connect();
   const [connection] = client.getConnections();
   if (!connection) {
@@ -15,6 +20,11 @@ async function main() {
   try {
     const address = connection.getEthereumAddress();
     console.log('Address:', address);
+    console.log('Current fleet contract:', connection.fleetContractHex);
+    if (nextFleetContract) {
+      client.setFleetContract(nextFleetContract);
+      console.log('Updated fleet contract for future tickets:', connection.fleetContractHex);
+    }
     const ping = await rpc.ping();
     console.log('Ping:', ping);
     const blockPeak = await rpc.getBlockPeak();

package/examples/fleetContractExample.js

@@ -0,0 +1,45 @@
+const { DiodeClientManager } = require('../index');
+
+const keyLocation = './db/keys.json';
+const initialFleetContract = process.env.DIODE_FLEET_CONTRACT || '0x1111111111111111111111111111111111111111';
+const nextFleetContract = process.env.DIODE_NEXT_FLEET_CONTRACT || '0x2222222222222222222222222222222222222222';
+const shouldConnect = process.env.DIODE_CONNECT === 'true';
+
+async function main() {
+  const client = new DiodeClientManager({
+    keyLocation,
+    fleetContract: initialFleetContract,
+  });
+
+  console.log('Initial manager fleet contract:', client.fleetContract);
+
+  if (!shouldConnect) {
+    client.setFleetContract(nextFleetContract);
+    console.log('Updated manager fleet contract:', client.fleetContract);
+    console.log('Set DIODE_CONNECT=true to connect and observe the updated contract on active relay connections.');
+    return;
+  }
+
+  try {
+    await client.connect();
+    console.log(`Connected relay count: ${client.getConnections().length}`);
+    for (const connection of client.getConnections()) {
+      console.log(`Before update ${connection.host}:${connection.port} fleet contract: ${connection.fleetContractHex}`);
+    }
+
+    client.setFleetContract(nextFleetContract);
+    console.log('Updated manager fleet contract:', client.fleetContract);
+    for (const connection of client.getConnections()) {
+      console.log(`After update ${connection.host}:${connection.port} fleet contract: ${connection.fleetContractHex}`);
+    }
+
+    console.log('The new fleet contract will be used on the next ticket generated by each connection.');
+  } finally {
+    client.close();
+  }
+}
+
+main().catch((error) => {
+  console.error('Fleet contract example failed:', error);
+  process.exitCode = 1;
+});

package/examples/publishPortTest.js

@@ -10,9 +10,10 @@ async function startPublishing() {
 
   // Create a PublishPort instance with initial ports
   const publishPort = new PublishPort(client, {
-    3000: { mode: 'public' },
+    3000: { mode: 'public', host: '192.168.1.10' },
     8080: { 
       mode: 'private',
+      host: 'backend.internal',
       whitelist: ['0xca1e71d8105a598810578fb6042fa8cbc1e7f039'] // Replace with actual addresses
     }
   }, keyLocation);
@@ -29,7 +30,7 @@ async function startPublishing() {
   // After 15 seconds, add multiple ports
   setTimeout(() => {
     console.log("Adding multiple ports");
-    publishPort.addPort(3000,{ mode: 'public' });
+    publishPort.addPort(3000,{ mode: 'public', host: '127.0.0.1' });
     console.log('Updated published ports:', publishPort.getPublishedPorts());
   }, 15000);
   

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "diodejs",
-  "version": "0.4.1",
+  "version": "0.4.2",
   "description": "A JavaScript client for interacting with the Diode network. It provides functionalities to bind and publish ports, send RPC commands, and handle responses.",
   "main": "index.js",
   "scripts": {

package/publishPort.js

@@ -38,6 +38,25 @@ function normalizeDeviceId(raw) {
   return '';
 }
 
+function normalizePublishedPortConfig(config = {}) {
+  const hasHost = Object.prototype.hasOwnProperty.call(config, 'host');
+  const rawHost = hasHost ? config.host : '127.0.0.1';
+  if (typeof rawHost !== 'string') {
+    throw new TypeError('PublishPort config.host must be a non-empty string');
+  }
+
+  const host = rawHost.trim();
+  if (!host) {
+    throw new TypeError('PublishPort config.host must be a non-empty string');
+  }
+
+  return {
+    mode: config.mode || 'public',
+    whitelist: Array.isArray(config.whitelist) ? config.whitelist : [],
+    host,
+  };
+}
+
 class DiodeSocket extends Duplex {
   constructor(ref, rpc) {
     super({ readableHighWaterMark: 256 * 1024, writableHighWaterMark: 256 * 1024, allowHalfOpen: false });
@@ -93,14 +112,11 @@ class PublishPort extends EventEmitter {
     const portNum = parseInt(port, 10);
     
     // Normalize the configuration
-    const portConfig = {
-      mode: config.mode || 'public',
-      whitelist: Array.isArray(config.whitelist) ? config.whitelist : []
-    };
+    const portConfig = normalizePublishedPortConfig(config);
     
     // Add to map
     this.publishedPorts.set(portNum, portConfig);
-    logger.info(() => `Added published port ${portNum} with mode: ${portConfig.mode}`);
+    logger.info(() => `Added published port ${portNum} with mode: ${portConfig.mode}, host: ${portConfig.host}`);
     
     return true;
   }
@@ -186,6 +202,10 @@ class PublishPort extends EventEmitter {
     return rpc;
   }
 
+  _getPublishedPortConfig(port) {
+    return this.publishedPorts.get(port);
+  }
+
   startListening() {
     if (this._listening) return this; // idempotent
     // Listen for unsolicited messages from the connection
@@ -269,7 +289,7 @@ class PublishPort extends EventEmitter {
     }
 
     // Get port configuration and check whitelist if in private mode
-    const portConfig = this.publishedPorts.get(port);
+    const portConfig = this._getPublishedPortConfig(port);
     if (portConfig.mode === 'private' && Array.isArray(portConfig.whitelist)) {
       if (!portConfig.whitelist.includes(deviceId)) {
         logger.warn(() => `Device ${deviceId} is not whitelisted for port ${port}. Rejecting request.`);
@@ -281,15 +301,15 @@ class PublishPort extends EventEmitter {
 
     // Handle based on protocol
     if (protocol === 'tcp') {
-      this.handleTCPConnection(sessionId, ref, port, deviceId, connection);
+      this.handleTCPConnection(sessionId, ref, port, deviceId, portConfig, connection);
     } else if (protocol === 'tls') {
       if (isHandshake) {
         this.handleTLSHandshake(sessionId, ref, port, deviceId, connection);
       } else {
-        this.handleTLSConnection(sessionId, ref, port, deviceId, connection);
+        this.handleTLSConnection(sessionId, ref, port, deviceId, portConfig, connection);
       }
     } else if (protocol === 'udp') {
-      this.handleUDPConnection(sessionId, ref, port, deviceId, connection);
+      this.handleUDPConnection(sessionId, ref, port, deviceId, portConfig, connection);
     } else {
       logger.warn(() => `Unsupported protocol: ${protocol}`);
       rpc.sendError(sessionId, ref, `Unsupported protocol: ${protocol}`);
@@ -449,7 +469,7 @@ class PublishPort extends EventEmitter {
     }
 
     // Get port configuration and check whitelist if in private mode
-    const portConfig = this.publishedPorts.get(port);
+    const portConfig = this._getPublishedPortConfig(port);
     if (portConfig.mode === 'private' && Array.isArray(portConfig.whitelist)) {
       if (!portConfig.whitelist.includes(deviceId)) {
         logger.warn(() => `Device ${deviceId} is not whitelisted for port ${port}. Rejecting request.`);
@@ -473,6 +493,7 @@ class PublishPort extends EventEmitter {
     const session = {
       physicalPort,
       port,
+      host: portConfig.host,
       protocol,
       deviceId: deviceId.toLowerCase(),
       connection,
@@ -527,7 +548,7 @@ class PublishPort extends EventEmitter {
 
   handleNativeTCPRelay(sessionId, physicalPortRef, session, connection) {
     const rpc = this._getRpcFor(connection);
-    const { physicalPort, port, deviceId } = session;
+    const { physicalPort, port, host, deviceId } = session;
     let responded = false;
     const sendOk = () => {
       if (responded) return;
@@ -544,7 +565,7 @@ class PublishPort extends EventEmitter {
     const relaySocket = net.connect({ host: relayHost, port: physicalPort }, () => {
       relaySocket.setNoDelay(true);
     });
-    const localSocket = net.connect({ port }, () => {
+    const localSocket = net.connect({ port, host }, () => {
       localSocket.setNoDelay(true);
     });
     localSocket.pause();
@@ -616,7 +637,7 @@ class PublishPort extends EventEmitter {
 
   handleNativeUDPRelay(sessionId, physicalPortRef, session, connection) {
     const rpc = this._getRpcFor(connection);
-    const { physicalPort, port, deviceId } = session;
+    const { physicalPort, port, host, deviceId } = session;
     let responded = false;
     const sendOk = () => {
       if (responded) return;
@@ -672,7 +693,7 @@ class PublishPort extends EventEmitter {
       relayReady = true;
       maybeReady();
     });
-    localSocket.connect(port, '127.0.0.1', () => {
+    localSocket.connect(port, host, () => {
       localReady = true;
       maybeReady();
     });
@@ -706,12 +727,12 @@ class PublishPort extends EventEmitter {
     }
   }
 
-  handleTCPConnection(sessionId, ref, port, deviceId, connection) {
+  handleTCPConnection(sessionId, ref, port, deviceId, portConfig, connection) {
     const rpc = this._getRpcFor(connection);
     // Create a TCP connection to the local service on the specified port
-    const localSocket = net.connect({ port: port }, () => {
+    const localSocket = net.connect({ port, host: portConfig.host }, () => {
       localSocket.setNoDelay(true);
-      logger.info(() => `Connected to local TCP service on port ${port}`);
+      logger.info(() => `Connected to local TCP service on ${portConfig.host}:${port}`);
       // Send success response
       rpc.sendResponse(sessionId, ref, 'ok');
     });
@@ -720,10 +741,10 @@ class PublishPort extends EventEmitter {
     this.setupLocalSocketHandlers(localSocket, ref, 'tcp', rpc, connection);
 
     // Store the local socket with the ref using connection's method
-    connection.addConnection(ref, { socket: localSocket, protocol: 'tcp', port, deviceId });
+    connection.addConnection(ref, { socket: localSocket, protocol: 'tcp', port, host: portConfig.host, deviceId });
   }
 
-  handleTLSConnection(sessionId, ref, port, deviceId, connection) {
+  handleTLSConnection(sessionId, ref, port, deviceId, portConfig, connection) {
     const rpc = this._getRpcFor(connection);
     // Create a DiodeSocket instance
     const diodeSocket = new DiodeSocket(ref, rpc);
@@ -748,8 +769,8 @@ class PublishPort extends EventEmitter {
     });
     tlsSocket.setNoDelay(true);
     // Connect to the local service (TCP or TLS as needed)
-    const localSocket = net.connect({ port: port }, () => {
-      logger.info(() => `Connected to local TCP service on port ${port}`);
+    const localSocket = net.connect({ port, host: portConfig.host }, () => {
+      logger.info(() => `Connected to local TCP service on ${portConfig.host}:${port}`);
       // Send success response
       rpc.sendResponse(sessionId, ref, 'ok');
     });
@@ -775,11 +796,12 @@ class PublishPort extends EventEmitter {
       localSocket,
       protocol: 'tls',
       port,
+      host: portConfig.host,
       deviceId,
     });
   }
 
-  handleUDPConnection(sessionId, ref, port, deviceId, connection) {
+  handleUDPConnection(sessionId, ref, port, deviceId, portConfig, connection) {
     const rpc = this._getRpcFor(connection);
     // Create a UDP socket
     const localSocket = dgram.createSocket('udp4');
@@ -795,7 +817,7 @@ class PublishPort extends EventEmitter {
     });
 
     // Store the remote address and port from the Diode client
-    const remoteInfo = {port, address: '127.0.0.1'};
+    const remoteInfo = { port, address: portConfig.host };
 
     // Send success response
     rpc.sendResponse(sessionId, ref, 'ok');
@@ -806,10 +828,11 @@ class PublishPort extends EventEmitter {
       protocol: 'udp',
       remoteInfo,
       port,
+      host: portConfig.host,
       deviceId
     });
 
-    logger.info(() => `UDP connection set up on port ${port}`);
+    logger.info(() => `UDP connection set up for ${portConfig.host}:${port}`);
 
     // Handle messages from the local UDP service
     localSocket.on('message', (msg, rinfo) => {
@@ -835,7 +858,7 @@ class PublishPort extends EventEmitter {
     const connectionInfo = connection.getConnection(ref);
     // Check if the port is still open and address is still in whitelist
     if (connectionInfo) {
-      const { socket: localSocket, protocol, remoteInfo, port, deviceId } = connectionInfo;
+      const { socket: localSocket, protocol, remoteInfo, port, host, deviceId } = connectionInfo;
 
       if (!this.publishedPorts.has(port)) {
         logger.warn(() => `Port ${port} is not published. Sending portclose.`);
@@ -844,7 +867,7 @@ class PublishPort extends EventEmitter {
         return;
       }
 
-      const portConfig = this.publishedPorts.get(port);
+      const portConfig = this._getPublishedPortConfig(port);
       if (portConfig.mode === 'private' && Array.isArray(portConfig.whitelist)) {
         if (!portConfig.whitelist.includes(deviceId)) {
           logger.warn(() => `Device ${deviceId} is not whitelisted for port ${port}. Sending portclose.`);
@@ -865,7 +888,7 @@ class PublishPort extends EventEmitter {
 
         // Update remoteInfo if not set
         if (!localSocket.remoteAddress) {
-          localSocket.remoteAddress = '127.0.0.1'; // Assuming local service is on localhost
+          localSocket.remoteAddress = host || (remoteInfo && remoteInfo.address) || portConfig.host;
           localSocket.remotePort = port;
         }
       } else if (protocol === 'tcp') {

package/test/clientManager.relaySelection.test.js

@@ -8,6 +8,7 @@ const { WebSocketServer } = require('ws');
 
 const DiodeClientManager = require('../clientManager');
 const { fetchNetworkDirectory } = require('../networkDiscoveryClient');
+const { DEFAULT_FLEET_CONTRACT } = require('../utils');
 
 const networkSnapshot = JSON.parse(
   fs.readFileSync(path.join(__dirname, 'fixtures', 'dio-network-snapshot.json'), 'utf8')
@@ -48,6 +49,8 @@ class FakeConnection extends EventEmitter {
     this.socket = { destroyed: false };
     this.closeCount = 0;
     this.serverEthereumAddress = options.serverEthereumAddress || '0x' + Buffer.from(hostKey).toString('hex').slice(0, 40).padEnd(40, '0');
+    this.fleetContract = null;
+    this.fleetContractUpdates = [];
     this.RPC = {
       ping: async () => {
         await delay(options.pingDelayMs || 0);
@@ -66,6 +69,12 @@ class FakeConnection extends EventEmitter {
     this.localAddressProvider = provider;
   }
 
+  setFleetContract(address) {
+    this.fleetContract = address;
+    this.fleetContractUpdates.push(address);
+    return this;
+  }
+
   close() {
     this.closeCount += 1;
     this.socket.destroyed = true;
@@ -117,6 +126,75 @@ class TestClientManager extends DiodeClientManager {
   }
 }
 
+test('constructor-provided fleet contract propagates to new managed connections', async () => {
+  const tempDir = makeTempDir();
+  const keyLocation = path.join(tempDir, 'keys.json');
+  const connection = new FakeConnection('custom:41046');
+  const manager = new TestClientManager({
+    keyLocation,
+    hosts: ['custom:41046'],
+    fleetContract: '1234567890abcdef1234567890ABCDEF12345678',
+    relaySelection: { scoreCachePath: null, networkDiscovery: { enabled: false } },
+  }, new Map([
+    ['custom:41046', { connection }],
+  ]));
+
+  await manager.connect();
+
+  assert.equal(connection.fleetContract, '0x1234567890abcdef1234567890abcdef12345678');
+  manager.close();
+});
+
+test('setFleetContract updates existing and future managed connections', async () => {
+  const tempDir = makeTempDir();
+  const keyLocation = path.join(tempDir, 'keys.json');
+  const manager = new TestClientManager({
+    keyLocation,
+    relaySelection: { scoreCachePath: null, networkDiscovery: { enabled: false } },
+  });
+  const existing = new FakeConnection('existing:41046');
+  const future = new FakeConnection('future:41046');
+
+  manager._registerConnection(existing, 'existing:41046');
+  manager.hostBehaviors.set('future:41046', { connection: future });
+
+  manager.setFleetContract('0xabcdefabcdefabcdefabcdefabcdefabcdefabcd');
+  await manager._ensureConnection('future:41046');
+
+  assert.equal(existing.fleetContract, '0xabcdefabcdefabcdefabcdefabcdefabcdefabcd');
+  assert.equal(future.fleetContract, '0xabcdefabcdefabcdefabcdefabcdefabcdefabcd');
+  manager.close();
+});
+
+test('invalid fleet contract values fail fast', () => {
+  const tempDir = makeTempDir();
+  const keyLocation = path.join(tempDir, 'keys.json');
+
+  assert.throws(
+    () => new DiodeClientManager({ keyLocation, fleetContract: '0x1234', relaySelection: { scoreCachePath: null } }),
+    /fleetContract must be a 20-byte EVM address hex string/i,
+  );
+
+  const manager = new DiodeClientManager({ keyLocation, relaySelection: { scoreCachePath: null } });
+  assert.throws(
+    () => manager.setFleetContract('not-a-contract'),
+    /fleetContract must be a 20-byte EVM address hex string/i,
+  );
+  manager.close();
+});
+
+test('default fleet contract is applied when manager config is omitted', () => {
+  const tempDir = makeTempDir();
+  const keyLocation = path.join(tempDir, 'keys.json');
+  const manager = new DiodeClientManager({ keyLocation, relaySelection: { scoreCachePath: null } });
+  const connection = new FakeConnection('default:41046');
+
+  manager._registerConnection(connection, 'default:41046');
+
+  assert.equal(connection.fleetContract, DEFAULT_FLEET_CONTRACT);
+  manager.close();
+});
+
 test('tested candidates rank by measured latency', () => {
   const tempDir = makeTempDir();
   const keyLocation = path.join(tempDir, 'keys.json');

package/test/fleetContract.test.js

@@ -0,0 +1,71 @@
+const test = require('node:test');
+const assert = require('node:assert/strict');
+const os = require('os');
+const fs = require('fs');
+const path = require('path');
+
+const DiodeConnection = require('../connection');
+const { DEFAULT_FLEET_CONTRACT } = require('../utils');
+
+function makeTempDir() {
+  return fs.mkdtempSync(path.join(os.tmpdir(), 'diode-fleet-test-'));
+}
+
+function makeConnection() {
+  const tempDir = makeTempDir();
+  const keyLocation = path.join(tempDir, 'keys.json');
+  const connection = new DiodeConnection('relay.example', 41046, keyLocation);
+  connection.RPC = {
+    getEpoch: async () => 77,
+  };
+  connection._waitForServerEthereumAddress = async () => Buffer.from('aa'.repeat(20), 'hex');
+  return connection;
+}
+
+test('createTicketCommand uses the configured fleet contract in ticketv2', async () => {
+  const connection = makeConnection();
+
+  connection.setFleetContract('0x1111111111111111111111111111111111111111');
+  const command = await connection.createTicketCommand();
+
+  assert.equal(command[0], 'ticketv2');
+  assert.equal(command[2], 77);
+  assert.ok(Buffer.isBuffer(command[3]));
+  assert.equal(command[3].toString('hex'), '1111111111111111111111111111111111111111');
+});
+
+test('createTicketSignature changes when the fleet contract changes', async () => {
+  const connection = makeConnection();
+  const serverIdBuffer = Buffer.from('bb'.repeat(20), 'hex');
+  const totalConnections = 5;
+  const totalBytes = 123456;
+  const localAddress = 'client-a';
+  const epoch = 88;
+
+  const defaultSignature = await connection.createTicketSignature(
+    serverIdBuffer,
+    totalConnections,
+    totalBytes,
+    localAddress,
+    epoch,
+  );
+
+  connection.setFleetContract('0x2222222222222222222222222222222222222222');
+  const updatedSignature = await connection.createTicketSignature(
+    serverIdBuffer,
+    totalConnections,
+    totalBytes,
+    localAddress,
+    epoch,
+  );
+
+  assert.notDeepEqual(updatedSignature, defaultSignature);
+});
+
+test('DiodeConnection defaults to the existing fleet contract', async () => {
+  const connection = makeConnection();
+
+  const command = await connection.createTicketCommand();
+
+  assert.equal(command[3].toString('hex'), DEFAULT_FLEET_CONTRACT.slice(2));
+});

package/test/publishPort.test.js

@@ -0,0 +1,399 @@
+const test = require('node:test');
+const assert = require('node:assert/strict');
+const EventEmitter = require('events');
+const net = require('net');
+const tls = require('tls');
+const dgram = require('dgram');
+
+const PublishPort = require('../publishPort');
+
+class FakeStreamSocket extends EventEmitter {
+  constructor() {
+    super();
+    this.destroyed = false;
+    this.remoteAddress = undefined;
+    this.remotePort = undefined;
+  }
+
+  setNoDelay() {}
+  pause() {}
+  write() {}
+  end() {}
+  destroy() {
+    this.destroyed = true;
+  }
+  pipe(destination) {
+    return destination;
+  }
+}
+
+class FakeDatagramSocket extends EventEmitter {
+  constructor() {
+    super();
+    this.connectCalls = [];
+    this.sendCalls = [];
+    this.closed = false;
+    this.remoteAddress = undefined;
+    this.remotePort = undefined;
+  }
+
+  connect(port, host, callback) {
+    this.connectCalls.push({ port, host });
+    if (typeof callback === 'function') {
+      callback();
+    }
+  }
+
+  send(...args) {
+    if (args.length >= 3 && typeof args[1] === 'number' && typeof args[2] === 'string') {
+      this.sendCalls.push({ data: args[0], port: args[1], address: args[2] });
+    } else {
+      this.sendCalls.push({ data: args[0] });
+    }
+    const callback = args.find((arg) => typeof arg === 'function');
+    if (callback) {
+      callback(null);
+    }
+  }
+
+  close() {
+    this.closed = true;
+  }
+
+  setRecvBufferSize() {}
+  setSendBufferSize() {}
+}
+
+class FakeTlsSocket extends EventEmitter {
+  setNoDelay() {}
+  pipe(destination) {
+    return destination;
+  }
+}
+
+class FakeConnection extends EventEmitter {
+  constructor() {
+    super();
+    this.connections = new Map();
+    this.sentResponses = [];
+    this.sentErrors = [];
+    this.portCloseCalls = [];
+    this.portSendCalls = [];
+    this.RPC = {
+      sendResponse: async (...args) => {
+        this.sentResponses.push(args);
+      },
+      sendError: async (...args) => {
+        this.sentErrors.push(args);
+      },
+      portClose: async (...args) => {
+        this.portCloseCalls.push(args);
+      },
+      portSend: async (...args) => {
+        this.portSendCalls.push(args);
+      },
+    };
+  }
+
+  addConnection(ref, connectionInfo) {
+    this.connections.set(ref.toString('hex'), connectionInfo);
+  }
+
+  getConnection(ref) {
+    return this.connections.get(ref.toString('hex'));
+  }
+
+  deleteConnection(ref) {
+    return this.connections.delete(ref.toString('hex'));
+  }
+
+  getClientSocket() {
+    return null;
+  }
+
+  getServerRelayHost() {
+    return 'relay.example';
+  }
+
+  getDeviceCertificate() {
+    return 'fake-cert';
+  }
+
+  getEthereumAddress() {
+    return '0x' + 'aa'.repeat(20);
+  }
+
+  getPrivateKey() {
+    return Buffer.alloc(32, 1);
+  }
+}
+
+function makeRef(value = '01') {
+  return Buffer.from(value.padStart(2, '0'), 'hex');
+}
+
+function makeSessionId(value = '02') {
+  return Buffer.from(value.padStart(2, '0'), 'hex');
+}
+
+function makeDeviceId(hexByte) {
+  const byte = hexByte.length === 1 ? hexByte.repeat(2) : hexByte;
+  return Buffer.from(byte.repeat(20), 'hex');
+}
+
+test('PublishPort array input defaults host to 127.0.0.1', () => {
+  const connection = new FakeConnection();
+  const publishPort = new PublishPort(connection, [8080]);
+
+  assert.deepEqual(publishPort.getPublishedPorts(), {
+    8080: { mode: 'public', whitelist: [], host: '127.0.0.1' },
+  });
+
+  publishPort.stopListening();
+});
+
+test('PublishPort preserves explicit host in object config', () => {
+  const connection = new FakeConnection();
+  const publishPort = new PublishPort(connection, {
+    8080: { mode: 'private', whitelist: ['0xabc'], host: ' backend.internal ' },
+  });
+
+  assert.deepEqual(publishPort.getPublishedPorts(), {
+    8080: { mode: 'private', whitelist: ['0xabc'], host: 'backend.internal' },
+  });
+
+  publishPort.stopListening();
+});
+
+test('PublishPort rejects invalid host values', () => {
+  const connection = new FakeConnection();
+
+  assert.throws(() => {
+    new PublishPort(connection, { 8080: { mode: 'public', host: '   ' } });
+  }, TypeError);
+
+  assert.throws(() => {
+    new PublishPort(connection, { 8080: { mode: 'public', host: 42 } });
+  }, TypeError);
+});
+
+test('TCP publish connects to configured host', () => {
+  const connection = new FakeConnection();
+  const publishPort = new PublishPort(connection, {
+    8080: { mode: 'public', host: '192.168.1.10' },
+  });
+  const originalConnect = net.connect;
+  const connectCalls = [];
+
+  net.connect = (options, callback) => {
+    const socket = new FakeStreamSocket();
+    connectCalls.push(options);
+    process.nextTick(() => {
+      if (typeof callback === 'function') {
+        callback();
+      }
+    });
+    return socket;
+  };
+
+  try {
+    publishPort.handleTCPConnection(makeSessionId(), makeRef(), 8080, '0x' + '11'.repeat(20), publishPort.getPublishedPorts()[8080], connection);
+  } finally {
+    net.connect = originalConnect;
+    publishPort.stopListening();
+  }
+
+  assert.equal(connectCalls.length, 1);
+  assert.deepEqual(connectCalls[0], { port: 8080, host: '192.168.1.10' });
+});
+
+test('TLS publish backend socket connects to configured host', () => {
+  const connection = new FakeConnection();
+  const publishPort = new PublishPort(connection, {
+    8443: { mode: 'public', host: 'backend.internal' },
+  });
+  const originalConnect = net.connect;
+  const originalTlsSocket = tls.TLSSocket;
+  const connectCalls = [];
+
+  net.connect = (options, callback) => {
+    const socket = new FakeStreamSocket();
+    connectCalls.push(options);
+    process.nextTick(() => {
+      if (typeof callback === 'function') {
+        callback();
+      }
+    });
+    return socket;
+  };
+  tls.TLSSocket = FakeTlsSocket;
+
+  try {
+    publishPort.handleTLSConnection(makeSessionId(), makeRef('03'), 8443, '0x' + '11'.repeat(20), publishPort.getPublishedPorts()[8443], connection);
+  } finally {
+    net.connect = originalConnect;
+    tls.TLSSocket = originalTlsSocket;
+    publishPort.stopListening();
+  }
+
+  assert.equal(connectCalls.length, 1);
+  assert.deepEqual(connectCalls[0], { port: 8443, host: 'backend.internal' });
+});
+
+test('UDP publish stores and sends to configured host', () => {
+  const connection = new FakeConnection();
+  const publishPort = new PublishPort(connection, {
+    5353: { mode: 'public', host: '192.168.1.20' },
+  });
+  const originalCreateSocket = dgram.createSocket;
+  const sockets = [];
+
+  dgram.createSocket = () => {
+    const socket = new FakeDatagramSocket();
+    sockets.push(socket);
+    return socket;
+  };
+
+  try {
+    const ref = makeRef('04');
+    publishPort.handleUDPConnection(makeSessionId('05'), ref, 5353, '0x' + '11'.repeat(20), publishPort.getPublishedPorts()[5353], connection);
+    publishPort.handlePortSend(makeSessionId('06'), ['portsend', ref, Buffer.from('hello')], connection);
+
+    const connectionInfo = connection.getConnection(ref);
+    assert.deepEqual(connectionInfo.remoteInfo, { port: 5353, address: '192.168.1.20' });
+    assert.equal(sockets[0].sendCalls.length, 1);
+    assert.equal(sockets[0].sendCalls[0].address, '192.168.1.20');
+    assert.equal(sockets[0].sendCalls[0].port, 5353);
+  } finally {
+    dgram.createSocket = originalCreateSocket;
+    publishPort.stopListening();
+  }
+});
+
+test('native TCP publish connects local socket to configured host', () => {
+  const connection = new FakeConnection();
+  const publishPort = new PublishPort(connection, {
+    8089: { mode: 'public', host: '10.0.0.8' },
+  });
+  const originalConnect = net.connect;
+  const connectCalls = [];
+
+  net.connect = (options, callback) => {
+    const socket = new FakeStreamSocket();
+    connectCalls.push(options);
+    process.nextTick(() => {
+      if (typeof callback === 'function') {
+        callback();
+      }
+      socket.emit('connect');
+    });
+    return socket;
+  };
+
+  try {
+    publishPort.handleNativeTCPRelay(
+      makeSessionId('07'),
+      41000,
+      { physicalPort: 41000, port: 8089, host: '10.0.0.8', deviceId: '0x' + '11'.repeat(20), ready: false, session: null },
+      connection
+    );
+  } finally {
+    net.connect = originalConnect;
+    publishPort.stopListening();
+  }
+
+  assert.equal(connectCalls.length, 2);
+  assert.deepEqual(connectCalls[0], { host: 'relay.example', port: 41000 });
+  assert.deepEqual(connectCalls[1], { port: 8089, host: '10.0.0.8' });
+});
+
+test('native UDP publish connects local socket to configured host', () => {
+  const connection = new FakeConnection();
+  const publishPort = new PublishPort(connection, {
+    8090: { mode: 'public', host: 'backend.internal' },
+  });
+  const originalCreateSocket = dgram.createSocket;
+  const sockets = [];
+
+  dgram.createSocket = () => {
+    const socket = new FakeDatagramSocket();
+    sockets.push(socket);
+    return socket;
+  };
+
+  try {
+    publishPort.handleNativeUDPRelay(
+      makeSessionId('08'),
+      41001,
+      { physicalPort: 41001, port: 8090, host: 'backend.internal', deviceId: '0x' + '11'.repeat(20), ready: false, session: null },
+      connection
+    );
+  } finally {
+    dgram.createSocket = originalCreateSocket;
+    publishPort.stopListening();
+  }
+
+  assert.equal(sockets.length, 2);
+  assert.deepEqual(sockets[0].connectCalls[0], { port: 41001, host: 'relay.example' });
+  assert.deepEqual(sockets[1].connectCalls[0], { port: 8090, host: 'backend.internal' });
+});
+
+test('handlePortOpen preserves localhost default when host is omitted', () => {
+  const connection = new FakeConnection();
+  const publishPort = new PublishPort(connection, [8081]);
+  const originalConnect = net.connect;
+  const connectCalls = [];
+
+  net.connect = (options, callback) => {
+    const socket = new FakeStreamSocket();
+    connectCalls.push(options);
+    process.nextTick(() => {
+      if (typeof callback === 'function') {
+        callback();
+      }
+    });
+    return socket;
+  };
+
+  try {
+    publishPort.handlePortOpen(
+      makeSessionId('09'),
+      ['portopen', '8081', makeRef('0a'), makeDeviceId('1')],
+      connection
+    );
+  } finally {
+    net.connect = originalConnect;
+    publishPort.stopListening();
+  }
+
+  assert.deepEqual(connectCalls[0], { port: 8081, host: '127.0.0.1' });
+});
+
+test('handlePortOpen rejects non-whitelisted devices before connecting', () => {
+  const connection = new FakeConnection();
+  const publishPort = new PublishPort(connection, {
+    3000: { mode: 'private', whitelist: ['0x' + '22'.repeat(20)], host: '192.168.1.30' },
+  });
+  const originalConnect = net.connect;
+  let connectCalled = false;
+
+  net.connect = () => {
+    connectCalled = true;
+    return new FakeStreamSocket();
+  };
+
+  try {
+    publishPort.handlePortOpen(
+      makeSessionId('0b'),
+      ['portopen', '3000', makeRef('0c'), makeDeviceId('1')],
+      connection
+    );
+  } finally {
+    net.connect = originalConnect;
+    publishPort.stopListening();
+  }
+
+  assert.equal(connectCalled, false);
+  assert.equal(connection.sentErrors.length, 1);
+  assert.equal(connection.sentErrors[0][2], 'Device not whitelisted');
+});

package/utils.js

@@ -199,6 +199,30 @@ function ensureDirectoryExistence(filePath) {
   fs.mkdirSync(dirname);
 }
 
+const DEFAULT_FLEET_CONTRACT = '0x6000000000000000000000000000000000000000';
+
+function normalizeFleetContractAddress(value) {
+  if (Buffer.isBuffer(value) || value instanceof Uint8Array) {
+    const buffer = toBufferView(value);
+    if (buffer.length !== 20) {
+      throw new Error('fleetContract must be a 20-byte EVM address');
+    }
+    return `0x${buffer.toString('hex')}`.toLowerCase();
+  }
+
+  if (typeof value !== 'string') {
+    throw new Error('fleetContract must be a 20-byte EVM address hex string');
+  }
+
+  const trimmed = value.trim();
+  const hex = trimmed.toLowerCase().startsWith('0x') ? trimmed.slice(2) : trimmed;
+  if (!/^[0-9a-fA-F]{40}$/.test(hex)) {
+    throw new Error('fleetContract must be a 20-byte EVM address hex string');
+  }
+
+  return `0x${hex.toLowerCase()}`;
+}
+
 module.exports = { 
   makeReadable, 
   parseRequestId, 
@@ -209,4 +233,6 @@ module.exports = {
   loadOrGenerateKeyPair,
   ensureDirectoryExistence,
   toBufferView,
+  DEFAULT_FLEET_CONTRACT,
+  normalizeFleetContractAddress,
 };