Nym API

ℹ️

Our documentation often refers to syntax annotated in <> brackets. We use this expression for variables that are unique to each user (like path, local moniker, versions et cetera). Any syntax in <> brackets needs to be substituted with your correct name or version, without the <> brackets. If you are unsure, please check our table of essential parameters and variables (opens in a new tab).

This page explains what the Nym API is, how operators are rewarded, what hardware it needs and how to run it in caching mode. If you are setting up a mainnet ecash signer, follow the Nym API signer setup guide instead, which covers the whole flow end to end.

What is the Nym API?

The Nym API is a binary operated by the Nyx validator set. It can run in several modes and has two main areas of functionality: network monitoring, which calculates the routing score of mixnet nodes, and the generation and validation of zk-nyms, our implementation of the Coconut Selective Disclosure Credential Scheme.

This matters both for proper decentralisation of network uptime calculation and, more pressingly, for enabling NymVPN to use privacy preserving payments.

⚠️

It is highly recommended to run nym-api alongside a full node and not a signing validator, since you will be exposing HTTP ports to the internet. We also observed degradation in p2p and block signing operations when nym-api was run alongside a signing validator.

Rewards

Operators of Nym API are rewarded for the extra work of taking part in credential generation. These rewards are calculated separately from rewards for block production.

Rewards for credential signing are calculated hourly, with API operators receiving an amount of the reward pool (330 NYM per hour, 237,600 NYM per month) proportional to the percentage of credentials they have signed.

Hardware requirements

The specification below is for running a full node alongside nym-api. It is recommended to run both on the same machine for optimum performance. Credential signing is primarily CPU-bound, so choose the fastest CPU available to you.

Minimum:

Hardware	Specification
CPU	8-cores, 2.8GHz base clock speed or higher
RAM	16GB DDR4+
Disk	500 GiB+ NVMe SSD

Recommended:

Hardware	Specification
CPU	16-cores, 2.8GHz base clock speed or higher
RAM	32GB DDR4+
Disk	1 TiB+ NVMe SSD

Full node configuration

To install a full node from scratch, refer to the Nyx validator setup and follow the steps there. Additionally, to ensure nym-api works as expected, confirm the configuration below.

1. Ensure transaction indexing is turned on in `config.toml`

nym-api checks the validity of user-submitted transactions when issuing credentials and as part of the double-spend check, so the index must not be disabled:

[tx_index]
indexer = "kv"

2. Ensure pruning settings are manually configured

Aggressively pruning data will lead to errors with your nym-api, because it reaches back into past transactions during issuance. In app.toml:

pruning = "custom"
pruning-keep-recent = "750000"
pruning-interval = "100"

The example value of 100 for pruning-interval can be customised as per your requirement.

ℹ️

If this full node exists purely to back a signer on the same machine, follow the local RPC setup instead - it binds RPC to loopback and covers the snapshot restore.

Credential generation and DKG

Validators that took part in a DKG ceremony became part of the quorum generating and verifying zk-nym credentials. These are used for private proof of payment for NymVPN, and in future will expand into more general use cases such as offline ecash (opens in a new tab).

The DKG ceremony creates a subset of existing validators who run nym-api alongside a Nyx full node, and they are the ones taking part in generation and verification of zk-nym credentials. The size of the minimum viable quorum is 10, with the initial set taking part in DKG being 17 validators, giving redundancy in case a validator drops or goes offline.

A DKG ceremony in points:

Deployment and initialisation of the group (opens in a new tab) and multisig (opens in a new tab) contracts by Nym. Only validators that are members of the group contract can take part.
Deployment and initialisation of an instance of the DKG contract (opens in a new tab) by Nym.
Operators enable zk-nym signing on their nym-api instance, as covered in the signer setup guide.
Under the hood each nym-api instance then takes part in several rounds of key submission, verification and derivation, until quorum is achieved.

ℹ️

Membership in the cw4 group contract is controlled by the network and is the sole authority the DKG contract consults. Being set up as a signer does not automatically make you a dealer, and group changes only take effect at the next DKG ceremony.

Current version

 
Binary Name:        nym-api
Build Timestamp:    2024-12-18T17:33:13.184930493Z
Build Version:      1.1.47
Commit SHA:         b628a5f8148f74c646915292c8b6dc0a46202a27
Commit Date:        2024-12-13T11:49:27.000000000+01:00
Commit Branch:      master
rustc Version:      1.84.0-nightly
rustc Channel:      nightly
cargo Profile:      release

Setup and usage

Viewing command help

Check your binary is properly compiled with:

./nym-api --help

Usage: nym-api [OPTIONS] <COMMAND>
 
Commands:
  init        Initialise a Nym Api instance with persistent config.toml file
  run         Run the Nym Api with provided configuration optionally overriding set parameters
  build-info  Show build information of this binary
  help        Print this message or the help of the given subcommand(s)
 
Options:
  -c, --config-env-file <CONFIG_ENV_FILE>  Path pointing to an env file that configures the Nym API [env: NYMAPI_CONFIG_ENV_FILE_ARG=]
      --no-banner                          A no-op flag included for consistency with other binaries (and compatibility with nymvisor, oops) [env: NYMAPI_NO_BANNER_ARG=]
  -h, --help                               Print help
  -V, --version                            Print version

You can also check the arguments for individual commands with:

./nym-api <COMMAND> --help

Initialising in caching mode

The API defaults to caching mode. Initialise an instance with:

./nym-api init

You can optionally pass a local identifier with the --id flag, otherwise the ID defaults to default.

ℹ️

To initialise an instance that signs credentials, you additionally need --enable-zk-nym, --mnemonic and --announce-address. The signer setup guide covers the full command and the funded account it requires.

Running your Nym API instance

./nym-api run --id <ID>

By default the API queries your full node on localhost:26657. If your node is hosted elsewhere, specify the RPC location with --nyxd-validator:

./nym-api run --id <ID> --nyxd-validator https://rpc-nym.yourcorp.tld:443

ℹ️

You can also change local_validator in the config file at $HOME/.nym/nym-api/<ID>/config/config.toml.

Automation

To automate restarts on reboot, see the Nym API systemd automation section.

You can also use nymvisor to automatically update nym-api - see the nymvisor upgrade page.

Exposing the web endpoint over HTTPS

It is recommended to expose the webserver over HTTPS using a webserver such as nginx. An example configuration is on the Nyx & Nym API configuration page. If you use a custom solution, ensure a permissive CORS policy by setting:

add_header 'Access-Control-Allow-Origin' '*';

Nyx Validator Setup Nym API Signer Setup