Stox Architecture Overview — Part 1: Blockchain Requests Manager

This article is the first in a series of articles discussing how Stox is working with the Ethereum blockchain.

This article is pretty technical and assumes you have knowledge in basic blockchain (transactions, nonce, gas) and software architecture (queues, services, database) terms.

Stox is a semi-decentralized Ethereum blockchain application. Meaning part of application operates directly on the Ethereum network with smart contracts, but a lot of the time it needs to interact with the blockchain from the outside, and that includes sending transactions to the Ethereum network. As transactions sent to the blockchain may take several minutes or even several hours (depending on network congestion), we needed to develop an infrastructure for automatically sending and tracking transactions on the blockchain.

To achieve that we designed a system that receives any kind of request on one end, construct a blockchain transaction, and outputs its result on the other end.

Our system needed to have the following characteristics:

1. Handle any Ethereum transaction, regardless of what it does, e.g. transfer funds, manage smart contract, deploy smart contracts.
2. Figure out the correct gas price to send a transaction.
3. Manage private keys for transaction signing.
4. Track transactions status and send a message in case of success / failure.

We chose an architecture of microservices centered around a single database. Requests and results will be transmitted via a queue. The database is used to save requests and transactions data and state.

Microservices Explained

Requests Reader

Description: The request reader listens to incoming requests from the incoming-requests queue and writes to the database. The request reader is indifferent to the specific request type it received.

Input: Request from incoming-requests queue

Output: Database request record

Example Output:

• Id: bab9713a-c161–2297–80b4–009c99986c17
• type: prize
• data:
  {
  “userStoxWalletAddress”:”0x2e9cd0e826dab8460eb628bae294bb44ac48aad6",
  “Amount”:10,
  “tokenAddress”:”0x006BeA43Baa3f7A6f765F14f10A1a1b08334EF45",
  “prizeDistributorAddress”:”0x69189716420FFCc0cA2e4F9869433389Df331f9c”
  }

Requests Handler

Description: The request handler takes requests and prepare transactions to be sent to the blockchain. Each transaction is prepared differently depends on the type of the request record. The request handler contains a list of “plugins” to handle the different types of request. Example of plugins:

• Send Prize — Send tokens prize to a user
• Create Wallet — Create a new smart wallet
• Withdraw Tokens — Withdraw tokens for a user from a Stox wallet
• Assign Wallets — Assign a Stox smart wallet for a user

To handle a new request type we just add a new plugin to the request handler.

The plugins write a new transaction record containing the binary transaction data sent to the blockchain.

Input: Database request record

Output: Database transaction record

Example Output:

• transaction data: 0xa9059cbb0000000000000000000000001e9cd0e826dab8460eba28bae294bb44ac48a5d6000000000000000000000000000000000000000000000000042758776b707d48
• from: 0x69189716420FFCc0cA2e4F9869433389Df331f9c
• to: 0x006BeA43Baa3f7A6f765F14f10A1a1b08334EF45

Note: More on stox smart wallets will be discussed on part 3 of the stox architecture overview.

Transactions Writer

Description: The transactions writer takes unsent transactions, determines their gas price and nonce, signs them in the transaction signer, and send them to the Ethereum network. After sending the transaction it records the transaction hash so we can track its execution.

Input: Database unsent transaction record

Output: Database sent transaction record

Note: More about determining gas price will be discussed on part 2 of the stox architecture overview.

Example Output:

• transaction hash: 0x1301091191d0f558a12d225ed4bd05d9c19d7a418f49778687a9f469da15f9c6
• gas price (gwei): 5
• nonce: 2852

Transactions Signer

Description: The transaction signer receives an unsigned transaction, retrieve the the appropriate private key for the transaction from the virtual private keys safe, and signs the transaction.

Input: Unsigned Transaction

Output: Signed Transaction

Transactions Monitor

Description: The transactions monitor periodically samples the transaction hash in the Ethereum node and looks for a transaction receipt to indicate success or failure of the transaction. When it finds a completed transaction, in publishes a message to the appropriate completed-[request-type]-requests queue.

Input: sent transaction record

Output: Completed request message to the completed-[request-type]-requests queue

Example Output:

Message published to the completed-prize-requests queue

• Id: bab9713a-c161–2297–80b4–009c99986c17
• transaction hash: 0x1301091191d0f558a12d225ed4bd05d9c19d7a418f49778687a9f469da15f9c6
• is successful: true
• error: none

The Request Manager is part of Stox blockchain prediction markets platform. You can view the entire source code on our github repository.

Also check out the other parts of our architecture overview:

• Part 2 — Optimizing Gas Costs