Blockchain Solution Design and Development for Logistics

Blockchain Solution Development for Logistics

Reconciliation of data between carrier, customs, and consignee takes up to 5 days — that's 120 hours of cargo idle time, each hour costing an average of $500 for a sea container. One erroneous Bill of Lading can delay cargo in port for a week and lead to a $2,000 fine. In the TradeLens project (Maersk + IBM), blockchain reduced document processing from 7 days to 2 hours — a 96% acceleration. TradeLens case study, 2020 Our clients achieve the same results: document workflow accelerates by 40%, error rate drops by 60%, and the cost of processing one document decreases by $3.

We will design and implement a turnkey blockchain solution: from supply chain audit to operator training. Fill out the consultation form — we will contact you within a day and show how it works on your case.

What Specifically Blockchain Solves in Logistics

Three problems that cost real money:

Document Authenticity. Bill of Lading — the key document in maritime logistics. Traditionally paper-based, delivered by courier. Electronic B/L (eBL) has existed for a long time, but centralized platforms (essDOCS, Bolero) require trust in the operator. CargoX implements B/L as NFT (ERC-721) on Ethereum — ownership transferable on-chain without an intermediary.

Transparency of Transaction Terms. Smart contract escrow: payment is released automatically upon delivery confirmation. No bank guarantees or letters of credit needed for small deals.

Tracking and Provenance. For pharmaceuticals, luxury goods, food — verification of origin and chain of custody is critical (temperature from 2°C to 8°C, humidity ≤60%). IoT sensors + blockchain = immutable audit trail.

How NFT Document Workflow Works?

Bill of Lading as NFT

contract ElectronicBillOfLading is ERC721, AccessControl {
    bytes32 public constant CARRIER_ROLE = keccak256("CARRIER_ROLE");
    bytes32 public constant CUSTOMS_ROLE = keccak256("CUSTOMS_ROLE");
    
    struct ShipmentData {
        string shipmentId;          // external ID from TMS
        address shipper;
        address consignee;
        string portOfLoading;
        string portOfDischarge;
        string cargoDescription;
        uint256 quantity;
        string unit;                // TEU, tonnes, pallets
        uint256 issuedAt;
        ShipmentStatus status;
        bytes32 dataHash;          // hash of full document in IPFS
    }
    
    enum ShipmentStatus {
        Issued,
        InTransit,
        ArrivedAtPort,
        CustomsCleared,
        Delivered,
        Surrendered
    }
    
    mapping(uint256 => ShipmentData) public shipments;
    mapping(uint256 => string[]) public statusHistory; // log of status changes
    
    uint256 private _tokenIdCounter;
    
    function issueBL(
        address consignee,
        string calldata shipmentId,
        string calldata portOfLoading,
        string calldata portOfDischarge,
        string calldata cargoDescription,
        uint256 quantity,
        string calldata unit,
        bytes32 dataHash
    ) external onlyRole(CARRIER_ROLE) returns (uint256) {
        uint256 tokenId = ++_tokenIdCounter;
        
        _mint(consignee, tokenId);
        
        shipments[tokenId] = ShipmentData({
            shipmentId: shipmentId,
            shipper: msg.sender,
            consignee: consignee,
            portOfLoading: portOfLoading,
            portOfDischarge: portOfDischarge,
            cargoDescription: cargoDescription,
            quantity: quantity,
            unit: unit,
            issuedAt: block.timestamp,
            status: ShipmentStatus.Issued,
            dataHash: dataHash
        });
        
        emit BLIssued(tokenId, consignee, shipmentId);
        return tokenId;
    }
    
    function updateStatus(
        uint256 tokenId,
        ShipmentStatus newStatus,
        string calldata note
    ) external {
        ShipmentData storage shipment = shipments[tokenId];
        
        if (newStatus == ShipmentStatus.CustomsCleared) {
            require(hasRole(CUSTOMS_ROLE, msg.sender), "Only customs");
        } else if (newStatus == ShipmentStatus.Delivered) {
            require(ownerOf(tokenId) == msg.sender, "Only consignee");
        } else {
            require(hasRole(CARRIER_ROLE, msg.sender), "Only carrier");
        }
        
        ShipmentStatus prevStatus = shipment.status;
        shipment.status = newStatus;
        statusHistory[tokenId].push(string(abi.encodePacked(
            Strings.toString(block.timestamp), ":", note
        )));
        
        emit StatusUpdated(tokenId, prevStatus, newStatus, msg.sender);
    }
    
    // Override transfer — B/L can only be transferred under certain statuses
    function _beforeTokenTransfer(address from, address to, uint256 tokenId, uint256 batchSize) 
        internal override 
    {
        super._beforeTokenTransfer(from, to, tokenId, batchSize);
        
        if (from != address(0)) {
            ShipmentStatus status = shipments[tokenId].status;
            require(
                status == ShipmentStatus.Issued || status == ShipmentStatus.InTransit,
                "BL not transferable in current status"
            );
        }
    }
}

