Contract: Implement Simple Dispute Resolution Contract #512
Description
Description:
Build a smart contract that manages disputes between shippers and carriers, allowing evidence submission and resolution by designated arbitrators.
Contract Purpose:
Provide a transparent, on-chain dispute resolution mechanism where parties can raise disputes, submit evidence, and have arbitrators make binding decisions.
Core Functionality to Implement:
1. Data Structures
Dispute:
- dispute_id (unique identifier)
- shipment_id (reference to disputed shipment)
- plaintiff_address (who raised the dispute)
- defendant_address (the other party)
- dispute_type (enum)
- reason_hash (hash of detailed reason, stored off-chain)
- status (enum: Open, UnderReview, Resolved, Closed)
- created_at (timestamp)
- deadline (timestamp for evidence submission)
- resolution_timestamp (when resolved)
- arbitrator_address (assigned arbitrator)
- resolution (enum: FavorPlaintiff, FavorDefendant, Split)
- resolution_notes_hash (hash of arbitrator's decision notes)
DisputeType Enum:
- NonDelivery (shipment not delivered)
- LateDelivery (delivered after agreed date)
- DamagedCargo (cargo received damaged)
- WrongLocation (delivered to wrong place)
- UnauthorizedCharges (unexpected fees)
- ServiceQuality (poor service)
- Other
DisputeStatus Enum:
- Open (just created)
- UnderReview (arbitrator assigned)
- Resolved (decision made)
- Closed (finalized, no appeals)
Resolution Enum:
- FavorPlaintiff (plaintiff wins)
- FavorDefendant (defendant wins)
- Split (partial resolution)
- Dismissed (invalid dispute)
Evidence:
- evidence_id
- dispute_id
- submitted_by
- evidence_type (Document, Photo, Testimony, Other)
- evidence_hash (hash of evidence file)
- description_hash
- submission_timestamp
2. Storage
- Map of dispute_id to Dispute
- Map of shipment_id to dispute_id (one dispute per shipment)
- Map of dispute_id to array of evidence_ids
- Set of arbitrator addresses
- Counter for total disputes
3. Contract Functions
Raise Dispute:
- Takes shipment_id, dispute_type, reason_hash
- Validates caller is shipper or carrier for that shipment
- Validates shipment status allows disputes (not already resolved)
- Checks no existing open dispute for that shipment
- Creates Dispute record with Open status
- Sets deadline (e.g., 7 days from creation)
- Emits DisputeRaised event
- Returns dispute_id
Submit Evidence:
- Takes dispute_id, evidence_type, evidence_hash, description_hash
- Validates caller is plaintiff or defendant
- Validates dispute is still Open or UnderReview
- Validates submission before deadline
- Creates Evidence record
- Adds to dispute's evidence array
- Emits EvidenceSubmitted event
Assign Arbitrator:
- Takes dispute_id, arbitrator_address
- Only callable by Admin
- Validates arbitrator is in authorized arbitrator set
- Assigns arbitrator to dispute
- Changes status to UnderReview
- Emits ArbitratorAssigned event
Resolve Dispute:
- Takes dispute_id, resolution, resolution_notes_hash
- Only callable by assigned arbitrator
- Validates dispute is UnderReview
- Changes status to Resolved
- Records resolution and notes
- Sets resolution_timestamp
- Emits DisputeResolved event
Close Dispute:
- Takes dispute_id
- Only callable by Admin or after appeal period (e.g., 3 days)
- Changes status to Closed
- Dispute becomes final and immutable
- Triggers actions (release/refund escrow, update reputation)
- Emits DisputeClosed event
Get Dispute:
- Takes dispute_id
- Returns complete Dispute struct
- Public read function
Get Evidence:
- Takes dispute_id
- Returns array of all Evidence structs for that dispute
- Public read function
Get User Disputes:
- Takes user_address
- Returns array of dispute_ids where user is plaintiff or defendant
- Public read function
Add Arbitrator:
- Takes arbitrator_address
- Only callable by Admin
- Adds address to arbitrator set
- Emits ArbitratorAdded event
Remove Arbitrator:
- Takes arbitrator_address
- Only callable by Admin
- Removes from arbitrator set
- Cannot remove if assigned to open disputes
- Emits ArbitratorRemoved event
4. Events
- DisputeRaised(dispute_id, shipment_id, plaintiff, defendant, dispute_type, timestamp)
- EvidenceSubmitted(evidence_id, dispute_id, submitted_by, evidence_type, timestamp)
- ArbitratorAssigned(dispute_id, arbitrator, timestamp)
- DisputeResolved(dispute_id, resolution, arbitrator, timestamp)
- DisputeClosed(dispute_id, final_resolution, timestamp)
- ArbitratorAdded(arbitrator_address, timestamp)
- ArbitratorRemoved(arbitrator_address, timestamp)
5. Access Control
- Only shipment parties can raise disputes
- Only dispute parties can submit evidence
- Only Admin can assign arbitrators
- Only assigned arbitrator can resolve dispute
- Only Admin can close disputes (or auto-close after period)
Dispute Resolution Flow:
- Party raises dispute → Status: Open
- Both parties submit evidence (within deadline)
- Admin assigns arbitrator → Status: UnderReview
- Arbitrator reviews evidence
- Arbitrator makes decision → Status: Resolved
- 3-day appeal period (future: parties can appeal)
- Auto-close or Admin close → Status: Closed
- Trigger escrow release/refund based on resolution
Evidence Handling:
- Actual evidence files stored off-chain (IPFS)
- Only hashes stored on-chain
- Evidence immutable once submitted
- Support multiple evidence submissions per party
- Evidence submission deadline enforced
Integration Points:
- Integrates with Shipment contract (validate shipment exists)
- Integrates with Escrow contract (freeze/release based on resolution)
- Integrates with Reputation contract (disputes affect reputation)
- Access Control contract validates roles
Acceptance Criteria:
- Raise dispute creates proper record
- One dispute per shipment enforced
- Submit evidence validates deadline
- Submit evidence restricted to parties
- Arbitrator assignment restricted to Admin
- Resolve dispute restricted to assigned arbitrator
- Close dispute triggers appropriate actions
- Get dispute returns complete data
- Get evidence returns all submissions
- Add/remove arbitrator restricted to Admin
- All events emit correctly
- Unit tests cover all functions (>80% coverage)
- Integration tests with Escrow and Reputation contracts
- Gas-optimized storage
Testing Requirements:
- Test dispute creation by shipper
- Test dispute creation by carrier
- Test dispute creation by unauthorized party (should fail)
- Test duplicate dispute prevention
- Test evidence submission before deadline
- Test evidence submission after deadline (should fail)
- Test arbitrator assignment
- Test dispute resolution by arbitrator
- Test dispute resolution by non-arbitrator (should fail)
- Test dispute closure
- Test adding/removing arbitrators