this is the best

docs/devdocs/Writing Smart Contracts/Glossary-and-Abbreviations.md

@@ -0,0 +1,34 @@
+---
+sidebar_position: 12
+title: Glossary of Special Terms and Abbreviations
+description: The terms, expressions and abbreviations that appear in the Fhenix documentation have the meaning and significance as defined and explained in this Glossary
+---
+
+The terms, expressions and abbreviations that appear in the Fhenix documentation have the meaning and significance as defined and explained in this Glossary. Note that specific terms in this Glossary may have a slightly different meaning and usage than identical or similar terms used in the technical literature of other companies or organizations.
+
+<table>
+<tr><th colspan="2"> Supported types </th></tr>
+<tr><td>    
+
+| Term/Abbreviation       | Definition |
+|------------|----------|
+| Abstract contract | In Solidity, an abstract contract is a contract that cannot be directly deployed on the blockchain. It serves as a blueprint for other contracts to inherit its functionalities |
+| Ciphertext | Encrypted data |
+| EIP-712 | A standard for adding signing capabilities to Ethereum transactions |
+| FHE | Fully Homomorphic Encryption |
+| Fully deterministic | In a fully deterministic system, the same inputs will always produce the same outputs, making the system reliable and predictable. This is generally considered beneficial for security and consistency. In contrast, if the system is not fully deterministic, there can be variations in the output even with the same input, due to factors like network delays, node failures, or other disruptions |
+| Fully Homomorphic Encryption (FHE) | A cryptographic technology that enables processing encrypted data without decrypting it |
+| MEV | Maximal Extractable Value |
+| Maximal Extractable Value | Maximal Extractable Value (MEV) techniques refer to strategies used by participants in blockchain networks, especially in decentralized finance (DeFi) systems, to extract the maximum possible profit from transaction ordering, inclusion, and exclusion within a block. MEV is essentially the profit that can be made by reordering, including, or excluding transactions in a block |
+| NaCL | Networking and Cryptography library |
+| Networking and Cryptography library (NaCl) | A public domain, high-speed software library for network communication, encryption, decryption, signatures, etc. developed by Daniel Bernstein |
+| Permission | That part of a permit that supplies proof that callers are who they say they are. A permission contains the signature and its corresponding public key. |
+| Permissioned contract | A permissioned contract is a sort of blueprint on which developers build to provide the core functionality of access control with EIP-712 signatures. Permissioned contracts lack specific implementations for functions. As such, a permissioned contract is a type of abstract contract |
+| Permit | A mechanism that allows the contract to verify cryptographically the identity of callers, ensuring that they are who they claim to be. In Fhenix, a permit is a signed message that contains the caller's public key, which the contract can use to verify the caller |
+| Plaintext | Unencrypted data |
+| Sealed Box Encryption | A feature of NaCl. The user provides a public key to the contract during a view function call, which the contract then uses to encrypt the data so that only the owner of the private key associated with the provided public key can decrypt it |
+| Select function (selector) | A selector is a function that accepts a control and two branches, and returns the result of the branch that corresponds to the condition. A selector operates like a traffic signal that decides which traffic to let through based on the color of the traffic light (control signal). In Fhenix this concept is implemented by calling a select function. The select function accepts a condition and two inputs and returns the input that corresponds to the state of the condition |
+| Threshold network | A threshold network requires that a predefined number of nodes must collaborate to successfully decrypt the data |
+| Trivial encryption | In the context of Fully Homomorphic Encryption (FHE), trivial encryption refers to a simplified and deterministic form of encryption. Trivial encryption always produces the same ciphertext for a given plaintext. This is in contrast to standard FHE, where the same plaintext encrypted multiple times typically results in different ciphertexts due to the incorporation of random elements for added security. The process is straightforward and involves a direct mapping of plaintext to ciphertext without the complex operations or randomness that characterize normal FHE encryption |
+
+</tr></td>

docs/devdocs/Writing Smart Contracts/Permissions.md

@@ -6,31 +6,33 @@ description: Managing access to sensitive data & Permissioned contracts
 
 ## Overview
 
