Blockchain Cargo Tracking System Development

Development of Cargo Tracking System on Blockchain

Cargo tracking systems have existed for decades — TMS, WMS, EDI. Problem is not lack of systems but that they don't talk to each other. Shipper in China uses one system, freight broker uses another, customs uses third, final recipient only sees what carrier deigns to tell them. Blockchain here is not "about technology" but neutral platform that all parties trust because none of them controls it.

Specifics of Cargo Operations: What Needs Tracking

Participants and Their Roles

Typical international shipment involves:

• Shipper (cargo sender) — creates Bill of Lading, initiates shipment
• Freight Forwarder — organizes transportation, documentation
• Carrier (transporter) — physically transports cargo (sea, air, rail, road)
• Port/Terminal Operator — container receipt and delivery
• Customs Broker — customs clearance
• Consignee (cargo receiver) — final recipient
• Bank/Financier — financing under Letter of Credit or documentary credit
• Inspector/Surveyor — independent cargo inspection

Each participant has their own system, their own view of cargo status. On-chain system provides single source of truth.

Key Documents and Events

Bill of Lading (B/L) — central document in maritime shipping. It's simultaneously carrier's receipt, transportation contract and cargo management document. B/L tokenization — separate topic (electronic B/L, eBL), regulated by BIMCO and DCSA standards.

Cargo Lifecycle Events:

Booking → Cargo Received at Origin Port → Loaded on Vessel → 
Departed → In Transit → Arrived at Destination Port → 
Customs Cleared → Available for Pickup → Delivered

For air transport: Air Waybill instead of B/L, different checkpoint events. For rail: Consignment Note (CIM/SMGS).

System Architecture

Data: What On-Chain, What Off-Chain

On-chain:

• Unique cargo identifier (shipment ID → hash)
• Document hashes (B/L, invoice, customs declaration, certificates)
• Custody transitions with timestamps
• Milestone events with coordinates (hash) and participant signatures
• Payment conditions and their fulfillment

Off-chain (IPFS/Arweave):

• Documents themselves (PDF, XML)
• Detailed sensor data logs
• Cargo photographs

Off-chain (traditional database for fast queries):

• Current status of all shipments for specific participant
• Analytics, reports
• Index by tracking number / container number

Shipment NFT

Cargo as NFT is correct abstraction for unique shipments. NFT transfer = transfer of cargo ownership (for Documentary Collection / Letter of Credit operations).

contract ShipmentRegistry is ERC721, AccessControl {
    struct Shipment {
        bytes32 shipmentId;         // unique ID
        bytes32 bookingReference;   // booking number
        ShipmentType shipmentType;  // FCL, LCL, Air, Rail, Road
        address shipper;
        address consignee;
        bytes32 originPortHash;
        bytes32 destinationPortHash;
        bytes32 blHash;             // hash of Bill of Lading
        ShipmentStatus status;
        uint64 estimatedDeparture;
        uint64 estimatedArrival;
    }

    mapping(bytes32 => Shipment) public shipments;
    mapping(bytes32 => MilestoneEvent[]) public milestones;
    mapping(bytes32 => bytes32[]) public documentHashes;

    function createShipment(
        bytes32 shipmentId,
        ShipmentType shipmentType,
        address consignee,
        bytes32 blHash,
        bytes32 originPortHash,
        bytes32 destinationPortHash,
        uint64 estimatedDeparture,
        uint64 estimatedArrival
    ) external onlyRole(FREIGHT_FORWARDER_ROLE) returns (uint256 tokenId) {
        // Mint NFT to shipper, who can transfer it
        tokenId = _nextTokenId++;
        _mint(msg.sender, tokenId);

        shipments[shipmentId] = Shipment({
            shipmentId: shipmentId,
            bookingReference: bytes32(0),
            shipmentType: shipmentType,
            shipper: msg.sender,
            consignee: consignee,
            originPortHash: originPortHash,
            destinationPortHash: destinationPortHash,
            blHash: blHash,
            status: ShipmentStatus.Booked,
            estimatedDeparture: estimatedDeparture,
            estimatedArrival: estimatedArrival
        });

        emit ShipmentCreated(shipmentId, msg.sender, consignee, shipmentType);
    }
}

Milestone Events and Multi-Signatures

Critical milestone events require confirmation from multiple parties. Loading onto vessel must be confirmed by both carrier and terminal operator:

struct PendingMilestone {
    bytes32 shipmentId;
    MilestoneType milestoneType;
    bytes32 locationHash;
    bytes32 evidenceHash;
    uint64 timestamp;
    mapping(address => bool) confirmations;
    uint256 confirmationCount;
    bool executed;
}

function confirmMilestone(bytes32 milestoneId) external {
    PendingMilestone storage milestone = pendingMilestones[milestoneId];
    require(hasRole(getMilestoneRole(milestone.milestoneType), msg.sender),
        "Unauthorized confirmer");
    require(!milestone.confirmations[msg.sender], "Already confirmed");

    milestone.confirmations[msg.sender] = true;
    milestone.confirmationCount++;

    if (milestone.confirmationCount >= REQUIRED_CONFIRMATIONS[milestone.milestoneType]) {
        executeMilestone(milestoneId);
    }
}

IoT Integration: Real-Time Position and State

For container shipping critical:

• GPS position — updates every N hours via satellite tracker
• Temperature / humidity — for reefer containers
• Vibration / shock — for fragile cargo
• Tamper sensors — unauthorized opening

IoT device data can't be written directly to blockchain — too expensive. Aggregation scheme:

IoT Device → Satellite/Cellular Gateway → Data Aggregation Server →
→ Oracle → Smart Contract (aggregated alerts + checkpoints)

Oracle records not raw stream but: current position every 6 hours, anomalous events (temperature out of range), arrival/departure port events.

Payment Automation: Letter of Credit On-Chain

Traditional Letter of Credit (LC) — one of most complex financial instruments, with 7–30 day delays on document processing. On-chain automation:

contract LetterOfCredit {
    enum LCStatus { Issued, DocumentsPresented, Verified, PaymentReleased, Rejected }

    struct LC {
        address applicant;       // buyer
        address beneficiary;     // seller
        address issuingBank;
        uint256 amount;
        address paymentToken;    // stablecoin (USDC/USDT)
        bytes32 shipmentId;      // tied to specific cargo
        bytes32[] requiredDocHashes;  // hashes of required documents
        uint64 expiryDate;
        LCStatus status;
    }

    function presentDocuments(
        bytes32 lcId,
        bytes32[] calldata documentHashes,
        bytes32 shipmentId
    ) external {
        LC storage lc = lcs[lcId];
        require(msg.sender == lc.beneficiary, "Not beneficiary");
        require(block.timestamp <= lc.expiryDate, "LC expired");

        // Verify cargo delivered on-chain
        require(
            shipmentRegistry.getMilestoneStatus(shipmentId, MilestoneType.Delivered),
            "Delivery not confirmed"
        );

        // Verify document hashes
        for (uint i = 0; i < lc.requiredDocHashes.length; i++) {
            require(
                isDocumentPresented(documentHashes, lc.requiredDocHashes[i]),
                "Missing required document"
            );
        }

        lc.status = LCStatus.DocumentsPresented;
        emit DocumentsPresented(lcId, msg.sender);
    }

    function releasePayment(bytes32 lcId) external onlyRole(BANK_ROLE) {
        LC storage lc = lcs[lcId];
        require(lc.status == LCStatus.DocumentsPresented, "Documents not presented");

        lc.status = LCStatus.PaymentReleased;
        IERC20(lc.paymentToken).safeTransfer(lc.beneficiary, lc.amount);
        emit PaymentReleased(lcId, lc.beneficiary, lc.amount);
    }
}

Customs Integration

Customs authorities in different countries beginning to accept blockchain-verified data. Key standards:

WCO Data Model — World Customs Organization standard for customs data. Data in blockchain must match this model for possible integration with ACS (Automated Customs Systems).

Single Window systems — many countries have or building national single window. Integration via API with hash storage on-chain.

Realistic customs integration: system records customs documents in IPFS, hashes in blockchain, customs broker with accredited key signs "customs cleared" milestone. Direct interaction of government systems with blockchain — possible in Singapore, UAE, Switzerland, in other jurisdictions — difficult.

Network Choice and Infrastructure

For consortium (limited participant circle): Polygon CDK or Arbitrum Orbit — private L2 with EVM compatibility. Low gas, control over validators, ability to configure permissioned access.

For open platform: Polygon PoS or Base — availability for any participants, good stablecoin payment liquidity, low fees.

Not recommended: Hyperledger Fabric — without strong enterprise reason. EVM infrastructure significantly more mature for DeFi payment integration.

Development Stages

Main technical risk — IoT reliability on vessel (coverage, battery, harsh conditions). Main operational risk — participant onboarding: convincing freight broker in Hong Kong and customs broker in Rotterdam to work with one system.