Developer Resources
Block ExplorerGitHubRun a NodeMigration GuideETN Testnet Faucet
  • Overview
  • Foundational topics
    • Intro to the Electroneum Smart Chain
    • Intro to ETN
    • Intro to dapps
    • Web2 vs Web3
    • Accounts
    • Transactions
    • Blocks
    • Electroneum Virtual Machine (EVM)
      • Opcodes
    • Gas and Fees
    • Nodes and clients
    • Networks
    • Consensus mechanisms
      • IBFT
  • Electroneum Stack
    • Intro to the stack
    • Smart contracts
    • Development networks
    • Development frameworks
    • Electroneum client APIs
      • JavaScript APIs
      • JSON-RPC
    • Storage
    • Integrated Development Environments (IDEs)
    • Metamask
  • Advanced
    • Bridges
    • Standards
      • Token standards
        • ERC-20 Fungible Tokens
        • ERC-721 NFTs
    • Oracles
    • Networking layer
      • Network addresses
    • Data structures and encoding
      • Patricia Merkle Trie
      • Recursive-length prefix (RLP)
      • Web3 secret storage definition
  • Design fundamentals
    • Intro to design and UX
  • ETN-SC Client
    • Getting started
      • Introduction
      • Hardware requirements
      • Instaling ETN-SC
    • Fundamentals
      • Command-line options
      • Security
      • Sync-modes
      • Account management
      • Databases
      • Backup & restore
      • Logs
      • Connecting to peers
      • Pruning
      • Private networks
      • Config files
      • Light client
    • Interacting with ETN-SC
      • JSON-RPC Server
        • Batch requests
        • Real-time events
      • JSON-RPC Namespaces
        • admin
        • clique
        • debug
        • eth
        • istanbul
        • les
        • miner
        • net
        • personal
        • txpool
      • JS Console
      • JS Console 2: Contracts
      • GraphQL Server
    • Developers
      • Introduction
      • Dapp developers
        • Dev mode
        • Go API
        • Go Account Management
        • Go Contract Bindings
      • EVM tracing
        • Introduction
        • Basic traces
        • Built-in tracers
        • Custom EVM tracer
        • Tutorial for JavaScript tracing
      • ETN-SC developer
        • Developer guide
        • Disclosures
        • DNS discovery setup guide
        • Code review guidelines
      • Contributing
    • Monitoring
      • Creating Dashboards
      • Understanding Dashboards
      • Ethstats
      • Metrics
    • Tools
      • Clef
        • Introduction
        • APIs
        • Rules
        • Setup
        • Datatypes
        • Tutorial
        • Clique-signing
      • abigen
      • devp2p
    • FAQs
  • Migration to Smart Chain
    • Overview
    • How to Migrate
      • ETN Online Wallets
      • Paper Wallets
      • CLI Wallet Users
      • Exchange Holders
      • Exchanges
    • Bridge Smart Contract
  • Misc. Guides
    • Set up Ledger + Metamask
  • MY.ELECTRONEUM.COM
    • Vendor API
Powered by GitBook
On this page
  • Introduction
  • Transports
  • HTTP Server
  • WebSocket Server
  • IPC Server
  • Choosing a transport protocol
  • Summary

Was this helpful?

  1. ETN-SC Client
  2. Interacting with ETN-SC

JSON-RPC Server

PreviousInteracting with ETN-SCNextBatch requests

Last updated 1 year ago

Was this helpful?

Interacting with Etn-sc requires sending requests to specific JSON-RPC API methods. Etn-sc supports all standard endpoints. The RPC requests must be sent to the node and the response returned to the client using some transport protocol. This page outlines the available transport protocols in Etn-sc, providing the information users require to choose a transport protocol for a specific user scenario.

Introduction

JSON-RPC is provided on multiple transports. Etn-sc supports JSON-RPC over HTTP, WebSocket and Unix Domain Sockets. Transports must be enabled through command-line flags.

Electroneum JSON-RPC APIs use a name-space system. RPC methods are grouped into several categories depending on their purpose. All method names are composed of the namespace, an underscore, and the actual method name within the namespace. For example, the eth_call method resides in the eth namespace.

Access to RPC methods can be enabled on a per-namespace basis. Find documentation for individual namespaces in the sidebar.

Transports

There are three transport protocols available in Etn-sc: IPC, HTTP and Websockets.

HTTP Server

is a unidirectional transport protocol that connects a client and server. The client sends a request to the server, and the server returns a response back to the client. An HTTP connection is closed after the response for a given request is sent.

HTTP is supported in every browser as well as almost all programming toolchains. Due to its ubiquity it has become the most widely used transport for interacting with Etn-sc. To start a HTTP server in Etn-sc, include the --http flag:

./etn-sc --http

If no other commands are provided, Etn-sc falls back to its default behaviour of accepting connections from the local loopback interface (127.0.0.1). The default listening port is 8545. The ip address and listening port can be customized using the --http.addr and --http.port flags:

./etn-sc --http --http.port 3334

Not all of the JSON-RPC method namespaces are enabled for HTTP requests by default. Instead, they have to be whitelisted explicitly when Etn-sc is started. Calling non-whitelisted RPC namespaces returns an RPC error with code -32602.

The default whitelist allows access to the eth, net and web3 namespaces. To enable access to other APIs like debugging (debug), they must be configured using the --http.api flag. Enabling these APIs over HTTP is not recommended because access to these methods increases the attack surface.

./etn-sc --http --http.api eth,net,web3
./etn-sc --http --http.corsdomain https://remix.ethereum.org

The --http.corsdomain command also accepts wildcards that enable access to the RPC from any origin:

--http.corsdomain '*'

WebSocket Server

Websocket is a bidirectional transport protocol. A Websocket connection is maintained by client and server until it is explicitly terminated by one. Most modern browsers support Websocket which means it has good tooling.

Configuration of the WebSocket endpoint in Etn-sc follows the same pattern as the HTTP transport. WebSocket access can be enabled using the --ws flag. If no additional information is provided, Etn-sc falls back to its default behaviour which is to establish the Websocket on port 8546. The --ws.addr, --ws.port and --ws.api flags can be used to customize settings for the WebSocket server. For example, to start Etn-sc with a Websocket connection for RPC using the custom port 3334 and whitelisting the eth, net and web3 namespaces:

./etn-sc --ws --ws.port 3334 --ws.api eth,net,web3

Cross-Origin request protection also applies to the WebSocket server. The --ws.origins flag can be used to allow access to the server from web pages:

./etn-sc --ws --ws.origins http://myapp.example.com

As with --http.corsdomain, using the wildcard --ws.origins '*' allows access from any origin.

By default, account unlocking is forbidden when HTTP or Websocket access is enabled (i.e. by passing --http or ws flag). This is because an attacker that manages to access the node via the externally-exposed HTTP/WS port can then control the unlocked account. It is possible to force account unlock by including the --allow-insecure-unlock flag but this is unsafe and not recommended except for expert users that completely understand how it can be used safely. This is not a hypothetical risk: there are bots that continually scan for http-enabled Electroneum nodes to attack

IPC Server

IPC is normally available for use in local environments where the node and the console exist on the same machine. Etn-sc creates a pipe in the computers local file system (at ipcpath) that configures a connection between node and console. The etn-sc.ipc file can also be used by other processes on the same machine to interact with Etn-sc.

On UNIX-based systems (Linux, OSX) the IPC is a UNIX domain socket. On Windows IPC is provided using named pipes. The IPC server is enabled by default and has access to all JSON-RPC namespaces.

The listening socket is placed into the data directory by default. On Linux and macOS, the default location of the etn-sc socket is

~/.electroneum-sc/etn-sc.ipc

On Windows, IPC is provided via named pipes. The default location of the etn-sc pipe is:

\\.\pipe\etn-sc.ipc

The location of the socket can be customized using the --ipcpath flag. IPC can be disabled using the --ipcdisable flag.

Choosing a transport protocol

The following table summarizes the relative strengths and weaknesses of each transport protocol so that users can make informed decisions about which to use.

HTTP
WS
IPC

Event subscription

N

Y

Y

Remote connection

Y

Y

N

Per-message metadata overhead

high

low

low

As a general rule IPC is most secure because it is limited to interactions on the local machine and cannot be exposed to external traffic. It can also be used to subscribe to events. HTTP is a familiar and idempotent transport that closes connections between requests and can therefore have lower overall overheads if the number of requests is fairly low. Websockets provides a continuous open channel that can enable event subscriptions and streaming and handle large volumes of requests with smaller per-message overheads.

Summary

RPC requests to a Etn-sc node can be made using three different transport protocols. The protocols are enabled at startup using their respective flags. The right choice of transport protocol depends on the specific use case.

Since the HTTP server is reachable from any local application, additional protection is built into the server to prevent misuse of the API from web pages. To enable access to the API from a web page (for example to use the online IDE, ), the server needs to be configured to accept Cross-Origin requests. This is achieved using the --http.corsdomain flag.

Because Websocket is bidirectional, servers can push events to clients. That makes Websocket a good choice for use-cases involving . Another benefit of Websocket is that after the handshake procedure, the overhead of individual messages is low, making it good for sending high number of requests.

JSON-RPC API
HTTP
Remix
event subscription