-The `Permissioned` contract is an abstract Solidity contract that leverages EIP-712 standard signatures to enforce access controls. It's designed to be used by developers who require signature verification to restrict access to certain contract functions. While it can be used to restrict any kind of function, it's particularly useful for creating access-controlled view functions where data should only be visible to entities with a verified signature.
+A `Permissioned` contract is an abstract Solidity contract that leverages EIP-712-standard signatures to enforce access controls. It is designed to be used by Solidity developers who require signature verification to restrict access to certain contract functions. `Permissioned` contracts can be used to restrict any kind of function. However, it is especially useful for creating an access-controlled view function, where data can only be visible to entities that present a verified signature.
 
 ## Use Cases
 
-One of the common use cases for such access control is in scenarios where sensitive information must be retrieved from a contract but should not be publicly accessible. For example, a contract managing private user data may implement view functions which require a signature to confirm the identity of the requester. This ensures that only the user or an authorized party can access that user's data.
+A typical use case of this access control mechanism arises when sensitive information that resides within a contract requires restricted public accessibility. For example, consider a contract managing private user data. This contract can implement view functions that require a signature to verify the requester’s identity. This approach ensures that only the authorized user or designated party can access that user's relevant data.
 
-## How to Use
+## Implementation​
 
-To utilize the `Permissioned` contract, you would inherit it in your own contract and apply the custom modifiers to the functions you want to protect. To implement access-controlled view functions, follow these steps:
+Implementing a `Permissioned` contract enables integrating access control functionalities within an application. In terms of coding, this involves deriving a new contract from the Permissioned contract (inheritance). Subsequently, custom modifiers can be applied to specific functions within the derived contract to enforce access control. These modifiers verify the presence of a valid signature using EIP-712 standards before granting access to the protected functions.
 
-1. Define a view function in your contract. For example, to retrieve sensitive data:
+To implement access-controlled view functions, do the following:
+
+1. Define the view function in your contract. For example, the following code snippet retrieves sensitive data:
 
     ```javascript
     function getSensitiveData(Permission calldata perm) public view onlySender(perm) returns (string memory) {
         // Logic to return sensitive data
     }
     ```
 
-2. Off-chain, the user generates a signature over their request using EIP-712 signed with their private key. This process typically involves structured data that lists the types of variables involved and their values. The result is a signature that proves the user consents to the requested operation.
+2. Off-chain, users generate a signature for their requests through the EIP-712 protocol and signed with their private key. This process typically involves structured data that lists the types of variables involved and their values. The result is a signature that can prove that the user consents to the requested operation.
 
-3. Call the view function with the generated signature as one of the parameters. Only if the signature is verified and corresponds to the `msg.sender` will the view function execute and return the sensitive data.
+3. Call the view function with the generated signature as one of the parameters. The view function executes and returns the sensitive data only when the signature is verified and corresponds to `msg.sender`.
 
 ## Example Scenario 1
 
-Imagine a contract holding medical records. You want to create a secure method for patients to view their records:
+Consider a contract that holds medical records. The following code snippet creates a secure method for patients to view their records:
 
 ```javascript
 pragma solidity ^0.8.20;
@@ -47,10 +49,10 @@ contract MedicalRecords is Permissioned {
 }
 ```
 
-The patient, after obtaining the appropriate signature using their private key, would submit it along with their request to view their records. The contract verifies the signature against the caller's address, and if it matches, returns the patient’s medical record.
+After obtaining the appropriate signature using their private key, the patient submits it together with their request to view their records. The contract verifies the signature against the caller's address, and if it matches, returns the patient’s medical record.
 
-:::danger
-In this example we are just showcasing the usage of permissions. `string` and `address` are still public data types and can be read directly from the chain!
+:::Vulnerability
+We have provided this code snippet to illustrate how permissions are used. This is not a complete implementation. Note that in this code `string` and `address` are public data types and can be read directly from the chain! Therefore, a full implementation of the code would have to handle this vulnerability.
 :::
 
 ## Example Scenario 2
