ErgoPay Protocol (EIP-20)
EIP-0020: ErgoPay Protocol
Authors: @aslesarenko, @MrStahlfelge
Status: Proposed
Created: 18-August-2021
Overview
ErgoPay is a standard for cross-platform interaction between an online dApp and a wallet app. It facilitates the creation, signing, and sending of Ergo transactions.
Key Features
- Cross-platform wallet and dApp interaction
- QR code and URI scheme support
- Secure transaction signing
- Universal smart contract support
- Cold wallet compatibility
Background and Motivation
Cryptocurrency wallets, such as the Ergo Android Wallet, typically support scanning QR codes of Payment Requests or intercepting a link with a special URI scheme.
However, this is only possible for simple transactions, such as transferring ERGs and assets between Pay-To-Public-Key addresses or transactions that only spend boxes from P2PK addresses.
The Problem
In Ergo's eUTXO model, a box can be protected by an arbitrarily complex contract, and any spending transaction should satisfy that condition. A universal wallet application cannot know all the specific details of all possible contracts.
Therefore, an interaction between a dApp and a wallet is required such that:
- The dApp builds a transaction and makes it available for the wallet application.
- The wallet app shows a confirmation screen to the user, displaying the inboxes and outboxes it is going to sign.
- When the user confirms, the wallet app signs the transaction and submits it to the blockchain or returns it back to the dApp.
- The dApp monitors the transaction on the blockchain and upon confirmations, proceeds with its business logic.
ErgoPay Interaction Protocol
An ErgoPay interaction between a Wallet and a dApp is driven by the dApp's user and proceeds as follows:
User Input
The user enters the necessary information in the dApp's UI and proceeds to a payment screen. Optionally, the dApp can request the user's P2PK address with an extra step using a signing request with a placeholder URL.
Payment Screen
The payment screen shows transaction details and a QR code as well as a clickable link.
Wallet Interaction
The user clicks the link to hand the information over to a wallet application on the same device, or scans the QR code using a wallet application.
Data Parsing
The Wallet application parses the QR code data and obtains either ErgoPaySigningRequest or ReducedTransaction data.
Payment Confirmation
When ErgoPaySigningRequest or ReducedTransaction is obtained, it is shown as a payment screen on the wallet app containing the same transaction details as the dApp screen.
User Confirmation
The user compares the dApp's screen, the Wallet's screen, and the transaction details and confirms the payment by using a "Sign" button.
Transaction Signing
The wallet application signs the transaction either using local private keys or using a Cold Wallet and EIP-0019 protocol. The result of signing is SignedTransaction data.
Transaction Submission
The Wallet obtains the transaction id and sends it to the dApp using ErgoPayTransactionSent API post message to replyToUrl if the URL is provided. If successful, the wallet then submits SignedTransaction to the blockchain.
Monitoring
The dApp monitors the transaction by id and proceeds with its business logic upon receiving enough confirmations. This concludes the ErgoPay protocol.
Data Formats
The data formats of this EIP are based on a new binary data structure and serialization format called ReducedTransaction, which is described in EIP-0019.
Option 1: URL Request
dApp provides URL request for ErgoPaySigningRequest information.
ergopay://<URL>The URL is provided without the https prefix. HTTP communication is not allowed except for IP addresses (for testing within a local network).
Option 2: URI Scheme
dApp provides URI scheme containing ReducedTransaction.
ergopay:<ReducedTransaction, base 64 url safe encoded>It is not possible to provide description, address, message, and replyToUrl in this simpler interchange format.
ErgoPaySigningRequest
The wallet application should request the URL and obtain the following data (in JSON format):
ErgoPaySigningRequest:
- transaction: ReducedTransaction (optional*)
- address: String (optional)
- message: String (optional*)
- messageSeverity: String (optional) "INFORMATION", "WARNING", "ERROR"
- replyToUrl: String (optional)💡 Important Notes
- Either a transaction or a message must be provided, otherwise the request is invalid.
- The wallet application should show the message and display the messageSeverity in a suitable way, if provided.
- If address is provided by the dApp, the wallet can preselect the key the user needs to sign the transaction.
Wallet App Implementation
Requirements
- QR code scanning capability
- URI scheme handling
- Transaction signing
- Blockchain submission
- Cold wallet support (optional)
dApp Implementation
Requirements
- Transaction building
- QR code generation
- API endpoint for signing requests
- Transaction monitoring
- User interface integration
Benefits for dApps
- dApp or website don't need to handle user's secrets (mnemonic/private keys)
- dApp's users don't need to worry about the security of their private keys
- ErgoPay EIP is compatible with Cold Wallet EIP
- Adding ErgoPay to product detail pages, cart, checkout page
- The payment screen can be presented immediately after user taps the Ergo Pay button
- ErgoPay is simple and universal, supporting all smart contracts
Benefits for Wallets
- Users can participate in Ergo dApps
- Wallet team can receive service fees from transactions
- Enhanced user experience with seamless dApp integration
- Competitive advantage over wallets without ErgoPay support
- Universal smart contract support
- Cross-platform compatibility