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)