Contract: Create Basic Shipment Smart Contract Structure #505
Description
Description:
Create the foundational smart contract structure for managing shipments on the blockchain. This contract will serve as the base for recording shipment lifecycle events immutably on-chain.
Target Blockchain: Starknet or Soroban (specify which based on project direction)
Contract Purpose:
This contract will store essential shipment information on the blockchain to provide transparency and immutability for freight operations.
Core Functionality to Implement:
1. Data Structures
Define the following structs/types:
- Shipment: Contains shipment_id, shipper_address, carrier_address, origin, destination, cargo_type, status, created_at, updated_at
- ShipmentStatus: Enum with variants: Created, Assigned, InTransit, Delivered, Cancelled
- Location: Struct with latitude, longitude, timestamp
2. Storage
- Map of shipment_id to Shipment data
- Counter for total shipments created
- Map of user addresses to their shipment IDs (for querying user's shipments)
3. Functions to Implement
Create Shipment:
- Takes parameters: shipper_address, origin, destination, cargo_type
- Generates unique shipment_id
- Initializes shipment with Created status
- Stores in contract storage
- Emits ShipmentCreated event
- Returns shipment_id
Get Shipment:
- Takes shipment_id as parameter
- Returns complete Shipment struct
- Handle case when shipment doesn't exist
Update Status:
- Takes shipment_id and new status
- Validates status transition is valid (Created → Assigned → InTransit → Delivered)
- Updates shipment status and updated_at timestamp
- Emits StatusUpdated event
- Only authorized addresses can update (shipper or carrier)
Assign Carrier:
- Takes shipment_id and carrier_address
- Updates carrier_address in shipment
- Changes status to Assigned
- Emits CarrierAssigned event
- Only shipper can assign carrier
4. Events to Define
- ShipmentCreated(shipment_id, shipper_address, timestamp)
- StatusUpdated(shipment_id, old_status, new_status, timestamp)
- CarrierAssigned(shipment_id, carrier_address, timestamp)
5. Access Control
- Only the shipper can create and assign carriers
- Only the assigned carrier can update status to InTransit and Delivered
- Anyone can read shipment data (public getter)
File Structure:
contracts/
├── src/
│ ├── lib.rs (main contract)
│ ├── types.rs (data structures)
│ ├── storage.rs (storage definitions)
│ └── errors.rs (error definitions)
├── tests/
│ └── shipment_tests.rs
└── Cargo.toml
Acceptance Criteria:
- All data structures properly defined with correct types
- Create shipment function works and increments counter
- Get shipment returns correct data
- Status updates follow proper workflow (can't skip states)
- Carrier assignment restricted to shipper only
- Status updates restricted to authorized parties
- All events emit correctly with proper parameters
- Unit tests cover all functions (minimum 80% coverage)
- Error handling for invalid inputs
- Documentation comments on all public functions
- Contract compiles without warnings
- Gas optimization considered (minimal storage writes)
Testing Requirements:
Write tests for:
- Creating a shipment successfully
- Getting shipment by ID
- Attempting to get non-existent shipment (should error)
- Updating status in correct sequence
- Attempting invalid status transitions (should fail)
- Assigning carrier by authorized user
- Attempting to assign carrier by unauthorized user (should fail)
- All event emissions