Chore/Improve Rationals Development Experience (#14)

* feat: Improved Devex for Rationals and made small adjustments to types.py

* docs: Improved examples and commenting

* feat: Added script that permits using nada-algebra with pre-release versions of Nillion

* afix: Added corrections to code to improve consistency

* fix: updated readme.md for rationals example

Author: jcabrero

README.md

@@ -8,10 +8,12 @@ Nada-Algebra is a Python library designed for algebraic operations on NumPy-like
 
 ## Features
 
+### Use Numpy Array Features
 - **Dot Product**: Compute the dot product between two NadaArray objects.
 - **Element-wise Operations**: Perform element-wise addition, subtraction, multiplication, and division with broadcasting support.
 - **Stacking**: Horizontally and vertically stack arrays.
-- **Custom Function Application**: Apply custom functions to each element of the array.
+### Use Decimal Numbers in Nada
+- **Rational Number Support**: Our implementation of `Rational` and `SecretRational` allows the use of simplified implementations of decimal numbers on top of Nillion.
 
 ## Installation
 ### Using pip

examples/README.md

@@ -3,4 +3,6 @@
 The following are the currently available examples:
 
 - [Dot Product](./dot_product)
-- [Matrix Multiplication](./matrix_multiplication)
+- [Matrix Multiplication](./matrix_multiplication)
+- [Broadcasting](./broadcasting/)
+- [Rational Numbers](./rational_numbers/)

examples/matrix_multiplication/network/compute.py

@@ -0,0 +1,103 @@
+# Import necessary libraries and modules
+import asyncio
+import py_nillion_client as nillion
+import os
+import sys
+import pytest
+import numpy as np
+import time
+from dotenv import load_dotenv
+
+# Add the parent directory to the system path to import modules from it
+sys.path.append(os.path.abspath(os.path.join(os.path.dirname(__file__), "../..")))
+
+# Import helper functions for creating nillion client and getting keys
+from dot_product.network.helpers.nillion_client_helper import create_nillion_client
+from dot_product.network.helpers.nillion_keypath_helper import (
+    getUserKeyFromFile,
+    getNodeKeyFromFile,
+)
+import nada_algebra.client as na_client
+
+# Load environment variables from a .env file
+load_dotenv()
+from dot_product.config.parameters import DIM
+
+
+# Main asynchronous function to coordinate the process
+async def main():
+    print(f"USING: {DIM}")
+    cluster_id = os.getenv("NILLION_CLUSTER_ID")
+    userkey = getUserKeyFromFile(os.getenv("NILLION_USERKEY_PATH_PARTY_1"))
+    nodekey = getNodeKeyFromFile(os.getenv("NILLION_NODEKEY_PATH_PARTY_1"))
+    client = create_nillion_client(userkey, nodekey)
+    party_id = client.party_id
+    user_id = client.user_id
+    party_names = na_client.parties(3)
+    program_name = "main"
+    program_mir_path = f"./target/{program_name}.nada.bin"
+
+    # Store the program
+    action_id = await client.store_program(cluster_id, program_name, program_mir_path)
+    program_id = f"{user_id}/{program_name}"
+    print("Stored program. action_id:", action_id)
+    print("Stored program_id:", program_id)
+
+    # Create and store secrets for two parties
+    A = np.ones([DIM, DIM])
+    stored_secret = nillion.Secrets(na_client.array(A, "A"))
+    secret_bindings = nillion.ProgramBindings(program_id)
+    secret_bindings.add_input_party(party_names[0], party_id)
+
+    # Store the secret for the specified party
+    A_store_id = await client.store_secrets(
+        cluster_id, secret_bindings, stored_secret, None
+    )
+
+    B = np.ones([DIM, DIM])
+    stored_secret = nillion.Secrets(na_client.array(B, "B"))
+
+    secret_bindings = nillion.ProgramBindings(program_id)
+    secret_bindings.add_input_party(party_names[1], party_id)
+
+    # Store the secret for the specified party
+    B_store_id = await client.store_secrets(
+        cluster_id, secret_bindings, stored_secret, None
+    )
+
+    # Set up the compute bindings for the parties
+    compute_bindings = nillion.ProgramBindings(program_id)
+    [
+        compute_bindings.add_input_party(party_name, party_id)
+        for party_name in party_names[:-1]
+    ]
+    compute_bindings.add_output_party(party_names[-1], party_id)
+
+    print(f"Computing using program {program_id}")
+    print(f"Use secret store_id: {A_store_id}, {B_store_id}")
+
+    computation_time_secrets = nillion.Secrets({"my_int2": nillion.SecretInteger(10)})
+
+    # Perform the computation and return the result
+    compute_id = await client.compute(
+        cluster_id,
+        compute_bindings,
+        [A_store_id, B_store_id],
+        computation_time_secrets,
+        nillion.PublicVariables({}),
+    )
+
+    # Monitor and print the computation result
+    print(f"The computation was sent to the network. compute_id: {compute_id}")
+    while True:
+        compute_event = await client.next_compute_event()
+        if isinstance(compute_event, nillion.ComputeFinishedEvent):
+            print(f"✅  Compute complete for compute_id {compute_event.uuid}")
+            print(f"🖥️  The result is {compute_event.result.value}")
+            return compute_event.result.value
+    return result
+
+
+# Run the main function if the script is executed directly
+if __name__ == "__main__":
+    asyncio.run(main())

examples/matrix_multiplication/network/helpers/nillion_client_helper.py

@@ -0,0 +1,12 @@
+import os
+import py_nillion_client as nillion
+from helpers.nillion_payments_helper import create_payments_config
+
+
+def create_nillion_client(userkey, nodekey):
+    bootnodes = [os.getenv("NILLION_BOOTNODE_MULTIADDRESS")]
+    payments_config = create_payments_config()
+
+    return nillion.NillionClient(
+        nodekey, bootnodes, nillion.ConnectionMode.relay(), userkey, payments_config
+    )

examples/matrix_multiplication/network/helpers/nillion_keypath_helper.py

@@ -0,0 +1,10 @@
+import os
+import py_nillion_client as nillion
+
+
+def getUserKeyFromFile(userkey_filepath):
+    return nillion.UserKey.from_file(userkey_filepath)
+
+
+def getNodeKeyFromFile(nodekey_filepath):
+    return nillion.NodeKey.from_file(nodekey_filepath)

examples/matrix_multiplication/network/helpers/nillion_payments_helper.py

@@ -0,0 +1,12 @@
+import os
+import py_nillion_client as nillion
+
+
+def create_payments_config():
+    return nillion.PaymentsConfig(
+        os.getenv("NILLION_BLOCKCHAIN_RPC_ENDPOINT"),
+        os.getenv("NILLION_WALLET_PRIVATE_KEY"),
+        int(os.getenv("NILLION_CHAIN_ID")),
+        os.getenv("NILLION_PAYMENTS_SC_ADDRESS"),
+        os.getenv("NILLION_BLINDING_FACTORS_MANAGER_SC_ADDRESS"),
+    )

examples/rational_numbers/README.md

@@ -0,0 +1,65 @@
+# Rational Numbers Tutorial
+
+This tutorial shows how to use Nada Algebra Rational datatypes to work with fixed-point numbers in Nada.
+
+## Notions
+
+This tutorial uses fixed point numbers as it is the only available way to use Fixed-Point numbers in Nada. The representation of a fixed point number uses integer places to represent decimal digits. Thus, every number is multiplied by a scaling factor, that we refer to as `SCALE` ($\Delta = 2^{16}$) or `LOG_SCALE` in its logarithmic notation ($log_2\Delta = 16$). In a nutshell, this means we will use 16 bits to represent decimals. 
+
+If we want to input a variable `a = float(3.2)`, we need to first encode it. For that we will define a new variable `a'` which is going to be the scaled version. In this case, the scaling factor (to simplify) is going to by 3 bits so, $log_2\Delta = 3$ and $\Delta = 2^3 = 8$. With the following formula, we compute the encoded value:
+
+$$ a' = round(a * \Delta) = round(a * 2^{log_2\Delta}) = 3.2 \cdot 2^3 = 3.2 \cdot 8 = 26 $$
+
+Thus, in order to introduce a value with 3 bits of precision, we would be inputing 26 instead of 3.2.
+
+
+
+## Example 
+
+```python
+from nada_dsl import *
+import nada_algebra as na
+
+
+def nada_main():
+    # We define the number of parties
+    parties = na.parties(3)
+
+    # We use na.SecretRational to create a secret rational number for party 0
+    a = na.SecretRational("my_input_0", parties[0]) 
+
+    # We use na.SecretRational to create a secret rational number for party 1
+    b = na.SecretRational("my_input_1", parties[1]) 
+
+    # This is a compile time rational number
+    c = na.Rational(1.2) 
+
+    # The formula below does operations on rational numbers and returns a rational number
+    # It's easy to see that (a + b - c) is both on numerator and denominator, so the end result is b
+    out_0 = ((a + b - c) * b) / (a + b - c) 
+
+    return [
+        Output(out_0.value, "my_output_0", parties[2]),
+    ]
+
+
+```
+
+0. We import Nada algebra using `import nada_algebra as na`.
+1. We create an array of parties, with our wrapper using `parties = na.parties(3)` which creates an array of parties named: `Party0`, `Party1` and `Party2`.
+2. We create our secret floating point variable `a` as `SecretRational("my_input_0", parties[0])` meaning the variable belongs to `Party0` and the name of the variable is `my_input_0`.
+3. We create our secret floating point variable `b` as `SecretRational("my_input_1", parties[1])` meaning the variable belongs to `Party1` and the name of the variable is `my_input_1`.
+4. Then, we operate normally with this variables, and Nada Algebra will ensure they maintain the consistency of the decimal places.
+5. Finally, we produce the outputs of the array like:  `Output(out_0.value, "my_output_0", parties[2]),` establishing that the output party will be `Party2`and the name of the output variable will be `my_output`. Not the difference between Nada Algebra and classic Nada where we add `out_0`**`.value`**.
+
+# How to Run the Tutorial
+
+1. Start by compiling the Nada program using the command:
+   ```
+   nada build
+   ```
+
+2. Next, ensure that the program functions correctly by testing it with:
+   ```
+   nada test
+   ```

examples/rational_numbers/nada-project.toml

@@ -0,0 +1,7 @@
+name = "rational_numbers"
+version = "0.1.0"
+authors = [""]
+
+[[programs]]
+path = "src/rational_numbers.py"
+prime_size = 128

examples/rational_numbers/network/compute.py

@@ -0,0 +1,100 @@
+# Import necessary libraries and modules
+import asyncio
+import py_nillion_client as nillion
+import os
+import sys
+import pytest
+import numpy as np
+import time
+from dotenv import load_dotenv
+
+# Add the parent directory to the system path to import modules from it
+sys.path.append(os.path.abspath(os.path.join(os.path.dirname(__file__), "../..")))
+
+# Import helper functions for creating nillion client and getting keys
+from dot_product.network.helpers.nillion_client_helper import create_nillion_client
+from dot_product.network.helpers.nillion_keypath_helper import (
+    getUserKeyFromFile,
+    getNodeKeyFromFile,
+)
+import nada_algebra.client as na_client
+
+# Load environment variables from a .env file
+load_dotenv()
+from dot_product.config.parameters import DIM
+
+
+# Main asynchronous function to coordinate the process
+async def main():
+    print(f"USING: {DIM}")
+    cluster_id = os.getenv("NILLION_CLUSTER_ID")
+    userkey = getUserKeyFromFile(os.getenv("NILLION_USERKEY_PATH_PARTY_1"))
+    nodekey = getNodeKeyFromFile(os.getenv("NILLION_NODEKEY_PATH_PARTY_1"))
+    client = create_nillion_client(userkey, nodekey)
+    party_id = client.party_id
+    user_id = client.user_id
+    party_names = na_client.parties(3)
+    program_name = "main"
+    program_mir_path = f"./target/{program_name}.nada.bin"
+
+    # Store the program
+    action_id = await client.store_program(cluster_id, program_name, program_mir_path)
+    program_id = f"{user_id}/{program_name}"
+    print("Stored program. action_id:", action_id)
+    print("Stored program_id:", program_id)
+
+    # Create and store secrets for two parties
+    stored_secret = nillion.Secrets({"my_input_0": na_client.SecretRational(3.2)})
+    secret_bindings = nillion.ProgramBindings(program_id)
+    secret_bindings.add_input_party(party_names[0], party_id)
+
+    # Store the secret for the specified party
+    A_store_id = await client.store_secrets(
+        cluster_id, secret_bindings, stored_secret, None
+    )
+
+    stored_secret = nillion.Secrets({"my_input_1": na_client.SecretRational(2.3)})
+    secret_bindings = nillion.ProgramBindings(program_id)
+    secret_bindings.add_input_party(party_names[1], party_id)
+
+    # Store the secret for the specified party
+    B_store_id = await client.store_secrets(
+        cluster_id, secret_bindings, stored_secret, None
+    )
+
+    # Set up the compute bindings for the parties
+    compute_bindings = nillion.ProgramBindings(program_id)
+    [
+        compute_bindings.add_input_party(party_name, party_id)
+        for party_name in party_names[:-1]
+    ]
+    compute_bindings.add_output_party(party_names[-1], party_id)
+
+    print(f"Computing using program {program_id}")
+    print(f"Use secret store_id: {A_store_id}, {B_store_id}")
+
+    computation_time_secrets = nillion.Secrets({"my_int2": nillion.SecretInteger(10)})
+
+    # Perform the computation and return the result
+    compute_id = await client.compute(
+        cluster_id,
+        compute_bindings,
+        [A_store_id, B_store_id],
+        computation_time_secrets,
+        nillion.PublicVariables({}),
+    )
+
+    # Monitor and print the computation result
+    print(f"The computation was sent to the network. compute_id: {compute_id}")
+    while True:
+        compute_event = await client.next_compute_event()
+        if isinstance(compute_event, nillion.ComputeFinishedEvent):
+            print(f"✅  Compute complete for compute_id {compute_event.uuid}")
+            print(f"🖥️  The result is {compute_event.result.value}")
+            return compute_event.result.value
+    return result
+
+
+# Run the main function if the script is executed directly
+if __name__ == "__main__":
+    asyncio.run(main())

examples/rational_numbers/network/helpers/nillion_client_helper.py

@@ -0,0 +1,12 @@
+import os
+import py_nillion_client as nillion
+from helpers.nillion_payments_helper import create_payments_config
+
+
+def create_nillion_client(userkey, nodekey):
+    bootnodes = [os.getenv("NILLION_BOOTNODE_MULTIADDRESS")]
+    payments_config = create_payments_config()
+
+    return nillion.NillionClient(
+        nodekey, bootnodes, nillion.ConnectionMode.relay(), userkey, payments_config
+    )