Transactional Knowledge Assets

Overview

This document outlines the structure and implementation of transactional knowledge assets for the SKYOCEAN platform MVP. Transactional knowledge assets represent the dynamic trading elements that flow through the platform, including commodities, purchase orders, shipping documentation, and financial instruments. These assets build upon the institutional foundation established in the platform.

Knowledge Asset Types

1. Commodity Records

The commodity knowledge asset defines tradable goods with their specifications:

{
  "assertion": [
    {
      "@id": "urn:id:skyocean:commodity:maize",
      "@type": ["http://schema.org/Product"],
      "http://schema.org/name": [{"@value": "US Yellow Corn"}],
      "http://schema.org/description": [{"@value": "Grade A US Yellow Corn/Maize"}],
      "http://schema.org/category": [{"@value": "Agricultural Products"}],
      "http://schema.org/sku": [{"@value": "AG-MAIZE-US-YELLOW-001"}],
      "http://schema.org/manufacturer": [{"@id": "urn:id:skyocean:supplier:usa:midwest001"}],
      "http://schema.org/weight": [{"@value": "5000kg"}],
      "http://schema.org/certifications": [
        {"@id": "urn:id:skyocean:cert:organic"},
        {"@id": "urn:id:skyocean:cert:usda"}
      ]
    },
    {
      "@id": "urn:id:skyocean:supplier:usa:midwest001",
      "@type": ["http://schema.org/Organization"],
      "http://schema.org/name": [{"@value": "Midwest Agricultural Cooperative"}]
    }
  ]
}

2. Purchase Orders

The purchase order knowledge asset represents trading agreements between parties:

{
  "assertion": [
    {
      "@id": "urn:id:skyocean:po:2024060001",
      "@type": ["http://schema.org/Order"],
      "http://schema.org/orderNumber": [{"@value": "PO-2024-06-0001"}],
      "http://schema.org/orderDate": [{"@value": "2024-06-05"}],
      "http://schema.org/customer": [{"@id": "urn:id:skyocean:customer:ghanaagro"}],
      "http://schema.org/seller": [{"@id": "urn:id:skyocean:sot"}],
      "http://schema.org/orderedItem": [
        {"@id": "urn:id:skyocean:po:2024060001:item1"}
      ],
      "http://schema.org/paymentMethod": [{"@value": "CAD - Cash Against Documents"}],
      "http://schema.org/paymentDue": [{"@value": "2024-08-15"}],
      "http://schema.org/totalPrice": [{"@value": "USD 87,500"}],
      "http://schema.org/paymentTerm": [{"@value": "CAD"}],
      "http://schema.org/financeProvider": [{"@id": "urn:id:skyocean:finance:platform"}],
      "http://schema.org/contractReference": [{"@value": "0x4a8bc8e14A3A77F81D9D6C43B6852148e0b8CFBa"}]
    },
    {
      "@id": "urn:id:skyocean:po:2024060001:item1",
      "@type": ["http://schema.org/OrderItem"],
      "http://schema.org/orderedItem": [{"@id": "urn:id:skyocean:commodity:maize"}],
      "http://schema.org/orderQuantity": [{"@value": "50000"}],
      "http://schema.org/orderItemStatus": [{"@value": "Confirmed"}],
      "http://schema.org/unitPrice": [{"@value": "USD 1.75/kg"}]
    },
    {
      "@id": "urn:id:skyocean:customer:ghanaagro",
      "@type": ["http://schema.org/Organization"],
      "http://schema.org/name": [{"@value": "Ghana Agricultural Development Ltd."}]
    },
    {
      "@id": "urn:id:skyocean:finance:platform",
      "@type": ["http://schema.org/Organization"],
      "http://schema.org/name": [{"@value": "SKYOCEAN Financing Platform"}]
    }
  ]
}

3. Shipping Documentation

The shipping documentation knowledge asset tracks logistics information:

{
  "assertion": [
    {
      "@id": "urn:id:skyocean:shipping:BL20240601",
      "@type": ["http://schema.org/ParcelDelivery"],
      "http://schema.org/trackingNumber": [{"@value": "BL-2024-06-0001"}],
      "http://schema.org/deliveryStatus": [{"@value": "InTransit"}],
      "http://schema.org/expectedArrivalFrom": [{"@value": "2024-07-20"}],
      "http://schema.org/expectedArrivalUntil": [{"@value": "2024-07-25"}],
      "http://schema.org/originAddress": [{"@id": "urn:id:skyocean:location:port:neworleans"}],
      "http://schema.org/deliveryAddress": [{"@id": "urn:id:skyocean:location:port:tema"}],
      "http://schema.org/itemShipped": [{"@id": "urn:id:skyocean:po:2024060001"}],
      "http://schema.org/carrier": [{"@id": "urn:id:skyocean:partner:logistics:atlanticship"}],
      "http://schema.org/smartContractAddress": [{"@value": "0x4a8bc8e14A3A77F81D9D6C43B6852148e0b8CFBa"}],
      "http://schema.org/relatedDocuments": [
        {"@id": "urn:id:skyocean:doc:inspection:2024060001"},
        {"@id": "urn:id:skyocean:doc:phytosanitary:2024060001"},
        {"@id": "urn:id:skyocean:doc:packinglist:2024060001"}
      ]
    },
    {
      "@id": "urn:id:skyocean:location:port:neworleans",
      "@type": ["http://schema.org/Place"],
      "http://schema.org/name": [{"@value": "Port of New Orleans"}],
      "http://schema.org/address": [{"@value": "New Orleans, Louisiana, USA"}]
    },
    {
      "@id": "urn:id:skyocean:location:port:tema",
      "@type": ["http://schema.org/Place"],
      "http://schema.org/name": [{"@value": "Port of Tema"}],
      "http://schema.org/address": [{"@value": "Tema, Ghana"}]
    }
  ]
}

4. Financial Instruments

The financial instrument knowledge asset represents payment mechanisms and guarantees:

{
  "assertion": [
    {
      "@id": "urn:id:skyocean:finance:CAD20240601",
      "@type": ["http://schema.org/FinancialProduct"],
      "http://schema.org/name": [{"@value": "Cash Against Documents Agreement"}],
      "http://schema.org/identifier": [{"@value": "CAD-2024-06-0001"}],
      "http://schema.org/financingType": [{"@value": "Platform Financing"}],
      "http://schema.org/issuer": [{"@id": "urn:id:skyocean:finance:platform"}],
      "http://schema.org/beneficiary": [{"@id": "urn:id:skyocean:sot"}],
      "http://schema.org/applicant": [{"@id": "urn:id:skyocean:customer:ghanaagro"}],
      "http://schema.org/amount": [{"@value": "USD 87,500"}],
      "http://schema.org/validFrom": [{"@value": "2024-06-10"}],
      "http://schema.org/validThrough": [{"@value": "2024-08-30"}],
      "http://schema.org/documentRequirements": [
        {"@value": "Clean Bill of Lading"},
        {"@value": "Commercial Invoice"},
        {"@value": "Packing List"},
        {"@value": "Certificate of Origin"},
        {"@value": "Phytosanitary Certificate"}
      ],
      "http://schema.org/paymentReleaseTrigger": [{"@value": "Documents Submission and Verification"}],
      "http://schema.org/relatedOrder": [{"@id": "urn:id:skyocean:po:2024060001"}],
      "http://schema.org/smartContractAddress": [{"@value": "0x4a8bc8e14A3A77F81D9D6C43B6852148e0b8CFBa"}]
    }
  ]
}

5. Inspection Certificates

The inspection certificate knowledge asset validates commodity quality:

{
  "assertion": [
    {
      "@id": "urn:id:skyocean:doc:inspection:2024060001",
      "@type": ["http://schema.org/Permit"],
      "http://schema.org/name": [{"@value": "Quality Inspection Certificate"}],
      "http://schema.org/identifier": [{"@value": "QIC-2024-06-0001"}],
      "http://schema.org/validFrom": [{"@value": "2024-06-15"}],
      "http://schema.org/issuedBy": [{"@id": "urn:id:skyocean:inspector:usagriculture"}],
      "http://schema.org/issuedThrough": [{"@value": "On-site inspection"}],
      "http://schema.org/permitAudience": [{"@value": "Trading partners"}],
      "http://schema.org/inspectedItem": [{"@id": "urn:id:skyocean:commodity:maize"}],
      "http://schema.org/result": [{"@value": "Passed"}],
      "http://schema.org/smartContractAddress": [{"@value": "0x4a8bc8e14A3A77F81D9D6C43B6852148e0b8CFBa"}],
      "http://schema.org/inspectionDetails": [
        {"@value": "Moisture content: 14.0%"},
        {"@value": "Broken kernels: <3%"},
        {"@value": "Foreign matter: <0.5%"}
      ],
      "http://schema.org/blockchainVerification": [{"@value": "true"}]
    },
    {
      "@id": "urn:id:skyocean:inspector:usagriculture",
      "@type": ["http://schema.org/Organization"],
      "http://schema.org/name": [{"@value": "US Agricultural Inspection Services"}]
    }
  ]
}

Implementation Guidelines

Transaction Asset Flow

The transactional knowledge assets follow a logical flow that mirrors the physical trading process:

Commodity Definition: Products are defined with specifications
Purchase Order Creation: Trading agreement is established
Financial Instrument Issuance: Payment security is arranged
Inspection & Certification: Quality verification is performed
Shipping Documentation: Logistics information is recorded

Asset Relationships

Transactional assets must maintain relationships across the process:

// Example relationship between assets
const relationships = {
  "urn:id:skyocean:po:2024060001": {
    "orderedItem": "urn:id:skyocean:commodity:maize",
    "financedBy": "urn:id:skyocean:finance:CAD20240601",
    "shipping": "urn:id:skyocean:shipping:BL20240601",
    "qualityVerification": "urn:id:skyocean:doc:inspection:2024060001",
    "smartContract": "0x4a8bc8e14A3A77F81D9D6C43B6852148e0b8CFBa"
  }
};

Public/Private Data Separation

Each transactional knowledge asset requires appropriate privacy controls:

// Example of public/private data separation for CAD financing
const financingAsset = {
  public: {
    assertion: [
      {
        "@id": "urn:id:skyocean:finance:CAD20240601",
        "@type": ["http://schema.org/FinancialProduct"],
        "http://schema.org/name": [{"@value": "Cash Against Documents Agreement"}],
        "http://schema.org/identifier": [{"@value": "CAD-2024-06-0001"}],
        "http://schema.org/financingType": [{"@value": "Platform Financing"}]
      }
    ]
  },
  private: {
    assertion: [
      {
        "@id": "urn:id:skyocean:finance:CAD20240601",
        "http://schema.org/amount": [{"@value": "USD 87,500"}],
        "http://schema.org/applicant": [{"@id": "urn:id:skyocean:customer:ghanaagro"}],
        "http://schema.org/financingFee": [{"@value": "3.5%"}],
        "http://schema.org/riskAssessment": [{"@value": "Medium"}]
      }
    ]
  }
};

Data Validation Rules

Transactional knowledge assets must adhere to specific validation rules:

Asset Type	Required Fields	Validation Rules
Commodity	name, sku, category	SKU format: [CATEGORY]-[PRODUCT]-[ORIGIN]-[TYPE]-[ID]
Purchase Order	orderNumber, orderDate, customer, orderedItem	Order number format: PO-YYYY-MM-NNNN
Shipping	trackingNumber, originAddress, deliveryAddress	Must reference valid PO
Financial	identifier, amount, validFrom, validThrough	Must reference valid customer and beneficiary
Inspection	identifier, issuedBy, result	Must reference valid commodity

Asset State Management

Transactional assets undergo state changes that must be recorded:

// Example of state transition management with smart contract integration
async function updateOrderStatus(orderID, newStatus, smartContractAddress) {
  // Retrieve the current asset
  const asset = await dkgClient.assets.get(orderID);
  
  // Update the status
  asset.public.assertion[0]["http://schema.org/orderStatus"] = [
    {"@value": newStatus}
  ];
  
  // Record update with state history
  asset.private.stateHistory = asset.private.stateHistory || [];
  asset.private.stateHistory.push({
    timestamp: new Date().toISOString(),
    previousStatus: asset.private.currentStatus,
    newStatus: newStatus,
    updatedBy: "system",
    smartContractEvent: newStatus === "PAYMENT_RELEASED" ? "FundsReleased" : ""
  });
  
  asset.private.currentStatus = newStatus;
  
  // For certain status changes, interact with the smart contract
  if (newStatus === "DOCUMENTS_VERIFIED" && smartContractAddress) {
    // Call the smart contract to approve documents
    const txHash = await blockchainService.callMethod(
      smartContractAddress,
      "approveDocuments",
      []
    );
    
    // Record the blockchain transaction
    asset.private.blockchainTransactions = asset.private.blockchainTransactions || [];
    asset.private.blockchainTransactions.push({
      timestamp: new Date().toISOString(),
      txHash: txHash,
      method: "approveDocuments",
      status: "SUBMITTED"
    });
  }
  
  // Update the asset on DKG
  return await dkgClient.assets.update(orderID, asset);
}

MVP Testing Strategy

For transactional knowledge assets, test the following scenarios:

Asset Creation Flow:
- Create a complete transaction sequence
- Verify all references and relationships
- Test state transitions
Document Verification:
- Test certificate creation and validation
- Verify document authenticity checks
- Test document approval workflows
Query Capabilities:
- Test retrieval by transaction ID
- Test filtering by status
- Test relationship traversal
Integration Testing:
- Test integration with institutional assets
- Verify smart contract triggers
- Test notifications and alerts

Implementation Sequence

For the MVP, implement the transactional assets in this order:

Commodity records
Purchase orders
Inspection certificates
Financial instruments
Shipping documentation

This sequence allows for incremental testing and validation of the core functionality before integrating more complex elements.

Security Considerations

Transactional knowledge assets require strict security measures:

Digital signatures for all certificates and financial instruments
Audit trail for all state changes
Timestamping for proof of existence
Role-based access to sensitive pricing and financial information

Next Steps

After implementing the transactional knowledge assets, the focus will shift to:

User interface development for asset visualization
Reporting and analytics functions
Smart contract integration for automated transactions
Partner API development for external system integration