Proposal for Standardized Move Script Generation and Human-Readable Transaction Manifests

[mshakeg]

I am reaching out to propose an enhancement to the user experience on Aptos that I believe could significantly improve the way users interact with dApps, particularly in terms of understanding and signing transactions.

Proposal Overview

The core of this proposal is to develop a standardized process for programmatically generating Move scripts that encapsulate dApp-specific transaction logic. This would be accompanied by a standardized function, possibly named transaction_manifest, which would be called by the user's connected wallet to sign transactions.

Technical Components

1. Manifest Instruction List:

   • An ordered list of standardized instructions that the dApp can pass to the wallet to generate a Move script. Some common examples could be:
     • CALL_FUNCTION(package_address, module_name, module_function, type_parameters, parameters, return_val_vars): Directive to call the specified module's function. If it's a function call to a trusted package (e.g., 0x1) such as aptos_framework::coin::withdraw, wallets in their visual representation can make this function call standout. return_val_vars are the local Move variable names assigned to the return values of the function call and can be referenced in other instructions that accept those variables of the same type.
     • ASSERT_CONTAINS_COIN(coin_var, amount): Asserts that the specified coin_var contains at least the specified amount.
   • Inspired by Radix’s transaction manifests, the community can review and adapt a more comprehensive instruction list from Radix Manifest Instructions.

2. Move Script Generator:

   • A TypeScript/JavaScript library(perhaps part of the @aptos-labs/ts-sdk) that dApps can use to generate transaction manifest move scripts from transaction manifest instruction lists. This library would output Move script source code that implements the requested transaction logic. Error handling can be discussed and refined by the community, with considerations similar to other in-wallet errors such as an invalid balance to execute the requested transaction.

3. Wallet Integration:

   • Wallets would integrate the ability to generate and then compile Move scripts and display them in both raw source code form for technical users and a more human-readable format for average users. Ideally, the Move scripts should be compiled in the browser. Alternatively, though more of a last resort the Move script could be submitted to the network in plain text to be compiled by validators.

Example Use Case

Imagine a user wants to perform a token swap on a decentralized exchange (DEX) using a dApp. The dApp would submit a standardized request to the user's wallet, detailing the instructions to be taken (e.g., step 1. withdraw X amount of Coin A, step 2. swap coin A for Coin B, step 3. ensure a minimum amount received, step 4. deposit Coin B back into the user's account). The wallet would then generate the Move script, compile it, and present it to the user. If the dApp did not include the minimum amount out guarantee in step 3, then the wallet will autopopulate that guarantee into the list of instructions. The wallet may give the user the option to customize those guarantees (e.g., to effectively increase/decrease slippage).

Example Transaction Manifest List:

[
  {
    "instruction": "CALL_FUNCTION",
    "package_address": "0x1",
    "module_name": "coin",
    "module_function": "withdraw",
    "type_parameters": ["0x1::x_coin::X"],
    "parameters": ["X_AMOUNT"],
    "return_val_vars": ["coin_x"]
  },
  {
    "instruction": "CALL_FUNCTION",
    "package_address": "some_dex_address",
    "module_name": "pool",
    "module_function": "swap_x_for_y",
    "type_parameters": ["0x123::x_coin::X", "0xabc::y_coin::Y"],
    "parameters": ["coin_x", "Y_MIN_AMOUNT"],
    "return_val_vars": ["coin_y"]
  },
  {
    "instruction": "ASSERT_CONTAINS_COIN",
    "coin_var": "coin_y",
    "amount": "Y_MIN_AMOUNT"
  },
  {
    "instruction": "CALL_FUNCTION",
    "package_address": "0x1",
    "module_name": "aptos_account",
    "module_function": "deposit",
    "type_parameters": ["0xabc::y_coin::Y"],
    "parameters": ["user_addr", "coin_y"]
  }
]

Example Generated Move Script:

script {
    use std::signer;
    use aptos_framework::coin;
    use aptos_framework::aptos_account;
    use some_dex_address::pool;

    const E_TOO_LITTLE_RECEIVED: u64 = 100;
    const X_AMOUNT: u64 = 12345;
    const Y_MIN_AMOUNT: u64 = 56789;

    fun transaction_manifest<X, Y>(user: &signer) {
        let user_addr = signer::address_of(user);

        // Step 1: Withdraw X_AMOUNT of Coin X from the user's account
        let coin_x = coin::withdraw<X>(user, X_AMOUNT);

        // Step 2: Call the swap function on the DEX module
        let coin_y = pool::swap_x_for_y<X, Y>(coin_x);

        // Step 3: Enforce that the amount of Coin Y received is at least Y_MIN_AMOUNT
        assert!(coin::value(&coin_y) >= Y_MIN_AMOUNT, E_TOO_LITTLE_RECEIVED);

        // Step 4: Deposit Coin Y into the user's account
        aptos_account::deposit(user_addr, coin_y);
    }
}

Wallet UI Visualization:

For the average user who may not be familiar with Move script syntax, wallets can provide a clean and intuitive UI that visualizes the transaction manifest's instruction list. Here are some ways wallets could approach this:

• Visual Summary: Display a summary of the transaction with icons and simple language. For example, "Withdraw 12,345 Coin X from User" followed by an arrow pointing to some_dex_address::pool::swap_x_for_y and then "Deposit at least 56,789 Coin Y to User".
• Step-by-Step Explanation: Break down the transaction into steps and explain each one perhaps using a local LLM. For instance, "First, we will take 12,345 Coin X from your account. Next, we will use those to attempt to get Coin Y from the DEX pool. Finally, we will make sure you get at least 56,789 Coin Y back into your account."

By providing both the raw Move script for technical users and a friendly UI for non-technical users, wallets can cater to the entire user base, ensuring transparency, security, and ease of use.

Benefits

1. Enhanced Security & User Trust:

   • Limiting the use of the user's signer to the script level prevents the signer from being passed to potentially untrusted modules. This reduces the risk of unauthorized/undesired actions, safeguarding the user's assets.

2. Simplified User Experience:

   • Users benefit from a streamlined experience with a clear and understandable transaction process, reducing the complexity & anxiety of interacting with dApps.

3. Standardization:

   • Establishing a common framework for transaction generation and signing leads to a more cohesive ecosystem. This standardization simplifies the development process and ensures a consistent user experience across different applications on the Aptos blockchain.

I look forward to the community’s feedback and discussions on how we can refine and implement this proposal.

[mshakeg]

A quicker solution to the compilation feasibility issue would be to have the dApp generate and compile the move script in advance and have the transaction_manifest function accept the configurable constants as parameters, so in the above-described DEX example X_AMOUNT and Y_MIN_AMOUNT would be added as parameters to transaction_manifest as follows:

fun transaction_manifest<X, Y>(user: &signer, x_amount: u64, y_min_amount: u64) {
  // ... basically the same function definition with the constants renamed to use the x_amount and y_min_amount parameters
}

However, the wallet would then have to decompile the script bytecode if the user wants to see the script code, which wouldn't be as readable as the variable names aren't preserved in the bytecode.

[mshakeg]

Aptos Intents enable this in a much cleaner way(and is more or less the same as Sui PTBs).

https://x.com/Aptos/status/1839605911251550484