Make WASM Arrays More Consistent Throughout Web Client

[dagarcia7]

There are some cases in the web client where there is a special Array type for a certain WASM object. For example, FeltArray here

miden-client/crates/web-client/src/models/felt.rs

Line 59 in 387826b

impl FeltArray {

. This would be fine except that sometimes the inputs to some WASM functions accept a FeltArray and other times a Vec<Felt> is accepted instead.

The original intent behind these custom Array objects was that I didn't want users stressing out over ownership issues in rust when they would call into it via WASM code. For example, if you called a function that passed in a Vec<Felt> and in JS you constructed a Felt[] and passed it in, then that array would be unusable later on within the scope of that same function code.

In any case, we should revisit these custom types and either make more to make things consistent, or remove them altogether. But the mix of the two right now is causing some confusion amongst builders.

[igamigo]

The original intent behind these custom Array objects was that I didn't want users stressing out over ownership issues in rust when they would call into it via WASM code. For example, if you called a function that passed in a Vec<Felt> and in JS you constructed a Felt[] and passed it in, then that array would be unusable later on within the scope of that same function code.

Thanks for the explanation! I wasn't fully aware of this. I recently ran some tests, and I couldn't see any particular differences in passing something like Vec<Felt> versus FeltArray, but this makes sense.

Overall, I'd favor letting wasm-bindgen do as much of the heavy lifting as possible, but if this results in worse UX then I agree we should look into adding wrappers (and making them as consistent as possible).

[fkrause98]

About modifying JS arrays / Rust-WASM vectors

Hi !I've been researching this issue for a bit, to see If we could come up with an ergonomic solution for the users of the web-client.
As of today, wasm-bindgen does not support passing either &Box<T>, &mut Box<T>, &Vec<T>, &mut Vec<T>, which makes "idiomatic" JS usage of this library a bit of a problem. Which If understand the original issue correctly, this is where the problem stems for.

(Source for the image)

Ideally, our code should work as follows:

let myArray = [Felt(1n), Felt(2n)];
wasmFunctionThatModifiesArray(myArray);
// myArray reflects changes.

But this is not the case, to reflect changes, we have to return a modified copy from the Rust/WASM-side, and
thus the code above will have to be used more like:

let myArray = [Felt(1n), Felt(2n)];
myArray = wasmFunctionThatModifiesArray(myArray);

So, the wasm code will look like this:

pub fn wasm_function_that_modifies_array(vec: Vec<Felt>) -> Vec<Felt> { ...  } 

I've stumbled upon a really nice blogspot with a couple of detailed examples and workarounds, but none
of them have convinced me, of course they can be discussed.
Here's the link: https://www.rossng.eu/posts/2025-02-22-wasm-bindgen-vec-parameters/.

Tried approaches

I've tried a few different approaches to see if we could modify the input vector, for example:

1. Using &Vec, &mut Vec, as stated before, this does not compile.
2. Using Box<&[Felt]>, Box<&mut [Felt]>, also does not compile.
3. Using as signature: mut vec Box<[Felt]>, throws a runtime error "Unreachable",the error I get is that rust tried to read a null pointer.

Potential but flawed approach

Generic Vec wrapper.

The next thing that came to mind is to wrap the Vector type with a struct that receives a generic type.
As of now, wasm-bindgen does not support generic values for #[wasm_bindgen] annotated structs, compilation
fails with an error explaining this.

I was hoping this idea would work since &mut self arguments do work with wasm-bindgen.

Specialized Vec wrapper.

Having a specialized struct wrapper for a dedicated type works (this is exactly what the original issue is describing),
but this approach gets cumbersome fast, plus I think this can confuse library users since we would have multiple
array types for each exposed struct.

Final thoughts

My conclusion for the time being is that maybe the extra specialized structs (like FeltArray) can be a bit confusing,
since when using this library from JS you'd have to instance a specialized array insted of using the default one.
I'd go for simply using Vecs in Rust, and leverage wasm-bindgen to translate the JS arrays to the correctly typed
Vecs in Rust.

That being said it'd be nice to have more opinions on how to tackle this 🙂.

[PhilippGackstatter]

I might be missing the point here completely, but perhaps it's useful as input anyway, so I thought I'd share. Perhaps you could try something like the following to avoid the Wasm bindings from consuming the input, i.e. the problem in #1281. It probably won't solve mutating arrays, though.

#[wasm_bindgen]
extern "C" {
  #[wasm_bindgen(typescript_type = "Array<string>")]
  pub type ArrayString;
}

(see https://github.com/iotaledger/identity/blob/1f8f7d8492cd54c16b93a7ce135fb3e578565859/bindings/wasm/identity_wasm/src/common/types.rs for the full code)

and then the usage looks like this:

#[wasm_bindgen(js_name=resolveMultiple)]
pub fn resolve_multiple(&self, dids: ArrayString) -> Result<PromiseArrayIToCoreDocument> {
  let dids: Vec<String> = dids
    .dyn_into::<Array>()?
    .iter()
    .map(|item| item.dyn_into::<JsString>().map(String::from))
    .collect::<Result<Vec<String>>>()?;
}

(see https://github.com/iotaledger/identity/blob/1f8f7d8492cd54c16b93a7ce135fb3e578565859/bindings/wasm/identity_wasm/src/resolver/wasm_resolver.rs#L195 for the full code)

I think one limitation might be that this only works for native JS types, e.g. JsString but not user-defined types, but I don't recall if that's the case. At least for return types, this also works for user-defined types, see usages of ArrayService for example. Also, I don't know what exactly this translates to under the hood, e.g. in raw JavaScript rather than TypeScript.

[fkrause98]

Thanks for the input! I've been looking into this approach since It seemed promising.

Unfortunately, this won't work, the types we define under wasm-bindgen use an unstable/private trait (defined by wasm-bindgen) to turn a js type to its rust equivalent. Even more so, to use something like web_sys::js::Array we'd always have to check the received types in the Array. I'm working on generating specified arrays with a macro under draft #1292 if you want to take a look.