@miden-sdk/miden-sdk 0.15.4 → 0.15.5

package/dist/mt/api-types.d.ts

@@ -30,6 +30,9 @@ import type {
   AccountStorageRequirements,
   TransactionScript,
   NoteScript,
+  NoteRecipient,
+  NoteExecutionHint,
+  NetworkAccountTarget,
   AdviceInputs,
   FeltArray,
   PswapLineageRecord,
@@ -357,6 +360,48 @@ export interface SendResult {
   result: TransactionResult;
 }
 
+/**
+ * Options for {@link TransactionsResource.createNetworkNote} and the standalone
+ * {@link buildNetworkNote}. Builds a Public, custom-script note carrying a
+ * `NetworkAccountTarget` attachment so a public network account auto-consumes it.
+ *
+ * Provide exactly one of `recipient` or `script`.
+ */
+export interface NetworkNoteOptions extends TransactionOptions {
+  /** Account that creates, funds, and submits the note (the executing sender). */
+  account: AccountRef;
+  /**
+   * The network account the note targets. Any account reference, or a pre-built
+   * `NetworkAccountTarget`. Encoded as the note's `NetworkAccountTarget`
+   * attachment — this is what makes `isNetworkNote()` true.
+   */
+  target: AccountRef | NetworkAccountTarget;
+  /** Execution hint when `target` is an account reference. Defaults to `always`. */
+  executionHint?: NoteExecutionHint;
+  /**
+   * Recipient carrying the note's custom consumption script. Build with
+   * `new NoteRecipient(serialNum, noteScript, noteStorage)`, or omit and pass
+   * `script` to have the recipient built for you.
+   */
+  recipient?: NoteRecipient;
+  /** Custom consumption script; the recipient is built with a fresh serial number. */
+  script?: NoteScript;
+  /** Note storage / inputs the script reads (used with `script`). */
+  inputs?: bigint[];
+  /** Assets locked into the note. Optional — a note may carry no assets. */
+  assets?: Asset | Asset[];
+  /** Extra attachment payload appended AFTER the required `NetworkAccountTarget`. */
+  attachment?: bigint[];
+}
+
+/** Result of {@link TransactionsResource.createNetworkNote}. */
+export interface NetworkNoteResult {
+  txId: TransactionId;
+  /** The built network note (read its id / attachments). */
+  note: Note;
+  result: TransactionResult;
+}
+
 /** Result of methods that previously returned bare TransactionId. */
 export interface TransactionSubmitResult {
   txId: TransactionId;
@@ -823,6 +868,13 @@ export interface TransactionsResource {
    * @param options - Mint options including the faucet, recipient, and amount.
    */
   mint(options: MintOptions): Promise<TransactionSubmitResult>;
+  /**
+   * Builds a Public custom-script note carrying a `NetworkAccountTarget`
+   * attachment, submits it as an own output note, and (optionally) waits for
+   * confirmation. The submitted note satisfies `Note.isNetworkNote()`, so a
+   * public network account will auto-consume it.
+   */
+  createNetworkNote(options: NetworkNoteOptions): Promise<NetworkNoteResult>;
   /**
    * Bridge a fungible asset out to another network via the AggLayer. Emits a
    * single public B2AGG (Bridge-to-AggLayer) note that the bridge account
@@ -1303,6 +1355,13 @@ export declare function createP2IDENote(
   options: P2IDEOptions
 ): ReturnType<WasmModule["Note"]["createP2IDENote"]>;
 
+/**
+ * Builds (without submitting) a Public custom-script note carrying a
+ * `NetworkAccountTarget` attachment. Provide exactly one of `recipient` or
+ * `script`.
+ */
+export declare function buildNetworkNote(opts: NetworkNoteOptions): Note;
+
 /** Builds a swap tag for note matching. Returns a NoteTag (use `.asU32()` for the numeric value). */
 export declare function buildSwapTag(
   options: BuildSwapTagOptions

package/dist/mt/crates/miden_client_web.d.ts

@@ -2113,6 +2113,44 @@ export class MerklePath {
     verify(index: bigint, node: Word, root: Word): boolean;
 }
 
+/**
+ * Targets a note at a public network account so the operator auto-consumes it.
+ *
+ * A note is a network note when it is `Public` and carries a valid
+ * `NetworkAccountTarget` attachment (see `Note.isNetworkNote`).
+ */
+export class NetworkAccountTarget {
+    free(): void;
+    [Symbol.dispose](): void;
+    /**
+     * Returns the note execution hint.
+     */
+    executionHint(): NoteExecutionHint;
+    /**
+     * Decodes a `NoteAttachment` back into a `NetworkAccountTarget`.
+     *
+     * # Errors
+     * Errors if the attachment is not a valid network-account-target attachment.
+     */
+    static fromAttachment(attachment: NoteAttachment): NetworkAccountTarget;
+    /**
+     * Creates a target for the given network account. `executionHint` defaults
+     * to `NoteExecutionHint.always()`.
+     *
+     * # Errors
+     * Errors if `account_id` is not a public account.
+     */
+    constructor(account_id: AccountId, execution_hint?: NoteExecutionHint | null);
+    /**
+     * Returns the targeted network account id.
+     */
+    targetId(): AccountId;
+    /**
+     * Encodes this target as a `NoteAttachment`.
+     */
+    toAttachment(): NoteAttachment;
+}
+
 /**
  * The identifier of a Miden network.
  */
@@ -2193,6 +2231,10 @@ export class Note {
      * Returns the assets locked inside the note.
      */
     assets(): NoteAssets;
+    /**
+     * Returns the note's attachments.
+     */
+    attachments(): NoteAttachment[];
     /**
      * Returns the commitment to the note (its ID).
      *
@@ -2228,6 +2270,11 @@ export class Note {
      * Returns the unique identifier of the note.
      */
     id(): NoteId;
+    /**
+     * Returns true if the note is a network note (public + a valid
+     * `NetworkAccountTarget` attachment).
+     */
+    isNetworkNote(): boolean;
     /**
      * Returns the public metadata associated with the note.
      */
@@ -2256,6 +2303,14 @@ export class Note {
      * Serializes the note into bytes.
      */
     serialize(): Uint8Array;
+    /**
+     * Creates a note carrying the provided attachments, using the metadata's
+     * sender / note type / tag (attachments on the metadata itself are ignored).
+     *
+     * # Errors
+     * Errors if the attachment set is invalid (too many attachments or words).
+     */
+    static withAttachments(note_assets: NoteAssets, note_metadata: NoteMetadata, note_recipient: NoteRecipient, attachments: NoteAttachment[]): Note;
 }
 
 export class NoteAndArgs {
@@ -2862,6 +2917,11 @@ export class NoteRecipient {
      * Returns the digest of the recipient data (used in the note commitment).
      */
     digest(): Word;
+    /**
+     * Creates a recipient from a script and storage, generating a fresh random
+     * serial number (the secret that prevents double-spends).
+     */
+    static fromScript(note_script: NoteScript, storage: NoteStorage): NoteRecipient;
     /**
      * Creates a note recipient from its serial number, script, and storage.
      */

package/dist/mt/docs-entry.d.ts

@@ -18,6 +18,7 @@ export {
   EthAddress,
   Felt,
   InputNoteRecord,
+  NetworkAccountTarget,
   Note,
   NoteExportFormat,
   NoteFile,

package/dist/mt/eager.js

@@ -1,6 +1,6 @@
 import { getWasmOrThrow } from './index.js';
 export { AccountType, AuthScheme, CompilerResource, Linking, MidenArrays, MidenClient, MockWasmWebClient, MockWasmWebClient as MockWebClient, NoteVisibility, StorageMode, StorageResult, StorageView, WasmWebClient, buildSwapTag, createP2IDENote, createP2IDNote, withSyncLock, wordToBigInt } from './index.js';
-export { Account, AccountArray, AccountBuilder, AccountBuilderResult, AccountCode, AccountComponent, AccountComponentCode, AccountDelta, AccountFile, AccountHeader, AccountId, AccountIdArray, AccountInterface, AccountProof, AccountReader, AccountStatus, AccountStorage, AccountStorageDelta, AccountStorageMode, AccountStorageRequirements, AccountVaultDelta, Address, AdviceInputs, AdviceMap, AssetVault, AuthFalcon512RpoMultisigConfig, AuthSecretKey, BasicFungibleFaucetComponent, BlockHeader, CodeBuilder, CommittedNote, ConsumableNoteRecord, Endpoint, EthAddress, ExecutedTransaction, Felt, FeltArray, FetchedAccount, FetchedNote, FlattenedU8Vec, ForeignAccount, ForeignAccountArray, FungibleAsset, FungibleAssetDelta, FungibleAssetDeltaItem, GetProceduresResultItem, InputNote, InputNoteRecord, InputNoteState, InputNotes, IntoUnderlyingByteSource, IntoUnderlyingSink, IntoUnderlyingSource, JsAccountUpdate, JsSettingMutation, JsStateSyncUpdate, JsStorageMapEntry, JsStorageSlot, JsVaultAsset, Library, MerklePath, NetworkId, NetworkNoteStatusInfo, NetworkType, Note, NoteAndArgs, NoteAndArgsArray, NoteArray, NoteAssets, NoteAttachment, NoteAttachmentScheme, NoteConsumability, NoteConsumptionStatus, NoteDetails, NoteDetailsAndTag, NoteDetailsAndTagArray, NoteExecutionHint, NoteExportFormat, NoteFile, NoteFilter, NoteFilterTypes, NoteHeader, NoteId, NoteIdAndArgs, NoteIdAndArgsArray, NoteInclusionProof, NoteLocation, NoteMetadata, NoteRecipient, NoteRecipientArray, NoteScript, NoteStorage, NoteSyncBlock, NoteSyncInfo, NoteTag, NoteType, OutputNote, OutputNoteArray, OutputNoteRecord, OutputNoteState, OutputNotes, Package, PartialNote, Poseidon2, ProcedureThreshold, Program, ProvenTransaction, PswapLineageRecord, PswapLineageState, PublicKey, RpcClient, Rpo256, SerializedInputNoteData, SerializedOutputNoteData, SerializedTransactionData, Signature, SigningInputs, SigningInputsType, SlotAndKeys, SparseMerklePath, StorageMap, StorageMapEntry, StorageMapEntryJs, StorageMapInfo, StorageMapUpdate, StorageSlot, StorageSlotArray, SyncSummary, TestUtils, TokenSymbol, TransactionArgs, TransactionFilter, TransactionId, TransactionProver, TransactionRecord, TransactionRequest, TransactionRequestBuilder, TransactionResult, TransactionScript, TransactionScriptInputPair, TransactionScriptInputPairArray, TransactionStatus, TransactionStoreUpdate, TransactionSummary, WebClient, WebKeystoreApi, Word, createAuthFalcon512RpoMultisig, exportStore, importStore, initSync, initThreadPool, mtProbeAsync, mtProbeSync, parallelSumBench, rayonThreadCount, sequentialSumBench, setupLogging, wbg_rayon_PoolBuilder, wbg_rayon_start_worker } from './Cargo-DjVnfWKi.js';
+export { Account, AccountArray, AccountBuilder, AccountBuilderResult, AccountCode, AccountComponent, AccountComponentCode, AccountDelta, AccountFile, AccountHeader, AccountId, AccountIdArray, AccountInterface, AccountProof, AccountReader, AccountStatus, AccountStorage, AccountStorageDelta, AccountStorageMode, AccountStorageRequirements, AccountVaultDelta, Address, AdviceInputs, AdviceMap, AssetVault, AuthFalcon512RpoMultisigConfig, AuthSecretKey, BasicFungibleFaucetComponent, BlockHeader, CodeBuilder, CommittedNote, ConsumableNoteRecord, Endpoint, EthAddress, ExecutedTransaction, Felt, FeltArray, FetchedAccount, FetchedNote, FlattenedU8Vec, ForeignAccount, ForeignAccountArray, FungibleAsset, FungibleAssetDelta, FungibleAssetDeltaItem, GetProceduresResultItem, InputNote, InputNoteRecord, InputNoteState, InputNotes, IntoUnderlyingByteSource, IntoUnderlyingSink, IntoUnderlyingSource, JsAccountUpdate, JsSettingMutation, JsStateSyncUpdate, JsStorageMapEntry, JsStorageSlot, JsVaultAsset, Library, MerklePath, NetworkAccountTarget, NetworkId, NetworkNoteStatusInfo, NetworkType, Note, NoteAndArgs, NoteAndArgsArray, NoteArray, NoteAssets, NoteAttachment, NoteAttachmentScheme, NoteConsumability, NoteConsumptionStatus, NoteDetails, NoteDetailsAndTag, NoteDetailsAndTagArray, NoteExecutionHint, NoteExportFormat, NoteFile, NoteFilter, NoteFilterTypes, NoteHeader, NoteId, NoteIdAndArgs, NoteIdAndArgsArray, NoteInclusionProof, NoteLocation, NoteMetadata, NoteRecipient, NoteRecipientArray, NoteScript, NoteStorage, NoteSyncBlock, NoteSyncInfo, NoteTag, NoteType, OutputNote, OutputNoteArray, OutputNoteRecord, OutputNoteState, OutputNotes, Package, PartialNote, Poseidon2, ProcedureThreshold, Program, ProvenTransaction, PswapLineageRecord, PswapLineageState, PublicKey, RpcClient, Rpo256, SerializedInputNoteData, SerializedOutputNoteData, SerializedTransactionData, Signature, SigningInputs, SigningInputsType, SlotAndKeys, SparseMerklePath, StorageMap, StorageMapEntry, StorageMapEntryJs, StorageMapInfo, StorageMapUpdate, StorageSlot, StorageSlotArray, SyncSummary, TestUtils, TokenSymbol, TransactionArgs, TransactionFilter, TransactionId, TransactionProver, TransactionRecord, TransactionRequest, TransactionRequestBuilder, TransactionResult, TransactionScript, TransactionScriptInputPair, TransactionScriptInputPairArray, TransactionStatus, TransactionStoreUpdate, TransactionSummary, WebClient, WebKeystoreApi, Word, createAuthFalcon512RpoMultisig, exportStore, importStore, initSync, initThreadPool, mtProbeAsync, mtProbeSync, parallelSumBench, rayonThreadCount, sequentialSumBench, setupLogging, wbg_rayon_PoolBuilder, wbg_rayon_start_worker } from './Cargo-C001gt8g.js';
 import './wasm.js';
 
 // Eager entry point for @miden-sdk/miden-sdk (browser builds).

package/dist/mt/index.js

@@ -1,5 +1,5 @@
 import loadWasm from './wasm.js';
-export { Account, AccountArray, AccountBuilder, AccountBuilderResult, AccountCode, AccountComponent, AccountComponentCode, AccountDelta, AccountFile, AccountHeader, AccountId, AccountIdArray, AccountInterface, AccountProof, AccountReader, AccountStatus, AccountStorage, AccountStorageDelta, AccountStorageMode, AccountStorageRequirements, AccountVaultDelta, Address, AdviceInputs, AdviceMap, AssetVault, AuthFalcon512RpoMultisigConfig, AuthSecretKey, BasicFungibleFaucetComponent, BlockHeader, CodeBuilder, CommittedNote, ConsumableNoteRecord, Endpoint, EthAddress, ExecutedTransaction, Felt, FeltArray, FetchedAccount, FetchedNote, FlattenedU8Vec, ForeignAccount, ForeignAccountArray, FungibleAsset, FungibleAssetDelta, FungibleAssetDeltaItem, GetProceduresResultItem, InputNote, InputNoteRecord, InputNoteState, InputNotes, IntoUnderlyingByteSource, IntoUnderlyingSink, IntoUnderlyingSource, JsAccountUpdate, JsSettingMutation, JsStateSyncUpdate, JsStorageMapEntry, JsStorageSlot, JsVaultAsset, Library, MerklePath, NetworkId, NetworkNoteStatusInfo, NetworkType, Note, NoteAndArgs, NoteAndArgsArray, NoteArray, NoteAssets, NoteAttachment, NoteAttachmentScheme, NoteConsumability, NoteConsumptionStatus, NoteDetails, NoteDetailsAndTag, NoteDetailsAndTagArray, NoteExecutionHint, NoteExportFormat, NoteFile, NoteFilter, NoteFilterTypes, NoteHeader, NoteId, NoteIdAndArgs, NoteIdAndArgsArray, NoteInclusionProof, NoteLocation, NoteMetadata, NoteRecipient, NoteRecipientArray, NoteScript, NoteStorage, NoteSyncBlock, NoteSyncInfo, NoteTag, NoteType, OutputNote, OutputNoteArray, OutputNoteRecord, OutputNoteState, OutputNotes, Package, PartialNote, Poseidon2, ProcedureThreshold, Program, ProvenTransaction, PswapLineageRecord, PswapLineageState, PublicKey, RpcClient, Rpo256, SerializedInputNoteData, SerializedOutputNoteData, SerializedTransactionData, Signature, SigningInputs, SigningInputsType, SlotAndKeys, SparseMerklePath, StorageMap, StorageMapEntry, StorageMapEntryJs, StorageMapInfo, StorageMapUpdate, StorageSlot, StorageSlotArray, SyncSummary, TestUtils, TokenSymbol, TransactionArgs, TransactionFilter, TransactionId, TransactionProver, TransactionRecord, TransactionRequest, TransactionRequestBuilder, TransactionResult, TransactionScript, TransactionScriptInputPair, TransactionScriptInputPairArray, TransactionStatus, TransactionStoreUpdate, TransactionSummary, WebClient, WebKeystoreApi, Word, createAuthFalcon512RpoMultisig, exportStore, importStore, initSync, initThreadPool, mtProbeAsync, mtProbeSync, parallelSumBench, rayonThreadCount, sequentialSumBench, setupLogging, wbg_rayon_PoolBuilder, wbg_rayon_start_worker } from './Cargo-DjVnfWKi.js';
+export { Account, AccountArray, AccountBuilder, AccountBuilderResult, AccountCode, AccountComponent, AccountComponentCode, AccountDelta, AccountFile, AccountHeader, AccountId, AccountIdArray, AccountInterface, AccountProof, AccountReader, AccountStatus, AccountStorage, AccountStorageDelta, AccountStorageMode, AccountStorageRequirements, AccountVaultDelta, Address, AdviceInputs, AdviceMap, AssetVault, AuthFalcon512RpoMultisigConfig, AuthSecretKey, BasicFungibleFaucetComponent, BlockHeader, CodeBuilder, CommittedNote, ConsumableNoteRecord, Endpoint, EthAddress, ExecutedTransaction, Felt, FeltArray, FetchedAccount, FetchedNote, FlattenedU8Vec, ForeignAccount, ForeignAccountArray, FungibleAsset, FungibleAssetDelta, FungibleAssetDeltaItem, GetProceduresResultItem, InputNote, InputNoteRecord, InputNoteState, InputNotes, IntoUnderlyingByteSource, IntoUnderlyingSink, IntoUnderlyingSource, JsAccountUpdate, JsSettingMutation, JsStateSyncUpdate, JsStorageMapEntry, JsStorageSlot, JsVaultAsset, Library, MerklePath, NetworkAccountTarget, NetworkId, NetworkNoteStatusInfo, NetworkType, Note, NoteAndArgs, NoteAndArgsArray, NoteArray, NoteAssets, NoteAttachment, NoteAttachmentScheme, NoteConsumability, NoteConsumptionStatus, NoteDetails, NoteDetailsAndTag, NoteDetailsAndTagArray, NoteExecutionHint, NoteExportFormat, NoteFile, NoteFilter, NoteFilterTypes, NoteHeader, NoteId, NoteIdAndArgs, NoteIdAndArgsArray, NoteInclusionProof, NoteLocation, NoteMetadata, NoteRecipient, NoteRecipientArray, NoteScript, NoteStorage, NoteSyncBlock, NoteSyncInfo, NoteTag, NoteType, OutputNote, OutputNoteArray, OutputNoteRecord, OutputNoteState, OutputNotes, Package, PartialNote, Poseidon2, ProcedureThreshold, Program, ProvenTransaction, PswapLineageRecord, PswapLineageState, PublicKey, RpcClient, Rpo256, SerializedInputNoteData, SerializedOutputNoteData, SerializedTransactionData, Signature, SigningInputs, SigningInputsType, SlotAndKeys, SparseMerklePath, StorageMap, StorageMapEntry, StorageMapEntryJs, StorageMapInfo, StorageMapUpdate, StorageSlot, StorageSlotArray, SyncSummary, TestUtils, TokenSymbol, TransactionArgs, TransactionFilter, TransactionId, TransactionProver, TransactionRecord, TransactionRequest, TransactionRequestBuilder, TransactionResult, TransactionScript, TransactionScriptInputPair, TransactionScriptInputPairArray, TransactionStatus, TransactionStoreUpdate, TransactionSummary, WebClient, WebKeystoreApi, Word, createAuthFalcon512RpoMultisig, exportStore, importStore, initSync, initThreadPool, mtProbeAsync, mtProbeSync, parallelSumBench, rayonThreadCount, sequentialSumBench, setupLogging, wbg_rayon_PoolBuilder, wbg_rayon_start_worker } from './Cargo-C001gt8g.js';
 
 const WorkerAction = Object.freeze({
   INIT: "init",
@@ -622,6 +622,97 @@ class TransactionsResource {
     return { txId, note: null, result };
   }
 
+  /**
+   * Builds a Public custom-script note carrying a NetworkAccountTarget
+   * attachment, submits it as an own output note, and optionally waits for
+   * confirmation. Provide exactly one of `recipient` or `script`.
+   */
+  async createNetworkNote(opts) {
+    this.#client.assertNotTerminated();
+    const wasm = await this.#getWasm();
+
+    if (opts.recipient && opts.script) {
+      throw new Error(
+        "createNetworkNote requires exactly one of `recipient` or `script`, not both."
+      );
+    }
+
+    const senderId = resolveAccountRef(opts.account, wasm);
+
+    const target =
+      opts.target instanceof wasm.NetworkAccountTarget
+        ? opts.target
+        : new wasm.NetworkAccountTarget(
+            resolveAccountRef(opts.target, wasm),
+            opts.executionHint
+          );
+
+    const noteAssets = opts.assets
+      ? new wasm.NoteAssets(
+          (Array.isArray(opts.assets) ? opts.assets : [opts.assets]).map(
+            (a) =>
+              new wasm.FungibleAsset(
+                resolveAccountRef(a.token, wasm),
+                BigInt(a.amount)
+              )
+          )
+        )
+      : new wasm.NoteAssets();
+
+    const metadata = new wasm.NoteMetadata(
+      senderId,
+      wasm.NoteType.Public,
+      wasm.NoteTag.withAccountTarget(target.targetId())
+    );
+
+    let recipient = opts.recipient;
+    if (!recipient) {
+      if (!opts.script) {
+        throw new Error(
+          "createNetworkNote requires either `recipient` or `script`."
+        );
+      }
+      const storage = new wasm.NoteStorage(
+        new wasm.FeltArray(
+          (opts.inputs ?? []).map((value) => new wasm.Felt(value))
+        )
+      );
+      recipient = wasm.NoteRecipient.fromScript(opts.script, storage);
+    }
+
+    const attachments = [target.toAttachment()];
+    if (opts.attachment) {
+      attachments.push(new wasm.NoteAttachment(opts.attachment));
+    }
+
+    const note = wasm.Note.withAttachments(
+      noteAssets,
+      metadata,
+      recipient,
+      attachments
+    );
+
+    // NoteArray constructor consumes its elements; use push(&note) to keep
+    // `note` valid so we can return it to the caller.
+    const ownOutputs = new wasm.NoteArray();
+    ownOutputs.push(note);
+    const request = new wasm.TransactionRequestBuilder()
+      .withOwnOutputNotes(ownOutputs)
+      .build();
+
+    const { txId, result } = await this.#submitOrSubmitWithProver(
+      senderId,
+      request,
+      opts.prover
+    );
+
+    if (opts.waitForConfirmation) {
+      await this.waitFor(txId.toHex(), { timeout: opts.timeout });
+    }
+
+    return { txId, note, result };
+  }
+
   async mint(opts) {
     this.#client.assertNotTerminated();
     const wasm = await this.#getWasm();