Functions

The Smart Contract will have several functions that can be categorized by the calling component (which is also an indication of their purpose):

• Called by other Smart Contract functions: These functions will be for internal calcualtions and for executing ether transfers between accounts.

• Called by Microservices: These functions will be called by microservices to send sensor data received from microcontrollers to the Smart Contract.

• Called by the Web App: These functions will be called to send data to the Smart Contract that comes as human inputs (such as order creation) and to retrieve data from Smart Contracts for display on the web app.

Access restrictions can be applied to functions so that only authorized participants can call the functions. For example, in our solution, the access control modifier below is applied to all functions so only the contract owner or participants with specifically provided access can call the function.

modifier restrictedUsers() {
  require(msg.sender == owner || Participants[msg.sender].contract_access == true, "Unauthorized");
    _;
}

Functions called by other Smart Contract functions

• calculateVehiclePenalties(order_id, vehicle_location)
  This function will calculate the penalities for the Transporter if a vehicle other than the one specified in the order is sent for loading or if the vehicle is changed between loading and unloading. The vehicle_location passed will determine whether penalties are to be calculated for the loading or unloading location. This function is executed as soon as the vehicle data is received from either location.

• calculateSchedulePenalties(order_id, schedule_type)
  This function will calculate the penalties for the Seller and Transporter if departure and arrival times at loading and unloading locations are later than those specified in the order. The schedule_type passed will determine whether penalties are to be calculated for the departure time or the arrival time and who they should be applied to. This function is executed as soon as the schedule data is received from either location.

• calculateQuantityPenalties(order_id, quantity_stage)
  This function will calculate the penalties for the Seller and Transporter if the quantity of items loaded is lesser than what was stated in the order and if the quantity of items unloaded is less than loaded. The quantity_stage passed will determine whether penalties are to be calculated for the loaded quantity or the unloaded quantity and who they should be applied to. This function is executed as soon as the quantity data is received from either location.

• calculateTransportConditionPenalties(order_id)
  This function wil calculate the penalties if the transporter fails to meet the expected order parameters. All the data received and stored from the microcontrollers is used for these calculations. Since penalties are determined based on duration of variation and not single values the penalties for transport conditions can only be calculated at the end of the order process (in this scenario when the unloaded data quantity has been received). The unloaded quantity data is the last data expected so when that is received the calculateQuantityPenalties() function completes its calcualtions and then calls this function. This is the last penalty calcualation so when this function completes its calculations it calls the paymentPostPenalties() functions to complete the order process.

• paymentPostPenalties(order_id)
  The penalties incurred by each participant for all violations are added and the amounts due to the seller and transporter are calculated and transferred to the respective participants. The penalty amount is transferred to the buyer as a refund. The status of the order us changed to Completed.

Functions called by Microservices

• receiveANPRData(order_id, vehicle_regn_num, vehicle_location)
  This function is called by the microservice to send the loading and unloading vehicle registration number data from the ANPR solution to the Smart Contract. The function stores the data in the incoming_data_struct which is mapped to the order_id. Since these are values received only once and the deviation can be determined with a single value, the calculateVehiclePenalties() function is called right after the data is stored.

• receiveScheduleData(order_id, schedule_type, microcontroller_data)
  This function is called by the microservice to send the vehicle departure and arrival time from the loading and unloading microcontrollers to the Smart Contract. The function stores in the incoming_data_struct which is mapped to the order_id. Since these are values received only once and the deviation can be determined with a single value, the calculateSchedulePenalties() function is called right after the data is stored.

• receiveQuantityData(order_id, quantity_stage, microcontroller_data)
  This function is called by the microservice to send the loaded and unloaded quantities from the loading and unloading microcontrollers to the Smart Contract. The function stores in the incoming_data_struct which is mapped to the order_id. Since these are values received only once and the deviation can be determined with a single value, the calculateQuantityPenalties() function is called right after the data is stored.

• receiveTransportConditions(order_id, microcontroller_data)
  This function is called by the microservice to send the transport condition parameter values from the vehicle microcontroller to the Smart Contract. The function stores in the incoming_data_struct which is mapped to the order_id. These are received multiple times at a predefined frequency over the time from loading to unloading and stored as a mapping of values.

In this design, all the above microservices functions are called by a single microservice which is responsible for filtering and cleaning the data from the microcontrollers before sending it to the Smart Contract.

Functions called by the Web Application

• addParticipant(role, name, account_address)
  This function is used by the Add Participant function accessed by the contract owner to add the Buyer, Seller, and Transporter participants to the Smart Contract, who are uniquely identified by their account addresses. The function has a check to prevent the same participant from being added twice and to ensure two participants are not mapped to the same role.

• Participants(account_address)
  This is a "getter" function that returns participant data stored in the Participants mapping.

• createOrder(order_id, seller_address, order_payments, item, expected_arrival_timestamp, schedule_penalty_amount)
  This function is used by the Create Order page accessed by the Buyer to create an order in the Smart Contract.

• updateOrderSeller(order_id, transporter_address, order_payments, expected_parameters, expected_departure_timestamp, ANPR_penalty_amount)
  This function is used by the Update Order page accessed by the Seller to update an order in the Smart Contract.

• updateOrderTransporter(order_id, allotted_vehicle)
  This function is used by the Update Order page accessed by the Transporter to udpate an order in the Smart Contract.

• getOrderData(order_id)
  Returns the order data mapped to the order_id in the order_data mapping.

• getPenalties(order_id)
  Returns the penalties applied to each participant along with the parameter they are penalized for. This will return an array of penalties mapped to the order_id in the penalties mapping.

• getIncomingData(order_id)
  Returns all the data received from the microcontroller.