Added OrderInstructions message (#268)

.changeset/green-beans-rhyme.md

@@ -0,0 +1,5 @@
+---
+"@tbdex/protocol": minor
+---
+
+Added OrderInstructions message.

packages/protocol/build/compile-validators.js

@@ -23,6 +23,7 @@ import OfferingSchema from '../../../tbdex/hosted/json-schemas/offering.schema.j
 import BalanceSchema from '../../../tbdex/hosted/json-schemas/balance.schema.json' assert { type: 'json' }
 import MessageSchema from '../../../tbdex/hosted/json-schemas/message.schema.json' assert { type: 'json' }
 import OrderSchema from '../../../tbdex/hosted/json-schemas/order.schema.json' assert { type: 'json' }
+import OrderInstructionsSchema from '../../../tbdex/hosted/json-schemas/orderinstructions.schema.json' assert { type: 'json' }
 import OrderstatusSchema from '../../../tbdex/hosted/json-schemas/orderstatus.schema.json' assert { type: 'json' }
 import QuoteSchema from '../../../tbdex/hosted/json-schemas/quote.schema.json' assert { type: 'json' }
 import ResourceSchema from '../../../tbdex/hosted/json-schemas/resource.schema.json' assert { type: 'json' }
@@ -36,6 +37,7 @@ const schemas = {
   balance     : BalanceSchema,
   message     : MessageSchema,
   order       : OrderSchema,
+  orderinstructions : OrderInstructionsSchema,
   orderstatus : OrderstatusSchema,
   quote       : QuoteSchema,
   resource    : ResourceSchema,

packages/protocol/src/exchange.ts

@@ -1,4 +1,4 @@
-import { Close, Order, OrderStatus, Quote, Rfq } from './message-kinds/index.js'
+import { Close, Order, OrderInstructions, OrderStatus, Quote, Rfq } from './message-kinds/index.js'
 import { Message } from './message.js'
 import { MessageKind } from './types.js'
 
@@ -18,9 +18,11 @@ export class Exchange {
   rfq: Rfq | undefined
   /** Message sent by the PFI in response to an RFQ */
   quote: Quote | undefined
-  /** Message sent by Alice to the PFI to accept a quote*/
+  /** Message sent by Alice to the PFI to accept a quote */
   order: Order | undefined
-  /** Message sent by the PFI to Alice to convet the current status of the order */
+  /** Message sent by the PFI to Alice to give payin and payout instructions */
+  orderInstructions: OrderInstructions | undefined
+  /** Message sent by the PFI to Alice to convey the current status of the order */
   orderstatus: OrderStatus[]
   /** Message sent by either the PFI or Alice to terminate an exchange */
   close: Close | undefined
@@ -83,6 +85,8 @@ export class Exchange {
       this.close = message
     } else if (message.isOrder()) {
       this.order = message
+    } else if (message.isOrderInstructions()) {
+      this.orderInstructions = message
     } else if (message.isOrderStatus()) {
       this.orderstatus.push(message)
     } else {
@@ -107,6 +111,7 @@ export class Exchange {
   get latestMessage(): Message | undefined {
     return this.close ??
            this.orderstatus[this.orderstatus.length - 1] ??
+           this.orderInstructions ??
            this.order ??
            this.quote ??
            this.rfq
@@ -134,6 +139,7 @@ export class Exchange {
       this.rfq,
       this.quote,
       this.order,
+      this.orderInstructions,
       ...this.orderstatus,
       this.close
     ]

packages/protocol/src/message-kinds/index.ts

@@ -1,5 +1,6 @@
 export * from './rfq.js'
 export * from './quote.js'
 export * from './order.js'
+export * from './order-instructions.js'
 export * from './order-status.js'
 export * from './close.js'

packages/protocol/src/message-kinds/order-instructions.ts

@@ -0,0 +1,73 @@
+import type { MessageKind, MessageModel, OrderInstructionsData, OrderInstructionsMetadata } from '../types.js'
+import { Message } from '../message.js'
+import { Parser } from '../parser.js'
+
+/**
+ * Options passed to {@link OrderInstructions.create}
+ * @beta
+ */
+export type CreateOrderInstructionsOptions = {
+  data: OrderInstructionsData
+  metadata: Omit<OrderInstructionsMetadata, 'id' |'kind' | 'createdAt' | 'protocol'> & { protocol?: OrderInstructionsMetadata['protocol'] }
+}
+
+/**
+ * Sent by the PFI to Alice to convey payment instructions.
+ * @beta
+ */
+export class OrderInstructions extends Message {
+  /** A set of valid Message kinds that can come after an Order Instructions */
+  readonly validNext = new Set<MessageKind>(['orderstatus', 'close'])
+
+  /** The message kind `orderinstructions`. */
+  readonly kind = 'orderinstructions'
+
+  /** Metadata such as sender, recipient, date created, and ID */
+  readonly metadata: OrderInstructionsMetadata
+
+  /** OrderInstructions' specific data containing payin and payout instructions  */
+  readonly data: OrderInstructionsData
+
+  constructor(metadata: OrderInstructionsMetadata, data: OrderInstructionsData, signature?: string) {
+    super(metadata, data, signature)
+    this.metadata = metadata
+    this.data = data
+  }
+
+  /**
+   * Parses a JSON message into an OrderInstructions.
+   * @param rawMessage - The OrderInstructions to parse.
+   * @throws Error if the OrderInstructions could not be parsed or is not a valid OrderInstructions.
+   * @returns The parsed OrderInstructions.
+   */
+  static async parse(rawMessage: MessageModel | string): Promise<OrderInstructions> {
+    const jsonMessage = Parser.rawToMessageModel(rawMessage)
+
+    const orderInstructions = new OrderInstructions(
+      jsonMessage.metadata as OrderInstructionsMetadata,
+      jsonMessage.data as OrderInstructionsData,
+      jsonMessage.signature
+    )
+
+    await orderInstructions.verify()
+    return orderInstructions
+  }
+
+  /**
+   * Creates an OrderInstructions with the given options.
+   * @param opts - Options to create an OrderInstructions.
+   */
+  static create(opts: CreateOrderInstructionsOptions): OrderInstructions {
+    const metadata: OrderInstructionsMetadata = {
+      ...opts.metadata,
+      kind      : 'orderinstructions',
+      id        : Message.generateId('orderinstructions'),
+      createdAt : new Date().toISOString(),
+      protocol  : opts.metadata.protocol ?? '1.0'
+    }
+
+    const orderInstructions = new OrderInstructions(metadata, opts.data)
+    orderInstructions.validateData()
+    return orderInstructions
+  }
+}

packages/protocol/src/message-kinds/order.ts

@@ -16,12 +16,14 @@ export type CreateOrderOptions = {
  */
 export class Order extends Message {
   /** a set of valid Message kinds that can come after an order */
-  readonly validNext = new Set<MessageKind>(['orderstatus'])
+  readonly validNext = new Set<MessageKind>(['orderinstructions', 'close'])
+
   /** The message kind (order) */
   readonly kind = 'order'
 
   /** Metadata such as sender, recipient, date created, and ID */
   readonly metadata: OrderMetadata
+
   /** Order's data */
   readonly data: OrderData
 

packages/protocol/src/message.ts

@@ -1,5 +1,5 @@
 import type { MessageKind, MessageModel, MessageMetadata, MessageData } from './types.js'
-import { Rfq, Quote, Order, OrderStatus, Close } from './message-kinds/index.js'
+import { Rfq, Quote, Order, OrderInstructions, OrderStatus, Close } from './message-kinds/index.js'
 
 import { Crypto } from './crypto.js'
 import { typeid } from 'typeid-js'
@@ -173,6 +173,11 @@ export abstract class Message {
     return this.metadata.kind === 'order'
   }
 
+  /** OrderInstructions type guard */
+  isOrderInstructions(): this is OrderInstructions {
+    return this.metadata.kind === 'orderinstructions'
+  }
+
   /** OrderStatus type guard */
   isOrderStatus(): this is OrderStatus {
     return this.metadata.kind === 'orderstatus'

packages/protocol/src/parser.ts

@@ -1,10 +1,10 @@
-import type { MessageModel, ResourceModel, RfqMetadata, RfqData, QuoteData, QuoteMetadata, OrderData, OrderMetadata, OrderStatusMetadata, OrderStatusData, CloseMetadata, CloseData, OfferingMetadata, OfferingData, BalanceMetadata, BalanceData } from './types.js'
+import type { MessageModel, ResourceModel, RfqMetadata, RfqData, QuoteData, QuoteMetadata, OrderData, OrderMetadata, OrderStatusMetadata, OrderStatusData, CloseMetadata, CloseData, OfferingMetadata, OfferingData, BalanceMetadata, BalanceData, OrderInstructionsMetadata, OrderInstructionsData } from './types.js'
 
 // eslint-disable-next-line @typescript-eslint/no-unused-vars
 import type { Resource } from './resource.js'
 import type { Message } from './message.js'
 
-import { Rfq, Quote, Order, OrderStatus, Close } from './message-kinds/index.js'
+import { Rfq, Quote, Order, OrderInstructions, OrderStatus, Close } from './message-kinds/index.js'
 import { Balance, Offering } from './resource-kinds/index.js'
 
 /**
@@ -53,6 +53,14 @@ export class Parser {
         )
         break
 
+      case 'orderinstructions':
+        message = new OrderInstructions(
+          jsonMessage.metadata as OrderInstructionsMetadata,
+          jsonMessage.data as OrderInstructionsData,
+          jsonMessage.signature
+        )
+        break
+
       case 'orderstatus':
         message = new OrderStatus(
           jsonMessage.metadata as OrderStatusMetadata,

packages/protocol/src/types.ts

@@ -248,6 +248,12 @@ export type QuoteMetadata = MessageMetadata & { kind: 'quote' }
  */
 export type OrderMetadata = MessageMetadata & { kind: 'order' }
 
+/**
+ * OrderInstructions' metadata
+ * @beta
+ */
+export type OrderInstructionsMetadata = MessageMetadata & { kind: 'orderinstructions' }
+
 /**
  * OrderStatus's metadata
  * @beta
@@ -264,13 +270,13 @@ export type CloseMetadata = MessageMetadata & { kind: 'close' }
  * Type alias to represent a set of message kind string keys
  * @beta
  */
-export type MessageKind = 'rfq' | 'quote' | 'order' | 'orderstatus' | 'close'
+export type MessageKind = 'rfq' | 'quote' | 'order' | 'orderinstructions' | 'orderstatus' | 'close'
 
 /**
  * Message's data
  * @beta
  */
-export type MessageData = RfqData | QuoteData | OrderData | OrderStatusData | CloseData
+export type MessageData = RfqData | QuoteData | OrderData | OrderInstructionsData | OrderStatusData | CloseData
 
 /**
  * Data contained in a RFQ message
@@ -394,6 +400,18 @@ export type QuoteDetails = {
   total: string
 }
 
+/**
+ * Describes the payment instructions with plain text and/or a link.
+ * @beta
+ */
+export type PaymentInstruction = {
+  /** Link to allow Alice to pay PFI, or be paid by the PFI. */
+  link?: string
+
+  /** Instruction on how Alice can pay PFI, or how Alice can be paid by the PFI. */
+  instruction?: string
+}
+
 /**
  * Message sent by Alice to the PFI to accept a Quote. Order is currently an empty object
  * @beta
@@ -402,6 +420,18 @@ export type OrderData = {
   [key: string]: never
 }
 
+/**
+ * Message sent by the PFI to Alice to convey payment instructions.
+ * @beta
+ */
+export type OrderInstructionsData = {
+  /** Object that describes how to pay the PFI (e.g. BTC address, payment link). */
+  payin: PaymentInstruction
+
+  /** Object that describes how be paid by the PFI (e.g. BTC address, payment link). */
+  payout: PaymentInstruction
+}
+
 /**
  * Message sent by the PFI to Alice to convey the current status of an order. There can be many OrderStatus
  * messages in a given Exchange