Welcome to the official documentation for Hashi, your comprehensive guide to understanding and integrating the Hashi oracle aggregator into your cross-chain applications. Whether you're new to cross-chain security or an experienced developer looking to enhance the security of your blockchain projects, this guide will provide you with all the necessary tools and insights.

Hashi is designed to increase the security of cross-chain interactions by utilizing multiple oracles to verify and validate block headers and messages between chains. By ensuring that cross-chain messages are validated by multiple independent oracles, Hashi mitigates risks associated with single points of failure and enhances the overall security of decentralized ecosystems.

Jump right in

Hashi is a robust and innovative EVM hash oracle aggregator designed to significantly enhance the security of cross-chain applications. It leverages multiple independent oracles to validate and verify block headers and messages across different blockchain networks, ensuring a more secure and reliable way to facilitate interactions between chains.

In a landscape where cross-chain bridges are prone to risks due to reliance on single points of failure, Hashi introduces an additive security model, where multiple oracles work together to ensure the integrity and authenticity of data relayed across chains. This approach minimizes vulnerabilities and strengthens the overall security of decentralized applications (dApps) that rely on cross-chain communication.

Key Features of Hashi

• Multi-Oracle Validation: Hashi aggregates the results from multiple oracles to validate block headers and messages, reducing the likelihood of failure due to malicious actors or faulty data.

• Cross-Chain Compatibility: It supports multiple blockchain networks, including Ethereum, Gnosis Chain, and others, making it adaptable to a wide range of dApps and cross-chain use cases.

• Arbitrary Message Relaying: Hashi allows for secure and scalable message relaying between chains, ensuring that cross-chain interactions are not only secure but also efficient.

• Additive Security: The more oracles that participate in Hashi, the stronger the security, creating an increasing level of protection as the network grows.

• RIP-7755 Compatibility: Hashi fosters standardization in the Cross-Chain interoperability landscape.

In essence, Hashi provides an advanced layer of security and reliability for any project that relies on cross-chain data, offering developers peace of mind and more control over the security of their decentralized applications.

As decentralized applications (dApps) increasingly interact with multiple blockchains, ensuring the security of cross-chain communication is more important than ever. Traditional solutions often face security challenges due to reliance on a single oracle or validator, introducing vulnerabilities and risks. Hashi addresses these challenges with its unique approach, which focuses on leveraging multiple oracles and secure block relaying to guarantee reliable cross-chain interactions.

Secure Block Relaying

One of Hashi's core functions is its block relaying mechanism, which allows it to securely transmit block headers from one chain to another. This process ensures that dApps working across chains can verify the validity of blockchain states with confidence. Instead of relying on individual messages, Hashi enables the transfer of block headers, ensuring data integrity through cryptographic verification.

Multi-Oracle Validation

Hashi further enhances security by requiring multiple independent oracles to validate and agree on the authenticity of block headers. This multi-oracle model significantly reduces the risks of depending on a single entity and increases the robustness of cross-chain transactions.

Avoiding Vendor Lock-In

Hashi serves as an abstraction layer between your dApp and the underlying oracles or relayers, meaning you’re not tied to any one provider. This flexibility allows developers to integrate multiple oracles from various vendors without the fear of vendor lock-in. Hashi abstracts the complexity, enabling seamless switching between oracles while maintaining the security of your cross-chain interactions. This way, you're always in control, and as new oracles emerge, you can easily adopt them without restructuring your dApp.

Reducing Single Points of Failure

In contrast to traditional cross-chain solutions that often rely on a single validator, Hashi distributes trust across multiple oracles. This significantly mitigates the risk of a single point of failure, ensuring that the security of your cross-chain transactions doesn’t hinge on one entity.

Scalable Security

Hashi’s additive security model allows you to scale the level of security according to your needs. By involving more oracles in the validation process, you can dynamically increase the security for high-value transactions or sensitive data, making Hashi adaptable for both simple and complex cross-chain applications.

Who Should Use Hashi?

• Cross-Chain Application Developers: Hashi provides a reliable, secure solution for developers building dApps that interact across multiple blockchains.

