Actors
An actor is an entity in the system which represents a user of the supply chain. It could be the producer of a commodity, or a logistics provider. While there may be many real people performing actions on behalf of a company, the protocol considers the company to be a single actor.
Actors span the whole supply chain:
Producer: an actor who generates assets, including commodities, and introduces them to the protocol. This could be a wheat farmer, or a warehouse data provider.
Custodian: an actor who bridges the gap between the physical and digital worlds. They hold the physical asset and attest to the truthfulness of the protocol representation.
Processor: an actor who transforms the physical asset in any way, and ensures that protocol state reflects this change.
Certifier: an actor who confirms or provides real-world information on an asset and stakes their reputation on its correctness.
Financier: an actor who provides finance for or against assets.
An actor in the protocol may fit into many roles. A site operator for a grain bulk handler could take part as a custodian, certifier, and publisher at the same time.
Assets
An asset represents part of the supply chain; a real-world entity with unique data and history. While an asset most commonly represents a commodity, it can take other forms, such as:
A silo, which tracks its inventory as a commodity moves in and out.
A finance agreement, which defines lending terms between a grower and financier.
A package of data, which can be sold to other actors.
Identifiers and attributes
From the moment of creation until end of life, an asset is identified by a unique asset ID. This ID always references the same asset across the protocol. At a lower level, each change to an asset generates a new version, identified by a version ID. The asset ID represents the asset and its history as a whole, while the version ID refers to a particular point in its history.
An asset's class defines its variety or commodity type, like "APPLE" or "WHEAT", which producers use when generating new entities in the system.
An asset is measured using a primary value and primary unit, which refer respectively to the amount of the asset and its unit of measurement. These can change over time. For example:
Applying shrinkage to a silo will reduce the primary value
Exporting an asset from Australia to the US might change the primary value and unit from a metric unit to an imperial unit
Provenance data
Assets can contain arbitrary data, reflecting their diverse purposes. Data on an asset takes the form of claims and evidence.
Claims are statements of fact about an asset. For example, a canola asset may contain claims like:
Grade, or the quality of the commodity
Origin, or the location at which it was grown
Storage temperature
By themselves, claims aren't verified - the reputation of the actor who made the claim is all that exists to show that they're correct. Evidence provides a means to support claims, allowing actors to add documentation and certificates that prove or back claims. This could take the form of an organic certification from Australian Certified Organic, or a quality sensor output.
Ownership
The owner of an asset is the actor or actors who have legal title to the asset. This can be split between multiple actors proportionally (e.g. one actor has 70%, another has 30%).
The custodian of an asset is the actor who physically controls the asset. This could be different to the owner.
The manager of an asset is the owner who is delegated permission by all other owners to manage the asset, and receives full permissions on the asset.
For example, in a scenario in which a shipment of nylon is stored in a warehouse, the ownership structure might look like this:
Owners: the producer owns 60%, a bank owns 40%
Custodian: the warehouse operator (since they hold the physical asset)
Manager: the producer, since the bank is happy to delegate management of the asset
Permissions
Control of assets is managed through a permission system. Actors can be given permissions to perform subsets of available actions on assets.
Files
Actors can upload files to use as evidence on assets. Files are immutable once uploaded, and have a similar permissioning system to assets that controls who can view and use the files.
Lenses
Actors can create lenses which provide a permissioned view for a group of assets, specifying the data that a certain user type can see. Lenses can restrict what is revealed of the asset's history, such as hiding the asset's class, quantity,and which claims and evidence are visible.
Using the API {#usage}
Geora offers a GraphQL API which allows developers to build full applications on the protocol. GraphQL is a query language that is well suited to Geora's graph-like domain model.
The API provides features like:
Creating and updating assets
Managing asset data and permissions
Uploading certificates and verifying claims
It also provides a query interface to create rich queries on objects like assets, asset versions, actors, and files.
For example, the following query will retrieve a particular version of an asset and show both ownership and claims on that version:
{
asset(id: "YXNzZXR8ODczMjEyNDIzNDMyNAo=") {
latestVersion {
id
quantity {
primaryUnit
primaryValue
}
}
}
}
The response contains all the requested information:
{
"data": {
"asset": {
"latestVersion": {
"id": "YXNzZXRWZXJzaW9ufDg3MzIxMjQyMzQzMjQK",
"quantity": {
"primaryValue": 56.6,
"primaryUnit": "kg"
}
}
}
}
}
Need a hand? 🤔
Get in touch using the live chat button to the bottom right of any Geora page and you'll be connected to us in real time! 👉