StacksPay Specification

Find the official proposed SIP at the Stacks SIP repo: https://github.com/stacksgov/sips/pull/202

Preamble

SIP Number: to be assigned

Title: Stacks Pay - A Payment Request Standard for Stacks Blockchain Payments

Author: Dan Trevino <dantrevino@gmail.com>

Consideration: Technical

Type: Standard

Status: Draft

Created: 24 September 2024

Layer: Application

License: CC0-1.0: Creative Commons CC0 1.0 Universal

Discussion-To: https://github.com/stacksgov/sips

Sign-off:

Abstract

Stacks Pay is a proposed payment request standard for the Stacks blockchain. The standard aims to create easy, secure bundles of transaction information that can be seamlessly shared off-chain, simplifying payment interactions between payers and recipients by providing a standardized method for encoding, decoding, and processing payment requests. By standardizing the structure and parameters of payment requests, Stacks Pay ensures interoperability between wallets and applications within the Stacks ecosystem.

This proposal does not require any changes to the current operation of the Stacks blockchain. Instead, consider these as convenience methods for wrapping existing Stacks transaction information, making them easily shareable.

License and Copyright

This SIP’s copyright is held by the Stacks Open Internet Foundation. This SIP is made available under the terms of the Creative Commons CC0 1.0 Universal license, available at https://creativecommons.org/publicdomain/zero/1.0/

Terminology

The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this document should be interpreted according to RFC 2119.

Introduction

The Stacks ecosystem requires a standardized protocol for payment request generation and processing to support its growing adoption. While established blockchain ecosystems have implemented payment request standards that enable features such as request reusability, metadata handling, and cryptographic verification, Stacks currently lacks such a protocol. This absence of a unified standard compels developers to implement custom solutions, risking ecosystem fragmentation through incompatible implementations and inconsistent payment flows.

Stacks Pay addresses this gap by introducing a payment request standard tailored specifically for the Stacks blockchain. The standard simplifies the process of sending and receiving payments, enhances interoperability among wallets and applications, and increases security by providing mechanisms to tie transactions back to payment requests.

Stacks Pay does not define smart contracts that may be used to facilitate specific functions, like subscriptions or NFT mints. Stacks Pay is strictly focused on defining the transaction payment information structure and encoding.

Operations

Stacks Pay defines several standard operations that specify the type of payment action to be performed. Each operation type has specific required and optional parameters.

`support`

Function: An open-ended, reusable request. Allows the payer to specify the amount and optionally the token, suitable for donations, tips, or gifts.

Required Parameters:

operation: 'support'
recipient: A valid Stacks address.
If the token parameter is not 'STX', the functionName defaults to 'transfer' by the wallet.

Optional Parameters:

token: Either 'STX' or a valid SIP-010 contract address. If not provided, defaults to 'STX'.
description: MAY be included to provide additional context for the payment request.
expiresAt: MAY be included; wallets MUST NOT process payment requests past the expiry time.
memo: MAY be included; MUST NOT include personal information.

Parameters to Ignore:

amount, contractName, dueDate, functionName, invoiceNumber. Wallets MUST ignore these parameters if present.

`invoice`

Function: Represents a payment request, such as an invoice for P2P payments or product purchases.

Required Parameters:

operation: 'invoice'
recipient: A valid Stacks address.
token: MUST be either 'STX' or a valid SIP-010 contract address.
amount: The amount to be paid.

Optional Parameters:

description: MAY be included to provide context for the payment request.
expiresAt: MAY be included; if included, wallets MUST NOT process payment requests past the expiry time.
invoiceNumber: MAY be included as an identifier.
dueDate: MAY be included.
memo: MAY be included. MUST NOT include personal information.

Parameters to Ignore:

contractName, functionName: Wallets MUST ignore these parameters if present.

`mint`

Function: Represents a non-fungible token minting request.

Required Parameters:

operation: 'mint'
contractName: A valid SIP-009 contract address.
functionName: A public contract function, typically mint or claim
token: MUST be either 'STX' or a valid SIP-010 contract name.
amount: The amount to be paid.

Optional Parameters:

