Move View Functions

[miker83z]

Proposal

Abstract

This proposal introduces a standardized interface for enabling ergonomic and application-specific queries to the on-chain state. We refer to this as "Move view function" as it will allow developers to write and call Move functions that return values without requiring transaction signing or state mutation (based on the Ethereum's Solidity view function feature concept). The proposal is made to improve developer productivity and simplifying access to on-chain data through RPC, CLI, and SDK interfaces.

Motivation

Currently, developers must write a significant amount of custom client-side logic to inspect on-chain data. This often involves multiple layers of fetching object IDs, deserializing raw bytes, and navigating dynamic fields just to reach an information stored within a Move object. While tools like dev-inspect or dry-run exist, they suffer from limitations such as complexity in usage and difficulty in decoding return values.

This proposal to address the following developer pain points:

• Being forced understand the logic of a Move data structure and then how to map that to RPC calls in order to fetch a piece of data, e.g., getting nested object ids.
• Some data structures can't be accessed through current RPC calls because of the way they use dynamic fields, e.g., Bag and Table data structures.
• Using dev-inspect can become complicated because the function returned values the developer gets are BCS bytes and then these need to be parsed, assuming the return type is known.

Specification

This proposal defines a developer interface to support Move View Functions. The following is a list of specifications related to its implementation:

• A View Function is any function in a Move module with a return type (this includes functions with visibility set to public, entry and private).
• Move View Functions are callable via at least one new RPC method that supports type parameters and normal function arguments.
• The use of such interface SHOULD NOT require signature checks, i.e., invoking a Move View Function that takes as input an Owned Object SHOULD be made possible to anyone and not only to the owner of such object.
• The use of such interface SHOULD NOT require the usage of a gas coin; spam attacks SHOULD be dealt with at the RPC level and not at the execution level; this because the Move View Function does not alter the state of the ledger and thus cannot deduce gas.
• Returned results MUST be resolved, i.e., the Move types deserialized, and then formatted in JSON.
• Must be integrated into the SDKs and the CLI.

Backwards Compatibility

This proposal is fully backwards compatible. The implementation of such a developer interface MUST NOT require changes to the Move language. Instead, it:

• Builds on top of existing execution paradigms, e.g., reusing dry-run or dev-inspect or creating a new execution mode.
• Does not require any changes to existing Move modules, i.e., any function with a return value can be used as Move View Function.
• Maintains compatibility with Move by not introducing any new language constructs or VM behavior (opposed to intrusive solutions such as Aptos view function).

Reference Implementation and Testing

An initial prototype exists using a variant of the dev-inspect call and CLI tooling. Here miker83z/iota@2081c1c. However, this only focuses on the modification of the execution side. Moreover, the developer experience is still suboptimal because it is still needed the manual decoding of return values.

Example RPC

The following example can be taken as a reference for the API model.

Request:

{
  "method": "iota_view",
  "params": {
    "package": "0x5e7a300e640f645a4030aeb507c7be16909e6fa9711e7ca2d4397bbd967d5c50",
    "module": "auction",
    "function": "get_auction_metadata",
    "type_args": [], 
    "arguments": ["auc.iota", "0x31deb8cbd320867089d52c37fed2d443520aac0fc5a957de1f64f9135b83f42b"]
  }
}

Response:

{
  "start": "447575403174913",
  "end": "447576324774913",
  "address": "0xc9f649324694c0c18c6278c3a81945fb3ef0c9b91f21dd5b6a4364447ee348df",
  "value": "500000000"
}

Copyright

Copyright and related rights waived via CC0.

Discussion

The discussion should continue to cover at least these points:

• What additional RPC methods will be added
• Plans on how to integrate it into SDKs/CLI/other tooling

CC: @iotaledger/vm-language @iotaledger/dev-tools @iotaledger/tooling

[miker83z]

Proposal 1 for extending the JSON-RPC Read API

This proposal is in line with the example and specifications made above.

iota_view

Executes a Move View Function. Which allows for nearly any Move call for a function with a return type and with any arguments. The function results values are provided and decoded using the appropriate Move type.

Parameters

Name	Required	Description
package_object_id < ObjectID >	Yes	The Move package ID, e.g. 0x2
module < string >	Yes	The Move module name, e.g. pay
function < string >	Yes	The move function name, e.g. get
type_arguments<[ TypeTag ]>	Yes	The type arguments of the Move function
arguments<[ IotaJsonValue ]>	Yes	The arguments to be passed into the Move function, in IotaJson format

Result

Name	Required	Description
error <[string,null]>	No	Execution error from executing the transactions
results< IotaMoveViewResult [array,null] >	No	Execution results (including return values) from executing the transactions

[miker83z]

Proposal 2 for extending the JSON-RPC Read API

This proposal works in parallel of proposal 1 and it is not meant to replace it. It consists of allowing a more complex query keeping most of the specifications made above about the Move View Function. The motivations for adding a second, more complex RPC Move View Function method are twofold:

• there can be the cases in which a Move View Function requires an input that is not pure or an Object, e.g., a Move struct, or can only be obtained by the execution of a prior move function, e.g., using the hot potato pattern;
• there can be cases in which the concept of "reading on-chain data" can be extended to "given the current on-chain state execute some Move code and return some data", e.g., implementing an Access Control List and a Move View function that verifies a public key is present in such list after that it has been verified a signature with the same public key (using ed25519_verify function for instance).

In both cases, the usage of a PTB instead of only one move call would serve the scope. This would make the query less ergonomic, because the developer must use something like unsafe_batchTransaction to construct a PTB before the view call, but more functional.
Additionally, since a move call like the proposal 1 above is still considered as a PTB at least at the execution level, the implementation of proposal 2 won't necessitate duplication of or much more additional code, but both proposals will share the same execution path and differ just at the interface level.

iota_viewTransactionBlock

Return the result values of the execution of a transaction block, while the effects are not committed to the chain. The function results values are provided and decoded using the appropriate Move type.

Parameters

Name	Required	Description
tx_bytes< Base64 >	Yes	The bytes of transaction block to execute; the last command must be a Move View Function

Result

Name	Required	Description
error <[string,null]>	No	Execution error from executing the transactions
results< IotaMoveViewResult [array,null] >	No	Execution results (including return values) from executing the transactions

Additional specifications for this proposal

• In this case the developer SHOULD be allowed to specify a sender and a gas coin or budget
• To limit the impact of the execution of such complex Move View Function (or Move View PTB) the max gas budget allowed COULD be reduced to a lower value in respect to a normal transaction execution
• The last command of the PTB passed as input MUST be a move call invoking a Move View Function

[philou-078]

Couldn't a 3rd solution be to enrich the response returned by the 3 current RPC (dry-run, dev-inspect and execute), in order to add the JSON representation of the returned values (of the last moveCall in the transaction) ?

Which would give, at the TS SDK level for example :

1. devInspectTransactionBlock( ) : DevInspectResults

// no change
export interface DevInspectResults {
    ...
    
    results?: IotaExecutionResult[] | null;
}

// new property "returnValuesAsJson"
export interface IotaExecutionResult {
     ... 
    
    // JSON representation
    returnValuesAsJson?: unknown | null;
}

2. dryRunTransactionBlock( ) : DryRunTransactionBlockResponse

// new property "results" (same as DevInspectResults)
export interface DryRunTransactionBlockResponse {
    ... 
    
    results?: IotaExecutionResult[] | null;
}

3. executeTransactionBlock(..., options: { ..., showResults: boolean }): IotaTransactionBlockResponse // new option "showResults"

// new property "results" (same as DevInspectResults)
export interface IotaTransactionBlockResponse{
    ... 
    
    // (valued if showResults == true)
    results?: IotaExecutionResult[] | null;
}

[miker83z]

Thanks for the suggestion! I think this is something to take into consideration, especially for the devInspectTransactionBlock (in the case of dry-run and execute the transaction effects should be enough). However, I do not think this should be included as part of a proposal for a Move View Function. The change you propose can be considered as a standalone task!