escrow smart contract for shipment

[mijinummi]

🚚 Payment Escrow Smart Contract Implementation (#506)

This PR introduces a secure, gas-optimized payment escrow smart contract that automates trust between shippers and carriers by holding funds in escrow until shipment delivery is confirmed.

The contract ensures fund safety, clear dispute handling, and strict access control, while integrating seamlessly with the Shipment contract.

---

🎯 Purpose

• Securely lock shipment payments in escrow
• Automatically release funds upon confirmed delivery
• Enable refunds for cancelled shipments
• Provide a structured dispute resolution flow
• Prevent fraud, reentrancy attacks, and invalid state transitions

---

🧱 Core Features

1. Escrow Data Model

• EscrowPayment

  • payment_id
  • shipment_id
  • payer_address (shipper)
  • payee_address (carrier)
  • amount
  • status
  • created_at
  • released_at
  • dispute_deadline

• PaymentStatus enum:

  • Pending
  • Locked
  • Released
  • Refunded
  • Disputed

---

⚙️ Contract Functionality

🔐 Escrow Lifecycle

• Create Escrow

  • Locks funds in contract
  • Enforces one escrow per shipment
  • Validates amount, addresses, and shipment ownership

• Release Payment

  • Requires shipment status = Delivered
  • Prevents release during active disputes
  • Transfers funds to carrier

• Refund Payment

  • Only allowed for cancelled shipments
  • Returns funds to shipper

---

⚖️ Dispute Management

• Initiate Dispute

  • Callable by shipper or carrier
  • Enforced dispute deadline
  • Freezes escrowed funds

• Resolve Dispute

  • Arbitrator-only access
  • Supports release or refund resolutions
  • Executes fund transfer atomically

---

🔍 Read Operations

• getPaymentDetails(payment_id)
  • Public read-only access to full escrow state

---

🔐 Access Control Summary

Action	Authorized
Create Escrow	Shipper
Release Payment	Shipper / Automated System
Refund Payment	Shipper
Initiate Dispute	Shipper or Carrier
Resolve Dispute	Arbitrator Only

---

🛡 Security Measures

• Reentrancy protection on all fund-transfer functions
• Strict non-zero address validation
• Exact payment amount enforcement
• Shipment ownership verification
• Dispute deadline enforcement
• Contract balance validation
• Prevention of:
  • Multiple escrows per shipment
  • Zero-value escrows
  • Self-payments
  • Invalid state transitions

---

🧪 Testing Coverage

Unit Tests

• Escrow creation (valid & invalid amounts)
• Release after delivery (success & failure cases)
• Refund for cancelled shipments
• Dispute initiation (within & after deadline)
• Dispute resolution (authorized vs unauthorized)
• Reentrancy attack prevention
• Edge cases (zero amount, duplicate escrow, self-payment)

Integration Tests

• Shipment contract status validation
• Shipper/carrier identity verification

✅ Test coverage exceeds 80%

---

⛽ Gas Optimization

• Minimal storage writes
• Efficient enum-based state management
• Single escrow mapping per shipment
• Optimized event emissions

---

🔗 Integration Notes

• Fully compatible with Shipment contract
• Designed for frontend integration (Next.js 14)
• Events structured for off-chain indexing and UI updates

---

✅ Acceptance Criteria Status

• Escrow creation locks funds
• Payment release works correctly
• Refunds return funds to shipper
• Disputes freeze funds
• Arbitrator resolution enforced
• Access controls validated
• Reentrancy attacks prevented
• Events emit correct data
• Unit & integration tests included
• Gas optimized

---

🚀 Ready for review and merge

[vercel]

@mijinummi is attempting to deploy a commit to the Mftee's projects Team on Vercel.

A member of the Team first needs to authorize it.