near-cli-rs icon indicating copy to clipboard operation
near-cli-rs copied to clipboard

Introduce teach-me mode

Open frol opened this issue 1 year ago • 0 comments

near-cli-rs can be an awesome tool to educate NEAR developers about how things actually work in NEAR.

For example, if would be great to provide more details about RPC calls that are executed and their parameters when tokens view-ft-balance is executed, which queries RPC for the token metadata and then the balance for the specific user. This would help answering questions like this much easier, I would just ask them to run near CLI with --teach-me flag.

Here is a rough illustration of the process when near --teach-me flag is set:

$ near --teach-me
> What are you up to? (select one of the options with the up-down arrows on your keyboard and press Enter) tokens      - Manage token assets such as NEAR, FT, NFT
> What is your account ID? frol.near
> Select actions with tokens: view-ft-balance   - View the balance of FT tokens
> What is the ft-contract account ID? wrap.near
> What is the name of the network? mainnet
> Сhoose block for view: now               - View properties in the final block
TEACH-ME: In order to display the FT symbol and format the decimal amount of owned tokens, we need to make a view-function call `ft_metadata` to the <wrap.near> contract, and we can do that with the query request to NEAR RPC node (https://docs.near.org/api/rpc/contracts#call-a-contract-function):
HTTP POST https://rpc.mainnet.near.org/
JSON-BODY: {
  "jsonrpc": "2.0",
  "id": "dontcare",
  "method": "query",
  "params": {
    "request_type": "call_function",
    "finality": "final",
    "account_id": "wrap.near",
    "method_name": "ft_metadata",
    "args_base64": "e30="
  }
}
RESPONSE: {
    "id": "dontcare",
    "jsonrpc": "2.0",
    "result": {
        "block_hash": "E4oQ8YhUcMSve7kRMvNeoM3ZSjJopJc1tPLztg3BWkmg",
        "block_height": 93496936,
        "logs": [],
        "result": [123,34,115,112,101,99,34,58,34,102,116,45,49,46,48,46,48,34,44,34,110,97,109,101,34,58,34,87,114,97,112,112,101,100,32,78,69,65,82,32,102,117,110,103,105,98,108,101,32,116,111,107,101,110,34,44,34,115,121,109,98,111,108,34,58,34,119,78,69,65,82,34,44,34,105,99,111,110,34,58,110,117,108,108,44,34,114,101,102,101,114,101,110,99,101,34,58,110,117,108,108,44,34,114,101,102,101,114,101,110,99,101,95,104,97,115,104,34,58,110,117,108,108,44,34,100,101,99,105,109,97,108,115,34,58,50,52,125]
    }
}
TEACH-ME: The `args_base64` (`e30=`) is a base64-encoded serialized arguments to `ft_metadata` function (`{}`), and the output `result` is an array of bytes (`{"spec":"ft-1.0.0","name":"Wrapped NEAR fungible token","symbol":"wNEAR","icon":null,"reference":null,"reference_hash":null,"decimals":24}`).

TEACH-ME: In order to get the FT balance for the specific account, we need to make a view-function call `ft_balance_of` to the <wrap.near> contract, and we can do that with the query request to NEAR RPC node (https://docs.near.org/api/rpc/contracts#call-a-contract-function):
HTTP POST https://rpc.mainnet.near.org/
JSON-BODY: {
  "jsonrpc": "2.0",
  "id": "dontcare",
  "method": "query",
  "params": {
    "request_type": "call_function",
    "finality": "final",
    "account_id": "wrap.near",
    "method_name": "ft_balance_of",
    "args_base64": "eyJhY2NvdW50X2lkIjogImZyb2wubmVhciJ9"
  }
}
RESPONSE: {
    "id": "dontcare",
    "jsonrpc": "2.0",
    "result": {
        "block_hash": "E4oQ8YhUcMSve7kRMvNeoM3ZSjJopJc1tPLztg3BWkmg",
        "block_height": 93496936,
        "logs": [],
        "result": [34, 57, 56, 55, 53, 48, 48, 48, 48, 48, 48, 48, 48, 48, 48, 48, 48, 48, 48, 48, 48, 48, 48, 48, 34]
    }
}
TEACH-ME: The `args_base64` (`eyJhY2NvdW50X2lkIjogImZyb2wubmVhciJ9`) is a base64-encoded serialized arguments to `ft_balance_of` function (`{"account_id": "frol.near"}`), and the output `result` is an array of bytes (`"98750000000000000000000"`).

--------------
No logs
--------------

<frol.near> account has 0.09875 wNEAR  (FT-contract: wrap.near)

Implementation hints

Follow offline flag implementation that is part of GlobalContext to add --teach-me flag throughout the project.

We can easily introduce TEACH-ME to the RPC helper functions:

https://github.com/near/near-cli-rs/blob/4f8576e1db857bdba45f9e3a57349253f99e07c2/src/common.rs#L1576-L1667

https://github.com/near/near-cli-rs/blob/4f8576e1db857bdba45f9e3a57349253f99e07c2/src/common.rs#L1688-L1767

That would already get us 80% through. Let's start with this and iterate from here.

frol avatar Jun 05 '23 08:06 frol