Building with Hyperledger Grid
A developer's guide to building distributed supply chain solutions
Learn how to leverage Hyperledger Grid's framework and components to create efficient, transparent, and interoperable supply chain applications.
In This Guide
What is Hyperledger Grid?
A framework for building distributed supply chain solutions
Supply Chain Focus
Hyperledger Grid is specifically designed for building supply chain applications. It provides a set of tools, libraries, and data models that address common supply chain challenges, such as track and trace, inventory management, and data sharing.
Why Use Grid?
Developers choose Grid for its modularity, flexibility, and focus on supply chain use cases. It provides pre-built components and data models that accelerate development. Grid supports multiple underlying blockchain platforms (Sawtooth, Fabric) and uses WebAssembly for smart contracts.
Architecture & Components
Key components include: *Grid Daemon (gridd):* The core process that handles requests and interacts with the underlying blockchain. *Grid SDK:* Provides libraries for building applications. *Smart Contract SDKs:* Rust SDK. *Grid CLI:* Command-line interface for interacting with Grid. *Pre-built Smart Contracts:* For common functions like track and trace, Pike (identity), and product management.* Data Models & Schemas:* Standardized ways to represent supply chain data.
Open Source & Community
Grid is an open-source project under the Hyperledger umbrella, with a growing community of developers and contributors. Collaboration and community feedback drive further development and adoption.
Understanding Grid's Architecture
The technical components of Hyperledger Grid
Key Grid Components
Exploring the core functionalities of Hyperledger Grid
Grid Track and Trace
Provides functionality for tracking the location and status of assets as they move through the supply chain. It uses a standardized data model to represent events and locations. This allows for building applications that can track products from origin to consumer.
Grid Pike
Pike is Grid's smart contract for managing organizations, agents, and roles. It provides a foundation for identity and permissions management within a Grid application. Pike allows you to define: *Organizations:* Entities participating in the supply chain. *Agents:* Users or systems that act on behalf of organizations. *Roles:* Permissions and responsibilities within the network.
Grid Product
Provides functionality for managing product information. It uses a standardized schema to represent products and their attributes. This allows for consistent representation of product data across different applications and organizations.
Grid Schema
Provides a mechanism for defining and managing data schemas. Schemas define the structure and format of data stored on the ledger. This ensures data consistency and interoperability between different applications. Grid uses a flexible schema format that allows for defining complex data types.
Grid Location
Provides functionality for managing and sharing location based data that can be referenced with track and trace and other smart contracts.
Grid Workflow
(Deprecated in later versions) Grid Workflow was a component for managing business processes. It's usage now deprecated and its functionality is to be handled by custom smart contracts.
Grid Daemon (gridd)
As covered previously, this is central to the running of Grid, handling transactions, interacting with the underling blockchain, and offering the REST API.
Grid Data Model
Understanding how data is structured and represented in Hyperledger Grid
Schemas
Grid uses schemas to define the structure and format of data stored on the ledger. Schemas are defined using a flexible and extensible format that allows for defining complex data types. Using schemas ensures data consistency and interoperability between applications
Properties
Schemas are composed of properties, each defines a name, a data type, and additional attributes.
Data Types
Grid supports a variety of data types, including : *String* *Integer* *Boolean* *Bytes* *Enumerated* *Struct*, and more, enabling a flexible representation of the data required.
GS1 Standards
Grid's data model is designed to be compatible with GS1 standards, which are widely used in the supply chain industry. This allows for seamless integration with existing GS1-based systems. Grid schemas often map to GS1 data definitions.
Extensibility
The Grid data model is extensible, allowing you to define your own custom schemas and properties to meet the specific needs of your application. You can build upon the existing Grid schemas or create entirely new ones.
Schema Management
Grid provides mechanisms for managing schemas, You can create, update, and delete schemas using the Grid CLI or the Grid SDK. Managing the schema, including versioning, is handled through smart contracts.
Example: Product Schema
The Grid Product smart contract uses a schema that might include properties like: *`product_id` (String):* A unique identifier for the product (e.g., GTIN). *`name` (String):* The name of the product. *`description` (String):* A description of the product. *`owner` (String):* The organization that owns the product. *`properties` (Struct):* A set of custom properties that describe the product.
Developing Grid Smart Contracts
Building custom logic with Rust and WebAssembly
Using the Grid SDK
Building client applications to interact with your Grid network
Rust SDK
Currently, Hyperledger Grid provides a Rust SDK to interact with Grid nodes via the `gridd` REST API. The SDK simplifies tasks like submitting transactions, querying state, and handling events.
Connecting to gridd
Your application uses the Grid SDK to connect to a Grid node (`gridd`). You provide the URL of the `gridd` REST API endpoint.
Submitting Transactions
To submit a transaction, your application uses the SDK to: *Create a transaction payload (data specific to the smart contract function).* *Create a transaction header.* *Sign the transaction with the user's private key.* *Submit the transaction to the `gridd` REST API.*
Querying State
Your application can use the SDK to query the state (data on the ledger). You can: *Retrieve data by key.* *List data based on a prefix.* *Use filters to retrieve specific data. The SDK provides functions for making these queries and parsing the results.
Handling Events
Your application can subscribe to events emitted by smart contracts or by the Grid daemon. This allows your application to react to changes in the state in real time. The SDK provides event listeners for different types of events. The events are provided via a websocket connection.
Asynchronous Operations
Many SDK operations are asynchronous. This is more evident in javascript, but needs considering with Rust. You need to handle the asynchronous nature of these operations appropriately.
Example: Submitting a Track and Trace Transaction
Using the SDK, you would: 1. Create a transaction payload containing the location and status of the asset. 2. Create a transaction header. 3. Sign the transaction. 4. Submit the transaction to `gridd`. 5. (Optionally) Listen for events to confirm that the transaction has been committed.
Permissions in Grid
Managing access control and authorization within your Grid application
Pike Smart Contract
Grid uses the Pike smart contract for managing organizations, agents, and roles. Pike provides a foundation for identity and permissions management. You can define roles and assign them to agents, controlling their access to specific smart contract functions.
Roles and Permissions
Roles define the permissions and responsibilities of agents within a Grid application. For example, you might have roles like `admin`, `recorder`, or `viewer`. Permissions are defined at the smart contract level, specifying which roles can execute specific functions.
Agent Authorization
When a transaction is submitted, the Grid daemon verifies the identity of the transaction submitter (the agent) and checks their permissions. The agent's identity is determined from the public key used to sign the transaction. The Pike smart contract is used to determine the agent's roles and permissions.
Integrating with External Identity Providers
While Pike provides a built-in identity management solution, Grid could integrate with an external identity provider (e.g., LDAP, OAuth) if necessary. This would likely be implemented at the `gridd` level by customizing the authorization logic.
Smart Contract-Level Permissions
Within your smart contracts, you can implement custom permission checks based on the agent's roles or attributes. For example, you might restrict access to certain functions based on the agent's organization or role. The transaction context contains the signer's public key, which can be checked against Pike.
Example Permissions Structure
An example permissions structure in Pike could have. Organizations -> Agents -> Roles. Roles would have permissions, to invoke x,y,z smart contract action. Permissions can be assigned at various levels of granularity.
Installation and Setup
Setting up your Hyperledger Grid development environment
Prerequisites
Before installing Grid, you need: *Operating System:* Linux, macOS, or Windows (with WSL2). *Rust:* The Rust programming language (including Cargo, the package manager) is required for building Grid and developing smart contracts. *Docker and Docker Compose:* Required for running Grid and its dependencies in containers. *Protobuf compiler and libraries*. *CMake*.
Installing Grid (from source)
The recommended way to install Grid is to build it from source. Clone the Grid repository from GitHub: `git clone https://github.com/hyperledger/grid.git` Follow the build instructions in the Grid repository's README file. This typically involves using `cargo build` to build the Grid components.
Installing pre-built components
Pre-built components are sometimes made available. Consult the Hyperledger Grid releases and documentation to check for availability and usage.
Running Grid (Docker Compose)
Grid provides Docker Compose files that make it easy to run a Grid node and its dependencies (e.g., Sawtooth or Fabric) in containers. The Docker Compose files are typically included in the Grid repository or example projects. Use `docker-compose up` to start the Grid environment.
Configuration (gridd)
The Grid daemon (`gridd`) is configured using a TOML configuration file. You can specify settings such as: *The REST API endpoint.* *The connection to the underlying blockchain (Sawtooth or Fabric).* *The storage backend.* *Security settings.* The configuration file allows you to customize the behavior of the Grid daemon.
Setting up Sawtooth or Fabric
If you're using Sawtooth as the underlying blockchain, you'll need to set up a Sawtooth network. If you're using Fabric, you'll need a Fabric network. Grid provides examples and documentation for setting up both Sawtooth and Fabric.
Installing the Grid CLI
The Grid CLI is often built as part of building Grid from source. The `grid` command-line tool allows you to submit transactions, query data, and manage your Grid node.
Testing & Deployment
Validating and deploying your Hyperledger Grid applications
Security Best Practices
Protecting your Hyperledger Grid applications
Secure Your Infrastructure
Ensure that the infrastructure on which your Grid application runs is secure. This includes securing the operating systems, networks, and physical servers. Follow security best practices for your infrastructure environment.
Smart Contract Security
When writing Grid smart contracts, follow secure coding practices. Validate all inputs, handle errors properly, and avoid common vulnerabilities. Review and test your smart contracts thoroughly. Consider conducting security audits.
Key Management
Securely manage the private keys used by your application and users. Never store private keys in plain text. Use secure key management solutions, such as hardware security modules (HSMs) or key management services.
Access Control (Pike)
Use the Pike smart contract to implement access control and authorization within your Grid application. Define roles and permissions to restrict access to sensitive operations and data. Regularly review and update your access control policies.
Network Security
Secure your Grid network by: *Using TLS for all communication between components.* *Restricting access to the Grid daemon's REST API.* *Using firewalls to protect your network.* *Monitoring your network for any suspicious activity.*
Data Confidentiality (Splinter)
If you need enhanced data confidentiality, consider using Splinter as a private networking layer for your Grid application. Splinter provides circuit-based communication, which can help protect sensitive data from unauthorized access.
Keep Software Updated
Regularly update your Grid components (Grid daemon, SDKs, smart contract SDKs) and dependencies to the latest versions. New releases often include security patches and bug fixes. Subscribe to security announcements for Hyperledger Grid.
Auditing
Consider undergoing security audits that focus on the smart contracts and overall infrastructure setup. These audits can identify vulnerabilities that may be missed by internal testing.
Hyperledger Grid Use Cases
Exploring supply chain scenarios where Grid excels
Future of Hyperledger Grid
Upcoming developments and roadmap for the project
Frequently Asked Questions
Common questions about developing with Hyperledger Grid
Additional Resources
Essential links and tools for Hyperledger Grid developers
Hyperledger Grid Documentation
Official documentation for Hyperledger Grid.
Hyperledger Grid GitHub
Source code repository for Hyperledger Grid.
Hyperledger Wiki
Wiki pages for Hyperledger projects, including Grid.
Hyperledger Discord
Discord server for Hyperledger projects, including channels for Grid.
Hyperledger Sawtooth Documentation
Documentation for Hyperledger Sawtooth, one of the supported platforms for Grid.
Hyperledger Fabric Documentation
Documentation of Hyperledger Fabric, one of the supported platforms for Grid.
Ready to Build with Hyperledger Grid?
Take the next steps in your supply chain blockchain development journey