miden-client-cli 0.14.1

The official command line client for interacting with the Miden network
Documentation
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
use std::io;
use std::sync::Arc;

use clap::{Parser, ValueEnum};
use miden_client::account::AccountId;
use miden_client::asset::{FungibleAsset, NonFungibleDeltaAction};
use miden_client::keystore::Keystore;
use miden_client::note::{
    BlockNumber,
    NoteType as MidenNoteType,
    SwapNote,
    get_input_note_with_id_prefix,
};
use miden_client::store::NoteRecordError;
use miden_client::transaction::{
    ExecutedTransaction,
    InputNote,
    PaymentNoteDescription,
    RawOutputNote,
    SwapTransactionData,
    TransactionRequest,
    TransactionRequestBuilder,
};
use miden_client::{Client, RemoteTransactionProver};
use tracing::info;

use crate::config::CliConfig;
use crate::create_dynamic_table;
use crate::errors::CliError;
use crate::utils::{
    SHARED_TOKEN_DOCUMENTATION,
    get_input_acc_id_by_prefix_or_default,
    load_faucet_details_map,
    parse_account_id,
};

#[derive(Debug, Clone, Copy, ValueEnum)]
pub enum NoteType {
    Public,
    Private,
}

impl From<&NoteType> for MidenNoteType {
    fn from(note_type: &NoteType) -> Self {
        match note_type {
            NoteType::Public => MidenNoteType::Public,
            NoteType::Private => MidenNoteType::Private,
        }
    }
}

/// Mint tokens from a fungible faucet to a wallet.
#[derive(Debug, Parser, Clone)]
pub struct MintCmd {
    /// Target account ID or its hex prefix.
    #[arg(short = 't', long = "target")]
    target_account_id: String,

    /// Asset to be minted.
    #[arg(short, long, help=format!("Asset to be minted.\n{SHARED_TOKEN_DOCUMENTATION}"))]
    asset: String,

    #[arg(short, long, value_enum)]
    note_type: NoteType,
    /// Flag to submit the executed transaction without asking for confirmation.
    #[arg(long, default_value_t = false)]
    force: bool,

    /// Flag to delegate proving to the remote prover specified in the config file.
    #[arg(long, default_value_t = false)]
    delegate_proving: bool,
}

impl MintCmd {
    pub async fn execute<AUTH: Keystore + Sync + 'static>(
        &self,
        mut client: Client<AUTH>,
    ) -> Result<(), CliError> {
        let force = self.force;
        let faucet_details_map = load_faucet_details_map()?;

        let fungible_asset = faucet_details_map.parse_fungible_asset(&client, &self.asset).await?;

        let target_account_id = parse_account_id(&client, self.target_account_id.as_str()).await?;

        let transaction_request = TransactionRequestBuilder::new()
            .build_mint_fungible_asset(
                fungible_asset,
                target_account_id,
                (&self.note_type).into(),
                client.rng(),
            )
            .map_err(|err| {
                CliError::Transaction(err.into(), "Failed to build mint transaction".to_string())
            })?;

        execute_transaction(
            &mut client,
            fungible_asset.faucet_id(),
            transaction_request,
            force,
            self.delegate_proving,
        )
        .await
    }
}

/// Create a pay-to-id transaction.
#[derive(Debug, Parser, Clone)]
pub struct SendCmd {
    /// Sender account ID or its hex prefix. If none is provided, the default account's ID is used
    /// instead.
    #[arg(short = 's', long = "sender")]
    sender_account_id: Option<String>,
    /// Target account ID or its hex prefix.
    #[arg(short = 't', long = "target")]
    target_account_id: String,

    /// Asset to be sent.
    #[arg(short, long, help=format!("Asset to be sent.\n{SHARED_TOKEN_DOCUMENTATION}"))]
    asset: String,

    #[arg(short, long, value_enum)]
    note_type: NoteType,
    /// Flag to submit the executed transaction without asking for confirmation
    #[arg(long, default_value_t = false)]
    force: bool,
    /// Set the recall height for the transaction. If the note wasn't consumed by this height, the
    /// sender may consume it back.
    ///
    /// Setting this flag turns the transaction from a `PayToId` to a `PayToIdWithRecall`.
    #[arg(short, long)]
    recall_height: Option<u32>,

