Miden blockexplorer - next iteration

[Dominik1999]

DRAFT

Goal: next iteration of the block explorer

On our explorer (https://testnet.midenscan.com/), we want to have a couple of updates and fixes.

General

• Can you change the Account Ids to bech32. After we closed this issue it should be clear what that means.

Main page (2 changes)

• Let's remove the "account updates" box - this should always be the same as the number of transactions. Can you find out why this differs?
• Add a status information of the testnet / devnet (red or green icon), you can leverage our endpoint.

Blocks

Overview tab (2 changes)

• Here again we have "Account Updates" and "Transactions". I think they should be the same thing. Not sure why the numbers are not the same currently, let's sync with the protocol and Node team.

Account Updates & Transactions

• The "Commited Block Number" seems always to reference to the block. So we can get rid of this info or put in the overview
• We should describe the transaction and the underlying account together (a transaction is defined as the account state change)

Accounts

• Again, merge Transactions and Account Updates
• Move "Procedure Digests" under "Code" similar to what Etherscan does. Then we need to find a way to split the procedures in "Read contract" and "Write contract".

Vault Assets

• Rename "Vault Assets" to "Assets"
• The assets in the explorer should show the token symbol, three letters, e.g., POL. However, we do not know the token symbol for every asset. We can provide you with an easy way how to read the token symbol.
• We should also show the token's decimals. The token symbol and the decimals are stored in the account in slot 1 (for public faucet accounts).
• We should not only show the Faucet Prefix ID but the whole Faucet Account ID in bech32 encoding.

Code tab (2 changes)

• For known digests (code snippets from the Miden Standard Library), we can show the MASM or even the Rust code. For that, we need to store a mapping from digest to MASM code. If the account code only consists of known digests, we can add a green hook symbol that this account is "verified". In addition to this, we'll also need to show storage offset and storage size. See below in the comment a mapping of known Digests and their MASM name.
• We should allow users to connect their wallet and read and write on the contract similar to Etherscan.

Storage

• We want to show the account's storage. There are two ways to store something in the account.

1. There are 255 Storage slots, each a Word. But usually will be much fewer - e.g., a basic wallet has only 1 storage slot.
2. There are key-value maps (StorageMaps). We need to show the leaves and the root of the tree. We should probably show a table (e.g., with 2 columns) with currently populated key-value pairs.

• We should show the Word = [Felt, Felt, Felt, Felt] if we don't know what the value is. For most known account components ("verified contracts") we know how to read that data and we should display it in a human readable form.

Upload accounts - can be implemented in the future

• We want to be able to upload an account to the explorer. Accounts are serialized as *.mac files. So when I click on a private account, there needs to be an upload button; I then upload my account, and if the account hash matches, all data should be shown as if the account were a public account.

Note Tags

• We want to be able to search notes by TAG. The TAG is in the note metadata. There should be a separate "Note tags" page where we list all tags and then when we click on a specific tag, we can see all notes which have this tag.

[bobbinth]

A few small comments from me:

It would be really nice to get some of these numbers to update dynamically (i.e., the block count, the transaction count etc.)

I think this may already be done. But the "dynamic row" is not there yet.

The token symbol and the decimals are stored in the account in slot 1 (for public accounts).

We'll need to define a strategy for how to reconcile data from the mapping file and the one stored in accounts.

Code tab (2 changes)

1. We currently show the code digests for public accounts (see here). We need to show the MAST code (once there is pprint merged into the Miden VM)
2. For known digests (code snippets from the Miden Standard Library), we can show the MASM code. For that, we need to store a mapping from digest to MASM code. If the account code only consists of known digests, we can add a green hoom symbol that this account is "verified".

In addition to this, we'll also need to show a couple of attributes for each procedure. Specifically, storage offset and storage size.

• There are 255 Storage slots, each a Word.
• There are StorageMaps, which are SparseMerkleTrees of depth 64. We need to show the leaves and the root of the tree.

There are could be up to 255 storage slot (but usually will be much fewer - e.g., a basic wallet has only 1 storage slot).

For key-value maps, we should probably show a table (e.g., with 2 columns) with currently populated key-value pairs.

Upload accounts - new

We want to be able to upload an account to the explorer. Accounts are serialized as *.mac files. So when I click on a private account, there needs to be an upload button; I then upload my account, and if the account hash matches, all data should be shown as if the account were a public account.

This is really a "nice-to-have" - I would tackle it only after everything else is done.

Also, another nice to have would be to be able to download NoteFile for public notes.

[PhilippGackstatter]

2. For known digests (code snippets from the Miden Standard Library), we can show the MASM code. For that, we need to store a mapping from digest to MASM code. If the account code only consists of known digests, we can add a green hoom symbol that this account is "verified".

Maybe @PhilippGackstatter can provide a mapping of the current MASM procedures.

Sure, here is the (current) mapping from the MAST root of the script to its name:

0xc491aa07f9a0da9838de1ae841ea7dc8d45cd5641f74a89faeb2ff8fa8cf801b -> P2ID
0x143480f4ddf09a321c6373edd8ea4768d04ef4238aa41d221c0129f83e5c1d5a -> P2IDR
0x4dd86dfc6ec16cef9d169480850d4e5e6d0de4eca662323f27be87486b2b7d21 -> SWAP

And in case this changes in the future, here is the Rust code that produces this mapping (placed in miden-lib/src/bin/script_hashes.rs and run with cargo run --bin script_hashes from the root, although I think any bin directory in miden-base should work):

use miden_lib::utils::Deserializable;
use miden_objects::{notes::NoteScript, vm::Program};

fn main() {
    let directory = std::fs::read_dir(concat!(env!("OUT_DIR"), "/assets/note_scripts/")).unwrap();

    for script in directory {
        let script = script.unwrap();
        let bytes = std::fs::read(script.path()).unwrap();
        let program = Program::read_from_bytes(&bytes).unwrap();
        let note_script = NoteScript::new(program);
        let script_name = script.path().file_stem().unwrap().to_os_string().into_string().unwrap();
        println!("{} -> {}", note_script.hash(), script_name);
    }
}

[PhilippGackstatter]

I just realized I misunderstood what was needed, so I hid my above comment.

2. For known digests (code snippets from the Miden Standard Library), we can show the MASM code. For that, we need to store a mapping from digest to MASM code. If the account code only consists of known digests, we can add a green hoom symbol that this account is "verified".

Contrary to note scripts, account code is a library, so it doesn't have a single, well-defined entrypoint, hence we cannot compute a single identifying MAST root for it (afaict).

I think what can be done instead to identify standard account contracts is first gather all of its exported procedure's MAST roots (hashes). If this set of roots matches one of the following sets exactly (no more or less elements) then we can show a verified contract symbol and display the name of the contract:

Contract: asm/miden/contracts/faucets/basic_fungible.masm
0xb8ab9250552340f85a7fae48b91bcdb66b9e03e6d7aa690ea20a161df45846b9 -> auth_tx_rpo_falcon512
0xc20293f0369767effe117526998e405f8745504ac280aa6052357f7f7779c017 -> burn
0x5975eac536b66c718e0aedb43b77c6cf7f7b1479f087e670bb9438baeee0f79a -> distribute

Contract: asm/miden/contracts/auth/basic.masm
0xb8ab9250552340f85a7fae48b91bcdb66b9e03e6d7aa690ea20a161df45846b9 -> auth_tx_rpo_falcon512

Contract: asm/miden/contracts/wallets/basic.masm
0x8500b731b95c38cc663dd823d18becc928ab99a8ddd8e5e589ef719ad609a4f5 -> create_note
0x7517eb7731fbfe883d6ab1bc8c66c95728f321e7c3538436e9ef9105d61637c1 -> move_asset_to_note
0xe048a235aba9e9806f8598fdfd8e76c21e3cc72955ca2e858b3a06020096bbc4 -> receive_asset

As far as I can tell, the auth/basic.masm is not a useful account contract by itself since it only does authentication, so I guess only the other two are relevant for the explorer.

For display purposes, I think some proper names for these contracts would be desirable, e.g. "Basic Wallet" and "Fungible Faucet".

The code for this is here.

Note: This requires the walkdir crate.

use std::{self};

use miden_lib::transaction::TransactionKernel;
use walkdir::WalkDir;

fn main() {
    let contracts_dir = concat!(env!("CARGO_MANIFEST_DIR"), "/asm/miden/contracts/");

    for entry in WalkDir::new(contracts_dir) {
        let entry = entry.unwrap();
        if entry.file_type().is_dir() {
            continue;
        }

        let contract_bytes = std::fs::read(entry.path()).unwrap();
        let contract_name = entry.path().strip_prefix(env!("CARGO_MANIFEST_DIR")).unwrap();

        let assembler = TransactionKernel::assembler();
        let lib = assembler.assemble_library([contract_bytes]).unwrap();

        println!("Contract: {}", contract_name.display());
        for module_info in lib.module_infos() {
            for (_, proc_info) in module_info.procedures() {
                println!("{} -> {}", proc_info.digest, proc_info.name);
            }
        }
        println!("");
    }
}