feat(web-client, react-sdk): contract creation, CompilerResource, transactions.execute(), and API improvements

CHANGELOG.md

@@ -31,6 +31,8 @@
 * [FEATURE][web] New `MidenClient` class with resource-based API (`client.accounts`, `client.transactions`, `client.notes`, `client.tags`, `client.settings`). Provides high-level transaction helpers (`send`, `mint`, `consume`, `swap`, `consumeAll`), transaction dry-runs via `preview()`, confirmation polling via `waitFor()`, and flexible account/note references that accept hex strings, bech32 strings, or WASM objects interchangeably (`AccountRef`, `NoteInput` types). Factory methods: `MidenClient.create()`, `MidenClient.createTestnet()`, `MidenClient.createMock()`. ([#1762](https://github.com/0xMiden/miden-client/pull/1762))
 * [FEATURE][web] Added `TransactionId.fromHex()` static constructor for creating transaction IDs from hex strings. ([#1762](https://github.com/0xMiden/miden-client/pull/1762))
 * [FEATURE][web] Added standalone tree-shakeable note utilities (`createP2IDNote`, `createP2IDENote`, `buildSwapTag`) usable without a client instance. ([#1762](https://github.com/0xMiden/miden-client/pull/1762))
+* [FEATURE][web] Custom contract support: `accounts.create()` with `ImmutableContract`/`MutableContract` types, new `client.compile` resource (`compile.component()`, `compile.txScript()` with `"dynamic"`/`"static"` linking), and `transactions.execute({ account, script, foreignAccounts? })` for custom script execution with FPI. ([#1828](https://github.com/0xMiden/miden-client/pull/1828))
+* [FEATURE][web] Account import improvements: `accounts.getOrImport(ref)` convenience method, and `accounts.import()` now accepts full `AccountRef` (string, `AccountId`, `Account`, `AccountHeader`) in addition to `{ file }` and `{ seed }` forms. ([#1828](https://github.com/0xMiden/miden-client/pull/1828))
 
 ## 0.13.1 (TBD)
 

crates/rust-client/src/rpc/domain/account.rs

@@ -671,8 +671,7 @@ impl From<AccountStorageRequirements> for Vec<account_detail_request::StorageMap
     fn from(
         value: AccountStorageRequirements,
     ) -> Vec<account_detail_request::StorageMapDetailRequest> {
-        use account_detail_request;
-        use account_detail_request::storage_map_detail_request;
+        use account_detail_request::{self, storage_map_detail_request};
         let request_map = value.0;
         let mut requests = Vec::with_capacity(request_map.len());
         for (slot_name, _map_keys) in request_map {

crates/web-client/js/client.js

@@ -3,6 +3,7 @@ import { TransactionsResource } from "./resources/transactions.js";
 import { NotesResource } from "./resources/notes.js";
 import { TagsResource } from "./resources/tags.js";
 import { SettingsResource } from "./resources/settings.js";
+import { CompilerResource } from "./resources/compiler.js";
 import { hashSeed } from "./utils.js";
 
 /**
@@ -33,6 +34,7 @@ export class MidenClient {
     this.notes = new NotesResource(inner, getWasm, this);
     this.tags = new TagsResource(inner, getWasm, this);
     this.settings = new SettingsResource(inner, getWasm, this);
+    this.compile = new CompilerResource(inner, getWasm, this);
   }
 
   /**
@@ -53,10 +55,12 @@ export class MidenClient {
 
     const seed = options?.seed ? await hashSeed(options.seed) : undefined;
 
+    const rpcUrl = resolveRpcUrl(options?.rpcUrl);
+
     let inner;
     if (options?.keystore) {
       inner = await WebClientClass.createClientWithExternalKeystore(
-        options?.rpcUrl,
+        rpcUrl,
         options?.noteTransportUrl,
         seed,
         options?.storeName,
@@ -66,7 +70,7 @@ export class MidenClient {
       );
     } else {
       inner = await WebClientClass.createClient(
-        options?.rpcUrl,
+        rpcUrl,
         options?.noteTransportUrl,
         seed,
         options?.storeName
@@ -76,10 +80,7 @@ export class MidenClient {
     let defaultProver = null;
     if (options?.proverUrl) {
       const wasm = await getWasm();
-      defaultProver = wasm.TransactionProver.newRemoteProver(
-        options.proverUrl,
-        undefined
-      );
+      defaultProver = resolveProver(options.proverUrl, wasm);
     }
 
     const client = new MidenClient(inner, getWasm, defaultProver);
@@ -247,3 +248,42 @@ export class MidenClient {
     }
   }
 }
+
+const RPC_URLS = {
+  testnet: "https://rpc.testnet.miden.io",
+  devnet: "https://rpc.devnet.miden.io",
+  localhost: "http://localhost:57291",
+  local: "http://localhost:57291",
+};
+
+/**
+ * Resolves an rpcUrl shorthand or raw URL into a concrete endpoint string.
+ *
+ * @param {string | undefined} rpcUrl - "testnet", "devnet", "localhost", "local", or a raw URL.
+ * @returns {string | undefined} A fully qualified URL, or undefined to use the SDK default.
+ */
+function resolveRpcUrl(rpcUrl) {
+  if (!rpcUrl) return undefined;
+  return RPC_URLS[rpcUrl.trim().toLowerCase()] ?? rpcUrl;
+}
+
+const PROVER_URLS = {
+  devnet: "https://tx-prover.devnet.miden.io",
+  testnet: "https://tx-prover.testnet.miden.io",
+};
+
+/**
+ * Resolves a proverUrl shorthand or raw URL into a TransactionProver.
+ *
+ * @param {string} proverUrl - "local", "devnet", "testnet", or a raw URL.
+ * @param {object} wasm - Loaded WASM module.
+ * @returns {object} A TransactionProver instance.
+ */
+function resolveProver(proverUrl, wasm) {
+  const normalized = proverUrl.trim().toLowerCase();
+  if (normalized === "local") {
+    return wasm.TransactionProver.newLocalProver();
+  }
+  const remoteUrl = PROVER_URLS[normalized] ?? proverUrl;
+  return wasm.TransactionProver.newRemoteProver(remoteUrl, undefined);
+}

crates/web-client/js/index.js

@@ -19,13 +19,26 @@ export const AccountType = Object.freeze({
   MutableWallet: "MutableWallet",
   ImmutableWallet: "ImmutableWallet",
   FungibleFaucet: "FungibleFaucet",
+  ImmutableContract: "ImmutableContract",
+  MutableContract: "MutableContract",
 });
 
 export const AuthScheme = Object.freeze({
   Falcon: "falcon",
   ECDSA: "ecdsa",
 });
 
+export const NoteVisibility = Object.freeze({
+  Public: "public",
+  Private: "private",
+});
+
+export const StorageMode = Object.freeze({
+  Public: "public",
+  Private: "private",
+  Network: "network",
+});
+
 export { MidenClient };
 export { createP2IDNote, createP2IDENote, buildSwapTag };
 
@@ -473,6 +486,23 @@ class WebClient {
     });
   }
 
+  async newAccount(account, overwrite) {
+    return this._serializeWasmCall(async () => {
+      const wasmWebClient = await this.getWasmWebClient();
+      return await wasmWebClient.newAccount(account, overwrite);
+    });
+  }
+
+  async addAccountSecretKeyToWebStore(accountId, secretKey) {
+    return this._serializeWasmCall(async () => {
+      const wasmWebClient = await this.getWasmWebClient();
+      return await wasmWebClient.addAccountSecretKeyToWebStore(
+        accountId,
+        secretKey
+      );
+    });
+  }
+
   async submitNewTransaction(accountId, transactionRequest) {
     try {
       if (!this.worker) {

crates/web-client/js/resources/accounts.js

@@ -34,6 +34,13 @@ export class AccountsResource {
       );
     }
 
+    if (
+      opts?.type === "ImmutableContract" ||
+      opts?.type === "MutableContract"
+    ) {
+      return await this.#createContract(opts, wasm);
+    }
+
     // Default: wallet (mutable or immutable based on type)
     const mutable = resolveAccountMutability(opts?.type);
     const storageMode = resolveStorageMode(opts?.storage ?? "private", wasm);
@@ -42,6 +49,43 @@ export class AccountsResource {
     return await this.#inner.newWallet(storageMode, mutable, authScheme, seed);
   }
 
+  async #createContract(opts, wasm) {
+    if (!opts.seed)
+      throw new Error("Contract creation requires a 'seed' (Uint8Array)");
+    if (!opts.auth)
+      throw new Error("Contract creation requires an 'auth' (AuthSecretKey)");
+
+    const mutable = opts.type === "MutableContract";
+    const accountTypeEnum = mutable
+      ? wasm.AccountType.RegularAccountUpdatableCode
+      : wasm.AccountType.RegularAccountImmutableCode;
+    const storageMode = resolveStorageMode(opts.storage ?? "public", wasm);
+    const authComponent =
+      wasm.AccountComponent.createAuthComponentFromSecretKey(opts.auth);
+
+    let builder = new wasm.AccountBuilder(opts.seed)
+      .accountType(accountTypeEnum)
+      .storageMode(storageMode)
+      .withAuthComponent(authComponent);
+
+    for (const component of opts.components ?? []) {
+      builder = builder.withComponent(component);
+    }
+
+    const built = builder.build();
+    const account = built.account;
+    const accountId = account.id();
+
+    await this.#inner.newAccount(account, false);
+    await this.#inner.addAccountSecretKeyToWebStore(accountId, opts.auth);
+    return await this.#inner.getAccount(accountId);
+  }
+
+  async getOrImport(ref) {
+    this.#client.assertNotTerminated();
+    return (await this.get(ref)) ?? (await this.import(ref));
+  }
+
   async get(ref) {
     this.#client.assertNotTerminated();
     const wasm = await this.#getWasm();
@@ -86,8 +130,10 @@ export class AccountsResource {
     this.#client.assertNotTerminated();
     const wasm = await this.#getWasm();
 
-    if (typeof input === "string") {
-      // Import by ID (hex or bech32 string)
+    // Early exit for string, Account, and AccountHeader types before property
+    // checks, preventing misrouting if a WASM object ever gains a .file or .seed
+    // property. Bare AccountId (no .id() method) falls through to the fallback.
+    if (typeof input === "string" || typeof input.id === "function") {
       const id = resolveAccountRef(input, wasm);
       await this.#inner.importAccountById(id);
       return await this.#inner.getAccount(id);
@@ -121,9 +167,10 @@ export class AccountsResource {
       );
     }
 
-    throw new Error(
-      "Invalid import input: expected a string, { file }, or { seed }"
-    );
+    // Fallback: treat as AccountRef (string, AccountId, Account, AccountHeader)
+    const id = resolveAccountRef(input, wasm);
+    await this.#inner.importAccountById(id);
+    return await this.#inner.getAccount(id);
   }
 
   async export(ref) {

crates/web-client/js/resources/compiler.js

@@ -0,0 +1,57 @@
+export class CompilerResource {
+  #inner;
+  #getWasm;
+  #client;
+
+  constructor(inner, getWasm, client) {
+    this.#inner = inner;
+    this.#getWasm = getWasm;
+    this.#client = client;
+  }
+
+  /**
+   * Compiles MASM code + slots into an AccountComponent ready for accounts.create().
+   *
+   * @param {{ code: string, slots: StorageSlot[] }} opts
+   * @returns {Promise<AccountComponent>}
+   */
+  async component({ code, slots }) {
+    this.#client.assertNotTerminated();
+    const wasm = await this.#getWasm();
+    const builder = this.#inner.createCodeBuilder();
+    const compiled = builder.compileAccountComponentCode(code);
+    return wasm.AccountComponent.compile(
+      compiled,
+      slots
+    ).withSupportsAllTypes();
+  }
+
+  /**
+   * Compiles a transaction script, optionally linking named libraries inline.
+   *
+   * @param {{ code: string, libraries?: Array<{ namespace: string, code: string, linking?: "dynamic" | "static" }> }} opts
+   * @returns {Promise<TransactionScript>}
+   */
+  async txScript({ code, libraries = [] }) {
+    this.#client.assertNotTerminated();
+    // Ensure WASM is initialized (result unused — only #inner needs it)
+    await this.#getWasm();
+    const builder = this.#inner.createCodeBuilder();
+    for (const lib of libraries) {
+      if (lib && typeof lib.namespace === "string") {
+        // Inline { namespace, code, linking? } — build and link automatically
+        const built = builder.buildLibrary(lib.namespace, lib.code);
+        if (lib.linking === "static") {
+          builder.linkStaticLibrary(built);
+        } else {
+          // Default: "dynamic" — matches existing tutorial behavior
+          builder.linkDynamicLibrary(built);
+        }
+      } else {
+        // Pre-built library object — link dynamically
+        builder.linkDynamicLibrary(lib);
+      }
+    }
+    return builder.compileTxScript(code);
+  }
+}

crates/web-client/js/resources/notes.js

@@ -1,4 +1,8 @@
-import { resolveAccountRef, resolveAddress } from "../utils.js";
+import {
+  resolveAccountRef,
+  resolveAddress,
+  resolveNoteIdHex,
+} from "../utils.js";
 
 export class NotesResource {
   #inner;
@@ -20,7 +24,7 @@ export class NotesResource {
 
   async get(noteId) {
     this.#client.assertNotTerminated();
-    const result = await this.#inner.getInputNote(noteId);
+    const result = await this.#inner.getInputNote(resolveNoteIdHex(noteId));
     return result ?? null;
   }
 
@@ -35,7 +39,8 @@ export class NotesResource {
     this.#client.assertNotTerminated();
     const wasm = await this.#getWasm();
     const accountId = resolveAccountRef(opts.account, wasm);
-    return await this.#inner.getConsumableNotes(accountId);
+    const consumable = await this.#inner.getConsumableNotes(accountId);
+    return consumable.map((c) => c.inputNoteRecord());
   }
 
   async import(noteFile) {
@@ -47,7 +52,7 @@ export class NotesResource {
     this.#client.assertNotTerminated();
     const wasm = await this.#getWasm();
     const format = opts?.format ?? wasm.NoteExportFormat.Full;
-    return await this.#inner.exportNoteFile(noteId, format);
+    return await this.#inner.exportNoteFile(resolveNoteIdHex(noteId), format);
   }
 
   async fetchPrivate(opts) {
@@ -62,9 +67,10 @@ export class NotesResource {
   async sendPrivate(opts) {
     this.#client.assertNotTerminated();
     const wasm = await this.#getWasm();
-    const noteRecord = await this.#inner.getInputNote(opts.noteId);
+    const noteHex = resolveNoteIdHex(opts.noteId);
+    const noteRecord = await this.#inner.getInputNote(noteHex);
     if (!noteRecord) {
-      throw new Error(`Note not found: ${opts.noteId}`);
+      throw new Error(`Note not found: ${noteHex}`);
     }
     const note = noteRecord.toNote();
     const address = resolveAddress(opts.to, wasm);
@@ -78,7 +84,9 @@ function buildNoteFilter(query, wasm) {
   }
 
   if (query.ids) {
-    const noteIds = query.ids.map((id) => wasm.NoteId.fromHex(id));
+    const noteIds = query.ids.map((id) =>
+      wasm.NoteId.fromHex(resolveNoteIdHex(id))
+    );
     return new wasm.NoteFilter(wasm.NoteFilterTypes.List, noteIds);
   }