Gateways

The Nym gateway was built in the building nym section. If you haven’t yet built Nym and want to run the code, go there first.

Info

As a result of Project Smoosh, the current version of nym-gateway binary also contains nym-network-requester functionality which can be enabled by the operator. This combination is a basis of Nym Exit Gateway node - an essential piece in our new setup. Please read more in our Project Smoosh FAQ and Exit Gateway pages. We recommend operators begin to shift their setups to this new combined node, instead of operating two separate binaries.

Any syntax in <> brackets is a user’s unique variable. Exchange with a corresponding name without the <> brackets.

Current version

1.1.33

Preliminary steps

Make sure you do the preparation listed in the preliminary steps page before setting up your Gateway.

Gateway setup

Now that you have built the codebase, set up your wallet, and have a VPS with the nym-gateway binary, you can set up your gateway with the instructions below.

To begin, move to /target/release directory from which you run the node commands:

cd target/release

Viewing command help

You can check that your binaries are properly compiled with:

./nym-gateway --help

Console output

Implementation of the Nym Mixnet Gateway

Usage: nym-gateway [OPTIONS] <COMMAND>

Commands:
  init                     Initialise the gateway
  node-details             Show details of this gateway
  run                      Starts the gateway
  setup-network-requester  Add network requester support to this gateway
  sign                     Sign text to prove ownership of this mixnode
  build-info               Show build information of this binary
  completions              Generate shell completions
  generate-fig-spec        Generate Fig specification
  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 gateway
      --no-banner                          Flag used for disabling the printed banner in tty
  -h, --help                               Print help
  -V, --version                            Print version

You can also check the various arguments required for individual commands with:

./nym-gateway <COMMAND> --help

Adding --no-banner startup flag will prevent Nym banner being printed even if run in tty environment.

Initialising your Gateway

As Nym developers build towards Exit Gateway functionality, operators can now run their nym-gateway binary with inbuilt Network Requester and include the our new exit policy. Considering the plan to smoosh all the nodes into one binary and have wide opened Exit Gateways, we recommend this setup, instead of operating two separate binaries.

Warning

Before you start an Exit Gateway, read our Operators Legal Forum page and Project Smoosh FAQ.

Info

There has been an ongoing development with dynamic upgrades. Follow the status of the Project Smoosh changes and the progression state of exit policy implementation to be up to date with the current design.

Note: Due to the development towards Exit Gateway functionality the --host flag has been replaced with --listening-address, this is the IP address which is used for receiving sphinx packets and listening to client data. Another flag --public-ips is required; it’s a comma separated list of IP’s that are announced to the nym-api, it is usually the address which is used for bonding.

Initialising Exit Gateway

An operator can initialise the Exit Gateway functionality by adding Network Requester with the new exit policy option:

./nym-gateway init --id <ID> --listening-address 0.0.0.0 --public-ips "$(curl -4 https://ifconfig.me)" --with-network-requester --with-exit-policy true

If we follow the previous example with <ID> chosen superexitgateway, adding the --with-network-requester and --with-exit-policy flags, the outcome will be:

Console output

config path: /home/runner/.nym/gateways/superexitgateway/config/config.toml
identity key: 6Doxi42ReQFhZ1GCjc973VqEYquEMMochqBdqPqvUi8D
sphinx key: 35DVRBM624VLM5G73qcXUoTpu9sutrFSB9Ch5fTAQxMG
bind address: 0.0.0.0
mix port: 1789, clients port: 9000
data store is at: /home/runner/.nym/gateways/superexitgateway/data/db.sqlite
Network requester:
	enabled: true
	config path: /home/runner/.nym/gateways/superexitgateway/config/network_requester_config.toml
	identity key: 9Ne8jhG2qjxExadCGdt5ZSHWZeWeKRQtDKaPReBFfPYW
	encryption key: DFNciJrWkfyzcHURBFZvo5JnegA1zfFdxREbzUzSPKDH
	address: 9Ne8jhG2qjxExadCGdt5ZSHWZeWeKRQtDKaPReBFfPYW.DFNciJrWkfyzcHURBFZvo5JnegA1zfFdxREbzUzSPKDH@6Doxi42ReQFhZ1GCjc973VqEYquEMMochqBdqPqvUi8D
	uses open proxy: false
	uses exit policy: true
	sends statistics: false
	allow list path: /home/runner/.nym/gateways/superexitgateway/data/network-requester-data/allowed.list
	unknown list path: /home/runner/.nym/gateways/superexitgateway/data/network-requester-data/unknown.list

You can see that the printed information besides identity and sphinx keys also includes a long string called address. This is the address to be provided to your local socks5 client as a --provider if you wish to connect to your own Exit Gateway.

