Tx script and note args felt order on the stack

[greenhat]

This would probably be fixed in 0xMiden/miden-vm#2393. @bitwalker or is it?

Problem

The Word arg passed to TransactionRequestBuilder::script_arg ends up in the reversed order in arg at run(arg: Word,...) tx script entrypoint (see the entrypoint example for a tx script at

compiler/examples/basic-wallet-tx-script/src/lib.rs

Lines 27 to 43 in af7f2f0

	fn run(arg: Word, account: &mut Account) {
	let num_felts = adv_push_mapvaln(arg.clone());
	let num_felts_u64 = num_felts.as_u64();
	assert_eq(Felt::from_u32((num_felts_u64 % 4) as u32), felt!(0));
	let num_words = Felt::from_u64_unchecked(num_felts_u64 / 4);
	let commitment = arg;
	let input = adv_load_preimage(num_words, commitment);
	let tag = input[TAG_INDEX];
	let aux = input[AUX_INDEX];
	let note_type = input[NOTE_TYPE_INDEX];
	let execution_hint = input[EXECUTION_HINT_INDEX];
	let recipient: [Felt; 4] = input[RECIPIENT_START..RECIPIENT_END].try_into().unwrap();
	let note_idx =
	output_note::create(tag.into(), aux, note_type.into(), execution_hint, recipient.into());
	let asset: [Felt; 4] = input[ASSET_START..ASSET_END].try_into().unwrap();
	account.move_asset_to_note(asset.into(), note_idx);
	}

).

Since tx and note script args are passed on the stack there is not much we can do in the compiler to convert it to the expected order. The run function is compiled to Wasm expecting 4 values on the stack and they are pushed on the stack by whoever calls the tx script program.

The current workaround is to reverse the Word before passing it in TransactionRequestBuilder::script_arg. However, it's unintuitive to the user and I have this issue reported by our pioneer.

Solutions

1. Emit a wrapper for the VM program's entrypoint that reverses the first 4 elements on the stack before calling the entrypoint.
2. Reverse the order of the tx script and note script args when they are put on the stack by the client/base. But that will be a breaking change for all the existing MASM code that uses args.
3. Do nothing and document the need to pass args reversed in TransactionRequestBuilder::script_arg and note script args docs.

I prefer 1 or 2.

/cc @bobbinth

[Keinberger]

Thanks for raising this @greenhat!

Additional Context

Just wanted to share that another pioneer team (Zoro) has been experiencing the same reversed order issue when working with MASM directly through the client (among other people in the past). They've requested a feature where the client auto-reverses Words when passing arguments to MASM code (for inputs, args, mapping keys, etc.). I have documented this feature here: 0xMiden/miden-client#1635

I believe these are two distinct issues that need to be addressed separately:

1. This issue (compiler): For Rust code compiled to MASM
2. Client-side: For developers writing MASM directly and using the Rust client APIs

However, I'm mentioning it here in case there's any overlap I'm not aware of. I'm not 100% certain how the compiler implementation would work and whether it might use the client internally for this.

I agree with your preference for solutions 1 or 2 for the compiler side.

[bobbinth]

Yes, this is a "known" issue - i.e., the canonical way for interpreting words on the stack is in "big-endian" order - i.e., most significant element on top (which most people interpret as "reverse" order). We are moving away from this and 0xMiden/miden-vm#2393 is a part of this process. It will take us some time to complete this though as basically everything in Miden kernel and standard library uses big-endian form for working with words (and by some time, I mean at least a month).

For this specific issue, I think we should go with option 1, but also create an issue in miden-base to transition to option 2. Once miden-base is updated to do this (probably no sooner than v0.14 release), we can roll back this change in the compiler.

[greenhat]

I made #850 and 0xMiden/miden-base#2218