[Feature] Add arithmetic types, plaintext, and conversion of plaintext & records to JS objects #944

iamalwaysuncomfortable · 2024-11-26T17:23:21Z

Motivation

From several requests and issues surrounding the SDK, the following features have been flagged as important to add.

Addition Field, Scalar, and Group Types

Addition of Field, Group, and Scalar types and core arithmetic methods on those types allowing useful work to be done using algebraic types.

Accessible Plaintext and Record Data + Conversion of Aleo types to JS type.

This PR adds the ability to access:

Methods to access the field of of a Record directly
Methods to access Struct fields
Methods for converting Plaintext types into JS objects. This includes Aleo Literal ( i.e. address, boolean, i8/i16/i32/i64/i128/u8/u16/u32/u64/u128, field, scalar, signature), Struct, and Array types) into JS types.

Transition and Transaction Data Accessor Methods

The ability to search for records, and get the inputs and outputs of Transitions and Transactions.

Addition of `GraphKey` and `ComputeKey`

This PR adds both the GraphKey and ComputeKey to the sdk, allowing GraphKeys to be used directly to determine ownership records.

Test Plan

This PR adds unit tests for all new features.

Pauan

There's various small nits that need to be fixed, otherwise it looks good to me.

Pauan · 2024-12-05T05:54:32Z

wasm/src/ledger/transaction.rs

