Merge pull request #287 from darwinia-network/aki-update

Update to endpoint mode
darwinia-network · Jul 22, 2022 · 24631a0 · 24631a0
2 parents ef0b63e + f664b41
commit 24631a0
Show file tree

Hide file tree

Showing 8 changed files with 413 additions and 451 deletions.
diff --git a/docs/glossary.md b/docs/glossary.md
@@ -1,20 +1,32 @@
 ---
-sidebar_position: 4
+sidebar_position: 7
 ---
 
 # Glossary
 
-## Dapp
+## Endpoint
 
-Decentralized application.
+The cross-chain operation entry. An endpoint is a smart contract which is used by Dapps to do cross-chain operations. 
 
-## Dapp developer
+The endpoint contract is created and deployed by the Dapp developer. After that Dapp can call the endpoint to do cross-chain operations.
 
-Dapp developers include those who develop applications based on the Darwinia Smart Contracts module, as well as those who develop Dapps on public chains, such as blockchain games or Defi applications on platforms such as Ethereum, TRON or EOS.
+```js
+contract YourEndpoint is MessageEndpoint {...}
+```
 
-## Dapp user
+```js
+contract YourDapp {
+    YourEndpoint endpoint;
 
-End users of Dapps.
+    constructor(YourEndpoint _endpoint) {
+        endpoint = _endpoint;
+    }
+
+    function foo() {
+        YourEndpoint(endpoint).remoteExecute(...);
+    }
+}
+```
 
 ## Source Chain
 
@@ -49,11 +61,11 @@ The message is sent by the source chain application layer and finally delivered
 
 The intermediary of cross-chain data is responsible for fetching data from one blockchain and then sending the data to the other side.
 
-## Channel
+## Channel & Lane
 
-Channels facilitate the transfer of data in one direction. A channel consists of a sender `outbound` of the source chain and a receiver `inbound` of the destination chain. Any user or system that wants to send a message on the bridge must submit it to the channel. The message layer supports multiple channels and provides different deliverability guarantees for messages, such as message replay protection, message order or out-of-order guarantee, etc.
+Channels facilitate the transfer of data in one direction. A channel consists of a sender `outboundLane` of the source chain and a receiver `inboundLane` of the target chain. Any user or system that wants to send a message on the bridge must submit it to the `outboundLane`. The message layer supports multiple channels and provides different deliverability guarantees for messages, such as message replay protection, message order or out-of-order guarantee, etc.
 
-Messages sent over the channel are assigned a unique (for this channel) strictly increasing integer value of the nonce. Messages sent over the same channel are guaranteed to be sent to the destination chain in the same order they were sent from the source chain. In other words, messages with nonce `N` will be delivered before nonce `N+1`.
+Messages sent over the channel are assigned a unique (for this channel) strictly increasing integer value of the nonce. Messages sent over the same channel are guaranteed to be sent to the target chain in the same order they were sent from the source chain. In other words, messages with nonce `N` will be delivered before nonce `N+1`.
 
 A single message channel can be thought of as a transport channel for a single application (on-chain, off-chain, or hybrid).
 

diff --git a/docs/sdk/api-reference.md b/docs/sdk/api-reference.md
@@ -4,139 +4,187 @@ sidebar_position: 1
 
 # API Reference
 
-### Initialization 
+## _setRemoteEndpoint
 
-Before you start using the SDK, you need to set some globle settings in your initialization function.
+Set the remote endpoint.
+
+This is an internal function to be called by the concrete endpoint functions.
 
 ```javascript
-contract Demo is SmartChainXApp {
-    constructor() public {
-        // Globle settings for Pangolin
-        dispatchAddress = 0x0000000000000000000000000000000000000019;
-        callIndexOfSendMessage = 0x2b03;
-        storageAddress = 0x000000000000000000000000000000000000001a;
-        callbackSender = 0x6461722f64766D70000000000000000000000000;
-    }
-    ...
-}
+function _setRemoteEndpoint(bytes4 _remoteChainId, address _remoteEndpoint)
+    internal
+```
+
+### Params:    
+
+* _remoteChainId: The remote chain id. [The full chain id list](./constants)
+
+* _remoteEndpoint: The remote endpoint contract address.
+
+## _remoteDispatch
 
+Dispatch a substrate call of the target chain. 
+
+This is an internal function to be called by the concrete endpoint functions.
+
+```javascript
+function _remoteDispatch(
+    uint32 tgtSpecVersion,
+    bytes memory tgtCallEncoded,
+    uint64 tgtCallWeight
+) internal returns (uint256)
 ```
