@miden-sdk/miden-sdk 0.14.4 → 0.15.0-alpha.4

package/js/resources/accounts.js

@@ -0,0 +1,224 @@
+import {
+  resolveAccountRef,
+  resolveStorageMode,
+  resolveAuthScheme,
+  resolveAccountMutability,
+  hashSeed,
+} from "../utils.js";
+
+export class AccountsResource {
+  #inner;
+  #getWasm;
+  #client;
+
+  constructor(inner, getWasm, client) {
+    this.#inner = inner;
+    this.#getWasm = getWasm;
+    this.#client = client;
+  }
+
+  async create(opts) {
+    this.#client.assertNotTerminated();
+    const wasm = await this.#getWasm();
+
+    const type = opts?.type;
+
+    if (
+      type === 0 ||
+      type === 1 ||
+      type === "FungibleFaucet" ||
+      type === "NonFungibleFaucet"
+    ) {
+      const storageMode = resolveStorageMode(opts.storage ?? "public", wasm);
+      const authScheme = resolveAuthScheme(opts.auth, wasm);
+      return await this.#inner.newFaucet(
+        storageMode,
+        type === 1 || type === "NonFungibleFaucet",
+        opts.symbol,
+        opts.decimals,
+        BigInt(opts.maxSupply),
+        authScheme
+      );
+    } else if (
+      type === "ImmutableContract" ||
+      type === "MutableContract" ||
+      opts?.components // Contracts are distinguished from wallets by having components
+    ) {
+      return await this.#createContract(opts, wasm);
+    } else {
+      // Default: wallet (mutable or immutable based on type)
+      const mutable = resolveAccountMutability(opts?.type);
+      const storageMode = resolveStorageMode(opts?.storage ?? "private", wasm);
+      const authScheme = resolveAuthScheme(opts?.auth, wasm);
+      const seed = opts?.seed ? await hashSeed(opts.seed) : undefined;
+      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)");
+
+    // Default to immutable when type is omitted (safer for contracts)
+    const mutable = opts.type === "MutableContract" || opts.type === 3;
+    const accountTypeEnum = mutable
+      ? wasm.AccountType.RegularAccountUpdatableCode
+      : wasm.AccountType.RegularAccountImmutableCode;
+    const storageMode = resolveStorageMode(opts.storage ?? "public", wasm);
+    const authComponent =
+      wasm.AccountComponent.createAuthComponentFromSecretKey(opts.auth);
+
+    // Schema commitment from `build()` is not a substitute for contract code; require explicit
+    // `components` so auth-only contracts are rejected at this layer.
+    const components = opts.components ?? [];
+    if (components.length === 0) {
+      throw new Error(
+        "Contract accounts require at least one non-auth procedure: pass at least one entry in `components`."
+      );
+    }
+
+    let builder = new wasm.AccountBuilder(opts.seed)
+      .accountType(accountTypeEnum)
+      .storageMode(storageMode)
+      .withAuthComponent(authComponent);
+
+    for (const component of components) {
+      builder = builder.withComponent(component);
+    }
+
+    const built = builder.build();
+    const account = built.account;
+
+    await this.#inner.newAccountWithSecretKey(account, opts.auth);
+    return account;
+  }
+
+  async insert({ account, overwrite = false }) {
+    this.#client.assertNotTerminated();
+    await this.#inner.newAccount(account, overwrite);
+  }
+
+  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();
+    const id = resolveAccountRef(ref, wasm);
+    const account = await this.#inner.getAccount(id);
+    return account ?? null;
+  }
+
+  async list() {
+    this.#client.assertNotTerminated();
+    return await this.#inner.getAccounts();
+  }
+
+  async getDetails(ref) {
+    this.#client.assertNotTerminated();
+    const wasm = await this.#getWasm();
+    const id = resolveAccountRef(ref, wasm);
+    const account = await this.#inner.getAccount(id);
+    if (!account) {
+      throw new Error(`Account not found: ${id.toString()}`);
+    }
+    const keys = this.#inner.keystore
+      ? await this.#inner.keystore.getCommitments(id)
+      : await this.#inner.getPublicKeyCommitmentsOfAccount(id);
+    return {
+      account,
+      vault: account.vault(),
+      storage: account.storage(),
+      code: account.code() ?? null,
+      keys,
+    };
+  }
+
+  async getBalance(accountRef, tokenRef) {
+    this.#client.assertNotTerminated();
+    const wasm = await this.#getWasm();
+    const accountId = resolveAccountRef(accountRef, wasm);
+    const faucetId = resolveAccountRef(tokenRef, wasm);
+    const reader = await this.#inner.accountReader(accountId);
+    return await reader.getBalance(faucetId);
+  }
+
+  async import(input) {
+    this.#client.assertNotTerminated();
+    const wasm = await this.#getWasm();
+
+    // 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);
+    }
+
+    if (input.file) {
+      // Extract accountId before importAccountFile — WASM consumes the
+      // AccountFile by value, invalidating the JS wrapper after the call.
+      const accountId =
+        typeof input.file.accountId === "function"
+          ? input.file.accountId()
+          : null;
+      await this.#inner.importAccountFile(input.file);
+      if (accountId) {
+        return await this.#inner.getAccount(accountId);
+      }
+      throw new Error(
+        "Could not determine account ID from AccountFile. " +
+          "Ensure the file contains a valid account."
+      );
+    }
+
+    if (input.seed) {
+      // Import public account from seed
+      const authScheme = resolveAuthScheme(input.auth, wasm);
+      const mutable = resolveAccountMutability(input.type);
+      return await this.#inner.importPublicAccountFromSeed(
+        input.seed,
+        mutable,
+        authScheme
+      );
+    }
+
+    // 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) {
+    this.#client.assertNotTerminated();
+    const wasm = await this.#getWasm();
+    const id = resolveAccountRef(ref, wasm);
+    return await this.#inner.exportAccountFile(id);
+  }
+
+  async addAddress(ref, addr) {
+    this.#client.assertNotTerminated();
+    const wasm = await this.#getWasm();
+    const id = resolveAccountRef(ref, wasm);
+    const address = wasm.Address.fromBech32(addr);
+    await this.#inner.insertAccountAddress(id, address);
+  }
+
+  async removeAddress(ref, addr) {
+    this.#client.assertNotTerminated();
+    const wasm = await this.#getWasm();
+    const id = resolveAccountRef(ref, wasm);
+    const address = wasm.Address.fromBech32(addr);
+    await this.#inner.removeAccountAddress(id, address);
+  }
+}