• Interoperability-Focused Projects: For teams needing cross-chain verification, Hashi’s abstraction layer and multi-oracle setup ensure flexibility and security.

• Bridge Operators: Hashi allows for robust security through its multi-oracle architecture, offering a solution that reduces the risks associated with traditional cross-chain bridges.

Hashi is built to provide flexibility, scalability, and security. Its multi-oracle, block-relaying architecture ensures that your cross-chain interactions are safe, reliable, and free from vendor lock-ins, giving you the freedom to innovate and adapt as the blockchain ecosystem evolves.

Hashi introduces a range of features designed to enhance the security and flexibility of cross-chain applications. Here’s a brief overview of what sets Hashi apart:

1. Multi-Oracle Validation

Hashi aggregates data from multiple independent oracles to validate block headers and messages. This reduces reliance on a single oracle and increases the security of cross-chain interactions.

2. Secure Block Relaying

Hashi relays entire block headers between chains, providing cryptographic proof of blockchain states across multiple networks. This ensures that data being relayed is both secure and verifiable.

3. Abstraction Layer for Oracles

Hashi acts as an abstraction layer, allowing you to easily switch between different oracles without being locked into a single provider. This flexibility helps avoid vendor lock-in and future-proofs your application.

4. Additive Security Model

With Hashi, security scales as more oracles are added to the validation process. This makes Hashi adaptable to a variety of applications, from low-risk operations to high-value transactions that require additional layers of security.

5. Cross-Chain Compatibility

Hashi supports a wide range of blockchains and oracle systems, making it a versatile solution for developers building cross-chain applications.

Hashi is a decentralized protocol that allows secure cross-chain communication. By enabling contracts on one blockchain to interact with contracts on another, Hashi facilitates cross-chain data transfer and execution through message dispatching, storage proofs, and cryptographic verification.

The process involves sending a message or verifying a state across blockchains, such as Sepolia and Gnosis Chiado, using a series of contracts and oracles. Let’s break down how this works in practice:

Verifying State with Cross-Chain Proofs

A powerful feature of Hashi is the ability to verify the state of a contract on one chain using cryptographic proofs stored on a different chain. Here’s how this works using Sepolia and Chiado as origin and target chains:

1. Storing Block Headers:

   • The first step is to relay block headers from Sepolia to Chiado.

   • These headers are stored in the Header Storage contract on Chiado and contain essential information like the state root, which can be used to validate the state of a Sepolia smart contract.

2. Requesting a Proof:

   • Verify the value stored in a specific storage slot of a contract on Sepolia (Chain A).

   • Generate a Merkle proof that shows the value of this storage slot on a particular block on Sepolia. This proof includes information from the block header (stored on Chiado) and the Merkle path leading to the value.

3. Submitting the Proof:

   • You submit this proof to the Yaru contract on Chiado. The Yaru contract checks the proof against the block header that was previously relayed and stored in the Header Storage contract.

   • If the proof is valid, Hashi confirms that the state on Sepolia matches what was proven in the Merkle proof.

In this way, you can verify contract state on Sepolia directly from Chiado, without interacting with Sepolia in real-time, using trustless proofs and stored block headers.

Message Dispatching Across Chains

1. Start on Chain A (Sepolia):

   • Imagine you have a contract on Sepolia that needs to send a message to a contract on Gnosis Chiado (Chain B).

   • On Sepolia, you use Hashi’s Yaho contract, which is specifically designed for dispatching messages across chains.

2. Sending the Message:

   • Your Sepolia contract calls the Yaho contract, instructing it to send a message to the Yaho contract on Chiado.

   • The message typically contains the target contract address on Chiado and the data you want to send (such as a function call or value).

3. Relaying the Message:

   • Once the message is dispatched, it is picked up by Hashi’s oracle network. These oracles listen for events on Sepolia, relay the message, and submit it to Yaho on Chiado for execution.

   • Multiple oracles are used for redundancy and security, ensuring that the message is properly validated before it’s passed to Chiado.