-If not set, the default is the settings of the Crab Network.
+### Params:    
+
+* tgtSpecVersion: The target chain's latest spec version.
+* tgtCallEncoded: The call to be dispatched on the target chain. It is a SCALE codec bytes.
+* tgtCallWeight: The weight of the call.
 
+### Return:
 
-### (Source Chain) sendMessage
+* message id
 
-Send a message through a bridge.
+## _remoteTransact
+
+Transact a evm call of the endpoint contract on the target chain.
+
+This is an internal function to be called by the concrete endpoint functions.
 
 ```javascript
-/// @notice Send message over a bridge
-/// @param bridge The bridge to send message
-/// @param payload The message payload to be sent
-/// @return nonce The nonce of the message
-function sendMessage(Bridge memory bridge, MessagePayload memory payload)
-    internal
-    returns (uint64)
+function _remoteTransact(
+    uint32 tgtSpecVersion,
+    bytes memory callPayload,
+    uint256 gasLimit
+) internal returns (uint256) 
+
 ```
+### Params:    
+
+* tgtSpecVersion: The target chain's latest spec version.
+* callPayload: The evm call to be transact on the target chain. It is a ABI codec bytes.
+* gasLimit: The gas limit to run the evm call.
+
+### Return:
+
+* message id
 
-Define the bridge to send message through:
+## _remoteExecute
+
+Execute a evm call of the target chain. The difference between the `_remoteExecute` and `_remoteTransact` is that `_remoteTransact` can only call functions of the remote endpoint, but `_remoteExecute` can call functions of other contracts as long as you allow.
+
+This is an internal function to be called by the concrete endpoint functions.
 
 ```javascript
-struct Bridge {
-    // The lane id
-    bytes4 srcOutlaneId;
-    // The storage key used to get market fee
-    bytes srcStorageKeyForMarketFee;
-    // The storage key used to get latest nonce
-    bytes srcStorageKeyForLatestNonce;
-}
+function _remoteExecute(
+    uint32 tgtSpecVersion,
+    address callReceiver,
+    bytes calldata callPayload,
+    uint256 gasLimit
+) internal returns (uint256)
 ```
+### Params:    
+
+* tgtSpecVersion: The target chain's latest spec version.
+* callReceiver: The contract address which has the function to be called.
+* callPayload: The evm call to be execute on the target chain. It is a ABI codec bytes.
+* gasLimit: The gas limit to run the evm call.
 
-Crab's bridges:
-1. To Darwinia bridge
-    ```javascript
-    Bridge memory bridge = Bridge(
-        // outlane id, lane to Darwinia
-        0,
-        // storage key for Darwinia market fee
-        hex"190d00dd4103825c78f55e5b5dbf8bfe2edb70953213f33a6ef6b8a5e3ffcab2",
-        // storage key for the latest nonce of Darwinia message lane
-        hex"c9b76e645ba80b6ca47619d64cb5e58d96c246acb9b55077390e3ca723a0ca1f11d2df4e979aa105cf552e9544ebd2b500000000"
-    );
-    ```
-
-Pangolin's bridges:
-1. To Pangoro bridge
-    ```javascript
-    Bridge memory bridge = Bridge(
-        // outlane id, lane to Darwinia
-        0,
-        // storage key for Darwinia market fee
-        hex"190d00dd4103825c78f55e5b5dbf8bfe2edb70953213f33a6ef6b8a5e3ffcab2",
-        // storage key for the latest nonce of Darwinia message lane
-        hex"c9b76e645ba80b6ca47619d64cb5e58d96c246acb9b55077390e3ca723a0ca1f11d2df4e979aa105cf552e9544ebd2b500000000"
-    );
-    ```
-    
-### (Source Chain) onMessageDelivered
-
-You need to implement this virtual function If you want to do something after the message is confirmed.
+### Return:
+
+* message id
+
+## fee
+
+Get the estimated cross-chain market fee.
 
 ```javascript
-/// @notice Callback function for 'send_message'
-/// @param lane Lane id
-/// @param nonce Nonce of the callback message
-/// @param result Dispatch result of cross chain message
-function onMessageDelivered(
-    bytes4 lane,
-    uint64 nonce,
-    bool result
-) external virtual;
+function fee() public view returns (uint256)
 ```
 
