@olane/o-node 0.7.13-alpha.1 → 0.7.13

package/dist/src/connection/o-node-connection.manager.d.ts

@@ -7,13 +7,21 @@ export declare class oNodeConnectionManager extends oConnectionManager {
     protected p2pNode: Libp2p;
     private defaultReadTimeoutMs?;
     private defaultDrainTimeoutMs?;
-    private connectionsByPeerId;
-    private pendingDialsByPeerId;
+    private connectionsByTransportKey;
+    private pendingDialsByTransportKey;
     constructor(config: oNodeConnectionManagerConfig);
     /**
      * Set up listeners to maintain connection cache state
      */
     private setupConnectionListeners;
+    /**
+     * Build a stable cache key from the libp2p transports on an address.
+     *
+     * We intentionally key the cache by transports (multiaddrs) instead of peer IDs
+     * to avoid ambiguity when multiple peers may share a peer ID or when addresses
+     * change but the libp2p transports are the true dial targets.
+     */
+    private getTransportKeyFromAddress;
     /**
      * Extract peer ID string from an address
      * @param address - The address to extract peer ID from

package/dist/src/connection/o-node-connection.manager.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"o-node-connection.manager.d.ts","sourceRoot":"","sources":["../../../src/connection/o-node-connection.manager.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,QAAQ,EAAE,iBAAiB,EAAE,kBAAkB,EAAE,MAAM,eAAe,CAAC;AAChF,OAAO,EAAE,MAAM,EAAE,UAAU,EAAU,MAAM,iBAAiB,CAAC;AAC7D,OAAO,EAAE,4BAA4B,EAAE,MAAM,kDAAkD,CAAC;AAEhG,OAAO,EAAE,eAAe,EAAE,MAAM,wBAAwB,CAAC;AAGzD,qBAAa,sBAAuB,SAAQ,kBAAkB;IAOhD,QAAQ,CAAC,MAAM,EAAE,4BAA4B;IANzD,SAAS,CAAC,OAAO,EAAE,MAAM,CAAC;IAC1B,OAAO,CAAC,oBAAoB,CAAC,CAAS;IACtC,OAAO,CAAC,qBAAqB,CAAC,CAAS;IACvC,OAAO,CAAC,mBAAmB,CAAsC;IACjE,OAAO,CAAC,oBAAoB,CAA+C;gBAEtD,MAAM,EAAE,4BAA4B;IAWzD;;OAEG;IACH,OAAO,CAAC,wBAAwB;IAUhC;;;;OAIG;IACH,OAAO,CAAC,oBAAoB;IAatB,qBAAqB,CACzB,cAAc,EAAE,QAAQ,EACxB,OAAO,EAAE,QAAQ,GAChB,OAAO,CAAC,UAAU,CAAC;YAmDR,WAAW;IAwBzB;;;;OAIG;IACG,OAAO,CAAC,MAAM,EAAE,iBAAiB,GAAG,OAAO,CAAC,eAAe,CAAC;IA8BlE;;;;OAIG;IACH,QAAQ,CAAC,OAAO,EAAE,QAAQ,GAAG,OAAO;IAmCpC;;;;OAIG;IACH,yBAAyB,CAAC,OAAO,EAAE,QAAQ,GAAG,UAAU,GAAG,IAAI;IA0C/D;;;OAGG;IACH,aAAa,IAAI;QACf,iBAAiB,EAAE,MAAM,CAAC;QAC1B,YAAY,EAAE,MAAM,CAAC;QACrB,iBAAiB,EAAE,KAAK,CAAC;YAAE,MAAM,EAAE,MAAM,CAAC;YAAC,MAAM,EAAE,MAAM,CAAA;SAAE,CAAC,CAAC;KAC9D;IAaD;;;OAGG;IACH,uBAAuB,IAAI,MAAM;CAalC"}
+{"version":3,"file":"o-node-connection.manager.d.ts","sourceRoot":"","sources":["../../../src/connection/o-node-connection.manager.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,QAAQ,EAAE,iBAAiB,EAAE,kBAAkB,EAAE,MAAM,eAAe,CAAC;AAChF,OAAO,EAAE,MAAM,EAAE,UAAU,EAAU,MAAM,iBAAiB,CAAC;AAC7D,OAAO,EAAE,4BAA4B,EAAE,MAAM,kDAAkD,CAAC;AAEhG,OAAO,EAAE,eAAe,EAAE,MAAM,wBAAwB,CAAC;AAGzD,qBAAa,sBAAuB,SAAQ,kBAAkB;IAOhD,QAAQ,CAAC,MAAM,EAAE,4BAA4B;IANzD,SAAS,CAAC,OAAO,EAAE,MAAM,CAAC;IAC1B,OAAO,CAAC,oBAAoB,CAAC,CAAS;IACtC,OAAO,CAAC,qBAAqB,CAAC,CAAS;IACvC,OAAO,CAAC,yBAAyB,CAAsC;IACvE,OAAO,CAAC,0BAA0B,CAA+C;gBAE5D,MAAM,EAAE,4BAA4B;IAWzD;;OAEG;IACH,OAAO,CAAC,wBAAwB;IAmBhC;;;;;;OAMG;IACH,OAAO,CAAC,0BAA0B;IAiBlC;;;;OAIG;IACH,OAAO,CAAC,oBAAoB;IAatB,qBAAqB,CACzB,cAAc,EAAE,QAAQ,EACxB,OAAO,EAAE,QAAQ,GAChB,OAAO,CAAC,UAAU,CAAC;YAsDR,WAAW;IAwBzB;;;;OAIG;IACG,OAAO,CAAC,MAAM,EAAE,iBAAiB,GAAG,OAAO,CAAC,eAAe,CAAC;IA8BlE;;;;OAIG;IACH,QAAQ,CAAC,OAAO,EAAE,QAAQ,GAAG,OAAO;IAoCpC;;;;OAIG;IACH,yBAAyB,CAAC,OAAO,EAAE,QAAQ,GAAG,UAAU,GAAG,IAAI;IA+C/D;;;OAGG;IACH,aAAa,IAAI;QACf,iBAAiB,EAAE,MAAM,CAAC;QAC1B,YAAY,EAAE,MAAM,CAAC;QACrB,iBAAiB,EAAE,KAAK,CAAC;YAAE,MAAM,EAAE,MAAM,CAAC;YAAC,MAAM,EAAE,MAAM,CAAA;SAAE,CAAC,CAAC;KAC9D;IAaD;;;OAGG;IACH,uBAAuB,IAAI,MAAM;CAalC"}

package/dist/src/connection/o-node-connection.manager.js

@@ -4,8 +4,8 @@ export class oNodeConnectionManager extends oConnectionManager {
     constructor(config) {
         super(config);
         this.config = config;
-        this.connectionsByPeerId = new Map();
-        this.pendingDialsByPeerId = new Map();
+        this.connectionsByTransportKey = new Map();
+        this.pendingDialsByTransportKey = new Map();
         this.p2pNode = config.p2pNode;
         this.defaultReadTimeoutMs = config.defaultReadTimeoutMs;
         this.defaultDrainTimeoutMs = config.defaultDrainTimeoutMs;
@@ -18,13 +18,41 @@ export class oNodeConnectionManager extends oConnectionManager {
      */
     setupConnectionListeners() {
         this.p2pNode.addEventListener('connection:close', (event) => {
-            const peerId = event.detail?.remotePeer?.toString();
-            if (peerId && this.connectionsByPeerId.has(peerId)) {
-                this.logger.debug('Connection closed, removing from cache:', peerId);
-                this.connectionsByPeerId.delete(peerId);
+            const connection = event.detail;
+            if (!connection) {
+                return;
+            }
+            for (const [transportKey, cachedConnection] of this.connectionsByTransportKey.entries()) {
+                if (cachedConnection === connection) {
+                    this.logger.debug('Connection closed, removing from cache for transport key:', transportKey);
+                    this.connectionsByTransportKey.delete(transportKey);
+                }
             }
         });
     }
+    /**
+     * Build a stable cache key from the libp2p transports on an address.
+     *
+     * We intentionally key the cache by transports (multiaddrs) instead of peer IDs
+     * to avoid ambiguity when multiple peers may share a peer ID or when addresses
+     * change but the libp2p transports are the true dial targets.
+     */
+    getTransportKeyFromAddress(address) {
+        try {
+            const nodeAddress = address;
+            const transports = nodeAddress.libp2pTransports;
+            if (!transports?.length) {
+                return null;
+            }
+            // Sort to ensure deterministic keys regardless of transport ordering.
+            const parts = transports.map((t) => t.toString()).sort();
+            return parts.join('|');
+        }
+        catch (error) {
+            this.logger.debug('Error extracting transport key from address:', error);
+            return null;
+        }
+    }
     /**
      * Extract peer ID string from an address
      * @param address - The address to extract peer ID from
@@ -44,56 +72,56 @@ export class oNodeConnectionManager extends oConnectionManager {
         }
     }
     async getOrCreateConnection(nextHopAddress, address) {
-        // Extract peer ID as the cache key
-        const peerId = this.getPeerIdFromAddress(nextHopAddress);
-        if (!peerId) {
-            throw new Error(`Unable to extract peer ID from address: ${nextHopAddress.toString()}`);
+        // Build a transport-based cache key from the next hop address
+        const transportKey = this.getTransportKeyFromAddress(nextHopAddress);
+        if (!transportKey) {
+            throw new Error(`Unable to extract libp2p transports from address: ${nextHopAddress.toString()}`);
         }
-        // Check if we have a cached connection by peer ID
-        const cachedConnection = this.connectionsByPeerId.get(peerId);
+        // Check if we have a cached connection by transport key
+        const cachedConnection = this.connectionsByTransportKey.get(transportKey);
         if (cachedConnection && cachedConnection.status === 'open') {
-            this.logger.debug('Reusing cached connection for peer:', peerId);
+            this.logger.debug('Reusing cached connection for transports:', transportKey);
             return cachedConnection;
         }
         // Clean up stale connection if it exists but is not open
         if (cachedConnection && cachedConnection.status !== 'open') {
-            this.logger.debug('Removing stale connection for peer:', peerId);
-            this.connectionsByPeerId.delete(peerId);
+            this.logger.debug('Removing stale connection for transports:', transportKey);
+            this.connectionsByTransportKey.delete(transportKey);
         }
-        // Check if libp2p has an active connection to this peer
+        // Check if libp2p has an active connection for this address
         const libp2pConnection = this.getCachedLibp2pConnection(nextHopAddress);
         if (libp2pConnection && libp2pConnection.status === 'open') {
-            this.logger.debug('Caching existing libp2p connection for peer:', peerId);
-            this.connectionsByPeerId.set(peerId, libp2pConnection);
+            this.logger.debug('Caching existing libp2p connection for transports:', transportKey);
+            this.connectionsByTransportKey.set(transportKey, libp2pConnection);
             return libp2pConnection;
         }
-        // Check if dial is already in progress for this peer
-        const pendingDial = this.pendingDialsByPeerId.get(peerId);
+        // Check if dial is already in progress for this transport key
+        const pendingDial = this.pendingDialsByTransportKey.get(transportKey);
         if (pendingDial) {
-            this.logger.debug('Awaiting existing dial for peer:', peerId);
+            this.logger.debug('Awaiting existing dial for transports:', transportKey);
             return pendingDial;
         }
-        // Start new dial and cache the promise by peer ID
-        const dialPromise = this.performDial(nextHopAddress, peerId);
-        this.pendingDialsByPeerId.set(peerId, dialPromise);
+        // Start new dial and cache the promise by transport key
+        const dialPromise = this.performDial(nextHopAddress, transportKey);
+        this.pendingDialsByTransportKey.set(transportKey, dialPromise);
         try {
             const connection = await dialPromise;
-            // Cache the established connection by peer ID
-            this.connectionsByPeerId.set(peerId, connection);
+            // Cache the established connection by transport key
+            this.connectionsByTransportKey.set(transportKey, connection);
             return connection;
         }
         finally {
-            this.pendingDialsByPeerId.delete(peerId);
+            this.pendingDialsByTransportKey.delete(transportKey);
         }
     }
-    async performDial(nextHopAddress, peerId) {
+    async performDial(nextHopAddress, transportKey) {
         this.logger.debug('Dialing new connection', {
             address: nextHopAddress.value,
-            peerId,
+            transportKey,
         });
         const connection = await this.p2pNode.dial(nextHopAddress.libp2pTransports.map((ma) => ma.toMultiaddr()));
         this.logger.debug('Successfully dialed connection', {
-            peerId,
+            transportKey,
             status: connection.status,
             remotePeer: connection.remotePeer?.toString(),
         });
@@ -128,16 +156,17 @@ export class oNodeConnectionManager extends oConnectionManager {
      */
     isCached(address) {
         try {
-            const peerId = this.getPeerIdFromAddress(address);
-            if (!peerId) {
+            const transportKey = this.getTransportKeyFromAddress(address);
+            if (!transportKey) {
                 return false;
             }
-            // Check our peer ID-based cache first
-            const cachedConnection = this.connectionsByPeerId.get(peerId);
+            // Check our transport-based cache first
+            const cachedConnection = this.connectionsByTransportKey.get(transportKey);
             if (cachedConnection?.status === 'open') {
                 return true;
             }
             // Fall back to checking libp2p's connections
+            const peerId = this.getPeerIdFromAddress(address);
             // the following works since the peer id param is not really required: https://github.com/libp2p/js-libp2p/blob/0bbf5021b53938b2bffcffca6c13c479a95c2a60/packages/libp2p/src/connection-manager/index.ts#L508
             const connections = this.p2pNode.getConnections(peerId); // ignore since converting to a proper peer id breaks the browser implementation
             // Check if we have at least one open connection
@@ -146,7 +175,7 @@ export class oNodeConnectionManager extends oConnectionManager {
             if (hasOpenConnection) {
                 const openConnection = connections.find((conn) => conn.status === 'open');
                 if (openConnection) {
-                    this.connectionsByPeerId.set(peerId, openConnection);
+                    this.connectionsByTransportKey.set(transportKey, openConnection);
                 }
             }
             return hasOpenConnection;
@@ -163,28 +192,32 @@ export class oNodeConnectionManager extends oConnectionManager {
      */
     getCachedLibp2pConnection(address) {
         try {
-            const peerId = this.getPeerIdFromAddress(address);
-            if (!peerId) {
+            const transportKey = this.getTransportKeyFromAddress(address);
+            if (!transportKey) {
                 return null;
             }
-            // Check peer ID-based cache first
-            const cachedConnection = this.connectionsByPeerId.get(peerId);
+            // Check transport-based cache first
+            const cachedConnection = this.connectionsByTransportKey.get(transportKey);
             if (cachedConnection?.status === 'open') {
                 return cachedConnection;
             }
+            const peerId = this.getPeerIdFromAddress(address);
+            if (!peerId) {
+                return null;
+            }
             // Query libp2p for connections to this peer
             const connections = this.p2pNode.getConnections();
             const filteredConnections = connections.filter((conn) => conn.remotePeer?.toString() === peerId);
             // Find the first open connection
             const openConnection = filteredConnections.find((conn) => conn.status === 'open');
-            // If we found an open connection in libp2p, cache it by peer ID
+            // If we found an open connection in libp2p, cache it by transport key
             if (openConnection) {
-                this.connectionsByPeerId.set(peerId, openConnection);
+                this.connectionsByTransportKey.set(transportKey, openConnection);
                 return openConnection;
             }
             // Clean up stale cache entry if connection is no longer open
             if (cachedConnection) {
-                this.connectionsByPeerId.delete(peerId);
+                this.connectionsByTransportKey.delete(transportKey);
             }
             return null;
         }
@@ -199,10 +232,10 @@ export class oNodeConnectionManager extends oConnectionManager {
      */
     getCacheStats() {
         return {
-            cachedConnections: this.connectionsByPeerId.size,
-            pendingDials: this.pendingDialsByPeerId.size,
-            connectionsByPeer: Array.from(this.connectionsByPeerId.entries()).map(([peerId, conn]) => ({
-                peerId,
+            cachedConnections: this.connectionsByTransportKey.size,
+            pendingDials: this.pendingDialsByTransportKey.size,
+            connectionsByPeer: Array.from(this.connectionsByTransportKey.values()).map((conn) => ({
+                peerId: conn.remotePeer?.toString() ?? 'unknown',
                 status: conn.status,
             })),
         };
@@ -213,9 +246,9 @@ export class oNodeConnectionManager extends oConnectionManager {
      */
     cleanupStaleConnections() {
         let removed = 0;
-        for (const [peerId, connection] of this.connectionsByPeerId.entries()) {
+        for (const [transportKey, connection] of this.connectionsByTransportKey.entries()) {
             if (connection.status !== 'open') {
-                this.connectionsByPeerId.delete(peerId);
+                this.connectionsByTransportKey.delete(transportKey);
                 removed++;
             }
         }

package/dist/src/o-node.d.ts

@@ -49,6 +49,20 @@ export declare class oNode extends oToolBase {
     initConnectionManager(): Promise<void>;
     hookInitializeFinished(): Promise<void>;
     hookStartFinished(): Promise<void>;
+    /**
+     * Validates that if a leader address is defined, it has associated transports.
+     * This is critical for non-leader nodes to be able to connect to their leader.
+     * @throws Error if leader is defined but has no transports
+     */
+    private validateLeaderTransports;
+    /**
+     * oNode-specific validation that runs before core start() logic.
+     *
+     * This ensures that leader transport configuration errors are
+     * surfaced quickly and before any libp2p nodes or other heavy
+     * resources are created.
+     */
+    protected validate(): Promise<void>;
     initialize(): Promise<void>;
     /**
      * Override use() to wrap leader/registry requests with retry logic

package/dist/src/o-node.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"o-node.d.ts","sourceRoot":"","sources":["../../src/o-node.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"o-node.d.ts","sourceRoot":"","sources":["../../src/o-node.ts"],"names":[],"mappings":"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"}

package/dist/src/o-node.js

@@ -75,11 +75,11 @@ export class oNode extends oToolBase {
                         params: {
                             eventType: 'node:stopping',
                             eventData: {
-                                address: this.address.toString(),
+                                address: this.address?.toString(),
                                 reason: 'graceful_shutdown',
                                 expectedDowntime: null,
                             },
-                            source: this.address.toString(),
+                            source: this.address?.toString(),
                         },
                     }),
                     new Promise((_, reject) => setTimeout(() => reject(new Error('timeout')), 2000)),
@@ -94,12 +94,16 @@ export class oNode extends oToolBase {
             this.logger.debug('No leader found, skipping unregistration');
             return;
         }
+        // no need to unregister since we did not generate a peerID yet
+        if (!this.peerId) {
+            return;
+        }
         const address = new oNodeAddress(RestrictedAddresses.REGISTRY);
         // attempt to unregister from the network
         const params = {
             method: 'remove',
             params: {
-                peerId: this.peerId.toString(),
+                peerId: this.peerId?.toString(),
             },
         };
         this.use(address, params).catch((error) => {
@@ -367,6 +371,42 @@ export class oNode extends oToolBase {
         this.logger.info(`Connection heartbeat config: leader=${this.connectionHeartbeatManager.getConfig().checkLeader}, ` +
             `parent=${this.connectionHeartbeatManager.getConfig().checkParent}`);
     }
+    /**
+     * Validates that if a leader address is defined, it has associated transports.
+     * This is critical for non-leader nodes to be able to connect to their leader.
+     * @throws Error if leader is defined but has no transports
+     */
+    async validateLeaderTransports() {
+        // Skip validation if this node is the leader itself
+        if (this.isLeader) {
+            return;
+        }
+        // Skip validation if no leader is configured
+        const leaderAddress = this.config?.leader;
+        if (!leaderAddress) {
+            return;
+        }
+        // Check if leader has transports
+        if (!leaderAddress.transports || leaderAddress.transports.length === 0) {
+            throw new Error(`Leader address is defined (${leaderAddress.toString()}) but has no transports. ` +
+                `Non-leader nodes require leader transports for network connectivity. ` +
+                `Please provide transports in the leader address configuration.`);
+        }
+        this.logger.debug('Leader transport validation passed', {
+            leader: leaderAddress.toString(),
+            transportCount: leaderAddress.transports.length
+        });
+    }
+    /**
+     * oNode-specific validation that runs before core start() logic.
+     *
+     * This ensures that leader transport configuration errors are
+     * surfaced quickly and before any libp2p nodes or other heavy
+     * resources are created.
+     */
+    async validate() {
+        await this.validateLeaderTransports();
+    }
     async initialize() {
         this.logger.debug('Initializing node...');
         if (this.state !== NodeState.STOPPED && this.state !== NodeState.STARTING) {

package/dist/test/connection-management.spec.js

@@ -145,7 +145,7 @@ describe('Connection Management', () => {
                 method: 'echo',
                 params: { message: 'test' },
             }).catch((err) => {
-                expect(err.message).to.be.equal('Unable to extract peer ID from address: o://nonexistent');
+                expect(err.code).to.be.equal('ECONNREFUSED');
             });
         });
         it('should verify connection is open before use', async () => {

package/dist/test/leader-transport-validation.spec.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=leader-transport-validation.spec.d.ts.map

package/dist/test/leader-transport-validation.spec.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"leader-transport-validation.spec.d.ts","sourceRoot":"","sources":["../../test/leader-transport-validation.spec.ts"],"names":[],"mappings":""}

package/dist/test/leader-transport-validation.spec.js

@@ -0,0 +1,177 @@
+import { expect } from 'chai';
+import { TestEnvironment } from './helpers/index.js';
+import { oNodeTool } from '../src/o-node.tool.js';
+import { oNodeAddress, oNodeTransport } from '../src/index.js';
+describe('Leader Transport Validation', () => {
+    const env = new TestEnvironment();
+    afterEach(async () => {
+        await env.cleanup();
+    });
+    describe('Node with leader configuration', () => {
+        it('should fail to start when leader has no transports', async () => {
+            const leaderAddress = new oNodeAddress('o://leader', []); // Empty transports
+            const node = new oNodeTool({
+                address: new oNodeAddress('o://child'),
+                leader: leaderAddress,
+                parent: null,
+            });
+            try {
+                await node.start();
+                expect.fail('Expected node.start() to throw an error');
+            }
+            catch (error) {
+                expect(error.message).to.include('Leader address is defined');
+                expect(error.message).to.include('but has no transports');
+                expect(error.message).to.include('o://leader');
+            }
+        });
+        it('should fail to start when leader has undefined transports', async () => {
+            const leaderAddress = new oNodeAddress('o://leader');
+            // Explicitly set transports to undefined
+            leaderAddress.transports = undefined;
+            const node = new oNodeTool({
+                address: new oNodeAddress('o://child'),
+                leader: leaderAddress,
+                parent: null,
+            });
+            try {
+                await node.start();
+                expect.fail('Expected node.start() to throw an error');
+            }
+            catch (error) {
+                expect(error.message).to.include('Leader address is defined');
+                expect(error.message).to.include('but has no transports');
+                expect(error.message).to.include('o://leader');
+            }
+        });
+        it('should fail to start when leader has null transports', async () => {
+            const leaderAddress = new oNodeAddress('o://leader');
+            // Explicitly set transports to null
+            leaderAddress.transports = null;
+            const node = new oNodeTool({
+                address: new oNodeAddress('o://child'),
+                leader: leaderAddress,
+                parent: null,
+            });
+            try {
+                await node.start();
+                expect.fail('Expected node.start() to throw an error');
+            }
+            catch (error) {
+                expect(error.message).to.include('Leader address is defined');
+                expect(error.message).to.include('but has no transports');
+                expect(error.message).to.include('o://leader');
+            }
+        });
+        it('should start successfully when leader has valid transports', async () => {
+            const leaderAddress = new oNodeAddress('o://leader', [
+                new oNodeTransport('/ip4/127.0.0.1/tcp/4001/p2p/12D3KooWTest123'),
+            ]);
+            const node = new oNodeTool({
+                address: new oNodeAddress('o://child'),
+                leader: leaderAddress,
+                parent: null,
+            });
+            // Should not throw
+            await node.start();
+            expect(node.state).to.not.equal('STOPPED');
+            await node.stop();
+        });
+        it('should start successfully when leader has multiple transports', async () => {
+            const leaderAddress = new oNodeAddress('o://leader', [
+                new oNodeTransport('/ip4/127.0.0.1/tcp/4001/p2p/12D3KooWTest123'),
+                new oNodeTransport('/ip4/192.168.1.1/tcp/4001/p2p/12D3KooWTest123'),
+            ]);
+            const node = new oNodeTool({
+                address: new oNodeAddress('o://child'),
+                leader: leaderAddress,
+                parent: null,
+            });
+            // Should not throw
+            await node.start();
+            expect(node.state).to.not.equal('STOPPED');
+            await node.stop();
+        });
+    });
+    describe('Node without leader configuration', () => {
+        it('should start successfully when leader is null', async () => {
+            const node = new oNodeTool({
+                address: new oNodeAddress('o://standalone'),
+                leader: null,
+                parent: null,
+            });
+            // Should not throw
+            await node.start();
+            expect(node.state).to.not.equal('STOPPED');
+            await node.stop();
+        });
+        it('should start successfully when leader is undefined', async () => {
+            const node = new oNodeTool({
+                address: new oNodeAddress('o://standalone'),
+                leader: undefined, // Explicitly undefined
+                parent: null,
+            });
+            // Should not throw
+            await node.start();
+            expect(node.state).to.not.equal('STOPPED');
+            await node.stop();
+        });
+    });
+    describe('Leader node (self-referential)', () => {
+        it('should start successfully as a leader without transports validation', async () => {
+            const node = new oNodeTool({
+                address: new oNodeAddress('o://leader'),
+                leader: null, // Leader nodes don't need a leader reference
+                parent: null,
+                type: 'LEADER', // Set as leader node
+            });
+            // Should not throw - leader nodes don't need leader transports
+            await node.start();
+            expect(node.state).to.not.equal('STOPPED');
+            await node.stop();
+        });
+    });
+    describe('Error message content', () => {
+        it('should provide helpful error message with leader address', async () => {
+            const leaderAddress = new oNodeAddress('o://my-custom-leader', []);
+            const node = new oNodeTool({
+                address: new oNodeAddress('o://child'),
+                leader: leaderAddress,
+                parent: null,
+            });
+            try {
+                await node.start();
+                expect.fail('Expected node.start() to throw an error');
+            }
+            catch (error) {
+                expect(error.message).to.include('o://my-custom-leader');
+                expect(error.message).to.include('Non-leader nodes require leader transports');
+                expect(error.message).to.include('Please provide transports');
+            }
+        });
+    });
+    describe('Validation timing', () => {
+        it('should fail before p2pNode creation (fast fail)', async () => {
+            const leaderAddress = new oNodeAddress('o://leader', []);
+            const node = new oNodeTool({
+                address: new oNodeAddress('o://child'),
+                leader: leaderAddress,
+                parent: null,
+            });
+            const startTime = Date.now();
+            try {
+                await node.start();
+                expect.fail('Expected node.start() to throw an error');
+            }
+            catch (error) {
+                const duration = Date.now() - startTime;
+                // Validation should happen very quickly (< 100ms)
+                // If it takes longer, it means we're doing expensive operations before validation
+                expect(duration).to.be.lessThan(100);
+                expect(error.message).to.include('Leader address is defined');
+                // Verify p2pNode was never created
+                expect(node.p2pNode).to.be.undefined;
+            }
+        });
+    });
+});

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@olane/o-node",
-  "version": "0.7.13-alpha.1",
+  "version": "0.7.13",
   "type": "module",
   "main": "dist/src/index.js",
   "types": "dist/src/index.d.ts",
@@ -40,7 +40,7 @@
   "devDependencies": {
     "@eslint/eslintrc": "^3.3.1",
     "@eslint/js": "^9.29.0",
-    "@olane/o-test": "0.7.13-alpha.1",
+    "@olane/o-test": "0.7.13",
     "@tsconfig/node20": "^20.1.6",
     "@types/jest": "^30.0.0",
     "@typescript-eslint/eslint-plugin": "^8.34.1",
@@ -59,12 +59,12 @@
     "typescript": "5.4.5"
   },
   "dependencies": {
-    "@olane/o-config": "0.7.13-alpha.1",
-    "@olane/o-core": "0.7.13-alpha.1",
-    "@olane/o-protocol": "0.7.13-alpha.1",
-    "@olane/o-tool": "0.7.13-alpha.1",
+    "@olane/o-config": "0.7.13",
+    "@olane/o-core": "0.7.13",
+    "@olane/o-protocol": "0.7.13",
+    "@olane/o-tool": "0.7.13",
     "debug": "^4.4.1",
     "dotenv": "^16.5.0"
   },
-  "gitHead": "7abba2239f85eb07a87401528b6df96e72449fe0"
+  "gitHead": "e86440c6502a9dff5569a99a8b0d22de8800c9b4"
 }