recipient: MAY be included; if present, MUST be a valid Stacks address. The NFT will be minted for the specified address.
description: MAY be included to provide context for the payment request
expiresAt: MAY be included. If included wallets MUST NOT process links after the expiry date/time.
invoiceNumber: MAY be included by the link creator to track individual requests.
memo: MAY be included. MUST NOT include personal information.

Parameters to Ignore:

contractName, functionName, dueDate: Wallets MUST ignore these parameters if present.

Custom Operations

Applications MAY define custom operations for specific use cases. Custom operation types MUST be prefixed to prevent naming conflicts (e.g., 'custom-example').

Handling Unrecognized Operations: If a wallet encounters an unrecognized operation type, it SHOULD:
Warn the User: Inform the user that the operation type is unrecognized.
Provide Safe Defaults: Default to a standard payment flow if possible.
Fail Gracefully: Prevent unexpected behavior or security risks.

Parameter Table (summary)

Operation	token	recipient	amount	description	memo	expiresAt	contractName	functionName	dueDate
support	O	R	I	O	O	I	I	I	I
invoice	R	R	R	O	O	O	I	I	O
mint	I	O	R	O	O	O	R	R	I
custom	O*	O*	O*	O*	O*	O*	O*	O*	O*

R - required
O - optionalas determined
I - ignored
O* - custom links are defined on a per application basis

Token Types

The token parameter indicates the type of token for the payment and MUST be one of:

'STX': For payments using the native STX token.
A valid SIP-010 contract address: For payments using SIP-010 compliant fungible tokens.

Note: SIP-010 contract addresses should be in the format CONTRACT_PRINCIPLE.CONTRACT_NAME, without the associated contract identifier.

URL Scheme

The Stacks Pay URL scheme MUST use the custom protocol web+stx:, followed by bech32m encoding of an operation and query parameters encoding the payment details with stx as the human readable part (hrp) of the encoding. The order of the parameters does not matter.

Format:

Format of the url string prior to encoding:

<operation>?recipient=<recipient>&token=<token>&amount=<amount>[&additional_params]

For example, here is the unencoded url using 'STX' token:

invoice?recipient=SP3FBR...&token=STX&amount=1000&description=Payment%20for%20Services

And here is an example using the SIP-010 Nothing Token:

invoice?operation=invoice&recipient=SP3FBR...&token=SP32AEEF6WW5Y0NMJ1S8SBSZDAY8R5J32NBZFPKKZ.nope&amount=1000&description=Payment+for+services

operation: Specifies the type of action or transaction. It MUST be included and be a string value.
Query Parameters: The payment parameters are appended as URL-encoded query parameters. See specific operation types for which are included for which operations.

Example encoded Stack Pay url:

stx1wajky2mnw3u8qcte8ghj76twwehkjcm98ahhqetjv96xjmmw845kuan0d93k2fnjv43kjurfv4h8g02n2qe9y4z9xarryv2wxer4zdjzgfd9yd62gar4y46p2sc9gd23xddrjkjgggu5k5jnye6x76m9dc74x4zcyesk6mm4de6r6vfsxqczver9wd3hy6tsw35k7m3a2pshjmt9de6zken0wg4hxetjwe5kxetnyejhsurfwfjhxst585erqv3595cnytfnx92ryve9xdqn2wf9xdqn2w26juk65n

And here is an example final encoded URL suitable for sharing as a link or QR Code.

web+stx:stx1wajky2mnw3u8qcte8ghj76twwehkjcm98ahhqetjv96xjmmw845kuan0d9...

Encoding and Decoding

Stacks Pay URLs MUST be encoded using Bech32m encoding with the human-readable part (HRP) set to 'stx' and a limit of 512. This ensures compatibility and data integrity, making it suitable for QR codes and platforms with URL limitations.

Variable Amounts and Donations

If the amount parameter is not specified (e.g., for donations), wallets MUST prompt the user to enter the desired amount before proceeding.
Applications SHOULD validate the entered amount to prevent errors or fraudulent transactions.

Security Considerations

