Home

Welcome to the dash-payment-gateway wiki!

How it Works

Technology Stack

• bitcore-lib-dash is used for wallet operations such as fetching a child address from the HD Wallet.
• express is used to handle incoming requests.
• log is used for logging at various levels.
• MySQL is used as the persistence layer and as a permanent caching layer.
• socket.io-client is used to listen for events from insight. Instead of polling for payments, transactions are listened for.
• lokijs is used as a fast memory cache. No data is persisted across restarts.

Software Architecture

The flow of data throughout the application follows a pretty standard pattern. Server.js acts as the single point of entrance into the application and as the controller in terms of MVC. Care is taken to place no business logic here.

Service Layer

All business logic is maintained at this layer, in a folder named service and in logically named files. Anything the Server needs is handled by the relevant service.

Data Layer

Data required by the service layer is provided by the repository layer. The Server should not request data directly from a repository, but rather from a service which can then request it from a repository. The service layer is import so operations may be performed on the data (or auditing of the operation) can be performed separately from the request for data and the physical fetch of the data.

Cacheing

The application relies on two layers of cacheing.

Persistent Cache

One layer of caching is a persistence layer and is used to store results from third party resources such as a request for the current price of Dash. For example, to get the current price of Dash, an HTTP request is made to a third party provider. Each time a successful call is made, the results of the call are cached in the database. If subsequent calls fail, the request will failover to the cache. It's persisted so it can survive system restarts.

Memory Cache

Since the application receives transaction events via a socket from the Insight API, the likelihood of handling many events is high during peak trading. To mitigate this, all pending payments are cached in memory in a loki collection. When a transaction event is received, the cache is queried for a match. If a match is found, control is handed off to an asynchronous service operation. The database and cache are kept in sync.

Startup

On startup, the application Bootstraps itself by executing the following operations.

1. A connection to the database is made and a connection pool is formed.
2. The counter for the HD wallet child is created if it does not already exist.
3. The wallet seed is converted to BIP32 format.
4. The cache is initialized. This involves creating the loki collection and populating it with all non-fully paid transactions. These are the transactions we care about.
5. A socket connection is made the Insight API so transactions can be listened to.
6. Insight is called for each pending payment identified. If any matches are found, the database and cache are updated with the latest balances. If a payment is made in full, the callback URL is invoked.

Request to Create a Receiver

A receiver represents a payment for something. It may or may not ever be paid. It consists of various pieces of data needed to process the payment if a payment is ever actually detected on the blockchain. See Create Receiver for for information on this operation.

Payments and Partial Payments

There are two situations in which a payment is identified.

1. A relevant transaction occurs on the Dash network and the Insight API broadcasts the event to our listener.
2. During the startup process. This indicates that payment was received during system downtime and must now be handled.

When a payment fully satisfies the receiver record, the transaction is removed from cache, the database record is updated, and the user supplied callback URL is invoked with details of the receiver record.

When a partial payment is received, the transaction is updated in cache, the database record is updated, and the user supplied callback URL is invoked with details of the receiver record. Partial payments trigger a callback to the client so that the client is aware of such and event. This address situations where a partial payment is accidentally received and the end user believes payment has been satisfied.