JSON-RPC APIs

For interacting with the blockchain, WorldLand provides a JSON-RPC API. The JSON-RPC API interacts with WorldLand in the form of JSON objects. RPC(Remote Procedure Call) refers to sending a request to the WorldLand node as a JSON object from the outside. You can interact with WorldLand by sending a JSON request to the RPC port exposed by WorldLand. Since JSON-RPC is not user-friendly, APIs such as web3 built on top of JSON-RPC provide user-friendly interfaces.

JSON-RPC Server

WorldLand has three transport protocols that can use the JSON-RPC API. The following table summarizes the comparison of the three transport protocols. IPC is a private and secure protocol. HTTP is a friendly protocol and reduces message overhead for intermittent requests. For continuous request processing, a WebSocket server is a good choice.

	HTTP	WebSoket	IPC
Subscribe to events	N	Y	Y
Remote Access	Y	Y	N
Metadata overhead per message	high	low	low

HTTP Server

HTTP is a one-way transport protocol that connects clients and servers. The client sends a request to the server and the server returns a response to the client. The HTTP connection is closed after the response to the given request has been sent. HTTP is the most commonly used because it is a very common and familiar protocol. Including the -http flag in the command launches the HTTP server.

./worldland -http

The HTTP server runs on localhost(127.0.0.1) and port 8545 by default. IP address and listening port This can be customized using the -http.addr and -http.port flags.

./worldland -http -http.port 3334 -http.addr 129.38.5.26

The HTTP server accepts only JSON-RPC requests for the eth,net,web3 modules by default. If you want to allow other modules, you must configure them using the -http.api flag.

Be careful with enabling additional API modules via HTTP as it increases your security risk.,

./worldland -http -http.api eth,net,web3

For security reasons, the HTTP server protects web pages from using APIs. To access the webpage, you need to add the webpage using the -http.corsdomain flag.

./worldland -http -http.corsdomain https://remix.ethereum.org

Add '*' to allow all web pages.

./worldland -http.corsdomain '*'

Websocket server

Websocket is a persistent, bidirectional transport protocol that keeps connections alive until terminated. Suitable for sending a large number of requests as it saves the handshake procedure. The flag command pattern is the same as for the HTTP server. The http command is replaced by ws. The default port for ws is 8546.

./worldland -ws -ws.port 3334 -ws.api eth,net,web3HTTP

Protecting webpage API requests is also the same, so use the -ws.origins flag for webpage requests.

./worldland -ws -ws.origins https://remix.ethereum.org

HTTP and Websocket servers allow external connections. This means that an external attacker can control the account inside WorldLand, so when the HTTP and Websocket servers are activated, the node account is locked. You can forcefully unlock an account by including the --allow-insecure-unlock flag, but this is not secure. Be aware that there are attacker bots constantly browsing the Ethereum HTTP server.

IPC server

IPC can usually be used in a local environment where the node and console exist on the same machine. WorldLand creates a local file socket to connect to the node. The IPC server is enabled by default and has access to all JSON-RPC modules. Sockets are placed in the same directory as the node.

~/DATA_DIR/geth.ipc

In Windows, IPC is provided through named pipes. The default location of the pipe is:

\\.\pipe\geth.ipc

The location of the socket can be changed using the -ipcpath flag and disabled with the -ipcdisable flag.

./worldland -ipcpath -ipcdisable

JSON-RPC Console

You can also start an interactive session by providing a console command when WorldLand starts. This will start the node and run the console in the same terminal. In this case, the log is output as well, so if not necessary, hide the log by redirecting it.

./worldland <other flags> console 2> /dev/null

You can redirect and save logs to a file. The level of detail provided in the logs can be tuned by supplying a value between 1-6 to the -verbosity flag, as shown in the example below.

./worldland <other flags> console --verbosity 3 2> worldland.log

You can interact with the node from the terminal console. The console supports the full JSON-RPC API.

To check the balance of the first account that already exists in the keystore:

eth.getBalance(eth.accounts[0]);

To send a transaction:

eth.sendTransaction({
  to: eth.accounts[0],
  to: eth.accounts[1],
  value: web3.toWei(0.5, 'ether')
});

You can also load a pre-built Javascript file into the console by passing the --preload flag when starting the console.

./worldland console --preload "/my/scripts/folder/utils.js"

You can close the console by typing exit or CTRL-D.

exit

APIs

WorldLand supports the same JSON-RPC module as Ethereum. See the JSON-RPC APIs of ethereum and go-ethereum for details.