+    #[wasm_bindgen(js_name = toBytesLe)]
+    pub fn to_bytes_le(&self) -> Result<Uint8Array, String> {
+        let bytes = self.0.to_bytes_le().map_err(|e| e.to_string())?;
+        let array = Uint8Array::new_with_length(bytes.len() as u32);


This should instead use Uint8Array::from, which is simpler and faster.

Pauan · 2024-12-05T05:57:51Z

wasm/src/ledger/transaction.rs

+    ///
+    /// @returns {Array<RecordPlaintext>} Array of record plaintext objects
+    pub fn owned_records(&self, view_key: &ViewKey) -> Array {
+        let array = Array::new();


This should instead use iterators and collect:

self.0.records() .into_iter() .filter_map(|(_, record_ciphertext)| { ... }) .collect()

Pauan · 2024-12-05T05:58:55Z

wasm/src/ledger/transaction.rs

+    ///
+    /// @returns {Array<{commitment: Field, record: RecordCiphertext}>} Array of record ciphertext objects
+    pub fn records(&self) -> Array {
+        let array = Array::new();


Same as above, this should use map + collect.

Pauan · 2024-12-05T06:01:10Z

wasm/src/ledger/transaction.rs

+    pub fn records(&self) -> Array {
+        let array = Array::new();
+        self.0.records().for_each(|(commitment, record_ciphertext)| {
+            let object = Object::new();


This should use the object! utility macro.

Pauan · 2024-12-05T06:01:48Z

wasm/src/ledger/transaction.rs

+    /// @returns {Object} Transaction summary
+    pub fn summary(&self, convert_to_js: bool) -> Result<Object, String> {
+        // Create a transaction object.
+        let transaction = Object::new();


Same as above, it would be nice to use the object! utility macro.

Pauan · 2024-12-05T06:28:46Z

wasm/src/programs/data/plaintext.rs

+    #[wasm_bindgen(js_name = "toBytesLe")]
+    pub fn to_bytes_le(&self) -> Result<Uint8Array, String> {
+        let rust_bytes = self.0.to_bytes_le().map_err(|e| e.to_string())?;
+        let array = Uint8Array::new_with_length(rust_bytes.len() as u32);


This should use Uint8Array::from.

wasm/src/programs/program.rs

Pauan · 2024-12-05T06:31:33Z

wasm/src/types/field.rs

+    }
+
+    /// Invert the field element.
+    pub fn inverse(&self) -> Field {


This should be called negate.

Negate isn't the right terminology in Field Theory given there's no general concept of negative as there is in the real or complex fields. In field theory inverse has very specific meaning and it's the corresponding member of the field that when added together produces the additive identity element (i.e. 0). If you look in SnarkVM Field traits, inverse is the terminology used for this as it matches the formal definitions in theory, so this should stay inverse.

Hmmmm, in that case I don't think it should be using the - operator... since - should have the meaning of "negate", not "invert".

We're generally used to a negation being defined for signed numeric types, but theoretically it is
creating the inverse element to the positive number, so it is indeed referring to an inversion operation.

A finite field is different however in that there are no negative numbers, and thus no signed bit to denote the sign. The confusion here stems from the fact that in unsigned integers, there's no inverse element (and thus it's not a field, ring, or even a group by definition) but since a finite field is indeed a field, it follows field axioms and thus has an additive inverse even though it has no negative numbers. However in theoretical notation (and in SnarkVM) the negative sign is used to denote the inverse element, so it's consistent with common notation in Field theory. The number it ends up though is usually a large number.

For instance, in the ed25519 field (integers mod 2^255 − 19)

You can write (-2) + 2 = 0 to say "element 2 + its additive inverse equals zero", but it is shorthand notation for (2^255 - 21) + 2 = 0. Thus (-2) + 2 = (2^255 - 21) + 2 = 0. This is why using the Neg trait in SnarkVM is valid, and using it here is valid as well.

Because we are defining a finite field, there are no negatives and negate isn't a standard term in Field arithmetic, but using the negative operator (as defined in SnarkVM) is consistent. Calling this negate here is incorrect because it may cause conflation of concepts and lead people to believe this is a signed object and potentially make mistakes in cryptographic code. Inverse is the operation defined here and that's the name that needs to stay on it.

Thanks for the explanation, that helps a lot.

Pauan · 2024-12-05T06:33:25Z

wasm/src/types/scalar.rs

+    }
+
+    /// Invert the field element.
+    pub fn inverse(&self) -> Scalar {


This should be called negate.

This should stay inverse same justification as Field (Scalar is also a finite field). Inverse is the mathematical definition of what's happening here and there's no standard negation in finite fields.

Pauan · 2024-12-05T06:34:12Z

website/src/workers/worker.js

@@ -418,5 +418,7 @@ self.addEventListener("message", (ev) => {
                programManager.setHost(defaultHost);
            }
        })();
+    } else if (ev.data.type === "PROPOSE_GAME") {


What's the purpose of this?

This is a mistake, I shall remove.

iamalwaysuncomfortable

Feedback addressed, @Pauan - when there's time to double check, let me know.

iamalwaysuncomfortable · 2024-12-05T15:49:31Z

wasm/src/types/field.rs

+    }
+
+    /// Invert the field element.
+    pub fn inverse(&self) -> Field {


Negate isn't the right terminology in Field Theory given there's no general concept of negative as there is in the real or complex fields. In field theory inverse has very specific meaning and it's the corresponding member of the field that when added together produces the additive identity element (i.e. 0). If you look in SnarkVM Field traits, inverse is the terminology used for this as it matches the formal definitions in theory, so this should stay inverse.

iamalwaysuncomfortable · 2024-12-05T15:56:35Z

wasm/src/types/group.rs

+    pub fn negate(&self) -> Group {
+        Group(-self.0)
+    }


@Pauan the reason this is called negate is because describes a different operation than the inverse operation of a field. A group element is an eliptic curve element and a negation is the definition given to the operation of flipping a point about it axis of symmetry, which is what -self.0 encapsulates. So that's why the difference here.

iamalwaysuncomfortable · 2024-12-05T15:57:22Z

wasm/src/types/scalar.rs

+    }
+
+    /// Invert the field element.
+    pub fn inverse(&self) -> Scalar {


This should stay inverse same justification as Field (Scalar is also a finite field). Inverse is the mathematical definition of what's happening here and there's no standard negation in finite fields.

iamalwaysuncomfortable · 2024-12-05T15:58:01Z

website/src/workers/worker.js

@@ -418,5 +418,7 @@ self.addEventListener("message", (ev) => {
                programManager.setHost(defaultHost);
            }
        })();
+    } else if (ev.data.type === "PROPOSE_GAME") {


This is a mistake, I shall remove.

iamalwaysuncomfortable · 2024-12-05T18:55:55Z

wasm/src/ledger/transaction.rs

+                let tpk = Group::from(transition.tpk());
+                let tcm = Field::from(transition.tcm());
+                let scm = Field::from(transition.scm());
+                if convert_to_js {


This will only work if its first wrapped in JsValue, which seems acceptable.

Pauan

Couple more minor issues to fix, otherwise it looks good to me.

Pauan · 2024-12-10T02:09:27Z

wasm/src/lib.rs

+        ($($key:literal: $value:expr,)*) => {{
+            let object = ::js_sys::Object::new();
+
+            $(Reflect::set(&object, &::wasm_bindgen::JsValue::from_str($key), &::wasm_bindgen::JsValue::from($value)).unwrap();)*


Minor nit: this should be ::js_sys::Reflect::set

Pauan · 2024-12-10T02:10:11Z

wasm/src/programs/data/helpers/future.rs

+        "programId" : argument.program_id().to_string(),
+        "functionName" : argument.function_name().to_string(),
+    };
+    let arguments = argument


This can be moved into the object! so it can avoid the Reflect::set.

Pauan · 2024-12-10T02:11:47Z

wasm/src/programs/data/helpers/input.rs

+            let record = object! {
+                "type": "record",
+            };
+            if convert_to_js {


I think it's cleaner to do something like this:

if convert_to_js { object! { "type": "record", ... } } else { object! { "type": "record", ... } }

Pauan · 2024-12-10T02:12:04Z

wasm/src/programs/data/helpers/input.rs

+            let external_record = object! {
+                "type": "extneralRecord",
+            };
+            if convert_to_js {


Same as above, better to use object! instead of Reflect::set

Pauan · 2024-12-10T02:12:37Z

wasm/src/programs/data/helpers/output.rs

+            };
+
+            // Create a record object.
+            if convert_to_js {


Same as above, better to use object! instead of Reflect::set

iamalwaysuncomfortable added 2 commits November 26, 2024 11:14

Add arithmetic types, plaintext, and conversion to JS objects

ce326d1

Add tests for all getter methods and ciphertext decryption methods

f27d96a

vercel bot deployed to Preview December 3, 2024 01:32 View deployment

Change check fmt to nightly

c387b6b

vercel bot deployed to Preview December 3, 2024 01:55 View deployment

Add format lints

24f6a2e

vercel bot deployed to Preview December 3, 2024 04:55 View deployment

iamalwaysuncomfortable requested review from jaketarnow, Pauan, esren0x and onetrickwolf December 3, 2024 04:55

iamalwaysuncomfortable marked this pull request as ready for review December 3, 2024 04:56

iamalwaysuncomfortable changed the title ~~[Feature] Add arithmetic types, plaintext, and conversion of Plaintext & Records to JS objects~~ [Feature] Add arithmetic types, plaintext, and conversion of plaintext & records to JS objects Dec 3, 2024

Pauan requested changes Dec 5, 2024

View reviewed changes

Use object macro for object formation and iterators for array formation

c13b54a

vercel bot deployed to Preview December 5, 2024 20:45 View deployment

iamalwaysuncomfortable commented Dec 5, 2024

View reviewed changes

iamalwaysuncomfortable requested a review from Pauan December 5, 2024 23:38

Pauan requested changes Dec 10, 2024

View reviewed changes

iamalwaysuncomfortable mentioned this pull request Dec 10, 2024

[Feature] Add Field, Group, Scalar, Plaintext, Ciphertext, Transitions, and Transactions to JS SDK. #948

Open

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

[Feature] Add arithmetic types, plaintext, and conversion of plaintext & records to JS objects #944

[Feature] Add arithmetic types, plaintext, and conversion of plaintext & records to JS objects #944

iamalwaysuncomfortable commented Nov 26, 2024 •

edited

Loading

Pauan left a comment

Pauan Dec 5, 2024

Pauan Dec 5, 2024

Pauan Dec 5, 2024

Pauan Dec 5, 2024

Pauan Dec 5, 2024

Pauan Dec 5, 2024

Pauan Dec 5, 2024

iamalwaysuncomfortable Dec 5, 2024 •

edited

Loading

Pauan Dec 6, 2024

iamalwaysuncomfortable Dec 6, 2024 •

edited

Loading

Pauan Dec 10, 2024

Pauan Dec 5, 2024

iamalwaysuncomfortable Dec 5, 2024

Pauan Dec 5, 2024

iamalwaysuncomfortable Dec 5, 2024

iamalwaysuncomfortable left a comment

iamalwaysuncomfortable Dec 5, 2024 •

edited

Loading

iamalwaysuncomfortable Dec 5, 2024 •

edited

Loading

iamalwaysuncomfortable Dec 5, 2024

iamalwaysuncomfortable Dec 5, 2024

iamalwaysuncomfortable Dec 5, 2024

Pauan left a comment

Pauan Dec 10, 2024

Pauan Dec 10, 2024

Pauan Dec 10, 2024

Pauan Dec 10, 2024

Pauan Dec 10, 2024

[Feature] Add arithmetic types, plaintext, and conversion of plaintext & records to JS objects #944

Are you sure you want to change the base?

[Feature] Add arithmetic types, plaintext, and conversion of plaintext & records to JS objects #944

Conversation

iamalwaysuncomfortable commented Nov 26, 2024 • edited Loading

Motivation

Addition Field, Scalar, and Group Types

Accessible Plaintext and Record Data + Conversion of Aleo types to JS type.

Transition and Transaction Data Accessor Methods

Addition of GraphKey and ComputeKey

Test Plan

Pauan left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

iamalwaysuncomfortable Dec 5, 2024 • edited Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

iamalwaysuncomfortable Dec 6, 2024 • edited Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

iamalwaysuncomfortable left a comment

Choose a reason for hiding this comment

iamalwaysuncomfortable Dec 5, 2024 • edited Loading

Choose a reason for hiding this comment

iamalwaysuncomfortable Dec 5, 2024 • edited Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Pauan left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

iamalwaysuncomfortable commented Nov 26, 2024 •

edited

Loading

Addition of `GraphKey` and `ComputeKey`

iamalwaysuncomfortable Dec 5, 2024 •

edited

Loading

iamalwaysuncomfortable Dec 6, 2024 •

edited

Loading

iamalwaysuncomfortable Dec 5, 2024 •

edited

Loading

iamalwaysuncomfortable Dec 5, 2024 •

edited

Loading