Grid Location Smart Contract Specification
Overview
Grid Location is a smart contract designed to run with the Sawtooth Sabre smart contract engine.
Grid Location is designed to supply Hyperledger Grid with a generic and extendable framework for storing and managing location entities. Grid Location offers explicit support for locations defined using the GS1 data standard, but is also designed to be flexible enough to support other standards.
Grid Location uses the Pike smart contract to manage location create, update, and delete permissions, as well as the organizations that own each location, and uses the Schema smart contract to describe the requirements for location entities.
State
All Grid Location objects are serialized using Protocol Buffers before being stored in state. These objects include Location, LocationList, and PropertyValue.
Location
A location is an arbitrary list of properties that is uniquely identified by a
location_id
. The properties
are described by a schema that was previously
defined using the Schema smart contract. The schema that the location will be
checked against is dictated by the Location’s namespace
field.
Currently, only the GS1
namespace has been defined.
A location has four fields
- location_id: A unique identifier for the location. For the GS1 namespace the location_id is a Global Location Number or GLN.
- namespace: The namespace that the location belongs to. A location’s namespace
dictates the rules for defining its
location_id
and the properties belonging to the location. Currently only the GS1 namespace is defined. - owner: The Pike organization ID of the organization that owns the location.
- properties: An arbitrary list of properties that describe the location. These properties are defined by a schema defined by the Schema smart contract.
message Location {
enum LocationNamespace {
UNSET_TYPE = 0;
GS1 = 1;
}
// Global Location Number as defined by GS1 specification
string location_id = 1;
LocationNamespace namespace = 2;
// Who owns this product (pike organization id)
string owner = 3;
// Addition attributes for custom configurations
repeated PropertyValue properties = 4;
}
Location List
Locations whose addresses collide are stored in a location list. A location list contains only one field.
message LocationList {
repeated Location entries = 1;
}
Addressing for GS1 locations
In order to uniquely locate GS1 locations in the Merkle-Radix state system, an address must be constructed which identifies the storage location of the Grid Location representation.
All Grid addresses are prefixed by the 6-hex-character namespace prefix “621dee”. Locations are further prefixed under the Grid namespace with reserved enumerations of “04” indicating Locations. (“01” = Schema, “02” = Product, and “03” = Product Catalog.) An additional “01” indicates “GS1 Locations”.
Therefore, all addresses starting with “621dee” + “04” are Grid locations, and more specifically, all addresses starting with “621dee” + “04” + “01” are Grid GS1 Locations identified by a GLN.
The GLN format consists of a 13-digit “numeric string” that follows a similar structure to GTIN-13. The GLN structure first includes a GS1 Company Prefix which is 7-10 digits in length and is assigned by a GS1 Member Organization. A location Reference number follows which is 2-5 digits in length and is allocated by the company to a location or party. Lastly, a single digit Check Digit is calculated and applied according to a GS1 algorithm. See GLN Data Format.
After the 10-hex-characters that are consumed by the grid namespace prefix, the location, and GS1 prefixes, there are 60 hex characters remaining in the address. The 13 digits of the GLN can be left padded with 45-hex-character zeroes and right padded with 2-hex-character zeroes to accommodate potential future storage associated with the GS1 Location representation, for example:
"621dee" + "04" + "01" + "000000000000000000000000000000000000000000000" +
13-character "numeric string" location_id + "00" // location_id == GLN
A full GS1 Location address (for example purposes) would therefore be:
"621dee0401000000000000000000000000000000000000000000000123456789012800"
Transaction Payload
Location Payload Transaction
LocationPayload
contains an action enum and the associated action payload. This
allows for the action payload to be dispatched to the appropriate logic.
Only the defined actions are available and only one action payload should be
defined in the LocationPayload
.
message LocationPayload {
enum Actions {
UNSET_ACTION = 0;
LOCATION_CREATE = 1;
LOCATION_UPDATE = 2;
LOCATION_DELETE = 3;
}
Action action = 1;
// Approximately when transaction was submitted, as a Unix UTC timestamp
uint64 timestamp = 2;
LocationCreateAction location_create = 3;
LocationUpdateAction location_update = 4;
LocationDeleteAction location_delete = 5;
}
message LocationCreateAction {
Location.LocationNamespace location_namespace = 1;
string location_id = 2;
string owner = 3;
repeated PropertyValue properties = 4;
}
message LocationUpdateAction {
// Not modified. Only used to find location object in state
Location.LocationNamespace location_namespace = 1;
// Not modified. Only used to find location object in state
string location_id = 2;
// This will replace all properties currently defined
repeated PropertyValue properties = 3;
}
message LocationDeleteAction {
// Not modified. Only used to find location object in state
Location.LocationNamespace location_namespace = 1;
// Not modified. Only used to find location object in state
string location_id = 2;
}
Location Create Action
LocationCreateAction
adds a new location to state. The transaction should be
submitted by an agent, which is identified by its signing key, acting on behalf
of the organization that corresponds to the owner in the create transaction.
(Organizations and agents are defined by the Pike smart contract.)
Validation requirements:
- If a location with
location_id
already exists the transaction is invalid. - The signer of the transaction must be an agent in the Pike state and must belong to an organization in Pike state, otherwise the transaction is invalid.
- The owner in the location must match the organization that the agent belongs to, otherwise the transaction is invalid.
- The agent must have the permission
can_create_location
for the organization, otherwise the transaction is invalid. - If the location namespace is
GS1
, the organization must contain a GS1 Company Prefix in its metadata (gs1_company_prefixes
), and the prefix must match the company prefix in thelocation_id
, which is a GLN if GS1, otherwise the transaction is invalid. - The properties must be valid for the location namespace. For example, if the location is GS1 location, its properties must only contain properties that are included in the GS1 Schema. If it includes a property not in the GS1 Schema the transaction is invalid.
If all requirements are met, the transaction will be accepted and the location will be created in state.
Location Update Action
LocationUpdateAction
updates an existing location in state. The transaction
should be submitted by an agent, identified by its signing key, acting on behalf
of an organization that corresponds to the owner in the location being updated.
(Organizations and agents are defined by the Pike smart contract.)
Validation requirements:
- If a location with
location_id
does not exist the transaction is invalid. - The signer of the transaction must be an agent in the Pike state and must belong to an organization in Pike state, otherwise the transaction is invalid.
- The owner in the location must match the organization that the agent belongs to, otherwise the transaction is invalid.
- The agent must have the permission
can_update_location
for the organization, otherwise the transaction is invalid. - The new properties must be valid for the location namespace. For example, if the location is a GS1 location, its properties must only contain properties that are included in the GS1 Schema. If it includes a property not in the GS1 Schema the transaction is invalid.
The properties in the location will be swapped for the new properties and the updated location will be set in state.
Location Delete Action
LocationDeleteAction
removes an existing location from state. The transaction
should be submitted by an agent, identified by its signing key, acting on behalf
of the organization that corresponds to the owner in the location being updated.
(Organizations and agents are defined by the Pike smart contract.)
Validation requirements:
- If a location with
location_id
does not exist the transaction is invalid. - The signer of the transaction must be an agent in the Pike state and must belong to an organization in Pike state, otherwise the transaction is invalid.
- The owner in the location must match the organization that the agent belongs to, otherwise the transaction is invalid.
- The agent must have the permission
can_delete_location
for the organization otherwise the transaction is invalid.
Inputs and Outputs
Location Create Action
The inputs for LocationCreateAction
must include:
- Grid address of the Agent submitting the transaction
- Grid address of the Organization the Location is being created for
- Grid address of the Location Namespace Schema the location’s properties must match
- Grid address of the Location to be created
The outputs for LocationCreateAction
must include:
- Grid address of the Location created
Location Update Action
The inputs for LocationUpdateAction
must include:
- Grid address of the Agent submitting the transaction
- Grid address of the Organization the Location is being updated for
- Grid address of the Location Namespace Schema the location’s properties must match
- Grid address of the Location to be updated
The outputs for LocationUpdateAction
must include:
- Grid address of the Location updated
Location Delete Action
The inputs for LocationDeleteAction
must include:
- Grid address of the Agent submitting the transaction
- Grid address of the Organization the Location is being deleted for Grid address of the Location to be deleted
The outputs for LocationDeleteAction
must include:
- Grid address of the Location to be deleted
Dependencies
The Location smart contract requires the Pike smart contract for permission and organization management, and the Schema smart contract for defining location schemas.
Family
- family_name: “grid_location”
- family_version: “1.0”