gitlab.com/SiaPrime/SiaPrime@v1.4.1/doc/RPC.md (about) 1 RPC 2 === 3 4 SiaPrime 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.