Skip to main content

Private RPC Server Mode

This page describes the "private" RPC server mode that restricts access to network data, facilitating data privacy.

Overview​

This RPC service mode requires authenticated call requests, disables ad-hoc SQL queries, and omits raw transaction data from transaction status queries.

danger

Private RPC mode should be used with peer filtering as described on the Private Networks page, or with coordinated access control applied across all nodes' P2P services (e.g. linked via VPN). Open access to a node's P2P service makes all data available to any other Kwil node that can reach it.

Node Configuration​

The app.private_rpc setting is used to enable the private RPC mode. Enable it in the config.toml file:

[app]

# Enforce data privacy: authenticate JSON-RPC call requests using challenge-based
# authentication. the node will only accept JSON-RPC requests that has a valid signed
# challenge response. This also disables ad hoc queries, and no raw transaction retrieval.
private_rpc = true

When enabled, kwild does the following:

  1. "Call" requests must be signed, and contain a challenge provided by the RPC service for replay protection.
  2. Ad-hoc SQL queries are disabled.
  3. Transaction status responses omit verbose transaction details that would contain the transaction body where any user data may be present.

The RPC server may also be configured to control call challenge handling. Challenges issued to clients expire after the duration specified by the app.challenge_expiry setting. This may be shortened if clients provide signed call requests quickly, or lengthened if interactive signing requires additional time. The app.challenge_rate_limit setting controls the maximum frequency at which a client (by IP address) is permitted to request call challenges. See the node config reference for details.

Quickstart​

To quickly enable private RPC mode, use the --app.private-rpc flag when starting kwild:

kwild --app.private-rpc

See the Node Quickstart guide for more information.

Client​

For RPC clients to make call requests with servers running in private mode, the call request must include a valid signature and a server-provided "challenge". The client requests a "challenge", which it includes in the call request that is signed with the user's private key for authentication.

note

The clients maintained by the Kwil team (Kwil CLI, kwil-js, and Kwil Go) will automatically handle the challenge request authentication if the client is configured with a private key.