github.com/NebulousLabs/Sia@v1.3.7/doc/RPC.md (about)

     1  RPC
     2  ===
     3  
     4  Sia peers communicate with each other via Remote Procedure Calls. An RPC consists of a unique ID and a pair of functions, one on the calling end and one on the receiving end. After the ID is written/received, both peers hand the connection off to their respective functions. Typically, the calling end writes an object to the receiver and then reads a response.
     5  
     6  RPC IDs are always 8 bytes and contain a human-readable name for the RPC. If the name is shorter than 8 bytes, the remainder is padded with zeros. If the name is longer than 8 bytes, it is truncated.
     7  
     8  ### Call Listing
     9  
    10  Unless otherwise specified, these calls follow a request/response pattern and use the [encoding](./Encoding.md) package to serialize data.
    11  
    12  **All data received via RPC should be considered untrusted and potentially malicious.**
    13  
    14  #### ShareNodes
    15  
    16  ShareNodes requests peer addresses from a peer.
    17  The gateway calls this RPC regularly to update its list of potential peers.
    18  
    19  ID: `"ShareNod"`
    20  
    21  Request: None
    22  
    23  Response:
    24  
    25  ```go
    26  []modules.NetAddress
    27  ```
    28  
    29  Recommendations:
    30  
    31  + Requesting peers should limit the request to 3000 bytes.
    32  + Responding peers should send no more than 10 peers, and should not send peers that are unlikely to be reachable.
    33  
    34  #### SendBlocks
    35  
    36  SendBlocks requests blocks from a peer. The blocks are added to the requesting peer's blockchain, and optionally rebroadcast to other peers. Unlike most RPCs, the SendBlocks call is a loop of requests and responses that continues until the responding peer has no more blocks to send.
    37  
    38  ID: `"SendBloc"`
    39  
    40  Request:
    41  
    42  ```go
    43  // Exponentially-spaced IDs of most-recently-seen blocks,
    44  // ordered from most recent to least recent.
    45  // Less than 32 elements may be present, but the last element
    46  // (index 31) is always the ID of the genesis block.
    47  [32]types.BlockID
    48  ```
    49  
    50  Response:
    51  
    52  ```go
    53  struct {
    54     // sequential list of blocks, beginning with the first
    55     // block in the main chain not seen by the requesting peer.
    56     blocks []types.Block
    57     // true if the responding peer can send more blocks
    58     more bool
    59  }
    60  ```
    61  
    62  Recommendations:
    63  
    64  + Requesting peers should limit the request to 20MB.
    65  + Responding peers should identify the most recent BlockID that is in their blockchain, and send up to 10 blocks following that block.
    66  + Responding peers should set `more = true` if they have not sent the most recent block in their chain.
    67  
    68  #### RelayHeader
    69  
    70  RelayHeader sends a block header ID to a peer, with the expectation that the peer will relay the ID to its own peers.
    71  
    72  ID: `"RelayHea"`
    73  
    74  Request:
    75  
    76  ```go
    77  types.BlockHeader
    78  ```
    79  
    80  Response: None
    81  
    82  Recommendation:
    83  
    84  + Requesting (sending) peers should call this RPC on all of their peers as soon as they mine or receive a block via `SendBlocks` or `SendBlk`.
    85  + Responding (receiving) peers should use the `SendBlk` RPC to download the actual block content. If the block is an orphan, `SendBlocks` should be used to discover the block's parent(s).
    86  + Responding peers should not rebroadcast the received ID until they have downloaded and verified the actual block.
    87  
    88  #### SendBlk
    89  
    90  SendBlk requests a block's contents from a peer, given the block's ID.
    91  
    92  ID: `"SendBlk\0"`
    93  
    94  Request:
    95  
    96  ```go
    97  types.BlockID
    98  ```
    99  
   100  Response:
   101  
   102  ```go
   103  types.Block
   104  ```
   105  
   106  + Requesting peers should limit the received block to 2 MB (the maximum block size).
   107  + Requesting peers should broadcast the block's ID using `RelayHeader` once the received block has been verified.
   108  + Responding peers may simply close the connection if the block ID does not match a known block.
   109  
   110  #### RelayTransactionSet
   111  
   112  RelayTransactionSet sends a transaction set to a peer.
   113  
   114  ID: `"RelayTra"`
   115  
   116  Request:
   117  
   118  ```go
   119  []types.Transaction
   120  ```
   121  
   122  Response: None
   123  
   124  Recommendations:
   125  
   126  + Requesting peers should limit the request to 2 MB (the maximum block size).
   127  + Responding peers should broadcast the received transaction set once it has been verified.