Discovery

Used to discover nodes and their supported protocols in the Marlin network.

Operation

Beacons

Beacons act as entry points into the discovery process. They contain a registry of nodes which can be queried by interested clients.

Node registration

Nodes can register with a beacon by sending a HEARTBEAT message. To remain in the beacon's registry, nodes must stay active and send a HEARTBEAT message at least once every 60s. It is recommended to send a message every 10-20s to accommodate random losses.

NodeBeaconNodeTimerNodeBeaconBeaconTimerSetupNodeTimerstartBeaconTimerstartHeartbeatloop[every 20s]timer eventHEARTBEATalt[new node][existing node]Add node to registryUpdate timestampCleanuploop[every 60s]timer eventRemove stale nodesfrom registry

Node discovery

Clients initiate discovery by sending a DISCPEER message to the beacon. The beacon responds with a LISTPEER message containing a list of nodes registered with it.

ClientNodeClientNodeDISCPEERLISTPEER

Protocol discovery

Clients can discover the supported protocols on a node by sending a DISCPROTO message. The node will respond with a LISTPROTO message containing a list of supported protocols.

ClientBeaconClientBeaconDISCPROTOLISTPROTO

Wire format

Every message is prefixed with a version byte and a message type byte. The message type identifies the message and the version field enables protocol upgrades in the future.

 0               1               2               3
 0 1 2 3 4 5 6 7 0 1 2 3 4 5 6 7 0 1 2 3 4 5 6 7 0 1 2 3 4 5 6 7
+++++++++++++++++++++++++++++++++
|    Version    |      Type     |
-----------------------------------------------------------------
|                            Payload                          ...
+++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++

DISCPROTO (0x00)

No payload.

 0               1               2               3
 0 1 2 3 4 5 6 7 0 1 2 3 4 5 6 7 0 1 2 3 4 5 6 7 0 1 2 3 4 5 6 7
+++++++++++++++++++++++++++++++++
|      0x00     |      0x00     |
+++++++++++++++++++++++++++++++++

LISTPROTO (0x01)

Payload contains 1 byte specifying number of protocol entries to follow. Each protocol entry has a 4 byte protocol number, 2 byte version and the port number on which the protocol is available.

 0               1               2               3
 0 1 2 3 4 5 6 7 0 1 2 3 4 5 6 7 0 1 2 3 4 5 6 7 0 1 2 3 4 5 6 7
+++++++++++++++++++++++++++++++++++++++++++++++++
|      0x00     |      0x01     |Num entries (N)|
-----------------------------------------------------------------
|                      Protocol Number (1)                      |
-----------------------------------------------------------------
|          Version (1)          |            Port (1)           |
-----------------------------------------------------------------
|                      Protocol Number (2)                      |
-----------------------------------------------------------------
|          Version (2)          |            Port (2)           |
-----------------------------------------------------------------
|                              ...                              |
-----------------------------------------------------------------
|                      Protocol Number (N)                      |
-----------------------------------------------------------------
|          Version (N)          |            Port (N)           |
+++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++

DISCPEER (0x02)

No payload.

 0               1               2               3
 0 1 2 3 4 5 6 7 0 1 2 3 4 5 6 7 0 1 2 3 4 5 6 7 0 1 2 3 4 5 6 7
+++++++++++++++++++++++++++++++++
|      0x00     |      0x02     |
+++++++++++++++++++++++++++++++++

LISTPEER (0x03)

Payload contains a list of address entries. Each address entry has a 2 byte family(currently set to AF_INET), a 4 byte IPv4 address and the port number on which the node is running discovery.

 0               1               2               3
 0 1 2 3 4 5 6 7 0 1 2 3 4 5 6 7 0 1 2 3 4 5 6 7 0 1 2 3 4 5 6 7
+++++++++++++++++++++++++++++++++
|      0x00     |      0x03     |
---------------------------------
|            AF_INET            |
-----------------------------------------------------------------
|                        IPv4 Address (1)                       |
-----------------------------------------------------------------
|            Port (1)           |
---------------------------------
|            AF_INET            |
-----------------------------------------------------------------
|                        IPv4 Address (2)                       |
-----------------------------------------------------------------
|            Port (2)           |
-----------------------------------------------------------------
|                              ...                              |
-----------------------------------------------------------------
|            AF_INET            |
-----------------------------------------------------------------
|                        IPv4 Address (N)                       |
-----------------------------------------------------------------
|            Port (N)           |
+++++++++++++++++++++++++++++++++

HEARTBEAT (0x04)

No payload.

 0               1               2               3
 0 1 2 3 4 5 6 7 0 1 2 3 4 5 6 7 0 1 2 3 4 5 6 7 0 1 2 3 4 5 6 7
+++++++++++++++++++++++++++++++++
|      0x00     |      0x04     |
+++++++++++++++++++++++++++++++++