4. Receiving and Executing the Message on Chain B (Chiado):

   • On Chiado, the Yaho contract receives the message after the oracles validate the block header and the message’s integrity.

   • Once validated, the Yaho contract triggers the appropriate callback function on the target contract (for example, updating the contract state or calling a specific function).

In practice, this allows you to seamlessly send a message from Sepolia to Chiado, have it validated by multiple oracles, and executed on the destination chain.

What we have:

• A ERC20 Transfer Event emitted in Sepolia USDC contract.

What we need:

• The verification on Chiado chain of the actual Sepolia Transfer event.

How Hashi enables the Event verification:

• With HashiAPI: a offchain component used to retrieve the Event Proof for the specific Sepolia Event emitted.

• With HashiProver: a onchain contract provided by Hashi which can verify the block proof provided by HashiAPI. HashiProver must be deployed on the target chain (Chiado in this case) and can be used in a custom contract which can use the Event proof verification provided by HashiProver itself.

Steps followed in this example:

• Fetch the event proof for Transfer event from Sepolia.

• Deploy a custom contract on Chiado that will verify the event proof using HashiProver.

• Submitting the proof to the custom contract.

The blockchain ecosystem is rapidly evolving into a diverse environment with various types of virtual machines (VMs), rollup stacks, and modular networks. As more unique blockchain platforms emerge connecting these ecosystems to enable seamless asset transfers, liquidity provision, and state verification has become a significant challenge.

The Problem

Traditional cross-chain solutions like General Message Passing (GMP) struggle to support the vast and expanding landscape of chains. Most chains can only establish direct connections to their primary settlement layer, limiting interactions across unrelated networks. Furthermore, existing cross-chain solutions often rely on capital-intensive models that are inefficient and costly, particularly when attempting to verify the state of one chain on another.

How SSN Solves It

The Hashi State Sharing Network (SSN) introduces a scalable and efficient solution for cross-chain interoperability. SSN facilitates the regular relaying of state information across multiple chains, allowing for secure, low-cost, and trust-minimized cross-chain interactions. By implementing multi-hop routing pathways, SSN enables communication between any chains, even those that are not directly connected. This solution optimizes state verification and reduces gas costs by leveraging intermediary networks (e.g., Gnosis) as hubs for state updates, making it easier for developers to build interoperable applications across chains.

In short, SSN provides a unified layer for state sharing, driving forward a vision of a fully interconnected blockchain ecosystem where diverse networks can collaborate seamlessly and securely.

This example demonstrates the validation of a Transfer Event from an ERC-20 contract on the Sepolia network using an event proof on the Chiado network. The proof is retrieved via an API call and provided to a custom contract to be deployed on Chiado. The contract utilizes the HashiProver helper library to verify the proof against the latest block header recorded in Hashi.

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 go through the core use cases with three examples:

• verify a foreign event

• read a foreign state via storage proofs

• push a message to foreign chain.

This example demonstrates the verification of the total supply of USDC on Optimism from Gnosis Chain using a storage proof. The proof will be fetched via HashiAPI and fed to a contract deployed on Gnosis Chain. The contract will use HashiProver to validate the proof against the last Optimism reported block header stored in Hashi.

Once the proof has been fetched, we can verify it using a custom contract on Chiado. The contract will use the HashiProver helper library to check the proof against the block header stored on Chiado.

Deploying the Custom Verification Contract on Chiado

Here is a custom contract that deployed on Chiado can be used 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 shoyuBashi_, address erc20Contract_, uint256 chainID_) {
        hashiProver = HashiProver(shoyuBashi_);
        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 custom logic here

    }
}

Deployment:

• In this example, pass to the custom verification contract constructor <ShoyuBashi contract address on Chiado, the ERC20 contract address on Sepolia, from which the Transfer event is emitted, chain ID of the ERC20Contract (Sepolia: 11155111)>

verifyForeignEvent explanation:

Inputs:

• proof: the HashiAPI retreived proof

Logic:

• check that the proof chainID matches the origin chain chainId (Sepolia in this case).

• The verifyForeignEvent function validates the event proof against the block header stored on Chiado, which was relayed from Sepolia.

