Skip to content

GeekyAnts/ethereum-logistics-application

Folders and files

NameName
Last commit message
Last commit date

Latest commit

 

History

6 Commits
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 

Repository files navigation

front-end-screenshot

Important Links

Logistics Delivery Application

Problem Statement

In many parts of the world, part-time jobs and freelancing are increasingly common across various sectors, including logistics and parcel delivery.

Current Scenario

Let's consider an example to illustrate the problem:

  • Person A wants to transfer a parcel from Location A to Location B.
  • Currently, Person A has to rely on established logistics companies with fixed service fees, offering no flexibility for negotiation or alternate fee options.
  • Delivery partners working for these logistics companies are bound by strict commitments, restricting their ability to take breaks or leave at will.
  • Delivery partners cannot set their own fees or choose orders based on convenience, such as picking orders closer to their home at the end of a shift.
  • Additionally, logistics companies may store and sell customer data to third parties, increasing the risk of data breaches and personal information misuse.

Issues

  • Lack of Flexibility in Service Fees: Shippers like Person A cannot negotiate or select different service fees.
  • Binding Commitments for Delivery Partners: These commitments limit the flexibility of delivery partners in managing their work schedules.
  • Inability to Choose Orders: Delivery partners lack the freedom to select orders based on their preferences or convenience.
  • Data Security Concerns: Possibility of data breaches and misuse of personal information.

Solution

We propose a blockchain-based solution with an auction system for service requests to address these issues.

How It Works

  • Service Request Creation: The shipper (Person A) creates a service request to transfer a parcel to the recipient (Person B), specifying the service fee they are willing to pay.
  • Auction System: Delivery partners can see the service request and participate in a Dutch auction, with bids hidden from each other.
  • Driverless NFT: Delivery partners need a Driverless NFT, created from a government-issued ID, to participate.
  • Bidding Process: Delivery partners place their bids and stake an insured cargo value equivalent to the item's value.
  • Selection and Allocation: The delivery partner with the lowest bid wins and is assigned the service request.
  • Delivery and Payment: Upon successful delivery, the delivery partner receives their bid amount, and any unspent portion of the service fee is refunded to the shipper.
  • Dispute Resolution: Any disputes are resolved through a voting system involving DAO members.

Benefits

  • Flexibility in Service Fees: Shippers can set their preferred service fees.
  • Autonomy for Delivery Partners: They can bid for jobs based on convenience and preferred fees.
  • Transparency and Security: Blockchain technology ensures secure and transparent transactions.
  • Data Privacy: Reduces the risk of data breaches.
  • Verification and Trust: Driverless NFTs ensure that only verified individuals can participate in the delivery process.
  • Dispute Resolution: A fair and transparent system is in place for resolving disputes.
  • Additional Incentives: Delivery partners earn tokens for successful deliveries, offering additional income opportunities.

Implementation of Logistics Delivery Application

Requirements

  • Metamask Wallet: Users need a Metamask wallet to interact with the contract.
  • User Roles: Roles include Admin, Shipper, Driver, and Receiver.
  • Driving License NFT: Required to apply for the Driver role.
  • Blockchain Network: We use the Sepolia network for our contracts.
  • User Interface: We have created a webpage with React and Redux for user interactions.

Features

  • Role Management: Users can request and approve different roles.
  • Service Request Management: Shippers can create and manage service requests.
  • Auction System: Drivers can bid on service requests.
  • Dispute Resolution: Disputes are handled through DAO voting.
  • Reward Mechanism: Drivers receive tokens for completed deliveries.

Assumptions

  • We assume users provide accurate location data and timestamps.
  • Service fees and cargo insurance values are in ETH.

How it works

logistics-delivery-application

How the Users and Roles are managed

user-flow

How the Dispute Resolution works

dispute-flow

Let's start with Smart Contracts

Do platform Setup!

