@ixo/topic-protocol 0.8.0 → 1.0.0-rc.1

package/templates/decision-to-pay/README.md

@@ -1,17 +1,18 @@
 # Decision-to-Pay Topic template pack
 
-This directory publishes four draft, machine-readable Topic Templates for
+This directory publishes versioned, machine-readable Topic Templates for
 consequential payment decisions:
 
-1. [Verified Work Payment](verified-work-payment.template.json)
-2. [Payment on Delivery](payment-on-delivery.template.json)
-3. [Milestone Payment Release](milestone-payment-release.template.json)
-4. [Outcome Payment Claim](outcome-payment-claim.template.json)
+1. [Verified Work Payment v0.1](verified-work-payment.template.json) — the original generic contract extension, retained unchanged for compatibility.
+2. [Verified Work Payment v0.2](verified-work-payment.v0.2.template.json) — the Claims-native candidate that binds a Deed, Job Topic, scoped AuthZ, intent escrow, claim, signed evaluation receipt, payment and canonical dispute.
+3. [Payment on Delivery](payment-on-delivery.template.json)
+4. [Milestone Payment Release](milestone-payment-release.template.json)
+5. [Outcome Payment Claim](outcome-payment-claim.template.json)
 
-The manifests extend the Topic kinds, recipes, and external-work contracts in
-`@ixo/topic-protocol` 0.7.0. Their compatibility block pins the reviewed
-baseline commit and names every additional contract, capability policy, and
-adapter needed by an implementation.
+The v1 manifests extend the Topic kinds, recipes, and external-work contracts
+in `@ixo/topic-protocol` 0.7.0. Verified Work Payment v0.2 targets Topic
+Protocol 0.8.0 and the canonical IXO Claims and Evaluation Engine interfaces.
+Every compatibility block pins its reviewed baseline and required extensions.
 
 ## Shared contracts
 
@@ -26,17 +27,16 @@ adapter needed by an implementation.
 
 ## Trust boundary
 
-These artifacts are draft contract extensions. They do not grant a capability,
-verify a signature, establish eligibility, approve a claim, or move money.
-Topic Protocol operations and their referenced records remain authoritative for
-delivery, evaluation, approval, claim, and settlement state. A conforming
-runtime must verify DIDs, delegated capabilities, signatures, revocation,
-replay protection, funding, KYC or sanctions requirements, dispute holds,
-trusted time, and payment-rail finality before accepting a settlement receipt.
+These artifacts do not grant a capability, verify a signature, establish
+eligibility, approve a claim, or move money. For v1, Topic Protocol operations
+and referenced records are the projected authorities. For Verified Work
+Payment v0.2, the Deed owns the work package and the IXO Claims module owns
+intent, escrow, claim, evaluation, payment, deposits, disputes, and
+adjudication. A conforming runtime must verify DIDs, delegated capabilities,
+signatures, revocation, replay protection, funding, evidence and rubric digests
+before offering a chain transaction.
 
-The Payable Obligation is an envelope and index over those separate axes. Its
-`axisProjection` must be derived from referenced protocol records; it is not an
-alternative settlement authority.
+Neither Payable Obligation version is an alternative settlement authority.
 
 ## Draft and privacy rules
 
@@ -57,3 +57,11 @@ or profile. The milestone template uses one child Topic per payable milestone,
 so corrections do not become new milestones. Outcome Payment Claim assumes a
 Delivery Packet for the underlying intervention; claims without external work
 need a future generalised obligation handoff.
+
+The v2 Verified Work Payment contract deliberately uses separate schemas:
+
+- [`decision-to-pay-template-v2.schema.json`](../../schemas/decision-to-pay-template-v2.schema.json) fixes the authority model: Deed for the work package, Job Topic for the binder/thread, Claims for execution, Evaluation Engine for the signed determination, and Portal for orchestration.
+- [`payment-terms-v2.schema.json`](../../schemas/payment-terms-v2.schema.json) maps immutable accepted terms to Claim Collection, AuthZ, evaluation and dispute configuration.
+- [`payable-obligation-v2.schema.json`](../../schemas/payable-obligation-v2.schema.json) is a read-only projection of chain and receipt evidence; it cannot approve or settle.
+
+The v1 schemas and all other templates remain available and retain their original semantics.

package/templates/decision-to-pay/verified-work-payment.v0.2.template.json

