package network

Get desktop application:
View/edit binary Protocol Buffers messages

Used in: AccountKeyPayload

• optional PublicKey peer_id = 5

  PeerId of the node owning the account_key. Used to route the message over TIER1. TODO(gprusak): it should be possible to add support for routing messages to an account_id directly (for TIER1), instead of routing to a specific peer_id. Then this field won't be necessary. Unless we use it instead of AnnounceAccount.

  required.

• optional PublicKey account_key = 6

  required.

• repeated PeerAddr proxies = 2

  List of nodes which - are trusted by the validator and - are connected to the validator directly - are willing to proxy traffic to the validator. It may include the validator node itself, if it has a public IP. If empty, the validator explicitly declares that it has no public IP and the TIER2 routing should be used instead (discouraged, might be disallowed in the future).

• uint64 version = 7

  Version of the AccountData. A node can override a previous version, by broadcasting a never version.

• optional google.protobuf.Timestamp timestamp = 4

  Time of creation of this AccountData. TODO(gprusak): consider expiring the AccountData based on this field.

A payload that can be signed with account keys. Since account keys are used to sign things in independent contexts, we need this common enum to prevent message replay attacks, like this one: - messages M1 and M2 of different types happen to have the same serialized representation. - an attacker observes M1 signed by A in some context - the attacker then sends M2 with A's signature of M1 (which also matches M2, since their serialized representations match) to B, effectively impersonating A. NOTE: that proto serialization is non-unique, so the message passed around with the signature should be in serialized form. TODO: move to a separate file, probably in a separate package.

• oneof payload_type

  • AccountData account_data = 2

  • OwnedAccount owned_account = 3

Used in: Handshake, SyncAccountsData

• bytes payload = 1

  protobuf-serialized AccountKeyPayload, required. It is passed in serialized form, because the protobuf encoding is non-deterministic. In particular encode(decode(payload)) might not match the signature.

• optional Signature signature = 2

  Signature of the payload, required.

  TODO: this is a good place to add optional fields: account_id, account_public_key, in case the signer of the message is not implied by the payload, or the context. Add them if needed.

Denotes an available route to `destination` of length `distance`

Used in: DistanceVector

• optional PublicKey destination = 1

• uint32 distance = 2

Wrapper of the borsh-encoded AnnounceAccount. https://github.com/near/nearcore/blob/1a4edefd0116f7d1e222bc96569367a02fe64199/core/primitives/src/network.rs#L86

Used in: RoutingTableUpdate

• bytes borsh = 1

Wrapper of the borsh-encoded NEAR chain block. https://github.com/near/nearcore/blob/1a4edefd0116f7d1e222bc96569367a02fe64199/core/primitives/src/block.rs#L77

Used in: BlockResponse

• bytes borsh = 1

Wrapper of the borsh-encoded BlockHeader. https://github.com/near/nearcore/blob/1a4edefd0116f7d1e222bc96569367a02fe64199/core/primitives/src/block_header.rs#L325

Used in: BlockHeadersResponse

• bytes borsh = 1

Request to send back headers of the NEAR chain blocks. Receiver finds in block_hashes the first hash of a block it knows about and rends back BlockHeadersResponse with block headers following that block. At most 512 block headers are returned: https://github.com/near/nearcore/blob/1a4edefd0116f7d1e222bc96569367a02fe64199/chain/client/src/sync.rs#L38 It might happen that the receiver doesn't know some of the hashes in the list in the following cases: - sender's view of the chain forked from the receiver's view of the chain - sender's view of the chain is ahead of receiver's view of the chain.

Used in: PeerMessage

• repeated CryptoHash block_hashes = 1

A collection of headers of the NEAR chain blocks.

Used in: PeerMessage

• repeated BlockHeader block_headers = 1

Request to send back a NEAR chain block with a given hash.

Used in: PeerMessage

• optional CryptoHash block_hash = 1

NEAR chain Block. It might be send both as a response to BlockRequest, or unsolicited in case a new Block is being broadcasted.

Used in: PeerMessage

• optional Block block = 1

Wrapper of borsh-encoded Challenge https://github.com/near/nearcore/blob/1a4edefd0116f7d1e222bc96569367a02fe64199/core/primitives/src/challenge.rs#L89

Used in: PeerMessage

• bytes borsh = 1

sha256 hash of the borsh-encoded NEAR Block.

Used in: BlockHeadersRequest, BlockRequest, GenesisId, OptimisticBlock, SnapshotHostInfo, StateRequestHeader, StateRequestPart

