XCall V2 changes

[AntonAndell]

The library to be used now for xcall development is:
xyz.venture23:xcall-lib:0.1.1' for java
cw-xcall-lib={package="cw-xcall-lib", git="https://github.com/icon-project/xcall-multi.git", branch="main", features = ["library"]} for cosmwam
Solidity lib: to be published?

Differences from IIP52 xCall

Multi protocol xCall is based on the initial spec defined
in IIP52.

• Two new optional parameters are added in sendCallMessage: _sources and destinations.
  These parameters can be specified to choose the protocols to deliver the xCall message.
  If, for example, a dapp wanted to use BTP, they specify the address of BMC as the source and the address of BMC on a
  destination chain as destinations.

• Rollback guarantees.
  In IIP52, xCall rollback executions can only be tried once before removed, which can cause loss of data in case of
  failure.
  In xCall multi protocol, it can be retried until successful.

• Two-way message success verification.
  For all two-way messages, a response has to be relayed back since the fee has already been paid.
  This means that in most cases, a response with the result success is being relayed back.
  In xCall multi protocol, we store this success receipt so that it can be verified by dapps.

• BTP address has been replaced completely by Network Address.
  A BTP address is a Network Address as defined here with a btp:// prefix.
  A Network Address in IIP52 refers to the Network ID in this document which might cause some confusion.

• The source of truth for a Network ID is now in xCall and not BMC.

• _nsn is removed from CallMessageSent event.

• Error messages are no longer relayed across chains in a response.

• _msg has been removed from ResponseMessage event. This is due to the removal of relaying the error messages.

• A message can now only be success or failure (1 or 0).
  In IIP52 a message can have many different error codes but was not used by dapps and the same behavior is not
  necessarily supported by all chains.

• MaxDataSize is defined on the whole payload rather than only user data
  This change was necessary to limit the size of the _sources and destinations parameters.

What this means for dapps using v1:

• The use of BTP address needs to be changed to NetworkAddress.
  Example remove btp prefix from btp://${NETWORK_LABEL_DESTINATION}/${CONTRACT_DESTINATION};
  Network Address implmentation will work the same as BTP address and no extra changes should be needed.

• If event listeners are used some parameters have changed.

Less priority:

• Multi protocol
• Success verification.

Example dapps:
Solidity:
https://github.com/icon-project/xcall-multi/blob/main/contracts/evm/contracts/mocks/dapp/DAppProxySample.sol
https://github.com/icon-project/xcall-multi/blob/main/contracts/evm/contracts/mocks/multi-protocol-dapp/MultiProtocolSampleDapp.sol

Java:
https://github.com/icon-project/xcall-multi/blob/main/contracts/javascore/example-dapps/dapp-multi-protocol/src/main/java/xcall/sample/dapp/MultiProtocolSampleDapp.java
https://github.com/icon-project/xcall-multi/blob/main/contracts/javascore/example-dapps/dapp-simple/src/main/java/xcall/sample/dapp/SimpleDapp.java

Cosmwasm:
https://github.com/icon-project/xcall-multi/tree/main/contracts/cosmwasm-vm/cw-mock-dapp-multi
https://github.com/icon-project/xcall-multi/tree/main/contracts/cosmwasm-vm/cw-mock-dapp

@FidelVe Lets keep discussion and questions in this issue during the development

[AntonAndell]

https://github.com/icon-project/IBC-Integration/blob/main/docs/ibc-setup-using-dive-cli.md
Can be used to setup test.

[FidelVe]

@AntonAndell thanks for the information, ill setup a local environment for testing, run some tests with the provided example dapps and ill contact you with any question before starting writing a draft for the new docs.

[FidelVe]

Hi @AntonAndell as I commented in previous calls here is the summary of things ive encountered during my tests of xcall v2

Differences between xcall v1 and xcall v2

Events

• Signature for ResponseMessage on v1 is different than v2 (see reference table).
• Signature for RollbackExecuted on v1 is different than v2 (see reference table).
• Signature for CallMessageSent on v1 is different than v2 (see reference table).

References V2, V1

Events descriptions

