1 of 13

Quick Start

The Quick Start guide will walk you through two core use cases of Hashi: verifying storage proofs or event proofs against a block header and pushing messages across chains. We’ll start with reading foreign state via storage proofs, followed by pushing a message to another chain. Both examples will help you understand the core functionality of Hashi and how to implement it in your projects.

The code can be found in Hashi template. This repository serves as a template for developers to kickstart a Hashi project using Hardhat/Foundry.

Verifying foreign event

In this example, you will verify the Transfer event of an ERC20 contract on Sepolia from Chiado using an event proof. The proof will be fetched via an API call and fed to a contract deployed on Chiado. The contract will use the HashiProver helper library to validate the proof against the last reported block header stored in Hashi.

Setting the scene

The first step is to understand what we’re trying to do:

You want to check if a specific Transfer event has been emitted from an ERC20 contract on Sepolia from Chiado.
We’ll do this by using HashiProver, which will verify the event from an ERC20 contract on Sepolia.
The proof will be verified using the latest block header that was relayed to Hashi from Sepolia to Chiado.

Here’s what we need to accomplish:

Fetch the event proof for Transfer event from Sepolia.
Deploy a contract on Chiado that will verify the event proof using HashiProver.
Submit the proof to this contract to validate the event on Sepolia.

Waiting for the state propagation

Before verifying the state, you need to fetch the event proof from Sepolia using the correct block number that has already been propagated to Hashi. This block number ensures that Hashi can verify the proof against the block header stored on Chiado.

Fetching the Proof

Use the following curl command to fetch the account and storage proof for the USDC total supply on Optimism:

curl --location --request POST 'https://jsonrpc.hashi-explorer.xyz/v1' \
--header 'Content-Type: application/json' \
--data-raw '{
  "id": 1,
  "jsonrpc": "2.0",
  "method": "hashi_getReceiptProof",
  "params": {
        "logIndex": 397,
        "blockNumber": 7016999,
        "chainId": 11155111,
        transactionHash: "0x25a6a5c138f3b5a434a3a2b5d6bf7bdf97cb700bd7515f801ecfb71f1d965e7b",
  }
}'

import axios from "axios";

const main = async () => {
  // fetch event proof from Hashi Prover
  console.log("Fetching event proof from Hashi prover...");
  const result = await axios.post(
    `http://jsonrpc.hashi-explorer.xyz:3000/v1`,
    {
      jsonrpc: "2.0",
      method: "hashi_getReceiptProof",
      params: {
        logIndex: 397,
        blockNumber: 7016999,
        chainId: 11155111,
        transactionHash: "0x25a6a5c138f3b5a434a3a2b5d6bf7bdf97cb700bd7515f801ecfb71f1d965e7b",
      },
      id: 1,
    },
    {
      headers: {
        "Content-Type": "application/json",
      },
    }
  );
  console.log("Event proof result", result.data.result.proof);
};

main();

chainId: 11155111 (Sepolia).
txHash: The tx hash that emitted the Transfer event on Sepolia: .
logIndex: The log index for the event.
blockNumber: The block number on Sepolia, 7016999, which must have already been propagated to Chiado via Hashi for the proof to be valid.

This curl command / script returns the event proof for the Transfer event on Sepolia, which will be used for verification on Chiado.

References

Receipt proof request script

Validating your statements

Once you’ve fetched the proof, you can now verify it using a contract on Chiado. The contract will use the HashiProver helper library to check the proof against the block header stored on Chiado.

Deploying the Verification Contract on Chiado

Here is the contract that you will deploy on Chiado to read and verify the Transfer event on Sepolia:

// SPDX-License-Identifier: MIT
pragma solidity ^0.8.0;

import { HashiProver } from "./HashiProver.sol";

contract MockERC20Prover {

    event TransferEventVerified(uint256 indexed chainID, bytes rlpEncodedEvent);

    HashiProver public hashiProver;
    address public erc20Contract;
    uint256 public chainID;

    constructor(address hashiProver_, address erc20Contract_, uint256 chainID_) {
        hashiProver = HashiProver(hashiProver_);
        erc20Contract = erc20Contract_;
        chainID = chainID_;
    }

    function verifyTransferEvent(HashiProver.ReceiptProof calldata proof, bytes memory expectedRlpEncodedEvent) external {
        require(proof.chainId == chainID, "Invalid chain id"); 

        bytes memory rlpEncodedEvent = hashiProver.verifyForeignEvent(proof);

        require(keccak256(rlpEncodedEvent) == keccak256(expectedRlpEncodedEvent), "invalid event");
        emit TransferEventVerified(proof.chainId , rlpEncodedEvent);

        // TODO: Define your logic here

    }
}

Deployment:

For quick start, we've deployed HashiProver & ShoyuBashi on a list of networks that you can call from your Prover contract (check #shoyubashi-and-hashi-prover). If you wish to configure your own oracle sets for your Hashi Prover, simply deploy a new ShoyuBashi contract, inherit Hashi Prover contract and configure your oracle sets in the ShoyuBashi contract.
In this example, pass the Hashi Prover contract on Chiado, ERC20Contract address on Sepolia that the Transfer event is emitted from, and chain ID of the ERC20Contract (Sepolia: 11155111)

Explanation:

This contract uses HashiProver to verify the event proof fetched earlier from Sepolia.
It checks that the proof is from Sepolia (chain ID 11155111), and rlpEncodedEvent returns from HashiProver.verifyForeignEvent matches the expectedRlpEncodedEvent that we passed as the function argument. To create the expectedRlpEncodedEvent, check out the helper script from Hashi-template.
The verifyForeignEvent function validates the event proof against the block header stored on Chiado, which was relayed from Sepolia.
If the proof is valid, the contract emits the TransferEventVerified event. You may defie your own logic after the proof has been verified.

References

Reading foreign state

In this example, you will verify the total supply of USDC on Optimism from Gnosis Chain using a storage proof. The proof will be fetched via an API call and fed to a contract deployed on Gnosis Chain. The contract will use the HashiProver helper library to validate the proof against the last reported block header stored in Hashi.

Setting the scene

The first step is to understand what we’re trying to do:

You want to check the total supply of USDC on Optimism from Gnosis Chain.
We’ll do this by using HashiProver, which will verify the state of a specific storage slot (holding the USDC total supply) on Optimism.
The proof will be verified using the latest block header that was relayed to Hashi from Optimism to Gnosis Chain.

Here’s what we need to accomplish:

Fetch the storage proof for the USDC total supply from Optimism.
Deploy a contract on Gnosis Chain that will verify the storage proof using HashiProver.
Submit the proof to this contract to validate the total supply on Optimism.

Waiting for the state propagation

Before verifying the state, you need to fetch the storage proof from Optimism using the correct block number that has already been propagated to Hashi. This block number ensures that Hashi can verify the proof against the block header stored on Gnosis Chain.

Fetching the Proof

Use the following curl command or javascript script to fetch the account and storage proof for the USDC total supply on Optimism:

chainId: 10 (Optimism).
address: The address of the USDC contract on Optimism: 0x0b2c639c533813f4aa9d7837caf62653d097ff85.
storageKeys: The storage key for the USDC total supply: 0xb.
blockNumber: The block number on Optimism, 126086800, which must have already been propagated to Gnosis Chain via Hashi for the proof to be valid.

This curl command returns the account and storage proof for the USDC total supply, which will be used for verification on Gnosis Chain.

Validating your statements

Once you’ve fetched the proof, you can now verify it using a contract on Gnosis Chain. The contract will use the HashiProver helper library to check the proof against the block header stored on Gnosis Chain.

Deploying the Verification Contract on Gnosis Chain

Here is the contract that you will deploy on Gnosis Chain to read and verify the USDC total supply on Optimism:

// SPDX-License-Identifier: MIT
pragma solidity ^0.8.20;

import { HashiProver } from "https://github.com/gnosis/hashi/blob/feat/hashi-prover/packages/evm/contracts/prover/HashiProver.sol";

contract UsdcTotalSupplyReader is HashiProver {
    event UsdcTotalSupply(uint256 totalSupply);

    constructor(address shoyuBashi) HashiProver(shoyuBashi) {}

    function readTotalSupply(HashiProver.AccountAndStorageProof calldata proof) external {
        require(proof.chainId == 10, "Invalid chain id"); // Optimism
        require(proof.account == 0x0b2C639c533813f4Aa9D7837CAf62653d097Ff85, "Invalid account");
        require(proof.storageKeys.length == 1 && proof.storageKeys[0] == bytes32(uint256(0xb)), "Invalid storage key");

        // Verify the proof against the latest block header stored in Hashi
        uint256 totalSupply = uint256(bytes32(verifyForeignStorage(proof)[0]));
        emit UsdcTotalSupply(totalSupply);
    }
}

Explanation:

This contract uses HashiProver to verify the storage proof fetched earlier from Optimism.
It checks that the proof is from Optimism (chain ID 10), and that the USDC contract address and storage key match the expected values.
The verifyForeignStorage function validates the proof against the block header stored on Gnosis Chain, which was relayed from Optimism.
If the proof is valid, the contract emits the total supply of USDC on Optimism.

Submitting the Proof

Once the contract is deployed on Gnosis Chain, you can submit the proof fetched from the API using the following command:

// Example of submitting the proof in Solidity (or via web3 call)
HashiProver.AccountAndStorageProof memory proof = { /* fetched proof from curl command */ };
usdcTotalSupplyReader.readTotalSupply(proof);