Escrow for Payments

Payment frozen in smart contract until delivery confirmation:

contract ShipmentEscrow {
    enum EscrowState { Created, Funded, Released, Disputed, Refunded }
    
    struct Escrow {
        address buyer;
        address seller;
        address carrier;
        uint256 amount;
        address token;              // USDC or other stablecoin
        uint256 blTokenId;          // ID of B/L NFT
        address blContract;
        EscrowState state;
        uint256 releaseDeadline;   // if no dispute before deadline — auto-release
    }
    
    mapping(bytes32 => Escrow) public escrows;
    
    function createEscrow(
        address seller,
        address carrier,
        uint256 amount,
        address token,
        uint256 blTokenId,
        address blContract,
        uint256 deliveryDeadline
    ) external returns (bytes32 escrowId) {
        escrowId = keccak256(abi.encodePacked(msg.sender, seller, blTokenId, block.timestamp));
        
        IERC20(token).safeTransferFrom(msg.sender, address(this), amount);
        
        escrows[escrowId] = Escrow({
            buyer: msg.sender,
            seller: seller,
            carrier: carrier,
            amount: amount,
            token: token,
            blTokenId: blTokenId,
            blContract: blContract,
            state: EscrowState.Funded,
            releaseDeadline: deliveryDeadline + 7 days
        });
    }
    
    function confirmDelivery(bytes32 escrowId) external {
        Escrow storage escrow = escrows[escrowId];
        require(msg.sender == escrow.buyer, "Only buyer");
        require(escrow.state == EscrowState.Funded, "Wrong state");
        
        ElectronicBillOfLading bl = ElectronicBillOfLading(escrow.blContract);
        require(
            bl.shipments(escrow.blTokenId).status == ElectronicBillOfLading.ShipmentStatus.Delivered,
            "Not delivered on-chain"
        );
        
        escrow.state = EscrowState.Released;
        IERC20(escrow.token).safeTransfer(escrow.seller, escrow.amount);
    }
}

Blockchain is Faster Than Traditional Databases

Blockchain replaces multiday reconciliation in Excel and email with a single secure ledger. Transactions are confirmed in minutes, not hours. In the TradeLens project, shipping time was reduced from 10 days to 1 day. This uses a shared ledger with PoA (Proof of Authority) consensus on a permissioned network — high throughput (up to 1000 TPS) and low latency.

How to Integrate Blockchain with Existing TMS?

Logistics TMS and ERP (SAP, Oracle) have REST/SOAP APIs. Our integration layer signs events and sends transactions on-chain:

class LogisticsIntegration {
  private web3Provider: Provider;
  private blContract: ElectronicBillOfLading;
  
