CCIP: get status offchain (#1825)

* CCIP: get status offchain

* Apply suggestions from code review

Co-authored-by: Dwight Lyle <dwightjl@gmail.com>

* add offchain page

* add offchain page

* add offchain page

---------

Co-authored-by: Dwight Lyle <dwightjl@gmail.com>

src/config/sidebar.ts

@@ -886,8 +886,18 @@ export const SIDEBAR: Partial<Record<Sections, SectionEntry[]>> = {
           url: "ccip/tutorials/programmable-token-transfers-defensive",
         },
         {
-          title: "Transfer Tokens between EOAs",
-          url: "ccip/tutorials/cross-chain-tokens-from-eoa",
+          title: "Offchain",
+          url: "ccip/tutorials/offchain",
+          children: [
+            {
+              title: "Transfer Tokens between EOAs",
+              url: "ccip/tutorials/cross-chain-tokens-from-eoa",
+            },
+            {
+              title: "Checking CCIP Message Status",
+              url: "ccip/tutorials/get-status-offchain",
+            },
+          ],
         },
         {
           title: "Transfer USDC with Data",

src/content/ccip/tutorials/cross-chain-tokens-from-eoa.mdx

@@ -2,23 +2,13 @@
 section: ccip
 date: Last Modified
 title: "Transfer Tokens between EOAs"
-whatsnext:
-  {
-    "Learn how to send arbitrary data over CCIP": "/ccip/tutorials/send-arbitrary-data",
-    "See example cross-chain dApps and tools": "/ccip/examples",
-    "See the list of supported networks": "/ccip/supported-networks",
-    "Learn CCIP best practices": "/ccip/best-practices",
-  }
+whatsnext: { "Checking CCIP Message Status Off-Chain": "/ccip/tutorials/get-status-offchain" }
 ---
 
 import { CodeSample, ClickToZoom, CopyText, Aside } from "@components"
 
 In this tutorial, you will use Chainlink CCIP to transfer tokens directly from your [EOA (Externally Owned Account)](https://ethereum.org/en/developers/docs/accounts/#types-of-account) to an account on a different blockchain. First, you will pay for CCIP fees on the source blockchain using LINK. Then, you will run the same example paying for CCIP fees in native gas, such as ETH on Ethereum or MATIC on Polygon.
 
-<Aside type="note" title="Node Operator Rewards">
-  CCIP rewards the oracle node and Risk Management node operators in LINK.
-</Aside>
-
 <Aside type="caution" title="Transferring tokens">
   This tutorial uses the term "transferring tokens" even though the tokens are not technically transferred. Instead,
   they are locked or burned on the source chain and then unlocked or minted on the destination chain. Read the [Token
@@ -48,11 +38,11 @@ In this tutorial, you will use Chainlink CCIP to transfer tokens directly from y
 
 1.  Learn how to [acquire CCIP test tokens](/ccip/test-tokens#mint-test-tokens). After following this guide, your [EOA (Externally Owned Account)](https://ethereum.org/en/developers/docs/accounts/#types-of-account) should have CCIP-BnM tokens, and CCIP-BnM should appear in the list of your tokens in MetaMask.
 
-1.  In a terminal, clone the [smart-contract-examples repository](https://github.com/smartcontractkit/smart-contract-examples) and change to the `smart-contract-examples/ccip-offchain/javascript` directory.
+1.  In a terminal, clone the [smart-contract-examples repository](https://github.com/smartcontractkit/smart-contract-examples) and change to the `smart-contract-examples/ccip/offchain/javascript` directory.
 
     ```shell
     git clone https://github.com/smartcontractkit/smart-contract-examples.git && \
-    cd smart-contract-examples/ccip-offchain/javascript
+    cd smart-contract-examples/ccip/offchain/javascript
     ```
 
 1.  Run `npm install` to install the dependencies.

src/content/ccip/tutorials/get-status-offchain.mdx

@@ -0,0 +1,87 @@
+---
+section: ccip
+date: Last Modified
+title: "Checking CCIP Message Status"
+---
+
+import { CodeSample, ClickToZoom, CopyText, Aside } from "@components"
+
+In this tutorial, you will learn how to verify the status of a Chainlink CCIP transaction offchain using JavaScript. Starting with a CCIP message ID, you'll execute the script to query the current status of a cross-chain message.
+
+## Before you begin
+
+1. Initiate a CCIP transaction and note the CCIP message ID. You can obtain the CCIP message ID by running any of the previous CCIP tutorials.
+1. Complete the prerequisites steps of the [Transfer Tokens between EOAs](/ccip/tutorials/cross-chain-tokens-from-eoa#before-you-begin) tutorial.
+
+## Tutorial
+
+This tutorial shows you on how to check the status of a Chainlink CCIP transaction using the [`get-status.js`](https://github.com/smartcontractkit/smart-contract-examples/blob/main/ccip/offchain/javascript/src/get-status.js) script. By supplying the script with the source, destination chains, and your CCIP message ID, you can verify the current status of your cross-chain message.
+
+**Execute the script in your command line:**
+
+```bash
+node src/get-status.js sourceChain destinationChain messageID
+```
+
+**The script requires the following parameters:**
+
+- `sourceChain` is the identifier for the source blockchain. For example, `ethereumSepolia`.
+- `destinationChain` is the identifier for the destination blockchain. For example, `polygonMumbai`.
+- `messageID` is the unique identifier for the CCIP transaction message that you need to check.
+
+**Example Usage:**
+
+If you initiated a transaction from the Ethereum Sepolia testnet to the Avalanche Fuji testnet and received a message ID, you can check the status of this message with the following command:
+
+```text
+$ node src/get-status.js ethereumSepolia polygonMumbai 0x4ea8080f2a51377247e93b5f45c00330b8c4fde3043e99847d0cab734f473df2
+
+Status of message 0x4ea8080f2a51377247e93b5f45c00330b8c4fde3043e99847d0cab734f473df2 on offRamp 0xAC1456bafcc3403eb6e34f08FD2945cd7B3C8F0A is SUCCESS
+```
+
+## Code Explanation
+
+The JavaScript `get-status.js` is designed to check the status of a user-provided CCIP message. The contract code includes several code comments to clarify each step, but this section explains the key elements.
+
+### Imports
+
+The script imports the required modules and data:
+
+- **Ethers.js**: [JavaScript library](https://docs.ethers.org/v6/) for interacting with the Ethereum Blockchain and its ecosystem.
+- **Router and OffRamp Contract ABIs**: These Application Binary Interfaces (ABIs) enable the script to interact with specific smart contracts on the blockchain.
+- **Configuration Functions**: Includes `getProviderRpcUrl` for retrieving the RPC URL of a blockchain, `getRouterConfig` for accessing the router smart contract's configuration, and `getMessageStatus` for translating numeric status codes into readable strings.
+
+#### Understanding the `getMessageStatus` function
+
+Before diving into the script execution, it's crucial to understand how the [`getMessageStatus`](https://github.com/smartcontractkit/smart-contract-examples/blob/main/ccip/offchain/javascript/src/config/offramp.js) function works. This function is designed to translate the numeric status codes returned by Solidity enums into human-readable statuses so they are clear to developers and users. The function uses a mapping defined in [`messageState.json`](https://github.com/smartcontractkit/smart-contract-examples/blob/main/ccip/offchain/config/messageState.json), which correlates to the [`MessageExecutionState`](https://github.com/smartcontractkit/ccip/blob/ccip-develop/contracts/src/v0.8/ccip/libraries/Internal.sol#L144) enum used by the [Chainlink CCIP's OffRamp](/ccip/architecture#offramp) contract.
+
+### Handling Arguments
+
+The `handleArguments` function ensures the script operates with the correct parameters. It validates the presence of three command-line arguments – the source chain identifier, the destination chain identifier, and the message ID.
+
+### Main Function: getStatus
+
+The script's core is encapsulated in the `getStatus` asynchronous function. This function completes initialization, configuration retrieval, and contract instantiation.
+
+#### Initialization
+
+Firstly, it establishes connections to the source and destination blockchain networks using the `JsonRpcProvider`.
+
+#### Configuration Retrieval
+
+The script then retrieves the configuration for router contracts on both the source and destination chains. This includes the router addresses and chain selectors.
+
+#### Contract Instantiation
+
+The script instantiates the source and destination router contracts using ethers and the router contract addresses.
+
+#### Status Query
+
+To query the status of the provided CCIP message ID, the script completes the following steps:
+
+1. Check if the source chain's router supports the destination chain
+2. Fetch OffRamp contracts associated with the destination router
+3. Filter these contracts to find those that match the source chain
+4. Query each matching OffRamp contract for an event related to the message ID
+
+If an event is found, the script reads the status from the arguments. It translates the numeric status into a human-readable status and logs this information.

src/content/ccip/tutorials/index.mdx

@@ -0,0 +1,21 @@
+---
+section: ccip
+date: Last Modified
+title: "CCIP tutorials"
+---
+
+You can explore several comprehensive guides to learn about cross-chain interoperability using CCIP. These tutorials provide step-by-step instructions to help you understand different patterns that you can incorporate into your blockchain projects.
+
+## Guides
+
+- [Transfer Tokens](/ccip/tutorials/cross-chain-tokens)
+- [Transfer Tokens with Data](/ccip/tutorials/programmable-token-transfers)
+- [Transfer Tokens with Data - Defensive Example](/ccip/tutorials/programmable-token-transfers-defensive)
+- [Offchain](/ccip/tutorials/offchain)
+  - [Transfer Tokens between EOAs](/ccip/tutorials/cross-chain-tokens-from-eoa)
+  - [Checking CCIP Message Status](/ccip/tutorials/get-status-offchain)
+- [Transfer USDC with Data](/ccip/tutorials/usdc)
+- [Send Arbitrary Data](/ccip/tutorials/send-arbitrary-data)
+- [Send Arbitrary Data with Acknowledgment of Receipt](/ccip/tutorials/send-arbitrary-data-receipt-acknowledgment)
+- [Manual Execution](/ccip/tutorials/manual-execution)
+- [Acquire Test Tokens](/ccip/test-tokens)

src/content/ccip/tutorials/offchain.mdx

@@ -0,0 +1,12 @@
+---
+section: ccip
+date: Last Modified
+title: "CCIP Offchain tutorials"
+---
+
+These tutorials focus on direct interaction between Externally Owned Accounts (EOAs) and the [CCIP Router](/ccip/architecture#router).
+
+## Tutorials
+
+- [Transfer Tokens between EOAs](/ccip/tutorials/cross-chain-tokens-from-eoa): Learn how to transfer tokens between Externally Owned Accounts (EOAs) across different blockchains, using Chainlink CCIP.
+- [Checking CCIP Message Status Off-Chain](/ccip/tutorials/get-status-offchain): Learn how to verify the status of Chainlink CCIP messages offchain using JavaScript.