• check that rlpEncodedEvent returned from HashiProver.verifyForeignEvent matches the expectedRlpEncodedEvent that we passed as the function argument. This is useful to check that the Event infos encoded in the proof just verified actually match the Event we expect.

• If the proof is valid, the contract emits the TransferEventVerified event. You may define your own logic after the proof has been verified.

Submitting the Proof

Once the contract is deployed on Chiado, 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.ReceiptProof memory proof = { /* fetched proof from curl command */ };
MockERC20Prover.verifyTransferEvent(proof, expectedRlpEncodedEvent);

This will trigger the contract to verify the proof using the block header stored in Hashi from Sepolia. If the proof is valid, the rplEncodedEvent will be emitted.

References

Fetching the Proof

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).

• logIndex: The log index for the event.

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

References

First we need to fetch the storage proof from Optimism using the block number of a Optimism block which header that has already been propagated to Hashi. This block number ensures that Hashi can verify the proof against the just mentioned block header propagated to 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.

Use the SP1 storage proof generator

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.

Once the proof has been fetched, we can now verify it using a custom 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 custom Verification Contract on Gnosis Chain

Here is a contract that deployed on Gnosis Chain can be used 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);
    }
}

Deployment:

• In this example, pass to the custom verification contract constructor <ShoyuBashi contract address on Gnosis Chain>

readTotalSupply explanation:

Inputs:

• proof: the HashiAPI retreived storage proof.

Logic:

• check that the proof chainID matches the origin chain chainID (Optimism in this case).

• check that the USDC contract address.

• check that storage key match the expected value.

• This contract uses HashiProver to verify on Gnosis Chain the storage proof coming from Optimism fetched earlier.

• 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.

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.

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

interface IYaho {
    function dispatchMessageToAdapters(
        uint256 targetChainId,
        uint256 threshold,
        address targetAddress,
        bytes memory data,
        address[] memory reporters,
        address[] memory adapters
    ) external;
}

contract SepoliaSender {
    IYaho public yaho = IYaho(0x21eAB033C7D2DF6A67AeF6C5Bda9A7F151eB9f52);  // Yaho address on Sepolia
    uint256 public threshold;
    address[] public reporters;
    address[] public adapters;

    constructor(address _yaho, uint256 _threshold, address[] memory _reporters, address[] memory _adapters) {
        threshold = _threshold;
        reporters = _reporters;
        adapters = _adapters;
    }

    // Function to send a cross-chain message to Chiado
    function sendMessageToChiado(
        uint256 targetChainId, 
        address targetAddress, 
        string memory _message
    ) public {
        bytes memory data = abi.encode(_message);
        yaho.dispatchMessageToAdapters(targetChainId, threshold, targetAddress, data, reporters, adapters);
    }
}

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.

• A list of reporters and adapters contract can be found in: Oracles

• Threshold must equal to expectedThreshold in Receiver contract.

Here’s what happens after you send the message:

1. 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).

2. 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.

3. 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.

Beyond block headers, Hashi supports secure message dispatching between blockchains. This allows dApps to send messages across chains while ensuring that the messages are verified and valid according to the state of the originating blockchain.

• How it Works Messages are dispatched after the validation of block headers, ensuring that any message relayed between two blockchains is consistent with the blockchain state. Hashi uses its multi-oracle validation system to verify these messages, making sure that only messages based on valid block headers are dispatched.

• Use Cases Message dispatching can be used in cross-chain token transfers, governance voting, or any application where information needs to be relayed from one blockchain to another securely and reliably.

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

// 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 "";
    }
}

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.

• A list of adapters on the target chain can be found in Oracles

Oracles play a pivotal role in Hashi’s ecosystem. They are responsible for relaying block headers and messages between blockchains and validating them in a decentralized manner. Hashi uses multiple oracles to ensure security and avoid relying on a single point of failure.

• Why Multiple Oracles? Trusting a single oracle can introduce vulnerabilities, especially in cross-chain environments where security is critical. Hashi solves this by using multiple oracles, each independently verifying the data. Only when consensus is reached among a majority of these oracles is the data accepted, significantly reducing the risk of manipulation or failure.