Use of Post Conditions: Applications SHOULD use Post Conditions in all asset transfers to ensure that only the intended assets and amounts are transferred.
Data Validation: Wallets and applications MUST validate all parameters to prevent injection attacks or malformed data.
Token Handling: Applications MUST handle different token types appropriately, ensuring the correct token is used in the transaction.
Memo Field Privacy: Sensitive information MUST NOT be included in the memo field, as it is visible to the public.

Backwards Compatibility

Stacks Pay is a new specification and does not require changes to the core operation of the Stacks blockchain or protocol-level upgrades. Transactions submitted via Stacks Pay remain fully compatible with the Stacks blockchain. However, wallets and applications that do not implement Stacks Pay will not recognize or process Stacks Pay URLs or payment requests.

Implementation

Wallet Integration

Wallets that support Stacks Pay MUST implement the following:

URL Handling: Recognize and parse web+stx: Bech32m-encoded URLs.
Parameter Extraction: Extract payment parameters according to the specification.
Operation Handling: Support standard operation types and handle custom operations appropriately.
User Interface: Present a user interface that displays payment details and allows the user to confirm or cancel the payment.
Token Support: Handle payments in STX and SIP-010 fungible tokens, interacting with smart contracts as required.
Use of Post Conditions: Include appropriate Post Conditions in transactions involving asset transfers.
Error Handling: Provide informative error messages if the URL is invalid or if required parameters are missing.

Merchant Integration

Merchants and service providers can integrate Stacks Pay into their platforms by:

Generating Payment Requests: Creating Stacks Pay URLs with all required parameters.
Sharing Payment Requests: Displaying the Stacks Pay URL as a QR code or hyperlink.
Processing Payments: Monitoring incoming transactions and verifying payments.

Application Integration

Applications facilitating payments can incorporate Stacks Pay by:

Providing Payment Links: Generating Stacks Pay URLs for sharable transactions.
Guiding Payment Flows: Implementing payment flows that guide users through the payment process using Stacks Pay URLs.
Handling SIP-010 Tokens: Interacting with token smart contracts when handling SIP-010 tokens.

Reference Implementation

A reference implementation of the Stacks Pay standard is available to assist developers in integrating the specification into their applications. The implementations cover multiple programming languages to cater to different development environments.

Source Code

The reference implementations can be found at the following repositories:

TypeScript: stacks-pay-js
Python: stacks-pay-py
Rust: stacks-pay-rs

These repositories contain source code demonstrating how to generate and parse Stacks Pay URLs, handle Bech32m encoding, in accordance with the specification.

Ratification

This SIP is considered ratified after:

SIP Approval and Community Review: The SIP undergoes formal review and approval by the designated Stacks governance bodies and is discussed publicly to gather feedback.
Reference Implementation: At least one reference implementation of the Stacks Pay standard is developed and made publicly available.
Wallet Support: At least one widely-used Stacks wallet implements support for the Stacks Pay URL scheme.
Merchant Adoption: At least ten merchants or two service providers integrate Stacks Pay into their sales processes.
Documentation: Comprehensive documentation is provided, including integration guides and code examples.

Economics

While Stacks Pay is an application-level standard that does not require changes to the core operation of the Stacks blockchain or affect token emission, its adoption can have indirect economic impacts on the Stacks ecosystem. These potential economic considerations include:

Increased Transaction Volume: Simplifying payment requests may lead to more transactions, increasing total transaction fees collected by miners and enhancing network security.
Enhanced Token Utility: Improved payment mechanisms can increase the utility and demand for STX and SIP-010 tokens, which may affect their market value.
Ecosystem Growth: Standardizing payment requests can attract more merchants and users to the Stacks ecosystem, fostering economic growth.
Business Opportunities: Developers and businesses may find new opportunities to create services that utilize Stacks Pay, contributing to the overall health and diversity of the ecosystem.

StacksPay Specification

Preamble

Abstract

License and Copyright

Terminology

Introduction

Operations

support

invoice

mint

Custom Operations

Parameter Table (summary)

Token Types

URL Scheme

Encoding and Decoding

Variable Amounts and Donations

Security Considerations

Backwards Compatibility

Implementation

Wallet Integration

Merchant Integration

Application Integration

Reference Implementation

Source Code

Ratification

Economics

Links

Related Work

Additional Resources

`support`

`invoice`

`mint`