The Transport Discovery is a service that exposes a RESTful interface and interacts with a database on the back-end. It registers the network topology of the network and allows the route finder to create a graph for finding optimal paths through the network.

The database stores Transport Entries that can be queried using their Transport ID or via a given Transport Edge.

The process of submitting a Transport Entry is called Registration and a Transport cannot be deregistered. However, nodes that are an Edge of a Transport, can update their Transport Status, and specify whether the Transport is up or down.

Any state-altering RESTful call to the Transport Discovery is authenticated using signatures, and replay attacks are avoided by expecting an incrementing security nonce (all communication should be encrypted with HTTPS anyhow).

This is a summary of the procedures that the Transport Discovery handles.

Registering a Transport:

Technically, Transports are created by the Skywire Nodes themselves via an internal Transport Factory implementation. The Transport Discovery is only responsible for registering Transports in the form of a Transport Entry.

When two Skywire Nodes establish a Transport connection between them, it is at first, unregistered in the Transport Discovery. The node that initiated the creation of the Transport (or the node that called the (transport.Transport).Dial method), is the node that is responsible for initiating the Transport Settlement Handshake.

If two nodes; A and B establish a Transport between them (where A is the Transport Initiator), A is then also responsible for sending the first handshake packet for the Transport Settlement Handshake. The procedure is as follows:

1. A sends B a proposed transport.Entry and also A's signature of the Entry (in the form of transport.SignedEntry).

2. B checks the transport.SignedEntry sent from A;

   1. The Entry.ID field should be unique (check via Transport Discovery).
   2. The Entry.Edges field should be ordered correctly and contain public keys of A and B.
   3. The Entry.Type field should have the expected Transport Type.
   4. The Signatures field should contain A's valid signature in the correct location (in the same index as A's public key in Entry.Edges).
   5. The Registered field should be empty.

3. B then adds it's only signature to the transport.SignedEntry and registers it to the Transport Discovery. Both public and private Transports are registered in the Transport Discovery (however only public Transports are publicly available).

4. B then informs A on the success/failure of the registration, or just that the transport.SignedEntry is accepted by itself (depending on whether the Transport is to be public or not).

Submitting Transport Statuses:

If a given Transport is public, the associated Transport Edges is responsible for submitting their individual Transport Statuses to the Transport Discovery whenever the follow events occur;

• Directly after a Transport is first successfully registered in the Transport Discovery.
• Whenever the Transport comes online/offline (connected/disconnected).

Obtaining Transports:

There are two ways to obtain transports; either via the assigned Transport ID, or via one of the Transport Edges. There is no restriction as who can access this information and results can be sorted by a given meta.

The following is a summary of all the Transport Discovery endpoints.

• GET /security/nonces/edge:<public-key>
• GET /transports/id:<transport-id>
• GET /transports/edge:<public-key>
• POST /transports
• POST /statuses

Further documentation of the endpoints is available here.