github.com/nspcc-dev/neo-go@v0.105.2-0.20240517133400-6be757af3eba/docs/rpc.md (about) 1 # RPC 2 3 ## Client 4 5 Client is provided as a Go package, so please refer to the 6 [relevant godocs page](https://godoc.org/github.com/nspcc-dev/neo-go/pkg/rpcclient). 7 8 ## Server 9 10 The server is written to support as much of the [JSON-RPC 2.0 Spec](http://www.jsonrpc.org/specification) as possible. The server is run as part of the node currently. 11 12 ### Example call 13 14 An example would be viewing the version of the node: 15 16 ```bash 17 $ curl -X POST -d '{"jsonrpc": "2.0", "method": "getversion", "params": [], "id": 1}' http://localhost:20332 18 ``` 19 20 which would yield the response: 21 22 ```json 23 { 24 "result" : { 25 "useragent" : "/NEO-GO:0.97.2/", 26 "tcpport" : 10333, 27 "network" : 860833102, 28 "nonce" : 105745208 29 }, 30 "jsonrpc" : "2.0", 31 "id" : 1 32 } 33 ``` 34 ### Supported methods 35 36 | Method | 37 | ------- | 38 | `calculatenetworkfee` | 39 | `findstates` | 40 | `findstorage` | 41 | `getapplicationlog` | 42 | `getbestblockhash` | 43 | `getblock` | 44 | `getblockcount` | 45 | `getblockhash` | 46 | `getblockheader` | 47 | `getblockheadercount` | 48 | `getcandidates` | 49 | `getcommittee` | 50 | `getconnectioncount` | 51 | `getcontractstate` | 52 | `getnativecontracts` | 53 | `getnep11balances` | 54 | `getnep11properties` | 55 | `getnep11transfers` | 56 | `getnep17balances` | 57 | `getnep17transfers` | 58 | `getnextblockvalidators` | 59 | `getpeers` | 60 | `getproof` | 61 | `getrawmempool` | 62 | `getrawtransaction` | 63 | `getstate` | 64 | `getstateheight` | 65 | `getstateroot` | 66 | `getstorage` | 67 | `gettransactionheight` | 68 | `getunclaimedgas` | 69 | `getversion` | 70 | `invokecontractverify` | 71 | `invokefunction` | 72 | `invokescript` | 73 | `sendrawtransaction` | 74 | `submitblock` | 75 | `submitoracleresponse` | 76 | `terminatesession` | 77 | `traverseiterator` | 78 | `validateaddress` | 79 | `verifyproof` | 80 81 #### Implementation notices 82 83 ##### JSON representation of enumerations 84 85 C# implementation contains a number of enumerations and while it outputs them 86 into JSON as comma-separated strings (or just strings if only one value is 87 allowed for this type) it accepts pure numbers for input (see #2563 for 88 example). NeoGo currently doesn't support this behavior. This affects the 89 following data types: 90 * transaction attribute type 91 * oracle response code 92 * transaction witness scope 93 * rule witness action 94 * condition rule witness type 95 * function call flag 96 * function call parameter type 97 * execution trigger type 98 * stack item type 99 100 Any call that takes any of these types for input in JSON format is affected. 101 102 ##### Response error codes 103 104 NeoGo currently uses a different set of error codes in comparison to C# implementation, see 105 [proposal](https://github.com/neo-project/proposals/pull/156). 106 NeoGo retains certain deprecated error codes, which will be removed once 107 all nodes adopt the new error standard. 108 109 ##### `calculatenetworkfee` 110 111 NeoGo tries to cover more cases with its calculatenetworkfee implementation, 112 whereas C# node support only standard signature contracts and deployed 113 contracts that can execute `verify` successfully on incomplete (not yet signed 114 properly) transaction, NeoGo also works with deployed contracts that fail at 115 this stage and executes non-standard contracts (that can fail 116 too). It's ignoring the result of any verification script (since the method 117 calculates fee and doesn't care about transaction validity). Invocation script 118 is used as is when provided, but absent it the system will try to infer one 119 based on the `verify` method signature (pushing dummy signatures or 120 hashes). If signature has some types which contents can't be adequately 121 guessed (arrays, maps, interop, void) they're ignored. See 122 neo-project/neo#2805 as well. 123 124 ##### `invokefunction`, `invokescript` 125 126 neo-go implementation of `invokefunction` does not return `tx` 127 field in the answer because that requires signing the transaction with some 128 key in the server, which doesn't fit the model of our node-client interactions. 129 If this signature is lacking, the transaction is almost useless, so there is no point 130 in returning it. 131 132 It's possible to use `invokefunction` not only with a contract scripthash, but also 133 with a contract name (for native contracts) or a contract ID (for all contracts). This 134 feature is not supported by the C# node. 135 136 If iterator is present on stack after function or script invocation then, depending 137 on `SessionEnable` RPC-server setting, iterator either will be marshalled as iterator 138 ID (corresponds to `SessionEnabled: true`) or as a set of traversed iterator values 139 up to `DefaultMaxIteratorResultItems` packed into array (corresponds to 140 `SessionEnabled: false`). 141 142 ##### `getcontractstate` 143 144 It's possible to get non-native contract state by its ID, unlike with C# node where 145 it only works for native contracts. 146 147 ##### `getrawtransaction` 148 149 VM state is included into verbose response along with other transaction fields if 150 the transaction is already on chain. 151 152 ##### `getstateroot` 153 154 This method is able to accept state root hash instead of index, unlike the C# node 155 where only index is accepted. 156 157 ##### `getstorage` 158 159 This method doesn't work for the Ledger contract, you can get data via regular 160 `getblock` and `getrawtransaction` calls. This method is able to get storage of 161 a native contract by its name (case-insensitive), unlike the C# node where 162 it only possible for index or hash. 163 164 ##### `getnep11balances` and `getnep17balances` 165 neo-go implementation of `getnep11balances` and `getnep17balances` does not 166 perform tracking of NEP-11 and NEP-17 balances for each account as it is done 167 in the C# node. Instead, a neo-go node maintains a list of standard-compliant 168 contracts, i.e. those contracts that have `NEP-11` or `NEP-17` declared in the 169 supported standards section of the manifest. Each time balances are queried, 170 the neo-go node asks every NEP-11/NEP-17 contract for the account balance by 171 invoking `balanceOf` method with the corresponding args. Invocation GAS limit 172 is set to be 3 GAS. All non-zero balances are included in the RPC call result. 173 174 Thus, if a token contract doesn't have proper standard declared in the list of 175 supported standards but emits compliant NEP-11/NEP-17 `Transfer` 176 notifications, the token balance won't be shown in the list of balances 177 returned by the neo-go node (unlike the C# node behavior). However, transfer 178 logs of such tokens are still available via respective `getnepXXtransfers` RPC 179 calls. 180 181 The behavior of the `LastUpdatedBlock` tracking for archival nodes as far as for 182 governing token balances matches the C# node's one. For non-archival nodes and 183 other NEP-11/NEP-17 tokens, if transfer's `LastUpdatedBlock` is lower than the 184 latest state synchronization point P the node working against, 185 `LastUpdatedBlock` equals P. For NEP-11 NFTs `LastUpdatedBlock` is equal for 186 all tokens of the same asset. 187 188 ##### `getversion` 189 190 NeoGo can return additional fields in the `protocol` object depending on the 191 extensions enabled. Specifically that's `p2psigextensions` and 192 `staterootinheader` booleans and `committeehistory` and `validatorshistory` 193 objects (that are effectively maps from stringified integers to other 194 integers. These fields are only returned when corresponding settings are 195 enabled in the server's protocol configuration. 196 197 ##### `getnep11transfers` and `getnep17transfers` 198 `transfernotifyindex` is not tracked by NeoGo, thus this field is always zero. 199 200 ##### `traverseiterator` and `terminatesession` 201 202 NeoGo returns an error when it is unable to find a session or iterator, unlike 203 the error-free C# response that provides a default result. 204 205 ##### `verifyProof` 206 207 NeoGo can generate an error in response to an invalid proof, unlike 208 the error-free C# implementation. 209 210 ### Unsupported methods 211 212 Methods listed below are not going to be supported for various reasons 213 and we're not accepting issues related to them. 214 215 | Method | Reason | 216 | ------- | ------------| 217 | `canceltransaction` | Doesn't fit neo-go wallet model, use CLI to do that (`neo-go util canceltx`) | 218 | `closewallet` | Doesn't fit neo-go wallet model | 219 | `dumpprivkey` | Shouldn't exist for security reasons, see `closewallet` comment also | 220 | `getnewaddress` | See `closewallet` comment, use CLI to do that | 221 | `getwalletbalance` | See `closewallet` comment, use `getnep17balances` for that | 222 | `getwalletunclaimedgas` | See `closewallet` comment, use `getunclaimedgas` for that | 223 | `importprivkey` | Not applicable to neo-go, see `closewallet` comment | 224 | `listaddress` | Not applicable to neo-go, see `closewallet` comment | 225 | `listplugins` | neo-go doesn't have any plugins, so it makes no sense | 226 | `openwallet` | Doesn't fit neo-go wallet model | 227 | `sendfrom` | Not applicable to neo-go, see `openwallet` comment | 228 | `sendmany` | Not applicable to neo-go, see `openwallet` comment | 229 | `sendtoaddress` | Not applicable to neo-go, see `claimgas` comment | 230 231 ### Extensions 232 233 Some additional extensions are implemented as a part of this RPC server. 234 235 #### `getblocksysfee` call 236 237 This method returns cumulative system fee for all transactions included in a 238 block. It can be removed in future versions, but at the moment you can use it 239 to see how much GAS is burned with a particular block (because system fees are 240 burned). 241 242 #### Historic calls 243 244 A set of `*historic` extension methods provide the ability of interacting with 245 *historical* chain state including invoking contract methods, running scripts and 246 retrieving contract storage items. It means that the contracts' storage state has 247 all its values got from MPT with the specified stateroot from past (or, which is 248 the same, with the stateroot of the block of the specified height). All 249 operations related to the contract storage will be performed using this past 250 contracts' storage state and using interop context (if required by the RPC 251 handler) with a block which is next to the block with the specified height. 252 253 Any historical RPC call needs the historical chain state to be presented in the 254 node storage, thus if the node keeps only latest MPT state the historical call 255 can not be handled properly and 256 [neorpc.ErrUnsupportedState](https://github.com/nspcc-dev/neo-go/blob/87e4b6beaafa3c180184cbbe88ba143378c5024c/pkg/neorpc/errors.go#L134) 257 is returned in this case. The historical calls only guaranteed to correctly work 258 on archival node that stores all MPT data. If a node keeps the number of latest 259 states and has the GC on (this setting corresponds to the 260 `RemoveUntraceableBlocks` set to `true`), then the behaviour of historical RPC 261 call is undefined. GC can always kick some data out of the storage while the 262 historical call is executing, thus keep in mind that the call can be processed 263 with `RemoveUntraceableBlocks` only with limitations on available data. 264 265 ##### `invokecontractverifyhistoric`, `invokefunctionhistoric` and `invokescripthistoric` calls 266 267 These methods provide the ability of *historical* calls and accept block hash or 268 block index or stateroot hash as the first parameter and the list of parameters 269 that is the same as of `invokecontractverify`, `invokefunction` and 270 `invokescript` correspondingly. The historical call assumes that the contracts' 271 storage state has all its values got from MPT with the specified stateroot (or, 272 which is the same, with the stateroot of the block of the specified height) and 273 the transaction will be invoked using interop context with block which is next to 274 the block with the specified height. This allows to perform test invocation using 275 the specified past chain state. These methods may be useful for debugging 276 purposes. 277 278 ##### `getstoragehistoric` and `findstoragehistoric` calls 279 280 These methods provide the ability of retrieving *historical* contract storage 281 items and accept stateroot hash as the first parameter and the list of parameters 282 that is the same as of `getstorage` and `findstorage` correspondingly. The 283 historical storage items retrieval process assume that the contracts' storage 284 state has all its values got from MPT with the specified stateroot. This allows 285 to track the contract storage scheme using the specified past chain state. These 286 methods may be useful for debugging purposes. 287 288 #### P2PNotary extensions 289 290 The following P2PNotary extensions can be used on P2P Notary enabled networks 291 only. 292 293 ##### `getrawnotarypool` call 294 295 `getrawnotarypool` method provides the ability to retrieve the content of the 296 RPC node's notary pool (a map from main transaction hashes to the corresponding 297 fallback transaction hashes for currently processing P2PNotaryRequest payloads). 298 You can use the `getrawnotarytransaction` method to iterate through 299 the results of `getrawnotarypool`, retrieve main/fallback transactions, 300 check their contents and act accordingly. 301 302 ##### `getrawnotarytransaction` call 303 304 The `getrawnotarytransaction` method takes a transaction hash and aims to locate 305 the corresponding transaction in the P2PNotaryRequest pool. It performs 306 this search across all the verified main and fallback transactions. 307 308 ##### `submitnotaryrequest` call 309 310 This method can be used on P2P Notary enabled networks to submit new notary 311 payloads to be relayed from RPC to P2P. 312 313 #### Limits and paging for getnep11transfers and getnep17transfers 314 315 `getnep11transfers` and `getnep17transfers` RPC calls never return more than 316 1000 results for one request (within the specified time frame). You can pass your 317 own limit via an additional parameter and then use paging to request the next 318 batch of transfers. 319 320 An example of requesting 10 events for address NbTiM6h8r99kpRtb428XcsUk1TzKed2gTc 321 within 0-1600094189000 timestamps: 322 323 ```json 324 { "jsonrpc": "2.0", "id": 5, "method": "getnep17transfers", "params": 325 ["NbTiM6h8r99kpRtb428XcsUk1TzKed2gTc", 0, 1600094189000, 10] } 326 ``` 327 328 Get the next 10 transfers for the same account within the same time frame: 329 330 ```json 331 { "jsonrpc": "2.0", "id": 5, "method": "getnep17transfers", "params": 332 ["NbTiM6h8r99kpRtb428XcsUk1TzKed2gTc", 0, 1600094189000, 10, 1] } 333 ``` 334 335 #### Websocket server 336 337 This server accepts websocket connections on `ws://$BASE_URL/ws` address. You 338 can use it to perform regular RPC calls over websockets (it's supposed to be a 339 little faster than going regular HTTP route) and you can also use it for 340 additional functionality provided only via websockets (like notifications). 341 342 #### Notification subsystem 343 344 Notification subsystem consists of two additional RPC methods (`subscribe` and 345 `unsubscribe` working only over websocket connection) that allow to subscribe 346 to various blockchain events (with simple event filtering) and receive them on 347 the client as JSON-RPC notifications. More details on that are written in the 348 [notifications specification](notifications.md). 349 350 ## Reference 351 352 * [JSON-RPC 2.0 Specification](http://www.jsonrpc.org/specification) 353 * [Neo JSON-RPC 2.0 docs](https://docs.neo.org/docs/en-us/reference/rpc/latest-version/api.html)