Navigation
QUICKSTART
Introducing State Proof Alpha
1552235664131
Sep 16, 2020
by Atul Mahamuni
Senior Vice President of Product at Swirlds Labs

In a typical decentralized ledger, if you need to cryptographically verify that a particular fact about a ledger — like a transaction or a balance — is true, you need to run the entire blockchain and validate the blockchain from the genesis till the point in time that is of interest.

Hedera has defined an innovative way to provide a cryptographic proof for the blockchain where any consensus node in the Hedera network can provide a portable proof that can be cryptographically verified and trusted, even if you don’t trust the node. The trust in the state proof is derived from the trust in the supermajority of stake in the Hedera nodes. For a more detailed understanding of State Proofs, check out this this blog posting by Paul Madsen, Technical Lead at Hedera: https://www.hedera.com/blog/state-proofs-on-hedera. Ahead of the launch of the full state proof capability, we're happy to announce the availability of a subset of that functionality called "State Proof Alpha", which is available on the testnet today and the mainnet soon.

Using State Proof Alpha, users can now obtain a cryptographic proof that a particular transaction took place on Hedera, and what the results of executing it were. A Hedera mirror node provides this portable proof for the transaction records that can be independently verified to ensure their validity. Similar to the promise of what will eventually be full state proofs on Hedera, the user can trust this state proof alpha served by mirror nodes, even when the user does not trust the mirror nodes. The validity of the proof can be checked independently to ensure that the Hedera mainnet truly had reached consensus on a specific transaction.

Keep reading below to understand how State Proof Alpha works and visit the official documentation at https://docs.hedera.com/hedera/core-concepts/mirror-nodes#state-proof-alpha to get started.

What is State proof alpha?

Here’s how State Proof Alpha works:

Obtaining the state proof:

  1. A user requests for a state proof alpha for a particular transaction ID to the mirror node REST API.
  2. Hedera mirror node responds with three artifacts returned in base64 encoding:
    1. A transaction record file that contains the transaction record for the specified transaction.
    2. A set of signature files signed by individual consensus nodes in the Hedera network.
    3. The address book that contains the public keys of the Hedera council nodes.
  3. This set of artifacts are a portable proof that can be independently validated.

Validating the state proof:

  1. The user first validates the address book. This can be done in various ways: The user could query the address book using a Hedera API call to the network as explained here or view the public keys here.
  2. Once the user has validated the address book, now they can trust the address book. With this trust, they parse the address book to create a map of Hedera node ID to their corresponding public keys
  3. The user then uses these public keys to validate if at least a third of these nodes had provided their signatures on the hash of the transaction record file.
  4. A hash of the transaction record file’s contents is generated and is verified against the hash contained in the signature files.
  5. Assuming that at least a third of these nodes had matching hashes, the user can then trust the transaction records file.
  6. With this trust in the transaction records file, the user can then parse this file and obtain an individual record for the transaction that they are interested in.

Usage

Obtaining the state proof:

You can view the mirror node state proof rest API documentation here.

State proof alpha mirror node rest API request:

Code Snippet Background 
/api/v1/transactions/:transaction-id/stateproof

State proof alpha request for transaction ID 0.0.88-1600124832-528679000

Code Snippet Background 
curl http://testnet.mirrornode.hedera.com/api/v1/transactions/0.0.88-1599071035-397056000/stateproof

This will download a package of the artifacts as follows in base64 encoding; save this file to reference in the next step:

Code Snippet Background 
{ 


"record_file": "AAAAAgAAAAMBCdm/bNWLd+iJ5Ens9RpybPyrqX03gsAquC11heMYEaE053a8GOYkmYnD8m1wEZCcAgAAAK0aZgpkCiB7Au09TM2zbc2cNXzcdknUWEmV0nS2DN+VuVOWwv3k+hpAgkqsvdnWDxUDc9U7rSan8BsjFhRKzsROI79+uzYuTroP817d6MRZEH+u1u8MELOtFlweeoWF4orbznYq1TDMDCJDChIKDAig7//6BRDYgIz8ARICGFgSAhgDGIDC1y8iAgh4MgxOZXR3b3JrIHBpbmdyEgoQCgYKAhgDEAIKBgoCGFgQAQAAALAKKAgWKiQKEAiw6gEQpo8HGgYIsNvG+gUSEAiw6gEQqaMHGgYIwPfG+gUSMA3XdV01Kno9eNehEezZj2nTGcDsElOVX/w0F5Q0i7Ams0IfYhhowa60PqCQ8y4E5BoMCKrv//oFEPDO0ZADIhIKDAig7//6BRDYgIz8ARICGFgqDE5ldHdvcmsgcGluZzCkxw9SHgoICgIYAxCC8wEKCAoCGFgQyY4fCggKAhhiEMibHQ==", 



"signature_files": { 



"0.0.4": "BF80ocWrrDhbbsgdN1+ucuf41D1QClqYwmKSw+8S9cXd/gb9XWvd4MNirjdEoz3kAgMAAAGAJLPBGZqI404JtJ3XiZyMOuCHp7C5RLeNdgCb9tIQ9jaEpZBe2kADiW6VHN/TtHGxJHspT6L3mofpVwYMLpv3SBUuslxMPPp2yXd1eOCoGJa4bJ+xYUj/0K0kqEp0uyjRX3Skfew8ofqvu71XjQcjFBlPevRCUDuxYLAl+nzhVVmOmKfWC9l+WYR9ADdfJuqqQvZI79d6h+IqQffBnGDAYIsgHgN80lnrbQHsvwlIQ/CV0DehNPEsuGs1b8/x4aHYeyJBCLwP/sAXhgIRR98plxD0y0zchTCWelh+NQC0aPe5r8pZ+ZXPb1TbNldSKJIrmf4ranf4/714uY5PiHpwVL4PNDh4FDSyRafWqISZTV7EHR0NrnzpJp3BdPr80PmjjU2gw4n3nd+qAG+gSpbW3Pkw/db3ZrMMVkQUqNUQ2RiIQuPkz3sktW+bExLHWlbbdK4gDYlfZoJ2o7L+yLeFZQtOvfb4STNJekisRFJHjzWkfkOFcbteNKhUuTaczk1V", 



"0.0.3": "BF80ocWrrDhbbsgdN1+ucuf41D1QClqYwmKSw+8S9cXd/gb9XWvd4MNirjdEoz3kAgMAAAGAJihwOx4RL+tcoIXChOCYBx4MgMZvwvJHY4QTiTd4zDMwnyaOizc9aBdHaieZrpWG7oseBDTEb1EsLWEBKWuvPvCZsTYlUIbPUUmHq4jZCtJjdWD015MVGbtAAVH2zQmXzGf/YqO9hwh6VLvn1ZNyDCl4k4wMqsVByewbpQIji6OcRCUuCGU0XDSCaREvrsuvI5vXftDgAq3nlGB/TEror/sFuzOHVbO99jd2QTA8UkV6Cr2kXwjQekWjfGpDn4ow5s8znqZKQ93vzGWmnmSDbBjLUYKuxcaJcxm2QFizWNrcCu+yjO4v2DrLWGWbu+9ZfJMOgp8cbrIshsmSWfDNfOjZ08VBalOY/I9cII7Ln1l2727xToen7iHWPnk2SYXWRoU56dSta7Cgwr/JxB8LeQyx4j2P7+Iy/K8zpAOu5p1WMZVNhJzCeRGZNEoFzt3nj9j7uGp6kPDsvT5Wbb+8bG4zFCqMhiPa8tqi27xghY83/efJG72qwp+h3FTlCa5/", 



"0.0.6": "BF80ocWrrDhbbsgdN1+ucuf41D1QClqYwmKSw+8S9cXd/gb9XWvd4MNirjdEoz3kAgMAAAGAY1oL4Ikcf+9rBLV9kdIgDvHMHhq5uAHsy0xpbNKO5YNYAmNNd5LnwHdG36QJpN4bENxl83EdegonMGSzxdjpCOMYzJloUGZGaVPKNPw9tjJN7ZxL/tZAoSMCUULzQrNfJzKF/bm3w7DTGLo32+NynRHAM7eb3uPhW3PhwZiQbVV36i3FbbT+vaQJJS0W7AV6sSERZjIfGJUC3umoBSaVXM7MhL2OwkkclcQKAnXu7kv8nC4aUi32gSF3rvcV1cBSL5ckMTGbJeMXBgcarcdIruSqk2UMT1ANlzHPTqLimAnls5rdX8IvYOXX0ewZnq7eDBVTchbW1msJw1d5fM8elWnU5yc2gcJSu2xmQ639ph+FwsPmHSzlnADgbB3ngVgTenPkEvZMgHM33/YMmAHjZwkaGoYiYjw/q1p2WTv1hrdA4jCw/Y+QjagHbmwsuu8jMb9R775HjrxriQuW1BMErgv2CHEJidCyLtwm8os3avn2YnxmlC1iAFzZt7VdSBrk", 



"0.0.5": "BF80ocWrrDhbbsgdN1+ucuf41D1QClqYwmKSw+8S9cXd/gb9XWvd4MNirjdEoz3kAgMAAAGAc2B7eKq6UxWP76uiKdNEbmiMgvpuU5RioXHo6D/X9cgfct58GygYvV4BVL2jYY9fAKWsDbbjVKiG8YsBn84vw3XKuWIku8lRv5nfgQydHTImrjeFCLPOuBfVFbyiti0kG9DiuvEGbPUYLVA/HGUwEyTLkG8Y4RP05eB2RZ6oWJC6iU0QS/cLiGwIw3q1/7EkQLRB3/lauypl9MYkoxlJSnvgVwnWJedVYnfunbgMTY97akUr4UPXmXijpJ9cdVGeMory+2AnEaMyl50Bf/lrrXd+WvfW9SeI+ExafDtqAU2BtkskimQ7sEJNY21lUWF8wH7k/PBArkT+ucIJAPjDKlwYSssHbsi2NuVO6FIV+XTMmNIWs8PwYu0Da77OidgW3srkk6OEQZBBu/np16UPqyom2Fd2ug342noVGMZCr0WSiIuZjLc37ytue48d//NO7JvR8CaFgCQPdSLMW4hVoNArjsj7xgGatoJWXZgw6WU65C14JGPRpCp8I640Qsjx" 



}, 



"address_books": [ 



"CtYGGgUwLjAuNSLMBjMwODIwMWEyMzAwZDA2MDkyYTg2NDg4NmY3MGQwMTAxMDEwNTAwMDM4MjAxOGYwMDMwODIwMThhMDI4MjAxODEwMDliYTQ1N2I3MzMwNWYwNGE5MWNjNDZiMWI5NjVjNGU4NDE3NTFhYmM4YjE0MTVhMGJhZGZkMWYzMmMyNDgyMzg2YTIyNzI1ZWI3ZWM3NGRlYTIxZTUwNjE3ZDY0OGVhNWFjMzkzNzQxYWIwMWI4ZWZiMzIxMjM5YjhkNGZkYjFkZmJlYjllM2YzOWFhNDY1ODBkZDA0NWQxOGNhNDRkMDAyYzM3ZGRiNTI3Y2NlNGRkYzMyYmZjNzM0MTk2NzFmNGNhNDQ2NGEzZjJhODRmYzg1YzcxYWNmMGU1YTg5NjI2ZGY2OWE4MTQ3NGVkMTY1MjlmODAxYThhZmE5N2U0MzVjNGUwNGE5NjRhMzU3NTI3Mjg4ODQzZTU4ZjBhMDVjZjUxNTNlZTQ1MDdiMmM2OGIzZDdmYjU0YWU2YTk1YTk1OWM4N2ExMmY2MzBlOTVjN2IxYjNjMzY5NWU4NTg2NjI0MTc5MjZkNzZjMTY5ODNmYWY2MTIyNTAzODc0NTkwN2U5Y2YxM2Q2N2MyYWNkNTAzY2E0NTFjODU5MzNhYzQxMThhY2MyNzk4MDFjYjk2ODM0OTkwMzE0NWNlZDI3NjI5ZGQwODkxNjMxNzA5MzU4N2E3N2MyMjA1Y2ZhNTI1NDNiNTNjM2I2ZWExNWI4NGUzZDJjMzBjMWVkNzUyYTQ2MzNjMzZiMjViOTg5M2VhMDJhZDU2MmViOWI3ODY4YjNiNGY0N2Y0YTI1ZTM1NjA2NDk2MmFjN2IyNWU1ODI5NDRmMDBkMzA3OThhMjYyZjkyMTRkOGM1ZTc0ZDBhODM3NmNjMmQ2YmE2NGUxOGY1ZTRhNDBhZmFjNjI1MDYyZDJjYTIzY2QyODAwNzA4MzIxZDM4MzQzMTRmMGU1ODQ0ODU5MjMyNjczYTMyZTcwYWUwZDcxMWUzMTA1ODFiY2RiMTRlODcxMzQ2OTRjNmUwOTMwZjQ2YjM3Yjk2ZDQ5YTY0NTczOTQ3MzMxZTdlNTA3ZDllNTZkZTVlNjE0NmYyZjAyMDMwMTAwMDEK1gYaBTAuMC42IswGMzA4MjAxYTIzMDBkMDYwOTJhODY0ODg2ZjcwZDAxMDEwMTA1MDAwMzgyMDE4ZjAwMzA4MjAxOGEwMjgyMDE4MTAwYzQyY2NhYzVmYmM2OTFmYmJlYmRhODdmZmQxZTc1YmRjZDg5MjI0OTRjZjQ0ZmRiY2NlZTQ5Nzg4NTIxYzM3OGJmNzdkYjA5MzRlYzBkMjE4M2Q3YzUxZGI2NmY4NjRjMTFhYjdkZTFhYzNjNGNmZGMxZjA5M2EyZDZmMzdlMmIzNGNiZTRjODEzMWY5NjgzYWQ0Mjg3OGM4M2QzNTU0YzY0NWFhMTY3YmNmYjA2NGE4M2RjNDVjNWIxMTU4NDk5ZjlkOTI1ODdmZmY3YWJjZDVmMjIxY2Q4MTUwNTQ4NDEzMDAwZmE2ZTU2NTkwODliMWRmZDY1NzY2ZWE3OGVhZWRmY2E2YjQ1NDU1ZmQ4YWI1OTg0ZGJlMzVlNTc5NWQyYzYzNWVhNzk3NGQ0M2U4ZWFlNGZlYmZmZTQ5MmU3MDdiNDhiMWIwZmM2NDgxYWU5ZTA5ZDM5MTMzMDA5YjdkMjY0MDJlNmU1MmU1ZTkxYjJiMzgwZDg4ZjBiZTdmYjRiMzAzZTcwMjE5Nzg1MDU3YWE5NGNlOTI0YzQ5MjZlOTE2NTY5Mjg2ZTg2YjNiYTY1MWNhMmEwYTYzZGY0ZjY5MDdmZWZlMzQ4M2Q5M2I0Y2UxZDRkMDNjNzE0MjExMTM3NWIyYzJjNTFkNGViODM5ZTM3YWY1MzBiMmNiZDZmNTBkNGNiMzZlMjc5MzcxNzBkOWNkZGFjMGFjZTJjYzI0YjgwNGIwYTI3MzUxY2Y4MzBiNzY1MjVlMjZkZmI5ZGJmNDlhMDU2NjI0YTc2ODYyNDk0ZTcyNjNkMGQ3MGNlYmFlOTUyOTQzZTU1ODQyZjVjYWQxM2ZjZjYwYTJlNmRjZjdhMWQ1MzNmM2E1YmI1NGVjMjE5MThjNzZlNTI1YmEyOTE0NjY3NTgzMWUxN2UzNmM2MWZlODU0OTg4MjhkMDliNzYyMDE1NDEyYjJlNTI3ODQ5YmFlYzFjZmZjNzdkZTRjMjk0YzU1MDgxMWU1OThmZjI0ZGExNWEzNDU2OWRkMDIwMzAxMDAwMQrWBhoFMC4wLjMizAYzMDgyMDFhMjMwMGQwNjA5MmE4NjQ4ODZmNzBkMDEwMTAxMDUwMDAzODIwMThmMDAzMDgyMDE4YTAyODIwMTgxMDA5ZjFmOGExMjFjMmZkNmM3NmZkNTA4ZDNlNDI5ZjBjNjRiY2I0NGM4MmE3MDU3MzU1MmFhZGNhZDA3MTU2OWU3MjE5NThmNWE1ZDA5Zjk1ODdmZmFmY2ZiZTUzNDFhMmYwMTE0YWNhZTM0NmVmM2M5MDIxM2QzNDM2ZWJiMjdmNDM1MGM5OTBjNWM4YzNmOGUxZTM2NzA3YmMwOGQ0MjU2MDgyM2UzZjI0ZTA5YTAzYWQwOTU1YTUwOTgwMTk2MjlkZDA0YjI3YjI1MWRjZTA1NWYzZGRjYjBhNDFkNjZmMDk0MWIwYjg3Y2RmZTM0OThkNDYwMzhhYjVkZjA2ZjYyYTVhZGUwODU5ODU3M2E4OGM4ZjU4NjBkYzE0OTJhNmUxODY0ODVhOWIxMzI1MGU2ZDE3YjgwY2QzOWM1YzgxOTEwOWU3M2NhNzMyZGIyM2VmOGJhYTc3NmVjODVjZTAwOTFiZWNiMmVkZWZiYWE1ZWQzZTVkYmZiZDFmODg1YTRmYTg4MWFmM2YxNDRhOGE1NjU4NTM1MzNkODkzOTM1OTIwODZiMmQxZDM2MmU0NWJmZTFmYjQ1NjgzYWJhNmM2NDA5NzlhZDZiNDY4NzcxODQ3MjZjNmViZDU4YjJlYWU4NWM3Y2ZlM2ZiYWJlZjVmNmNjZWQ4NTAwMzRiMzg0NzIwNmMyZDY3OGMzNjE4NzYwMjZiOGQzNTFlMDAyYWY1ZTBmZmU2ZjViMWYyOTVmZGMyZjQ2OWNhYTJkMjM4MWVhMGI0OGNhOTg3Y2MyYzhlNjM1ZThiMTljZTVlMTcyYTkzNzYxYThkNDkwYTlhNDUxOGQ3MjU1ODgwYTE0ZDc3YjdiYTc3NDg5MmI5MmE0MGJiODEzNjJlMzRmYzZkNTE3OGQ5YjMwMTEyOTM0MjA1Y2I3N2ZiOWEyODI0MjczOTQ1NjRhODU1NGVhNDcyODZhNDdmODYyMzllNzVjOTQ3ODljZTk4Yzk5ODQ0NzgyNDYyOTQ0ZjYxMzE2N2Q3YjUwMjAzMDEwMDAxCtYGGgUwLjAuNCLMBjMwODIwMWEyMzAwZDA2MDkyYTg2NDg4NmY3MGQwMTAxMDEwNTAwMDM4MjAxOGYwMDMwODIwMThhMDI4MjAxODEwMGM1NTdhZjU3OWZhODM1MDFiZTg5OWIyODkwNzc2NWJmZGZjZDUyYWI0MzJiMDE5NWExZjFlY2Q4NmZjMDBhYjZjNTUwOWIwZmRkOTdlZGQzY2I1Y2VhNTZhMjk1ZjMxMmFiYjU1MDgzMWRiZjk2M2Y0NTAxMThiNGZjYzZlMjJjZjQ2NzYyMDBjZTljYzhlZGZiYmY1NThkYzY5ZjAyNDI2NGFkN2QzZGFiMjNiZWQyMTMzYzI3NGU2OTM0NDg5MTU1ZGIxMDg3ZjkwMzcwOTA1YzY0MTg1YTYyMTFkYzc0MmZiOWE2OTA5ZDgyMTg2OTQ3YjI3NzQ2M2RmYjNmZjBhY2Q0N2VmZjEyZWFkMWY2OTcyZWYyYzEyMDM3OTNjNDVlNzc1NzViZTRmYTExMGM3ZTQwZmE4ZGI5YzYxODdkMTEzZjQ3MDQwMTQxNzkwNzFhYmY1OWJlN2QyYjBkZTgyZGU0MjE1ZGMyNTUwNmIxYzljMjZlNDkxNzQwMWM5OTc1MDZlMzc3ZTZiZjAzYjY4ODcyN2U3OTQwZmFkNjljNWUwZGEzY2Q1Y2JkMmJlNzc3MzUwYWVhMmQwZDQ3ZTk3YTQ0OGM4NGJlNmNlMTM0ZDY0YmVlMDk4NWMyOTE2MmY0YzFlNTY3Y2NhOTNkMDZhM2MxYmU4YWJjZTM1YjU1N2ZiNzdmNGZlNjcxYTY2ZGVjNzkwNzU2ZDBlODgxODE2NWYyYmFjYWE4OTFhYWU3YWM3NDM3ZmM3MTc1YjZlYjZkZWI3NDcyMzc4NzUxYmI2YmY5YjBlMTQ4M2Y5NjY4ZTlmZGJkNTYwNGMzOWIxNGQ5ZTJiZWRlZWM4NDZhOTgwZDcwNGQxNzFlN2JhNGI3ZmNkMWEzMGQ5NDVjYTEyZjQ3YTMyNWQ5Mzk4YWExOGY5NzA2NjA1NGQ0ZDE1ZmM4OTk0ZTJkZWJlNzNlOTI3MWQ1NDg2ODNmNjFlYTQ0ZmIyNTA3MWUzNTE4YTc4ZWQzZWIzN2U3MWEwNjkxZjI2NzAyMDMwMTAwMDE=" 



]}