@@ -73,9 +75,9 @@ contract Test {
 }
 ```
 
-## Notes
+## Best Practices​
 
-- Permissioned view functions only allow access upon successful signature verification, enhancing contract's data privacy.
-- Users need to protect their private keys used to generate EIP-712 signatures to maintain the integrity of the access control system.
-- Developers must integrate off-chain EIP-712 compliant signing processes to ensure users can generate valid signatures for contract interactions.
+- Implement permissioned view functions to allow access upon successful signature verification to enhance contract data privacy.
+- Emphasize that users need to protect the private keys that they use to generate EIP-712 signatures to maintain the integrity of the access control system.
+- Developers must integrate off-chain EIP-712 compliant signing processes to ensure users can generate valid signatures for smart contract interactions.
 - EIP-712 signatures provide strong assurances of user intention, making them ideal for sensitive operations.

docs/devdocs/Writing Smart Contracts/Select.md

@@ -4,9 +4,9 @@ title: 🌴 Select vs If...else
 description: Why if..else is not possible and what are the alternatives
 ---
 
-Writing code with Fully Homomorphic Encryption (FHE) introduces a fundamental shift in how we handle conditionals or branches in our code. As you already know, with FHE, we're operating on encrypted data. This means we can't use typical `if...else` branching structures, because we don't have visibility into the actual values we're comparing.
+Writing code with Fully Homomorphic Encryption (FHE) introduces a fundamental shift in how we generally handle conditional branching in code. Since FHE operates on encrypted data, typical `if...else` branching structures cannot be used, because actual values are not visible.
 
-For example, this will not work:
+For example, the following code does not work:
 
 ```Javascript
 euint32 a = FHE.asEuint32(10);
@@ -18,22 +18,21 @@ if (a.lt(b)) {
 }
 ```
 
-When writing Solidity contracts for our blockchain, you'll need to consider all possible branches of a conditional at the same time. It's somewhat akin to writing constant-time cryptographic code, where you want to avoid timing attacks that could leak information about secret data.
+When writing Solidity contracts for the Fhenix blockchain, it is necessary to consider all possible branches of a conditional at the same time. This is somewhat akin to writing constant-time cryptographic code, where the objective is to avoid timing attacks that could leak information about secret data.
 
-To handle these conditionals, we use a concept called a "selector".
-A selector is a function that takes in a control and two branches, and returns the result of the branch that corresponds to the condition. A selector is like a traffic signal that decides which traffic to let through based on the color of the light (control signal).
+To handle conditional branching, we use a special type of function called a "selector." A selector is a function that accepts a control and two branches, and returns the result of the branch that corresponds to the condition. A selector operates like a traffic signal that decides which traffic to let through based on the color of the traffic light (control signal).
 
-In Fhenix, we utilize this by calling the `select` function. It's a function that takes in a condition and two inputs, and returns the input that corresponds to the state of the condition. You can think of this like a ternary boolean conditional (`condition ? "yes" : "no"`), but for encrypted data.
+In Fhenix this concept is implemented by calling a `select` function. The `select`function accepts a condition and two inputs and returns the input that corresponds to the state of the condition. It is like a ternary Boolean conditional (`condition ? "yes" : "no"`) but for encrypted data.
 
-Let's take a look at an example of `select` usage from a Blind Auction Smart Contract: TBD(ADD LINK):
+Consider the following `select` function example implemented in a Blind Auction Smart Contract: TBD(ADD LINK):
 
 ```Javascript
 ebool isHigher = existingBid.lt(value);
 bids[msg.sender] = FHE.select(isHigher, value, existingBid);
 ```
 
-In this snippet, the bidder is trying to place a new bid that is higher than their existing one. The `lt` function checks if the existing bid is less than the new value and assigns the result to `isHigher` (the result is of type `ebool`).
+In this snippet, the bidder offers a new bid that is higher than the existing one. The `lt` function checks whether the existing bid is less than the new value and assigns the result to `isHigher` (the result is of type `ebool`).
 
-Then `FHE.select` takes over. If `isHigher` is true (remember, this is still an encrypted boolean, not a plaintext one), it returns the `value` (the new bid), otherwise, it returns `existingBid`. This gets assigned to `bids[msg.sender]`, effectively replacing the old bid with the new one if the new one is higher.
+Then, `FHE.select` takes control. If `isHigher` is true (remember, this is still an encrypted Boolean, not a plaintext one), it returns the `value` (the new bid). Otherwise, it returns `existingBid`. The returned value is assigned to bids[`msg.sender`], effectively replacing the old bid with the new one if the new one is higher.
 
-The crucial part here is that all these operations take place on encrypted data, so the actual value of the bids and the result of the comparison stay concealed. It's a powerful pattern to handle conditional execution in the context of FHE data, maintaining privacy without sacrificing functionality.
+The crucial point here is that after the initial comparison, all operations occur on encrypted data. This ensures that the actual values of bids and the comparison result (stored in `isHigher`) remain concealed. This powerful feature demonstrates conditional execution in the context of FHE data, which maintains privacy without sacrificing functionality.