From 7e95e388c1cfde7fb4b3b6f64b70e511421d3c26 Mon Sep 17 00:00:00 2001 From: toml01 <7473870+toml01@users.noreply.github.com> Date: Wed, 6 Nov 2024 17:15:49 +0100 Subject: [PATCH 01/11] threshold network --- .../Fhenix Testnet/Threshold-Network.md | 19 +++++++++++++++++++ 1 file changed, 19 insertions(+) create mode 100644 docs/devdocs/Fhenix Testnet/Threshold-Network.md diff --git a/docs/devdocs/Fhenix Testnet/Threshold-Network.md b/docs/devdocs/Fhenix Testnet/Threshold-Network.md new file mode 100644 index 00000000..e8b4d77a --- /dev/null +++ b/docs/devdocs/Fhenix Testnet/Threshold-Network.md @@ -0,0 +1,19 @@ +--- +sidebar_position: 5 +title: 🔒 Treshold Network +--- + +In principle, a Threshold Network is a cryptographic system designed to enhance security and trust by distributing control and decision-making across multiple parties. In such a network, sensitive operations, such as decryption or signing, require collaboration among a subset of participants, rather than relying on a single entity. + +## Mechanism + +In Fhenix’s Nitrogen testnet, the Threshold Network performs decryption operations. The Threshold Network is currently initialized by a Trusted Dealer (in the future, we plan to eliminate the Trusted Dealer). The Trusted Dealer initially generates a key. Then, the Dealer uses Shamir's Secret Sharing cryptographic algorithm to generate Secret Shares of the key to share among individual members. Each member holds exactly one secret share. To perform a decryption, a Threshold (MPC) Protocol is implemented. The protocol uses a T-out-f-N scheme, meaning that T parties out of a total of N existing parties need to agree and work together to perform a decryption. This mechanism reduces trust assumptions and thereby increases system trustworthiness from the end-users’ perspective. The Threshold Network in Nitrogen requires 3 out of 4 parties to decrypt ciphertexts. + +## Authentication + +A Test Network authentication mechanism is important to differentiate between valid and invalid (or malicious) decryption requests. The authentication mechanism ensures that no party can decrypt data that is not supposed to be decrypted. +Authentication is currently under development and not yet included in the testnet. It will be added in future Fhenix versions. + +## Threshold Network in Nitrogen + +In Nitrogen, the Threshold Network is used by [Security Zone](todo) 0 (which is the default). From 71994610f4c5246cd3a15260003f3889eb4c0f6b Mon Sep 17 00:00:00 2001 From: toml01 <7473870+toml01@users.noreply.github.com> Date: Wed, 6 Nov 2024 17:45:08 +0100 Subject: [PATCH 02/11] threshold network --- docs/devdocs/Fhenix Testnet/Threshold-Network.md | 15 ++++++++++----- 1 file changed, 10 insertions(+), 5 deletions(-) diff --git a/docs/devdocs/Fhenix Testnet/Threshold-Network.md b/docs/devdocs/Fhenix Testnet/Threshold-Network.md index e8b4d77a..74b3ac80 100644 --- a/docs/devdocs/Fhenix Testnet/Threshold-Network.md +++ b/docs/devdocs/Fhenix Testnet/Threshold-Network.md @@ -5,15 +5,20 @@ title: 🔒 Treshold Network In principle, a Threshold Network is a cryptographic system designed to enhance security and trust by distributing control and decision-making across multiple parties. In such a network, sensitive operations, such as decryption or signing, require collaboration among a subset of participants, rather than relying on a single entity. -## Mechanism +## Concept + +In Fhenix’s Nitrogen testnet, the Threshold Network performs decryption operations. The Threshold Network is currently initialized by a Trusted Dealer (in the future, we plan to eliminate the Trusted Dealer). The Trusted Dealer initially generates a key. Then, the Dealer uses Shamir's Secret Sharing cryptographic algorithm to generate Secret Shares of the key to share among individual members. Each member holds exactly one secret share. To perform a decryption, the secret shares are used to perform partial decryptions through a multiparty computation (MPC) protocol. These partial decryptions are then combined into the final plaintext. The protocol uses a T-out-f-N scheme, meaning that T parties out of a total of N existing parties need to agree and work together to perform a decryption. The benefit of this approach is that a single entity (Threshold Network “member”) cannot decrypt the ciphertext, since it is necessary to have a consensus in order to decrypt, which provides the end user with additional protection from malicious actors. + +:::note[Note] +The Threshold Network in Nitrogen requires 3 out of 4 parties to decrypt ciphertexts. +::: -In Fhenix’s Nitrogen testnet, the Threshold Network performs decryption operations. The Threshold Network is currently initialized by a Trusted Dealer (in the future, we plan to eliminate the Trusted Dealer). The Trusted Dealer initially generates a key. Then, the Dealer uses Shamir's Secret Sharing cryptographic algorithm to generate Secret Shares of the key to share among individual members. Each member holds exactly one secret share. To perform a decryption, a Threshold (MPC) Protocol is implemented. The protocol uses a T-out-f-N scheme, meaning that T parties out of a total of N existing parties need to agree and work together to perform a decryption. This mechanism reduces trust assumptions and thereby increases system trustworthiness from the end-users’ perspective. The Threshold Network in Nitrogen requires 3 out of 4 parties to decrypt ciphertexts. ## Authentication -A Test Network authentication mechanism is important to differentiate between valid and invalid (or malicious) decryption requests. The authentication mechanism ensures that no party can decrypt data that is not supposed to be decrypted. -Authentication is currently under development and not yet included in the testnet. It will be added in future Fhenix versions. +A Threshold Network authentication mechanism is important to differentiate between valid and invalid (or malicious) decryption requests. The authentication mechanism ensures that no party can decrypt data that is not supposed to be decrypted. +Authentication is currently under development and not yet included in this testnet. It will be added in future Fhenix versions. ## Threshold Network in Nitrogen -In Nitrogen, the Threshold Network is used by [Security Zone](todo) 0 (which is the default). +In Nitrogen, the Threshold Network is used by [Security Zone](../Writing%20Smart%20Contracts/Security-Zones.md) 0 (which is the default). From 29280bad78878706db986b233d0a6019217c5bb7 Mon Sep 17 00:00:00 2001 From: toml01 <7473870+toml01@users.noreply.github.com> Date: Wed, 6 Nov 2024 20:04:00 +0100 Subject: [PATCH 03/11] sec zones --- .../Writing Smart Contracts/Security-Zones.md | 75 +++++++++++++++++++ 1 file changed, 75 insertions(+) create mode 100644 docs/devdocs/Writing Smart Contracts/Security-Zones.md diff --git a/docs/devdocs/Writing Smart Contracts/Security-Zones.md b/docs/devdocs/Writing Smart Contracts/Security-Zones.md new file mode 100644 index 00000000..77fb6d48 --- /dev/null +++ b/docs/devdocs/Writing Smart Contracts/Security-Zones.md @@ -0,0 +1,75 @@ +--- +sidebar_position: 200 +title: 🛡️ Security Zones +--- + +## Why we need Security Zones + +In various use cases, scenarios, and applications, different levels of security, trust, and performance may be required. However, it is preferable to have everything operate within a single blockchain, as deploying across multiple networks (blockchains) is cumbersome and has its own unique challenges, such as bridging, coordination and more. Furthermore, different parts of a single application may require unique combinations of various configurations. Settling on a single configuration would typically compromise overall security and performance—leaving the application only as secure as its weakest or as fast as its slowest component. + +## What are Security Zones + +Fhenix developed Security Zones to address this problem. With Fhenix, multiple encryption key sets (i.e., Security Zones) can coexist on a single network. Previously, we were limited to optimizing a single cryptographic key set to meet average security and performance needs. Now, with multiple Security Zones, Fhenix can tailor encryption configurations to specific use cases, eliminating the need to compromise on security, performance, or trust. + +For example, highly sensitive information can be protected with maximum security guarantees by using a Threshold Network for encryption. For less sensitive data, a local key set controlled by the sequencer may suffice, offering better performance with slightly lower but acceptable trust assumptions. Similarly, some applications may prefer an encryption scheme that specializes in small ciphertext sizes but slower computation, while apps may need to optimize for transaction price above everything else. Security zones will allow having different schemes with different configurations, all under one roof (or rather, one network - Fhenix). + +:::warning[Important Dev Hint] +An important nuance of Security Zones is that two ciphertexts that are encrypted using two different security zones are not compatible, since every Zone represents a different set of **FHE keys**. For example, we cannot compute enc(a) + enc(b), where a and b were encrypted using different Zones. +::: +:::info[Note] +Currently, creating new Security Zones is not dynamically supported, which means that users cannot implement this feature on their own. Rather, they must choose between the existing, pre-generated Security Zones available with Nitrogen on launch. However, we may add a dynamic Security Zones feature in the future. +::: + +## Security Zone in Nitrogen + +In Nitrogen, we introduce two Security Zones to demonstrate the concept: + +### Threshold Network (zone 0 - default) +This zone uses a Threshold Network. The benefit of this approach is that it provides the end user with additional protection from malicious actors. For further reading on the Threshold network, [see here](../Fhenix%20Testnet/Threshold-Network.md). + +### Local (zone 1) +This zone uses a local key set held by the sequencer (this is how previous Fhenix testnets handled the decryption key). The intention of this zone is to offer faster decryption but require more trust from the user with the tradeoff of assuming a trusted sequencer. + +:::info[Dev Hint] +Whether you are porting a contract from a previous Fhenix version, or creating a new one - you don't have to do anything in particular to use the Threshold Network. Security Zone 0 is the default one - meaning that you don't need to modify your code to use it! See the code example below 👇 +::: + +## Code Example + +```sol title="Contract.sol" +function addSecZone0(n1 inEuint32, n2 inEuint32) { + euint32 first = FHE.asEuint32(n1); // This implicitly uses Security Zone 0 + euint32 second = FHE.asEuint32(n2, 0); // This also uses Security Zone 0 + + euint32 result = first + second; // `result` will be marked 'security zone 0' automatically +} + +function addSecZone1(n1 inEuint32, n2 inEuint32) { + euint32 first = FHE.asEuint32(n1, 1); // To use a non-default SZ, you have to be explicit + euint32 second = FHE.asEuint32(n2, 1); + + euint32 result = first + second; // `result` will be marked 'security zone 1' automatically +} +``` + +```js title="index.js" +const client = new FhenixClient({ provider }); + +let first = await client.encrypt_uint32(5); // This implicitly uses Security Zone 0 +let second = await client.encrypt_uint32(1332, 0); // This implicitly uses Security Zone 0 +await contract.addSecZone0(first, second); + +first = await client.encrypt_uint32(5, 1); // To use a non-default SZ, you have to be explicit +econd = await client.encrypt_uint32(1332, 1); +await contract.addSecZone1(first, second); +``` + +## When can I specify a Security Zone? + +In **Solidity**, you will notice that you can specify a Security Zone only when calling functions that are creating `eunitX` types, meaning in `FHE.asEuintX()` functions. This is because the `euintX` types include metadata about the Security Zone that the ciphertext was encrypted with. + +In **fhenix.js**, you can specify a Security Zone only in the `encrypt()` functions because you need to encrypt the data with the desired Security Zone's public key. + +:::info[Note] +The current security zones are implemented to demonstrate the concept with tradeoffs between security and performance. However, they are not indicative of a production deployment. +::: \ No newline at end of file From a87317e68cb4a0d7c298e988780780193d8f91a4 Mon Sep 17 00:00:00 2001 From: toml01 <7473870+toml01@users.noreply.github.com> Date: Wed, 6 Nov 2024 20:31:54 +0100 Subject: [PATCH 04/11] remove mock randomness limitation --- docs/devdocs/Fhenix Testnet/Details/Limitations.md | 6 ------ 1 file changed, 6 deletions(-) diff --git a/docs/devdocs/Fhenix Testnet/Details/Limitations.md b/docs/devdocs/Fhenix Testnet/Details/Limitations.md index 38465482..119fb2d8 100644 --- a/docs/devdocs/Fhenix Testnet/Details/Limitations.md +++ b/docs/devdocs/Fhenix Testnet/Details/Limitations.md @@ -14,12 +14,6 @@ real sensitive data or private keys on the testnet. The current iteration of the network does not include multiple components (such as input knowledge proofs, threshold decryption, execution proofs, etc.) that are critical for the security of data and network keys. These features will be added iteratively as we move towards full release - this should be obvious, but please **do not store any valuable information on the network as long as it is in the testnet phase**. -## Randomness - -Randomness as a service is planned as a future addition. Until we can guarantee a secure source of randomness, we do not -want to make such a function available as a network service. For demos and development that require a source of randomness, we encourage -the use of external oracles, or usage of a [mock random number generator](../../Writing%20Smart%20Contracts/Useful-Tips.md#randomness). - ## Gas Costs All gas costs are subject to change, and are being evaluated for optimization. The current gas costs are not final, and may change. From feb249e0812df148499b64584e1679e13fc2bcf8 Mon Sep 17 00:00:00 2001 From: Tom Langer <7473870+toml01@users.noreply.github.com> Date: Wed, 6 Nov 2024 18:54:19 +0100 Subject: [PATCH 05/11] Update docusaurus.config.ts --- docusaurus.config.ts | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docusaurus.config.ts b/docusaurus.config.ts index c3c9e8e5..1d7b890a 100644 --- a/docusaurus.config.ts +++ b/docusaurus.config.ts @@ -35,10 +35,10 @@ const config: Config = { 'classic', { docs: { - lastVersion: 'current', + lastVersion: 'Helium', versions: { current: { - label: 'Helium', + label: 'Nitrogen', path: '.' } }, From fd529260bb11d053d286dabf5221d510a0f37368 Mon Sep 17 00:00:00 2001 From: toml01 <7473870+toml01@users.noreply.github.com> Date: Wed, 6 Nov 2024 20:31:00 +0100 Subject: [PATCH 06/11] fix paths --- docusaurus.config.ts | 8 +++++++- 1 file changed, 7 insertions(+), 1 deletion(-) diff --git a/docusaurus.config.ts b/docusaurus.config.ts index 1d7b890a..4d85de63 100644 --- a/docusaurus.config.ts +++ b/docusaurus.config.ts @@ -39,7 +39,13 @@ const config: Config = { versions: { current: { label: 'Nitrogen', - path: '.' + path: 'nitrogen', + banner: 'unreleased', + badge: true + }, + Helium: { + label: 'Helium', + badge: false } }, sidebarPath: './sidebars.ts', From 0ef6544be153c1b692829a15523676de0a313d05 Mon Sep 17 00:00:00 2001 From: toml01 <7473870+toml01@users.noreply.github.com> Date: Wed, 6 Nov 2024 20:40:39 +0100 Subject: [PATCH 07/11] whoopsie --- src/components/AdditionalFeatures/index.tsx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/components/AdditionalFeatures/index.tsx b/src/components/AdditionalFeatures/index.tsx index 9a36d342..20f574f0 100644 --- a/src/components/AdditionalFeatures/index.tsx +++ b/src/components/AdditionalFeatures/index.tsx @@ -8,7 +8,7 @@ import Link from '@docusaurus/Link'; export function GettingStartedFrame(): JSX.Element { const { colorMode } = useColorMode(); - const iframeSrc = "https://getting-started.nitrogen.fhenix.zone" + (colorMode === 'light' ? "?isLight=1" : ""); + const iframeSrc = "https://getting-started.helium.fhenix.zone" + (colorMode === 'light' ? "?isLight=1" : ""); return (
From 3bf4663fab45fc8d91b667a2327161e107cc66fe Mon Sep 17 00:00:00 2001 From: toml01 <7473870+toml01@users.noreply.github.com> Date: Wed, 6 Nov 2024 20:41:57 +0100 Subject: [PATCH 08/11] nitro getting started --- src/components/AdditionalFeatures/index.tsx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/components/AdditionalFeatures/index.tsx b/src/components/AdditionalFeatures/index.tsx index 20f574f0..9a36d342 100644 --- a/src/components/AdditionalFeatures/index.tsx +++ b/src/components/AdditionalFeatures/index.tsx @@ -8,7 +8,7 @@ import Link from '@docusaurus/Link'; export function GettingStartedFrame(): JSX.Element { const { colorMode } = useColorMode(); - const iframeSrc = "https://getting-started.helium.fhenix.zone" + (colorMode === 'light' ? "?isLight=1" : ""); + const iframeSrc = "https://getting-started.nitrogen.fhenix.zone" + (colorMode === 'light' ? "?isLight=1" : ""); return (
From 92b6612386f8ea494564f498a88d67c2c5d3dc30 Mon Sep 17 00:00:00 2001 From: Milan Sedivy Date: Sun, 10 Nov 2024 19:17:18 +0200 Subject: [PATCH 09/11] Add changelog --- docs/devdocs/Fhenix Testnet/Details/Changelog.md | 7 ++++++- 1 file changed, 6 insertions(+), 1 deletion(-) diff --git a/docs/devdocs/Fhenix Testnet/Details/Changelog.md b/docs/devdocs/Fhenix Testnet/Details/Changelog.md index fb1fe895..ed066f64 100644 --- a/docs/devdocs/Fhenix Testnet/Details/Changelog.md +++ b/docs/devdocs/Fhenix Testnet/Details/Changelog.md @@ -7,7 +7,12 @@ Here you can find a list of changes between different versions of the Fhenix Tes ### Nitrogen -TBD +- Fixed casts between eaddress and different euints +- Introduced Security zones +- Introduced Threshold Network as default for security zone 0 +- Introduced Parallel decryptions +- Introduced new precompiles for operations with encrypted uints: random, rotate right, rotate left, square +- General bug fixes and stability improvements ### Helium From b1e72ee9869b4d4ed916c19b05b86b67d6e596fb Mon Sep 17 00:00:00 2001 From: toml01 <7473870+toml01@users.noreply.github.com> Date: Wed, 13 Nov 2024 16:27:50 +0100 Subject: [PATCH 10/11] parallel decryptions --- .../Parallel-Decryptions.md | 55 +++++++++++++++++++ 1 file changed, 55 insertions(+) create mode 100644 docs/devdocs/Writing Smart Contracts/Parallel-Decryptions.md diff --git a/docs/devdocs/Writing Smart Contracts/Parallel-Decryptions.md b/docs/devdocs/Writing Smart Contracts/Parallel-Decryptions.md new file mode 100644 index 00000000..84158a65 --- /dev/null +++ b/docs/devdocs/Writing Smart Contracts/Parallel-Decryptions.md @@ -0,0 +1,55 @@ +--- +sidebar_position: 300 +title: 🔀 Parallel Decryptions +--- + +In Fully Homomorphic Encryption (FHE) schemes, decryption can be slow and computationally expensive, especially when using a [Threshold Network](../Fhenix%20Testnet/Threshold-Network.md). Additionally, since a Threshold Network functions as a sort of network in itself and serves as an oracle for the main blockchain, it cannot perform decryption synchronously, since decryptions may take too long to be practical or the Threshold Network might be busy or unavailable. +To address this issue, Nitrogen introduces Parallel Decryptions. This feature performs asynchronous decryption while providing the experience of synchronous decryption. Instead of using callbacks, as in traditional oracle-based protocols, Fhenix allows developers to write code normally, without needing to be concerned that a decryption request is being sent to an external component. + +### Better developer and user experience + +This approach improves the whole experience in two key ways: +* Developers can write clean, cohesive code without worrying about asynchronous decryption. +* Users and dApps avoid the need for multiple transactions to handle decryption callbacks. + + +```solidity + euint32 encrypted; + uint32 decrypted; + + function decryptInFhenix() public { + // Beginning of function logic .. + + decrypted = FHE.decrypt(encrypted); + + // Continue of function logic.. + } + + // -------- Otherwise.. -------- + // (*simplified* example of callback-based decryption) + + function requestDecrypt() public { + // Beginning of function logic .. + FHE.decryptWithCallback(encrypted); + } + + // This function will be called after some time in a different TX + function receiveDecryptCallback(uint32 result) public { + decrypted = result; + // Continue of function logic.. + } +``` + +As shown in the example above, Fhenix's parallel decryption approach allows for clean, straightforward code that reads like normal synchronous operations. Developers can write their business logic in a natural flow, with decryption seamlessly integrated into their functions. This makes the code more maintainable and easier to understand, while Fhenix handles all the complexity of asynchronous decryption behind the scenes. + +### In depth + +Behind the scenes, decryption requests are detected in transactions and sent to the appropriate decrypting party (whether Threshold Network or local decryptor). While these decryption requests are processed, the transactions are pushed to a special queue (a sort of tx-mempool). After all the decryption requests for a transaction are completed, the transaction is included in a block and executed. + +:::note +Since Fhenix is an L2 solution with a sequencer, no traditional mempool is in place. As a result, there may be a slight delay before the transaction is included and executed in a block, potentially leading to a timeout of the original transaction (tx) receipt. To handle this, periodically query the tx hash in your UI. +::: + +```javascript + +``` From 1de76e46c28891e78760364a4934e50c31204ae4 Mon Sep 17 00:00:00 2001 From: toml01 <7473870+toml01@users.noreply.github.com> Date: Wed, 13 Nov 2024 16:27:57 +0100 Subject: [PATCH 11/11] code example --- .../Parallel-Decryptions.md | 53 ++++++++++++++++++- 1 file changed, 52 insertions(+), 1 deletion(-) diff --git a/docs/devdocs/Writing Smart Contracts/Parallel-Decryptions.md b/docs/devdocs/Writing Smart Contracts/Parallel-Decryptions.md index 84158a65..ba56ee09 100644 --- a/docs/devdocs/Writing Smart Contracts/Parallel-Decryptions.md +++ b/docs/devdocs/Writing Smart Contracts/Parallel-Decryptions.md @@ -51,5 +51,56 @@ Since Fhenix is an L2 solution with a sequencer, no traditional mempool is in pl ::: ```javascript - +// Example of handling parallel decryption transactions in a frontend application +async function handleDecryptTransaction(contract, methodName, ...args) { + try { + // Send the transaction that includes decryption + const tx = await contract[methodName](...args); + + // Get initial transaction receipt + let receipt = await tx.wait(); + + // If the receipt times out, periodically check the transaction status + if (!receipt || receipt.status === 'pending') { + receipt = await pollTransactionStatus(tx.hash); + } + + return receipt; + } catch (error) { + console.error('Transaction failed:', error); + throw error; + } +} + +// Helper function to poll transaction status +async function pollTransactionStatus(txHash, maxAttempts = 20) { + let attempts = 0; + + while (attempts < maxAttempts) { + const receipt = await provider.getTransactionReceipt(txHash); + + if (receipt && receipt.status === 1) { + return receipt; + } + + // Wait 3 seconds before next attempt + await new Promise(resolve => setTimeout(resolve, 3000)); + attempts++; + } + + throw new Error('Transaction timeout: Decryption taking longer than expected'); +} + +// Usage example +const contract = new ethers.Contract(address, abi, signer); + +try { + const receipt = await handleDecryptTransaction( + contract, + 'decryptInFhenix' + ); + console.log('Transaction completed:', receipt); +} catch (error) { + console.log('Failed to process decryption:', error); +} ```