Version the skill around V1 production and V2 beta protocol profiles

README.md

@@ -2,6 +2,8 @@
 
 # Trustless Work Development Skill
 
+> **Protocol version: V1.** This file documents the production V1 integration — the only version deployed on mainnet. The V2 API, React SDK and Blocks surfaces are **not** documented in this skill yet; for the contract-level differences between V1 and V2 see [constitution.md](constitution.md).
+
 [View on skills.sh](https://www.skills.sh/trustless-work/trustlesswork-skill)
 
 A comprehensive AI skill for developing with the Trustless Work platform - enabling escrow contracts, milestone-based payments, and dispute resolution on the Stellar blockchain.

SKILL.md

@@ -31,9 +31,21 @@ Install this skill using:
 npx skills add trustless-work/trustlesswork-skill
 ```
 
+### Protocol version — read this first
+
+Trustless Work has two protocol versions, and they are not interchangeable.
+
+- **V1 is production and the default.** It is the only version deployed on mainnet. Build every normal integration from [skills/protocol/v1.md](skills/protocol/v1.md).
+- **V2 is beta and testnet-only.** It is deployed on testnet, so you can build on it there — see [skills/protocol/v2.md](skills/protocol/v2.md) — but never on mainnet while it is beta, and never as the recommended production path. Say it is beta every time.
+- **Explaining V2 is always in scope.** Answer any V2 question; the restriction is which network you target, not whether the user said "beta".
+- **Never mix them.** Roles, payload shapes, approval semantics and lifecycle rules belong to one version at a time.
+- **If the version is ambiguous, use V1** and state which version you are describing.
+
+Escrow type (single-release or multi-release) and protocol version are independent: there is a V1 and a V2 of each. Always know both before writing code.
+
 ### When working with Trustless Work:
 
-1. **Know the platform laws** — Read [constitution.md](constitution.md) before designing any escrow flow: role permissions, lifecycle preconditions, and API rules, each tagged as contract-enforced, canonical workflow, security practice, or versioned fact
+1. **Know the platform laws** — Read [constitution.md](constitution.md) before designing any escrow flow: the universal laws and the version-selection rule, each tagged as contract-enforced, canonical workflow, security practice, or versioned fact. Then load the profile for the version you are targeting.
 2. **Configure MCP (recommended)** — See [MCP Integration](#mcp-integration) below for live docs and escrow tools
 3. **Understand core concepts** - See [skills/api/core-concepts.md](skills/api/core-concepts.md)
 4. **Choose escrow type**:
@@ -71,7 +83,11 @@ These are the non-obvious facts that the agent will get wrong without being told
 Load these on demand — only when the task requires them:
 
 ### Platform Laws
-- Read **[constitution.md](constitution.md)** before designing any escrow flow or answering questions about what a role can or cannot do — the compressed agent-facing summary of role permissions, lifecycle preconditions, API rules, fees, and network rules, with each statement tagged ENFORCED / CANONICAL / SECURITY / FACT and a source-of-truth hierarchy on top.
+- Read **[constitution.md](constitution.md)** before designing any escrow flow or answering questions about what a role can or cannot do — the universal laws, the version-selection rule, API and network rules, with each statement tagged ENFORCED / CANONICAL / SECURITY / FACT and a source-of-truth hierarchy on top.
+
+### Protocol Profiles
+- Read **[skills/protocol/v1.md](skills/protocol/v1.md)** for roles, lifecycle, payload rules and economics — **the default for every integration**.
+- Read **[skills/protocol/v2.md](skills/protocol/v2.md)** only when the user explicitly asks for V2 or beta behavior.
 
 ### REST API
 - Read **[skills/api/core-concepts.md](skills/api/core-concepts.md)** for roles, lifecycle, flags, and auth details.

skills/api/core-concepts.md

@@ -1,5 +1,7 @@
 # Core Concepts
 
+> **Protocol version: V1.** This file documents the production V1 integration — the only version deployed on mainnet. The V2 API, React SDK and Blocks surfaces are **not** documented in this skill yet; for the contract-level differences between V1 and V2 see [constitution.md](../../constitution.md).
+
 ## Overview
 
 Trustless Work is **Escrow-as-a-Service (EaaS)** for stablecoin escrow. It enables trust-minimized conditional payments on Stellar blockchain using Soroban smart contracts. Build **non-custodial** flows with milestones, approvals, and disputes. Ideal for freelancing, marketplaces, grant disbursements, and any milestone-based payment flow.

skills/api/multi-release-escrow.md

@@ -1,5 +1,7 @@
 # Multi-Release Escrow
 
+> **Protocol version: V1.** This file documents the production V1 integration — the only version deployed on mainnet. The V2 API, React SDK and Blocks surfaces are **not** documented in this skill yet; for the contract-level differences between V1 and V2 see [constitution.md](../../constitution.md).
+
 Multi-release escrows release funds incrementally as each milestone is completed and approved.
 
 ## When to Use

skills/api/single-release-escrow.md

@@ -1,5 +1,7 @@
 # Single-Release Escrow
 
+> **Protocol version: V1.** This file documents the production V1 integration — the only version deployed on mainnet. The V2 API, React SDK and Blocks surfaces are **not** documented in this skill yet; for the contract-level differences between V1 and V2 see [constitution.md](../../constitution.md).
+
 Single-release escrows release all funds in one payment after all milestones are completed and approved.
 
 ## When to Use

skills/api/trustlines.md

@@ -1,5 +1,7 @@
 # Trustlines
 
+> **Applies to both protocol versions.** Trustlines are a Stellar network requirement, independent of the Trustless Work protocol version.
+
 Trustlines are required for accounts to hold and transact with non-native assets (anything other than XLM) on the Stellar network.
 
 ## What is a Trustline?

skills/api/types.md

@@ -1,5 +1,7 @@
 # TypeScript Types Reference
 
+> **Protocol version: V1.** This file documents the production V1 integration — the only version deployed on mainnet. The V2 API, React SDK and Blocks surfaces are **not** documented in this skill yet; for the contract-level differences between V1 and V2 see [constitution.md](../../constitution.md).
+
 Complete TypeScript type definitions for all Trustless Work API payloads, responses, and errors.
 
 ## Payloads

skills/blocks/components.md

@@ -1,5 +1,7 @@
 # Blocks Components
 
+> **Protocol version: V1.** This file documents the production V1 integration — the only version deployed on mainnet. The V2 API, React SDK and Blocks surfaces are **not** documented in this skill yet; for the contract-level differences between V1 and V2 see [constitution.md](../../constitution.md).
+
 Pre-built UI components for escrow management interfaces. All components can be installed via CLI and are fully customizable.
 
 ## Installation

skills/blocks/hooks.md

@@ -1,5 +1,7 @@
 # Blocks TanStack Query Hooks
 
+> **Protocol version: V1.** This file documents the production V1 integration — the only version deployed on mainnet. The V2 API, React SDK and Blocks surfaces are **not** documented in this skill yet; for the contract-level differences between V1 and V2 see [constitution.md](../../constitution.md).
+
 TanStack Query hooks for fetching and mutating escrows.
 
 ## Installation

skills/blocks/introduction.md

@@ -1,5 +1,7 @@
 # Blocks SDK Introduction
 
+> **Protocol version: V1.** This file documents the production V1 integration — the only version deployed on mainnet. The V2 API, React SDK and Blocks surfaces are **not** documented in this skill yet; for the contract-level differences between V1 and V2 see [constitution.md](../../constitution.md).
+
 The Trustless Work Blocks SDK (`@trustless-work/blocks`) provides pre-built UI components, providers, and TanStack Query hooks for quickly building escrow management interfaces.
 
 ## What You Get

skills/blocks/providers.md

@@ -1,5 +1,7 @@
 # Blocks Providers
 
+> **Protocol version: V1.** This file documents the production V1 integration — the only version deployed on mainnet. The V2 API, React SDK and Blocks surfaces are **not** documented in this skill yet; for the contract-level differences between V1 and V2 see [constitution.md](../../constitution.md).
+
 Providers for escrow state, wallet context, dialogs, and amount formatting. **Provider order is critical** — do not reorder.
 
 ## Required Provider Stack

skills/blocks/vibe-coding.md

@@ -1,5 +1,7 @@
 # Vibe Coding Guide
 
+> **Protocol version: V1.** This file documents the production V1 integration — the only version deployed on mainnet. The V2 API, React SDK and Blocks surfaces are **not** documented in this skill yet; for the contract-level differences between V1 and V2 see [constitution.md](../../constitution.md).
+
 Single-file AI context guide for Trustless Work Escrow Blocks with Next.js. Built for agent workflows.
 
 {% hint style="info" %}

skills/protocol/v1.md

@@ -0,0 +1,95 @@
+# Trustless Work V1 — Protocol Profile
+
+**Status: production.** V1 is the only Trustless Work protocol live on mainnet and the default for every integration unless the user explicitly asks for V2 beta.
+
+Read [constitution.md](../../constitution.md) first for the universal laws and the tag meanings. This file carries the V1-specific rules.
+
+**Contract references:** `single-release-main@6e4d40e25057dc51fcffd9c5cbee05eaf369380a` · `multi-release-main@d5cfc2ee0341141ab0a348388771afe71c8c28d2`.
+
+**API base path:** `/escrow/single-release/v1/...` and `/escrow/multi-release/v1/...`.
+
+---
+
+## 1. Role Assignments and Authority
+
+**[ENFORCED]** Each row describes authority granted by that **role assignment**. The final column means "this role assignment alone does not authorize this action" — it is not a prohibition on an address that also holds another role.
+
+| Role assignment | This assignment authorizes | This assignment alone does not authorize |
+|---|---|---|
+| `approver` | Approve milestones; raise a dispute | Milestone status/evidence updates; release; dispute resolution |
+| `serviceProvider` | Change milestone status and attach evidence; raise a dispute | Approval; release; dispute resolution |
+| `releaseSigner` | Release funds (`release-funds` / `release-milestone-funds`); raise a dispute | Approval; milestone status/evidence updates; dispute resolution |
+| `disputeResolver` | Execute dispute **resolution** and its distributions — the address assigned to this role is required to resolve | Raising a dispute — the contract explicitly rejects the `disputeResolver` address from doing so |
+| `receiver` | Receive funds when release executes; raise a dispute (single-release: the escrow `receiver`; multi-release: each milestone's `receiver`, for that milestone) | Approval; milestone status/evidence updates; release; dispute resolution |
+| `platformAddress` | Receive the platform fee at release; update the escrow subject to §2.3; raise a dispute | Approval; milestone status/evidence updates; release; dispute resolution; replacing the escrow's `platformAddress` |
+
+**Who may raise a dispute** (verified against the V1 contract source): `approver`, `serviceProvider`, `platformAddress`, `releaseSigner`, and the (milestone) `receiver`. The `disputeResolver` address is explicitly rejected. Note: docs v1 describes a narrower set (no receiver/platform); the contract source is the higher truth layer here.
+
+Actors without a role slot:
+
+- **Deploy signer** (`signer`): signs the deploy transaction; gains no escrow permissions from it.
+- **Depositor**: *anyone* holding the asset and its trustline may fund an escrow; funding grants no permissions inside it.
+
+**[FACT]** One address may hold multiple roles by design. Its effective authority is the combination of those role assignments, except where the contract contains an explicit address-level prohibition (for example, an address assigned as `disputeResolver` cannot raise a dispute even if it also matches another dispute-capable role).
+
+**[CANONICAL]** Use distinct addresses when the product workflow requires separation of duties or independent checks. Role separation is a configurator choice, not a V1 contract requirement.
+
+> V2 replaces this model with role collections plus `admin` and `observers`, and adds contract-enforced overlap prohibitions. Do not carry V2 role rules into a V1 answer.
+
+---
+
+## 2. Lifecycle Laws
+
+1. **[CANONICAL]** The recommended workflow is Deploy → Fund → Milestone updates → Approval → Release, with disputes as an interruption path. Individual steps have their own enforced preconditions (below); the sequence itself is the canonical integration pattern, not a contract rule.
+
+2. **Deploy and external references**
+   - **[FACT]** `engagementId` is a caller-defined external reference used by the configurator/integrator to associate an escrow with its own business object or serial number — for example a contract, sale, invoice, order, grant, or internal record. **V1 does not enforce global uniqueness of `engagementId`.** `EscrowAlreadyInitialized` means that the same escrow contract instance has already been initialized; it does not mean the `engagementId` exists globally.
+   - **[ENFORCED]** Deploy constraints include: at least 1 and at most 50 milestones; configured amounts must be positive; `platformFee` cannot exceed the contract/API cap; initial release/dispute/resolution/approval flags must satisfy the escrow type's initialization rules. Single-release API deploy milestones carry **only** `description` (no `status`, no `approvedFlag`). Multi-release has **no top-level `amount`**: each milestone defines its own `amount` and `receiver`, and `receiver` does not exist in its `roles` object.
+
+3. **[ENFORCED] Update laws are state- and escrow-type-aware:**
+   - Only the existing `platformAddress` may call `update-escrow`, and the `platformAddress` itself cannot be replaced.
+   - **Before funding — Single Release:** escrow properties may be changed by the platform subject to the validator; an already-approved existing milestone blocks property changes, and the updated state cannot introduce release/dispute/resolution or approved milestone flags.
+   - **Before funding — Multi Release:** the platform may update escrow properties subject to the validator; existing milestone flags must be preserved, and any newly appended milestone must start with all milestone flags false.
+   - **After funding — both V1 types:** existing escrow properties and existing milestones are frozen. The only permitted structural change is appending new milestones that satisfy the initial/unset flag requirements. **Existing approved milestones do not by themselves prevent appending new milestones** as long as the funded escrow's existing state is preserved.
+
+4. **[ENFORCED]** Completion ≠ approval: the `serviceProvider` marking a milestone complete moves no funds. Only the `approver` role assignment's separate approval satisfies the approval precondition.
+
+5. **[ENFORCED]** Single-release: **all** milestones must be approved and no dispute active before `release-funds`; the contract then pays out the **configured escrow amount** minus fees in one payment (release requires the contract balance to cover it — payouts are computed from `escrow.amount`, not from arbitrary excess balance).
+
+6. **[ENFORCED]** Multi-release: each milestone is approved and released independently; disputes and resolutions are per-milestone.
+
+7. **[ENFORCED]** Dispute-resolution invariants differ by escrow type, and resolution is terminal in both:
+   - **Single-release** `resolve-dispute`: the escrow must be disputed; distributions (max 50 entries) must be positive and sum **exactly** to the current escrow balance.
+   - **Multi-release** `resolve-milestone-dispute`: the milestone must be disputed (not released/resolved); distributions (max 50 entries) must be positive, must **not exceed the milestone's amount**, and must not exceed the current contract balance — they do **not** have to equal the full balance.
+   - Once resolved, a dispute cannot be reopened.
+
+8. **[ENFORCED] `withdraw-remaining-funds`** exists for **both** escrow types in V1, in the contract and in the API (`POST /escrow/single-release/v1/withdraw-remaining-funds` and the multi-release equivalent). It is not Multi Release-only.
+   - Only the address assigned as `disputeResolver` may call it.
+   - Preconditions: at most 50 distributions; every amount strictly positive; the total greater than zero; and the contract balance at least the total.
+   - **"Fully processed" in V1 includes an open dispute.** Single Release requires `released || resolved || disputed`; Multi Release requires every milestone to satisfy the same. An escrow with an unresolved dispute therefore satisfies the precondition. V2 narrowed this — do not describe the V1 rule as if it were the V2 one.
+   - It is **fee-bearing**, not a plain sweep: each recipient's amount is reduced pro rata by the protocol fee and the platform fee, and recipients receive the net.
+   - **[FACT]** Single Release V1 emits no event for this operation, so a withdrawal there is not observable through the indexer; Multi Release V1 does emit one.
+   - Validated in [`trustlesswork-smart-contract-stellar#117`](https://github.com/Trustless-Work/trustlesswork-smart-contract-stellar/issues/117).
+
+---
+
+## 3. V1 API Payload Laws
+
+1. **[ENFORCED]** `amount` is a **number** in V1 operate payloads — deploy, `fund-escrow`, milestone amounts, dispute distributions. Never send these operate amounts as strings.
+2. **[ENFORCED]** `milestoneIndex` is a **string** (`"0"`, `"1"`, …) at the V1 API layer — even though it looks numeric.
+3. **[ENFORCED]** In the V1 API payload shape described by this skill, `trustline.address` is the token **issuer** address (starts with `G`), never the escrow Soroban contract address; the companion field is `symbol`, not `code`. The API resolves the Soroban token contract internally from issuer plus symbol.
+
+---
+
+## 4. Economic Laws
+
+1. **[CANONICAL]** Funding target: the configured escrow `amount` (single-release) or the sum of milestone amounts (multi-release). `platformFee` is a **fee-rate configuration** set at deploy — not an extra token amount to fund.
+2. **[ENFORCED]** `fund-escrow` itself only enforces amount > 0, sufficient signer balance, and escrow-property consistency — it does not require a single deposit to equal the configured amount. What is enforced later: **release requires the contract balance to cover the configured release amount**.
+3. **[ENFORCED]** At release, the contract computes deductions from the **configured release amount** — the platform fee (sent to `platformAddress`) and the Trustless Work protocol fee — and transfers the remainder to the receiver for that release.
+4. **[FACT]** The protocol fee is currently a fixed **0.3%** on V1 mainnet.
+5. **[ENFORCED]** The V1 contract/API rejects `platformFee` values above its configured cap (currently 99% subject also to the protocol-fee basis-point constraint).
+6. **[FACT]** On the mainnet contract lineage (`*-main`) the Trustless Work fee address is **hardcoded in the contract**. On the testnet lineage (`*-develop`) it is a call parameter so tests and API-driven testing can run. This is a deliberate network-level security property — the destination of protocol fees must not be caller-supplied on mainnet — and it holds in V1 and V2 alike. It is not a version difference, and the parameter form must never be presented as the preferred shape.
+
+---
+
+**Sources**: [Smart-contract source](https://github.com/Trustless-Work/trustlesswork-smart-contract-stellar) (`single-release-main` / `multi-release-main`) · [Roles in Trustless Work](https://docs.trustlesswork.com/trustless-work/introduction/technology-overview/roles-in-trustless-work) · [Escrow Lifecycle](https://docs.trustlesswork.com/trustless-work/introduction/technology-overview/escrow-lifecycle) · [Dispute Resolution](https://docs.trustlesswork.com/trustless-work/introduction/technology-overview/escrow-lifecycle/dispute-resolution) · [Release Phase](https://docs.trustlesswork.com/trustless-work/introduction/technology-overview/escrow-lifecycle/release-phase) · [Update Escrow](https://docs.trustlesswork.com/trustless-work/api-rest/deploy/update-escrow-properties) · [Withdraw Remaining Funds](https://docs.trustlesswork.com/trustless-work/api-rest/deploy-1/withdraw-remaining-funds)