Additionally

Add Network Requester to an existing Gateway

If you already upgraded your Gateway to the latest version and initialised without a Network Requester, you can easily change its functionality to Exit Gateway with a command setup-network-requester.

See the options:

./nym-gateway setup-network-requester --help

Console output

Add network requester support to this gateway

Usage: nym-gateway setup-network-requester [OPTIONS] --id <ID>

Options:
      --id <ID>
          The id of the gateway you want to initialise local network requester for
      --custom-config-path <CUSTOM_CONFIG_PATH>
          Path to custom location for network requester's config
      --enabled <ENABLED>
          Specify whether the network requester should be enabled [possible values: true, false]
      --open-proxy <OPEN_PROXY>
          Specifies whether this network requester should run in 'open-proxy' mode [possible values: true, false]
      --enable-statistics <ENABLE_STATISTICS>
          Enable service anonymized statistics that get sent to a statistics aggregator server [possible values: true, false]
      --statistics-recipient <STATISTICS_RECIPIENT>
          Mixnet client address where a statistics aggregator is running. The default value is a Nym aggregator client
      --with-exit-policy <WITH_EXIT_POLICY>
          Specifies whether this network requester will run using the default ExitPolicy as opposed to the allow list. Note: this setting will become the default in the future releases [possible values: true, false]
  -o, --output <OUTPUT>
          [default: text] [possible values: text, json]
  -h, --help
          Print help

To setup Exit Gateway functionality with our new exit policy add a flag --with-exit-policy true.

./nym-gateway setup-network-requester --enabled true --with-exit-policy true --id <ID> 

Say we have a Gateway with <ID> as new-gateway, originally initialised and ran without the Exit Gateway functionality. To change the setup, run:

./nym-gateway setup-network-requester --enabled true --with-exit-policy true --id new-gateway

Console output

config path: /home/runner/.nym/gateways/new-gateway/config/config.toml
identity key: 6QCDuDp6gxTERVJWG5YQ8xKCeoo5f1uTudWYpJ3TPFur
sphinx key: 8h5ndEqR1UT2yUZxuhjaxpPF2PpiUgB7LYQwBs59ekkV
bind address: 0.0.0.0
mix port: 1789, clients port: 9000
data store is at: /home/runner/.nym/gateways/new-gateway/data/db.sqlite

Network requester:
	enabled: true
	config path: /home/runner/.nym/gateways/new-gateway/config/network_requester_config.toml
	identity key: 6ucEJB6Gg1ev9bwGqLF7RrM6CWVTJfHURNek9FY6HGSF
	encryption key: 7jqpzKbhy7zLqHeDFYCfwZVdoPcVbky7gkQd6QbrExAM
	address: 6ucEJB6Gg1ev9bwGqLF7RrM6CWVTJfHURNek9FY6HGSF.7jqpzKbhy7zLqHeDFYCfwZVdoPcVbky7gkQd6QbrExAM@6QCDuDp6gxTERVJWG5YQ8xKCeoo5f1uTudWYpJ3TPFur
	uses open proxy: false
	uses exit policy: true
	sends statistics: false
	allow list path: /home/runner/.nym/gateways/new-gateway/data/network-requester-data/allowed.list
	unknown list path: /home/runner/.nym/gateways/new-gateway/data/network-requester-data/unknown.list

In case there are any unexpected problems, you can also change it manually by editing the Gateway config file stored in /home/user/.nym/gateways/<ID>/config/config.toml where the line under [network_requester] needs to be edited from false to true.

[network_requester]
# Specifies whether Network Requester service is enabled in this process.
enabled = true

Save, exit and restart your Gateway. Now you are an operator of post-smooshed Exit Gateway.

Enable Nym exit policy to an existing Gateway with Network Requester functionality

In case you already added Network Requester functionality to your Gateway as described above but haven’t enabled the exit policy there is an easy tweak to do so and turn your node into Nym Exit Gateway.

Open the config file stored at .nym/gateways/<ID>/config/network_requester_config.toml and set:

use_deprecated_allow_list = false

Save, exit and restart your Gateway. Now you are an operator of post-smooshed Exit gateway.

Info

All information about Network Requester part of your Exit Gateway is in /home/user/.nym/gateways/<ID>/config/network_requester_config.toml.

For now you can run Gateway without Network Requester or with and without the new exit policy. This will soon change as we inform in our Project Smoosh FAQ.

To read more about the configuration like whitelisted outbound requesters in allowed.list and other useful information, see the page Network Requester whitelist.

Initialising Gateway without Network Requester

In case you don’t want to run your Gateway with the Exit Gateway functionality, you still can run a simple Gateway.