    /// Set the timelock height for the transaction. The note will not be consumable until this
    /// height is reached.
    #[arg(short = 'i', long)]
    timelock_height: Option<u32>,

    /// Flag to delegate proving to the remote prover specified in the config file
    #[arg(long, default_value_t = false)]
    delegate_proving: bool,
}

impl SendCmd {
    pub async fn execute<AUTH: Keystore + Sync + 'static>(
        &self,
        mut client: Client<AUTH>,
    ) -> Result<(), CliError> {
        let force = self.force;

        let faucet_details_map = load_faucet_details_map()?;

        let fungible_asset = faucet_details_map.parse_fungible_asset(&client, &self.asset).await?;

        // try to use either the provided argument or the default account
        let sender_account_id =
            get_input_acc_id_by_prefix_or_default(&client, self.sender_account_id.clone()).await?;
        let target_account_id = parse_account_id(&client, self.target_account_id.as_str()).await?;

        let mut payment_description = PaymentNoteDescription::new(
            vec![fungible_asset.into()],
            sender_account_id,
            target_account_id,
        );

        if let Some(recall_height) = self.recall_height {
            payment_description =
                payment_description.with_reclaim_height(BlockNumber::from(recall_height));
        }

        if let Some(timelock_height) = self.timelock_height {
            payment_description =
                payment_description.with_timelock_height(BlockNumber::from(timelock_height));
        }

        let transaction_request = TransactionRequestBuilder::new()
            .build_pay_to_id(payment_description, (&self.note_type).into(), client.rng())
            .map_err(|err| {
                CliError::Transaction(err.into(), "Failed to build payment transaction".to_string())
            })?;

        execute_transaction(
            &mut client,
            sender_account_id,
            transaction_request,
            force,
            self.delegate_proving,
        )
        .await
    }
}

/// Create a swap transaction.
#[derive(Debug, Parser, Clone)]
pub struct SwapCmd {
    /// Sender account ID or its hex prefix. If none is provided, the default account's ID is used
    /// instead.
    #[arg(short = 's', long = "source")]
    sender_account_id: Option<String>,

    /// Asset offered.
    #[arg(short = 'o', long = "offered-asset", help=format!("Asset offered.\n{SHARED_TOKEN_DOCUMENTATION}"))]
    offered_asset: String,

    /// Asset requested.
    #[arg(short, long, help=format!("Asset requested.\n{SHARED_TOKEN_DOCUMENTATION}"))]
    requested_asset: String,

    /// Visibility of the swap note to be created.
    #[arg(short, long, value_enum)]
    note_type: NoteType,

    /// Flag to submit the executed transaction without asking for confirmation.
    #[arg(long, default_value_t = false)]
    force: bool,

    /// Flag to delegate proving to the remote prover specified in the config file.
    #[arg(long, default_value_t = false)]
    delegate_proving: bool,
}

impl SwapCmd {
    pub async fn execute<AUTH: Keystore + Sync + 'static>(
        &self,
        mut client: Client<AUTH>,
    ) -> Result<(), CliError> {
        let force = self.force;

        let faucet_details_map = load_faucet_details_map()?;

        let offered_fungible_asset =
            faucet_details_map.parse_fungible_asset(&client, &self.offered_asset).await?;
        let requested_fungible_asset =
            faucet_details_map.parse_fungible_asset(&client, &self.requested_asset).await?;

        // try to use either the provided argument or the default account
        let sender_account_id =
            get_input_acc_id_by_prefix_or_default(&client, self.sender_account_id.clone()).await?;

        let swap_transaction = SwapTransactionData::new(
            sender_account_id,
            offered_fungible_asset.into(),
            requested_fungible_asset.into(),
        );

        let transaction_request = TransactionRequestBuilder::new()
            .build_swap(
                &swap_transaction,
                (&self.note_type).into(),
                MidenNoteType::Private,
                client.rng(),
            )
            .map_err(|err| {
                CliError::Transaction(err.into(), "Failed to build swap transaction".to_string())
            })?;

        execute_transaction(
            &mut client,
            sender_account_id,
            transaction_request,
            force,
            self.delegate_proving,
        )
        .await?;

        let payback_note_tag: u32 = SwapNote::build_tag(
            (&self.note_type).into(),
            &swap_transaction.offered_asset(),
            &swap_transaction.requested_asset(),
        )
        .into();
        println!(
            "To receive updates about the payback Swap Note run `miden-client tags --add {payback_note_tag}`",
        );

        Ok(())
    }
}