Event Name	Signature V1	Signature V2	Params V1	Params V2
CallMessage	CallMessage(str,str,int,int,bytes)	CallMessage(str,str,int,int,bytes)	(_from, _to, _sn, _reqId, _data)	(_from, _to, _sn, _reqId, _data)
CallExecuted	CallExecuted(int,int,str)	CallExecuted(int,int,str)	(_reqId, _code, _msg)	(_reqId, _code, _msg)
ResponseMessage	ResponseMessage(int,int,str)	ResponseMessage(int,int)	(_sn, _code, _msg)	(_sn, _code)
RollbackMessage	RollbackMessage(int)	RollbackMessage(int)	(_sn)	(_sn)
RollbackExecuted	RollbackExecuted(int,int,str)	RollbackExecuted(int)	(_sn, _code, _msg)	(_sn)
CallMessageSent	CallMessageSent(Address,str,int,int)	CallMessageSent(Address,str,int)	(_from, _to, _sn, _nsn)	(_from, _to, _sn)

Main interface

The following section describes the differences in the main interfaces (contract methods) between xcall V1 and xcall V2.

sendCallMessage

• xcall V1: public BigInteger sendCallMessage(String _to, byte[] _data, @Optional byte[] _rollback)
• xcall V2: public BigInteger sendCallMessage(String _to, byte[] _data, @Optional byte[] _rollback, @Optional String[] _sources, @Optional String[] _destinations)

executeCall

Same interface on both versions.

• xcall V1: public void executeCall(BigInteger _reqId, byte[] _data)
• xcall V2: public void executeCall(BigInteger _reqId, byte[] _data)

handleCallMessage

• xcall V1: public void handleCallMessage(String _from, byte[] _data)
• xcall V2: public void handleCallMessage(String _from, byte[] _data, String[] protocols)

executeRollback

Same interface on both versions.

• xcall V1: public void executeRollback(BigInteger _sn)
• xcall V2: public void executeRollback(BigInteger _sn)

Topics to discuss for updating current documentation.

Taking into consideration the differences described in the previous points and the comment by @AntonAndell, I believe there are several items that are needed to fully document xcall-v2, each item has a different priority which I would like to discuss here before making changes to the documentation. The following is a list of the items with my personal assessment of the priority in each of them:

• (priority: medium ): Describe an example for sending a message using the optional params _sources and destinations in the sendCallmessage method. Is this currently possible? for this example to work we need to have (unless im misundestanding) a network connection that currently has both BTP and other (IBC?) type of underlying protocol, that way we can use one set of networks and showcase two different examples of sending a cross-chain message using two different protocols.
• (priority low): For the functionality of rollback now being guaranteed, I dont think there needs to be an example or a showcase for this in the documentation for developers, is an underlying functionality that improves upon the handling of the rollbacks, let me know if anyone has a different opinion on this.
• (priority high): retrieving the "success receipt" for a "two-way communication". Show an example in the docs showcasing this, how can the receipt be retrieved? do we need to show the 2 different ways this is handled in both xcall-v1 and xcall-v2?
• (priority high): describing the usage of "network ID" instead of "btp address"
• (priority high): Show an example on how to get the list of network IDs from the xcall contract (previously the BMC contract), calling getNetworkAddress will return the network Id of the current chain, calling getVerifiers will return the network Id and contract addresses (are these the xcall or BMC addresses?) of the connected networks.
• (priority high): clarification on CallExecuted event. When making the executeCall transaction on the destination chain (this example destination is Havah), I can see the CallExecuted event as this {"scoreAddress":"cxf35c6158382096ea8cf7c54ee338ddfcaf2869a3","indexed":["CallExecuted(int,int,str)","0x25"],"data":["0x0","UserReverted(0)"]}. the signature of this events is described as CallExecuted(_reqId, _code, _msg). for this event _reqId is the id of the message, _code I assume is the error code which can only be 0x0 or 0x1 (on which I assume 0x1 is a success?), for _msg is this the error message?
• (priority high): clarification on CallExecuted event. is the transaction to the dapp contract executed in the case that _code is 0x0 and 0x1 or only on 0x1?

[AntonAndell]

• " Describe an example for sending a message using the optional params _sources and destinations" You already did this with the multi protocol sample dapp but you only used 1 protocol but nothing much changes as you add more

• retrieving the "success receipt" for a "two-way communication". Not very high priority since it is only a pure addition to xCall v1 No core fucntionality changes due to this.

• "Show an example on how to get the list of network IDs from the xcall contract" This data will be kept offchain. To find available connections and networkIds one should check some type of off chain wiki. The docs mabye should contain this titself.

[FidelVe]

PR #31 closes this issue