  // Webhook from TMS on cargo status change
  async handleTMSStatusUpdate(event: TMSEvent) {
    const { shipmentId, newStatus, timestamp, operator } = event;
    
    const tokenId = await this.getTokenIdByShipmentId(shipmentId);
    const onChainStatus = this.mapTMSStatusToOnChain(newStatus);
    
    // Send transaction
    const tx = await this.blContract.updateStatus(
      tokenId,
      onChainStatus,
      `TMS update: ${newStatus} at ${timestamp}`
    );
    
    await tx.wait();
    
    // Update local DB
    await this.db.shipments.update({
      where: { shipmentId },
      data: { lastTxHash: tx.hash, onChainStatus },
    });
  }
}

How IoT Telemetry Gets on Blockchain?

For cold chain (pharma, food), verification of storage conditions is critical. IoT sensors transmit data via a gateway (Raspberry Pi) to a smart contract through an oracle. We use Chainlink Functions for decentralized aggregation:

contract ShipmentTelemetry {
    struct TelemetryRecord {
        uint256 timestamp;
        int16 temperature;      // in tenths of degrees (156 = 15.6°C)
        uint16 humidity;        // in tenths of percent
        int32 latitude;         // in microdegrees
        int32 longitude;
        address oracle;         // who signed the data
    }
    
    mapping(uint256 => TelemetryRecord[]) public telemetry; // tokenId => records
    mapping(uint256 => bool) public conditionViolated;     // whether violations occurred
    
    // Allowed ranges for cargo
    struct ConditionRequirements {
        int16 minTemp;
        int16 maxTemp;
        uint16 maxHumidity;
    }
    mapping(uint256 => ConditionRequirements) public requirements;
    
    function submitTelemetry(
        uint256 shipmentTokenId,
        int16 temperature,
        uint16 humidity,
        int32 lat,
        int32 lon,
        bytes calldata oracleSignature
    ) external {
        bytes32 dataHash = keccak256(abi.encodePacked(
            shipmentTokenId, temperature, humidity, lat, lon, block.timestamp / 300
        ));
        address signer = ECDSA.recover(dataHash.toEthSignedMessageHash(), oracleSignature);
        require(isApprovedOracle(signer), "Unauthorized oracle");
        
        telemetry[shipmentTokenId].push(TelemetryRecord({
            timestamp: block.timestamp,
            temperature: temperature,
            humidity: humidity,
            latitude: lat,
            longitude: lon,
            oracle: signer
        }));
        
        ConditionRequirements memory req = requirements[shipmentTokenId];
        if (temperature < req.minTemp || temperature > req.maxTemp || humidity > req.maxHumidity) {
            conditionViolated[shipmentTokenId] = true;
            emit ConditionViolation(shipmentTokenId, temperature, humidity, block.timestamp);
        }
    }
}

Blockchain Selection: Public vs Private vs Hybrid

Choice depends on requirements for confidentiality and composability.

For B2B consortium with known participants — Hyperledger Fabric. For open protocol with tokenization — Polygon with private transactions.

Consensus Comparison for Logistics

What is Included in the Work (Deliverables)

• Architectural documentation (interaction diagrams, contract specifications)
• Smart contracts with unit tests (Foundry / Hardhat)
• Integration layer (Node.js/Fastify) with API
• Frontend panel (Next.js + wagmi)
• Changelog and audit report (Mythril/Slither)
• Operator training (2–4 hours)
• Technical support for 3 months after release

Timeline and Cost

Approximate timelines:

• MVP (B/L NFT + basic tracking + simple escrow) — from 6 weeks
• Production (IoT, multi-party workflow, full integration) — from 4 months

Cost is calculated individually after audit. Fill out the form — we will contact you within a day. Order a system demonstration on your case — we will show a live prototype.

Our Experience

We are a team of blockchain engineers with 5+ years of experience in Web3. We have delivered over 10 projects for logistics, fintech, and DeFi. We use only verified OpenZeppelin libraries, ERC standards, and undergo formal smart contract audits.

Get a consultation: contact us via email or Telegram — we will show cases and architecture for your task.

