Substrate & FRAME Supply Chain Sample

*Status: *

Please use this project as an example to learn from, not to use as a basis for starting a new Substrate project intended to go to production.

This sample project demonstrates how the Substrate framework for building blockchains and its standard FRAME library for runtime development can be used to quickly build an ergonomic, end-to-end, blockchain-based application. This sample includes a custom front-end that was created from the helpful Substrate Front-End Template, which itself makes use of the powerful Polkadot{JS} API. The chain in this sample is a fork of the official Substrate Node Template - a supported starting point that decreases the time it takes to implement a custom next-generation blockchain.

The use case that this sample demonstrates is a decentralized supply-chain consortium. In order to accomplish this, FRAME is used to implement custom business logic as well as existing standards, such as decentralized identifiers (DIDs).

The capabilities demonstrated by this project include:

• Fine-grained and performance-preserving role-based access control (RBAC).
• Set-up and coordinate a decentralized network (permissioned blockchain) among several organisations.
• Manage decentralized identities for member organisations and their delegates.
• Register products and associated metadata, such as the organisation that owns them.
• Create shipments and track their journey through the supply chain.
• Monitor a shipment's storage and transportation conditions.

The sample demonstrates many features and capabilities of the Substrate framework, including:

• Consortium network with a proof-of-authority consensus (Aura for block production, GRANDPA for block finalization). Substrate and FRAME ship with a number of well-research and battle-tested consensus mechanisms and also make it possible to design and implement custom consensus mechanisms.
• Dynamic set of authority nodes.
• Role-based access control (RBAC) built on signed extensions.
• Reliable real-world data integration with off-chain workers.
• Flexible blockchain runtime development that uses FRAME pallets to encapsulate domain-specific logic (e.g. separate pallets for product registry & tracking).

Running the Demo

Follow the [installation instructions](https://substrate.dev/docs/en/knowledgebase/getting-started

This demo also uses Node.js and Yarn, so ensure that those dependencies are installed before continuing.

• Run the Substrate chain

  cd chain
  cargo build --release
  # Launch the node in development mode and do not persist chain state
  ./target/release/enterprise-sample --dev --tmp

OR

cd chain
# Launch the node in development mode and do not persist chain state
  cargo run -- --dev --tmp

• Launch the front-end

  cd ui
  yarn install && yarn start

• [Optional] Run the initialization script to bootstrap a consortium, create organizations, products, and shipments, and track the shipments from creation to delivery. Continue to the guided demo to perform these steps manually, and learn more about them in the process. The initialization script is designed to work on a newly launched chain.

  cd scripts
  yarn && yarn start

Guided Demo

This guided demo will walk through a simplified version of the steps performed by the initialization script. The demo makes use of a number of well-known development accounts. In order to understand the demo's steps, it's necessary to understand the runtime modules (pallets) that inform the supply chain application and how they relate to each other.

Project Components

The supply chain consortium application is comprised of a number of a modules, many of which are configured in the chain specification's development_config function:

• Role-Based Access Control (RBAC) pallet - This pallet maintains an on-chain registry of roles and the users to which those roles are assigned. A Role is a tuple that encapsulates the name of a pallet and a Permission that qualifies the level of access granted by the Role. A Permission is an enum with the following variants: Execute and Manage. The Execute permission allows a user to invoke a pallet's dispatchable functions. The Manage permission allows a user to assign and revoke roles for a pallet, and also implies the Execute permission. Access control validation is done at the transaction pool validation layer by way of the RBAC pallet's Authorize signed extension. Notice the permissions that are configured in the chain specification file. Alice is granted the Execute permission on the RBAC pallet, which allows her to use the RBAC pallet to create roles. In order to enable her to bootstrap the consortium, Alice is also granted the Manage permission on a few other pallet.
• Registrar pallet - The Registrar pallet inherits decentralized identifier (DID) capabilities from the DID pallet and uses these capabilities to implement an organization registry. This pallet maintains a list of organizations and maps each organization to a list of members. Organizations are identified by the ID of the account that created and owns it, which means that an account may create and own at most one organization. Organizations are associated with a name, which is designated by the value of the Org attribute on the DID of the organization owner. Organization owners are the only accounts that may add members to their organizations. When an account is added to an organization as a member, the organization owner creates an OrgMember delegate for the member's DID - this is a way for the organization owner to certify an account's membership in the organization. The registrar pallet exposes a custom origin, EnsureOrg, that validates whether or not an account owns or is a member of at least one organization. The EnsureOrg origin is used to control access to many of the chain's capabilities, including the ability to create roles with the RBAC pallet.
• Product Registry pallet - This pallet maintains a registry of products and maps each product to the organization to which it belongs. A product is defined by three required properties (an ID, an owner, and a time of creation), and may have one or more optional user-defined properties. The EnsureOrg origin is used to control the accounts that are allowed to create products.
• Product Tracking pallet - The Product Tracking pallet tracks shipments of products as they move throughout the supply chain. The EnsureOrg origin is used to control the accounts that are allowed to interact with this pallet. Shipments, like products, are assigned an ID and associated with an organization. This pallet supports tracking several types of shipping events: registration, pickup, scan, and delivery. With the exception of registration, shipment events may be associated with a list of sensor readings. Shipment events are placed in a queue that is monitored by an off-chain worker; when events appear in this queue the off-chain worker sends them to an HTTP listener.

Demo Steps

1. Navigate to the locally deployed instance of the demo UI, which should be running at http://localhost:8000/demo. Notice that the UI has an account selector that default to the Alice account. This is important due to the special permissions that were configured for Alice in the chain specification file.

   

2. Use the Members tab to create the Execute permission for three pallets: registrar, productRegistry, and productTracking.

   

3. Assign the three newly created roles to Bob, whose address is 5FHneW46xGXgs5mUiveU4sbTyGBzmstUspZC92UhjJM694ty. This will allow Bob to create an organization, products, shipments, and shipment events.

   

   Note: use this link to navigate to the Polkadot{JS} Apps UI and configure it to connect to the local supply chain network: https://polkadot.js.org/apps/#/explorer?rpc=ws://127.0.0.1:9944. Use the block hash provided by the supply chain UI to inspect the block that contained a transaction.

   

4. Use the account selector to switch to Bob's account, and then go back to the Organizations tab to create an organization.

   

5. Navigate to the Products tab and create two products.

   

6. Use the Shipments tab to create a shipment with the two products that were created in the previous step.

   

7. Navigate to the Tracking tab and use its UI to pickup, scan, and deliver the package. Note: don't try to include a sensor reading in a Scan or Deliver event due to an unresolved bug in this project.

   

   

Related Github Repositories

• Validator Set Pallet

Disclaimer

This project is intended for demonstration purposes and is not audited or ready for production use.