Crate acceptxmr

source ·
Expand description

AcceptXMR: Accept Monero in Your Application

This library aims to provide a simple, reliable, and efficient means to track monero payments.

To track payments, the PaymentGateway generates subaddresses using your private view key and primary address. It then watches for monero sent to that subaddress using a monero daemon of your choosing, your private view key and your primary address.

Use this library at your own risk, it is young and unproven.

Key Advantages

  • View pair only, no hot wallet.
  • Subaddress based.
  • Pending invoices can be stored persistently, enabling recovery from power loss.
  • Number of confirmations is configurable per-invoice.
  • Ignores transactions with non-zero timelocks.
  • Payment can occur over multiple transactions.

Security

AcceptXMR is non-custodial, and does not require a hot wallet. However, it does require your private view key and primary address for scanning outputs. If keeping these private is important to you, please take appropriate precautions to secure the platform you run your application on and keep your private view key out of your git repository!.

Care is taken to protect users from malicious transactions containing timelocks or duplicate output keys (i.e. the burning bug). For the best protection against the burning bug, it is recommended that users use a dedicated wallet or account index for AcceptXMR that is not used for any other purpose. The payment gateway’s initial height should also be set to the wallet’s restore height. These measures allow AcceptXMR to keep a full inventory of used output keys so that duplicates can be reliably identified.

Also note that anonymity networks like TOR are not currently supported for RPC calls. This means that your network traffic will reveal that you are interacting with the monero network.

Reliability

This library strives for reliability, but that attempt may not be successful. AcceptXMR is young and unproven, and relies on several crates which are undergoing rapid changes themselves. For example, the primary storage layer implementation (Sled) is still in beta.

That said, this payment gateway should survive unexpected power loss thanks to the ability to flush pending invoices to disk each time new blocks/transactions are scanned. A best effort is made to keep the scanning thread free any of potential panics, and RPC calls in the scanning thread are logged on failure and repeated next scan. In the event that an error does occur, the liberal use of logging within this library will hopefully facilitate a speedy diagnosis and correction.

Use this library at your own risk.

Performance

It is strongly recommended that you host your own monero daemon on the same local network. Network and daemon slowness are the primary cause of high invoice update latency in the majority of use cases.

To reduce the average latency before receiving invoice updates, you may also consider lowering the PaymentGateway’s scan_interval below the default of 1 second:

use acceptxmr::{PaymentGateway, storage::stores::InMemory};
use std::time::Duration;

let private_view_key =
    "ad2093a5705b9f33e6f0f0c1bc1f5f639c756cdfc168c8f2ac6127ccbdab3a03";
let primary_address =
    "4613YiHLM6JMH4zejMB2zJY5TwQCxL8p65ufw8kBP5yxX9itmuGLqp1dS4tkVoTxjyH3aYhYNrtGHbQzJQP5bFus3KHVdmf";

let store = InMemory::new();

let payment_gateway = PaymentGateway::builder(
    private_view_key.to_string(),
    primary_address.to_string(),
    store
)
.scan_interval(Duration::from_millis(100)) // Scan for updates every 100 ms.
.build()?;

Please note that scan_interval is the minimum time between scanning for updates. If your daemon’s response time is already greater than your scan_interval, or if your CPU is unable to scan new transactions fast enough, reducing your scan_interval will do nothing.

Features

Serde

The serde feature enables serde (de)serialization on select types.

bincode

The bincode feature enables bincode (de)serialization on select types.

in-memory

The in-memory feature enables the InMemory storage implementation.

sled

The sled feature enables the Sled storage implementation. The bincode feature will also be enabled by this feature.

sqlite

The sqlite feature enables the Sqlite storage implementation. The bincode feature will also be enabled by this feature.

Modules

  • storage
    AcceptXMR can use a storage layer of your choosing. Consumers of this library can use one of the existing storage layers found in stores, or can implement the Storage trait themselves for a custom storage solution.

Structs

  • Invoice
    Representation of an invoice. Invoices are created by the PaymentGateway.
  • InvoiceId
    An invoice ID uniquely identifies a given invoice by the combination of its subaddress index and creation height.
  • PaymentGateway
    The PaymentGateway allows you to track new Invoices, remove old Invoices from tracking, and subscribe to Invoices that are already pending.
  • PaymentGatewayBuilder
    A builder for the payment gateway. Used to configure your desired monero daemon, scan interval, view key, etc.
  • SubIndex
    A subaddress index.
  • Subscriber
    A means of receiving updates on a given invoice. Subscribers are returned by PaymentGateways when subscribing to a invoice.

Enums