How does Nyx work?

​

Summary

This doc will help you understand how Nyx works. It has overviews of core Nyx private account operations:

• Account creation, including where your private account keys live.
• Login.
• Transactions.

This doc has some technical terms and assumes you have a basic familiarity with blockchains and web apps. For a more technical deep-dive into how Nyx private accounts work, see our Technical Overview. For deep dives in to specific Nyx actions see here.

---

​

Account creation

​

Summary

At a high level, you sign a message with your Ethereum wallet to prove you own your connected Ethereum account, which will be linked to one and only one private Nyx account. You then create a passkey that will be used to encrypt your private account data in your browser before it’s sent to the Nyx backend (stored there in encrypted form so you can access Nyx across devices and browsers). Finally, you sign a message with your Ethereum wallet to authorize your private account creation transaction. The transaction is executed on your device and only a zero-knowledge proof is sent to the Aztec network. These are the steps involved in doing the above:

1. You sign an offchain message with your Ethereum wallet. Every connected public account is associated with one Nyx wallet ID, which is a hash of the Ethereum address.
2. Your signature is used to generate a zero-knowledge proof in your browser. The proof shows that you control the Ethereum address associated with a Nyx account ID - in this case a new one for the account you’re creating - without revealing to us what your Ethereum address actually is (learn more in our Technical Overview doc).
3. The proof is sent to our backend (not the signature), which attempts to validate the proof.
4. If the proof is valid, the Nyx app prompts you to create an initial passkey that will be enrolled for your account. This passkey will be used to encrypt and decrypt your private account data in your browser. Please make multiple passkeys and back up your account so that you don’t lose access to your assets (learn more).
5. If a passkey is successfully created, your Nyx private account secret is generated on your device. This secret is encrypted with your passkey and then stored on our backend so you can use Nyx across devices and browsers. Later, when you log back into Nyx, the Nyx app fetches your encrypted data from our backend and uses one of your enrolled passkeys to decrypt it on your browser so you can view and use your private account assets.
6. You sign a final offchain message with your Ethereum wallet to authorize the creation of your private account. All of your private account transactions are authorized by offchain messages signed by your public account (see our technical overview of the relationship between your public and private accounts here).
7. The transaction is executed locally on your device. Then, a zero-knowledge proof is generated that proves the transaction is valid and approved by the new account owner. This proof is sent to the Aztec network.
8. Aztec sequencers validate the proof, apply the transaction effects, and include the transaction in a block.

​

Diagram

​

Where your private account keys live

As covered above, your private account keys are derived on your device using your private account secret, each time you use Nyx. When you create an account, your private account secret is created on your device. It is encrypted on your device using your initial passkey and stored in encrypted form on our backend to support your use of Nyx across devices and browsers (learn more). Whenever you log into Nyx, a passkey enrolled for your account is used to decrypt the secret in your browser so that your private account’s privacy keys can be derived in your browser again and you can view and use your private account. The privacy keys only live temporarily in your browser when you are using Nyx.

---

​

Login

​

Summary

At a high level, login involves first proving that you control an Ethereum address that controls a Nyx private account. Then, fetching and decrypting the encrypted account data for that private account so you can view and use it. These are the steps involved in doing the above:

1. You sign an offchain message with your Ethereum wallet. Every connected public account is associated with a Nyx wallet ID, which is a hash of the Ethereum address.
2. Your signature is used to generate a zero-knowledge proof in your browser. The proof shows that you control the Ethereum address associated with a Nyx account ID without revealing what your Ethereum address actually is (learn more in our Technical Overview doc).
3. The proof is sent to our backend (not the signature), which attempts to validate the proof.
4. If the proof is valid, the Nyx app prompts you for a passkey you’ve enrolled for your account.
5. If a passkey is found and verified, your Nyx app session is verified and the app asks the backend for your encrypted private account data.
6. Your private account data is decrypted in your browser. Now you, and only you, can view and use your private account.

Your account state - contacts list and pending transaction claims - is encrypted on your device and synced to our backend. It is always up to date whenever you log into your account (on the same or different device) and repeat the process above. Privacy and security addition to #3 above: We do not store a mapping from your Ethereum address to your Aztec private address, only a mapping from a hash of your Ethereum address to its associated encrypted private account data. We believe this is safe because once you send funds into a Nyx smart contract when you fund your private account, you publicly reveal that your Ethereum address has a Nyx account. Additionally, the encrypted private account data associated with an Ethereum address can only be decrypted and understood by the owner of that Ethereum address as they have a Nyx passkey used to encrypt the data (learn more).

​

Diagram

---

​

Private account transactions

​

Summary

At a high level, you sign one or two offline messages with your Ethereum wallet to approve the private account transaction. Then, the transaction is executed on your device and only zero-knowledge proofs and encrypted data about your asset moving are sent to the Aztec network. These are the steps involved in doing the above:

1. You use the Nyx app to initiate a transaction (e.g. deposit 20 USDC into Aave).
2. For certain transactions, e.g. Earn and Send to Ethereum, you sign an offchain message with your Ethereum wallet to authorize a smart contract to update another smart contract’s state on your behalf. This is similar to approvals / allowances in Ethereum contracts, except that on Aztec, these only require extra signatures to be verified together with the transaction signature, as opposed to separate approval transactions to be executed beforehand.
3. You sign an offchain message with your Ethereum wallet. This signature approves the overall transaction. It is also used in proof generation to prove that the Nyx private account authorized the action. For a technical summary of how your Ethereum wallet governs the actions of your private account, see here.
4. The transaction is executed locally on your device. Then, a zero-knowledge proof is generated that proves the transaction is valid and approved by the asset owner. This proof is sent to the Aztec network. The private state involved in the transaction (e.g. the 20 USDC you transferred to someone else) will never be revealed publicly, only the proof. You can learn more in the Aztec Network developer docs.
5. Aztec sequencers validate the proof, apply the transaction effects, and include the transaction in a block.

​

Diagram

---

​

The main elements of Nyx

These are the main elements involved in Nyx account operations.

• Your public account: Authorizes private account actions through offchain message signing.
• Your private Nyx account on the Aztec blockchain: The Aztec blockchain was built to enable private account balances and actions. This is where your private account lives, with a balance and actions invisible to everyone else (including us).
• The Nyx app frontend (in your browser): This is where you view your private account and initiate private actions. When you initiate a private transaction, the following happens: your Ethereum wallet signs an offchain message approving the transaction and then a zero knowledge proof containing this and the transaction information is generated on your browser and submitted to the Aztec blockchain.
• The Nyx app backend: Stores a limited amount of information - such as your contacts, account secret, and pending asset claim secrets - in an encrypted form we cannot read. This is so that you can use Nyx across devices and browsers, and so that you do not have the burden of having to store things like your contacts.
• Your passkey(s): This is used in your browser to encrypt information sent to our backend (and decrypt information loaded from our backend). This is how we ensure that only you can view and use your private account.
• Smart contracts: Nyx smart contracts on the Ethereum and Aztec blockchains (along with Aztec, Aave, and other smart contracts). These facilitate Nyx actions.
• Nyx relayers: The relayer’s purpose is to monitor the Aztec network for certain events (messages), and then call the corresponding Ethereum contracts to finalize those message operations on Ethereum. One main benefit from this pattern is that the relayer is shown as the sender and there is no link to your public account that approved the action in Nyx. Examples include depositing into, and redeeming from Aave, which are anonymous actions you can take using Nyx.

The first five elements are shown in the images above. For a look at how smart contracts and relayers fit in, see our diagrams of how Nyx features work (e.g. private Earn)