MVP Integration Flow

This document outlines the integration flow between key components of the Skyocean MVP: the ERP system, DKG Edge Node, blockchain smart contracts, and other external systems. Understanding this flow is essential for developers to implement the correct sequence of operations and data transformations.

Component Interaction Overview

The MVP integration involves several key systems working together in a coordinated flow:

graph TD
    A[ERPNext] -->|1. Transaction Data| B[Edge Node]
    B -->|2. Create Knowledge Asset| C[DKG Network]
    B -->|3. Notify KA Creation| D[Web Application]
    D -->|4. Create Smart Contract| E[Blockchain]
    E -->|5. Return Contract Address| D
    D -->|6. Update KA with Contract Address| B
    B -->|7. Update Knowledge Asset| C
    F[Document Upload] -->|8. Document Data| B
    B -->|9. Update KA with Document Status| C
    B -->|10. Notify Document Status Change| D
    D -->|11. Update Smart Contract| E
    E -->|12. Emit Payment Event| D
    D -->|13. Update KA with Payment Status| B
    B -->|14. Final KA Update| C
    D <-->|15. API Integration| G[Simulated Customs/Banking]
    A <-->|16. Fetch Latest Status| D

Detailed Flow Sequence

1. Knowledge Asset Creation (First Step) 

// Example ERPNext data sent to Edge Node
{
  "transaction_id": "SKY-T12345",
  "part_number": "571925-3-1",
  "part_name": "COOLING TURBINE",
  "condition": "OH",
  "quantity": 2,
  "unit_price": 25000,
  "buyer": "AirLines Ltd",
  "seller": "Parts Depot Inc"
}
  • ERPNext captures trade transaction details
  • Data is sent to the Edge Node via API
  • Edge Node converts ERP data to JSON-LD format
  • Edge Node creates a Knowledge Asset (KA) in the DKG
  • DKG anchors the KA on its own blockchain (OriginTrail’s blockchain)

The Knowledge Asset now exists in the DKG with a unique UAL (Universal Asset Locator).

2. Smart Contract Creation (Triggered by KA) 

// Simplified Smart Contract Example
pragma solidity ^0.8.0;

contract TradeEscrow {
    string public kaIdentifier;  // DKG Knowledge Asset UAL
    address public buyer;
    address public seller;
    uint256 public amount;
    bool public documentsApproved = false;
    bool public fundsReleased = false;
    
    event DocumentsApproved(string kaIdentifier);
    event FundsReleased(string kaIdentifier, uint256 amount);
    
    constructor(string memory _kaIdentifier, address _seller) payable {
        kaIdentifier = _kaIdentifier;
        buyer = msg.sender;
        seller = _seller;
        amount = msg.value;
    }
    
    function approveDocuments() external {
        // Called when all documents are verified
        require(msg.sender == buyer, "Only buyer can approve");
        documentsApproved = true;
        emit DocumentsApproved(kaIdentifier);
    }
    
    function releaseFunds() external {
        // Can be triggered by system or manually by buyer
        require(documentsApproved, "Documents not yet approved");
        require(!fundsReleased, "Funds already released");
        fundsReleased = true;
        
        payable(seller).transfer(amount);
        emit FundsReleased(kaIdentifier, amount);
    }
}
  • After KA creation, Edge Node notifies the Web Application
  • Web Application initiates smart contract creation on business blockchain (Sepolia testnet)
  • Smart contract is created with KA identifier (UAL) as a reference
  • Smart contract deployment returns contract address
  • Web Application calls Edge Node API to update the KA with contract address

The Knowledge Asset now references the smart contract and vice versa.

3. Bidirectional Updates

DKG → Blockchain Flow 