Blockchain Infrastructure Deployment: Nodes, RPC, Indexing

Subgraph fell at 3:47 AM. By morning users saw outdated balances, transactions "hung" in the UI, support received 47 tickets in an hour. Cause: the handler in the subgraph failed on a transaction with a non-standard event log — and the entire index stopped. We have encountered such situations dozens of times. Our experience shows: blockchain infrastructure does not forgive gaps in observability. Guaranteeing uptime without multi-layered monitoring and fault-tolerant architecture is impossible. Over 8 years working with Ethereum, Polygon, and Solana, we have developed an approach that allows predictable deployment of infrastructure of any scale — from a single node to a multichain grid with dozens of subgraphs.

RPC Layer Architecture

Every dApp interaction with the blockchain goes through RPC — the JSON-RPC API provided by a node. Three options:

Managed providers — Alchemy, QuickNode, Infura, Ankr. Minimal operational costs, SLA, built-in monitoring. Limits: rate limits (Alchemy Free: 300 RU/sec), vendor lock, potential downtime during provider incidents. For most projects — the right choice at the start.

Self-owned nodes — full control, no rate limits, no third-party dependence. Cost: archive Ethereum node requires 2.5–3TB SSD, a strong server, and DevOps support. Sync from scratch on Ethereum via Geth/Nethermind — 3–7 days. Justified under high load or latency requirements.

Hybrid — self-owned node as primary, managed provider as fallback. Standard for protocols with high TVL. Proper load balancing can reduce costs by 20–30% compared to pure managed setup. Under high monthly request volume, hybrid saves significantly.

How to Set Up an RPC Layer Without a Single Point of Failure?

At least two providers, DNS round-robin with health check every 5 seconds, automatic fallback when latency >500 ms. In practice, this gives 99.99% availability during any provider failure. For protocols with high TVL, we recommend a custom HA-proxy (nginx or Envoy) in front of two managed providers.

Why Is a Hybrid RPC Scheme More Cost-Effective Than Pure Managed?

At high request volumes, managed providers can be very expensive; a hybrid using a self-owned node as primary and a managed fallback cuts costs significantly without losing SLA.

Ethereum Node Clients

