From 78bd6ebd1842b03ceab1e47f68f3c5e333196d04 Mon Sep 17 00:00:00 2001 From: Kendall Weihe Date: Thu, 13 Jun 2024 11:52:15 -0400 Subject: [PATCH 1/7] Begin APID --- docs/API_DESIGN.md | 0 docs/rfc-0001/README.md | 52 +++++++++++++++++++++++++++++++++++++++++ 2 files changed, 52 insertions(+) create mode 100644 docs/API_DESIGN.md create mode 100644 docs/rfc-0001/README.md diff --git a/docs/API_DESIGN.md b/docs/API_DESIGN.md new file mode 100644 index 00000000..e69de29b diff --git a/docs/rfc-0001/README.md b/docs/rfc-0001/README.md new file mode 100644 index 00000000..87e8c3af --- /dev/null +++ b/docs/rfc-0001/README.md @@ -0,0 +1,52 @@ +# tbDEX API Design (APID) + +**Last Updated:** June 13, 2024 + +**Custom DSL Version:** 0.1.0 + +- [Resources](#resources) + - [`Resource`](#resource) + - [`ResourceMetadata`](#resourcemetadata) + - [Offering](#offering) + - [`OfferingData`](#offeringdata) +- [Messages](#messages) + +# Resources + +## `Resource` + +```pseudocode! +INTERFACE Resource + METHOD sign(bearer_did: BearerDid) + METHOD verify(): bool +``` + +## `ResourceMetadata` + +```pseudocode! +CLASS ResourceMetadata + PUBLIC DATA kind: string + /// 🚧 more members +``` + +## Offering + +```pseudocode! +CLASS Offering IMPLEMENTS Resource + CONSTRUCTOR(from: string, data: OfferingData, protocol: string) + CONSTRUCTOR(json: string) + METHOD sign(bearer_did: BearerDid) + METHOD verify(): bool +``` + +### `OfferingData` + +```pseudocode! +CLASS OfferingData + PUBLIC DATA description: string + /// 🚧 more members +``` + +# Messages + +... \ No newline at end of file From 17b60834f943ef6ee673f93b0df52308afe21096 Mon Sep 17 00:00:00 2001 From: Kendall Weihe Date: Tue, 18 Jun 2024 09:54:59 -0400 Subject: [PATCH 2/7] Add resources and messages --- docs/API_DESIGN.md | 389 ++++++++++++++++++++++++++++++++++++++++ docs/rfc-0001/README.md | 52 ------ 2 files changed, 389 insertions(+), 52 deletions(-) diff --git a/docs/API_DESIGN.md b/docs/API_DESIGN.md index e69de29b..7f9c75a8 100644 --- a/docs/API_DESIGN.md +++ b/docs/API_DESIGN.md @@ -0,0 +1,389 @@ +# tbDEX API Design (APID) + +**Last Updated:** June 13, 2024 + +**Custom DSL Version:** 0.1.0 + +- [Resources](#resources) + - [`ResourceKind`](#resourcekind) + - [`Resource`](#resource) + - [`ResourceMetadata`](#resourcemetadata) + - [`Offering`](#offering) + - [`OfferingData`](#offeringdata) + - [`PayinDetails`](#payindetails) + - [`PayinMethod`](#payinmethod) + - [`PayoutDetails`](#payoutdetails) + - [`PayoutMethod`](#payoutmethod) + - [`Balance`](#balance) + - [`BalanceData`](#balancedata) +- [Messages](#messages) + - [`MessageKind`](#messagekind) + - [`Message`](#message) + - [`MessageMetadata`](#messagemetadata) + - [`Rfq`](#rfq) + - [`CreateRfqData`](#createrfqdata) + - [`CreateSelectedPayinMethod`](#createselectedpayinmethod) + - [`CreateSelectedPayoutMethod`](#createselectedpayoutmethod) + - [`RfqData`](#rfqdata) + - [`SelectedPayinMethod`](#selectedpayinmethod) + - [`SelectedPayoutMethod`](#selectedpayoutmethod) + - [`RfqPrivateData`](#rfqprivatedata) + - [`PrivatePaymentDetails`](#privatepaymentdetails) + - [`Quote`](#quote) + - [`QuoteData`](#quotedata) + - [`QuoteDetails`](#quotedetails) + - [`PaymentInstructions`](#paymentinstructions) + - [`Order`](#order) + - [`OrderStatus`](#orderstatus) + - [`OrderStatusData`](#orderstatusdata) + - [`Close`](#close) + - [`CloseData`](#closedata) + +🚧 Codify the Web5 APID dependencies 🚧 + +🚧 "valid next" 🚧 + +# Resources + +## `ResourceKind` + +```pseudocode! +ENUM ResourceKind + offering, + balance, +``` + +## `Resource` + +```pseudocode! +INTERFACE Resource + METHOD sign(bearer_did: BearerDid) + METHOD verify(): bool +``` + +> 🚧 `signature` is a required field on all `Resource` implementations, but we have a `sign()` method which must be called +> +> 🚧 instead we should've passed a `Signer` (or `BearerDid`) into the constructor + +## `ResourceMetadata` + +```pseudocode! +CLASS ResourceMetadata + PUBLIC DATA kind: string + PUBLIC DATA from: string + PUBLIC DATA to: string + PUBLIC DATA id: string + PUBLIC DATA protocol: string + PUBLIC DATA createdAt: string + PUBLIC DATA updatedAt: string? +``` + +## `Offering` + +```pseudocode! +CLASS Offering IMPLEMENTS Resource + PUBLIC DATA metadata: ResourceMetadata + PUBLIC DATA data: OfferingData + PUBLIC DATA signature: string + CONSTRUCTOR(from: string, data: OfferingData, protocol: string) + CONSTRUCTOR(json: string) + METHOD sign(bearer_did: BearerDid) + METHOD verify(): bool +``` + +### `OfferingData` + +```pseudocode! +CLASS OfferingData + PUBLIC DATA description: string + PUBLIC DATA payoutUnitsPerPayinUnit: string + PUBLIC DATA payin PayinDetails + PUBLIC DATA payout PayoutDetails + PUBLIC DATA requiredClaims PresentationDefinition +``` + +#### `PayinDetails` + +```pseudocode! +CLASS PayinDetails + PUBLIC DATA currencyCode: string + PUBLIC DATA min: string? + PUBLIC DATA max: string? + PUBLIC DATA methods: []PayinMethod +``` + +##### `PayinMethod` + +```pseudocode! +CLASS PayinMethod + PUBLIC DATA kind: string + PUBLIC DATA name: string? + PUBLIC DATA description: string? + PUBLIC DATA group: string? + PUBLIC DATA requiredPaymentDetails: JsonNode? // 🚧 + PUBLIC DATA fee: string? + PUBLIC DATA min: string? + PUBLIC DATA max: string? +``` + +#### `PayoutDetails` + +```pseudocode! +CLASS PayoutDetails + PUBLIC DATA currencyCode: string + PUBLIC DATA min: string? + PUBLIC DATA max: string? + PUBLIC DATA methods: []PayoutMethod +``` + +##### `PayoutMethod` + +```pseudocode! +CLASS PayinMethod + PUBLIC DATA kind: string + PUBLIC DATA name: string? + PUBLIC DATA description: string? + PUBLIC DATA group: string? + PUBLIC DATA requiredPaymentDetails: JsonNode? // 🚧 + PUBLIC DATA fee: string? + PUBLIC DATA min: string? + PUBLIC DATA max: string? + PUBLIC DATA estimatedSettlementTime: int +``` + +## `Balance` + +```pseudocode! +CLASS Balance IMPLEMENTS Resource + PUBLIC DATA metadata: ResourceMetadata + PUBLIC DATA data: BalanceData + PUBLIC DATA signature: string + CONSTRUCTOR(from: string, data: BalanceData, protocol: string) + CONSTRUCTOR(json: string) + METHOD sign(bearer_did: BearerDid) + METHOD verify(): bool +``` + +### `BalanceData` + +```pseudocode! +CLASS BalanceData + PUBLIC DATA currencyCode: string + PUBLIC DATA available: string +``` + +# Messages + +## `MessageKind` + +```pseudocode! +ENUM MessageKind + rfq, + quote, + order, + orderstatus, + close, +``` + +## `Message` + +```pseudocode! +INTERFACE Message + METHOD sign(bearer_did: BearerDid) + METHOD verify(): bool +``` + +## `MessageMetadata` + +```pseudocode! +CLASS MessageMetadata + PUBLIC DATA from: string + PUBLIC DATA to: string + PUBLIC DATA kind: MessageKind + PUBLIC DATA id: string + PUBLIC DATA exchangeId: string + PUBLIC DATA externalId: string? + PUBLIC DATA createdAt: string + PUBLIC DATA protocol: string +``` + +## `Rfq` + +```pseudocode! +CLASS Rfq IMPLEMENTS Message + PUBLIC DATA metadata: MessageMetadata + PUBLIC DATA data: RfqData + PUBLIC DATA privateData: RfqPrivateData + PUBLIC DATA signature: string + CONSTRUCTOR(to: string, from: string, rfqData: CreateRfqData, protocol: string, externalId: string?) + CONSTRUCTOR(json: string, requireAllPrivateData: bool?) + METHOD sign(bearer_did: BearerDid) + METHOD verify(): bool + METHOD verifyOfferingRequirements(offering: Offering): bool + METHOD verifyAllPrivateData(): bool + METHOD verifyPresentPrivateData(): bool +``` + +### `CreateRfqData` + +```pseudocode! +CLASS CreateRfqData + PUBLIC DATA offeringId: string + PUBLIC DATA payin: CreateSelectedPayinMethod + PUBLIC DATA payout: CreateSelectedPayoutMethod + PUBLIC DATA claims: string[] +``` + +#### `CreateSelectedPayinMethod` + +```pseudocode! +CLASS CreateSelectedPayinMethod + PUBLIC DATA kind: string + PUBLIC DATA paymentDetails: Map? // 🚧 + PUBLIC DATA amount: string +``` + +#### `CreateSelectedPayoutMethod` + +```pseudocode! +CLASS CreateSelectedPayoutMethod + PUBLIC DATA kind: string + PUBLIC DATA paymentDetails: Map // 🚧 +``` + +### `RfqData` + +```pseudocode! +CLASS RfqData + PUBLIC DATA offeringId: string + PUBLIC DATA payin: SelectedPayinMethod + PUBLIC DATA payout: SelectedPayoutMethod + PUBLIC DATA claimsHash: string? +``` + +#### `SelectedPayinMethod` + +```pseudocode! +CLASS SelectedPayinMethod + PUBLIC DATA kind: string + PUBLIC DATA paymentDetailsHash: string? + PUBLIC DATA amount: string +``` + +#### `SelectedPayoutMethod` + +```pseudocode! +CLASS SelectedPayoutMethod + PUBLIC DATA kind: string + PUBLIC DATA paymentDetailsHash: string? +``` + +### `RfqPrivateData` + +```pseudocode! +CLASS RfqPrivateData + PUBLIC DATA salt: string + PUBLIC DATA payin: PrivatePaymentDetails? + PUBLIC DATA payout: PrivatePaymentDetails? + PUBLIC DATA claims: string[]? +``` + +#### `PrivatePaymentDetails` + +```pseudocode! +CLASS PrivatePaymentDetails + PUBLIC DATA paymentDetails: Map? // 🚧 +``` + +## `Quote` + +```pseudocode! +CLASS Quote IMPLEMENTS Message + PUBLIC DATA metadata: MessageMetadata + PUBLIC DATA data: QuoteData + PUBLIC DATA signature: string + CONSTRUCTOR(to: string, from: string, exchangeId: string, quoteData: QuoteData, protocol: string, externalId: string?) + CONSTRUCTOR(json: string) + METHOD sign(bearer_did: BearerDid) + METHOD verify(): bool +``` + +### `QuoteData` + +```pseudocode! +CLASS QuoteData + PUBLIC DATA expiresAt: string + PUBLIC DATA payin: QuoteDetails + PUBLIC DATA payout: QuoteDetails +``` + +#### `QuoteDetails` + +```pseudocode! +CLASS QuoteDetails + PUBLIC DATA currencyCode: string + PUBLIC DATA amount: string + PUBLIC DATA fee: string? + PUBLIC DATA paymentInstructions: PaymentInstructions? +``` + +##### `PaymentInstructions` + +```pseudocode! +CLASS PaymentInstructions + PUBLIC DATA link: string? + PUBLIC DATA instruction: string? +``` + +## `Order` + +```pseudocode! +CLASS Order IMPLEMENTS Message + PUBLIC DATA metadata: MessageMetadata + PUBLIC DATA signature: string + CONSTRUCTOR(to: string, from: string, exchangeId: string, protocol: string, externalId: string?) + CONSTRUCTOR(json: string) + METHOD sign(bearer_did: BearerDid) + METHOD verify(): bool +``` + +## `OrderStatus` + +```pseudocode! +CLASS OrderStatus IMPLEMENTS Message + PUBLIC DATA metadata: MessageMetadata + PUBLIC DATA data: OrderStatusData + PUBLIC DATA signature: string + CONSTRUCTOR(to: string, from: string, exchangeId: string, orderStatusData: OrderStatusData, protocol: string, externalId: string?) + CONSTRUCTOR(json: string) + METHOD sign(bearer_did: BearerDid) + METHOD verify(): bool +``` + +### `OrderStatusData` + +```pseudocode! +CLASS OrderStatusData + PUBLIC DATA orderStatus: string +``` + +## `Close` + +```pseudocode! +CLASS Close IMPLEMENTS Message + PUBLIC DATA metadata: MessageMetadata + PUBLIC DATA data: CloseData + PUBLIC DATA signature: string + CONSTRUCTOR(to: string, from: string, exchangeId: string, closeData: CloseData, protocol: string, externalId: string?) + CONSTRUCTOR(json: string) + METHOD sign(bearer_did: BearerDid) + METHOD verify(): bool +``` + +### `CloseData` + +```pseudocode! +CLASS CloseData + PUBLIC DATA reason: string? + PUBLIC DATA success: bool? +``` \ No newline at end of file diff --git a/docs/rfc-0001/README.md b/docs/rfc-0001/README.md index 87e8c3af..e69de29b 100644 --- a/docs/rfc-0001/README.md +++ b/docs/rfc-0001/README.md @@ -1,52 +0,0 @@ -# tbDEX API Design (APID) - -**Last Updated:** June 13, 2024 - -**Custom DSL Version:** 0.1.0 - -- [Resources](#resources) - - [`Resource`](#resource) - - [`ResourceMetadata`](#resourcemetadata) - - [Offering](#offering) - - [`OfferingData`](#offeringdata) -- [Messages](#messages) - -# Resources - -## `Resource` - -```pseudocode! -INTERFACE Resource - METHOD sign(bearer_did: BearerDid) - METHOD verify(): bool -``` - -## `ResourceMetadata` - -```pseudocode! -CLASS ResourceMetadata - PUBLIC DATA kind: string - /// 🚧 more members -``` - -## Offering - -```pseudocode! -CLASS Offering IMPLEMENTS Resource - CONSTRUCTOR(from: string, data: OfferingData, protocol: string) - CONSTRUCTOR(json: string) - METHOD sign(bearer_did: BearerDid) - METHOD verify(): bool -``` - -### `OfferingData` - -```pseudocode! -CLASS OfferingData - PUBLIC DATA description: string - /// 🚧 more members -``` - -# Messages - -... \ No newline at end of file From 86da2118ee0a538eb2004de2545090e5a506c51d Mon Sep 17 00:00:00 2001 From: Kendall Weihe Date: Wed, 19 Jun 2024 08:44:47 -0400 Subject: [PATCH 3/7] Prepare for Draft PR --- docs/API_DESIGN.md | 77 ++++++++++++++++++++++++++++++---------------- 1 file changed, 50 insertions(+), 27 deletions(-) diff --git a/docs/API_DESIGN.md b/docs/API_DESIGN.md index 7f9c75a8..b6feaef9 100644 --- a/docs/API_DESIGN.md +++ b/docs/API_DESIGN.md @@ -4,16 +4,17 @@ **Custom DSL Version:** 0.1.0 +- [Web5 Dependencies](#web5-dependencies) - [Resources](#resources) - [`ResourceKind`](#resourcekind) - [`Resource`](#resource) - [`ResourceMetadata`](#resourcemetadata) - [`Offering`](#offering) - [`OfferingData`](#offeringdata) - - [`PayinDetails`](#payindetails) - - [`PayinMethod`](#payinmethod) - - [`PayoutDetails`](#payoutdetails) - - [`PayoutMethod`](#payoutmethod) + - [`PayinDetails`](#payindetails) + - [`PayinMethod`](#payinmethod) + - [`PayoutDetails`](#payoutdetails) + - [`PayoutMethod`](#payoutmethod) - [`Balance`](#balance) - [`BalanceData`](#balancedata) - [Messages](#messages) @@ -22,26 +23,33 @@ - [`MessageMetadata`](#messagemetadata) - [`Rfq`](#rfq) - [`CreateRfqData`](#createrfqdata) - - [`CreateSelectedPayinMethod`](#createselectedpayinmethod) - - [`CreateSelectedPayoutMethod`](#createselectedpayoutmethod) + - [`CreateSelectedPayinMethod`](#createselectedpayinmethod) + - [`CreateSelectedPayoutMethod`](#createselectedpayoutmethod) - [`RfqData`](#rfqdata) - - [`SelectedPayinMethod`](#selectedpayinmethod) - - [`SelectedPayoutMethod`](#selectedpayoutmethod) + - [`SelectedPayinMethod`](#selectedpayinmethod) + - [`SelectedPayoutMethod`](#selectedpayoutmethod) - [`RfqPrivateData`](#rfqprivatedata) - - [`PrivatePaymentDetails`](#privatepaymentdetails) + - [`PrivatePaymentDetails`](#privatepaymentdetails) - [`Quote`](#quote) - [`QuoteData`](#quotedata) - - [`QuoteDetails`](#quotedetails) - - [`PaymentInstructions`](#paymentinstructions) + - [`QuoteDetails`](#quotedetails) + - [`PaymentInstructions`](#paymentinstructions) - [`Order`](#order) - [`OrderStatus`](#orderstatus) - [`OrderStatusData`](#orderstatusdata) - [`Close`](#close) - [`CloseData`](#closedata) +- [HTTP Client](#http-client) + - [`TbdexHttpClient`](#tbdexhttpclient) -🚧 Codify the Web5 APID dependencies 🚧 +# Web5 Dependencies -🚧 "valid next" 🚧 +- `PresentationDefinition` +- `BearerDid` + +> [!WARNING] +> +> 🚧 Add links to Web5 APID # Resources @@ -102,7 +110,7 @@ CLASS OfferingData PUBLIC DATA requiredClaims PresentationDefinition ``` -#### `PayinDetails` +### `PayinDetails` ```pseudocode! CLASS PayinDetails @@ -112,7 +120,7 @@ CLASS PayinDetails PUBLIC DATA methods: []PayinMethod ``` -##### `PayinMethod` +### `PayinMethod` ```pseudocode! CLASS PayinMethod @@ -126,7 +134,7 @@ CLASS PayinMethod PUBLIC DATA max: string? ``` -#### `PayoutDetails` +### `PayoutDetails` ```pseudocode! CLASS PayoutDetails @@ -136,7 +144,7 @@ CLASS PayoutDetails PUBLIC DATA methods: []PayoutMethod ``` -##### `PayoutMethod` +### `PayoutMethod` ```pseudocode! CLASS PayinMethod @@ -231,10 +239,10 @@ CLASS CreateRfqData PUBLIC DATA offeringId: string PUBLIC DATA payin: CreateSelectedPayinMethod PUBLIC DATA payout: CreateSelectedPayoutMethod - PUBLIC DATA claims: string[] + PUBLIC DATA claims: []string ``` -#### `CreateSelectedPayinMethod` +### `CreateSelectedPayinMethod` ```pseudocode! CLASS CreateSelectedPayinMethod @@ -243,7 +251,7 @@ CLASS CreateSelectedPayinMethod PUBLIC DATA amount: string ``` -#### `CreateSelectedPayoutMethod` +### `CreateSelectedPayoutMethod` ```pseudocode! CLASS CreateSelectedPayoutMethod @@ -261,7 +269,7 @@ CLASS RfqData PUBLIC DATA claimsHash: string? ``` -#### `SelectedPayinMethod` +### `SelectedPayinMethod` ```pseudocode! CLASS SelectedPayinMethod @@ -270,7 +278,7 @@ CLASS SelectedPayinMethod PUBLIC DATA amount: string ``` -#### `SelectedPayoutMethod` +### `SelectedPayoutMethod` ```pseudocode! CLASS SelectedPayoutMethod @@ -285,10 +293,10 @@ CLASS RfqPrivateData PUBLIC DATA salt: string PUBLIC DATA payin: PrivatePaymentDetails? PUBLIC DATA payout: PrivatePaymentDetails? - PUBLIC DATA claims: string[]? + PUBLIC DATA claims: []string? ``` -#### `PrivatePaymentDetails` +### `PrivatePaymentDetails` ```pseudocode! CLASS PrivatePaymentDetails @@ -317,7 +325,7 @@ CLASS QuoteData PUBLIC DATA payout: QuoteDetails ``` -#### `QuoteDetails` +### `QuoteDetails` ```pseudocode! CLASS QuoteDetails @@ -327,7 +335,7 @@ CLASS QuoteDetails PUBLIC DATA paymentInstructions: PaymentInstructions? ``` -##### `PaymentInstructions` +### `PaymentInstructions` ```pseudocode! CLASS PaymentInstructions @@ -386,4 +394,19 @@ CLASS Close IMPLEMENTS Message CLASS CloseData PUBLIC DATA reason: string? PUBLIC DATA success: bool? -``` \ No newline at end of file +``` + +# HTTP Client + +## `TbdexHttpClient` + +```pseudocode! +CLASS TbdexHttpClient + STATIC METHOD getOfferings(pfiDid: string): []Offering + STATIC METHOD getBalances(pfiDid: string, requesterDid: BearerDid): []Balance + STATIC METHOD createExchange(rfq: Rfq, replyTo: string?) + STATIC METHOD submitOrder(order: Order) + STATIC METHOD submitClose(close: Close) + STATIC METHOD getExchange(pfiDid: string, requesterDid: BearerDid, exchangeId: string): []Message + STATIC METHOD getExchanges(pfiDid: string, requesterDid: BearerDid): []Message +``` From e10b5b4b8d585c98698d399ca2a732ce28b4b9cc Mon Sep 17 00:00:00 2001 From: Kendall Weihe Date: Thu, 20 Jun 2024 09:27:16 -0400 Subject: [PATCH 4/7] Create rfcs directory --- docs/{rfc-0001/README.md => API_DESIGN-preferred.md} | 0 docs/rfcs/rfc-0001/README.md | 0 2 files changed, 0 insertions(+), 0 deletions(-) rename docs/{rfc-0001/README.md => API_DESIGN-preferred.md} (100%) create mode 100644 docs/rfcs/rfc-0001/README.md diff --git a/docs/rfc-0001/README.md b/docs/API_DESIGN-preferred.md similarity index 100% rename from docs/rfc-0001/README.md rename to docs/API_DESIGN-preferred.md diff --git a/docs/rfcs/rfc-0001/README.md b/docs/rfcs/rfc-0001/README.md new file mode 100644 index 00000000..e69de29b From c60b4af7bc593b52896226aca5bc9d2d1ab46249 Mon Sep 17 00:00:00 2001 From: Kendall Weihe Date: Thu, 20 Jun 2024 11:46:34 -0400 Subject: [PATCH 5/7] Remove empty file --- docs/API_DESIGN-preferred.md | 0 1 file changed, 0 insertions(+), 0 deletions(-) delete mode 100644 docs/API_DESIGN-preferred.md diff --git a/docs/API_DESIGN-preferred.md b/docs/API_DESIGN-preferred.md deleted file mode 100644 index e69de29b..00000000 From 89be13b6762127bac3f6580a4ca2bf4d0cfab14e Mon Sep 17 00:00:00 2001 From: Kendall Weihe Date: Sat, 22 Jun 2024 19:29:52 -0400 Subject: [PATCH 6/7] Deviate from tbdex-kt to ideal for Rust Core --- docs/API_DESIGN.md | 145 +++++++++++++++++++++++++++------------------ 1 file changed, 88 insertions(+), 57 deletions(-) diff --git a/docs/API_DESIGN.md b/docs/API_DESIGN.md index b6feaef9..0f172e2a 100644 --- a/docs/API_DESIGN.md +++ b/docs/API_DESIGN.md @@ -7,7 +7,6 @@ - [Web5 Dependencies](#web5-dependencies) - [Resources](#resources) - [`ResourceKind`](#resourcekind) - - [`Resource`](#resource) - [`ResourceMetadata`](#resourcemetadata) - [`Offering`](#offering) - [`OfferingData`](#offeringdata) @@ -19,7 +18,6 @@ - [`BalanceData`](#balancedata) - [Messages](#messages) - [`MessageKind`](#messagekind) - - [`Message`](#message) - [`MessageMetadata`](#messagemetadata) - [`Rfq`](#rfq) - [`CreateRfqData`](#createrfqdata) @@ -40,7 +38,30 @@ - [`Close`](#close) - [`CloseData`](#closedata) - [HTTP Client](#http-client) - - [`TbdexHttpClient`](#tbdexhttpclient) + - [`Exchange`](#exchange) + - [`get_offerings()`](#get_offerings) + - [`get_balances()`](#get_balances) + - [`create_exchange()`](#create_exchange) + - [`submit_order()`](#submit_order) + - [`submit_close()`](#submit_close) + - [`get_exchange()`](#get_exchange) + - [`get_exchanges()`](#get_exchanges) + +> [!WARNING] +> +> We need to define `JsonNode` + +> [!WARNING] +> +> Snake vs camel casing is inconsistent + +> [!NOTE] +> +> All `CONSTRUCTOR(json: string)` instances in this APID perform cryptographic verification. + +> [!WARNING] +> +> `FUNCTION` needs to be added to the Custom DSL # Web5 Dependencies @@ -61,18 +82,6 @@ ENUM ResourceKind balance, ``` -## `Resource` - -```pseudocode! -INTERFACE Resource - METHOD sign(bearer_did: BearerDid) - METHOD verify(): bool -``` - -> 🚧 `signature` is a required field on all `Resource` implementations, but we have a `sign()` method which must be called -> -> 🚧 instead we should've passed a `Signer` (or `BearerDid`) into the constructor - ## `ResourceMetadata` ```pseudocode! @@ -93,10 +102,9 @@ CLASS Offering IMPLEMENTS Resource PUBLIC DATA metadata: ResourceMetadata PUBLIC DATA data: OfferingData PUBLIC DATA signature: string - CONSTRUCTOR(from: string, data: OfferingData, protocol: string) - CONSTRUCTOR(json: string) - METHOD sign(bearer_did: BearerDid) - METHOD verify(): bool + CONSTRUCTOR(bearer_did: BearerDid, from: string, data: OfferingData, protocol: string) + CONSTRUCTOR(json: string) + METHOD to_json(): string ``` ### `OfferingData` @@ -166,10 +174,9 @@ CLASS Balance IMPLEMENTS Resource PUBLIC DATA metadata: ResourceMetadata PUBLIC DATA data: BalanceData PUBLIC DATA signature: string - CONSTRUCTOR(from: string, data: BalanceData, protocol: string) + CONSTRUCTOR(bearer_did: BearerDid, from: string, data: BalanceData, protocol: string) CONSTRUCTOR(json: string) - METHOD sign(bearer_did: BearerDid) - METHOD verify(): bool + METHOD to_json(): string ``` ### `BalanceData` @@ -193,14 +200,6 @@ ENUM MessageKind close, ``` -## `Message` - -```pseudocode! -INTERFACE Message - METHOD sign(bearer_did: BearerDid) - METHOD verify(): bool -``` - ## `MessageMetadata` ```pseudocode! @@ -223,13 +222,9 @@ CLASS Rfq IMPLEMENTS Message PUBLIC DATA data: RfqData PUBLIC DATA privateData: RfqPrivateData PUBLIC DATA signature: string - CONSTRUCTOR(to: string, from: string, rfqData: CreateRfqData, protocol: string, externalId: string?) + CONSTRUCTOR(bearer_did: BearerDid, to: string, from: string, rfqData: CreateRfqData, protocol: string, externalId: string?) CONSTRUCTOR(json: string, requireAllPrivateData: bool?) - METHOD sign(bearer_did: BearerDid) - METHOD verify(): bool - METHOD verifyOfferingRequirements(offering: Offering): bool - METHOD verifyAllPrivateData(): bool - METHOD verifyPresentPrivateData(): bool + METHOD to_json(): string ``` ### `CreateRfqData` @@ -310,10 +305,9 @@ CLASS Quote IMPLEMENTS Message PUBLIC DATA metadata: MessageMetadata PUBLIC DATA data: QuoteData PUBLIC DATA signature: string - CONSTRUCTOR(to: string, from: string, exchangeId: string, quoteData: QuoteData, protocol: string, externalId: string?) + CONSTRUCTOR(bearer_did: BearerDid, to: string, from: string, exchangeId: string, quoteData: QuoteData, protocol: string, externalId: string?) CONSTRUCTOR(json: string) - METHOD sign(bearer_did: BearerDid) - METHOD verify(): bool + METHOD to_json(): string ``` ### `QuoteData` @@ -349,10 +343,9 @@ CLASS PaymentInstructions CLASS Order IMPLEMENTS Message PUBLIC DATA metadata: MessageMetadata PUBLIC DATA signature: string - CONSTRUCTOR(to: string, from: string, exchangeId: string, protocol: string, externalId: string?) + CONSTRUCTOR(bearer_did: BearerDid, to: string, from: string, exchangeId: string, protocol: string, externalId: string?) CONSTRUCTOR(json: string) - METHOD sign(bearer_did: BearerDid) - METHOD verify(): bool + METHOD to_json(): string ``` ## `OrderStatus` @@ -362,10 +355,9 @@ CLASS OrderStatus IMPLEMENTS Message PUBLIC DATA metadata: MessageMetadata PUBLIC DATA data: OrderStatusData PUBLIC DATA signature: string - CONSTRUCTOR(to: string, from: string, exchangeId: string, orderStatusData: OrderStatusData, protocol: string, externalId: string?) + CONSTRUCTOR(bearer_did: BearerDid, to: string, from: string, exchangeId: string, orderStatusData: OrderStatusData, protocol: string, externalId: string?) CONSTRUCTOR(json: string) - METHOD sign(bearer_did: BearerDid) - METHOD verify(): bool + METHOD to_json(): string ``` ### `OrderStatusData` @@ -382,10 +374,9 @@ CLASS Close IMPLEMENTS Message PUBLIC DATA metadata: MessageMetadata PUBLIC DATA data: CloseData PUBLIC DATA signature: string - CONSTRUCTOR(to: string, from: string, exchangeId: string, closeData: CloseData, protocol: string, externalId: string?) + CONSTRUCTOR(bearer_did: BearerDid, to: string, from: string, exchangeId: string, closeData: CloseData, protocol: string, externalId: string?) CONSTRUCTOR(json: string) - METHOD sign(bearer_did: BearerDid) - METHOD verify(): bool + METHOD to_json(): string ``` ### `CloseData` @@ -398,15 +389,55 @@ CLASS CloseData # HTTP Client -## `TbdexHttpClient` +## `Exchange` + +```pseudocode! +CLASS Exchange + PUBLIC DATA rfq: Rfq + PUBLIC DATA quote: Quote + PUBLIC DATA order: Order + PUBLIC DATA order_statuses: []OrderStatus + PUBLIC DATA close: Close +``` + +## `get_offerings()` + +```pseudocode! +FUNCTION get_offerings(pfi_did_uri: string): []Offering +``` + +## `get_balances()` + +```pseudocode! +FUNCTION get_balances(pfi_did_uri: string, bearer_did: BearerDid): []Balance +``` + +## `create_exchange()` + +```pseudocode! +FUNCTION create_exchange(rfq: Rfq, reply_to: string?) +``` + +## `submit_order()` + +```pseudocode! +FUNCTION submit_order(order: Order) +``` + +## `submit_close()` + +```pseudocode! +FUNCTION submit_close(order: Order) +``` + +## `get_exchange()` + +```pseudocode! +FUNCTION get_exchange(pfi_did_uri: string, bearer_did: BearerDid, exchange_id: string): Exchange +``` + +## `get_exchanges()` ```pseudocode! -CLASS TbdexHttpClient - STATIC METHOD getOfferings(pfiDid: string): []Offering - STATIC METHOD getBalances(pfiDid: string, requesterDid: BearerDid): []Balance - STATIC METHOD createExchange(rfq: Rfq, replyTo: string?) - STATIC METHOD submitOrder(order: Order) - STATIC METHOD submitClose(close: Close) - STATIC METHOD getExchange(pfiDid: string, requesterDid: BearerDid, exchangeId: string): []Message - STATIC METHOD getExchanges(pfiDid: string, requesterDid: BearerDid): []Message +FUNCTION get_exchanges(pfi_did_uri: string, bearer_did: BearerDid): []string ``` From e188b3050363132db6c2e8b53630c6f0e7f792d0 Mon Sep 17 00:00:00 2001 From: Kendall Weihe Date: Thu, 27 Jun 2024 23:13:17 -0400 Subject: [PATCH 7/7] Add RFC --- docs/API_DESIGN.md | 8 +++---- docs/rfcs/rfc-0001/README.md | 46 ++++++++++++++++++++++++++++++++++++ 2 files changed, 50 insertions(+), 4 deletions(-) diff --git a/docs/API_DESIGN.md b/docs/API_DESIGN.md index 0f172e2a..c16790e0 100644 --- a/docs/API_DESIGN.md +++ b/docs/API_DESIGN.md @@ -55,10 +55,6 @@ > > Snake vs camel casing is inconsistent -> [!NOTE] -> -> All `CONSTRUCTOR(json: string)` instances in this APID perform cryptographic verification. - > [!WARNING] > > `FUNCTION` needs to be added to the Custom DSL @@ -97,6 +93,10 @@ CLASS ResourceMetadata ## `Offering` +> [!NOTE] +> +> All `CONSTRUCTOR(json: string)` instances in this APID perform cryptographic verification on the `signature` property. + ```pseudocode! CLASS Offering IMPLEMENTS Resource PUBLIC DATA metadata: ResourceMetadata diff --git a/docs/rfcs/rfc-0001/README.md b/docs/rfcs/rfc-0001/README.md index e69de29b..5a2dd321 100644 --- a/docs/rfcs/rfc-0001/README.md +++ b/docs/rfcs/rfc-0001/README.md @@ -0,0 +1,46 @@ +# RFC-0001 Standard tbDEX API Design (APID) Document v0.1.0 + +- [Summary](#summary) +- [Motivation](#motivation) +- [Detailed Design](#detailed-design) + - [Known Limitations](#known-limitations) +- [Drawbacks](#drawbacks) +- [Alternatives](#alternatives) +- [Prior Art](#prior-art) + +# Summary + +Lay the initial foundations to drive early implementations, with the expectation to subsequently iterate and build upon. + +# Motivation + +The driving motivations for a standard API design, adopted across many language implementations, is well defined in the [Web5 RFC-0001](https://github.com/TBD54566975/web5-rs/blob/main/docs/rfcs/rcf-0001/README.md#motivation). + +# Detailed Design + +This RFC defines version 0.1.0 of the APID, but is expected to change hereafter. + +Many of the design decisions were made from prior implementations, namely [the `tbdex-kt` implementation](https://github.com/TBD54566975/tbdex-kt/). Primary deviations from the [pre-existing `tbdex-kt` implementation](https://github.com/TBD54566975/tbdex-kt/) are three-fold. + +1. A difference of namespacing. Although namespacing is not currently explicitly supported in the [Custom DSL](https://github.com/TBD54566975/web5-rs/blob/main/docs/CUSTOM_DSL.md), the hierarchy of the APID markdown file has implicit intentions of namespacing. +2. Migration away from a class `TbdexHttpClient` with static methods, wherein the class served no purpose other than an obscure namespace, and towards functions -- for example, instead of `TbdexHttpClient.getOfferings()` it's now `tbdex.httpclient` (namespaces) and a function `getOfferings()`. +3. No polymorphic base classes for `Resource` and `Message`. Polymorphism is primarily relevant for use cases of developer-defined instances, for example a "bring-your-own" cryptography abstraction wherein the SDK cannot support the full enumeration of possible use cases, but that's not the case for tbDEX resources and messages, both of which are well-defined. For situations of DRY, permissions are encouraged. + +## Known Limitations + +- Lack of support for `FUNCTIONS` in the [Custom DSL](https://github.com/TBD54566975/web5-rs/blob/main/docs/CUSTOM_DSL.md). +- Lack of support for a JSON Object type in the [Custom DSL](https://github.com/TBD54566975/web5-rs/blob/main/docs/CUSTOM_DSL.md). +- Snake casing and camel casing is inconsistent. +- No "HTTP Server" functionality. + +# Drawbacks + +None. + +# Alternatives + +None. + +# Prior Art + +Heavily inspired by [Web5 RFC-0001](https://github.com/TBD54566975/web5-rs/blob/main/docs/rfcs/rcf-0001/README.md). \ No newline at end of file