This will trigger the contract to verify the proof using the block header stored in Hashi from Optimism. If the proof is valid, the total supply of USDC will be emitted.

Pushing a message

In this example, we’ll send a message from a contract on Sepolia to another contract on Chiado, using Hashi to relay and execute the message. The callback will be triggered and validated on Chiado using the provided onMessage function.

Writing your message sending contract

Here’s how you write a contract on Sepolia that dispatches a message using Hashi’s Yaho contract. This message will be relayed to Chiado and trigger the callback.

Explanation:

The contract interacts with the Yaho contract on Sepolia to dispatch a message to Chiado using dispatchMessageToAdapters.
The sendMessageToChiado function takes the target chain ID(10200 for Chiado), target address (ChiadoReceiver contract on Chiado), and the message to be sent.
The reporters, adapters, and threshold are passed into the Yaho contract for cross-chain message validation and relaying.

Deployment:

Deploy this contract on Sepolia, passing the reporters, adapters, and threshold into the constructor.
Threshold must equal to expectedThreshold in Receiver contract.

Implementing your callback

Now, we’ll write the callback function on Chiado using the onMessage implementation you provided. This contract will handle the message sent from Sepolia.

Explanation:

The onMessage function implements the callback, which is triggered when the Yaru contract on Chiado relays the message.
The function checks that the Yaru contract on Chiado is the sender, that the chainId, sender address, and threshold match what was expected, and that the list of adapters matches the expected hash.
After the validations pass, the message is decoded and stored in the contract.

Deployment:

Deploy this contract on Chiado. Ensure that the values like SOURCE_SENDER_ADDRESS (Sepolia sender contract), EXPECTED_THRESHOLD, and ADAPTERS are correctly configured.

Waiting for the cross-chain execution

Here’s what happens after you send the message:

Message Dispatch on Sepolia:
- When sendMessageToChiado is called on the SepoliaSender contract, the message is dispatched through Yaho on Sepolia.
- The message is sent with the targetChainId, threshold, reporters, and adapters, and the data (in this case, the message string).
Oracles and Relaying:
- Hashi’s oracles pick up the message and relay it to Chiado.
- The oracles validate the message and check the block headers for consensus.
Message Receipt and Callback on Chiado:
- On Chiado, the Yaru contract receives the message and triggers the onMessage function on the ChiadoReceiver contract.
- The callback validates the message by ensuring that the message is from the expected Yaru contract, the source chain, and the correct sender.
- After validation, the message is decoded and stored in the contract.

Example Scenario

You deploy SepoliaSender on Sepolia and configure it with the appropriate Yaho contract and oracle parameters.
You deploy ChiadoReceiver on Chiado to handle the incoming message and validate it against Hashi’s oracle system.
When you call sendMessageToChiado from SepoliaSender, the message is dispatched to Chiado, where the callback function processes it and updates the state.

// SPDX-License-Identifier: MIT pragma solidity ^0.8.0; contract ChiadoReceiver { /// @dev Yaru contract on the Chiado w.r.t the Sepolia address public YARU = 0xBA9165973963a6E5608f03b9648c34A737E48f68; /// @dev Source chain ID of Sepolia uint256 public SOURCE_CHAIN_ID = 11155111; /// @dev Expected threshold to be met by the adapters uint256 public EXPECTED_THRESHOLD; /// @dev Sender SepoliaSender contract address address public SOURCE_SENDER_ADDRESS; /// @dev hash of adapters address bytes32 public ADAPTERS_HASH; /// @dev message that is last received from sender contract's sendMessageToTarget function string public lastReceivedMessage; constructor(uint256 expectedThreshold, address sourceSender, address[] memory adapters){ EXPECTED_THRESHOLD = expectedThreshold; SOURCE_SENDER_ADDRESS = sourceSender; ADAPTERS_HASH = keccak256(abi.encodePacked(adapters)); } /// @dev Function that gets triggered when the message is relayed, called by Yaru contract /// @param chainId chainId of the chain where message is sending from /// @param sender sender contract /// @param threshold threshold of the message that should be met by adapters /// @param adapters an array of adapters to check the threshold with /// @param data abi-encoded message /// @return function onMessage( uint256, /*messageId*/ uint256 chainId, address sender, uint256 threshold, address[] memory adapters, bytes memory data ) external returns (bytes memory) { require(msg.sender == YARU, "only called by Yaru"); require(chainId == SOURCE_CHAIN_ID, "invalid source chain ID"); require(threshold == EXPECTED_THRESHOLD, "invalid number of threshold"); require(sender == SOURCE_SENDER_ADDRESS, "invalid sender address from source chain"); require( keccak256(abi.encodePacked(adapters)) == ADAPTERS_HASH, "invalid adapters hash"); // Decode the message and store it (string memory message) = abi.decode(data, (string)); lastReceivedMessage = message; return ""; } }