Skip to content

Commit d48767d

Browse files
pelleclaude
pelle
and
claude
committed
Complete TAIP-18 Asset Exchange and TAIP-17 Escrow integration
Added comprehensive support for Exchange and Quote message types per TAIP-18, plus enhanced Escrow documentation from TAIP-17. Updates include TypeScript interfaces, JSON schemas, comprehensive validator support with Zod v4, full test coverage, and complete documentation integration. Key additions: - Exchange/Quote interfaces with multi-asset arrays and business logic validation - JSON schemas for exchange.json and quote.json with CAIP-19/DTI/ISO-4217 support - Enhanced validator.ts with ExchangeSchema, QuoteSchema, EscrowSchema, CaptureSchema - Comprehensive test coverage (105 tests passing) for all new validators - Updated documentation in messages.md and transactions.md - Enhanced changelogs for both TypeScript package v1.12.0 and main repository 🤖 Generated with [Claude Code](https://claude.ai/code) Co-Authored-By: Claude <[email protected]>
1 parent cecde82 commit d48767d

File tree

10 files changed

+1198
-16
lines changed

10 files changed

+1198
-16
lines changed

‎CHANGELOG.md‎

Lines changed: 15 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -14,6 +14,21 @@ This changelog focuses on:
1414
- Protocol structural changes
1515
- Breaking changes
1616

17+
## [2025-09-01]
18+
19+
### Added
20+
- **TAIP-18 Asset Exchange**: Added Exchange and Quote message types for cross-asset transactions
21+
- New Exchange message type for requesting asset conversion quotes (USDC to EURC, USD to crypto, cross-chain)
22+
- New Quote message type for liquidity provider responses with pricing and expiration timestamps
23+
- Support for multi-asset arrays enabling flexible routing and provider selection
24+
- Compatible with existing TAIP-4 Authorize/Settle flows for quote acceptance and settlement
25+
- Integration with TAIP-17 Escrow for counterparty risk management in exchanges
26+
- Enables use cases: cross-asset payments, FX transactions, on/off-ramp services, cross-chain bridging
27+
- **Updated JSON Schemas**: Added exchange.json and quote.json message schemas
28+
- **Updated TypeScript Package v1.12.0**: Added Exchange and Quote interfaces and message wrappers
29+
- See [packages/typescript/CHANGELOG.md](packages/typescript/CHANGELOG.md) for complete details
30+
- **Updated Documentation**: Enhanced messages.md and transactions.md with Exchange and Quote documentation
31+
1732
## [2025-08-23]
1833

1934
### Enhanced

‎messages.md‎

Lines changed: 114 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -329,6 +329,120 @@ Initiates a payment request from a merchant to a customer.
329329
}
330330
```
331331

332+
### Exchange
333+
[TAIP-18] - Draft
334+
335+
Requests a quote for exchanging assets between different types or chains. Enables cross-asset quotes (e.g., USDC to EURC, USD to USDC).
336+
337+
| Attribute | Type | Required | Status | Description |
338+
|-----------|------|----------|---------|-------------|
339+
| @context | string | Yes | Draft ([TAIP-18]) | JSON-LD context "https://tap.rsvp/schema/1.0" |
340+
| @type | string | Yes | Draft ([TAIP-18]) | JSON-LD type "https://tap.rsvp/schema/1.0#Exchange" |
341+
| fromAssets | array of string | Yes | Draft ([TAIP-18]) | Available source assets (CAIP-19, DTI, or ISO-4217 currency codes) |
342+
| toAssets | array of string | Yes | Draft ([TAIP-18]) | Desired target assets (CAIP-19, DTI, or ISO-4217 currency codes) |
343+
| fromAmount | string | No | Draft ([TAIP-18]) | Amount of source asset to exchange. Either fromAmount or toAmount must be provided |
344+
| toAmount | string | No | Draft ([TAIP-18]) | Amount of target asset desired. Either fromAmount or toAmount must be provided |
345+
| requester | [Party](#party) | Yes | Draft ([TAIP-18]) | Party requesting the exchange |
346+
| provider | [Party](#party) | No | Draft ([TAIP-18]) | Optional preferred liquidity provider. When omitted, Exchange can be broadcast to multiple providers |
347+
| agents | array of [Agent](#agent) | Yes | Draft ([TAIP-18]) | Array of agents involved in the exchange request |
348+
| policies | array of [Policy](#policy) | No | Draft ([TAIP-18]) | Optional compliance or presentation requirements |
349+
350+
#### Example
351+
```json
352+
{
353+
"id": "exchange-request-123",
354+
"type": "https://tap.rsvp/schema/1.0#Exchange",
355+
"from": "did:web:wallet.example",
356+
"to": ["did:web:lp.example"],
357+
"created_time": 1719226800,
358+
"expires_time": 1719313200,
359+
"body": {
360+
"@context": "https://tap.rsvp/schema/1.0",
361+
"@type": "https://tap.rsvp/schema/1.0#Exchange",
362+
"fromAssets": ["eip155:1/erc20:0xA0b86991c6218b36c1d19d4a2e9eb0ce3606eb48"],
363+
"toAssets": ["eip155:1/erc20:0xB00b00b00b00b00b00b00b00b00b00b00b00b00b"],
364+
"fromAmount": "1000.00",
365+
"requester": {
366+
"@id": "did:web:business.example",
367+
"@type": "https://schema.org/Organization",
368+
"name": "Example Business"
369+
},
370+
"provider": {
371+
"@id": "did:web:liquidity.provider",
372+
"@type": "https://schema.org/Organization",
373+
"name": "LP Corp"
374+
},
375+
"agents": [
376+
{
377+
"@id": "did:web:wallet.example",
378+
"for": "did:web:business.example",
379+
"role": "requester"
380+
},
381+
{
382+
"@id": "did:web:lp.example",
383+
"for": "did:web:liquidity.provider",
384+
"role": "provider"
385+
}
386+
]
387+
}
388+
}
389+
```
390+
391+
### Quote
392+
[TAIP-18] - Draft
393+
394+
Response to an Exchange request providing pricing and terms. Sent by liquidity providers or orchestrators with specific rates.
395+
396+
| Attribute | Type | Required | Status | Description |
397+
|-----------|------|----------|---------|-------------|
398+
| @context | string | Yes | Draft ([TAIP-18]) | JSON-LD context "https://tap.rsvp/schema/1.0" |
399+
| @type | string | Yes | Draft ([TAIP-18]) | JSON-LD type "https://tap.rsvp/schema/1.0#Quote" |
400+
| fromAsset | string | Yes | Draft ([TAIP-18]) | Source asset for the exchange (CAIP-19, DTI, or ISO-4217 currency code) |
401+
| toAsset | string | Yes | Draft ([TAIP-18]) | Target asset for the exchange (CAIP-19, DTI, or ISO-4217 currency code) |
402+
| fromAmount | string | Yes | Draft ([TAIP-18]) | Amount of source asset to be exchanged |
403+
| toAmount | string | Yes | Draft ([TAIP-18]) | Amount of target asset to be received |
404+
| provider | [Party](#party) | Yes | Draft ([TAIP-18]) | Liquidity provider party information |
405+
| agents | array of [Agent](#agent) | Yes | Draft ([TAIP-18]) | Array of agents involved in the quote |
406+
| expiresAt | string | Yes | Draft ([TAIP-18]) | ISO 8601 timestamp when quote expires |
407+
408+
#### Example
409+
```json
410+
{
411+
"id": "quote-456",
412+
"type": "https://tap.rsvp/schema/1.0#Quote",
413+
"from": "did:web:lp.example",
414+
"to": ["did:web:wallet.example"],
415+
"thid": "exchange-request-123",
416+
"created_time": 1719226850,
417+
"body": {
418+
"@context": "https://tap.rsvp/schema/1.0",
419+
"@type": "https://tap.rsvp/schema/1.0#Quote",
420+
"fromAsset": "eip155:1/erc20:0xA0b86991c6218b36c1d19d4a2e9eb0ce3606eb48",
421+
"toAsset": "eip155:1/erc20:0xB00b00b00b00b00b00b00b00b00b00b00b00b00b",
422+
"fromAmount": "1000.00",
423+
"toAmount": "908.50",
424+
"provider": {
425+
"@id": "did:web:liquidity.provider",
426+
"@type": "https://schema.org/Organization",
427+
"name": "LP Corp"
428+
},
429+
"agents": [
430+
{
431+
"@id": "did:web:wallet.example",
432+
"for": "did:web:business.example",
433+
"role": "requester"
434+
},
435+
{
436+
"@id": "did:web:lp.example",
437+
"for": "did:web:liquidity.provider",
438+
"role": "provider"
439+
}
440+
],
441+
"expiresAt": "2025-07-21T00:00:00Z"
442+
}
443+
}
444+
```
445+
332446
### Escrow
333447
[TAIP-17] - Draft
334448

‎packages/typescript/CHANGELOG.md‎

Lines changed: 13 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -2,6 +2,19 @@
22

33
All notable changes to the TypeScript package are documented in this file.
44

5+
## [1.12.0] - 2025-09-01
6+
7+
### Added
8+
- **TAIP-18 Asset Exchange**: Added Exchange and Quote message types for cross-asset transactions
9+
- Added `Exchange` interface supporting multi-asset arrays for source and target assets
10+
- Added `Quote` interface for liquidity provider responses with pricing and expiration
11+
- Support for CAIP-19, DTI, and ISO-4217 currency codes in asset arrays
12+
- Added `ExchangeMessage` and `QuoteMessage` DIDComm wrappers
13+
- Updated `Transactions` union type to include `Exchange`
14+
- Updated `TAPMessage` union type to include `ExchangeMessage` and `QuoteMessage`
15+
- Enhanced TAIP specification cross-reference documentation
16+
- Enables cross-asset quotes (USDC to EURC), FX transactions, on/off-ramp services, and cross-chain bridging
17+
518
## [1.11.0] - 2025-08-23
619

720
### Enhanced

‎packages/typescript/package.json‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,6 @@
11
{
22
"name": "@taprsvp/types",
3-
"version": "1.11.0",
3+
"version": "1.12.0",
44
"description": "TypeScript types and interfaces for the Transaction Authorization Protocol (TAP)",
55
"main": "dist/index.js",
66
"types": "dist/index.d.ts",

‎packages/typescript/src/tap.ts‎

Lines changed: 180 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1058,7 +1058,7 @@ export type Policies =
10581058
* @see {@link https://github.com/TransactionAuthorizationProtocol/TAIPs/blob/main/TAIPs/taip-14.md | TAIP-14: Payment Request}
10591059
* @see {@link https://github.com/TransactionAuthorizationProtocol/TAIPs/blob/main/TAIPs/taip-17.md | TAIP-17: Escrow}
10601060
*/
1061-
export type Transactions = Transfer | Payment | Escrow;
1061+
export type Transactions = Transfer | Payment | Exchange | Escrow;
10621062

10631063
/**
10641064
* Transfer Message
@@ -1258,6 +1258,160 @@ export interface Payment extends TapMessageObject<"Payment"> {
12581258
agents: Agent[];
12591259
}
12601260

1261+
/**
1262+
* Exchange Message
1263+
* Requests a quote for exchanging assets between different types or chains.
1264+
* Used to request cross-asset quotes (e.g., USDC to EURC, USD to USDC).
1265+
*
1266+
* @example
1267+
* ```typescript
1268+
* const exchange: Exchange = {
1269+
* "@context": "https://tap.rsvp/schema/1.0",
1270+
* "@type": "Exchange",
1271+
* fromAssets: ["eip155:1/erc20:0xA0b86991c6218b36c1d19d4a2e9eb0ce3606eb48"], // USDC
1272+
* toAssets: ["eip155:1/erc20:0x1aBaEA1f7C830bD89Acc67eC4af516284b1bC33c"], // EURC
1273+
* fromAmount: "1000.00",
1274+
* requester: {
1275+
* "@id": "did:example:requester",
1276+
* "@type": "https://schema.org/Organization",
1277+
* name: "Example Business"
1278+
* },
1279+
* agents: [{
1280+
* "@id": "did:example:requester-agent",
1281+
* for: "did:example:requester",
1282+
* role: "requester"
1283+
* }]
1284+
* };
1285+
* ```
1286+
*
1287+
* @see {@link https://github.com/TransactionAuthorizationProtocol/TAIPs/blob/main/TAIPs/taip-18.md | TAIP-18: Asset Exchange}
1288+
*/
1289+
export interface Exchange extends TapMessageObject<"Exchange"> {
1290+
/**
1291+
* Array of available source assets
1292+
* Can include CAIP-19, DTI, or ISO-4217 currency codes
1293+
*/
1294+
fromAssets: (CAIP19 | DTI | IsoCurrency)[];
1295+
1296+
/**
1297+
* Array of desired target assets
1298+
* Can include CAIP-19, DTI, or ISO-4217 currency codes
1299+
*/
1300+
toAssets: (CAIP19 | DTI | IsoCurrency)[];
1301+
1302+
/**
1303+
* Optional amount of source asset to exchange
1304+
* String representation of the decimal amount
1305+
* Either fromAmount or toAmount must be provided
1306+
*/
1307+
fromAmount?: Amount;
1308+
1309+
/**
1310+
* Optional amount of target asset desired
1311+
* String representation of the decimal amount
1312+
* Either fromAmount or toAmount must be provided
1313+
*/
1314+
toAmount?: Amount;
1315+
1316+
/**
1317+
* Party requesting the exchange
1318+
* The entity seeking to exchange assets
1319+
*/
1320+
requester: Party;
1321+
1322+
/**
1323+
* Optional preferred liquidity provider
1324+
* When omitted, the Exchange can be broadcast to multiple providers
1325+
*/
1326+
provider?: Party;
1327+
1328+
/**
1329+
* List of agents involved in the exchange request
1330+
* Must include agent acting for the requester
1331+
*/
1332+
agents: Agent[];
1333+
1334+
/**
1335+
* Optional compliance or presentation requirements
1336+
* Policies that must be satisfied for the exchange
1337+
*/
1338+
policies?: Policies[];
1339+
}
1340+
1341+
/**
1342+
* Quote Message
1343+
* Response to an Exchange request providing pricing and terms.
1344+
* Sent by liquidity providers or orchestrators with specific rates.
1345+
*
1346+
* @example
1347+
* ```typescript
1348+
* const quote: Quote = {
1349+
* "@context": "https://tap.rsvp/schema/1.0",
1350+
* "@type": "Quote",
1351+
* fromAsset: "eip155:1/erc20:0xA0b86991c6218b36c1d19d4a2e9eb0ce3606eb48",
1352+
* toAsset: "eip155:1/erc20:0x1aBaEA1f7C830bD89Acc67eC4af516284b1bC33c",
1353+
* fromAmount: "1000.00",
1354+
* toAmount: "908.50",
1355+
* provider: {
1356+
* "@id": "did:example:liquidity-provider",
1357+
* "@type": "https://schema.org/Organization",
1358+
* name: "LP Corp"
1359+
* },
1360+
* agents: [{
1361+
* "@id": "did:example:lp-agent",
1362+
* for: "did:example:liquidity-provider",
1363+
* role: "provider"
1364+
* }],
1365+
* expiresAt: "2025-07-21T00:00:00Z"
1366+
* };
1367+
* ```
1368+
*
1369+
* @see {@link https://github.com/TransactionAuthorizationProtocol/TAIPs/blob/main/TAIPs/taip-18.md | TAIP-18: Asset Exchange}
1370+
*/
1371+
export interface Quote extends TapMessageObject<"Quote"> {
1372+
/**
1373+
* Source asset for the exchange
1374+
* CAIP-19, DTI, or ISO-4217 currency code
1375+
*/
1376+
fromAsset: CAIP19 | DTI | IsoCurrency;
1377+
1378+
/**
1379+
* Target asset for the exchange
1380+
* CAIP-19, DTI, or ISO-4217 currency code
1381+
*/
1382+
toAsset: CAIP19 | DTI | IsoCurrency;
1383+
1384+
/**
1385+
* Amount of source asset to be exchanged
1386+
* String representation of the decimal amount
1387+
*/
1388+
fromAmount: Amount;
1389+
1390+
/**
1391+
* Amount of target asset to be received
1392+
* String representation of the decimal amount
1393+
*/
1394+
toAmount: Amount;
1395+
1396+
/**
1397+
* Liquidity provider party information
1398+
* The entity providing the quote
1399+
*/
1400+
provider: Party;
1401+
1402+
/**
1403+
* List of agents involved in the quote
1404+
* Must include all agents from the original Exchange request plus provider agents
1405+
*/
1406+
agents: Agent[];
1407+
1408+
/**
1409+
* Quote expiration timestamp
1410+
* ISO 8601 timestamp when the quote becomes invalid
1411+
*/
1412+
expiresAt: ISO8601DateTime;
1413+
}
1414+
12611415
// ============================================================================
12621416
// AUTHORIZATION AND LIFECYCLE MESSAGES
12631417
// ============================================================================
@@ -1828,6 +1982,28 @@ export interface PaymentMessage extends DIDCommMessage<Payment> {
18281982
type: "https://tap.rsvp/schema/1.0#Payment";
18291983
}
18301984

1985+
/**
1986+
* Exchange Message Wrapper
1987+
* DIDComm envelope for an Exchange message.
1988+
*
1989+
* @see {@link https://github.com/TransactionAuthorizationProtocol/TAIPs/blob/main/TAIPs/taip-2.md | TAIP-2: Message Format}
1990+
* @see {@link https://github.com/TransactionAuthorizationProtocol/TAIPs/blob/main/TAIPs/taip-18.md | TAIP-18: Asset Exchange}
1991+
*/
1992+
export interface ExchangeMessage extends DIDCommMessage<Exchange> {
1993+
type: "https://tap.rsvp/schema/1.0#Exchange";
1994+
}
1995+
1996+
/**
1997+
* Quote Message Wrapper
1998+
* DIDComm envelope for a Quote message.
1999+
*
2000+
* @see {@link https://github.com/TransactionAuthorizationProtocol/TAIPs/blob/main/TAIPs/taip-2.md | TAIP-2: Message Format}
2001+
* @see {@link https://github.com/TransactionAuthorizationProtocol/TAIPs/blob/main/TAIPs/taip-18.md | TAIP-18: Asset Exchange}
2002+
*/
2003+
export interface QuoteMessage extends DIDCommReply<Quote> {
2004+
type: "https://tap.rsvp/schema/1.0#Quote";
2005+
}
2006+
18312007
/**
18322008
* Authorization Message Wrapper
18332009
* DIDComm envelope for an Authorization message.
@@ -2177,6 +2353,8 @@ export interface PresentationMessage extends DIDCommReply<Record<string, never>>
21772353
export type TAPMessage =
21782354
| TransferMessage
21792355
| PaymentMessage
2356+
| ExchangeMessage
2357+
| QuoteMessage
21802358
| AuthorizeMessage
21812359
| SettleMessage
21822360
| RejectMessage
@@ -2212,6 +2390,7 @@ export type TAPMessage =
22122390
* - TAIP-4: Authorization Flow → {@link Authorize}, {@link Settle}, {@link Reject}, {@link Cancel}, {@link Revert}, {@link AuthorizationRequired}
22132391
* - TAIP-14: Payment Request → {@link Payment}, {@link PaymentMessage}
22142392
* - TAIP-17: Composable Escrow → {@link Escrow}, {@link Capture}, {@link EscrowMessage}, {@link CaptureMessage}
2393+
* - TAIP-18: Asset Exchange → {@link Exchange}, {@link Quote}, {@link ExchangeMessage}, {@link QuoteMessage}
22152394
*
22162395
* **Participant Management:**
22172396
* - TAIP-5: Agents → {@link Agent}, {@link UpdateAgent}, {@link AddAgents}, {@link ReplaceAgent}, {@link RemoveAgent}

0 commit comments

Comments
 (0)