Execution clients: Geth (most used), Nethermind (C#, fast sync), Besu (Java, enterprise), Erigon (fastest sync, efficient archive mode ~2TB instead of 3TB).

Consensus clients (post-Merge): Lighthouse (Rust), Prysm (Go), Teku (Java), Nimbus (Nim). Each node after The Merge requires a pair of execution + consensus clients.

For DevOps: eth-docker — Docker Compose configurations for all client combinations. Setting up monitoring via Grafana + Prometheus is mandatory; a standard dashboard is available in each client's repository.

The Graph: Event Indexing

The Graph Protocol — decentralized indexing. A subgraph describes which events from which contracts to index and how to transform them into a GraphQL schema.

Subgraph structure:

• subgraph.yaml — manifest: contract addresses, startBlock, events to handle
• schema.graphql — GraphQL schema of entities
• src/mapping.ts — AssemblyScript event handlers

dataSources:
  - kind: ethereum
    name: UniswapV3Pool
    network: mainnet
    source:
      address: "0x88e6A0c2dDD26FEEb64F039a2c41296FcB3f5640"
      abi: UniswapV3Pool
      startBlock: 12370624
    mapping:
      eventHandlers:
        - event: Swap(indexed address,indexed address,int256,int256,uint160,uint128,int24)
          handler: handleSwap

AssemblyScript handlers — not TypeScript. No nullable types, no closures, no many standard APIs. An error in the handler stops the subgraph indexing on that transaction. Important: add try-catch for operations that can fail (e.g., store.get() for an entity that may not exist).

How to Avoid Subgraph Indexing Stops?

Graph Node logs are monitored in real-time; on hasIndexingErrors = true an alert fires and an automatic node restart (via systemd or Kubernetes). Typical downtime on error — 150–300 seconds to recover. Additionally, for production we set up a watchdog that restarts Graph Node if subgraph lag exceeds 50 blocks.

Choosing Between Hosted Service and Decentralized Network

Graph Hosted Service (free, centralized) is deprecated in favor of Subgraph Studio + Graph Network. For production: deploy on Graph Network with GRT curation signal — the subgraph gets indexers proportional to curation.

Alternatives to The Graph: Ponder (TypeScript, self-hosted, easier to debug), Envio (ultra-fast indexer, supports EVM + non-EVM), Subsquid (TypeScript, own network), Moralis Streams (managed, webhook-based). Our experience shows: for high-load projects with unique logic, Ponder or Envio are more effective — they give full control over the process and do not require GRT tokenomics.

Webhooks and Real-Time Notifications

Alchemy Webhooks and QuickNode Streams allow receiving events in real-time via HTTP webhook or WebSocket. For monitoring addresses, new transactions, mints — this is faster than polling RPC.

Tenderly — platform for monitoring and alerts. You can set up an alert for a specific contract event, balance change, function call with certain parameters. Transaction simulation via Tenderly API is invaluable for debugging.

Monitoring and Observability

Minimum monitoring stack for a protocol:

On-chain: OpenZeppelin Defender Sentinel — watches contract events, triggers webhook or Autotask when conditions are met. Forta Network — community-maintained bots detect anomalies (large withdrawals, flash loans, governance attacks).

Infrastructure: Grafana + Prometheus for nodes, Datadog or Grafana Cloud for managed metrics. Alerts on: node is 10+ blocks behind, RPC latency >500ms, subgraph lag >100 blocks.

Uptime: Better Uptime or PagerDuty on RPC endpoint and subgraph health endpoint (The Graph provides _meta { hasIndexingErrors, block { number } }).

Why Is Monitoring Without Tenderly Insufficient?

Tenderly provides transaction simulation and detailed traces — critical for debugging subgraph and smart contract errors. Forta focuses on network anomalies, not your infrastructure. The combination of Tenderly plus a custom Grafana dashboard covers 90% of incident scenarios.

Multichain Infrastructure

A protocol on 5 chains = 5 separate RPC endpoints, 5 subgraphs, 5 monitoring configs. Manageable but requires deployment automation.

For subgraph multi-network deployment: graph deploy --network mainnet, graph deploy --network arbitrum-one etc. with a unified codebase and network-specific addresses in separate config files.

Chainlink CCIP and LayerZero for cross-chain messaging require monitoring of both chains and transactions on intermediate relayers. A reorg on the source chain after a confirmed mint on the target chain is a classic bridge problem. Solution: wait for finality (on Ethereum ~15 minutes after Merge for economic finality) before confirming on the target chain.

Infrastructure Setup Process

1. Audit current stack — determine chains, request volume, latency and availability requirements.
2. Architecture design — select providers, load balancing, redundancy.
3. Subgraph development — manifest → schema → handlers → testing on local Graph Node → deploy to testnet → mainnet.
4. Monitoring configuration — Tenderly alerts, Grafana dashboard, PagerDuty integration.
5. Documentation and runbook — what to do when: subgraph falls behind, RPC downtime, node desync.
6. Handover to operations — team training, access transfer, first month support.

What's Included

• Deployment of managed or self-hosted Ethereum, Polygon, BNB Chain nodes
• RPC layer setup with primary/fallback and load balancing
• Subgraph development and deployment for your protocol
• Monitoring connection (Tenderly, Grafana, alerts)
• Runbook and operations documentation
• Team training (up to 4 hours online)
• 30-day support after delivery

Timeline

All projects are managed in a GitHub/GitLab repository with CI/CD; configuration code stays with you. Order infrastructure deployment — we'll show how to cut costs by 20–30% without losing reliability. Get a consultation — we'll demonstrate how we deployed infrastructure for a protocol with large TVL on Ethereum and Arbitrum. Contact us.