/// Consume with the account corresponding to `account_id` all of the notes from `list_of_notes`.
/// If no account ID is provided, the default one is used. If no notes are provided, any notes
/// that are identified to be owned by the account ID are consumed.
#[derive(Debug, Parser, Clone)]
pub struct ConsumeNotesCmd {
    /// The account ID to be used to consume the note or its hex prefix. If none is provided, the
    /// default account's ID is used instead.
    #[arg(short = 'a', long = "account")]
    account_id: Option<String>,
    /// A list of note IDs or the hex prefixes of their corresponding IDs.
    list_of_notes: Vec<String>,
    /// Flag to submit the executed transaction without asking for confirmation.
    #[arg(short, long, default_value_t = false)]
    force: bool,

    /// Flag to delegate proving to the remote prover specified in the config file.
    #[arg(long, default_value_t = false)]
    delegate_proving: bool,
}

impl ConsumeNotesCmd {
    pub async fn execute<AUTH: Keystore + Sync + 'static>(
        &self,
        mut client: Client<AUTH>,
    ) -> Result<(), CliError> {
        let force = self.force;

        let mut input_notes = Vec::new();

        for note_id in &self.list_of_notes {
            let note_record = get_input_note_with_id_prefix(&client, note_id)
                .await
                .map_err(|_| CliError::Input(format!("Input note ID {note_id} is neither a valid Note ID nor a prefix of a known Note ID")))?;

            input_notes.push((
                note_record.try_into().map_err(|err: NoteRecordError| {
                    CliError::Transaction(err.into(), "Failed to convert note record".to_string())
                })?,
                None,
            ));
        }

        let account_id =
            get_input_acc_id_by_prefix_or_default(&client, self.account_id.clone()).await?;

        if input_notes.is_empty() {
            info!("No input note IDs provided, getting all notes consumable by {}", account_id);
            let consumable_notes = client.get_consumable_notes(Some(account_id)).await?;
            for (note_record, _) in consumable_notes {
                input_notes.push((
                    note_record.try_into().map_err(|err: NoteRecordError| {
                        CliError::Transaction(
                            err.into(),
                            "Failed to convert note record".to_string(),
                        )
                    })?,
                    None,
                ));
            }
        }

        if input_notes.is_empty() {
            return Err(CliError::Transaction(
                "No input notes were provided and the store does not contain any notes consumable by {account_id}".into(),
                "Input notes check failed".to_string(),
            ));
        }

        let transaction_request = TransactionRequestBuilder::new()
            .input_notes(input_notes)
            .build()
            .map_err(|err| {
                CliError::Transaction(
                    err.into(),
                    "Failed to build consume notes transaction".to_string(),
                )
            })?;

        execute_transaction(
            &mut client,
            account_id,
            transaction_request,
            force,
            self.delegate_proving,
        )
        .await
    }
}

// EXECUTE TRANSACTION
// ================================================================================================

