Catena-X Integration | Supply-Y Protocol Docs

Transport decision

Reuse EDC when both companies already have an approved path.

The Package contract stays the same. Catena-X replaces the payload transport, not Supply-Y Skills, Thread semantics, receipts or audit.

Both sides have approved EDC: Catena-X Mode
Either side lacks EDC: Native Mode
Thread already started: Do not switch silently

One collaboration, three clear owners

EDC moves bytes; Supply-Y coordinates the decision loop

Customer AgentsCreate, approve, encrypt, verify and decrypt

Business plaintext and private keys remain in customer-controlled environments.

EDC connectorsCatalog, contract and peer-to-peer transfer

The exact encrypted Package bytes move once through the EDC data plane.

Supply-YIdentity, manifest, Thread, receipts and audit

Supply-Y stores references and state, not a duplicate Catena-X payload.

Exact exchange sequence

One Package, one EDC asset, one auditable outcome

01
Sender AgentBuild Package
Apply the Skill and local approval to one bounded business object.
02
Sender AgentProtect bytes
Encrypt for the participants and sign before the Package leaves.
03
Sender EDCPublish asset
Publish those exact encrypted and signed bytes as one EDC asset.
04
Supply-Y APIAccept manifest
Verify the signed control manifest and bind Package, asset and digest.
05
EDC data planeTransfer once
Negotiate and move the Package peer-to-peer without a Native copy.
06
Recipient AgentVerify and open
Check asset digest and sender signature, then decrypt locally.
07
Supply-Y threadRecord outcome
Retain receipts, normalized state and ciphertext-safe audit evidence.

Validated API example

`POST /v1/packages`

The request carries authenticated Package metadata and EDC references instead of a second ciphertext body.

{
  "transport_mode": "catena_x",
  "metadata": {
    "package_id": "pkg_material_constraint_001",
    "thread_id": "thread_material_constraint_01",
    "protocol_version": "supply-y/1.0",
    "skill": "supply-y.material-risk@0.1.0",
    "content_digest": "sha-256=:0lYf4IyJ08r4292s/NJvaKu1JXi5cjXjaT0HNpt6r04=:"
  },
  "edc": {
    "connector_id": "edc_tier3_001",
    "asset_id": "asset_pkg_material_constraint_001",
    "asset_digest": "sha-256=:AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA=:",
    "contract_agreement_id": "contract_agreement_001",
    "transfer_process_id": "transfer_process_001"
  },
  "sender_signature": {
    "key_id": "key_agent_signing_001",
    "algorithm": "ES256"
  }
}

Inspect the complete API contract

Executable reference evidence

26 checks passed across 10 Agent processes

Node.js sender (JOSE) · Python recipient (cryptography and dependency-free schema validator) · Node.js receipt verifier (WebCrypto)

Node.js processes: 6
Python processes: 4
Supply-Y payload copies: 0
Audit events: 6
Package identity: Preserved
Python recipient: Verified

Open machine evidence

Status: Live integration guide for Supply-Y Protocol 1.0. It explains the current Catena-X transport contract and executable local evidence; it does not claim a completed partner EDC certification.

When to select Catena-X Mode

Select Catena-X Mode only when both participating companies already operate compatible, approved EDC connectors for the intended exchange. Otherwise use Native Mode.

The transport mode is fixed for the lifetime of a Loop Thread. Do not switch an active thread silently. Start a new thread with an explicit configuration decision if the transport path changes.

Responsibility split

Owner	Responsibility
Customer Agent	Creates the bounded business object, applies the approved Skill and local policy, encrypts and signs the Package, publishes the exact bytes as an EDC asset, verifies inbound bytes and decrypts locally
Customer EDC connectors	Asset catalog, contract negotiation, usage-policy enforcement and peer-to-peer data-plane transfer
Supply-Y	One Agent-facing API, Package and Thread identities, signed control-manifest verification, normalized state, notifications, receipts and ciphertext-safe audit evidence

Supply-Y does not become a second data plane. It does not upload the Catena-X Package into Native object storage.

What the customer configures

Both companies need registered Agents that advertise catena_x, approved connector identities and a customer-local Connection Profile. The Catena-X transport branch requires two typed references:

transport.edc_connector_reference points to customer-controlled connector configuration;
transport.edc_policy_profile_reference points to the approved EDC policy profile.

Customers also retain their OAuth credentials, EDC secrets, private keys, data mappings, Skill approval and decrypted Package content. Supply-Y receives references and signed evidence, not those secrets.

One Package, one transport

The sender creates the same encrypted and signed Supply-Y wire Package used by the Native contract, then publishes those exact bytes as one EDC asset. The signed Catena-X control manifest binds the Package metadata to the connector, asset and exact RFC 9530 asset digest.

contract_agreement_id and transfer_process_id are included when available. The recipient verifies the asset digest before verifying the sender signature and decrypting the Package locally.

The same Package must not be sent through Native storage as a fallback copy. A transfer failure remains a Catena-X thread failure and follows explicit retry, recovery or exit handling.

Policy split

EDC contract and usage-policy controls are the right layer for participant access, contract negotiation, purpose and any supported retention or forwarding obligations.

Supply-Y Skills and customer Agents remain responsible for Package field rules, prohibited disclosures, confidence and known-unknown requirements, human approval, response obligations, tool boundaries, Thread state and Network Story semantics. An EDC contract does not prove that the sender's hidden business facts are true or that every application-level rule ran honestly.

Failure and recovery

Contract negotiation, transfer processing, Supply-Y control-plane acceptance, recipient verification and recipient receipt are separate states. One success does not imply the others succeeded.

Use stable Package and transfer identifiers, idempotent API submission, signed notifications, ordered polling and explicit receipts. If an asset digest, sender signature, recipient identity or policy binding fails, reject the transfer instead of silently creating a Native copy.

Current evidence and limit

The committed cross-language reference harness proves that Native and Catena-X preserve the same Package identity, content digest and object semantics. A Node.js sender transfers exact signed and encrypted bytes to a Python recipient, which verifies, decrypts, schema-validates and signs the receipt. The Catena-X run creates one simulated EDC asset, zero Native objects and zero Supply-Y payload copies, then produces a valid append-only audit chain.

This is executable contract evidence, not external EDC certification. The Node.js and Python implementations are both maintained in this repository, and the EDC path is a deterministic local adapter. The public hosted Sandbox tests Native Mode with fictional data; a real partner connector run, an independently maintained external Agent and customer KMS or HSM evidence remain required before a production claim.

Common integration mistakes

Sending the Package through EDC and Native storage “for reliability.” This creates two payload paths and violates the one-transport rule.
Adding connector, asset or transfer fields inside the business object. Transport routing belongs in authenticated delivery metadata and the signed control manifest.
Assuming an EDC usage policy replaces Supply-Y field, reasoning, approval or tool controls.
Storing customer EDC credentials in Supply-Y application tables instead of a protected secret flow.
Treating the local reference adapter as proof of partner EDC interoperability.

Inspect the exact CatenaXPackageCreate contract, the two-Agent interoperability evidence, or Plan a Managed Pilot with one agreed transport path.

On this page