Docs (#156)

* docs * Fix review
ringecosystem · Oct 31, 2023 · e9a80d5 · e9a80d5
1 parent 881609f
commit e9a80d5
Show file tree

Hide file tree

Showing 19 changed files with 300 additions and 20 deletions.
diff --git a/src/Application.sol b/src/Application.sol
@@ -1,4 +1,19 @@
-// SPDX-License-Identifier: MIT
+// This file is part of Darwinia.
+// Copyright (C) 2018-2023 Darwinia Network
+// SPDX-License-Identifier: GPL-3.0
+//
+// Darwinia is free software: you can redistribute it and/or modify
+// it under the terms of the GNU General Public License as published by
+// the Free Software Foundation, either version 3 of the License, or
+// (at your option) any later version.
+//
+// Darwinia is distributed in the hope that it will be useful,
+// but WITHOUT ANY WARRANTY; without even the implied warranty of
+// MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
+// GNU General Public License for more details.
+//
+// You should have received a copy of the GNU General Public License
+// along with Darwinia. If not, see <https://www.gnu.org/licenses/>.
 
 pragma solidity ^0.8.17;
 
@@ -7,15 +22,17 @@ abstract contract Application {
         _line = payable(msg.sender);
     }
 
+    /// @notice The cross-chain message source chainId
     function _fromChainId() internal pure returns (uint256 _msgDataFromChainId) {
         require(msg.data.length >= 52, "!fromChainId");
         assembly {
             _msgDataFromChainId := calldataload(sub(calldatasize(), 52))
         }
     }
 
+    /// @notice Get the source chain fromDapp address.
     function _xmsgSender() internal pure returns (address payable _from) {
-        require(msg.data.length >= 20, "!line");
+        require(msg.data.length >= 20, "!fromDapp");
         assembly {
             _from := shr(96, calldataload(sub(calldatasize(), 20)))
         }

diff --git a/src/LineRegistry.sol b/src/LineRegistry.sol
@@ -1,10 +1,28 @@
-// SPDX-License-Identifier: MIT
+// This file is part of Darwinia.
+// Copyright (C) 2018-2023 Darwinia Network
+// SPDX-License-Identifier: GPL-3.0
+//
+// Darwinia is free software: you can redistribute it and/or modify
+// it under the terms of the GNU General Public License as published by
+// the Free Software Foundation, either version 3 of the License, or
+// (at your option) any later version.
+//
+// Darwinia is distributed in the hope that it will be useful,
+// but WITHOUT ANY WARRANTY; without even the implied warranty of
+// MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
+// GNU General Public License for more details.
+//
+// You should have received a copy of the GNU General Public License
+// along with Darwinia. If not, see <https://www.gnu.org/licenses/>.
 
 pragma solidity ^0.8.17;
 
 import "@openzeppelin/contracts/access/Ownable2Step.sol";
 import "./interfaces/ILineMetadata.sol";
 
+/// @title LineRegistry
+/// @notice LineRegistry will be deployed on each chain. 
+///         It is the registry of messageLine and can be used to verify whether the line has been registered.
 contract LineRegistry is Ownable2Step {
     // lineName => lineAddress
     mapping(string => address) private _lineLookup;

diff --git a/src/chain-id-mappings/AxelarChainIdMapping.sol b/src/chain-id-mappings/AxelarChainIdMapping.sol
@@ -1,5 +1,5 @@
 // This file is part of Darwinia.
-// Copyright (C) 2018-2022 Darwinia Network
+// Copyright (C) 2018-2023 Darwinia Network
 // SPDX-License-Identifier: GPL-3.0
 //
 // Darwinia is free software: you can redistribute it and/or modify

diff --git a/src/chain-id-mappings/CelerChainIdMapping.sol b/src/chain-id-mappings/CelerChainIdMapping.sol
@@ -1,5 +1,5 @@
 // This file is part of Darwinia.
-// Copyright (C) 2018-2022 Darwinia Network
+// Copyright (C) 2018-2023 Darwinia Network
 // SPDX-License-Identifier: GPL-3.0
 //
 // Darwinia is free software: you can redistribute it and/or modify

diff --git a/src/chain-id-mappings/LayerZeroChainIdMapping.sol b/src/chain-id-mappings/LayerZeroChainIdMapping.sol
@@ -1,5 +1,5 @@
 // This file is part of Darwinia.
-// Copyright (C) 2018-2022 Darwinia Network
+// Copyright (C) 2018-2023 Darwinia Network
 // SPDX-License-Identifier: GPL-3.0
 //
 // Darwinia is free software: you can redistribute it and/or modify

diff --git a/src/examples/ExampleReceiverDapp.sol b/src/examples/ExampleReceiverDapp.sol
@@ -1,4 +1,19 @@
-// SPDX-License-Identifier: MIT
+// This file is part of Darwinia.
+// Copyright (C) 2018-2023 Darwinia Network
+// SPDX-License-Identifier: GPL-3.0
+//
+// Darwinia is free software: you can redistribute it and/or modify
+// it under the terms of the GNU General Public License as published by
+// the Free Software Foundation, either version 3 of the License, or
+// (at your option) any later version.
+//
+// Darwinia is distributed in the hope that it will be useful,
+// but WITHOUT ANY WARRANTY; without even the implied warranty of
+// MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
+// GNU General Public License for more details.
+//
+// You should have received a copy of the GNU General Public License
+// along with Darwinia. If not, see <https://www.gnu.org/licenses/>.
 
 pragma solidity ^0.8.17;
 
@@ -17,6 +32,7 @@ contract ExampleReceiverDapp is Application {
         DAPP = dapp;
     }
 
+    /// @notice You could check the fromDapp address or messageLine address.
     function xxx(bytes calldata message) external {
         uint256 fromChainId = _fromChainId();
         address fromDapp = _xmsgSender();

diff --git a/src/interfaces/ILineMetadata.sol b/src/interfaces/ILineMetadata.sol
@@ -1,7 +1,27 @@
-// SPDX-License-Identifier: MIT
+// This file is part of Darwinia.
+// Copyright (C) 2018-2023 Darwinia Network
+// SPDX-License-Identifier: GPL-3.0
+//
+// Darwinia is free software: you can redistribute it and/or modify
+// it under the terms of the GNU General Public License as published by
+// the Free Software Foundation, either version 3 of the License, or
+// (at your option) any later version.
+//
+// Darwinia is distributed in the hope that it will be useful,
+// but WITHOUT ANY WARRANTY; without even the implied warranty of
+// MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
+// GNU General Public License for more details.
+//
+// You should have received a copy of the GNU General Public License
+// along with Darwinia. If not, see <https://www.gnu.org/licenses/>.
+
 pragma solidity ^0.8.0;
 
 interface ILineMetadata {
+    /// @notice Get the line name, it's globally unique and immutable.
+    /// @return The MessageLine name.
     function name() external view returns (string memory);
+
+    /// @return The line metadata uri.
     function uri() external view returns (string memory);
 }
diff --git a/src/interfaces/IMessageLine.sol b/src/interfaces/IMessageLine.sol
@@ -1,11 +1,40 @@
-// SPDX-License-Identifier: MIT
+// This file is part of Darwinia.
+// Copyright (C) 2018-2023 Darwinia Network
+// SPDX-License-Identifier: GPL-3.0
+//
+// Darwinia is free software: you can redistribute it and/or modify
+// it under the terms of the GNU General Public License as published by
+// the Free Software Foundation, either version 3 of the License, or
+// (at your option) any later version.
+//
+// Darwinia is distributed in the hope that it will be useful,
+// but WITHOUT ANY WARRANTY; without even the implied warranty of
+// MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
+// GNU General Public License for more details.
+//
+// You should have received a copy of the GNU General Public License
+// along with Darwinia. If not, see <https://www.gnu.org/licenses/>.
+
 pragma solidity ^0.8.0;
 
 interface IMessageLine {
     error MessageFailure(bytes errorData);
 
+    /// @dev Send a cross-chain message over the MessageLine.
+    /// @notice Send a cross-chain message over the MessageLine.
+    /// @param toChainId The message destination chain id. <https://eips.ethereum.org/EIPS/eip-155>
+    /// @param toDapp The user application contract address which receive the message.
+    /// @param message The calldata which encoded by ABI Encoding.
+    /// @param params Extend parameters to adapt to different message protocols.
     function send(uint256 toChainId, address toDapp, bytes calldata message, bytes calldata params) external payable;
 
+    /// @notice Get a quote in source native gas, for the amount that send() requires to pay for message delivery.
+    ///         It should be noted that not all lines will implement this interface.
+    /// @dev If the messaging protocol does not support on-chain fetch fee, then revert with "Unimplemented!".
+    /// @param toChainId The message destination chain id. <https://eips.ethereum.org/EIPS/eip-155>
+    /// @param toDapp The user application contract address which receive the message.
+    /// @param message The calldata which encoded by ABI Encoding.
+    /// @param params Extend parameters to adapt to different message protocols.
     function fee(uint256 toChainId, address toDapp, bytes calldata message, bytes calldata params)
         external
         view

diff --git a/src/lines/AxelarLine.sol b/src/lines/AxelarLine.sol
@@ -1,4 +1,19 @@
-// SPDX-License-Identifier: MIT
+// This file is part of Darwinia.
+// Copyright (C) 2018-2023 Darwinia Network
+// SPDX-License-Identifier: GPL-3.0
+//
+// Darwinia is free software: you can redistribute it and/or modify
+// it under the terms of the GNU General Public License as published by
+// the Free Software Foundation, either version 3 of the License, or
+// (at your option) any later version.
+//
+// Darwinia is distributed in the hope that it will be useful,
+// but WITHOUT ANY WARRANTY; without even the implied warranty of
+// MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
+// GNU General Public License for more details.
+//
+// You should have received a copy of the GNU General Public License
+// along with Darwinia. If not, see <https://www.gnu.org/licenses/>.
 
 pragma solidity ^0.8.17;
 

diff --git a/src/lines/CelerLine.sol b/src/lines/CelerLine.sol
@@ -1,4 +1,19 @@
-// SPDX-License-Identifier: MIT
+// This file is part of Darwinia.
+// Copyright (C) 2018-2023 Darwinia Network
+// SPDX-License-Identifier: GPL-3.0
+//
+// Darwinia is free software: you can redistribute it and/or modify
+// it under the terms of the GNU General Public License as published by
+// the Free Software Foundation, either version 3 of the License, or
+// (at your option) any later version.
+//
+// Darwinia is distributed in the hope that it will be useful,
+// but WITHOUT ANY WARRANTY; without even the implied warranty of
+// MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
+// GNU General Public License for more details.
+//
+// You should have received a copy of the GNU General Public License
+// along with Darwinia. If not, see <https://www.gnu.org/licenses/>.
 
 pragma solidity 0.8.9;
 

diff --git a/src/lines/DarwiniaLine.sol b/src/lines/DarwiniaLine.sol
@@ -1,4 +1,19 @@
-// SPDX-License-Identifier: MIT
+// This file is part of Darwinia.
+// Copyright (C) 2018-2023 Darwinia Network
+// SPDX-License-Identifier: GPL-3.0
+//
+// Darwinia is free software: you can redistribute it and/or modify
+// it under the terms of the GNU General Public License as published by
+// the Free Software Foundation, either version 3 of the License, or
+// (at your option) any later version.
+//
+// Darwinia is distributed in the hope that it will be useful,
+// but WITHOUT ANY WARRANTY; without even the implied warranty of
+// MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
+// GNU General Public License for more details.
+//
+// You should have received a copy of the GNU General Public License
+// along with Darwinia. If not, see <https://www.gnu.org/licenses/>.
 
 pragma solidity ^0.8.17;
 

diff --git a/src/lines/DarwiniaS2SLine.sol b/src/lines/DarwiniaS2SLine.sol
@@ -1,4 +1,20 @@
-// SPDX-License-Identifier: MIT
+// This file is part of Darwinia.
+// Copyright (C) 2018-2023 Darwinia Network
+// SPDX-License-Identifier: GPL-3.0
+//
+// Darwinia is free software: you can redistribute it and/or modify
+// it under the terms of the GNU General Public License as published by
+// the Free Software Foundation, either version 3 of the License, or
+// (at your option) any later version.
+//
+// Darwinia is distributed in the hope that it will be useful,
+// but WITHOUT ANY WARRANTY; without even the implied warranty of
+// MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
+// GNU General Public License for more details.
+//
+// You should have received a copy of the GNU General Public License
+// along with Darwinia. If not, see <https://www.gnu.org/licenses/>.
+
 pragma solidity ^0.8.17;
 
 import "./base/BaseMessageLine.sol";

diff --git a/src/lines/LayerZeroLine.sol b/src/lines/LayerZeroLine.sol
@@ -1,4 +1,19 @@
-// SPDX-License-Identifier: MIT
+// This file is part of Darwinia.
+// Copyright (C) 2018-2023 Darwinia Network
+// SPDX-License-Identifier: GPL-3.0
+//
+// Darwinia is free software: you can redistribute it and/or modify
+// it under the terms of the GNU General Public License as published by
+// the Free Software Foundation, either version 3 of the License, or
+// (at your option) any later version.
+//
+// Darwinia is distributed in the hope that it will be useful,
+// but WITHOUT ANY WARRANTY; without even the implied warranty of
+// MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
+// GNU General Public License for more details.
+//
+// You should have received a copy of the GNU General Public License
+// along with Darwinia. If not, see <https://www.gnu.org/licenses/>.
 
 pragma solidity ^0.8.17;
 

diff --git a/src/lines/ORMPLine.sol b/src/lines/ORMPLine.sol
@@ -1,4 +1,20 @@
-// SPDX-License-Identifier: MIT
+// This file is part of Darwinia.
+// Copyright (C) 2018-2023 Darwinia Network
+// SPDX-License-Identifier: GPL-3.0
+//
+// Darwinia is free software: you can redistribute it and/or modify
+// it under the terms of the GNU General Public License as published by
+// the Free Software Foundation, either version 3 of the License, or
+// (at your option) any later version.
+//
+// Darwinia is distributed in the hope that it will be useful,
+// but WITHOUT ANY WARRANTY; without even the implied warranty of
+// MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
+// GNU General Public License for more details.
+//
+// You should have received a copy of the GNU General Public License
+// along with Darwinia. If not, see <https://www.gnu.org/licenses/>.
+
 pragma solidity ^0.8.17;
 
 import "./base/BaseMessageLine.sol";

diff --git a/src/lines/base/BaseMessageLine.sol b/src/lines/base/BaseMessageLine.sol
@@ -1,4 +1,19 @@
-// SPDX-License-Identifier: MIT
+// This file is part of Darwinia.
+// Copyright (C) 2018-2023 Darwinia Network
+// SPDX-License-Identifier: GPL-3.0
+//
+// Darwinia is free software: you can redistribute it and/or modify
+// it under the terms of the GNU General Public License as published by
+// the Free Software Foundation, either version 3 of the License, or
+// (at your option) any later version.
+//
+// Darwinia is distributed in the hope that it will be useful,
+// but WITHOUT ANY WARRANTY; without even the implied warranty of
+// MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
+// GNU General Public License for more details.
+//
+// You should have received a copy of the GNU General Public License
+// along with Darwinia. If not, see <https://www.gnu.org/licenses/>.
 
 pragma solidity ^0.8.0;
 
@@ -12,6 +27,13 @@ abstract contract BaseMessageLine is IMessageLine, LineMetadata {
         return block.chainid;
     }
 
+    /// @dev Send a cross-chain message over the MessageLine.
+    ///      Line developer should implement this, then it will be called by `send`.
+    /// @param fromDapp The real sender account who send the message.
+    /// @param toChainId The message destination chain id. <https://eips.ethereum.org/EIPS/eip-155>
+    /// @param toDapp The user application contract address which receive the message.
+    /// @param message The calldata which encoded by ABI Encoding.
+    /// @param params Extend parameters to adapt to different message protocols.
     function _send(address fromDapp, uint256 toChainId, address toDapp, bytes calldata message, bytes calldata params)
         internal
         virtual;
@@ -20,6 +42,12 @@ abstract contract BaseMessageLine is IMessageLine, LineMetadata {
         _send(msg.sender, toChainId, toDapp, message, params);
     }
 
+    /// @dev Make toDapp accept messages.
+    ///      This should be called by message line when a message is received.
+    /// @param fromChainId The source chainId, standard evm chainId.
+    /// @param fromDapp The message sender in source chain.
+    /// @param toDapp The message receiver in dest chain.
+    /// @param message The message body.
     function _recv(uint256 fromChainId, address fromDapp, address toDapp, bytes memory message)
         internal
         returns (bytes memory)

diff --git a/src/lines/base/FromLineLookup.sol b/src/lines/base/FromLineLookup.sol
@@ -1,4 +1,19 @@
-// SPDX-License-Identifier: MIT
+// This file is part of Darwinia.
+// Copyright (C) 2018-2023 Darwinia Network
+// SPDX-License-Identifier: GPL-3.0
+//
+// Darwinia is free software: you can redistribute it and/or modify
+// it under the terms of the GNU General Public License as published by
+// the Free Software Foundation, either version 3 of the License, or
+// (at your option) any later version.
+//
+// Darwinia is distributed in the hope that it will be useful,
+// but WITHOUT ANY WARRANTY; without even the implied warranty of
+// MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
+// GNU General Public License for more details.
+//
+// You should have received a copy of the GNU General Public License
+// along with Darwinia. If not, see <https://www.gnu.org/licenses/>.
 
 pragma solidity ^0.8.0;