Nyx Blockchain

Nyx is a Cosmos SDK blockchain. The blockchain plays a supporting but fundamental role in the mixnet: the NYM token used to incentivise node operators is one of two native tokens of the chain, and the chain is where the Mixnet, Vesting and zk-nym smart contracts are deployed.

Validators

Validators secure the Nyx blockchain via Proof of Stake consensus. The Nyx blockchain records the ledger of NYM transactions and executes the smart contracts for distributing NYM rewards. The Nyx validators are run via the nyxd binary (codebase (opens in a new tab)), maintaining a CosmWasm- and IBC-enabled blockchain.

Detailed info on Nyx Validators and token flow can be found in Nym Reward Sharing for Mixnets document (opens in a new tab) in section 2.3 and 2.4 and in the Nym Whitepaper (opens in a new tab) section 3.1.

NymAPI

The NymAPI is a binary operated by a subset of the Nyx validator set. This binary can be run in several different modes, and has two main bits of functionality:

• Network monitoring (calculating the routing score of Mixnet nodes)
• Generation and validation of zk-nyms, a combination of the Coconut Selective Disclosure Credential and Offline Ecash schemes.

This is important for both the proper decentralisation of the network uptime calculation and, more pressingly, enabling the NymVPN to utilise privacy preserving payments.

Smart Contracts

The Nyx blockchain is CosmWasm (opens in a new tab) enabled.

The following contracts are deployed to the chain:

• The Mixnet contract which manages the network topology of the mixnet and tracks delegations & rewarding.
• The Vesting contract which manages NYM token vesting functionality. This will soon be deprecated.
• The Quorum Multisig used by the subset of the Nyx Validators that generate and validate zk-nyms to manage reward payouts for nodes.
• The zk-nym contract which keeps track of NYM deposits used as payment for zk-nym generation.

The addresses of deployed smart contracts can be found in the network-defaults (opens in a new tab) directory of the codebase alongside other network default values.

Interacting with Contracts

You can use the API docs to see how you can interact with the contracts. The NymAPI in particular has multiple endpoints to query the Mixnet state, topology, and various zk-Nym-related endpoints.

Mixnet Contract

The Mixnet smart contract is a core piece of the Nym system, functioning as the mixnet directory and keeping track of delegations and rewards: the core functionality required by an incentivised mixnet. You can find the code and build instructions here (opens in a new tab).

Having a smart contract act as a decentralised topology directory for clients connecting to the Mixnet allows us to mitigate several possible attacks which systems relying on P2P networking are susceptible to. See Why Nym is not P2P.

The Mixnet contract has multiple functions:

• Storing bonded mix node and gateway information (and removing this on unbonding).
• Providing the network-topology to the (cached) Validator API endpoint used by clients on startup for routing information.
• Storing delegation and bond amounts.
• Storing reward amounts.

Vesting Contract

The vesting contract allows for the creation of vesting accounts, allowing NYM tokens to vest over time, and for users to minimally interact with the Mixnet using their unvested tokens. You can find the code and build instructions here (opens in a new tab).

The Vesting contract has multiple functions:

• Creating and storing vesting NYM token vesting accounts.
• Interacting with the Mixnet using vesting (i.e. non-transferable) tokens, allowing users to delegate their unvested tokens.

Multisig Contract

The multisig contract used by the NymAPI Quroum - a subset of the Nyx Validator set taking on the additional work of generating and validating zk-nyms - to execute certain actions in the zk-nym contract.

It is essentially an instance of the canonical (opens in a new tab) cw3-flex-multisig using the cw4-group contract, with one minor change to restrict the addresses allowed to submit proposals.

Zk-Nym Contract

This contract is a hub for zk-nym related actions, being called by either:

• The zk-nym payment backend
• Nodes running in Gateway mode
• The multisig contract

The following functionality is controlled by the multisig contract:

• Getting the list of blacklisted addresses who have tried to double-spend a zk-nym.
• Proposing to add an address to the blacklist.
• Executing an open proposal.
• The the zk-nym payment backend can deposit funds with information used to identify the deposit.
• Finally, nodes running as Gateways can create a proposal to redeem a set of spend zk-nyms.