• bytes hash = 1

  sha256 hash (32 bytes)

Disconnect is send by a node before closing a TCP connection. There is no guarantee that it will be sent in all circumstances.

Used in: PeerMessage

• bool remove_from_connection_store = 1

/ Message shared by a peer listing the distances it has to other peers / in the NEAR network. / / It includes a collection of signed edges forming a spanning tree / which verifiably achieves the advertised routing distances. / / The distances in the tree may be the same or better than the advertised / distances; see routing::graph_v2::tests::inconsistent_peers.

Used in: PeerMessage

• optional PublicKey root = 1

  PeerId of the node sending the message.

• repeated AdvertisedPeerDistance distances = 2

  List of distances the root has to other peers in the network.

• repeated Edge edges = 3

  Spanning tree of signed edges achieving the claimed distances (or better).

Wrapper of borsh-encoded Edge. https://cs.github.com/near/nearcore/blob/1a4edefd0116f7d1e222bc96569367a02fe64199/chain/network-primitives/src/network_protocol/edge.rs#L32

Used in: DistanceVector, LastEdge, RoutingTableUpdate, UpdateNonceResponse

• bytes borsh = 1

Used in: PeerMessage

(message has no fields)

Used in: PeerMessage

• bytes compressed_proof = 1

Unique identifier of the NEAR chain.

Used in: HandshakeFailure, PeerChainInfo

• string chain_id = 1

  Name of the chain (for example "mainnet").

• optional CryptoHash hash = 2

  Hash of the genesis block(?) of the NEAR chain.

Handshake is the first message exchanged after establishing a TCP connection. If A opened a connection B, then 1. A sends Handshake to B. 2a. If B accepts the handshake, it sends Handshake to A and connection is established. 2b. If B rejects the handshake, it sends HandshakeFailure to A. A may retry the Handshake with a different payload.

Used in: PeerMessage

• uint32 protocol_version = 1

  The protocol_version that the sender wants to use for communication. Currently NEAR protocol and NEAR network protocol are versioned together (it may change in the future), however peers may communicate with the newer version of the NEAR network protocol, than the NEAR protocol version approved by the quorum of the validators. If B doesn't support protocol_version, it sends back HandshakeFailure with reason ProtocolVersionMismatch.

• uint32 oldest_supported_version = 2

  Oldest version of the NEAR network protocol that the peer supports.

• optional PublicKey sender_peer_id = 3

  PeerId of the sender.

• optional PublicKey target_peer_id = 4

  PeerId of the receiver that the sender expects. In case of mismatch, receiver sends back HandshakeFailure with reason InvalidTarget.

• uint32 sender_listen_port = 5

  TCP port on which sender is listening for inbound connections.

• optional PeerChainInfo sender_chain_info = 6

  Basic info about the NEAR chain that the sender belongs to. Sender expects receiver to belong to the same chain. In case of mismatch, receiver sends back HandshakeFailure with reason GenesisMismatch.

• optional PartialEdgeInfo partial_edge_info = 7

  Edge (sender,receiver) signed by sender, which once signed by receiver may be broadcasted to the network to prove that the connection has been established. In case receiver accepts the Handshake, it sends back back a Handshake containing his signature in this field. WARNING: this field contains a signature of (sender_peer_id,target_peer_id,nonce) tuple, which currently the only thing that we have as a substitute for a real authentication. TODO(gprusak): for TIER1 authentication is way more important than for TIER2, so this thing should be replaced with sth better.

• optional AccountKeySignedPayload owned_account = 8

  See description of OwnedAccount.

  optional

Response to Handshake, in case the Handshake was rejected.

Used in: PeerMessage

• HandshakeFailure.Reason reason = 1

  Reason for rejecting the Handshake.

• optional PeerInfo peer_info = 2

  Data about the peer.

• optional GenesisId genesis_id = 3

  GenesisId of the NEAR chain that the peer belongs to.

• uint32 version = 4

  Newest NEAR network version supported by the peer.

• uint32 oldest_supported_version = 5

  Oldest NEAR network version supported by the peer.

Used in: HandshakeFailure

• UNKNOWN = 0

• ProtocolVersionMismatch = 1

  Peer doesn't support protocol_version indicated in the handshake.

• GenesisMismatch = 2

  Peer doesn't belong to the chain indicated in the handshake.

• InvalidTarget = 3

  target_id doesn't match the id of the peer.

TODO: document it.

Used in: PeerMessage

• optional Edge edge = 1

Used in: PeerMessage

• bytes inner = 1