-If you don't want this function to be wrongly called, you should add a check to the first line of your implemention like this,
+### Return:
+
+* the estimated cross-chain market fee. The decimals is 18.
+
+## modifier onlyMessageSender
+
+This modifier is used to restrict a function to be called only by the remote sender.
 
 ```javascript
-contract RemarkDemo is SmartChainXApp {
-    ...
-
-    function onMessageDelivered(
-        bytes4 lane,
-        uint64 nonce,
-        bool result
-    ) external override {
-        require(msg.sender == callbackSender, "Only pallet address is allowed call 'onMessageDelivered'");
-        // TODO: Your code goes here...
-    }
-}
+modifier onlyMessageSender()
 ```
 
-Callback sender list:
+## execute
 
-### (Target Chain) requireSenderOfSourceChain
+This external function is called remotely to execute an evm call.
 
-When a function on the target chain is called by source chain, in order to ensure that this function can only be called by the sender on the source chain, this check needs to be added to the first line of the function.
+It is the mate of `_remoteExecute`.
 
 ```javascript
-/// @notice This function is used to check the sender.
-/// @param srcChainId The source chain id
-/// @param sender The sender of the message on the source chain
-function requireSenderOfSourceChain(bytes4 srcChainId, address sender)
+function execute(address callReceiver, bytes calldata callPayload)
+    external
+    onlyMessageSender
+```
+
+## _canBeExecuted
+
+This is an internal virtual function to be overrided.
+
+It is used to check if a call can be executed on the receiver contract.
+
+```javascript
+function _canBeExecuted(address callReceiver, bytes calldata callPayload)
     internal
+    view
+    virtual
+    returns (bool)
+```
+
+## lastDeliveredMessageId
+
+Get the last delivered **inbound** message id.
+
+```javascript
+function lastDeliveredMessageId() public view returns (uint256)
+```
+
+### Return:
+
+* The last delivered inbound message id
+
+## isMessageDelivered
+
+Check if an **inbound** message has been delivered.
+
+```javascript
+function isMessageDelivered(uint256 messageId) public view returns (bool)
 ```
 
-example:
+### Params:    
+
+* messageId: The inbound message id.
+
+## encodeMessageId
+
+Build a message by encoding a lane id and a message nonce.
 
 ```javascript
-contract Demo is SmartChainXApp {
-    uint256 public number;
+function encodeMessageId(bytes4 laneId, uint64 nonce)
+    public
+    pure
+    returns (uint256)
+```
+
+## decodeMessageId
 
-    // this `add` function will be called by `0x6Be02d1d3665660d22FF9624b7BE0551ee1Ac91b` on source chain
-    function add(uint256 _value) public {
-        requireSenderOfSourceChain(0, 0x6Be02d1d3665660d22FF9624b7BE0551ee1Ac91b);
-        number = number + _value;
-    }
+Decode a message into a lane id and a message nonce.
+
+```javascript
+function decodeMessageId(uint256 messageId)
+    public
+    pure
+    returns (bytes4, uint64)
+```
 
-    ...
-}
+### Params:    
 
-```
+* messageId: The inbound message id.
diff --git a/docs/sdk/constants.md b/docs/sdk/constants.md
@@ -0,0 +1,25 @@
+---
+sidebar_position: 6
+---
+
+# Constants
+
+## Chain Identifiers
+
+The chain identifier is used to uniquely identify the chain and is entered as a parameter when [setting the remote endpoint](./api-reference.md#_setRemoteEndpoint).
+
+    bytes4 constant _DARWINIA_CHAIN_ID = 0x64617277; // darw
+    bytes4 constant _CRAB_CHAIN_ID = 0x63726162; // crab
+    bytes4 constant _PANGORO_CHAIN_ID = 0x70616772; // pagr
+    bytes4 constant _PANGOLIN_CHAIN_ID = 0x7061676c; // pagl
+    bytes4 constant _PANGOLIN_PARACHAIN_CHAIN_ID = 0x70676c70; // pglp
+    bytes4 constant _CRAB_PARACHAIN_CHAIN_ID = 0x63726170; // crap
+
+## Lane Identifiers
+
+The lane identifier identify the channel used to send and receive messages. Go to [Glossary](../glossary#channel--lane) to see more info. 
+
+    bytes4 constant _DARWINIA_CRAB_LANE_ID = 0x00000000;
+    bytes4 constant _PANGORO_PANGOLIN_LANE_ID = 0x726f6c69; // roli
+    bytes4 constant _PANGOLIN_PANGOLIN_PARACHAIN_LANE_ID = 0x70616c69; // pali
+    bytes4 constant _CRAB_CRAB_PARACHAIN_LANE_ID = 0x70616372; // pali