From 8f7d997b3e0a517be3fdca781887a0a108f931ff Mon Sep 17 00:00:00 2001 From: Chris Troutner Date: Fri, 11 Mar 2022 16:37:29 -0800 Subject: [PATCH] Editing dev docs --- dev-docs/specification.md | 50 +++++++++++++++++++++++---------------- 1 file changed, 30 insertions(+), 20 deletions(-) diff --git a/dev-docs/specification.md b/dev-docs/specification.md index 640ddc4..07f0e5a 100644 --- a/dev-docs/specification.md +++ b/dev-docs/specification.md @@ -13,12 +13,12 @@ This reflects the [Clean Architecture](https://bafybeiajggd4zju7oen627bcy5l32hrx Entities make up the core business concepts. If these entities change, they fundamentally change the entire app. -### Order +### Offer -An order is created from data passed to the app by the P2WDB webhook. +An offer is created from data passed to the app by the P2WDB webhook. It is destroyed when the UTXO described in the Signal has been detected as spent. -Order entities have the following properties: +Offer entities have the following properties: - _tokenId_ - The unique ID that identifies the class of token being offered for sale. - _buyOrSell_ - A string with a value `buy` or `sell` indicating which type of offer this is. @@ -40,15 +40,15 @@ Order entities have the following properties: - _messageType_ - Not used. Provided for future functionality. - _messageClass_ - Not used. Provided for future functionality. -### Offer +### Order -An Offer Entity is nearly the same as an Order. But while an Order is generated -by a webhook from P2WDB, the Offer Entity is created internally. It is used -to track an 'Order' generated and managed by this application. +An Order Entity is nearly the same as an Offer. But while an Offer is generated +by a webhook from P2WDB, the Order Entity is created internally. It is used +to track an 'Offer' generated and managed by this application. -The Offer tracks the [HD index address](https://github.com/bitcoinbook/bitcoinbook/blob/develop/ch05.asciidoc#hd-wallets-bip-32bip-44) used to hold tokens or BCH for sale. This is the part of the app concerned with the custody of the funds. It creates a segregated [UTXO](https://github.com/bitcoinbook/bitcoinbook/blob/develop/ch06.asciidoc#transaction-outputs-and-inputs) to hold the offered asset. The Offer is automatically destroyed if the UTXO is spent. +The Order tracks the [HD index address](https://github.com/bitcoinbook/bitcoinbook/blob/develop/ch05.asciidoc#hd-wallets-bip-32bip-44) used to hold tokens or BCH for sale. This is the part of the app concerned with the custody of the funds. It creates a segregated [UTXO](https://github.com/bitcoinbook/bitcoinbook/blob/develop/ch06.asciidoc#transaction-outputs-and-inputs) to hold the offered asset. The Order is automatically destroyed if the UTXO is spent. -Offer entities have the following properties: +Order entities have the following properties: - _offerIpfsId_ - The IPFS ID of the instance of `ipfs-swap-service` that is managing the offer. - _offerBchAddr_ - The BCH address controlling the offer. @@ -73,31 +73,41 @@ Offer entities have the following properties: - _messageType_ - Not used. Provided for future functionality. - _messageClass_ - Not used. Provided for future functionality. +### Counter Offer + +A Counter Offer is the other side of an Offer. It contains a partially signed transaction, created by the Taker. The Maker will review the Counter Offer before accepting and finalizing the trade. + +Details TBD. + ## Use Cases Use cases are verbs or actions that is done _to_ an Entity or _between_ Entities. -### Order - -- **`createOrder()`** - This method is triggered by a webhook from the P2WDB. It will take the data provided by the P2WDB and create a new Order entity in the local database. - ### Offer +- **`createOffer()`** - This method is triggered by a webhook from the P2WDB. It will take the data provided by the P2WDB and create a new Order entity in the local database. + +### Order + - **`ensureFunds()`** - Ensure that the wallet has enough BCH and tokens to complete the requested trade. -- **`moveTokens()`** - Move the tokens indicated in the offer to a temporary holding address. This will generate the UTXO used in the webhook message. This function moves the funds and returns the UTXO information. -- **`createOffer()`** - A macro command that leverages `ensureFunds()` and `moveTokens()`, to create a new Offer and submit it to the P2WDB. +- **`moveTokens()`** - Move the tokens indicated in the order to a temporary holding address. This will generate the UTXO used in the webhook message. This function moves the funds and returns the UTXO information. +- **`createOrder()`** - A macro command that leverages `ensureFunds()` and `moveTokens()`, to create a new Order and submit it to the P2WDB. + +### Counter Offer + +TBD ## Controllers Controllers are inputs to the system. When a controller is activated, it causes the system to react in some way. -### Orders - -- **POST /order** - This POST REST API endpoint will be triggered by a webhook generated from P2WDB. This will notify the `bch-dex` that a new entry has been added to the P2WDB that matches the `appId` of `swap-`, where `` has a value of `avax`, `bch`, or `ecash`. It's a new entry that should be evaluated for inclusion in the `ipfs-swap-service` local database. - ### Offers -- **POST /offer** - This POST REST API endpoint can be triggered by the Client or a simple curl call. It passes in the data needed for `ipfs-swap-service` to generate and track a new Offer, then submit the data to the P2WDB to generate an Order that is tracked by all other instances of `ipfs-swap-service`. +- **POST /offer** - This POST REST API endpoint will be triggered by a webhook generated from P2WDB. This will notify the `bch-dex` that a new entry has been added to the P2WDB that matches the `appId` of `swap-`, where `` has a value of `avax`, `bch`, or `ecash`. It's a new entry that should be evaluated for inclusion in the `ipfs-swap-service` local database. + +### Orders + +- **POST /order** - This POST REST API endpoint can be triggered by the Client or a simple curl call. It passes in the data needed for `bch-dex` to generate and track a new Order, then submit the data to the P2WDB to generate an Offer that is tracked by all other instances of `bch-dex`. ## Adapters