package/js/resources/compiler.js

@@ -0,0 +1,74 @@
+export class CompilerResource {
+  #inner;
+  #getWasm;
+  #client;
+
+  constructor(inner, getWasm, client = null) {
+    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[], supportAllTypes?: boolean }} opts
+   * @returns {Promise<AccountComponent>}
+   */
+  async component({ code, slots = [], supportAllTypes = true }) {
+    this.#client?.assertNotTerminated();
+    const wasm = await this.#getWasm();
+    const builder = await this.#inner.createCodeBuilder();
+    const compiled = builder.compileAccountComponentCode(code);
+    const component = wasm.AccountComponent.compile(compiled, slots);
+    return supportAllTypes ? component.withSupportsAllTypes() : component;
+  }
+
+  /**
+   * 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 = await this.#inner.createCodeBuilder();
+    linkLibraries(builder, libraries);
+    return builder.compileTxScript(code);
+  }
+
+  /**
+   * Compiles a note script, optionally linking named libraries inline.
+   *
+   * @param {{ code: string, libraries?: Array<{ namespace: string, code: string, linking?: "dynamic" | "static" }> }} opts
+   * @returns {Promise<NoteScript>}
+   */
+  async noteScript({ code, libraries = [] }) {
+    this.#client?.assertNotTerminated();
+    await this.#getWasm();
+    const builder = await this.#inner.createCodeBuilder();
+    linkLibraries(builder, libraries);
+    return builder.compileNoteScript(code);
+  }
+}
+
+// Builds and links each library entry against `builder`. Inline
+// `{ namespace, code, linking? }` entries are built via `buildLibrary` and
+// linked according to `linking` (defaulting to dynamic, matching tutorial
+// behavior). Pre-built library objects are linked dynamically.
+function linkLibraries(builder, libraries) {
+  for (const lib of libraries) {
+    if (lib && typeof lib.namespace === "string") {
+      const built = builder.buildLibrary(lib.namespace, lib.code);
+      if (lib.linking === "static") {
+        builder.linkStaticLibrary(built);
+      } else {
+        builder.linkDynamicLibrary(built);
+      }
+    } else {
+      builder.linkDynamicLibrary(lib);
+    }
+  }
+}

