Minotari Payment Processor

The Minotari Payment Processor is a service designed to handle and automate payment processing within the Minotari ecosystem. It integrates with a Tari base node and a Payment Receiver (PR) API to manage payment batches, sign transactions, broadcast them to the network, and confirm their status on-chain.

Workspaces

This project consists of two main workspaces:

minotari-client

This workspace contains autogenerated client code for interacting with external services.

To regenerate the client code, use the following make command:

make regenerate-client

minotari_payment_processor

This is the main executable service of the project.

Setup and Installation

To get the minotari_payment_processor up and running, follow these steps:

1. Database Setup

First, you need to create and migrate the SQLite database:

mkdir -p data
sqlx database create
sqlx migrate run

Database migrations are located in the migrations folder.

2. Database Schema Regeneration

If the database schema changes, you need to regenerate the documentation in docs/db/db_schema.sql using the following command:

make db-dump

Configuration

The minotari_payment_processor is configured using environment variables. These variables can be set in a .env file in the project root or directly in your system environment.

Because the application uses structured configuration, hierarchical settings (like accounts) use double underscores (__) as separators.

Core Settings

• DATABASE_URL (Mandatory): The URL for the SQLite database.
  • Example: DATABASE_URL="sqlite://data/payments.db"
• TARI_NETWORK (Optional): The Tari network to run on. Defaults to MainNet.
  • Options: MainNet, Esmeralda, NextNet, Igor.
  • Example: TARI_NETWORK="Esmeralda"
• PAYMENT_RECEIVER (Mandatory): The URL of the Payment Receiver (PR) API.
  • Example: PAYMENT_RECEIVER="http://localhost:9000"
• BASE_NODE (Mandatory): The URL of the Tari Base Node.
  • Example: BASE_NODE="https://rpc.esmeralda.tari.com"
• CONSOLE_WALLET_PATH (Mandatory): The path to the minotari_console_wallet executable, used for signing transactions.
• CONSOLE_WALLET_BASE_PATH (Mandatory): Wallet base path (--base-path).
  • Example: CONSOLE_WALLET_PATH="/usr/local/bin/minotari_console_wallet"
• CONSOLE_WALLET_PASSWORD (Mandatory): The password for the console wallet.
  • Example: CONSOLE_WALLET_PASSWORD="my_secure_password"
• LISTEN_IP (Optional): The IP address the HTTP API server will listen on. Defaults to 0.0.0.0.
  • Example: LISTEN_IP="0.0.0.0"
• LISTEN_PORT (Optional): The port the HTTP API server will listen on. Defaults to 9145.
  • Example: LISTEN_PORT="9145"
• CONFIRMATION_CHECKER_REQUIRED_CONFIRMATIONS (Optional): The number of confirmations required before a transaction is considered final. Defaults to 10.
  • Example: CONFIRMATION_CHECKER_REQUIRED_CONFIRMATIONS="10"
• MAX_INPUT_COUNT_PER_TX (Optional): The max number of UTXOs, which can be used in a single transaction. If it exceeds this amount, we do a COINJOIN. Defaults to 400.
  • Example: MAX_INPUT_COUNT_PER_TX="200"

Account Configuration

The application supports configuring multiple payment receiver accounts. Because the number of accounts is dynamic, the configuration uses a specific pattern with double underscores (__) to map environment variables to specific accounts.

The format is: ACCOUNTS__<UNIQUE_IDENTIFIER>__<FIELD>

Each account requires three fields: NAME, VIEW_KEY (Hex), and PUBLIC_SPEND_KEY (Hex).

Example configuration for two accounts ("Primary" and "Backup"):

# Account 1: Identifier 'default'
ACCOUNTS__DEFAULT__NAME="default"
ACCOUNTS__DEFAULT__VIEW_KEY="a1b2c3d4..." 
ACCOUNTS__DEFAULT__PUBLIC_SPEND_KEY="e5f6g7h8..."

# Account 2: Identifier 'backup'
ACCOUNTS__BACKUP__NAME="backup"
ACCOUNTS__BACKUP__VIEW_KEY="11223344..."
ACCOUNTS__BACKUP__PUBLIC_SPEND_KEY="55667788..."

## HTTP API

The service exposes an HTTP API that can be easily browsed using Swagger UI. If you are using the default port, you can access it at:

http://localhost:9145/swagger-ui/

The API definitions can be found in `minotari_payment_processor/src/api/mod.rs`.

## Background Workers

The `minotari_payment_processor` runs several background workers that perform specific tasks in the payment processing pipeline. Each worker executes its task and then sleeps for a configurable duration.

The workers are located in the `minotari_payment_processor/src/workers` directory and include:

*   `batch_creator`: Responsible for creating new payment batches from received payments.
*   `unsigned_tx_creator`: Creates unsigned transactions for payment batches by interacting with the Payment Receiver (PR) API.
*   `transaction_signer`: Signs unsigned transactions using the `minotari_console_wallet`.
*   `broadcaster`: Broadcasts signed transactions to the Tari base node.
*   `confirmation_checker`: Checks the confirmation status of broadcasted transactions on the Tari blockchain.