image.png

An Unofficial Guide to Qubic Services Integration

Integrate Qubic into existing services via full node, remote node, archive server, or API, with varying control and complexity.

Qsilver · Feb 17, 2024.

Introduction

Integrating Qubic into existing services can be done in four main ways, each offering different levels of control and complexity:

  1. Run a full node: Direct access to in-memory data for operations.
  2. Run a remote node: Query public full nodes to obtain the required data for operations.
  3. Run an archive server: Build a local full archive of all Qubic data for operations.
  4. Interface with Qubic API server: Simplest method, but with less control over data availability.

The lower the number, the more work involved but the more control you have over data availability. Regardless of the level you choose, understanding the critical differences about Qubic is essential.

Important Differences about Qubic

For services dealing with monetary value, the two most important differences about Qubic are:

  1. Even if a txid is included in a validated tick, it might not have done anything.
  2. Address balance can be changed without a specific transaction transferring from A to B, e.g., by a smart contract operation.

Due to these differences, Qubic processing should be based on address balance changes, ensuring changes by smart contracts do not confuse the logic.

Deposit Handling

To simplify deposit handling, it's recommended to use normal transactions. Deposits made using smart contracts could be ignored or handled manually (with an extra charge to cover costs).

  1. Iterate through all transactions in each tick and identify destination addresses belonging to customers.
  2. Flag these addresses for balance checking.
  3. Get entity info for flagged addresses to see which ones received new funds.
  4. Update the current entity info for addresses that received new funds.

Balance changes might not match the transaction amount due to txid failures or smart contract deposits. Ignoring SC deposits ensures the user gets credited for SC deposits even if the txid failed.

Balance-Based Deposit Processing

This method might require more bandwidth but is viable for midrange services by polling hundreds of thousands of addresses over the network via a remote node. It ensures all deposit methods are properly credited, enhancing user experience.

  1. Maintain the latest validated entity data for each user address.
  2. In a polling loop, compare the latest entity data to the validated entity data.
  3. Validate the latest entity data using the merkle tree.
  4. If it validates, update the validated entity data and generate a deposit event based on the difference in total deposits.

Withdraw Processing

Small Volumes

  1. Obtain validated entity data for the sending address.
  2. Queue a withdraw transaction based on destination and amount.
  3. Generate the expected entity data for outgoingAmount and the current outgoingAmount + amount of the withdrawal.
  4. Process the queue by creating and broadcasting the withdraw transaction.
  5. After a specified tick, check if entity data outgoingAmount has changed to the expected amount.
  6. If it has, mark the withdraw as complete, remove it from the queue, and update validated entity data. If not, retry the process.

Medium Volumes

  1. Use the SENDMANY SC command to batch up to 25 withdrawals in a single transaction.
  2. Apply the same logic as for small volumes, using SENDMANY instead of simple send transactions.
  3. A single address using SENDMANY can achieve around 100 withdrawals per minute.

High Volumes

  1. Use the sendmany app to send up to 15,625 payments, completing in about 20 ticks (~8000 withdrawals per minute).
  2. The sendmany app uses the SENDMANY SC in a three-level fanout. Payments are specified in a .csv file, processed to calculate the total amount, and sent to a special address.
  3. Once funds arrive, they are distributed in three generations (25 x 25 x 25 payments).

sendmany Repository

For details on the sendmany program, visit the repository:

sendmany GitHub Repository

Conclusion

Integrating Qubic into existing services requires careful consideration of data handling, especially for monetary transactions. By choosing the appropriate integration method and understanding the unique aspects of Qubic, services can effectively manage deposits and withdrawals at varying scales.

Read Qsilver’s “Unofficial” Series

For the latest updates, join the Valis Discord, follow us on X, and bookmark our blog.

← Previous

Qwallet, Qclient and Qserver

Next →

Setting Up and Running a Qubic Archive Server

On this Page