GET Documentation — State change batches

A state change of tickets and other tracked assets in the GET Protocol results in a state change receipt. A single receipt contains 4 data points about a state change of a digital asset tracked by the GET Protocol. Receipts are aggregated in Receipt Batches. These files are periodically stored on the public IPFS network. By blockchain developer Kasper Keunen.

This blog will provide details on the concept of Receipt Batches in the GET Protocol.

A single state change defined: If a ticket is scanned it changes state. The ticket changes from being valid to being invalid.

In Statebox/petri-net jargon we refer to a different state as a ‘place’. By scanning a ticket moves from the ‘valid’ place to the ‘activated’ (or invalid) place. In its new place the ticket has different properties.

To read more about the different properties per place read this blog.

This change of a ticket state means that its new state (or new place) the ticket asset has different properties. In order to spread to other actors in the GET Protocol that a certain state change has occurred, state change receipts are used. More information about the structure of state change receipts is disclosed in this blog: (NOT YET PUBLISHED).

Screenshot of 8 state change receipts in the form they are currently stored on the IPFS network.

Receipt batches

Stoolbox stores the ticket mutation data it collects periodically on IPFS. IPFS is essentially a distributed and public Google-drive (IPFS has a lot of similarities with the torrent file network). After a file is stored, anybody with an internet connection and knowledge of the location of the file can access the file. Example of an IPFS batch as stored by the GET Protocol.

The fact that IPFS has no centralized controller is a feature. As it is impossible to censor or manipulate. However, because of this feature, there isn’t any guarantee data stored to IPFS will remain available. In addition, there is no reliable way of knowing how long a file to IPFS has been stored there.

In order to make the data published to IPFS immutable, blockchain anchoring of the IPFS file location is used. This means that the file location on IPFS is stored in a smart contract(currently deployed on Ethereum). We call this contract the ‘IPFS anchoring smart contract’.

Batch anchoring smart contract

The current implementation of this contract has two main functions:

1. Making the IPFS batch locations public (like this).
2. The contract acts as a single source of truth for the ticket explorer nodes (decentral API endpoint)
3. Timestamping and sorting the batches in an immutable manner.

The smart contract code that is currently used to anchor tickets can be found on Etherscan.

Immutable timestamping

The role of the IPFS anchoring smart contract is to store and timestamp the IPFS hashes containing the state change batches in an immutable and public manner.

By crawling this public smart contract, a ticket explorer can collect the complete transaction history of the GET Protocol.

Figure A. Diagram showing the storage and ordering function of the IPFS anchoring contract.

Note for developers: The address and exact coding of the IPFS anchoring smart contract is expected to change in the future. For example we are working on adding a GET proof of burn check part of the contract logic. If you have ideas or suggestions on how to go about this in a decentral manner we would love to hear them!

More details on the API-endpoint approach of the burn-address is explained in the blog linked below.

The Transparency API endpoint — The case for burning

Storing hashes to the IPFS anchor contract

Per time interval the GET Protocol stores an IPFS batch hash by using the ‘registerBatch’ solidity function. As of now only the owner of this contract is allowed to publish batch data to this contract.

function registerBatch(string memory _ipfsHash) public onlyProtocol                 {
        batches.push(Batch(_ipfsHash));
        emit Update(_ipfsHash);
}

With the current implementation of the anchoring contract, only whitelisted GET Protocol Ethereum addresses are allowed to store batches to the anchoring contract.

Reading data from the anchoring contract

The image below shows the process of decoding a registration of an IPFS batch ‘by hand’ with Etherscan. When automating Ethereum tooling as web3 can be used.

Figure B. Anybody can decode the input data of every transaction done in the contract. Try it yourself. Check out the transaction receipt page, click “Click to see More”. Then where it says ‘View Input As’ select UTF-8. This will expose a hash. This is the IPFS hash.

The GET Protocol will provide tools & scripts to decode and extract the batches stored on IPFS automatically.

The hashes stored in the contact look like this:

QmURj5jz7PLkjCNRNxhXwNZLmyk1Y9CGZHqTAuhhzJ8742

This hash is all that is needed to download the complete batch file from the IPFS nodes. Try it yourself! You could use an Infura API endpoint to fetch the file:
https://gateway.ipfs.io/ipfs/QmURj5jz7PLkjCNRNxhXwNZLmyk1Y9CGZHqTAuhhzJ8742

The IPFS hash doesn’t only allow a node to access the receipt data, it also allows the node to verify if the published IPFS hash actually corresponds to the stored file. As the hash is the digest of the buffer(this is actually a foundational feat of the IPFS/torrenting/p2p networks).

Serializing batches

Incoming state changes are published in batches. Each IPFS batch consists of a raw text file with each line of a batch representing a state change receipt of an execution.

All receipts in a particular batch will have the same timestamp. As the timestamp of the (Ethereum)block that registered the IPFS batch anchoring contract call/registration. It is very well possible that multiple state change receipts of a single ticket are present in the same batch.

In the “Event” feed of the anchor smart contract the latest 25 IPFS registrations are shown. By decoding the input values to “Text” one can Source

A ticket explorer node extracts the locations of the IPFS batches anchored in the contract. The blockheight of the anchor transaction registering a IPFS hash will determine the timestamp the state changes in the batch will be attributed.

IPFS hash, blockheight of registration contract call 
QmYSPwQmcyjJ7K1JqC78xGniU5mH4rYSDKMw6z7gBpjs8R ->  9545498
QmPF6HQFPdiTd6yqjU41TKgtT5ffzgFNLgdZtFbMhteKa1 -> 9545240
QmSvkjwf5YdxeoUUvzv2Wf1WobkcVqjn2tU91ZmwEMWo3C -> 9544958
QmTVF2EoEAHyVDMhs4iRKYDg58oGigi19zU4ZKX26iAS28 -> 9543592
QmaaM9tJhDt5A73GY6ug3hmDcTTEc1PNb6XetnXtvqPc7s -> 9542517

With help of the web3.py documentation we can figure out what the timestamp of the block height registering the batch is.

IPFS hash, blockheight ETH, 
batch: QmY... with 46 state changes timestamped at 24/02/2020 10:00
batch: QmP... with 6 state changes timestamped at 24/02/2020 
batch: QmS... with 21 state changes timestamped at 24/02/2020
batch: QmT... with 12 state changes timestamped at 24/02/2020
batch: Qma... with 8 state changes timestamped at: 23/02/2020 23

Ticket explorer nodes can store and index the receipt data in a way that they can easily retrieve and serve the data when it is requested. When any actor in the protocol doubts the validity of the served data, it is easy to check the data by looking up the registration of the batch on Ethereum or spinning up a node for themselves.

More about the GET Protocol

Any questions or want to know more about what we do? Join our active Telegram community for any questions you might have, read our whitepaper, visit the website, join the discussion on the GET Protocol Reddit. Or get yourself a smart event ticket in our sandbox environment. Download the GUTS Tickets app on iOS or Android.