Fibers - Shipment tracking system powered by blockchain and zero-knowledge proofs (PoC)

Setup for local demo environment

• Clone four repositories (node, tracker, ui and navigator)

  1. Node: git clone https://github.com/aleksandar-veljkovic/fibers-node
  2. Tracker: git clone https://github.com/aleksandar-veljkovic/fibers-tracker
  3. UI Panel: git clone https://github.com/aleksandar-veljkovic/fibers-ui
  4. Navigator: git clone https://github.com/aleksandar-veljkovic/fibers-navigator

• Deploying smart contract

  1. Start Ganache service on 127.0.0.1:8545
  2. Run npx hardhat run --network localhost scripts/deploy.js to deploy fibers smart contract

• Whitelisting users

  1. Run npx hardhat run --network localhost scripts/whitelist-local.js

• Running tracker service

  1. In tracker directory, install depentencies using npm install and
  2. start service npm start. The service is running on http://127.0.0.1:2992

• Running nodes

  1. Make sure that no *.sqlite files are found in the node directory
  2. In the node directory, install depentencies using npm install and
  3. Start node 1 as node index.js DEVELOPMENT node1 in one terminal
  4. Start node 2 as node index.js DEVELOPMENT node2 in different terminal

• Running UI

  1. In ui directory, install depentencies using npm install and
  2. Start UI using npm start command
  3. Open the same address http://localhost:3000 in two different browser windows
  4. In one window, select Node 1 from the login form and use credentials: admin, admin
  5. In the other window, select Node 2 from the login form and use credentials: admin, admin

• Running navigator

  1. In ui directory, install depentencies using npm install and
  2. Build UI using npm run build command
  3. Serve UI using npx serve build -l 12345 on port 12345
  4. Open browser tab and open the app running on http://localhost:12345

Demo flow

• Creating shipment AB-123

  1. In UI interface connected with the Node 1 select Sent shipments tab and click on the + Register Sent shipment button.
  2. In the form input
     • Shipment Label: AB-123
     • Receiving company: AirCargo
     • Receiving department: Port of Sydney
     • Leave the current date for the shipment date
     • Shipment mass: 500
  3. Click on the Register Shipment button and wait for the shipment to be created. It might take a few seconds, as the ZK proof for shipment label hash is being generated

• Editing shipment items and publishing the shipment

  1. Select the newly created shipment by clicking on the View button in the table row
  2. On the right side of the edit page, click on the Edit button to modify the shipment items list
  3. Input values
     • Item ID: PKG1
     • Unit: Unit
     • Quantity: 1
  4. Click on the + button to confirm the input and click on the Confirm button to save the list of items
  5. Click on the Publish button to publish the shipment on Blockchain. This may take a while.

• Confirming the received shipment

  1. In the other browser window, connected to the Node 2, you should be able to see new notification (generated by the blockchain event), notifying the user that a new shipment has been registered. Click on the View button to display the shipment details
  2. In the Received mass field input the sent mass quantity (500).
  3. Click on the Save button to save the changes
  4. Click on the Confirm button to submit the confirmation on Blockchain. This may take while, as the ZK proof of items list is being generated
  5. Once the shipment confirmation is complete, the app connected to Node 1 should display notification that the shipment is now confirmed.

• Forwarding the shipment AB-123 in a new shipment labeled as CD-456

  1. In the browser window connected to Node 2, open the Sent shipments tab and click on the + Register Sent Shipment button.
  2. In the form, input:
     • Shipment label: CD-456
     • Receiving company: World Shop
     • Receiving department: Belgrade Warehouse
     • Leave the shipment date as current date
     • Shipment mass: 500
  3. Wait for the shipment to become created and click on the View button to view the shipment details
  4. In the edit page, select Edit button to edit the items list
  5. Input item data:
     • Item ID: AB-123
     • Unit: Unit
     • Quantity: 1
  6. Click on the + button to confirm the input and click on the Confirm button to save changes made to the items list.
  7. Click on the Publish button to publish the shipment.
  8. Once the shipment is published, go to the browser tab running the Navigator app.

• Querying the shipment data as an external user

  1. In the Navigator UI, type AB-123 in the input field and click on the Search button
  2. The UI will ask the tracker node about the AB-123 item/shipment and the tracker will ask the network nodes about the shipment. The nodes will respond with shipment label hashes stored on Blockchain and ZK proofs. There are two possible ZK proofs that could be returned from the node. If the shipment with the ID is found in the database, the node will return ZK proof that the shipment label hash (combined with random salt) is indeed stored on chain together with other shipment details. If the item with the requested ID is found in database, the node will respond with an inclusion proof, proving that the ID is indeed found in the claimed shipment but without revealing any other item from the shipment.
  3. UI will display:
     • Shipment history,
     • Green border and arrow around the Confirmed shipment
     • Sent and received hashes, that could be used in the reconciliation process, together with sent and received mass values
     • Map displaying the locations of departments through which the shipment has passed.
  4. The first shipment card contains information about the SHIPMENT AB-123 and the second one contains the information about the SHIPMENT CD-345 which contains the ITEM AB-123 - a shipment stored within the other shipment.