• Oracle Adapters Hashi uses a universal adapter interface, making it easy to add support for new oracles as they emerge. This flexibility allows Hashi to evolve with the ecosystem, accommodating new oracle solutions as needed.

Block headers are at the heart of Hashi’s security model. Rather than just relying on arbitrary messages between chains, Hashi works by relaying entire block headers from one blockchain to another. This means that dApps can verify not only the content of a message but the actual state of the originating chain.

• Why Block Headers? Block headers contain essential information about the state of a blockchain, including the hash of the previous block, timestamp, and the Merkle root of all transactions. By relaying these, Hashi ensures that cross-chain interactions are based on cryptographic proofs tied to actual blockchain states, making them much more secure than simple message relays.

• How Hashi Uses Block Headers Multiple independent oracles relay these block headers, which are then aggregated and validated by Hashi. The result is a robust verification process where only confirmed, valid block headers are accepted, ensuring data integrity across chains.

Hashi’s security model is based on additive security, where the more oracles involved, the greater the level of protection. This allows developers to dynamically scale the security of their cross-chain interactions by increasing the number of oracles participating in validation.

• How Additive Security Works Rather than relying on a single source of truth, Hashi collects validation results from multiple oracles. As more oracles participate in validating block headers and messages, the security of the system increases. This model ensures that even if one or several oracles are compromised, the overall integrity of the system is maintained.

• Dynamic Security Developers can adjust the security threshold based on their specific needs. For routine transactions, fewer oracles may be sufficient, but for high-stakes interactions, the number of validating oracles can be increased to ensure maximum security.

Hashi integrates multiple oracles to relay block headers and messages securely across different blockchains. Each oracle operates with its own set of contracts and mechanisms depending on the source and destination chains. Below are the deployment details for each oracle, including testnets when available.

GMP Oracles

A GMP Oracle (General Message Passing Oracle) facilitates message transmission across different blockchain networks by acting as a trusted entity to validate, relay, and process cross-chain messages, ensuring that data or instructions are accurately transferred between chains.

LayerZero

Reporter

Adapter

Hyperbridge

Reporter

Adapter

AMB (Arbitrary Message Bridge)

Gnosis Chain's Arbitrary Message Bridge (AMB) is the chain's legacy canonical bridge. It enables cross-chain communication between Gnosis Chain and Ethereum (and other EVM networks). It allows contracts to send data and trigger actions on another chain through a set of decentralized validators.

Wormhole

CCIP (Chainlink Cross-Chain Interoperability Protocol)

ZK Light Clients

A ZK Light Client is a lightweight blockchain client that uses zero-knowledge proofs (ZKPs) to securely verify and relay blockchain state data between networks.

Light client-based oracles don't need for a reporter contract on the source chain to dispatch messages or block headers. Instead, they only require an adapter on the destination chain. Off-chain systems generate cryptographic proofs, which are submitted to the adapter contract for on-chain verification. Once validated, the resulting hash is securely stored on the destination chain.

DendrETH

Spectre

*Spectre listens MessageDispatched event from Source Chain's Yaho and verify on Spectre Adapter on Destination Chain.

SP1-Helios

SP1 Verifier

Hashi relies on a set of core smart contracts to enable secure cross-chain communication, storage verification, and message dispatching. These contracts form the backbone of Hashi's decentralized system, ensuring that data and messages relayed across different blockchains are validated, secure, and cryptographically sound.

In this section, we’ll introduce the key contracts that you will interact with when using Hashi, detailing their primary functions and how they work together to facilitate cross-chain operations.

1. Yaho (Message Dispatch Contract)

The Yaho contract is responsible for dispatching messages from one blockchain to another. It manages the sending of cross-chain messages by interacting with Hashi’s oracle system, ensuring that messages are transmitted and validated before they are delivered to the destination chain.

• Primary Function: Dispatches messages across chains.

• Usage: Interacts with oracles to relay messages from the source chain (e.g., Sepolia) to the destination chain (e.g., Gnosis Chain).