package/js/resources/keystore.js

@@ -0,0 +1,54 @@
+export class KeystoreResource {
+  #inner;
+  #client;
+
+  constructor(inner, client) {
+    this.#inner = inner;
+    this.#client = client;
+  }
+
+  async insert(accountId, secretKey) {
+    this.#client.assertNotTerminated();
+    if (this.#inner.keystore) {
+      return await this.#inner.keystore.insert(accountId, secretKey);
+    }
+    return await this.#inner.addAccountSecretKeyToWebStore(
+      accountId,
+      secretKey
+    );
+  }
+
+  async get(pubKeyCommitment) {
+    this.#client.assertNotTerminated();
+    if (this.#inner.keystore) {
+      return await this.#inner.keystore.get(pubKeyCommitment);
+    }
+    return await this.#inner.getAccountAuthByPubKeyCommitment(pubKeyCommitment);
+  }
+
+  async remove(pubKeyCommitment) {
+    this.#client.assertNotTerminated();
+    if (this.#inner.keystore) {
+      return await this.#inner.keystore.remove(pubKeyCommitment);
+    }
+    throw new Error("remove() is not supported on this platform");
+  }
+
+  async getCommitments(accountId) {
+    this.#client.assertNotTerminated();
+    if (this.#inner.keystore) {
+      return await this.#inner.keystore.getCommitments(accountId);
+    }
+    return await this.#inner.getPublicKeyCommitmentsOfAccount(accountId);
+  }
+
+  async getAccountId(pubKeyCommitment) {
+    this.#client.assertNotTerminated();
+    if (this.#inner.keystore) {
+      return await this.#inner.keystore.getAccountId(pubKeyCommitment);
+    }
+    const account =
+      await this.#inner.getAccountByKeyCommitment(pubKeyCommitment);
+    return account ? account.id() : undefined;
+  }
+}

package/js/resources/notes.js

