xytara 1.0.0

package/adapters/adapter-manifest.schema.json

@@ -0,0 +1,209 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "xytara/adapter-manifest.schema.json",
+  "title": "xytara Adapter Manifest",
+  "type": "object",
+  "additionalProperties": false,
+  "required": [
+    "adapter_id",
+    "adapter_class",
+    "adapter_version",
+    "interface_version",
+    "display_name",
+    "description",
+    "capabilities",
+    "compatibility",
+    "health_contract",
+    "idempotency_contract",
+    "failure_contract",
+    "proof_contract"
+  ],
+  "properties": {
+    "adapter_id": {
+      "type": "string",
+      "minLength": 1
+    },
+    "adapter_class": {
+      "type": "string",
+      "enum": [
+        "execution_adapter",
+        "payment_rail_adapter",
+        "settlement_adapter",
+        "agent_protocol_adapter",
+        "identity_registry_adapter"
+      ]
+    },
+    "adapter_version": {
+      "type": "string",
+      "minLength": 1
+    },
+    "interface_version": {
+      "type": "string",
+      "minLength": 1
+    },
+    "display_name": {
+      "type": "string",
+      "minLength": 1
+    },
+    "description": {
+      "type": "string",
+      "minLength": 1
+    },
+    "capabilities": {
+      "type": "array",
+      "minItems": 1,
+      "items": {
+        "type": "string",
+        "minLength": 1
+      }
+    },
+    "compatibility": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": [
+        "node",
+        "commerce_contract",
+        "proof_contract"
+      ],
+      "properties": {
+        "node": {
+          "type": "string",
+          "minLength": 1
+        },
+        "commerce_contract": {
+          "type": "string",
+          "minLength": 1
+        },
+        "proof_contract": {
+          "type": "string",
+          "minLength": 1
+        }
+      }
+    },
+    "health_contract": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": [
+        "check_kind",
+        "supports_readiness"
+      ],
+      "properties": {
+        "check_kind": {
+          "type": "string",
+          "minLength": 1
+        },
+        "supports_readiness": {
+          "type": "boolean"
+        }
+      }
+    },
+    "idempotency_contract": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": [
+        "strategy",
+        "scope"
+      ],
+      "properties": {
+        "strategy": {
+          "type": "string",
+          "minLength": 1
+        },
+        "scope": {
+          "type": "string",
+          "minLength": 1
+        }
+      }
+    },
+    "failure_contract": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": [
+        "categories",
+        "retryable_categories"
+      ],
+      "properties": {
+        "categories": {
+          "type": "array",
+          "minItems": 1,
+          "items": {
+            "type": "string",
+            "minLength": 1
+          }
+        },
+        "retryable_categories": {
+          "type": "array",
+          "items": {
+            "type": "string",
+            "minLength": 1
+          }
+        }
+      }
+    },
+    "proof_contract": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": [
+        "emits_proof_compatible_facts",
+        "proof_mode"
+      ],
+      "properties": {
+        "emits_proof_compatible_facts": {
+          "type": "boolean"
+        },
+        "proof_mode": {
+          "type": "string",
+          "minLength": 1
+        }
+      }
+    },
+    "latency_class": {
+      "type": "string"
+    },
+    "pricing_basis": {
+      "type": "string"
+    },
+    "execution_modes": {
+      "type": "array",
+      "items": {
+        "type": "string",
+        "minLength": 1
+      }
+    },
+    "required_secrets": {
+      "type": "array",
+      "items": {
+        "type": "string",
+        "minLength": 1
+      }
+    },
+    "required_permissions": {
+      "type": "array",
+      "items": {
+        "type": "string",
+        "minLength": 1
+      }
+    },
+    "supported_profiles": {
+      "type": "array",
+      "items": {
+        "type": "string",
+        "minLength": 1
+      }
+    },
+    "supported_regions": {
+      "type": "array",
+      "items": {
+        "type": "string",
+        "minLength": 1
+      }
+    },
+    "supported_settlement_modes": {
+      "type": "array",
+      "items": {
+        "type": "string",
+        "minLength": 1
+      }
+    }
+  }
+}

package/adapters/examples/example-execution-adapter.js

