improve polkadot-sdk documentation

polytope-labs · Nov 21, 2024 · acbe906 · acbe906
1 parent a877701
commit acbe906
Show file tree

Hide file tree

Showing 19 changed files with 665 additions and 497 deletions.
diff --git a/docs/pages/developers/evm/dispatching.mdx b/docs/pages/developers/evm/dispatching.mdx
@@ -9,7 +9,7 @@ A POST request is simply a cross-chain message to be executed by some `IIsmpModu
 A post request is created using the `DispatchPost` struct
 
 ```solidity showLineNumbers
-// An object for dispatching post requests to the IsmpDispatcher
+// An object for dispatching post requests 
 struct DispatchPost {
     // Use the StateMachine library to create this
     bytes dest;
@@ -19,14 +19,15 @@ struct DispatchPost {
     bytes body;
     // timeout for this request in seconds
     uint64 timeout;
-    // The amount put up to be paid to the relayer, this is in $DAI and charged to tx.origin
+    // The amount put up to be paid to the relayer, 
+    // this is in DAI and charged to msg.sender
     uint256 fee;
     // who pays for this request?
     address payer;
 }
 ```
 
-### Dispatch Parameters:
+### Dispatch Parameters
 
 - `dest`: Destination chain, for this you'll use the `StateMachine` library eg `StateMachine.evm(1)` for Ethereum Mainnet.
 
@@ -38,7 +39,8 @@ struct DispatchPost {
 
 - `body`: Serialized byte representation of the message (to be decoded by the receiving contract).
   <br />
-- `timeout`: Relative time in seconds for message validity. Messages exceeding this timeout cannot be processed on the destination and require user action (timeout message) to revert changes.
+- `timeout`: Time in seconds for message validity eg 3600 for a timeout of 1 hour, or 0 for no timeout. ie Messages will never expire. If the timeout is set to a non-zero value, messages that have exceeded this timeout will be rejected on the destination and require user action
+  (timeout message) to revert changes.
   <br />
 - `fee`: Optional relayer fees, this can also be set to zero if the application developers prefer to self-relay.
   <br />
@@ -71,22 +73,23 @@ Dispatching a POST response, going by it's name is, well, a response to a previo
 A post response dispatch has the following fields:
 
 ```solidity showLineNumbers
-// An object for dispatching post responses to the IsmpDispatcher
+// An object for dispatching post responses 
 struct DispatchPostResponse {
     // The request that initiated this response
     PostRequest request;
     // bytes for post response
     bytes response;
     // timeout for this response in seconds
     uint64 timeout;
-    // the amount put up to be paid to the relayer, this is in $DAI and charged to tx.origin
+    // The amount put up to be paid to the relayer, 
+    // this is in DAI and charged to msg.sender
     uint256 fee;
     // who pays for this request?
     address payer;
 }
 ```
 
-### Dispatch Parameters:
+### Dispatch Parameters
 
 - `request`: The request object that was previously received.
 
@@ -96,7 +99,7 @@ struct DispatchPostResponse {
 
   <br />
 
-- `timeout`: Relative time in seconds for message validity. Messages exceeding this timeout cannot be processed on the destination and require user action
+- `timeout`: Time in seconds for message validity eg 3600 for a timeout of 1 hour, or 0 for no timeout. ie Messages will never expire. If the timeout is set to a non-zero value, messages that have exceeded this timeout will be rejected on the destination and require user action
   (timeout message) to revert changes.
 
   <br />
@@ -136,7 +139,7 @@ When dispatching get requests,
 you specify the storage keys you need to read and the block height at which you need to read these storage entries.
 
 ```solidity
-// An object for dispatching get requests to the IsmpDispatcher
+// An object for dispatching get requests 
 struct DispatchGet {
     // bytes representation of the destination state machine
     bytes dest;
@@ -153,7 +156,7 @@ struct DispatchGet {
 }
 ```
 
-### Dispatch Parameters:
+### Dispatch Parameters
 
 - `dest`: The chain whose database should be read (e.g., `StateMachine.evm(1)` for Ethereum Mainnet).
 
@@ -167,8 +170,8 @@ struct DispatchGet {
 
   <br />
 
-- `timeout`: Relative time in seconds for message validity. Responses exceeding this timeout cannot be processed on the source and require user action (timeout
-  message) to revert changes.
+- `timeout`: Time in seconds for message validity eg 3600 for a timeout of 1 hour, or 0 for no timeout. ie Messages will never expire. If the timeout is set to a non-zero value, messages that have exceeded this timeout will be rejected on the destination and require user action
+  (timeout message) to revert changes.
 
   <br />
 

diff --git a/docs/pages/developers/evm/receiving.mdx b/docs/pages/developers/evm/receiving.mdx
@@ -4,43 +4,41 @@ To receive ISMP messages a contract must implement the [`IIsmpModule`](https://g
 
 The required methods for the [`IIsmpModule`](https://github.com/polytope-labs/ismp-solidity/blob/main/interfaces/IIsmpModule.sol#L42) is described in detail below:
 
-
 ## `onAccept`
 
-This is the callback method for new POST requests that have been verified by Hyperbridge. After the `IHandler` verifies the neccessary proofs of this request, they are passed on to the host, which in turn calls the `onAccept` method for the intended modules. The arguments provided `IncomingPostRequest` holds both the request object itself and the account that initally called the Handler contract, this may be either a 3rd party relayer or a user who is self-relaying.
+This is the callback method for new POST requests that have been verified by Hyperbridge. After the `IHandler` verifies the necessary proofs of this request, they are passed on to the host, which in turn calls the `onAccept` method for the intended modules. The arguments provided `IncomingPostRequest` holds both the request object itself and the account that initally called the Handler contract, this may be either a 3rd party relayer or a user who is self-relaying.
 
 `IIsmpModule`'s should ensure that is method is only callable by the `host` or risk critical vulnerabilies from unauthorized calls to this method by malicious actors. A modifier `onlyHost` is provided as part of the `BaseIsmpModule` for this.
 
 ## `onPostRequestTimeout`
 
 In the event that some initially dispatched request was unable to be delivered. Whether as a result of insufficient fees provided to the relayers, Or a revert during request execution on the destination chain. Then Hyperbridge allows this request to gracefully timeout, and this timeout can be reported back to the sending module on the source chain.
 
-This callback is provided as a way to execute some logic in the event that some request times out. This can be seen as a *catch* block in a try/catch for cross-chain messages. Typically you'll want to revert any state changes that were made prior to dispatching the request.
+This callback is provided as a way to execute some logic in the event that some request times out. This can be seen as a _catch_ block in a try/catch for cross-chain messages. Typically you'll want to revert any state changes that were made prior to dispatching the request.
 
 ## `onPostResponse`
 
-This is the callback method for new POST responses that have been verified by Hyperbridge. After the `IHandler` verifies the neccessary proofs of this response, they are passed on to the host, which in turn calls the `onPostResponse` method for the intended modules. The arguments provided `IncomingPostResponse` holds both the resopnse object itself and the account that initally called the Handler contract, this may be either a 3rd party relayer or a user who is self-relaying.
+This is the callback method for new POST responses that have been verified by Hyperbridge. After the `IHandler` verifies the necessary proofs of this response, they are passed on to the host, which in turn calls the `onPostResponse` method for the intended modules. The arguments provided `IncomingPostResponse` holds both the resopnse object itself and the account that initally called the Handler contract, this may be either a 3rd party relayer or a user who is self-relaying.
 
 `IIsmpModule`'s should ensure that is method is only callable by the `host` or risk critical vulnerabilies from unauthorized calls to this method by malicious actors. A modifier `onlyHost` is provided as part of the `BaseIsmpModule` for this.
 
 ## `onPostResponseTimeout`
 
 In the event that some initially dispatched response was unable to be delivered. Whether as a result of insufficient fees provided to the relayers, Or a revert during response execution on the destination chain. Then Hyperbridge allows this response to gracefully timeout, and this timeout can be reported back to the sending module on the source chain.
 
-This callback is provided as a way to execute some logic in the event that some response times out. This can be seen as a *catch* block in a try/catch for cross-chain messages. Typically you'll want to revert any state changes that were made prior to dispatching the response.
+This callback is provided as a way to execute some logic in the event that some response times out. This can be seen as a _catch_ block in a try/catch for cross-chain messages. Typically you'll want to revert any state changes that were made prior to dispatching the response.
 
 ## `onGetResponse`
 
-This is the callback method for new GET responses that have been verified by Hyperbridge. After the `IHandler` verifies the neccessary proofs of this response, they are passed on to the host, which in turn calls the `onGetResponse` method for the intended modules. The arguments provided `IncomingGetResponse` holds both the resopnse object itself and the account that initally called the Handler contract, this may be either a 3rd party relayer or a user who is self-relaying.
+This is the callback method for new GET responses that have been verified by Hyperbridge. After the `IHandler` verifies the necessary proofs of this response, they are passed on to the host, which in turn calls the `onGetResponse` method for the intended modules. The arguments provided `IncomingGetResponse` holds both the resopnse object itself and the account that initally called the Handler contract, this may be either a 3rd party relayer or a user who is self-relaying.
 
 `IIsmpModule`'s should ensure that is method is only callable by the `host` or risk critical vulnerabilies from unauthorized calls to this method by malicious actors. A modifier `onlyHost` is provided as part of the `BaseIsmpModule` for this.
 
 ## `onGetTimeout`
 
 In the event that some GET request is unable to be processed. Likely as a result of insufficient fees provided. Then Hyperbridge allows this request to gracefully timeout, and this timeout can be reported back to the sending module on the source chain.
 
-This callback is provided as a way to execute some logic in the event that some request times out. This can be seen as a *catch* block in a try/catch for cross-chain messages. Typically you'll want to revert any state changes that were made prior to dispatching the request.
-
+This callback is provided as a way to execute some logic in the event that some request times out. This can be seen as a _catch_ block in a try/catch for cross-chain messages. Typically you'll want to revert any state changes that were made prior to dispatching the request.
 
 ## Example `IIsmpModule`
 
@@ -90,43 +88,66 @@ contract Example is BaseIsmpModule {
         return IDispatcher(host).dispatch{value: msg.value}(post);
     }
 
-    function onAccept(IncomingPostRequest memory incoming) external override onlyHost {
+    function onAccept(IncomingPostRequest memory incoming)
+        external
+        override
+        onlyHost
+    {
         // decode request body
-        // Check that decoded value can be executed successfully
-        // Make state changes
+        // make any necessary state changes
         emit PostReceived();
     }
 
-    function onPostRequestTimeout(PostRequest memory request) external override onlyHost {
-        // revert any state changes made when post request was dispatched
+    function onPostRequestTimeout(PostRequest memory request)
+        external
+        override
+        onlyHost
+    {
+        // revert any state changes made
+        // when post request was dispatched
         emit PostTimeoutReceived();
     }
 
-    function onPostResponse(IncomingPostResponse memory) external override onlyHost {
+    function onPostResponse(IncomingPostResponse memory)
+        external
+        override
+        onlyHost
+    {
         // decode response
-        // Check that decoded value can be executed successfully
-        // Make state changes
+        // make any necessary state changes
         emit PostResponseReceived();
     }
 
-    function onPostResponseTimeout(PostResponse memory) external override onlyHost {
-        // revert any state changes made when post response was dispatched
+    function onPostResponseTimeout(PostResponse memory)
+        external
+        override
+        onlyHost
+    {
+        // revert any state changes made
+        // when post response was dispatched
         emit PostResponseTimeoutReceived();
     }
 
-    function onGetResponse(IncomingGetResponse memory) external override onlyHost {
+    function onGetResponse(IncomingGetResponse memory)
+        external
+        override
+        onlyHost
+    {
         emit GetResponseReceived();
     }
 
-    function onGetTimeout(GetRequest memory) external override onlyHost {
-        // revert any state changes made when get request was dispatched
+    function onGetTimeout(GetRequest memory)
+        external
+        override
+        onlyHost
+    {
+        // revert any state changes
+        // made when get request was dispatched
         emit GetTimeoutReceived();
     }
 }
 ```
 
-
 ## Security Considerations
 
-* Limit the caller of these functions to the `IIsmpHost` contract only. This prevents unauthorized messages from being executed.
-
+- Limit the caller of these functions to the `IIsmpHost` contract only. This prevents unauthorized messages from being executed.
diff --git a/docs/pages/developers/explore/index.mdx b/docs/pages/developers/explore/index.mdx
@@ -9,5 +9,5 @@ Hyperbridge brings together advanced cryptographic and mechanistic protocols to
 
 The protocol is facilitated by:
 
- - A permissionless set of relayers who transmit cross-chain messages authenticated by cryptographic proofs.
- - Hyperbridge Nexus, a blockchain that serves a crypto-economic coprocessor for aggregating interoperability proofs.
+ - A permissionless set of relayers that transmit cross-chain messages authenticated by cryptographic proofs.
+ - Hyperbridge Nexus, a blockchain that serves as a crypto-economic coprocessor for aggregating interoperability proofs.
diff --git a/docs/pages/developers/network/node.mdx b/docs/pages/developers/network/node.mdx
@@ -102,7 +102,8 @@ rustup component add rust-src
 Download a local copy of the repo and checkout the latest release tag
 
 ```bash
-export LATEST_TAG=hyperbridge-v0.5.0
+# fetch the latest tag from docker hub
+LATEST_TAG=$(curl -s https://hub.docker.com/v2/repositories/polytopelabs/hyperbridge/tags\?page_size\=1\&page\=2 | jq -r '.results[0].name')
 git clone https://github.com/polytope-labs/hyperbridge.git
 cd ./hyperbridge
 git checkout ${LATEST_TAG}
@@ -162,28 +163,6 @@ hyperbridge \
     --sync=fast-unsafe
 ```
 
-### Kusama
-
-Hyperbridge is live on Kusama with a chainId of `messier` and ParaId of `3340`. We do not recommend joining the kusama network at this time.
-
-```bash
-export PUBLIC_IP_ADDRESS=<your-node-public-ip-address>
-hyperbridge \
-    --base-path=$HOME/.hyperbridge \
-    --pruning=archive \
-    --name="Your node name here"  \
-    --rpc-cors=all \
-    --rpc-port=9944 \
-    --unsafe-rpc-external \
-    --rpc-methods=unsafe \
-    --chain=messier \
-    --no-mdns \
-    --listen-addr=/ip4/0.0.0.0/tcp/30333 \
-    --listen-addr=/ip6/::/tcp/30333 \
-    --public-addr=/ip4/$PUBLIC_IP_ADDRESS/tcp/30333 \
-    --out-peers=32
-```
-
 ### Polkadot
 
 Hyperbridge is also live on Polkadot with a chainId of `nexus` and ParaId of `3367`.