SUPPLYCHAIN.md

A Bridge, Not a Replacement

This isn't another logistics standard to replace EDIFACT, DCSA, or IATA ONE Record. It's a recognition that autonomous agents need a meta-layer to navigate the Byzantine maze of existing protocols. When machines orchestrate supply chains, they need translation, not revolution.

The reality: Ocean freight operates in hours and days, not milliseconds. Carriers negotiate space over email. Customs requires paper documents. Banks need wet signatures. This protocol acknowledges these constraints while enabling agent coordination where possible.

SUPPLYCHAIN.md proposes a pragmatic wrapper — mapping agent intents to industry standards, bridging incompatible systems, and providing event consistency across fragmented infrastructure.

Living Protocol

Returns versioned schemas, conformance tests, and transformation mappings to industry standards (DCSA → JSON, EDIFACT → JSON, etc.). The endpoint itself is hypothetical — but something like it will emerge.

The Translation Challenge

Your agent encounters: IATA ONE Record for air cargo, DCSA for ocean events, GS1 EPCIS for tracking, ISO 20022 for payments, FIATA eFBL for documents, and hundreds of proprietary carrier APIs.

No universal protocol will replace these overnight. Instead, agents need a translation layer that speaks all dialects while maintaining semantic consistency.

Realistic Coordination Model

POST /announce
{
  "agent_id": "freight_sf_8k2x",
  "capabilities": ["ocean_freight", "ltl", "customs"],
  "coverage": ["US_WEST", "TRANS_PACIFIC"],
  "quote_sla_minutes": 15,  // Not milliseconds
  "service_windows": {
    "ocean": "weekly_sailings",
    "response_time": "business_hours_PST"
  },
  "jurisdictions": ["US", "CN", "SG"],
  "standards_supported": ["DCSA", "EDIFACT", "JSON"]
}

// Step 1: Quote (async, may take minutes/hours)
POST /quote
{
  "origin": "CNSHA",  // UN/LOCODE
  "destination": "USOAK",
  "incoterms": "FOB",
  "cargo": {
    "hs_code": "8471.30",
    "weight_kg": 5000,
    "volume_cbm": 45,
    "dangerous_goods_class": null,
    "temperature_range_c": [2, 8]
  },
  "constraints": {
    "preferred_transit_days": 14,  // Soft constraint
    "max_cost_usd": 15000,
    "required_by": "2025-09-30T00:00:00Z"
  }
}

// Step 2: Hold (with TTL)
POST /hold
{
  "quote_id": "q_9k3m2x",
  "hold_until": "2025-08-27T17:00:00Z"
}

// Step 3: Book (after KYC/compliance)
POST /book
{
  "hold_id": "h_7x2k4m",
  "shipper": {...},  // Full legal entity
  "consignee": {...},
  "notify_party": {...},
  "letter_of_credit": "LC123456"
}

// Step 4: Document issuance
POST /issue/bill-of-lading
{
  "booking_id": "bk_4k2m8x",
  "type": "negotiable",
  "copies": 3
}

WebSocket: wss://supplychain.md/events

{
  "eventTime": "2025-09-15T14:00:00Z",
  "eventType": "ObjectEvent",
  "bizStep": "departing",
  "disposition": "in_transit",
  "readPoint": "geo:31.2304,121.4737",
  "bizLocation": "CNSHA",
  "source": {
    "type": "carrier",
    "id": "MAEU",
    "signature": "0x7f9..."  // Signed attestation
  },
  "objects": ["urn:epc:id:sscc:0614141.1234567890"],
  "extensions": {
    "vessel_imo": "9811000",
    "new_eta": "2025-09-30T06:00:00Z",
    "confidence": 0.85
  }
}

Standards Alignment

The protocol provides canonical JSON schemas with bidirectional transformations. Your agent speaks JSON; the protocol handles EDIFACT/X12/XML translation.

Trust & Identity

// DID-based agent identity
{
  "agent_did": "did:web:supplychain.md:agent:7x9k2",
  "operator_did": "did:web:example.com",
  "credentials": [
    {
      "type": "ForwarderLicense",
      "issuer": "did:web:fmc.gov",
      "number": "FF-12345"
    }
  ],
  "attestations": {
    "kyc": "0x8f2...",  // Privacy-preserving proof
    "aml": "0x9a3..."
  }
}

Every action requires appropriate credentials. Every event includes cryptographic provenance. Audit trails are immutable.

Realistic Features

Implementation Considerations

Roadmap

Open Development

This document is published under MIT License (code examples) and CC-BY 4.0 (specification) to enable open collaboration while maintaining attribution.

We include a defensive patent pledge: No patents will be sought on these protocols. Prior art established 2025-08-26T12:00:00Z.

Contact

📧 proofmdorg@gmail.com