async fn execute_transaction<AUTH: Keystore + Sync + 'static>(
    client: &mut Client<AUTH>,
    account_id: AccountId,
    transaction_request: TransactionRequest,
    force: bool,
    delegated_proving: bool,
) -> Result<(), CliError> {
    println!("Executing transaction...");
    let transaction_result = client.execute_transaction(account_id, transaction_request).await?;

    let executed_transaction = transaction_result.executed_transaction().clone();

    // Show delta and ask for confirmation
    print_transaction_details(&executed_transaction)?;
    if !force {
        println!(
            "\nContinue with proving and submission? Changes will be irreversible once the proof is finalized on the network (y/N)"
        );
        let mut proceed_str: String = String::new();
        io::stdin().read_line(&mut proceed_str).expect("Should read line");

        if proceed_str.trim().to_lowercase() != "y" {
            println!("Transaction was cancelled.");
            return Ok(());
        }
    }

    let transaction_id = executed_transaction.id();
    let output_notes = executed_transaction
        .output_notes()
        .iter()
        .map(RawOutputNote::id)
        .collect::<Vec<_>>();

    println!("Proving transaction...");

    let prover = if delegated_proving {
        let cli_config = CliConfig::load()?;
        let remote_prover_endpoint =
            cli_config.remote_prover_endpoint.as_ref().ok_or(CliError::Config(
                "Remote prover endpoint".to_string().into(),
                "remote prover endpoint is not set in the configuration file".to_string(),
            ))?;

        Arc::new(
            RemoteTransactionProver::new(remote_prover_endpoint.to_string())
                .with_timeout(cli_config.remote_prover_timeout),
        )
    } else {
        client.prover()
    };

    let proven_transaction = client.prove_transaction_with(&transaction_result, prover).await?;

    println!("Submitting transaction to node...");

    let submission_height = client
        .submit_proven_transaction(proven_transaction, &transaction_result)
        .await?;
    println!("Applying transaction to store...");
    client.apply_transaction(&transaction_result, submission_height).await?;

    println!("Successfully created transaction.");
    println!("Transaction ID: {transaction_id}");

    if output_notes.is_empty() {
        println!("The transaction did not generate any output notes.");
    } else {
        println!("Output notes:");
        for note_id in &output_notes {
            println!("\t- {note_id}");
        }
    }

    Ok(())
}

fn print_transaction_details(executed_tx: &ExecutedTransaction) -> Result<(), CliError> {
    println!("The transaction will have the following effects:\n");

    // INPUT NOTES
    let input_note_ids = executed_tx.input_notes().iter().map(InputNote::id).collect::<Vec<_>>();
    if input_note_ids.is_empty() {
        println!("No notes will be consumed.");
    } else {
        println!("The following notes will be consumed:");
        for input_note_id in input_note_ids {
            println!("\t- {}", input_note_id.to_hex());
        }
    }
    println!();

    // OUTPUT NOTES
    let output_note_count = executed_tx.output_notes().iter().count();
    if output_note_count == 0 {
        println!("No notes will be created as a result of this transaction.");
    } else {
        println!("{output_note_count} notes will be created as a result of this transaction.");
    }
    println!();

    // ACCOUNT CHANGES
    println!("The account with ID {} will be modified as follows:", executed_tx.account_id());

    let account_delta = executed_tx.account_delta();

    let has_storage_changes = !account_delta.storage().is_empty();
    if has_storage_changes {
        let mut table = create_dynamic_table(&["Storage Slot", "Effect"]);

        for (updated_item_slot, new_value) in account_delta.storage().values() {
            table.add_row(vec![
                updated_item_slot.to_string(),
                format!("Updated ({})", new_value.to_hex()),
            ]);
        }

        println!("Storage changes:");
        println!("{table}");
    } else {
        println!("Account Storage will not be changed.");
    }

    if account_delta.vault().is_empty() {
        println!("Account Vault will not be changed.");
    } else {
        let faucet_details_map = load_faucet_details_map()?;
        let mut table = create_dynamic_table(&["Asset Type", "Faucet ID", "Amount"]);

        for (vault_key, amount) in account_delta.vault().fungible().iter() {
            let asset = FungibleAsset::new(vault_key.faucet_id(), amount.unsigned_abs())
                .map_err(CliError::Asset)?;
            let (faucet_fmt, amount_fmt) = faucet_details_map.format_fungible_asset(&asset)?;

            if amount.is_positive() {
                table.add_row(vec!["Fungible Asset", &faucet_fmt, &format!("+{amount_fmt}")]);
            } else {
                table.add_row(vec!["Fungible Asset", &faucet_fmt, &format!("-{amount_fmt}")]);
            }
        }

        for (asset, action) in account_delta.vault().non_fungible().iter() {
            match action {
                NonFungibleDeltaAction::Add => {
                    table.add_row(vec![
                        "Non Fungible Asset",
                        &asset.faucet_id().prefix().to_hex(),
                        "1",
                    ]);
                },
                NonFungibleDeltaAction::Remove => {
                    table.add_row(vec![
                        "Non Fungible Asset",
                        &asset.faucet_id().prefix().to_hex(),
                        "-1",
                    ]);
                },
            }
        }

        println!("Vault changes:");
        println!("{table}");
    }

    println!("Nonce incremented by: {}.", account_delta.nonce_delta());

    Ok(())
}