To check available configuration options use:

 ./nym-gateway init --help

Console output

Initialise the gateway

Usage: nym-gateway init [OPTIONS] --id <ID> --listening-address <LISTENING_ADDRESS>

Options:
      --id <ID>
          Id of the gateway we want to create config for
      --listening-address <LISTENING_ADDRESS>
          The listening address on which the gateway will be receiving sphinx packets and listening for client data
      --public-ips <PUBLIC_IPS>
          Comma separated list of public ip addresses that will announced to the nym-api and subsequently to the clients. In nearly all circumstances, it's going to be identical to the address you're going to use for bonding
      --hostname <HOSTNAME>
          Optional hostname associated with this gateway that will announced to the nym-api and subsequently to the clients
      --mix-port <MIX_PORT>
          The port on which the gateway will be listening for sphinx packets
      --clients-port <CLIENTS_PORT>
          The port on which the gateway will be listening for clients gateway-requests
      --datastore <DATASTORE>
          Path to sqlite database containing all gateway persistent data
      --nym-apis <NYM_APIS>
          Comma separated list of endpoints of nym APIs
      --mnemonic <MNEMONIC>
          Cosmos wallet mnemonic needed for double spending protection
      --enabled-statistics <ENABLED_STATISTICS>
          Enable/disable gateway anonymized statistics that get sent to a statistics aggregator server [possible values: true, false]
      --statistics-service-url <STATISTICS_SERVICE_URL>
          URL where a statistics aggregator is running. The default value is a Nym aggregator server
      --with-network-requester
          Allows this gateway to run an embedded network requester for minimal network overhead
      --open-proxy <OPEN_PROXY>
          Specifies whether this network requester should run in 'open-proxy' mode [possible values: true, false]
      --enable-statistics <ENABLE_STATISTICS>
          Enable service anonymized statistics that get sent to a statistics aggregator server [possible values: true, false]
      --statistics-recipient <STATISTICS_RECIPIENT>
          Mixnet client address where a statistics aggregator is running. The default value is a Nym aggregator client
      --with-exit-policy <WITH_EXIT_POLICY>
          Specifies whether this network requester will run using the default ExitPolicy as opposed to the allow list. Note: this setting will become the default in the future releases [possible values: true, false]
  -o, --output <OUTPUT>
          [default: text] [possible values: text, json]
  -h, --help
          Print help

The following command returns a Gateway on your current IP with the <ID> of simple-gateway:

./nym-gateway init --id simple-gateway --listening-address 0.0.0.0 --public-ips "$(curl -4 https://ifconfig.me)"

Console output

config path: /home/runner/.nym/gateways/simple-gateway/config/config.toml
identity key: P9eW8vniDZHCkDwr2ZThzJJtgCq6z3dWyou47SfJA9K
sphinx key: Fyyd23hRBEH9RxSkESRks7pgpLHNVrk9kabbFn89Qg4e
bind address: 0.0.0.0
mix port: 1789, clients port: 9000
data store is at: /home/runner/.nym/gateways/simple-gateway/data/db.sqlite