@@ -0,0 +1,61 @@
+"use strict";
+
+const fs = require("fs");
+const path = require("path");
+
+const manifest = JSON.parse(
+  fs.readFileSync(path.resolve(__dirname, "example-execution-adapter.manifest.json"), "utf8")
+);
+
+async function getHealth() {
+  return {
+    status: "ok",
+    readiness: "ready",
+    adapter_id: manifest.adapter_id
+  };
+}
+
+function describeCapabilities() {
+  return {
+    adapter_id: manifest.adapter_id,
+    adapter_class: manifest.adapter_class,
+    capabilities: manifest.capabilities.slice(),
+    execution_modes: Array.isArray(manifest.execution_modes) ? manifest.execution_modes.slice() : []
+  };
+}
+
+async function preview(request) {
+  return {
+    adapter_id: manifest.adapter_id,
+    accepted: true,
+    preview: {
+      task_ref: request && request.task_ref ? request.task_ref : "example.task",
+      mode: "preview",
+      echoed_body: request && request.body ? request.body : {}
+    }
+  };
+}
+
+async function execute(request) {
+  return {
+    adapter_id: manifest.adapter_id,
+    status: "completed",
+    result: {
+      task_ref: request && request.task_ref ? request.task_ref : "example.task",
+      mode: "execute",
+      echoed_body: request && request.body ? request.body : {}
+    },
+    proof_facts: {
+      emits_proof_compatible_facts: manifest.proof_contract.emits_proof_compatible_facts,
+      proof_mode: manifest.proof_contract.proof_mode
+    }
+  };
+}
+
+module.exports = {
+  manifest,
+  getHealth,
+  describeCapabilities,
+  preview,
+  execute
+};

package/adapters/examples/example-execution-adapter.manifest.json

@@ -0,0 +1,62 @@
+{
+  "adapter_id": "example.execution.echo",
+  "adapter_class": "execution_adapter",
+  "adapter_version": "1.0.0",
+  "interface_version": "commerce-adapter-interface/v1",
+  "display_name": "Example Echo Execution Adapter",
+  "description": "Reference execution adapter manifest used to validate adapter contract shape.",
+  "capabilities": [
+    "task.execute",
+    "task.validate",
+    "task.preview"
+  ],
+  "compatibility": {
+    "node": ">=18",
+    "commerce_contract": "commerce-repo-final-contract/v1",
+    "proof_contract": "proof-repo-final-contract/v1"
+  },
+  "health_contract": {
+    "check_kind": "self_reported",
+    "supports_readiness": true
+  },
+  "idempotency_contract": {
+    "strategy": "caller_supplied_key",
+    "scope": "task_execution"
+  },
+  "failure_contract": {
+    "categories": [
+      "invalid_input",
+      "timeout",
+      "upstream_unavailable"
+    ],
+    "retryable_categories": [
+      "timeout",
+      "upstream_unavailable"
+    ]
+  },
+  "proof_contract": {
+    "emits_proof_compatible_facts": true,
+    "proof_mode": "execution_facts_only"
+  },
+  "latency_class": "interactive",
+  "pricing_basis": "per_task",
+  "execution_modes": [
+    "sync",
+    "waited"
+  ],
+  "required_secrets": [
+    "EXAMPLE_EXECUTION_TOKEN"
+  ],
+  "required_permissions": [
+    "network:outbound"
+  ],
+  "supported_profiles": [
+    "default"
+  ],
+  "supported_regions": [
+    "global"
+  ],
+  "supported_settlement_modes": [
+    "none"
+  ]
+}

package/adapters/examples/example-settlement-adapter.js

@@ -0,0 +1,55 @@
+"use strict";
+
+const fs = require("fs");
+const path = require("path");
+
+const manifest = JSON.parse(
+  fs.readFileSync(path.resolve(__dirname, "example-settlement-adapter.manifest.json"), "utf8")
+);
+
+async function getHealth() {
+  return {
+    status: "ok",
+    readiness: "ready",
+    adapter_id: manifest.adapter_id
+  };
+}
+
+function describeCapabilities() {
+  return {
+    adapter_id: manifest.adapter_id,
+    adapter_class: manifest.adapter_class,
+    capabilities: manifest.capabilities.slice(),
+    supported_settlement_modes: Array.isArray(manifest.supported_settlement_modes)
+      ? manifest.supported_settlement_modes.slice()
+      : []
+  };
+}
+
+async function settle(request) {
+  return {
+    adapter_id: manifest.adapter_id,
+    status: "submitted",
+    settlement_ref: `anchor://${request && request.intent_id ? request.intent_id : "demo-intent"}`,
+    proof_facts: {
+      emits_proof_compatible_facts: manifest.proof_contract.emits_proof_compatible_facts,
+      proof_mode: manifest.proof_contract.proof_mode
+    }
+  };
+}
+
+async function getFinality(reference) {
+  return {
+    adapter_id: manifest.adapter_id,
+    settlement_ref: reference,
+    finality_status: "confirmed"
+  };
+}
+
+module.exports = {
+  manifest,
+  getHealth,
+  describeCapabilities,
+  settle,
+  getFinality
+};

