Update TypeScript types, schemas, and documentation for TAIP-17

- Add Escrow and Capture interfaces to TypeScript types
- Create JSON schemas for Escrow and Capture messages
- Update messages.md with Escrow and Capture documentation
- Add TAIP-17 to README.md and CHANGELOG.md
- Update agent.json schema to support flexible role values including EscrowAgent
- Ensure all components follow existing TAP patterns

🤖 Generated with [Claude Code](https://claude.ai/code)

Co-Authored-By: Claude <noreply@anthropic.com>

Author: pelle

CHANGELOG.md

@@ -38,6 +38,11 @@ This changelog focuses on:
 ### Added
 - JSON Schema definitions for all TAP message types in `/schemas/` directory
 - Developer resources page with implementation guides
+- TAIP-17: Composable Escrow workflow (Draft)
+  - New `Escrow` message type for holding assets on behalf of parties
+  - New `Capture` message type for releasing escrowed funds
+  - Supports both cryptocurrency assets and fiat currency denominations
+  - Enables payment guarantees and asset swap use cases
 - TypeScript fixes: Added `by` field to Cancel interface
 
 ### Removed

README.md

@@ -42,6 +42,7 @@ The purpose of TAIPs is to provide the community with a means to propose enhance
 | 14   | [Payment Requests](./TAIPs/taip-14.md)                                 |
 | 15   | [Agent Connection Protocol](./TAIPs/taip-15.md)                         |
 | 16   | [Invoices](./TAIPs/taip-16.md)                                         |
+| 17   | [Composable Escrow](./TAIPs/taip-17.md)                                |
 
 ## Implementation Resources
 

messages.md

@@ -12,12 +12,14 @@ permalink: /messages/
 - [Transaction Message](#transaction-message)
   - [Transfer](#transfer)
   - [Payment](#payment)
+  - [Escrow](#escrow)
 - [Authorization Flow Messages](#authorization-flow-messages)
   - [Authorize](#authorize)
   - [Settle](#settle)
   - [Reject](#reject)
   - [Cancel](#cancel)
   - [Revert](#revert)
+  - [Capture](#capture)
 - [Participant Management Messages](#participant-management-messages)
   - [UpdateAgent](#updateagent)
   - [UpdateParty](#updateparty)
@@ -271,6 +273,104 @@ Initiates a payment request from a merchant to a customer.
 }
 ```
 
+### Escrow
+[TAIP-17] - Draft
+
+Requests an agent to hold assets in escrow on behalf of parties, enabling payment guarantees and asset swaps.
+
+| Attribute | Type | Required | Status | Description |
+|-----------|------|----------|---------|-------------|
+| @context | string | Yes | Draft ([TAIP-17]) | JSON-LD context "https://tap.rsvp/schema/1.0" |
+| @type | string | Yes | Draft ([TAIP-17]) | JSON-LD type "https://tap.rsvp/schema/1.0#Escrow" |
+| asset | string | No | Draft ([TAIP-17]) | CAIP-19 identifier for the specific cryptocurrency asset. Either asset OR currency must be present |
+| currency | string | No | Draft ([TAIP-17]) | ISO 4217 currency code for fiat-denominated escrows. Either asset OR currency must be present |
+| amount | string | Yes | Draft ([TAIP-17]) | Amount to be held in escrow (decimal string) |
+| originator | [Party](#party) | Yes | Draft ([TAIP-17]) | Party whose assets will be placed in escrow |
+| beneficiary | [Party](#party) | Yes | Draft ([TAIP-17]) | Party who will receive the assets when released |
+| expiry | string | Yes | Draft ([TAIP-17]) | ISO 8601 timestamp after which the escrow automatically expires |
+| agreement | string | No | Draft ([TAIP-17]) | URL or URI referencing the terms and conditions of the escrow |
+| agents | array of [Agent](#agent) | Yes | Draft ([TAIP-17]) | Array of agents involved in the escrow. Exactly one agent MUST have role "EscrowAgent" |
+
+#### Examples
+
+##### Payment guarantee escrow
+```json
+{
+  "id": "123e4567-e89b-12d3-a456-426614174000",
+  "type": "https://tap.rsvp/schema/1.0#Escrow",
+  "from": "did:web:merchant.example",
+  "to": ["did:web:paymentprocessor.example"],
+  "created_time": 1719226800,
+  "expires_time": 1719313200,
+  "body": {
+    "@context": "https://tap.rsvp/schema/1.0",
+    "@type": "https://tap.rsvp/schema/1.0#Escrow",
+    "asset": "eip155:1/erc20:0xa0b86991c6218b36c1d19d4a2e9eb0ce3606eb48",
+    "amount": "100.00",
+    "originator": {
+      "@id": "did:eg:customer"
+    },
+    "beneficiary": {
+      "@id": "did:web:merchant.example"
+    },
+    "expiry": "2025-06-25T00:00:00Z",
+    "agreement": "https://merchant.example/order/12345/terms",
+    "agents": [
+      {
+        "@id": "did:web:merchant.example",
+        "for": "did:web:merchant.example"
+      },
+      {
+        "@id": "did:web:paymentprocessor.example",
+        "role": "EscrowAgent"
+      },
+      {
+        "@id": "did:web:customer.wallet",
+        "for": "did:eg:customer"
+      }
+    ]
+  }
+}
+```
+
+##### Fiat currency escrow
+```json
+{
+  "id": "789e0123-e89b-12d3-a456-426614174003",
+  "type": "https://tap.rsvp/schema/1.0#Escrow",
+  "from": "did:web:marketplace.example",
+  "to": ["did:web:escrow.bank"],
+  "body": {
+    "@context": "https://tap.rsvp/schema/1.0",
+    "@type": "https://tap.rsvp/schema/1.0#Escrow",
+    "currency": "USD",
+    "amount": "500.00",
+    "originator": {
+      "@id": "did:eg:buyer"
+    },
+    "beneficiary": {
+      "@id": "did:eg:seller"
+    },
+    "expiry": "2025-07-01T00:00:00Z",
+    "agreement": "https://marketplace.example/purchase/98765",
+    "agents": [
+      {
+        "@id": "did:web:marketplace.example",
+        "for": "did:eg:seller"
+      },
+      {
+        "@id": "did:web:buyer.bank",
+        "for": "did:eg:buyer"
+      },
+      {
+        "@id": "did:web:escrow.bank",
+        "role": "EscrowAgent"
+      }
+    ]
+  }
+}
+```
+
 ## Authorization Flow Messages
 
 ### Authorize
@@ -446,6 +546,55 @@ Requests a reversal of a settled transaction. This could be part of a dispute re
 }
 ```
 
+### Capture
+[TAIP-17] - Draft
+
+Authorizes the release of escrowed funds to the beneficiary. Only agents acting for the beneficiary can send this message.
+
+| Attribute | Type | Required | Status | Description |
+|-----------|------|----------|---------|-------------|
+| @context | string | Yes | Draft ([TAIP-17]) | JSON-LD context "https://tap.rsvp/schema/1.0" |
+| @type | string | Yes | Draft ([TAIP-17]) | JSON-LD type "https://tap.rsvp/schema/1.0#Capture" |
+| amount | string | No | Draft ([TAIP-17]) | Amount to capture (decimal string). If omitted, captures full escrow amount. Must be ≤ original amount |
+| settlementAddress | string | No | Draft ([TAIP-17]) | Blockchain address for settlement. If omitted, uses address from earlier Authorize |
+
+> **Note:** The message refers to the original Escrow message via the DIDComm `thid` (thread ID) in the message envelope.
+
+#### Examples
+
+##### Full capture
+```json
+{
+  "id": "capture-123",
+  "type": "https://tap.rsvp/schema/1.0#Capture",
+  "from": "did:web:merchant.example",
+  "to": ["did:web:paymentprocessor.example"],
+  "thid": "123e4567-e89b-12d3-a456-426614174000",
+  "body": {
+    "@context": "https://tap.rsvp/schema/1.0",
+    "@type": "https://tap.rsvp/schema/1.0#Capture",
+    "settlementAddress": "eip155:1:0x742d35Cc6634C0532925a3b844Bc9e7595f1234"
+  }
+}
+```
+
+##### Partial capture
+```json
+{
+  "id": "capture-456",
+  "type": "https://tap.rsvp/schema/1.0#Capture",
+  "from": "did:web:merchant.example",
+  "to": ["did:web:paymentprocessor.example"],
+  "thid": "123e4567-e89b-12d3-a456-426614174000",
+  "body": {
+    "@context": "https://tap.rsvp/schema/1.0",
+    "@type": "https://tap.rsvp/schema/1.0#Capture",
+    "amount": "95.00",
+    "settlementAddress": "eip155:1:0x742d35Cc6634C0532925a3b844Bc9e7595f1234"
+  }
+}
+```
+
 ## Participant Management Messages
 
 ### UpdateAgent

packages/typescript/src/tap.ts

@@ -1164,6 +1164,110 @@ export interface AuthorizationRequiredMessage
   type: "https://tap.rsvp/schema/1.0#AuthorizationRequired";
 }
 
+/**
+ * Escrow Message
+ * Requests an agent to hold assets in escrow on behalf of parties.
+ * Enables payment guarantees, asset swaps, and conditional payments.
+ *
+ * @see {@link https://github.com/TransactionAuthorizationProtocol/TAIPs/blob/main/TAIPs/taip-17.md | TAIP-17: Composable Escrow}
+ */
+export interface Escrow extends TapMessageObject<"Escrow"> {
+  /**
+   * Asset to be held in escrow
+   * CAIP-19 identifier for blockchain assets
+   * Either asset OR currency is required
+   */
+  asset?: CAIP19;
+
+  /**
+   * ISO 4217 currency code
+   * For fiat-denominated escrows
+   * Either asset OR currency is required
+   */
+  currency?: IsoCurrency;
+
+  /**
+   * Amount to be held in escrow
+   * String representation of the decimal amount
+   */
+  amount: Amount;
+
+  /**
+   * Party whose assets will be placed in escrow
+   * The party providing the funds
+   */
+  originator: Participant<"Party">;
+
+  /**
+   * Party who will receive the assets when released
+   * The intended recipient of the escrowed funds
+   */
+  beneficiary: Participant<"Party">;
+
+  /**
+   * Expiration timestamp
+   * After this time, funds automatically return to originator
+   */
+  expiry: ISO8601DateTime;
+
+  /**
+   * Optional agreement reference
+   * URL or URI of the escrow terms and conditions
+   */
+  agreement?: string;
+
+  /**
+   * List of agents involved in the escrow
+   * Exactly one agent MUST have role "EscrowAgent"
+   */
+  agents: Participant<"Agent">[];
+}
+
+/**
+ * Capture Message
+ * Authorizes the release of escrowed funds to the beneficiary.
+ * Sent by an agent acting for the beneficiary.
+ *
+ * @see {@link https://github.com/TransactionAuthorizationProtocol/TAIPs/blob/main/TAIPs/taip-17.md | TAIP-17: Composable Escrow}
+ */
+export interface Capture extends TapMessageObject<"Capture"> {
+  /**
+   * Optional amount to capture
+   * If omitted, captures full escrow amount
+   * Must be less than or equal to original escrow amount
+   */
+  amount?: Amount;
+
+  /**
+   * Optional settlement address
+   * Blockchain address for settlement
+   * If omitted, uses address from earlier Authorize
+   */
+  settlementAddress?: CAIP10;
+}
+
+/**
+ * Escrow Message Wrapper
+ * DIDComm envelope for an Escrow message.
+ *
+ * @see {@link https://github.com/TransactionAuthorizationProtocol/TAIPs/blob/main/TAIPs/taip-2.md | TAIP-2: Message Format}
+ * @see {@link https://github.com/TransactionAuthorizationProtocol/TAIPs/blob/main/TAIPs/taip-17.md | TAIP-17: Composable Escrow}
+ */
+export interface EscrowMessage extends DIDCommMessage<Escrow> {
+  type: "https://tap.rsvp/schema/1.0#Escrow";
+}
+
+/**
+ * Capture Message Wrapper
+ * DIDComm envelope for a Capture message.
+ *
+ * @see {@link https://github.com/TransactionAuthorizationProtocol/TAIPs/blob/main/TAIPs/taip-2.md | TAIP-2: Message Format}
+ * @see {@link https://github.com/TransactionAuthorizationProtocol/TAIPs/blob/main/TAIPs/taip-17.md | TAIP-17: Composable Escrow}
+ */
+export interface CaptureMessage extends DIDCommReply<Capture> {
+  type: "https://tap.rsvp/schema/1.0#Capture";
+}
+
 /**
  * TAP Message
  * Union type of all possible TAP messages.
@@ -1188,6 +1292,8 @@ export type TAPMessage =
   | ConfirmRelationshipMessage
   | UpdatePoliciesMessage
   | ConnectMessage
-  | AuthorizationRequiredMessage;
+  | AuthorizationRequiredMessage
+  | EscrowMessage
+  | CaptureMessage;
 
 // All types and interfaces are now exported directly in their declarations

schemas/data-structures/agent.json

@@ -4,20 +4,47 @@
   "title": "Agent",
   "description": "Represents software acting on behalf of a participant",
   "type": "object",
-  "required": ["did", "role"],
+  "required": ["@id"],
   "properties": {
-    "did": {
+    "@id": {
       "$ref": "../common/base-types.json#/$defs/did",
       "description": "Decentralized Identifier of the agent"
     },
+    "@type": {
+      "const": "Agent",
+      "description": "Type identifier for Agent"
+    },
     "role": {
       "type": "string",
-      "enum": ["originator", "beneficiary", "vasp", "wallet", "mediator", "observer"],
-      "description": "Role of the agent in the transaction"
+      "pattern": "^[A-Z][a-zA-Z]*$",
+      "description": "Role of the agent in the transaction (PascalCase). Standard values include: SettlementAddress, SourceAddress, CustodialService, EscrowAgent"
     },
     "for": {
-      "$ref": "../common/base-types.json#/$defs/did",
-      "description": "DID of the party this agent represents"
+      "oneOf": [
+        {
+          "$ref": "../common/base-types.json#/$defs/did"
+        },
+        {
+          "type": "array",
+          "items": {
+            "$ref": "../common/base-types.json#/$defs/did"
+          },
+          "minItems": 1
+        }
+      ],
+      "description": "DID(s) of the party/parties this agent represents"
+    },
+    "name": {
+      "type": "string",
+      "description": "Human-readable name of the agent"
+    },
+    "nameHash": {
+      "$ref": "../common/base-types.json#/$defs/base64",
+      "description": "SHA-256 hash of the normalized agent name"
+    },
+    "lei:leiCode": {
+      "$ref": "../common/base-types.json#/$defs/lei",
+      "description": "Legal Entity Identifier code"
     },
     "policies": {
       "type": "array",