// Pseudocode for document status change handling
function handleDocumentStatusChange(documentId, newStatus) {
  // 1. Get the associated Knowledge Asset
  const ka = await edgeNode.getKnowledgeAsset(documentId);
  
  // 2. Check if all required documents are approved
  const allDocumentsApproved = checkAllDocumentsApproved(ka);
  
  if (allDocumentsApproved) {
    // 3. Get smart contract address from KA
    const contractAddress = ka.contractAddress;
    
    // 4. Call smart contract to approve documents
    await blockchain.callContract(
      contractAddress, 
      "approveDocuments", 
      []  // No parameters needed
    );
  }
}
  • When documents are uploaded to Edge Node, they are processed into the KA
  • Edge Node detects document status changes (e.g., all documents approved)
  • Edge Node notifies Web Application
  • Web Application calls smart contract to update status
  • Smart contract emits events that can be monitored

Blockchain → DKG Flow 

// Pseudocode for blockchain event handling
function listenForBlockchainEvents() {
  blockchain.on("FundsReleased", async (kaIdentifier, amount) => {
    // 1. Update the Knowledge Asset with payment information
    await edgeNode.updateKnowledgeAsset(kaIdentifier, {
      paymentStatus: "COMPLETED",
      paymentAmount: amount,
      paymentDate: new Date().toISOString()
    });
    
    // 2. Notify any other systems (ERP, etc.)
    await notifyExternalSystems(kaIdentifier, "PAYMENT_COMPLETE");
  });
}
  • Smart contract emits events (e.g., payment released)
  • Web Application listens for these blockchain events
  • When event is detected, Web Application calls Edge Node API to update KA
  • KA is updated with new status information
  • Changes are reflected in the DKG network

4. ERP Integration

The ERP system needs to stay in sync with the latest state of transactions:

  • ERP queries Web Application for latest status
  • Web Application fetches:
    • Knowledge Asset data from Edge Node
    • Smart contract state from blockchain
  • Web Application returns combined status to ERP
  • ERP updates its transaction records accordingly

Simulated External Systems for MVP

For the MVP, external systems like customs and banking are simulated:

// Example of simulated customs clearance API endpoint
app.post('/api/customs/usa/clearance', (req, res) => {
  const { transactionId, documentHashes } = req.body;
  
  // In MVP, always return success after short delay
  setTimeout(() => {
    res.json({
      status: "CLEARED",
      clearanceId: "US-CLR-" + Math.floor(Math.random() * 100000),
      timestamp: new Date().toISOString(),
      message: "Customs clearance simulated successfully"
    });
  }, 2000); // 2-second delay to simulate processing
});

// Example of simulated bank payment API endpoint
app.post('/api/bank/payment/confirm', (req, res) => {
  const { transactionId, amount, currency } = req.body;
  
  // In MVP, always return success after short delay
  setTimeout(() => {
    res.json({
      status: "PAYMENT_CONFIRMED",
      paymentId: "PMT-" + Math.floor(Math.random() * 100000),
      timestamp: new Date().toISOString(),
      message: "Bank payment simulated successfully"
    });
  }, 3000); // 3-second delay to simulate processing
});

MVP Dashboard Visualization

The Web Application provides a unified dashboard that displays:

  1. Transaction Overview: Basic details from ERPNext
  2. Document Status: From Knowledge Asset in DKG
  3. Blockchain Status: From smart contract events and state
  4. External System Status: From simulated customs and banking APIs

This gives a complete view of the transaction lifecycle across all integrated systems.

Technical Considerations for Implementation

1. Asynchronous Processing

Most operations in this flow are asynchronous. Implement:

  • Webhook listeners for Edge Node events
  • Blockchain event listeners for smart contract events
  • Message queue for reliable event processing

2. Error Handling

Implement robust error handling for:

  • Failed API calls to Edge Node
  • Blockchain transaction failures
  • Network disconnections
  • Data inconsistencies between systems

3. State Reconciliation

Develop mechanisms to handle:

  • Missed events
  • System restarts
  • Data synchronization between components

Conclusion

This integration flow provides a comprehensive view of how data and events move between systems in the Skyocean MVP. By implementing this flow, developers can create a cohesive solution that demonstrates the key value propositions of the platform: document verification through DKG, automated transactions through blockchain smart contracts, and comprehensive supply chain management through ERP integration.

The MVP implementation should focus on demonstrating this complete flow, even if some components (like customs and banking systems) are simulated. This approach provides a clear path to future expansion where simulated components can be replaced with real integrations.