Verification:

Hedera mirror node provides a pre-built utility code called check state proof that automates the tasks of validating the address book, checking the signatures on the transaction record file, and subsequent validation of the transaction record.

To install the state proof validator, you will need to install the Hedera Mirror Node and complete the check state proof instructions here.

Installation

From check-state-proof/ in the Hedera Mirror Node repository run:

Code Snippet Background 
npm install -g .

Run

From command line run; where testnet is the default network and <filePath> is the location of the mirror node state proof response json file:

Code Snippet Background 
check-state-proof -t <transactionId> -f <filePath>

A successful state proof validation response will return the following:

Code Snippet Background 
Record file hash was successfully matched with signature files 


----------------------------------------------- 


The state proof is cryptographically valid 


-----------------------------------------------

A response that is not successful:

Code Snippet Background 
Transaction ID 0_0_88_1600124832_528679001 not present in record file. Available transaction IDs: 0_0_88_1600124832_528679000 


----------------------------------------------- 


The state proof is cryptographically invalid 


-----------------------------------------------

Availability

This feature is available in Hedera mirror node release 0.18.2. If you are running your own instance of the mirror node using Hedera’s open source code (https://github.com/hashgraph/hedera-mirror-node) or accessing Hedera hosted mirror node, you can access this state proof alpha feature.

Uses

You can use Hedera’s state proof alpha for any place where there is a need to cryptographically validate that a particular transaction took place.

Examples are:

  • Proof of payment
  • Proof of transfer
  • Generating a transaction record for bookkeeping/accounting purposes
  • Usage in audits or for proving compliance
  • Proving in a court of law
  • Validating transactions on Hedera to generate Oracle messages
  • Validating transactions on Hedera for minting/burning tokens in other blockchains for interoperability use cases

How is State Proof Alpha different than the eventual State Proof?

Here are some of the disadvantages of State Proof Alpha as compared to the eventual State Proof capability:

  1. Size of proof/Volume of data: Since the state proof alpha returns a transaction record file, which could contain thousands of transactions, the size of the proof returned by state proof alpha is large. Hedera mainnet and testnet currently creates a transaction record file every 2 seconds, and therefore this file could contain transactions for 2 seconds, as against to a single merkle root hash and the merkle path that will be returned in the eventual state proof. While this makes the state proof alpha more inefficient than the eventual state proof, it’s significantly better than other blockchains where the user must process all the blocks from the genesis of the blockchain.
  2. A side effect of a large size of the proof is that the proof checking will have to process more records. While this is not a concern in a typical software application, this could be a problem if the user is trying to run this checking in a smart contract on chains where the gas price could run up easily.
  3. Currently, Hedera’s address book is still evolving as we add council members. By the time we launch eventual State Proof, we expect the address book will be stable and we will provide more elegant solution to check the validity of the address book

How do you plan to use State Proof Alpha?

Our vibrant user community always finds creative ways to use the functionality we provide. How do you plan to use this feature? Please drop us a note at [email protected] or Tweet us at @hashgraph.

View All Posts