Testnet Client Requirements

[frisitano]

Overview

The purpose of this document is to define the specification for the miden client such that we can satisfy the functional requirements of the miden private test network. The functional requirement that we have is to provide the ability for assets to be sent from one account to another. The miden client will be implemented as a command line utility. There are two broad classes of functionality that the CLI client needs to support, these are account management and transaction management. This is a work in progress.

Account management

### Grind Account Digest
Description: The purpose of this command is to grind a digest that is suitable for creating an account of the specified type. For the purpose of the private test network we will most likely be interested in regular accounts. We may want to reduce the work required for testnet. Please see this method for the backend implementation.
Method: grind_seed
Parameters: Account type

Create Signing Key

Description: This command will allow the user to create a signing key (most likely Falcon). We will need a high entropy source of randomness to support this.
Method: create_signing_key
Paramaters:

• name (provide some default)

Create Account

Description: This command will allow the user to create an account. We still need to flesh out the details of account creation but it has been proposed that should be able to support this as part of the standard transaction kernel.
Method: create_account
Paramaters:

• account_type
• account_seed
• signing_key_name

Account data management

Description: We need to store account data for the user. To support this we should store a client side database that keeps track of information relating to an account. This can include comprehensive account information and potentially also notes associated with it.

### Account Exploration
Description: We should provide the user the ability to introspect their account. To support this we should provide an endpoint that provides a description of said account.
Method: describe_account
Parameters: account_id (defaults to the currently set account)

Transaction Management

Send Asset

Description: We need to provide the user the ability to send assets to another account. We need to decide if we will have multiple assets on testnet or only a single asset, this will impact the parameters of this command. This command will use a standardised masm script to achieve this functionality. We will need to use the key associated with the account to create a signature. Once the transaction has been created, execute and proven it should be sent to the node via the RPC call. The CLI client should then poll to check when the transaction has been included in a block and update the local database accordingly with new state information.
Method: send_assets
Paramaters:

• recipient_account_id
• amount

Receive Asset

Description: We need to provide the user the ability to receive assets. To achieve this we will utilise a standard masm script. The user will need to specify the notes which contain the assets they want to consume. These notes can be discovered using the note discovery command specified bellow. The transaction will be constructed, executed and proven by the client and then submitted to the node. The client will then be responsible for polling the node to check when the transaction has been included in a block and update the local database accordingly.
Method: receive_assets
Paramaters:

• note_identifiers (I'm not sure if this should be a list of note origins or some other identifier)

Chain Exploration

We should expose a few methods on the client that enables the user to explore the state of the chain and get information required to execute transactions. The list of endpoints described below should be sufficient for the private test network.

Note Discovery

Description: We need a mechanism to identify notes of interest to a specific account. This will allow the user to find notes and construct transactions to consume these notes. This piece of functionality depends on the node RPC design which is currently in progress.
Method: get_notes_by_tag
Paramaters:

• note_tag

### Block Discovery
Description: This command allows the user to query the node RPC for a specific block based on its block number. Whilst this endpoint isn't a hard requirement for the private test network it may be of value for users who want to familiarise themselves with the miden rollup.
Method: get_block
Paramaters:

• block_number

[bobbinth]

Great summary! Thank you! Adding a bit more about how I'm envisioning the CLI to work. These are just preliminary thoughts - feel free to comment with suggestions.

We probably should come up with a better name, but for now, I'll use miden. I'm imagining this as a non-interactive CLI interface (though, maybe we should make it interactive?). It would have the following commands:

USAGE:
    miden < SUBCOMMAND>

SUBCOMMANDS:
    account      View accounts, create accounts
    connect      Connect to Miden node
    note         View notes, consume notes
    send         Send assets
    sync         Retrieve the latest data from Miden node

The account subcommand would have the following options:

USAGE:
    miden account [OPTIONS]

OPTIONS:
    -d, --default   Sets the default account
    -l, --list      Lists all accounts together with their assets/storage
    -n, --new       Creates a new account
    -r, --remove    Deletes an account

The connect subcommand would have the following options:

USAGE:
    miden connect <Miden node address>

The note subcommand would have the following options:

USAGE:
    miden note [OPTIONS]

OPTIONS:
    -c, --consume    Consume a specific note
    -h, --history    List all notes sent/received by this client.
    -p, --pending    List all notes which haven't been consumed yet.

The connect subcommand would have the following options:

USAGE:
    miden connect <Miden node address>

The send subcommand would have the following options:

USAGE:
    miden send [OPTIONS]

OPTIONS:
    -a, --asset     Asset to be sent (both fungible and non-fungible).
    -s, --source    ID of the account from which the asset is to be sent (if omitted default is used).
    -t, --target    ID of the account to which the asset is to be sent.

The sync subcommand would have the following options:

USAGE:
    miden sync