• Key Methods:

  • dispatchMessageToAdapters(uint256 targetChainId, uint256 threshold, address targetAddress, bytes memory data, address[] memory reporters, address[] memory adapters)

    • Dispatches a message with specified reporters and adapters to the target chain.

2. Yaru (Message Validation Contract)

The Yaru contract handles the receiving and validation of cross-chain messages. It works on the destination chain to ensure that messages sent by the Yaho contract are legitimate and validated by Hashi’s oracles before triggering any actions.

• Primary Function: Validates cross-chain messages and triggers callbacks on the destination chain.

• Usage: Used on the receiving side to validate messages dispatched by Yaho.

• Key Methods:

  • onMessage(uint256 messageId, uint256 chainId, address sender, uint256 threshold, address[] memory adapters, bytes memory data)

    • Validates a message and triggers the corresponding action on the destination contract.

3. Header Storage

The Header Storage contract stores block headers from a source chain, which are then used to verify storage proofs or validate the state on the destination chain. Block headers are essential to cross-chain validation, as they contain the cryptographic data needed to prove the state of a contract on another chain.

• Primary Function: Stores block headers for cross-chain state verification.

• Usage: Relays block headers from the source chain (e.g., Optimism) to the destination chain (e.g., Gnosis Chain).

• Key Methods:

  • storeBlockHeader(bytes memory headerData)

    • Stores a new block header from the source chain.

4. HashiProver

HashiProver is a helper contract used to verify cross-chain storage proofs and account states. It works by comparing the storage proofs provided with the block headers stored in the Header Storage contract.

• Primary Function: Verifies storage proofs and account states across chains.

• Usage: Used when you need to verify a foreign contract’s state (e.g., checking the USDC total supply on Optimism from Gnosis Chain).

• Key Methods:

  • verifyForeignStorage(AccountAndStorageProof calldata proof)

    • Verifies a storage proof against the latest block header stored in the Header Storage contract.

5. ShoyuBashi (Oracle Manager Contract)

ShoyuBashi manages the oracles that relay messages and block headers between chains. This contract is responsible for coordinating the oracle system and ensuring that multiple oracles reach consensus before a message or block header is considered valid.

• Primary Function: Manages oracles and relays messages or block headers.

• Usage: Ensures secure and validated message passing between chains by coordinating oracle responses.

• Key Methods:

  • relayBlockHeader(uint256 chainId, bytes memory headerData)

    • Relays block headers between chains using oracles.

  • dispatchMessage(uint256 chainId, address targetAddress, bytes memory data)

    • Dispatches messages through oracles for cross-chain validation.

Understanding Their Roles

Each of these contracts plays a crucial role in Hashi’s cross-chain framework:

• Yaho dispatches messages, while Yaru validates them.

• Header Storage stores block headers, which are used by HashiProver to verify state proofs.

• ShoyuBashi coordinates oracles to securely relay data between chains.

These contracts work in harmony to ensure that messages and state changes across blockchains are cryptographically secure and validated by multiple independent oracles, ensuring a trustless cross-chain environment.

The following are the main Hashi contracts deployed on supported blockchains, including Yaho, and Yaru for secure message dispatch and block header aggregation. Testnets are also included where applicable.

Yaho & Yaru

Hashi & Header Storage

Hashi contract serves as an entry point for other contracts to check the hashes and threshold from the adapter contracts. Header Storage stores the block header with respect to a block number.

*Arbitrum uses ArbHeaderStorage.sol instead of HeaderStorage.sol

ShoyuBashi & Hashi Prover

ShoyuBashi lets developers configure their own set of oracles to verify a hash. The Hashi Prover contract verifies storage and event proofs from the source chain on the target chain.

Please note that the following deployed contracts are designed to help you quickly get started with Hashi's state verification logic as the adapters are configured in ShoyuBashi contract and developer can simply call Hashi Prover's verify functions to verify the proof.

Solana (experimental)

The HashiProver API enables developers to easily interact with Hashi's cross-chain storage and state verification functionalities programmatically.