Solidity

  Objects
  enum Role {
    None,
    Admin,
    Shipper,
    Driver,
    Receiver
  }

  enum RequestStatus {
    Pending,
    Approved,
    Rejected
  }

  enum Status {
    DRAFT, // Created by Shipper
    READY_FOR_AUCTION, // Updated by Shipper
    DRIVER_ASSIGNED, // Updated by System
    READY_FOR_PICKUP, // Updated by Shipper
    PARCEL_PICKED_UP, // Updated by Driver
    IN_TRANSIT, // Updated by Driver
    DELIVERED, // Updated by Driver
    CONDITIONALLY_ACCEPTED, // Updated by Receiver
    UNCONDITIONALLY_ACCEPTED, // Updated by Receiver
    CANCELLED, // Updated by Shipper (Only in DRAFT status)
    DISPUTE, // Updated by Receiver
    DISPUTE_RESOLVED // Updated by System
  }

  enum WhomToVote {
    Driver,
    Receiver,
    None
  }

  enum Acceptance {
    CONDITIONAL,
    UNCONDITIONAL
  }

  struct RoleRequest {
    uint256 requestId;
    address applicantUID;
    Role requestedRole;
    RequestStatus requestStatus;
    address approverUID; // Person who approves or rejects the request
  }

  struct User {
    string name;
    address uid;
    string phoneNumberWithISO;
    string serviceGeoHash;
    uint ratingStarsInt;
    string ratingStarsString;
    Role[] role;
  }

  /**
   * @dev For finding out role request info and it's index for updation in User Role Request contract
   */
  struct RoleRequestWithIndexDto {
    RoleRequest roleRequest;
    uint index;
  }

  struct DrivingLicenseInfo {
    string name;
    string id;
    string image;
  }

  struct DriverInfo {
    address driverUID;
    uint256 serviceFee;
    uint256 cargoInsuranceValue;
    bool cargoValueRefunded;
    bool serviceFeeRefunded;
  }

  struct BidInfo {
    address uid;
    uint256 serviceFee;
  }

  /**
   * @dev For Maintaining vote count for Driver & Receiver in case of dispute
   */
  struct VoteCount {
    uint256 driver;
    uint256 receiver;
    uint256 total;
  }

  struct SRInfo {
    uint256 requestId;
    string description;
    address shipperUID;
    address receiverUID;
    string originGeoHash; // Origin geo hash from where parcel has to be picked up
    string destGeoHash; // Destination geo hash from where parcel has to dropped
    uint256 cargoInsurableValue; // Product Value
    uint256 serviceFee; // Delivery charges that shipper is willing to pay
    uint256 requestedPickupTime; // Time at which parcel has to be picket up (In timestamp - seconds)
    uint256 requestedDeliveryTime; // Time at which parcel has to be dropped (In timestamp - seconds)
    uint256 auctionEndTime; // After how many minutes auction should end (Number - minutes)
    address driverUID; // System will update this after auction ends
    Status status;
    string disputeWinner; // empty or DRAW or DRIVER or RECEIVER
    BidInfo bidInfo;
    bool disputeVoteGiven;
  }

  /**
   * @dev For finding out SR info and it's index for updation in Dispute Service Request contract
   */
  struct SRResult {
    Types.SRInfo sr;
    uint256 index;
  }
  DrivingLicenseNFT Functions
Function Name Input Params Return value Description
publicMint() string _driverName,
string _driverLicenseNumber,
string _ipfsHash
- Mints a new token to the sender and stores the driver's information.
validateNFT() address _addr bool Validates if the address owns a valid NFT.
getDriverLicenseInfoByTokenId() uint256 _tokenId DrivingLicenseInfo Retrieves the driver's information by token ID.
burn() uint256 _tokenId - Burns the token.
  User Functions