@@ -0,0 +1,319 @@
+{
+  "$schema": "../../schemas/decision-to-pay-template-v2.schema.json",
+  "version": 2,
+  "id": "urn:ixo:decision-to-pay:template:verified-work-payment",
+  "templateVersion": "0.2.0",
+  "label": "Verified Work Payment",
+  "description": "Commission work through a Deed-bound Job, grant a selected Service Agent exact claim authority, escrow an intent, evaluate submitted evidence, and let the IXO Claims module record the determination and control payment.",
+  "maturity": "candidate",
+  "compatibility": {
+    "protocolPackage": "@ixo/topic-protocol",
+    "protocolVersion": "0.8.0",
+    "sourceCommit": "3cab2dd2f2606d33da588e9875c025eaea4b9e4c",
+    "claimsModule": "v8",
+    "sdkVersion": "3.0.0",
+    "implementationStatus": "candidate_contract",
+    "requiredExtensions": [
+      "org.ixo.payment-terms/v2",
+      "org.ixo.payable-obligation/v2",
+      "ixo.claims.v1beta1",
+      "ixo-evaluation-engine/signed-receipt"
+    ],
+    "constraints": [
+      "The Deed is the executable work-package authority; the Job Topic is its binder, message thread and projection.",
+      "The IXO Claims module is authoritative for intent, escrow, claim, evaluation, payment, deposits, disputes and adjudication.",
+      "The bounded mainnet pilot requires human-signed evaluations; capped automation is testnet-only until separately approved."
+    ]
+  },
+  "topic": {
+    "kind": "org.ixo.job-card",
+    "profile": "https://topic-protocol.ixo.world/profiles/job-card",
+    "domain": "deed",
+    "role": "contract_binder_and_message_thread",
+    "bindingPaths": {
+      "deed": "/bindings/deed",
+      "claimCollection": "/bindings/claimCollection",
+      "manifest": "/bindings/verifiedWorkPaymentManifest",
+      "claimSchema": "/bindings/claimSchema",
+      "rubric": "/bindings/rubric"
+    },
+    "lifecyclePolicy": {
+      "topicIsProjection": true,
+      "chainStateIsAuthoritative": true,
+      "resolveRule": "Resolve the Job only after the configured completion rule and a terminal Claims-module state; settlement alone does not rewrite the Job contract."
+    }
+  },
+  "authorities": {
+    "workPackage": "deed",
+    "conversation": "job_topic",
+    "claims": "ixo.claims.v1beta1",
+    "evaluation": "ixo_evaluation_engine",
+    "orchestration": "ixo_portal"
+  },
+  "actors": [
+    {
+      "role": "deed_owner",
+      "identity": "did",
+      "required": true,
+      "capabilities": ["deed/configure", "claims/authorise", "claims/pause"],
+      "constraints": ["Must control the Deed entity and its Claims admin account."]
+    },
+    {
+      "role": "payer",
+      "identity": "did",
+      "required": true,
+      "capabilities": ["claims/fund-intent"],
+      "constraints": ["Payment accounts must be entity accounts configured on the Claim Collection."]
+    },
+    {
+      "role": "service_agent",
+      "identity": "did",
+      "required": true,
+      "capabilities": ["bid/submit", "claim/intent", "claim/submit"],
+      "constraints": ["Claim and intent actions require the accepted bid's scoped SubmitClaimAuthorization."]
+    },
+    {
+      "role": "evaluation_engine",
+      "identity": "did",
+      "required": true,
+      "capabilities": ["claim/read-evidence", "evaluation/issue-receipt"],
+      "constraints": ["May submit MsgEvaluateClaim only when an explicit environment-specific chain grant and policy enable automation."]
+    },
+    {
+      "role": "human_evaluator",
+      "identity": "did",
+      "required": true,
+      "capabilities": ["claim/evaluate"],
+      "constraints": ["A changed determination requires a newly issued final receipt before signing MsgEvaluateClaim."]
+    },
+    {
+      "role": "adjudicator",
+      "identity": "did",
+      "required": true,
+      "capabilities": ["claim/adjudicate-dispute"],
+      "constraints": ["Must be whitelisted by the Claim Collection and sign the canonical resolution payload."
+      ]
+    }
+  ],
+  "resources": [
+    {
+      "role": "deed",
+      "type": "ixo.iid.entity.deed",
+      "required": true,
+      "authority": "deed",
+      "binding": "topic_binding",
+      "confidentiality": "public",
+      "notes": "Owns the executable work package and Claim Collection."
+    },
+    {
+      "role": "payment_terms",
+      "type": "org.ixo.payment-terms",
+      "required": true,
+      "authority": "bound_resource",
+      "binding": "deed_linked_resource",
+      "schemaRef": "https://topic-protocol.ixo.world/schemas/payment-terms-v2.schema.json",
+      "confidentiality": "vfs_ucan"
+    },
+    {
+      "role": "payable_obligation",
+      "type": "org.ixo.payable-obligation",
+      "required": true,
+      "authority": "ixo_claims_module",
+      "binding": "claims_record",
+      "schemaRef": "https://topic-protocol.ixo.world/schemas/payable-obligation-v2.schema.json",
+      "confidentiality": "room_encrypted",
+      "notes": "Read-only projection; cannot approve, settle or reverse payment."
+    },
+    {
+      "role": "bid_schema",
+      "type": "surveyjs.bid",
+      "required": true,
+      "authority": "deed",
+      "binding": "deed_linked_resource",
+      "confidentiality": "vfs_ucan"
+    },
+    {
+      "role": "claim_schema",
+      "type": "surveyjs.claim",
+      "required": true,
+      "authority": "deed",
+      "binding": "deed_linked_resource",
+      "confidentiality": "vfs_ucan"
+    },
+    {
+      "role": "claim_collection",
+      "type": "ixo.claims.v1beta1.Collection",
+      "required": true,
+      "authority": "ixo_claims_module",
+      "binding": "claims_record",
+      "confidentiality": "claims_module"
+    },
+    {
+      "role": "rubric",
+      "type": "ixo.evaluation.rubric",
+      "required": true,
+      "authority": "deed",
+      "binding": "deed_linked_resource",
+      "confidentiality": "vfs_ucan"
+    },
+    {
+      "role": "evaluation_receipt",
+      "type": "ixo.udid.impact-determination",
+      "required": true,
+      "authority": "evaluation_engine",
+      "binding": "content_addressed_receipt",
+      "confidentiality": "room_encrypted"
+    },
+    {
+      "role": "evidence",
+      "type": "ixo.vfs",
+      "required": true,
+      "authority": "bound_resource",
+      "binding": "vfs_attachment",
+      "confidentiality": "vfs_ucan"
+    }
+  ],
+  "lifecycle": [
+    {
+      "sequence": 1,
+      "id": "validate-deed",
+      "authority": "deed",
+      "preconditions": ["All constitutional, instruction, schema, collection, rubric, service, capability and funding checks pass."],
+      "result": "A content-addressed readiness report authorises Job launch."
+    },
+    {
+      "sequence": 2,
+      "id": "create-job-topic",
+      "authority": "job_topic",
+      "preconditions": ["The Topic is created inside the validated Deed domain with every required binding."],
+      "result": "The Job binder and participant message thread exist without becoming payment authority."
+    },
+    {
+      "sequence": 3,
+      "id": "submit-bid",
+      "authority": "bids_service",
+      "preconditions": ["The Service Agent uses the Deed bid schema and signs the bid."],
+      "result": "A pending bid binds provider identity, price, quota, intent duration and expiry."
+    },
+    {
+      "sequence": 4,
+      "id": "accept-bid-and-grant",
+      "authority": "cosmos_authz",
+      "messageType": "/cosmos.authz.v1beta1.MsgGrant",
+      "preconditions": ["The accepted bid values pass the Payment Terms and collection caps."],
+      "result": "The selected Service Agent receives an exact SubmitClaimAuthorization."
+    },
+    {
+      "sequence": 5,
+      "id": "claim-intent",
+      "authority": "ixo_claims_module",
+      "messageType": "/ixo.claims.v1beta1.MsgClaimIntent",
+      "preconditions": ["Collection intent policy permits the action and the scoped grant covers the amount and duration."],
+      "result": "The Claims module records an active intent and escrows the configured funds."
+    },
+    {
+      "sequence": 6,
+      "id": "submit-claim",
+      "authority": "ixo_claims_module",
+      "messageType": "/ixo.claims.v1beta1.MsgSubmitClaim",
+      "preconditions": ["Work evidence validates against the bound claim schema and the required intent is active."],
+      "result": "The Claims module records the evidence-bound claim."
+    },
+    {
+      "sequence": 7,
+      "id": "evaluate-evidence",
+      "authority": "evaluation_engine",
+      "preconditions": ["Claim, collection, Deed, claim schema, rubric and evidence digests all match."],
+      "result": "The engine normalises facts, applies the rubric and issues a signed UDID Impact Determination receipt."
+    },
+    {
+      "sequence": 8,
+      "id": "record-evaluation",
+      "authority": "ixo_claims_module",
+      "messageType": "/ixo.claims.v1beta1.MsgEvaluateClaim",
+      "preconditions": ["The authorised signer verifies that the receipt and proposed chain status match exactly."],
+      "result": "The Claims module records APPROVED, REJECTED, FLAGGED or INVALIDATED and applies canonical payment rules."
+    },
+    {
+      "sequence": 9,
+      "id": "project-payment",
+      "authority": "ixo_claims_module",
+      "preconditions": ["Portal reads payment state from Claims and Blocksync instead of a local settlement state machine."],
+      "result": "The Job displays the authoritative payment status and transaction reference."
+    },
+    {
+      "sequence": 10,
+      "id": "dispute-and-adjudicate",
+      "authority": "ixo_claims_module",
+      "messageType": "/ixo.claims.v1beta1.MsgDisputeClaim",
+      "preconditions": ["The disputing DID is registered and deposits and adjudicators are configured."],
+      "result": "A canonical dispute is opened; a whitelisted adjudicator later resolves it with MsgAdjudicateDispute."
+    }
+  ],
+  "capabilityPolicy": {
+    "submitClaimAuthorization": {
+      "typeUrl": "/ixo.claims.v1beta1.SubmitClaimAuthorization",
+      "requiredConstraints": ["collectionId", "agentQuota", "maxAmount", "intentDurationNs", "memberAddress"],
+      "deriveFromAcceptedBid": true,
+      "expiryBound": "min(job_end,collection_end)"
+    },
+    "evaluateClaimAuthorization": {
+      "typeUrl": "/ixo.claims.v1beta1.EvaluateClaimAuthorization",
+      "requiredConstraints": ["collectionId", "claimIds", "agentQuota", "beforeDate", "maxCustomAmount"],
+      "expiryBound": "collection_end"
+    },
+    "engineUcan": {
+      "abilities": ["ixo:matrix-claims-bot", "subscriptions/read"],
+      "audienceBound": true,
+      "resourceBound": true,
+      "timeBound": true,
+      "revocable": true,
+      "environmentBound": true
+    },
+    "revocationTriggers": ["job_cancelled", "job_completed", "job_expired", "bidder_removed", "security_incident"]
+  },
+  "pilotPolicy": {
+    "intentPolicy": "REQUIRED",
+    "assetType": "native",
+    "payoutTimeoutNs": "0",
+    "mainnetEvaluationMode": "HUMAN_SIGNED",
+    "testnetAutomation": "CAPPED",
+    "deferredFeatures": ["cw20", "cw1155", "team_budgets", "delayed_withdrawal", "mainnet_automation", "other_decision_to_pay_templates"]
+  },
+  "settlement": {
+    "templateMovesFunds": false,
+    "claimsModuleMovesFunds": true,
+    "authority": "ixo.claims.v1beta1",
+    "adapter": "canonical_impactxclient_sdk",
+    "approvalTrigger": "MsgEvaluateClaim(APPROVED)",
+    "disputeRecourse": "deposit_slashing_and_adjudication_not_payment_reversal"
+  },
+  "privacy": {
+    "topicIsConfidentialityBoundary": false,
+    "topicCapabilityGrantsVfsAccess": false,
+    "sensitiveResourceStorage": "encrypted_room_or_ucan_vfs",
+    "receiptExcludesPii": true
+  },
+  "acceptanceCriteria": [
+    {
+      "id": "deed-ready",
+      "statement": "Job launch is impossible until the complete Deed work package passes readiness checks.",
+      "verification": "Negative fixtures omit each required resource and assert launch remains blocked."
+    },
+    {
+      "id": "least-authority",
+      "statement": "An accepted bid grants only the negotiated claim scope and rejected, expired or excessive actions fail.",
+      "verification": "Inspect the decoded authz grant and execute negative chain vectors."
+    },
+    {
+      "id": "proof-to-payment",
+      "statement": "Required intent, evidence-bound claim, signed receipt and human evaluation produce the exact Claims-module payment.",
+      "verification": "Publish real-wallet transaction hashes, receipt CID and payment projection from testnet."
+    },
+    {
+      "id": "flag-and-dispute",
+      "statement": "FLAGGED is non-terminal and unpaid; canonical disputes lock deposits and require whitelisted adjudication.",
+      "verification": "Run flag, re-evaluation, awarded-dispute and dismissed-dispute conformance vectors."
+    }
+  ]
+}