@@ -0,0 +1,124 @@
+import {
+  resolveAccountRef,
+  resolveAddress,
+  resolveNoteIdHex,
+} from "../utils.js";
+
+export class NotesResource {
+  #inner;
+  #getWasm;
+  #client;
+
+  constructor(inner, getWasm, client) {
+    this.#inner = inner;
+    this.#getWasm = getWasm;
+    this.#client = client;
+  }
+
+  async list(query) {
+    this.#client.assertNotTerminated();
+    const wasm = await this.#getWasm();
+    const filter = buildNoteFilter(query, wasm);
+    return await this.#inner.getInputNotes(filter);
+  }
+
+  async get(noteId) {
+    this.#client.assertNotTerminated();
+    const result = await this.#inner.getInputNote(resolveNoteIdHex(noteId));
+    return result ?? null;
+  }
+
+  async listSent(query) {
+    this.#client.assertNotTerminated();
+    const wasm = await this.#getWasm();
+    const filter = buildNoteFilter(query, wasm);
+    return await this.#inner.getOutputNotes(filter);
+  }
+
+  async listAvailable(opts) {
+    this.#client.assertNotTerminated();
+    const wasm = await this.#getWasm();
+    const accountId = resolveAccountRef(opts.account, wasm);
+    const consumable = await this.#inner.getConsumableNotes(accountId);
+    return consumable.map((c) => c.inputNoteRecord());
+  }
+
+  async import(noteFile) {
+    this.#client.assertNotTerminated();
+    return await this.#inner.importNoteFile(noteFile);
+  }
+
+  async export(noteId, opts) {
+    this.#client.assertNotTerminated();
+    const wasm = await this.#getWasm();
+    const format = opts?.format ?? wasm.NoteExportFormat.Full;
+    return await this.#inner.exportNoteFile(resolveNoteIdHex(noteId), format);
+  }
+
+  async fetchPrivate(opts) {
+    this.#client.assertNotTerminated();
+    if (opts?.mode === "all") {
+      await this.#inner.fetchAllPrivateNotes();
+    } else {
+      await this.#inner.fetchPrivateNotes();
+    }
+  }
+
+  async sendPrivate(opts) {
+    this.#client.assertNotTerminated();
+    const wasm = await this.#getWasm();
+
+    let note;
+    const input = opts.note;
+    // Check if input is a Note object (has .id() and .assets() but not .toNote())
+    if (
+      input &&
+      typeof input === "object" &&
+      typeof input.id === "function" &&
+      typeof input.assets === "function" &&
+      typeof input.toNote !== "function"
+    ) {
+      note = input;
+    } else {
+      const noteHex = resolveNoteIdHex(input);
+      const noteRecord = await this.#inner.getInputNote(noteHex);
+      if (!noteRecord) {
+        throw new Error(`Note not found: ${noteHex}`);
+      }
+      note = noteRecord.toNote();
+    }
+
+    const address = resolveAddress(opts.to, wasm);
+    await this.#inner.sendPrivateNote(note, address);
+  }
+}
+
+function buildNoteFilter(query, wasm) {
+  if (!query) {
+    return new wasm.NoteFilter(wasm.NoteFilterTypes.All, undefined);
+  }
+
+  if (query.ids) {
+    const noteIds = query.ids.map((id) =>
+      wasm.NoteId.fromHex(resolveNoteIdHex(id))
+    );
+    return new wasm.NoteFilter(wasm.NoteFilterTypes.List, noteIds);
+  }
+
+  if (query.status) {
+    const statusMap = {
+      consumed: wasm.NoteFilterTypes.Consumed,
+      committed: wasm.NoteFilterTypes.Committed,
+      expected: wasm.NoteFilterTypes.Expected,
+      processing: wasm.NoteFilterTypes.Processing,
+      unverified: wasm.NoteFilterTypes.Unverified,
+    };
+    const filterType = statusMap[query.status];
+    if (filterType === undefined) {
+      throw new Error(`Unknown note status: ${query.status}`);
+    }
+    return new wasm.NoteFilter(filterType, undefined);
+  }
+
+  return new wasm.NoteFilter(wasm.NoteFilterTypes.All, undefined);
+}

package/js/resources/settings.js

@@ -0,0 +1,30 @@
+export class SettingsResource {
+  #inner;
+  #client;
+
+  constructor(inner, _getWasm, client) {
+    this.#inner = inner;
+    this.#client = client;
+  }
+
+  async get(key) {
+    this.#client.assertNotTerminated();
+    const value = await this.#inner.getSetting(key);
+    return value === undefined ? null : value;
+  }
+
+  async set(key, value) {
+    this.#client.assertNotTerminated();
+    await this.#inner.setSetting(key, value);
+  }
+
+  async remove(key) {
+    this.#client.assertNotTerminated();
+    await this.#inner.removeSetting(key);
+  }
+
+  async listKeys() {
+    this.#client.assertNotTerminated();
+    return await this.#inner.listSettingKeys();
+  }
+}

package/js/resources/tags.js

@@ -0,0 +1,31 @@
+export class TagsResource {
+  #inner;
+  #client;
+
+  constructor(inner, getWasm, client) {
+    this.#inner = inner;
+    this.#client = client;
+  }
+
+  async add(tag) {
+    this.#client.assertNotTerminated();
+    await this.#inner.addTag(String(tag));
+  }
+
+  async remove(tag) {
+    this.#client.assertNotTerminated();
+    await this.#inner.removeTag(String(tag));
+  }
+
+  async list() {
+    this.#client.assertNotTerminated();
+    const tags = await this.#inner.listTags();
+    return Array.from(tags).map((t) => {
+      const n = Number(t);
+      if (Number.isNaN(n)) {
+        throw new Error(`Invalid tag value: ${t}`);
+      }
+      return n;
+    });
+  }
+}