Function Name Input Params Return value Description
createUser() string _name,
string _geoHash
- Creates a new user.
createRoleRequest() Role _requestedRole - Creates a new role request.
approveOrRejectRoleRequest() uint256 _roleRequestId,
bool _approve
- Approves or rejects a role request.
getAllRoleRequests() - RoleRequest[] Retrieves all role requests.
getMyRoleRequests() - RoleRequest[] Retrieves role requests for the caller.
getRoleRequestsInMyRegion() - RoleRequest[] Retrieves role requests in the caller's region.
getUserGeoHash() address _uid string Retrieves serviceGeoHash for a user.
isUserRegistered() address _userAddr - Checks if a user is registered.
createSRRoleCheck() address _shipper,
address _receiverUID,
string _receiverName,
string _receiverGeoHash,
string _phoneNumberWithISO
- Checks if the shipper and receiver exist and assigns the Receiver role if not already assigned; also checks if the Shipper has the required role.
hasRoleShipper() address _addr - Checks if a user is a Shipper.
hasRoleDriver() address _addr - Checks if a user is a Driver.
hasRoleReceiver() address _addr - Checks if a user is a Receiver.
isAdmin() address _addr - Checks if a user is an Admin.
deductStars() address _addr - Deducts stars from a Driver's rating.
getUserInfo() address _addr "User" object Returns user details for the provided UID
updateUserInfo() string _name,
string _geoHash,
string _phoneNumberWithISO
"User" object Update the basic user details & returns back the updated object
  Dispute Functions
Function Name Input Params Return value Description
vote() uint256 _srId,
WhomToVote _whomToVote
- Allows a user to vote on a disputed service request
getAllDisputedSRInDriverArea() - SRInfo[] Retrieves all disputed service requests in the driver's service area
  Service Request Functions
Function Name Input Params Return value Description
createNewSR() SRInfo _srInfo,
string _receiverPhoneNoWithISO
- Creates a new service request and adds it to the state variable srInfos
editDraftSR() string _requestId,
Status _newStatus,
uint256 _requestedPickupTime,
uint256 _requestedDeliveryTime,
uint256 _auctionEndTime
- Edits an existing draft service request
cancelSR() string _requestId - Cancels a service request if it is in draft mode
dutchBid() string _requestId,
uint256 _serviceFee
- Places a dutch bid on a service request
declareWinner() string _requestId - Declares the winner of an auction for a service request
updateSRStatus() string _requestId,
Status _newStatus
- Updates the status of a service request
getAuctionSRListinDriverRegion() - SRInfo[] Retrieves all service requests in the driver's region that are ready for auction
getAllSRs() - SRInfo[] Retrieves all service requests, Admin can only call this method
getMySRs() - SRInfo[] Retrieves all service requests that are specific to requestor
decideWinnerForDispute() string _requestId - Decides the winner of a dispute for a service request
  Events
Event Name Params Description
TransferedTokens address _from,
address _to,
uint256 _tokens
Triggers when tokens are transferred
NewUserAdded string _name,
address _uid,
string _serviceGeoHash
Triggers when a new user is added
NewRoleRequestAdded uint256 _requestId,
address _applicantUID,
Role _requestedRole
Triggers when a new role request is added
NewSRInDisputeSystem address _from,
uint256 _srId,
SRInfo _srInfo
Triggers when a new service request is added to the dispute system
NewVoteAdded uint256 _srId,
string message
Triggers when a new vote is added to a disputed service request
NewSRAdded SRInfo _srInfo,
address _creator,
string message
Triggers when a new service request is added
SRUpdated SRInfo _srInfo,
address _creator,
string message
Triggers when a service request is updated
SRCancelled string _requestId,
address _canceller,
string message
Triggers when a service request is cancelled
NewBidEntry string _requestId,
address _bidder,
uint256 _serviceFee
Triggers when a new bid is placed on a service request
AuctionResults string _requestId,
address _winner,
string message
Triggers when the auction for a service request has a winner
DisputedSRResult string _requestId,
string message
Triggers when a dispute resolution result is declared
  Errors
