Ongoing discussion about improvement for the Michelson-Encoder package

[roxaneletourneau]

What is the Michelson-Encoder?

The main feature of the Michelson-Encoder is to transform Michelson data to javascript and javascript data to Michelson. We use this feature to provide an easy way for the users to write the storage when deploying a contract, the parameters when calling an entry point of a contract or a “lambda” view, the key when fetching the value of a big map, and the parameter when calling an off-chain view (tzip16). This feature is also used to create a friendly representation when fetching the storage value of a contract.

What are the problems we want to solve?

Issue	Suggested Improvement	Comment
When calling a smart contract entry point having a complex parameter, even with the abstraction over the Michelson syntax, it might be hard for the user to write the parameters.	Accept an object as a parameter of a contract entry point (instead of flat parameters)	Consider keeping the current implementation where parameters need to be flattened and provide a new method that accepts an object to avoid disruption for the users.
Non-uniform types between Michelson-Encoder and Michel-Codec packages	Incorporate the types of the Michel-Codec package into the Michelson-Encoder package
Difficult to figure out how to write entry point parameters or storage objects.	Add more documentation about the extractSchema method.
Error messages may be unclear.	Provide Better validation of the parameters and more explicit error messages	Consider using the assertDataValidInternal method of the Michel-Codec package.
Not up-to-date, missing types from the newer protocols	We should keep better track of added types for each new protocol and add a corresponding token in the Michelson-encoder package.
Parameters for contract calls made of a union or a list of unions have very different formats: union looks like methods.entrypoint("annotation", value) while list of unions looks like methods.entrypoint({ or_annot: { field_annot: value }})	Both representations of a union value as a parameter (whether alone or in a list) should be identical

[roxaneletourneau]

Issue: When calling a complex smart contract entry point, even with the abstraction over the Michelson syntax provided by Taquito, it might be hard for the user to figure out how to write the parameters correctly.

Current implementation:

The ContractAbstraction class contains a member named methods which is dynamically populated when instantiating the class. The methods member is an object having contract entry point names as key and a function as a value. This function accepts flattened javascript arguments and returns an instance of the ContractMethod class. When calling the send method of the ContractMethod class, the Encode method of the ParameterSchema class is used to transform the arguments passed to the function into Michelson data.

Suggested changes:

We want to provide a way for the user of Taquito to pass an object when calling a contract entry point, like it is the case for deploying a contract using the storage parameter.

Changes to the Michelson-encoder package:

Add an EncodeObject method on the ParameterSchema class which will accept an object as parameter and will be called on the root member (this.root.EncodeObject(value);). All tokens of the MichelsonEncoder already implement an EncodeObject method, so no further changes should be required in the MichelsonEncoder package.

Changes to the taquito package

• Add a new property isObject in the ContractMethod class:

  class ContractMethod<T extends ContractProvider | Wallet> {
    constructor(
      private provider: T,
      private address: string,
      private parameterSchema: ParameterSchema,
      private name: string,
      private args: any[],
      private isMultipleEntrypoint = true,
      private isAnonymous = false
      private isObject = false // new property
    ) { }
  

  If isObject is set to true, use the EncodeObject method of the ParameterSchema class to transform the argument into Michelson format, else use its Encode method.

• Different strategies can be used to implement the change:

  Solution 1:

  Add a new property on the ContractAbstraction named methodsObject. We would have two implementations that have the same purpose. The difference would be that they accept a different parameter format and the users could choose between their preferred one. We could deprecate the methods member in the future if there is more enthusiasm over the new methodsObject member. The same logic as the one used for the storage parameter when deploying a contract would be used; the keys of the object would be the annotations or indexes when the Michelson type does not contain annotation.

  const opMethod = await contract.methods.mint('tz1PgQt52JMirBUhhkq1eanX8hVd1Fsg71Lr', 100).send(); // flat params
  
  const opMethod = await contract.methodsObject.mint({to:'tz1PgQt52JMirBUhhkq1eanX8hVd1Fsg71Lr', value: 100}) // object param

  Solution 2:

  Add a configuration on the TezosToolkit class that will allow enabling the use of object format when calling an entry point. The configuration would be set to false by default and could be changed by doing:

  Tezos.setProvider({ configContractAbstraction: { enableObjectFormat: true }});
  

  The configuration value would be added to the context, so we could access it inside the ContractMethod class to determinate if it is the Encode or the EncodeObject method that needs to be used to transform the value into Michelson.

[Innkst]

I see a pro for Solution 1 that users have choices to use flat params vs. object params while Solution 2 is a full switch to use object params.
If 'methods' gets deprecated we'd essentially get the same switch, but we might want to use Solution 2 as a temporary measure to let users gradually transition before fully deprecating.

[jevonearth]

I'm leaning to Solution 1 because it allows existing projects to start using the new way incrementally.

Whereas, with Solution 2, I think when a user sets the optional enableObjectFormat param to true, an existing project would break until they update all the calls.