package/adapters/examples/example-settlement-adapter.manifest.json

@@ -0,0 +1,59 @@
+{
+  "adapter_id": "example.settlement.anchor",
+  "adapter_class": "settlement_adapter",
+  "adapter_version": "1.0.0",
+  "interface_version": "commerce-adapter-interface/v1",
+  "display_name": "Example Settlement Anchor Adapter",
+  "description": "Reference settlement adapter manifest used to validate settlement-side adapter contract shape.",
+  "capabilities": [
+    "settlement.submit",
+    "settlement.finality",
+    "settlement.reference"
+  ],
+  "compatibility": {
+    "node": ">=18",
+    "commerce_contract": "commerce-repo-final-contract/v1",
+    "proof_contract": "proof-repo-final-contract/v1"
+  },
+  "health_contract": {
+    "check_kind": "self_reported",
+    "supports_readiness": true
+  },
+  "idempotency_contract": {
+    "strategy": "caller_supplied_key",
+    "scope": "settlement_request"
+  },
+  "failure_contract": {
+    "categories": [
+      "invalid_input",
+      "timeout",
+      "upstream_unavailable",
+      "settlement_failure"
+    ],
+    "retryable_categories": [
+      "timeout",
+      "upstream_unavailable"
+    ]
+  },
+  "proof_contract": {
+    "emits_proof_compatible_facts": true,
+    "proof_mode": "settlement_reference_only"
+  },
+  "latency_class": "governed_async",
+  "required_secrets": [
+    "EXAMPLE_SETTLEMENT_TOKEN"
+  ],
+  "required_permissions": [
+    "network:outbound"
+  ],
+  "supported_profiles": [
+    "default",
+    "anchored"
+  ],
+  "supported_regions": [
+    "global"
+  ],
+  "supported_settlement_modes": [
+    "anchor_commit"
+  ]
+}

package/adapters/interfaces.js

@@ -0,0 +1,56 @@
+"use strict";
+
+const ADAPTER_INTERFACE_VERSION = "commerce-adapter-interface/v1";
+
+function isPlainObject(value) {
+  return value !== null && typeof value === "object" && !Array.isArray(value);
+}
+
+function validateAdapterImplementation(adapter) {
+  const errors = [];
+  if (!isPlainObject(adapter)) {
+    errors.push("adapter must be an object");
+    return errors;
+  }
+
+  if (!isPlainObject(adapter.manifest)) {
+    errors.push("adapter.manifest must be an object");
+  }
+
+  if (typeof adapter.getHealth !== "function") {
+    errors.push("adapter.getHealth must be a function");
+  }
+
+  if (typeof adapter.describeCapabilities !== "function") {
+    errors.push("adapter.describeCapabilities must be a function");
+  }
+
+  if (adapter.manifest && adapter.manifest.adapter_class === "execution_adapter") {
+    if (typeof adapter.execute !== "function") {
+      errors.push("execution adapters must implement execute");
+    }
+    if (typeof adapter.preview !== "function") {
+      errors.push("execution adapters should implement preview");
+    }
+  }
+
+  if (adapter.manifest && adapter.manifest.adapter_class === "settlement_adapter") {
+    if (typeof adapter.settle !== "function") {
+      errors.push("settlement adapters must implement settle");
+    }
+    if (typeof adapter.getFinality !== "function") {
+      errors.push("settlement adapters should implement getFinality");
+    }
+  }
+
+  if (adapter.manifest && adapter.manifest.interface_version !== ADAPTER_INTERFACE_VERSION) {
+    errors.push(`adapter.manifest.interface_version must be ${ADAPTER_INTERFACE_VERSION}`);
+  }
+
+  return errors;
+}
+
+module.exports = {
+  ADAPTER_INTERFACE_VERSION,
+  validateAdapterImplementation
+};

package/client.js

@@ -0,0 +1,3 @@
+"use strict";
+
+module.exports = require("./lib/commerce_client");