Using Storage Proof API

This guide will walk you through the process of submitting a Storage Proof API Batch query to prove the Ethereum balance of a specific account using Herodotus.

Step 1: Prepare the API Request

First, we'll construct the API request to submit a batch query. We'll use the /submit-batch-query endpoint for this purpose.

Request Details:

• Method: POST

• URL: https://api.herodotus.cloud/submit-batch-query

• Headers:

  • Content-Type: application/json

Request Body:

{
  "destinationChainId": "11155111",
  "fee": "0",
  "data": {
    "11155111": {
      "block:5150551": {
        "accounts": {
          "0x17C2D875CB397D813eAE817DaFD25807E348Df07": {
            "props": ["BALANCE"],
            "slots": []
          }
        }
      }
    }
  }
}

Let's break down the request body:

• destinationChainId: "11155111" represents the Ethereum Sepolia testnet, which is both the source and destination chain for this query.

• fee: Set to "0" as this is a testnet query.

• data: This object specifies what we want to prove:

  • 11155111: Indicates we're querying the Ethereum Sepolia testnet (chain ID 11155111).

  • block:5150551: We're looking at a specific block number (5150551).

  • accounts: Specifies which accounts we're interested in.

  • 0x17C2D875CB397D813eAE817DaFD25807E348Df07: The account address we want to prove the balance for.

  • props: We're requesting the "BALANCE" property.

  • slots: An empty array as we're not querying any specific storage slots.

Step 2: Send the API Request

Use your preferred method (curl, Postman, or a programming language of your choice) to send this POST request to the Herodotus API.

Don't forget to include your API key as a query parameter:

https://api.herodotus.cloud/submit-batch-query?apiKey=YOUR_API_KEY_HERE

Step 3: Handle the API Response

If successful, you'll receive a response with an internalId. This ID is crucial for checking the status of your query later.

Example response:

{
  "internalId": "01J2V235ABJY55JS2MY051ZJFJ"
}

Step 4: Check Query Status

API Method

You can check the status of your query using the /batch-query-status endpoint:

GET https://api.herodotus.cloud/batch-query-status?apiKey=YOUR_API_KEY_HERE&batchQueryId=01J2V235ABJY55JS2MY051ZJFJ

The response will indicate whether the query is "DONE", "IN_PROGRESS", or "REJECTED".

Storage Proof Dashboard

Alternatively, you can monitor the progress of your Storage Proof query using the Herodotus Storage Proof Dashboard. This visual interface provides detailed information about your batch query and its status. Here's how to use it:

1. Navigate to the Explorer section of the Herodotus platform.

2. Enter your Batch Query ID in the search bar at the top of the page.

3. The dashboard will display detailed information about your query, including:

   • Batch Query ID

   • Submission Timestamp

   • Destination Chain

   • Fee

   • Current Status (e.g., RECEIVED, ACCEPTED, DONE)

1. You can see the progress of individual queries within your batch. Each query goes through several steps:

   • INITIAL_STATE

   • BLOCKHASH_AVAILABLE

   • HEADER_ACCUMULATED

   • ACCOUNT_ACCUMULATED

1. The dashboard updates in real-time, showing the status of each step (COMPLETED, IN_PROGRESS) and the timestamp for when each step started and completed.

2. Once all steps are completed, the overall status of your batch query will change to DONE, indicating that the Storage Proof is ready.

This visual dashboard provides an intuitive way to track the progress of your Storage Proofs and understand the various stages involved in generating the proof.

You can view the request related to this tutorial here: https://dashboard.herodotus.dev/explorer/query/01J2V235ABJY55JS2MY051ZJFJ

Step 5: Retrieve Results

Once the status of your query is "DONE", you can retrieve and verify the results of your Storage Proof. This process involves interacting with the Herodotus Facts Registry contract on the destination chain (in this case, Sepolia). Here's how to do it:

Facts Registry Contract

At the time of this tutorial, the current Ethereum Sepolia Facts Registry contract address is:

0x7Cb1C4a51575Dc4505D8a8Ea361fc07346E5BC02

Retrieving and Verifying Data

To access the proven data, use the accountField method in the FactsRegistry contract. This method takes three parameters:

• The address of the contract you're proving data for

• The block number at which you're proving the data

• The storage slot you're accessing

We remove the padded zeros, convert to a decimal.

https://www.rapidtables.com/convert/number/hex-to-decimal.html?x=1043251713F3CC4E87

Next we divide by $10^{18}$:

$$299986203928494362247/10^{18}= 299.986203928$$

https://sepolia.etherscan.io/balancecheck-tool?a=0x17C2D875CB397D813eAE817DaFD25807E348Df07

We can see that the balance matches the accounts historical balance as we expect.

The account balance has now been successfully proven and now can be retrieved on-chain with the FactsRegistry contract.

Conclusion

You've now successfully submitted a Storage Proof API Batch query to prove the Ethereum balance of account 0x17C2D875CB397D813eAE817DaFD25807E348Df07 on the Ethereum Sepolia testnet at a specific block. This proven data can be used in various applications where verifiable on-chain data is required.

By following these steps, you can leverage Storage Proofs to verify on-chain data in a trustless manner, opening up possibilities for more secure and transparent blockchain applications.