Introduction

UMA lets anyone send and receive money (fiat and crypto) 24/7 using their favorite UMA-enabled wallet, exchange, or bank. UMA is global and open source. This guide walks through the life of an UMA payment step-by-step to explain the standard and how you can implement UMA using the UMA SDK.
UMA Demo UX
  • UMA - Universal Money Address. An UMA looks like an email address with a leading $ symbol. For example, $alice@vasp.com
  • VASP - Virtual Asset Service Provider. A VASP generally includes a business that conducts one or more of the following actions on behalf of customers:
    • Exchange between virtual assets (like bitcoin) and fiat currencies
    • Exchange between one or more forms of virtual assets
    • Transfer of virtual assets
    • Safekeeping or administration or virtual assets or instruments enabling control over virtual assets
    • Participating in and provision of financial services related to an issuer's offer and/or sale of a virtual asset The UMA standard has been designed to help participating VASPs meet key regulatory obligations as part of the messaging and transaction flow.
  • Travel Rule (TR) - Regulated financial institutions (FIs) such as banks, payment services providers, and digital wallets - including VASPs - may be required under the Travel Rule (and related requirements) to collect, send, and receive specific information about a payment sender and recipient when transmitting a customer payment above specified monetary thresholds. The applicability of the Travel Rule depends on the regulatory regimes that apply to the sending and receiving FI, among other factors. UMA facilitates sending and receiving VASP compliance with relevant Travel Rule requirements.
  • Compliance Provider - A third-party or internal compliance service that provides blockchain analysis and related services for risk and regulatory compliance. UMA facilitates risk assessment and transaction monitoring reviews both pre- and post-transaction.
  • Sending VASP - The VASP sending an UMA-powered Lightning payment for its customer. Sometimes referred to as “VASP1” in UMA Standard documents and diagrams.
  • Receiving VASP - The VASP receiving an UMA-powered Lightning payment for its customer. Sometimes referred to as “VASP2” in UMA Standard documents and diagrams.
  • VASP Identity Authority - An optional participant in the UMA standard which can be used to validate public keys of UMA participants. For example, when a receiving VASP retrieves a signature and the signing public key from a sending VASP, it can ask the VASP ID Authority whether the provided public key indeed belongs to the VASP domain specified as the sender.
The UMA Standard is an extension of LNURL and therefore closely aligns with the LNURL-PAY specification.
There are 4 main steps of the UMA payment flow:
  1. The initial lnurlp request from the sending VASP to the receiving VASP. Using the recipient's UMA as provided by the sending user, this call allows the sending VASP to retrieve basic data about the receiver, such as preferred currency, an estimated exchange rate, and the status of the recipient as a VASP (e.g., to determine whether the Travel Rule applies).
  2. The payreq request from the sending VASP to the receiving VASP. This allows the sender to specify an amount to send in the receiving currency. The sending VASP can also include Travel Rule information and any additional required compliance data, e.g., sending node pubkeys and sending channel UTXOs for blockchain analysis review by the receiving VASP’s Compliance Provider. The receiving VASP creates a BOLT-11 invoice which can be returned to the sender.
  3. The sender pays the invoice using the standard Lightning Network payment flow.
  4. Post-transaction hooks to register the transaction with a Compliance Provider, to facilitate post-transaction analysis.
UMA Overview Swimlanes
Along the way, the UMA standard provides mechanisms for verifying the identity of the other VASP, providing and securing compliance data, and ensuring time-bound exchange rates between currencies.
The following sections take a deeper dive into the life of an UMA payment and the corresponding SDK calls needed to complete the flow. First, let's install the SDK to get started:
$ npm install @uma-sdk/core