The $(curl -4 https://ifconfig.me) command above returns your IP automatically using an external service. Alternatively, you can enter your IP manually if you wish. If you do this, remember to enter your IP without any port information.

Running your Gateway

The run command starts the Gateway:

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

Bonding your Gateway

Info

Before you bond your Gateway, please make sure the firewall configuration is setup so your Gateway can be reached from the outside. You can also setup WSS on your Gateway and automate your Gateway to simplify the operation overhead. We highly recommend to run any of these steps before bonding to prevent disruption of your Gateway’s routing score later on.

You can bond your Gateway via the Desktop wallet. Make sure your Gateway is running first, then follow the steps below:

  1. Open your wallet, and head to the Bonding page, then select the node type Gateway and input your node details. Press Next.

  2. Enter the Amount, Operating cost and press Next.

  3. You will be asked to run a the sign command with your gateway - copy and paste the long signature <PAYLOAD_GENERATED_BY_THE_WALLET> and paste it as a value of --contract-msg in the following command:

./nym-gateway sign --id <YOUR_ID> --contract-msg <PAYLOAD_GENERATED_BY_THE_WALLET>

It will look something like this (as <YOUR_ID> we used supergateway):

Console output

./nym-gateway sign --id supergateway --contract-msg 2Mf8xYytgEeyJke9LA7TjhHoGQWNBEfgHZtTyy2krFJfGHSiqy7FLgTnauSkQepCZTqKN5Yfi34JQCuog9k6FGA2EjsdpNGAWHZiuUGDipyJ6UksNKRxnFKhYW7ri4MRduyZwbR98y5fQMLAwHne1Tjm9cXYCn8McfigNt77WAYwBk5bRRKmC34BJMmWcAxphcLES2v9RdSR68tkHSpy2C8STfdmAQs3tZg8bJS5Qa8pQdqx14TnfQAPLk3QYCynfUJvgcQTrg29aqCasceGRpKdQ3Tbn81MLXAGAs7JLBbiMEAhCezAr2kEN8kET1q54zXtKz6znTPgeTZoSbP8rzf4k2JKHZYWrHYF9JriXepuZTnyxAKAxvGFPBk8Z6KAQi33NRQkwd7MPyttatHna6kG9x7knffV6ebGzgRBf7NV27LurH8x4L1uUXwm1v1UYCA1WSBQ9Pp2JW69k5v5v7G9gBy8RUcZnMbeL26Qqb8WkuGcmuHhaFfoqSfV7PRHPpPT4M8uRqUyR4bjUtSJJM1yh6QSeZk9BEazzoJqPeYeGoiFDZ3LMj2jesbJweQR4caaYuRczK92UGSSqu9zBKmE45a


      _ __  _   _ _ __ ___
     | '_ \| | | | '_ \ _ \
     | | | | |_| | | | | | |
     |_| |_|\__, |_| |_| |_|
            |___/

             (nym-gateway - version v1.1.<XX>)  


>>> attempting to sign 2Mf8xYytgEeyJke9LA7TjhHoGQWNBEfgHZtTyy2krFJfGHSiqy7FLgTnauSkQepCZTqKN5Yfi34JQCuog9k6FGA2EjsdpNGAWHZiuUGDipyJ6UksNKRxnFKhYW7ri4MRduyZwbR98y5fQMLAwHne1Tjm9cXYCn8McfigNt77WAYwBk5bRRKmC34BJMmWcAxphcLES2v9RdSR68tkHSpy2C8STfdmAQs3tZg8bJS5Qa8pQdqx14TnfQAPLk3QYCynfUJvgcQTrg29aqCasceGRpKdQ3Tbn81MLXAGAs7JLBbiMEAhCezAr2kEN8kET1q54zXtKz6znTPgeTZoSbP8rzf4k2JKHZYWrHYF9JriXepuZTnyxAKAxvGFPBk8Z6KAQi33NRQkwd7MPyttatHna6kG9x7knffV6ebGzgRBf7NV27LurH8x4L1uUXwm1v1UYCA1WSBQ9Pp2JW69k5v5v7G9gBy8RUcZnMbeL26Qqb8WkuGcmuHhaFfoqSfV7PRHPpPT4M8uRqUyR4bjUtSJJM1yh6QSeZk9BEazzoJqPeYeGoiFDZ3LMj2jesbJweQR4caaYuRczK92UGSSqu9zBKmE45a
>>> decoding the message...
>>> message to sign: {"nonce":0,"algorithm":"ed25519","message_type":"gateway-bonding","content":{"sender":"n1ewmme88q22l8syvgshqma02jv0vqrug9zq9dy8","proxy":null,"funds":[{"denom":"unym","amount":"100000000"}],"data":{"gateway":{"host":"62.240.134.189","mix_port":1789,"clients_port":9000,"location":"62.240.134.189","sphinx_key":"FKbuN7mPdoCG9jA3CkAfXxC5X4rHhqeMVtmfRtJ3cFZd","identity_key":"3RoAhR8gEdfBETMjm2vbMFzKddxXDdE9ygBAnJHWqSzD","version":"1.1.13"}}}}
>>> The base58-encoded signature is:
2SPDjLjX4b6XEtkgG7yD8Znsb1xycL1edFvRK4JcVnPsM9k6HXEUUeVS6rswRiYxoj1bMgiRKyPDwiksiuyxu8Xi
  • Copy the resulting signature:
# >>> The base58-encoded signature is:
2SPDjLjX4b6XEtkgG7yD8Znsb1xycL1edFvRK4JcVnPsM9k6HXEUUeVS6rswRiYxoj1bMgiRKyPDwiksiuyxu8Xi
  • And paste it into the wallet nodal, press Next and confirm the transaction.

Paste Signature
This image is just an example, copy-paste your own base58-encoded signature.

  • Your Gateway is now bonded.

You are asked to sign a transaction on bonding so that the Mixnet smart contract is able to map your Nym address to your node. This allows us to create a nonce for each account and defend against replay attacks.

Via the CLI (power users)

If you want to bond your Gateway via the CLI, then check out the relevant section in the Nym CLI docs.

Maintenance

For Gateway upgrade, firewall setup, port configuration, API endpoints, VPS suggestions, automation, WSS setup and more, see the maintenance page

Last change: 2024-02-22, commit: eabb36b