Commit 8e4eedc2 authored by Hugo Trentesaux's avatar Hugo Trentesaux Committed by Éloïs

[ref] ws2pv2: move bincode and prepare CBOR

parent c8c37841
# Bincode serialization format for ws2pv2
Bincode is an alternative serialization format supported by nodes having "RBC" in their api features. The tables given here correspond to the successive fields in the bincode version of the messages.
## Primitive types
u8 : Unsigned 8-bit integer.
u16 : Unsigned 16-bit integer.
u32 : Unsigned 32-bit integer.
u64 : Unsigned 64-bit integer.
i8 : Signed 8-bit integer.
i16 : Signed 16-bit integer.
i32 : Signed 32-bit integer.
i64 : Signed 64-bit integer.
bool : boolean stored on 8 bits (0x00 = false, 0x01 = true, any other value must generate an error).
0 : Corresponds to data that must be filled with bits to zero (for example padding).
## Useful non-primitive types
### (T, U)
(T, U) = Tuples of 2 elements. the 1st type T and the second type U.
A tuple is simply a concatenation of types written one after the other.
A tuple can be of any size (no maximum limit), but its size is necessarily fixed.
The different elements may be of different types, but the order cannot change.
### [T; n]
Array of n elements of type T.
If the size of the array is variable, its size (in number of cells) is stored on 8 bytes.
| data | size in bytes | data type |
| :---------: | ------------: | ------------: |
| cells_count | 8 | u64 |
| content* | ?*cells_count | (T1, T2, ...) |
All cells in the table are written one after the other without a separator, _like_ a tuple of `cells_count` elements of the same type.
**/*\ CAUTION: If the size of the array is static (=a literal constant) then the array is serialized without a size field. **
For example, the content of a public key ed25519 is a 32-byte array, (a [u8; 32] therefore), it is serialized directly without a size field.
### Opt(T)
Indicates that a field is optional. The optional fields are preceded by a 1-byte boolean that indicates whether or not the field is present.
| data | size in bytes | data type |
| :-----: | ------------: | --------: |
| is_some | 1 | u8 |
| content | ? | T |
If `is_some` is equal to `1`, field `content` is present.
If `is_some` is equal to `0`, field `content` is missing.
Any other value of `is_some` is prohibited and will invalidate the entire message.
### String
String formatted in utf8 and [NFKC normalized](https://fr.wikipedia.org/wiki/Normalisation_Unicode#NFKC).
**/!\ WARNING: All strings are systematically prefixed with their size, including for an empty string. The size is stored on 8 bytes as shown in the table below :**
| data | size in bytes | data type |
| :------: | ------------: | -------------: |
| str_size | 8 | u64 |
| content | str_size | [u8; str_size] |
content := String in binary utf8 with [NFKC normalization](https://fr.wikipedia.org/wiki/Normalisation_Unicode#NFKC).
If the string is empty, field `content` is missing and `str_size` is equal to zero.
### Blockstamp
| data | size in bytes | data type |
| :--------: | ------------: | --------: |
| block_id | 4 | u32 |
| block_hash | 32 | [u8; 32] |
### KeysAlgorithm
| algorithm | u32 |
| :-------: | ---: |
| Ed25519 | 0 |
| Schnorr | 1 |
### PubkeyBox
Contains the signatory's public key.
| data | size in bytes | data type |
| :-------: | ------------: | ------------: |
| algorithm | 4 | KeysAlgorithm |
| content | ? | ?* |
_*The type of field `content` depends on the algorithm. In the case of Ed25519, `content` is a 32-byte array containing the public key._
### SigBox
Contains the cryptographic signature of a document.
| data name | size in bytes | data type |
| :-------: | ------------: | ------------: |
| algorithm | 4 | KeysAlgorithm |
| content | ? | ?* |
_*The type of field `content` depends on the algorithm. In the case of Ed25519, `content` is a 64-byte array containing the signature._
## Endianness
All numbers (integers and floats) are encoded in little endian.
## Endpoint v2
| data name | size in bytes | data type |
| :--------------: | ------------: | ------------: |
| api_name | ? | String |
| api_version | 2 | u16 |
| network_features | 1 | u8 |
| api_features | 1 | u8 |
| endpoint_version | 4 | u32 |
| host | ? | Opt(String) |
| ip_v4 | 4 | Opt([u8; 4]) |
| ip_v6 | 16 | Opt([u16; 8]) |
| port | 2 | u16 |
| path | ? | Opt(String) |
## Peer card
Signed document declaring all the endpoints of a peer.
| data name | size in bytes | data type |
| :---------------: | ------------- | --------------------------- |
| version | 4 | u32 |
| currency_code | 2 | u16 |
| issuer_public_key | ? | PubkeyBox |
| node_id | 4 | u32 |
| blockstamp | 36 | Blockstamp |
| endpoints_count | 8 | u64 |
| endpoints_datas | ? | [Endpoint; endpoints_count] |
| signature | ? | SigBox |
## Messages
All messages are encapsulated in the following format :
| data name | size in bytes | data type |
| :------------: | ------------: | --------: |
| ws2p_version | 4 | u32 |
| currency_name | ? | String |
| issuer_node_id | 4 | u32 |
| issuer_pubkey | ? | PubkeyBox |
| message_type | 4 | u32 |
| payload | ? | ?* |
| signature | ? | SigBox |
### message_type
| `message_type` | code | Hashed | Signed |
|:--------------------:|--------|--------|--------|
| CONNECT | 0 | no | yes |
| ACK | 1 | no | yes |
| SECRET_FLAGS | 2 | no | yes |
| OK | 3 | no | yes |
| KO | 4 | no | yes |
| REQUEST | 5 | yes | no |
| REQUEST_RESPONSE | 6 | yes | no |
| PEERS | 7 | yes | no |
| HEADS_V2 | 8 | yes | no |
| HEADS_V3 | 9 | yes | no |
| BLOCKS | 10 | yes | no |
| PENDING_IDENTITIES | 11 | yes | no |
| PENDING_MEMBERSHIPS | 12 | yes | no |
| PENDING_CERTS | 13 | yes | no |
| PENDING_REVOCATIONS | 14 | yes | no |
| PENDING_TXS | 15 | yes | no |
### CONNECT message
| data name | size in bytes | data type |
| :-----------: | ------------- | --------------- |
| challenge | 32 | [u8; 32] |
| af_size | 1 | u8 |
| api_features | af_size | WS2PFeatures |
| flags_size | 1 | u8 |
| flags_queries | flags_size | WS2PFlags |
| peer_card | ? | Peer card |
| chunkstamp | 37 | Opt(Blockstamp) |
### ACK message
| data name | size in bytes | data type |
| :-------: | ------------- | --------- |
| challenge | 32 | [u8;32] |
### SECRET FLAGS message
| data name | size in bytes | data type |
| :----------: | ------------- | ---------------- |
| flags_size | 1 | u8 |
| flags | flags_size | WS2PSecretFlags |
| member_proof | ? | Opt(MembreProof) |
MembreProof type :
| data name | size in bytes | data type |
| :-------: | ------------- | --------- |
| pubkey | ? | PubkeyBox |
| sig | ? | SigBox |
#### WS2PSecretFlags type definition
| bit | flag |
| :-------: | --------------- |
| 0000_0001 | LOW_FLOW_DEMAND |
### OK message
| data name | size in bytes | data type |
| :-------: | ------------- | --------- |
| prefix/- | 2 | u16/0 |
#### SYNC_INFO message
| data name | size in bytes | data type |
| :---------------: | --------------------- | ----------------------------- |
| chunk_size | 32 | u32 |
| target_blockstamp | 36 | Blockstamp |
| milestones_count | 8 | u64 |
| milestones | 32 × milestones_count | [Hash; milestones_count ] |
| peer_cards_count | 8 | u64 |
| peer_cards | ? × peer_cards_count | [PeerCard; peer_cards_count ] |
### KO message
| data name | size in bytes | data type |
| :-------: | ------------- | --------- |
| reason | 2 | u16 |
\ No newline at end of file
This diff is collapsed.
Markdown is supported
0%
or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment