0xMiden · greenhat · Jul 29, 2026 · Jul 30, 2026 · Jul 30, 2026 · Jul 30, 2026
diff --git a/.release/config.toml b/.release/config.toml
@@ -218,6 +218,12 @@ unit = "sdk"
 publish = true
 version-source = "sdk"
 
+[[packages]]
+name = "miden-tx-script-args"
+unit = "sdk"
+publish = true
+version-source = "sdk"
+
 [[packages]]
 name = "midenc-frontend-wasm-metadata"
 unit = "sdk"

diff --git a/Cargo.lock b/Cargo.lock
diff --git a/Cargo.toml b/Cargo.toml
@@ -35,6 +35,7 @@ members = [
     "sdk/base-sys",
     "sdk/sdk",
     "sdk/stdlib-sys",
+    "sdk/tx-script-args",
     "sdk/wasm-metadata",
     "tools/cargo-miden",
     "tools/expect-test",
@@ -190,6 +191,7 @@ midenc-expect-test = { path = "tools/expect-test" }
 miden-base-sys = { version = "0.14.0-rc.1", path = "sdk/base-sys" }
 miden-field-repr = { version = "0.14.0-rc.1", path = "sdk/field-repr/repr" }
 miden-stdlib-sys = { version = "0.14.0-rc.1", path = "sdk/stdlib-sys" }
+miden-tx-script-args = { version = "0.14.0-rc.1", path = "sdk/tx-script-args" }
 
 [patch.crates-io]
 #midenc-hir-type = { path = "../miden-vm/crates/midenc-hir-type"}

diff --git a/examples/auth-component-no-auth/Cargo.lock b/examples/auth-component-no-auth/Cargo.lock
diff --git a/examples/auth-component-rpo-falcon512/Cargo.lock b/examples/auth-component-rpo-falcon512/Cargo.lock
diff --git a/examples/basic-wallet-tx-script/Cargo.lock b/examples/basic-wallet-tx-script/Cargo.lock
diff --git a/examples/basic-wallet-tx-script/src/lib.rs b/examples/basic-wallet-tx-script/src/lib.rs
@@ -2,43 +2,32 @@
 #![no_std]
 #![feature(alloc_error_handler)]
 
-// However, we could still use some standard library types while
-// remaining no-std compatible, if we uncommented the following lines:
-//
-//
-// extern crate alloc;
-// use alloc::vec::Vec;
-
-use miden::{intrinsics::advice::adv_push_mapvaln, *};
+use miden::*;
 
 /// Native account of the transaction script: exposes the `basic-wallet` component methods (e.g.
 /// `move_asset_to_note`) gathered from the `basic_wallet` package.
 #[account(basic_wallet::BasicWallet)]
 struct Wallet;
 
-// Input layout constants
-const TAG_INDEX: usize = 0;
-const NOTE_TYPE_INDEX: usize = 1;
-const RECIPIENT_START: usize = 2;
-const RECIPIENT_END: usize = 6;
-const ASSET_START: usize = 6;
-const ASSET_END: usize = 14;
+/// Arguments of the transaction script, transported via the `TX_SCRIPT_ARGS` word.
+///
+/// The encoding exceeds one word, so the args word is the hash of the encoded fields and the
+/// values travel through the advice provider, verified against the args word (see `ScriptArgs`).
+/// Hosts building the transaction encode a struct with the identical field layout.
+#[derive(FromFeltRepr, ToFeltRepr)]
+pub struct TxScriptArgs {
+    /// The output note's tag.
+    pub tag: Tag,
+    /// The output note's type.
+    pub note_type: NoteType,
+    /// The output note's recipient digest.
+    pub recipient: Recipient,
+    /// The asset to move to the output note.
+    pub asset: Asset,
+}
 
 #[tx_script]
-fn run(arg: Word, account: &mut Wallet) {
-    let num_felts = adv_push_mapvaln(arg);
-    let num_felts_u64 = num_felts.as_canonical_u64();
-    assert_eq(Felt::from_u32((num_felts_u64 % 4) as u32), felt!(0));
-    let num_words = Felt::new(num_felts_u64 / 4).unwrap();
-    let commitment = arg;
-    let input = adv_load_preimage(num_words, commitment);
-    let tag = input[TAG_INDEX];
-    let note_type = input[NOTE_TYPE_INDEX];
-    let recipient: [Felt; 4] = input[RECIPIENT_START..RECIPIENT_END].try_into().unwrap();
-    let note_idx = account.create_note(tag.into(), note_type.into(), recipient.into());
-    let asset: [Felt; 8] = input[ASSET_START..ASSET_END].try_into().unwrap();
-    let asset_key: [Felt; 4] = asset[..4].try_into().unwrap();
-    let asset_value: [Felt; 4] = asset[4..].try_into().unwrap();
-    let asset = Asset::new(asset_key, asset_value);
-    account.move_asset_to_note(asset, note_idx);
+fn run(args: TxScriptArgs, account: &mut Wallet) {
+    let note_idx = account.create_note(args.tag, args.note_type, args.recipient);
+    account.move_asset_to_note(args.asset, note_idx);
 }
diff --git a/examples/basic-wallet/Cargo.lock b/examples/basic-wallet/Cargo.lock
diff --git a/examples/counter-contract/Cargo.lock b/examples/counter-contract/Cargo.lock
diff --git a/examples/counter-note/Cargo.lock b/examples/counter-note/Cargo.lock
diff --git a/examples/p2id-note/Cargo.lock b/examples/p2id-note/Cargo.lock
diff --git a/examples/p2ide-note/Cargo.lock b/examples/p2ide-note/Cargo.lock
diff --git a/examples/storage-example/Cargo.lock b/examples/storage-example/Cargo.lock
diff --git a/sdk/CHANGELOG.md b/sdk/CHANGELOG.md
@@ -5,6 +5,42 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [Unreleased]
+
+### Added
+
+- `#[tx_script]` entrypoints now take typed script arguments: the entrypoint is a free function
+  of any name whose by-value parameter can be any `ScriptArgs` type (every
+  `FromFeltRepr + ToFeltRepr` type qualifies, e.g. `Felt`, `Word`, or a user struct deriving
+  both) and is decoded automatically from the `TX_SCRIPT_ARGS` word — packed directly in the
+  args word when the encoding statically fits its 4 felts, or fetched from the advice provider
+  and hash-verified against the args word otherwise. The parameters may appear in any order
+  (the account reference is optional); existing `fn run(arg: Word, ...)` signatures keep
+  compiling and behave unchanged. On the host, `ScriptArgs::encode` on a struct with the
+  identical layout yields the args word or the advice-map preimage (`EncodedScriptArgs`). The
+  trait lives in the new `miden-tx-script-args` crate (re-exported from `miden`), which
+  off-chain code can depend on without pulling in any on-chain SDK crates.
+  `ScriptArgs::decode` returns `Result<_, ScriptArgsError>`: the generated entrypoint wrapper
+  panics on decode errors (failing the transaction), while off-chain code handles them as
+  values. On the basic-wallet example script, typed decoding costs about 790 VM cycles and
+  4.4 KB of package size over the previous hand-rolled advice decode. See the
+  [migration guide](./sdk/MIGRATION.md) for adopting typed arguments #1291
+- `FromFeltRepr` gained a `FIXED_LEN: Option<usize>` associated constant — the statically known
+  encoded length in felts, used by `ScriptArgs` to pick the transport mode at compile time. It
+  defaults to `None` (variable length, the fail-safe commitment transport), so existing manual
+  implementations keep compiling; `#[derive(FromFeltRepr)]` computes the exact value #1291
+- `Tag`, `NoteType`, `Recipient`, and `Asset` now implement `FromFeltRepr`/`ToFeltRepr`
+  (and `AccountId` gained `ToFeltRepr`), so they can be used as fields of derived
+  script-argument structs. The `miden` crate additionally re-exports `miden_field_repr` under
+  its own crate name, so the derives' generated code resolves in crates that only depend on
+  `miden` and glob-import it #1291
+
+### Fixed
+
+- `adv_load_preimage` no longer truncates huge word counts into an undersized buffer on wasm32
+  (a potential guest heap overflow); it now traps for counts of `2^30` words or more, whose felt
+  total cannot be represented in the 32-bit address space #1291
+
 ## [0.14.0-rc.1]
 
 ### Added