Below is the list of available API calls, with detailed descriptions of their parameters, request methods, and expected responses.

Usage

where:

• <rpc_url>: The RPC URL of your node.

• <reference_block_number>(optional): The block number in hexadecimal format.

• <proof_block_number>: The block number for the proof, specified in hexadecimal format (e.g., 0xAABBCC). If <proof_block_number> is set to a value less than <reference_block_number>, the program will validate the entire chain of blocks from <reference_block_number> down to <proof_block_number>.

• <account>: The account address to verify.

• <storage_key>: The storage key you wish to verify.

What we have:

------

What we need:

• The verification on Gnosis Chain chain of USDC total supply on Optimism.

How Hashi enables the Event verification:

• With HashiAPI: a offchain component used to retrieve the Storage Proof of a specific storage slot (the one holding the USDC total supply).

• With HashiProver: a onchain contract provided by Hashi which can verify the block proof provided by HashiAPI. HashiProver must be deployed on the target chain (Gnosis Chain in this case) and can be used in a custom contract which can use the Event proof verification provided by HashiProver itself.

Steps followed in this example:

• Fetch the storage proof for the USDC total supply on Optimism.

• Deploy a custom contract on Gnosis Chain that will verify the event proof using HashiProver.

• Submitting the proof to the custom contract.

Overview

Hashi’s core functionality is to propagate block headers across multiple chains, enabling cross-chain state verification. On EVM-based chains, this can be done in a trustless manner because the EVM exposes the last 256 block headers. However, this approach is not feasible on Solana, as the Solana VM only provides slot hashes, which do not include commitments that would allow verification of account states (as opposed to the state_root on Ethereum).

How to read a Solana account from an EVM chain

Once the accounts_root is successfully stored in the corresponding adapter(s) on Base, you can read the account data by calling HashiProver.verifyForeignSolanaAccount from any contract.

Hashi offers a range of resources to help developers get started and integrate Hashi into their cross-chain applications.

Overview

Key Features:

• Cross-Chain Voting: Cast your vote from any chain with seamless authentication across multiple bridges.

• Additive Security: The Hashi plugin uses a multi-oracle validation model, which helps ensure a trust-minimized voting process.

• Compatibility Beyond EVM: The Hashi plugin supports a broader range of blockchain ecosystems, expanding governance capabilities to non-EVM chains.

Hashi is committed to ensuring the security and reliability of its protocol. To this end, it regularly undergoes comprehensive third-party security audits. Below are the completed audit reports, which assess the key security components of Hashi.

g0 Audits (March 2024 & June 2024)

The g0 audits evaluated the security of Hashi’s core components, including oracle integration, block header aggregation, and cross-chain message dispatching.

Omega Audit (June 2024)

The Omega audit focused on Hashi’s integration with the Gnosis Bridge, assessing the interaction between Hashi’s oracle system and the cross-chain relaying mechanism.

Least Authority Audit (June 2024)

The Least Authority audit examined Hashi’s multi-oracle validation system and overall security architecture, ensuring its resilience against potential security threats.

Safe Crosschain is a mechanism crafted to empower users with the ability to control a Safe across different blockchains using Hashi. The idea is to have a main Safe that controls secondary Safes deployed abroad using storage proofs verification against a block header propagated using Hashi.

Overview

How the Integration Works

When Openfort's primary proof provider (Polymer) is unavailable, Hashi steps in to ensure liquidity providers (LPs) can still generate valid proofs for their fronted funds. This is achieved by using a local Hashi RPC API that wraps Ethereum methods like eth_getProof for storage proofs or eth_getTransactionReceipt for event proofs. The proof generated by Hashi is then submitted through the fallbackRepay function of Openfort's InvoiceManager smart contract, enabling refunds solely with public on-chain data and avoiding reliance on third parties.

Key Steps:

1. Proof Generation: LPs run a Hashi RPC API locally to generate proofs.

2. Proof Submission: The generated proof is submitted via the fallbackRepay function.

3. Repayment Processing: Openfort's InvoiceManager contract handles the repayment using only on-chain data, ensuring a trustless and permissionless fallback strategy.