mirror of
https://github.com/Permissionless-Software-Foundation/bch-dex.git
synced 2026-09-21 16:52:00 -07:00
Forked from slp-dex
This commit is contained in:
Chris Troutner
@@ -0,0 +1,64 @@
|
||||
# Developer Documentation
|
||||
|
||||
This is living documentation that will be updated, edited, and changed over time, using the same version control as the rest of the code. The purpose of this documentation is to capture and explain how this ipfs-swap-service interacts with the [P2WDB](https://github.com/Permissionless-Software-Foundation/ipfs-p2wdb-service), to create a permissionless, censorship-resistant database for storing trading orders. A web client will be built in the future that will interact with the REST API of this app.
|
||||
|
||||
- [Specification](./specification.md)
|
||||
|
||||
# Overview
|
||||
|
||||
There are three major pieces of software behind the ipfs-swap-service concept. They work together to form a censorship-resistant application for exchanging transaction data for building trades.
|
||||
|
||||
|
||||
|
||||
- _Client_ could be a web browser, or a command-line client like [psf-bch-wallet](https://github.com/Permissionless-Software-Foundation/psf-bch-wallet) or [psf-avax-wallet](https://github.com/Permissionless-Software-Foundation/psf-avax-wallet).
|
||||
- [ipfs-swap-service](https://github.com/christroutner/ipfs-swap-service) is the back end REST API that maintains a local database of information that the client reads from.
|
||||
- [P2WDB](https://github.com/Permissionless-Software-Foundation/ipfs-p2wdb-service) is the pay-to-write global database with a REST API for interfacing with the other two pieces of software.
|
||||
|
||||
The arrows in the image represent the information flow between the three pieces of software:
|
||||
|
||||
- The _Client_ displays information about orders. It _reads_ this information from ipfs-swap-service.
|
||||
- The _Client_ is also a wallet. It can generate the needed transactions to _write_ information to the P2WDB.
|
||||
- `ipfs-swap-service` imports data from the global P2WDB database into its local database, using a [webhook](https://en.wikipedia.org/wiki/Webhook) (dashed line). It can also custody funds by creating an _Offer_ and submitting the data to the P2WDB to generate an _Order_ (solid line).
|
||||
|
||||
This architecture keeps the global database highly censorship resistant, while allowing local installations to maintain tight control over the user experience. The goal is to have many redundant copies of `ipfs-swap-service` on the network, and to empower individual traders to run their own, private copy.
|
||||
|
||||
# Back End
|
||||
|
||||
This section provides additional information on `ipfs-swap-service` and P2WDB back end software.
|
||||
|
||||
## P2WDB
|
||||
|
||||
The heart of the censorship resistance is the pay-to-write database ([P2WDB](https://github.com/Permissionless-Software-Foundation/ipfs-p2wdb-service)). This is an [OrbitDB](https://orbitdb.org/) peer-to-peer (p2p) database. The write-access rules have been customized to allow anyone to write to the database, so long as they prove that a sufficient quantity of [PSF tokens](https://psfoundation.cash) have been burned, to pay for the write.
|
||||
|
||||
Because OrbitDB is a p2p database, no one party holds the 'official' copy of the database. Instead, like a blockchain, the database is replicated among several peers, and they coordinate updates to the database using consensus rules. Peers are free to leave or enter the network. Each peer independently verifies the database entries have sufficient proof-of-burn.
|
||||
|
||||
## `ipfs-swap-service`
|
||||
|
||||
The [ipfs-swap-service](https://github.com/christroutner/ipfs-swap-service) replicates a copy of the global P2WDB, but has the ability to apply localized filters to the data before passing it on to the _Client_, to be displayed.
|
||||
|
||||
`ipfs-swap-service` is based on this [ipfs-service-provider boilerplate](https://github.com/Permissionless-Software-Foundation/ipfs-service-provider). It's a production-ready template for a web server, providing interfaces via REST API over HTTP, as well as JSON RPC over IPFS. It includes many features for building a web app. This includes user management and authentication, REST API and JSON RPC scaffolding, API documentation, Docker container generation, and extensive test coverage. It's intended to be customized for the needs of the website administrator.
|
||||
|
||||
- [Specification](./specification.md)
|
||||
|
||||
# Workflows
|
||||
|
||||
This section describes the protocols for the database interactions between the three main software components.
|
||||
|
||||
These are just a brief, high-level overview. Review the [Specifications](./specification.md) for more details.
|
||||
|
||||
## Writing to the Global Database
|
||||
|
||||
Adding data to the global P2WDB is a result of the interaction between the _Client_ and the P2WDB. Ideally, `ipfs-swap-service` is not involved. The [p2wdb npm library](https://www.npmjs.com/package/p2wdb) can be leveraged for easy reading and writing to the P2WDB.
|
||||
|
||||
During development, `ipfs-swap-service` is being used to submit Offers to the P2WDB and custody funds. When the project reaches maturity, these functions may be removed, and they should be handled by the Client, so that legal issues around custody of funds are not a problem.
|
||||
|
||||
Writing data follows these steps:
|
||||
|
||||
- A user submits data to the POST `/offer` REST API endpoint. This will move the funds a segregated UTXO and submit the data to the P2WDB to convert the Offer to an Order. Offers are tracked by the local instance of `ipfs-swap-service`, but Orders are tracked by all instances of `ipfs-swap-service`.
|
||||
- The P2WDB REST API will then evaluate the data and attempt to update the p2p database using the TXID.
|
||||
- Each peer on the network will independently validate the new database entry.
|
||||
- `ipfs-swap-service` will receive a webhook call to its POST `/order` endpoint. This event will trigger the import of the new data into the apps local Mongo database, and generate a new Order model.
|
||||
|
||||
## Reading from the Local Database
|
||||
|
||||
The Client reads data from the local database stored by `ipfs-swap-service`, and does not read the global database directly. This gives `ipfs-swap-service` the opportunity to filter and modify the data locally for a more controlled user experience.
|
||||
Binary file not shown.
Binary file not shown.
|
After Width: | Height: | Size: 7.2 KiB |
Binary file not shown.
Binary file not shown.
|
After Width: | Height: | Size: 10 KiB |
@@ -0,0 +1,107 @@
|
||||
# ipfs-swap-service Specification
|
||||
|
||||
This document contains a high-level, human-readable specification for the four major architectural areas of the ipfs-swap-service:
|
||||
|
||||
- Entities
|
||||
- Use Cases
|
||||
- Controllers (inputs)
|
||||
- Adapters (outputs)
|
||||
|
||||
This reflects the [Clean Architecture](https://troutsblog.com/blog/clean-architecture) design pattern.
|
||||
|
||||
## Entities
|
||||
|
||||
Entities make up the core business concepts. If these entities change, they fundamentally change the entire app.
|
||||
|
||||
### Order
|
||||
|
||||
An order 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:
|
||||
|
||||
- _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.
|
||||
- _rateInSats_ - The rate in terms of tokens-per-currency-unit.
|
||||
- For Bitcoin, the min currency is sats.
|
||||
- For AVAX, the min currency is nano-Avax.
|
||||
- for eCash, the min currency is bits.
|
||||
- _minSatsToExchange_ - The minimum order size accepted.
|
||||
- _signature_ - A message signed by the address which created the order.
|
||||
- _sigMsg_ - The clear-text message used to generate the signature.
|
||||
- _utxoTxid_ - The TXID of the UTXO used in the order.
|
||||
- _utxoVout_ - The vout of the UTXO used in the order.
|
||||
- _numTokens_ - The maximum number of tokens offered for sale.
|
||||
- _timestamp_ - The ISO time when the order was created.
|
||||
- _localTimestamp_ - The localized time when the order was created.
|
||||
- _p2wdbTxid_ - The TXID proof-of-burn used to add the order to the P2WDB.
|
||||
- _p2wdbHash_ - The hash used to identify the order entry in the P2WDB.
|
||||
- _lokadId_ - Not used. Provided for future functionality.
|
||||
- _messageType_ - Not used. Provided for future functionality.
|
||||
- _messageClass_ - Not used. Provided for future functionality.
|
||||
|
||||
### Offer
|
||||
|
||||
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 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 accidentally spent, which is why it needs to be segregated from other wallet UTXOs.
|
||||
|
||||
Offer 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.
|
||||
- _offerPubKey_ - The public key used to generate the BCH address, used for encryption.
|
||||
- _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.
|
||||
- _rateInSats_ - The rate in terms of tokens-per-currency-unit.
|
||||
- For Bitcoin, the min currency is sats.
|
||||
- For AVAX, the min currency is nano-Avax.
|
||||
- for eCash, the min currency is bits.
|
||||
- _minSatsToExchange_ - The minimum order size accepted.
|
||||
- _signature_ - A message signed by the address which created the order.
|
||||
- _sigMsg_ - The clear-text message used to generate the signature.
|
||||
- _utxoTxid_ - The TXID of the UTXO used in the order.
|
||||
- _utxoVout_ - The vout of the UTXO used in the order.
|
||||
- _numTokens_ - The maximum number of tokens offered for sale.
|
||||
- _timestamp_ - The ISO time when the order was created.
|
||||
- _localTimestamp_ - The localized time when the order was created.
|
||||
- _p2wdbTxid_ - The TXID proof-of-burn used to add the order to the P2WDB.
|
||||
- _p2wdbHash_ - The hash used to identify the order entry in the P2WDB.
|
||||
- _lokadId_ - Not used. Provided for future functionality.
|
||||
- _messageType_ - Not used. Provided for future functionality.
|
||||
- _messageClass_ - Not used. Provided for future functionality.
|
||||
|
||||
## 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
|
||||
|
||||
- **`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.
|
||||
|
||||
## 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 by the P2WDB. This will notify the `ipfs-swap-service` that a new entry has been added to the P2WDB that matches the `appId` of `swap-<chain>`, where `<chain>` 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`.
|
||||
|
||||
## Adapters
|
||||
|
||||
Adapters are output libraries so that the business logic doesn't need to know any specific information about the I/O. They are essentially the output of the application.
|
||||
|
||||
- **localdb** - An adapter for the local database (MongoDB).
|
||||
- **ipfs** - An adapter for IPFS and the ipfs-coord library. It allows the app to use the JSON-RPC over IPFS.
|
||||
Reference in New Issue
Block a user