:::danger
This document is out of date. Please see https://github.com/zdave-parity/jam-np/blob/main/simple.md
:::

# JAM Simple Networking Protocol (JAMNP-S)

## Required connectivity

### QUIC

All connections are based on QUIC protocol.

### Endpoints

All validators in both the current epoch and the following should ensure they are connected to all other such validators.

The validator's IP-layer endpoints are given as IPv6/port combinations, to be found in the first 18 bytes of validator metadata, with the first 16 bytes being the IPv6 address and the latter 2 being a little endian representation of the port.

**Strategy**: For all such pairwise connections, we assign a Preferred Initiator for the connection based on the Ed25519 public key, quantity $k_e, k \in \mathbb{K}$. After a reasonable timeout (e.g. 5 seconds), the other validator may choose to initiate a connection. Given two peer IDs $(a, b) \in \mathbb{K}^2$, the Preferred Initiator $P(a, b) \in \{a, b\}$ is given as:

$$
P(a, b) \equiv \begin{cases}
a &\text{when } \text{bits}(a)_{255} \oplus \text{bits}(b)_{255} \oplus (a < b)\\
b &\text{otherwise}
\end{cases}
$$

Validators should accept connections from other nodes too, with a reasonable number of slots (e.g. 20) reserved for Work Package Builders. They may reasonably be required to prove their credentials through submission of a valid Work Package in order to retain their connection when others purport to be able to do the same.

### Encryption & Handshake

TLS 1.3 is used for connection encryption and peer authentication.

During the TLS handshake, both the client (the peer that initiated the connection) and the server (the peer that accepted the connection) must present X.509 certificates. A peer's certificate must:

- Use Ed25519 as the signature algorithm.
- Use the peer's Ed25519 key. If the peer is a validator, this key should have been published on chain.
- Have a single alternative name, which must be a 53-character DNS name consisting of "e" followed by the Ed25519 public key, base-32 encoded using the alphabet "abcdefghijklmnopqrstuvwxyz234567".

The certificates _should_ be self-signed, however this is not required and need not be verified.

The connection should be closed if the remote peer does not send a certificate, or the certificate does not meet the above requirements. Note that in the case where a connection is being accepted, the remote peer's Ed25519 key is not known in advance, but consistency between the certificate's key and alternative name should still be checked.

Encryption and authentication occur as usual in TLS:

- Diffie-Hellman key exchange is used to produce an ephemeral encryption key.
- Both peers sign the handshake transcript hash.

## JAMSNP Handshake

In order to identify the protocol name, version and chain.

### Spec

We utilize the QUIC/TLS "ALPN". The protocol identifier should be `jamnp-s/V/H`. Here `V` is the protocol version, `0`. Here `H` is the first 8 nibbles of the genesis header of the chain.

## Protocols and Streams

All communication happens on one of many QUIC streams. Many such streams may be in existence at once. Streams are associated with a Stream Kind, a identifier for the protocol which will be in force over the substream.

All Stream Kinds may be characterised into one of two patterns:

1. Unique Persistent streams: Only one stream may be open for each Stream Kind. They will tend to be opened after connection and stay alive for the duration of the connection. Such streams may have multiple types of messages which are sent over the stream. An example would be the synchronisation stream.
2. Common Ephemeral streams: Zero or many streams be open for each Stream Kind. They will tend to be opened to make a specific query or submit a particular datum and closed immediately after completion. Such streams tend to have a single message format and expect a single response back. An example would be a Work Package submission stream.

All messages are prefixed by the (following) message size, as a SCALE-encoded 32-bit unsigned integer. In all cases, replies should be made in the order of their corresponding messages.

### CE: Ticket submission
The sharing of a Safrole ticket for inclusion in a block.

Validator -> Validator

--> <Ticket>
<-- { 0 (Success), 1 (Bad) }

### CE: Work Report publication

Submission of a fully guaranteed Work Report ready for inclusion in a block.

Guarantor(*) -> Validator

--> <Guaranteed Work Report>
<-- { 0 (Success), 1 (Bad) }

### CE: Assurance publication

Submission of an availability assurance ready for inclusion in a block.

Assurer -> Validator

--> <Assurance>
<-- { 0 (Success), 1 (Bad) }

### CE: Judgement publication
Announcement of a judgement, ready for inclusion in a block and as a signal for potential further auditing.

Auditor -> Validator

--> <Judgement>
<-- { 0 (Success), 1 (Bad) }

### CE: Preimage publication
Announcement of a requested preimage, ready for inclusion in a block.

Node -> Validator

--> <Preimage>
<-- { 0 (Success), 1 (Bad) }

### CE: Block publication
Announcement of a new block.

Author -> Node OR Validator

--> <Block>
<-- { 0 (Success), 1 (Bad) }

### CE: Work Package Submission and Sharing

Happens either from a WP Builder to a Guarantor assigned to the relevant core, or between guarantors on the same core assignment after a guarantor has determined that a WP is valid and can generate a WR which is submittable on-chain. Includes its extrinsic data segments, any pre-existing signatures (which should always be greater than one if it is coming from a Guarantor), the imported data and justification for correctness. The latter is not needed in the case that the sender is a WP Builder.

Guarantor(c) -> Guarantor(c) OR Builder(p | p_c == c)

--> <Work Package> ++ Vec<Signature>
<-- { 0 (Success), 1 (Bad) }
--> Vec<Extrinsic> ++ Vec<JustifiedImport>
<-- { 0 (Success), 1 (Bad) }

### CE: Audit-announcement
Announcement of requirement to audit.

Auditor -> Validator

TBD

### CE: ImportDA query & response
Request for one or more 12-byte segment chunks from the Import DA Lake.

Assurer <-> Guarantor(*)

TBD

### CE: AuditDA query & response
Request for one or more chunks from the Audit DA Lake.

Assurer <-> Auditor

TBD

### CE: Public ImportDA reconstruction
Request for a complete reconstruction of a exported segment.

Assurer <-> Node OR Guarantor

TBD

### UP: Chain sync
Will probably be several different messages/responses.

@Arkadiy wdyt?

TBD

## TODO

- Chunk distribution along with correctness proof
- JAMNP-F:
- EC block publication
- Warp sync
- G2G handoff
- Mixnet and ticket submission
- Light-client protocol
- WebRTC etc