Error Name Params Description
AccessDenied address from, string message Triggers when access is denied
NotAuthorized address uid, string message Triggers when a user is not authorized to perform an action
InvalidInput address uid, string message Triggers when the input is invalid
NotSufficientFunds address account, string message Triggers when the account does not have sufficient funds
OnlyDisputedSRCanBeAdded address from, Types.SRInfo srInfo Triggers when a service request is not in dispute
AlreadyVoted uint256 srId, string message Triggers when a user has already
VotingEndedAlready uint256 srId, string message Triggers when voting has already ended
SelfVoteNotAllowed uint256 srId, string message Triggers when a user tries to vote for themselves
VotingInProgress address from, uint256 srId, string message Triggers when voting is in progress
InvalidDLInput string name, string value, string message Triggers when the input for a driving license is invalid
PublicMintError string name, string id, string image, string message Triggers when there is an error in minting a public token
InternalMintError address from, address to, string message Triggers when there is an internal error in minting a token
DLInfoNotFound uint256 tokenId, string message Triggers when the driving license information is not found
OwnerUnauthorized uint256 tokenId, string message Triggers when the owner is unauthorized to perform an action
NFTNotFound address uid, string message Triggers when an NFT is not found
UserNotRegistered address uid, string message Triggers when a user is not registered
UserAlreadyExists address uid, string message Triggers when a user already exists
RequestAlreadyProcessed address uid, string message, uint256 requestId Triggers when a role request has already been processed
InvalidSRStatus Types.Status status, string message Triggers when the status of a service request is invalid
InvalidValue string value, string message Triggers when the value is invalid
InvalidGeoHash string geoHash, string message Triggers when the geo hash is invalid
InvalidProductValue uint256 value, string message Triggers when the product value is invalid
InvalidAuctionTime uint256 timestamp, string message Triggers when the auction time is invalid
SRDoesNotExists uint256 srId, string message Triggers when a service request does not exist
SRCannotBeUpdated uint256 srId, string message Triggers when a service request cannot be updated
SRAccessDenied uint256 srId, string message Triggers when access is denied for a service request
SRCannotBeCancelled uint256 srId, string message Triggers when a service request cannot be cancelled
AuctionNotStarted uint256 srId, string message Triggers when the auction has not started for a service request
AuctionEnded uint256 srId, string message Triggers when the auction has ended for a service request
SROutOfRegion uint256 srId, string message Triggers when a service request is out of the driver's region
AlreadyBidded address bidder, string message Triggers when a user has already placed a bid
AuctionInProgress uint256 srId, string message Triggers when the auction is in progress for a service request
SRDisputeAlreadyResolved uint256 srId, string message Triggers when a dispute for a service request has already been resolved
  Versions
  • Compiler: solc: v0.8.24+commit.e11b9ed9
  • Truffle: v5.11.5
  • Hardhat: v2.22.4
  • Node: v18.16.1 (or above)

Quick Start

  • Navigate inside the project

    cd logistics-project/blockchain
  • Install the dependencies

    npm install
  • Update the Metamask Pass phrase in hardhat.config.js file at hardhat.accounts.mnemonic

  • Start the hardhat Node

    npm start
  • Open new Terminal at same path & Compile the contracts

    npm run compile
  • Deploy to localhost/hardhat

    _Note depending on hardhat node port number, you need to change in hardhat config file

    npm run deploy:reset
  • Add Hardhat as a network in the Metamask by following this link, You can Navigate to Step-5 in the guide directly.

Team ✨

Meet the amazing team who developed this project.


Suresh Konakanchi

💻 📖 🚧

Anuj Singh

💻 📖 🚧

Pallab Singha

💻 📖 🚧

Arpit Kumar

💻 📖 🚧

Mohamed Farhan S

💻 📖 🚧

How frontend works

  Service Requests

user-flow

user-flow

  Dispute, Auction Flows

user-flow

user-flow

user-flow

user-flow

  Profile & NFT Flows

user-flow

user-flow

user-flow

About

No description, website, or topics provided.

Resources

License

Stars

Watchers

Forks

Releases

No releases published

Packages

No packages published