Geora is a blockchain-based platform for securing, tracking, and financingagricultural supply chains. Geora provides digital infrastructure and tools that allowusers along agricultural supply chains to build trade and finance solutions using theWorkspace, Showcase, Network, and Developer capabilities of the platform. Thisdocument contains an overview of the technical design and implementation ofGeora, including a breakdown of its components and the technologies used.
TLDR
How does Geora work?
Users interact with Geora through our web app and developer API. They cancreate shared asset records across an entire supply chain, interact with othersupply chain participants, and share their product journeys with their customers.
Underlying the user-facing application is a private Ethereum blockchain. All highvalue interactions and data additions in the app are immutably recorded on theblockchain.
By combining traditional and blockchain technology, Geora can make the mostof blockchain’s advantages, without sacrificing the ease-of-use and speed of traditional applications.
Why does Geora use blockchain?
Supply chains are naturally distributed networks of producers, traders, andcustomers, who want to contribute to shared data records but may not have preexisting trusted relationships
Blockchains provide a verifiable audit trail which is extremely difficult to tamperwith, and can be validated by any participant in the network
The blockchain ecosystem is increasingly standardised and interoperable,allowing Geora asset records to be shared with marketplaces and decentralised finance products
Can I use my existing data platforms with Geora?
An increasing number of agri-data platforms have direct integrations to Geora, meaning you can get started right away without manually re-entering data.
The Geora developer API provides complete access to all Geora functionality, and can be used to directly integrate new data platforms.
For customers on the Business subscription plan, their ten developer hours per month can be used on integrating exported data from various platforms with Geora asset records.
How is my data secured when I use Geora?
Customer privacy and flexibility of data permissioning are built into Geora at all layers. All data entered is private by default, and stored on the blockchain in a manner that only allows those with access to reveal it.
Through permissioned asset lenses and exhibits, you can share part or all ofyour asset records with certain other users, or your customers.
Geora uses industry best practices to secure your account data, files, and all other personal information stored in the application.
Core Technology
Geora is a hybrid blockchain system. The system is composed of three layers:
Network layer: contains core logic and immutable, verifiable data, using theEthereum blockchain and IPFS decentralized storage network, and secured byconsensus amongst participants
Business logic layer: contains application logic, including smart contracts encoding financial agreements and supply-chain workflows, and simplifies access to the platform by providing key management and efficient data storage,eliminating the need for blockchain experience
Access layer: contains customer-facing tools for building rich traceability records,tailored to the user’s supply chain, and showcasing their stories to consumers, counterparties, and regulators
In this section, we will elaborate on each of these layers, and the components within.
Network layer
The protocol layer is the source-of-truth for data in Geora. A private, distributed network of Ethereum nodes contains asset, certificate, and broader supply-chain data. Core logic is encoded into smart contracts on the network, which govern asset ownership, permissions, and verifiable digital certifications. All participants of the network are able to verify that the logic is correctly executed.
Data stored in the protocol layer is immutable and versioned; meaning each update to the system adds another layer to its history. This history cannot be rewritten,providing an auditable record of changes to any data in the protocol, as well as an execution record for all trade and finance events. The histories of these workflow scan be accessed and analysed by tools in the application and business logic layers.
Asset data is not added in isolation: each record can be linked to other assets, smart contracts, and sustainability tokens, to build a complete picture of a supply chain. All claims and certificates which back sustainability data are fully auditable.
Geora has developed infrastructure to scale and manage the private network,reducing the complexity of interacting with a blockchain for both users and developers; the Geora API is blockchain-agnostic, without compromising onimmutability and data security.
This layer also stores encrypted certificates in IPFS, which are hashed and attached to assets in the Ethereum smart contracts - preventing any centralised point of failure for digital certificate storage.
Business logic layer
The business logic layer manages and deploys Ethereum smart contracts. Using these contracts and a customisable workflow engine it supports financial agreements and workflows tailored to customer requirements. These workflows can operate on assets, tokens, certificates, users, and digital currency to perform domain-specific actions.
At its core, Geora’s smart contracts represent agri-assets as semi-fungible tokens,which are continuously updated as they move through different stages of the supply chain.
The asset tokens are built by combining ubiquitous Ethereum token standards: ERC20 (fungible tokens), ERC-721 (non-fungible tokens), and ERC-1633 (re-fungible tokens). They are therefore compatible with other DeFi, traceability, and blockchain protocols. Each asset can be further linked to tokens representing eco-credits,carbon or water offsets, and financial instruments.
Blockchains are typically difficult to use, even for experience developers, due to theiradded complexities around security, performance, and distributed transactionmanagement. The business logic layer also contains supporting infrastructure whichsimplifies customer use of the platform:
Key management: to keep customer information secure, Geora manages eachuser’s cryptographic keys. These keys are tied to customer identity and used tosign and verify actions and certificates in the protocol layer. The keymanagement component removes the security burden of key storage forcustomers.
Data storage: the integration layer provides a fast, queryable database that reflects data stored in the protocol layer and makes it available to the access layer and third-party applications and integrations. Using a unique eventsourcing architecture, Geora is able to provide a fast and user-friendly access point that allows developers, financiers and farmers alike to use blockchain as a data storage platform, without sacrificing the trust provided by an immutable ledger.
Implementation
The layer is made up of a number of components deployed across Amazon Web Services and DigitalOcean, and relies upon managed providers of databases(Amazon Relational Database Service), secret management (AWS Secrets Manager), and file storage (AWS S3). Components are developed in the TypeScript, Haskell, Purescript, and Java languages
Core Technology
This layer provides customers of all technical abilities with access to the Geora platform. As part of the access layer, Geora provides a SaaS supply-chain traceability solution for non-technical users through a web app. The app is split into four complementary modules:
Workspace: this module provides a digital toolkit for asset traceability. Users can define asset data standards to support their supply chain, add and update traceability data and attachments, configure integrations with other systems, and trade asset records with other users.
Showcase: this module allows users to share the traceability stories of the assets in a secure, permissioned manner. Through lenses, asset histories can be filtered and configured to show only the information relevant to a particular viewer, from a consumer interested in a product’s sustainability credentials to a regulator inspecting an organic history. Exhibits bundle lenses together into market places and product showcases. All shared assets are fully brandable and can be embedded in other websites or apps.
Network: this module allows users to build and manage their network of producers, counterparties, and other contacts. After inviting other participants into their network, a network owner can assign permissioned roles and grant awards representing seasonal membership, certifications, and standard compliance.
Developer: this module allows customers with more technical capabilities to access the Geora API to build their own applications using the platform. Geora provides access to the business logic layer through a flexible and intuitive GraphQL API, which assumes no blockchain knowledge and makes it easy for developers from different backgrounds to build supply-chain solutions. Since the Geora API sits between the customer and the blockchain network, it shields users and developers from protocol details. Geora is able to stay up-to-date with the latest blockchain technology without forcing customers to modify their systems. The Developer module also contains comprehensive documentation and an API playground, giving developers the tools they need to get started with Geora.
Platform Performance and Privacy
Blockchain protocol
Geora uses the Ethereum blockchain to power the network layer. This is a private, permissioned network containing nodes which execute and verify all transactions.These nodes are operated by both Geora and its customers, creating a consortium chain.
Ethereum provides a number of advantages over other networks:
Configurable consensus algorithms for building fast private networks
A strong core team pushing state-of-the art advances in blockchain technology like sharding and proof-of-stake
Mature and comprehensive smart contract languages and tools
A large developer ecosystem
The network is secured using the IBFT2 consensus protocol, which provides finality and fault tolerance. It prevents bad actors from adding incorrect data or breaking the rules of the system. With a current block time of two seconds and high gas limits, the network is capable of processing hundreds of transactions per second in parallel,and tens of thousands of updates.
The network is composed of multiple validator nodes, including those managed by customers. It supports nodes entering and leaving the network, and tolerates node failures, without compromising up time and remaining highly-available.
Privacy
Customer privacy and flexibility of data permissioning are built into Geora at all layers. Geora supports data privacy, making asset and workflow data available to only those with permission, as well as transactional privacy, which obscures a customer’s counterparties and the actions they take within financial contracts.
To achieve these goals, Geora uses a three-pronged privacy solution:
Merkle trees and other hash technologies secure asset data at the protocol layer by compressing all data into one or more cryptographic hashes. The protocol can share this hash across all nodes without revealing any of the constituent data. Through Merkle proofs or providing plain text, workflows and contracts can check specific values in the data without revealing the entire asset.
When customers upload certificates, the protocol encrypts the data using a unique data key per certificate and stores it on IPFS. Users can share and revoke access to these files using their own private keys via asymmetric encryption.
Each user in the system can hide their identity using pseudo-anonymous ondemand identities. For each action they take, the user can generate a new identity using a hierarchical deterministic wallet that cannot be traced back to their public identity.
Data Management and Backups
Data residency
Network layer: the private Ethereum blockchain is maintained by Geora and hosted across two clouds for redundancy (AWS and DigitalOcean) in Singapore and the US. The public IPFS network is inherently decentralised, and has nodes all over the world. We host our own IPFS nodes in Singapore, and files uploaded are "pinned" so they are always at least stored on our nodes.
Business logic layer: all data is held in AWS in the Singapore region. Services and data are distributed across multiple availability zones for redundancy. All transactional data is stored in an Amazon RDS managed database. Customer files including asset certificates are encrypted and stored in Amazon S3 file storage.
Access layer: the Geora web app is hosted in AWS in the Singapore region, and distributed worldwide across the Amazon Cloudfront edge network.
The platform uses a handful of external services to enhance its functionality, each with its own data residency and privacy policies. Each of these services receives only the minimum data required to operate.
Honeycomb:application tracing, auditing, and monitoring
Grafana:application and network monitoring
Backups
A hybrid blockchain solution lends itself well to data resiliency. The “core” data in the Geora platform is stored in our Ethereum network, which spans two continents and two clouds for maximum redundancy. The network can tolerate limited node failures and still accept new data. All network data is fully replicated across all nodes, and in the event of a wider outage the network will stop accepting new transactions, but maintain existing data in the append-only log.
Transaction data from Ethereum is mirrored into Apache Kafka and streamed into RDS by our proprietary event sourcing service. This means that core transactional data is replicated to at least three data stores: Ethereum, Kafka, and RDS. Any of these stores can be rebuilt with data from any other store.
Customer data that does not fit the blockchain, like account information, is also stored in RDS. A daily automated backup is taken of this data.
Data segregation
As a SaaS platform, Geora does not physically segregate data from different customers or accounts. However, our platform is designed with privacy in mind and enforces strict logical segregation at the database level. Services with different data requirements are given minimum permissions to function to minimise the risk of data leakage.
In particular, the GraphQL API which is available to all customers is strictly controlled. The API can only resolve customer data through a dedicated database role, which is restricted with row-level security. This separates account data at the database level, rather than the application level. Even in the event that an attacker can exploit the API to execute arbitrary database queries, these queries could only see the data which is permissioned to a single customer account.
All customer files which are stored outside of the database (in S3 and IPFS) are encrypted with a unique key per file. Revealing the key for a particular file does not allow access to any other files from the same or other customers.
Security and Access Control
Platform access
The Geora UI and API are secured by industry-standard JWT authentication. Our identity provider, Auth0, is responsible for authenticating all user requests and returning a signed JWT that permits access to the API. Customer authentication information is stored by Auth0, and the Geora team has no access to customer passwords or password hashes.
Some parts of the Geora platform are able to be made public. For example, a customer can share a QR code that links to the history of a particular asset. By default, all data is private, and a customer must always explicitly grant permission to make it public. Through our lens feature, each public view of an asset history can contain some or all of the asset history, and can leave sensitive data hidden. Public view permissions are enforced at the database layer using row-level security, as with regular customer data.
Development practices and support
The Geora team follows best practices for secure development. Access to resources and deployment environments is access-controlled and scoped to individual developers, using AWS IAM authentication and a password manager. All code and development artifacts are subject to code review for security and correctness before deployment.
As part of the customer support process, the Geora team may access customer data when given direct permission. Access is restricted through admin accounts with limited team access, is time-limited to the support request, and is fully audited through our tracing infrastructure. Additionally, the nature of the blockchain means that unauthorized data changes are immutably recorded forever and cannot be hidden.
Integrations
To integrate customer systems with the platform, Geora provides three options:
Direct API integration: the Geora GraphQL API is used by the customer’s development team and/or the Geora team to directly integrate customer systems. The integration authenticates as one or more customer accounts and can read and write data using their permissions. This is the most flexible and fullfeatured integration option, as all of the platform’s features are available to the customer directly. It is also the only path (except the UI) for extracting data,rather than writing. GraphQL allows expressive queries which access only the minimum data required.
Webhooks: the customer system sends relevant events to a set of Geora-controlled webhook endpoints, which receive, process, and store the data in thecustomer account/s.
Email: the customer system sends relevant data in either CSV or XML format to a dedicated email address. The Geora platform is notified on new emails, and processes and stores the data in the customer account/s.
As part of the integration process, the Geora team engages with the customer to understand their requirements and find the best integration option. If the customer chooses webhook or email integrations, there may be additional development work required by the Geora team.
Data sent via the API and webhook options is encrypted in transit with HTTPS..
The frequency of data refresh of each customer integration depends on requirements. The system is capable of high-frequency refresh, receiving live updates as events occur in customer systems, down to daily or weekly bulk uploads