• optional Signature signature = 2

• optional CryptoHash hash = 3

Proof that a given peer owns the account key. Included in every handshake sent by a validator node. Note: sign AccountKeyPayload, rather than OwnedAccount directly.

Used in: AccountKeyPayload

• optional PublicKey account_key = 1

  required

• optional PublicKey peer_id = 2

  PeerId of the node owning the account_key.

  required

• optional google.protobuf.Timestamp timestamp = 3

  Timestamp indicates the date of signing - we do not assume the nodes' clocks to be synchronized, but for security if the timestamp deviation is too large, the handshake will be rejected. TODO(gprusak): an alternative would be a 3-way handshake with a random challenge to sign, or even better: just use some standard asymmetric encryption.

  required

Wrapper of the borsh-encoded PartialEdgeInfo. https://github.com/near/nearcore/blob/1a4edefd0116f7d1e222bc96569367a02fe64199/chain/network-primitives/src/network_protocol/edge.rs#L11

Used in: Handshake, UpdateNonceRequest

• bytes borsh = 1

Used in: AccountData

• optional SocketAddr addr = 1

  required

• optional PublicKey peer_id = 2

  required

Basic information about the chain view maintained by a peer.

Used in: Handshake

• optional GenesisId genesis_id = 1

• uint64 height = 2

  Height of the highest NEAR chain block known to a peer.

• repeated uint64 tracked_shards = 3

  Shards of the NEAR chain tracked by the peer.

• bool archival = 4

  Whether the peer is an archival node.

Wrapper of borsh-encoded PeerInfo. https://github.com/near/nearcore/blob/1a4edefd0116f7d1e222bc96569367a02fe64199/chain/network-primitives/src/network_protocol/mod.rs#L30

Used in: HandshakeFailure, PeersResponse

• bytes borsh = 1

PeerMessage is a wrapper of all message types exchanged between NEAR nodes. The wire format of a single message M consists of len(M)+4 bytes: <len(M)> : 4 bytes : little endian uint32 <M> : N bytes : binary encoded protobuf PeerMessage M

• optional TraceContext trace_context = 26

  Inter-process tracing information.

• oneof message_type

  • Handshake tier1_handshake = 27

    Handshakes for different network tiers explicitly use different PeerMessage variants. This way we avoid accidental connections, such that one end thinks it is a TIER2 connection and the other thinks it is a TIER1 connection. Currently the same PeerActor handles all types of connections, hence the contents are identical for all types of connections. If we ever decide to separate the handshake implementations, we can copy the Handshake message type definition and make it evolve differently for different tiers.

  • Handshake tier2_handshake = 4

  • Handshake tier3_handshake = 33

  • HandshakeFailure handshake_failure = 5

  • LastEdge last_edge = 6

  • RoutingTableUpdate sync_routing_table = 7

  • DistanceVector distance_vector = 28

  • UpdateNonceRequest update_nonce_request = 8

  • UpdateNonceResponse update_nonce_response = 9

  • SyncAccountsData sync_accounts_data = 25

  • PeersRequest peers_request = 10

  • PeersResponse peers_response = 11

  • BlockHeadersRequest block_headers_request = 12

  • BlockHeadersResponse block_headers_response = 13

  • BlockRequest block_request = 14

  • BlockResponse block_response = 15

  • SignedTransaction transaction = 16

  • RoutedMessage routed = 17

  • Disconnect disconnect = 18

  • Challenge challenge = 19

  • StateRequestHeader state_request_header = 29

  • StateRequestPart state_request_part = 30

  • StateResponse state_response = 31

  • SyncSnapshotHosts sync_snapshot_hosts = 32

  • EpochSyncRequest epoch_sync_request = 34

  • EpochSyncResponse epoch_sync_response = 35

  • OptimisticBlock optimistic_block = 36

Request to send a list of known healthy peers (i.e. considered honest and available by the receiver). max_peers limits the number of peers to send back. max_direct_peers limits the number of direct peers to send back. See PeersResponse below for the response.

Used in: PeerMessage

• optional uint32 max_peers = 1

• optional uint32 max_direct_peers = 2

Response to PeersRequest

Used in: PeerMessage

• repeated PeerInfo peers = 1

  Peers drawn from the PeerStore of the responding node, which includes peers learned transitively from other peers

• repeated PeerInfo direct_peers = 2

  Peers directly connected to the responding node

Wrapper of borsh-encoded PublicKey. https://github.com/near/nearcore/blob/1a4edefd0116f7d1e222bc96569367a02fe64199/core/crypto/src/signature.rs#L201

