Creating mdbook documentation for RPC

docs/src/SUMMARY.md

@@ -15,6 +15,7 @@
   - [Reorganization](./neptune-core/reorganization.md)
   - [Keys and Addresses](./neptune-core/keys.md)
   - [Utxo Notification](./neptune-core/utxo_notification.md)
+  - [RPC](./neptune-core/rpc.md)
 - [User Guides](./user-guides.md)
   - [Installation](./user-guides/installation.md)
   - [Managing Secret Seeds](./user-guides/managing-secret-seeds.md)

docs/src/neptune-core/rpc.md

@@ -0,0 +1,37 @@
+# RPC
+`neptune-core` provides an RPC server and client based on [tarpc](https://docs.rs/crate/tarpc) with [serde_json](https://docs.rs/crate/serde_json) transport. The RPC server provides a set of methods that allow clients to query the state of the node, submit transactions, and interact with the blockchain.
+
+As we use [tarpc](https://docs.rs/crate/tarpc/latest), it is easier to build a client in Rust. However, it is also possible to build a client in other languages that support JSON-RPC.
+
+The RPC server listens on the address specified by the `rpc-port` configuration option. The default address is `9799`.
+
+## Authentication 
+`neptune-core` currently supports cookie-based authentication. The RPC server provides a `cookie-hint` method that allows clients to locate the data-directory in a zero configuration way. If this method fails, the client should fall-back to the default data-directory location.
+
+## Versionning 
+Currently, we are on version `1.0` of the RPC server. This version is hardcoded in the RPC server and client. We will increment the version number if we make breaking changes to the RPC server.
+
+## Security 
+
+The RPC server allows other programs to interact with a `neptune-core` node including submitting transactions and querying the state of the node. This section suggests some best practices for securing the RPC server.
+
+- Securing the executable : Since the RPC server runs on the same executable as `neptune-core` it is important to secure the executable to prevent unauthorized access. This can be done by setting the appropriate permissions on the executable and using a secure operating system.
+
+- Securing remote access : The RPC server can be accessed remotely by clients on the internet. It is important to secure the RPC server to prevent unauthorized access. This can be done by setting up a firewall to restrict access to the RPC server port and using encryption to secure the connection.
+
+- Secure string handling : The RPC server accepts strings as input from clients. It is important to validate and sanitize the input strings to prevent injection attacks.
+
+## RPC Methods
+
+The RPC server provides several methods that allow clients to interact with the node. The list of methods and examples are provided on the [`neptune-cash` crate documentation](https://docs.rs/neptune-cash/latest/neptune_cash/rpc_server/trait.RPC.html).
+
+## RPC consistency guarantees
+State that can be queried via RPCs is guaranteed to be at least up-to-date with the chain state immediately prior to the call's execution. However, the state returned by RPCs that reflect the mempool may not be up-to-date with the current mempool state.
+
+## Transaction Pool
+The mempool state returned via an RPC is consistent with itself and with the chain state at the time of the call. Thus, the mempool state only encompasses transactions that are considered mine-able by the node at the time of the RPC.
+
+The mempool state returned via an RPC reflects all effects of mempool and chain state related RPCs that returned prior to this call.
+
+## Limitations
+There is a known issue in the JSON-RPC interface that can cause a node to crash if too many http connections are being opened at the same time because the system runs out of available file descriptors. To prevent this from happening you might want to increase the number of maximum allowed file descriptors in your system and try to prevent opening too many connections to your JSON-RPC interface at the same time if this is under your control. It is hard to give general advice since this depends on your system but if you make several hundred requests at once you are definitely at risk of encountering this issue.