Used in: AccountData, AdvertisedPeerDistance, DistanceVector, Handshake, OwnedAccount, PeerAddr, SnapshotHostInfo

• bytes borsh = 1

Wrapper of borsh-encoded RoutedMessage https://github.com/near/nearcore/blob/1a4edefd0116f7d1e222bc96569367a02fe64199/chain/network-primitives/src/network_protocol/mod.rs#L295

Used in: PeerMessage

• bytes borsh = 1

• optional google.protobuf.Timestamp created_at = 2

  Timestamp of creating the Routed message by its original author.

• uint32 num_hops = 4

  Number of peers this routed message traveled through. Doesn't include the peer that created the message.

Wrapper of borsh-encoded RoutingSyncV2 https://github.com/near/nearcore/blob/1a4edefd0116f7d1e222bc96569367a02fe64199/chain/network/src/network_protocol.rs#L225

• bytes borsh = 1

Message sent whenever the sender learns about new connections between the peers in the network (I think). It provides a view of the whole NEAR network to each peer. Edges constitute a graph between PeerIds, signed by both of the peers. This is one of the first messages sent after Handshake. First RoutingTableUpdate contains the whole graph known to peer. Afterwards only the graph delta (changed edges) are included. Accounts provides a mapping AccountId -> PeerId, providing knowledge about which NEAR peer controls which NEAR account.

Used in: PeerMessage

• repeated Edge edges = 1

• repeated AnnounceAccount accounts = 2

  list of known NEAR validator accounts

Wrapper of borsh-encoded Signature. TODO: link to the rust Signature type.

Used in: AccountKeySignedPayload, OptimisticBlock, SnapshotHostInfo

• bytes borsh = 1

Wrapper of borsh-encoded SignedTransaction https://github.com/near/nearcore/blob/1a4edefd0116f7d1e222bc96569367a02fe64199/core/primitives/src/transaction.rs#L218

Used in: PeerMessage

• bytes borsh = 1

Used in: SyncSnapshotHosts

• optional PublicKey peer_id = 1

• optional CryptoHash sync_hash = 2

• uint64 epoch_height = 3

• repeated uint64 shards = 4

• optional Signature signature = 5

Used in: PeerAddr

• bytes ip = 1

  IPv4 (4 bytes) or IPv6 (16 bytes) in network byte order.

• uint32 port = 2

  TCP port (actually uint16, however uint32 is smallest supported protobuf type).

Used in: PeerMessage

• uint64 shard_id = 1

• optional CryptoHash sync_hash = 2

Used in: PeerMessage

• uint64 shard_id = 1

• optional CryptoHash sync_hash = 2

• uint64 part_id = 3

Used in: PeerMessage

• optional StateResponseInfo state_response_info = 1

Wrapper of the borsh-encoded StateResponseInfo.

Used in: StateResponse

• bytes borsh = 1

SyncAccountData message can represent: - incremental sync (incremental = true, requesting_full_sync = false) - full sync request (incremental = false, requesting_full_sync = true) - full sync response (incremental = false, requesting_full_sync = false)

Used in: PeerMessage

• repeated AccountKeySignedPayload accounts_data = 1

  Data about the (important) accounts, which should be broadcasted to the whole network. Contains AccountKeyPayload.account_data.

• bool incremental = 2

  Indicates whether this message is an incremental sync (true), or a full sync (false). Useful for tracking time since the last full sync.

• bool requesting_full_sync = 3

  Indicates that sender requests a full sync message in return. Useful for soliciting a full sync periodically.

Used in: PeerMessage

• repeated SnapshotHostInfo hosts = 1

  Information about peers in the network hosting state snapshots

Inter-process tracing information.

Used in: PeerMessage

• bytes trace_id = 1

  16 bytes representing TraceId: https://docs.rs/opentelemetry/latest/opentelemetry/trace/struct.TraceId.html

• bytes span_id = 2

  8 bytes representing SpanId: https://docs.rs/opentelemetry/latest/opentelemetry/trace/struct.SpanId.html

• TraceContext.SamplingPriority sampling_priority = 3

Used in: TraceContext

• UNKNOWN = 0

• AutoReject = 1

• UserReject = 2

• AutoKeep = 3

• UserKeep = 4

TODO: document it.

Used in: PeerMessage

• optional PartialEdgeInfo partial_edge_info = 1

Deprecated. Use SyncRoutingTable instead.

Used in: PeerMessage

• optional Edge edge = 1