From a67e190572b339b7c9a966d53936b5fadc9649d2 Mon Sep 17 00:00:00 2001 From: Dan Trevino Date: Thu, 26 Sep 2024 10:10:32 -0500 Subject: [PATCH 1/7] add sip --- sips/sip-02x/sip-02x-stacks-pay.md | 196 +++++++++++++++++++++++++++++ 1 file changed, 196 insertions(+) create mode 100644 sips/sip-02x/sip-02x-stacks-pay.md diff --git a/sips/sip-02x/sip-02x-stacks-pay.md b/sips/sip-02x/sip-02x-stacks-pay.md new file mode 100644 index 000000000..fc850d964 --- /dev/null +++ b/sips/sip-02x/sip-02x-stacks-pay.md @@ -0,0 +1,196 @@ +## Preamble + +SIP Number: to be assigned + +Title: Stacks Pay: A Payment Request Standard for Stacks Blockchain Payments + +Author: [Dan Trevino @dantrevino] + +Consideration: Technical + +Type: Standard + +Status: Draft + +Created: 2024-09-24 + +License: CC0-1.0: Creative Commons CC0 1.0 Universal + +Sign-off: + +## Abstract + +This SIP proposes a payment request standard, **Stacks Pay**, for the Stacks blockchain. The standard aims to enable secure, efficient, and flexible payment interactions between payers and recipients by defining a unified method for creating 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. + +## License and Copyright +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/ This SIP’s copyright is held by the Stacks Open Internet Foundation. + +## Motivation + +As the Stacks ecosystem grows, there's an increasing demand for a standardized method to request and process payments. Currently, there is no unified standard for creating and handling payment requests on the Stacks blockchain, which leads to fragmentation and inconsistent user experiences. Existing payment request standards in other ecosystems offer features like reusable payment requests and enhanced security, but no such standard exists for Stacks. + +**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. + +## Specification + +### Overview + +Stacks Pay defines a standardized method for creating and processing payment requests on the Stacks blockchain using a URL scheme to encode necessary payment information. This allows wallets and applications to parse and handle payments consistently. + +### Payment Parameters + +A Stacks Pay payment request **MUST** include the following parameters: + +- **`recipient`**: The Stacks address of the payment recipient. +- **`token`**: The type of token used for payment. This **MUST** be either `'STX'` or `'SIP10'`. +- **`description`**: A description providing context for the payment. +- **`spId`**: A unique identifier for the payment request (Stacks Pay ID). + +Optional parameters: + +- **`amount`**: The amount to be paid, in micro-STX or token units. If not provided, the payer **MUST** enter the amount. +- **`contractAddress`**: The contract principal and contract name, separated by a '.'. This field is **REQUIRED** if `token` is `'SIP10'`. +- **`functionName`**: The contract function name (e.g., `transfer`, `mint`). This field is **REQUIRED** if `token` is `'SIP10'`. + +### 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. +- `'SIP10'`: For payments using SIP-010 compliant fungible tokens. + +### URL Scheme + +The Stacks Pay URL scheme **MUST** use the custom protocol `stxpay://`, followed by an `operation` and query parameters encoding the payment details. + +**Format:** + +``` +stxpay://?recipient=&token=&description=&spId=[&amount=][&contractAddress=][&functionName=] +``` + +- **`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. + +**Example:** + +``` +stxpay://pay?recipient=SP3FBR...&token=STX&description=Payment%20for%20Services&spId=3KMf8...&amount=1000 +``` + +### Operation Field + +The `operation` field **MUST** specify the type of action to be performed. Standard operation types include: + +- **`'pay'`**: Initiates a standard payment with specified parameters. +- **`'donate'`**: Allows the payer to specify the amount. +- **`'subscribe'`**: Initiates a subscription or recurring payment. +- **`'invoice'`**: Represents a payment request for an invoice. + +Wallets and applications **MUST** recognize and correctly process these standard operation types. + +### Encoding and Decoding + +Stacks Pay URLs **MUST** be encoded using **Bech32m encoding** with the human-readable part (HRP) set to `'stx'`. This ensures compatibility and data integrity, making it suitable for QR codes and platforms with URL limitations. + +### Including `spId` in the Memo Field + +To associate a transaction with its payment request, the `spId` **MUST** be included in the transaction's memo field. + +- **Generating `spId`**: The `spId` **MUST** be a unique identifier generated using a cryptographically secure random number generator and encoded efficiently (e.g., using Base58 encoding) to fit within the 34-byte memo field limit. +- **Including in Memo**: When constructing the transaction, the payer's wallet **MUST** include the `spId` in the memo field. The memo field **MUST NOT** exceed 34 bytes. + +### 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 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 publicly visible. + +## 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 `stxpay://` URLs, including 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. +- **Memo Field Inclusion**: Include the `spId` in the transaction's memo field. +- **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 and a unique `spId`. +- **Sharing Payment Requests**: Displaying the Stacks Pay URL as a QR code or hyperlink. +- **Processing Payments**: Monitoring incoming transactions, extracting `spId`s from memo fields, and verifying payments. + +### Application Integration + +Applications facilitating payments can incorporate Stacks Pay by: + +- **Providing Payment Links**: Generating Stacks Pay URLs for 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. +- **Ensuring Security**: Generating and storing `spId`s securely and complying with privacy regulations. + +## Ratification + +This SIP is considered ratified after: + +1. **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. +2. **Reference Implementation**: At least one reference implementation of the Stacks Pay standard is developed and made publicly available. +3. **Wallet Support**: At least one widely-used Stacks wallet implements support for the Stacks Pay URL scheme. +4. **Merchant Adoption**: At least ten merchants or two service providers integrate Stacks Pay into their platforms. +5. **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, potentially affecting 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 around Stacks Pay, contributing to the overall health and diversity of the ecosystem. + +## Links + +### Related Work + +- **SIP-010: Fungible Tokens**: Defines a standard interface for fungible tokens on the Stacks blockchain. + +- **Bitcoin Payment Protocol (BIP 21)**: A URI scheme for Bitcoin payments, inspiring the use of a custom URI scheme in Stacks Pay. + +- **Lightning Network Invoices (BOLT-11 and BOLT-12)**: Specify invoice formats for the Lightning Network, supporting features like reusable payment requests and enhanced security. Stacks Pay draws inspiration from these protocols in supporting variable amounts and reusable payment requests. + + - **BOLT-11**: Defines a standard for Lightning Network invoices, enabling off-chain transactions with detailed payment information. + + - **BOLT-12**: Introduces offers and invoices that enhance privacy and functionality over BOLT-11, allowing for more flexible payment requests. + +- **Ethereum EIP-681**: A standard for representing Ethereum payment requests as URIs, which influences the design of the Stacks Pay URL scheme. + +### Additional Resources + +- [RFC 2119 - Key words for use in RFCs to Indicate Requirement Levels](https://www.ietf.org/rfc/rfc2119.txt) + +- [Bech32m Specification](https://github.com/bitcoin/bips/blob/master/bip-0350.mediawiki) + +- [SIP-010: Fungible Tokens](https://github.com/blockstack/SIPs/blob/master/sips/sip-010/sip-010.md) + +- [BOLT-11 Specification](https://github.com/lightning/bolts/blob/master/11-payment-encoding.md) + +- [BOLT-12 Specification](https://github.com/lightning/bolts/blob/master/12-offer-encoding.md) From 8ca9162fd1eca09270a2cc86b9ed168d67335ce1 Mon Sep 17 00:00:00 2001 From: Dan Trevino Date: Sat, 28 Sep 2024 00:23:18 -0500 Subject: [PATCH 2/7] update per recommendations --- sips/sip-02x/sip-02x-stacks-pay.md | 40 +++++++++++++++++++++++++----- 1 file changed, 34 insertions(+), 6 deletions(-) diff --git a/sips/sip-02x/sip-02x-stacks-pay.md b/sips/sip-02x/sip-02x-stacks-pay.md index fc850d964..852629b0c 100644 --- a/sips/sip-02x/sip-02x-stacks-pay.md +++ b/sips/sip-02x/sip-02x-stacks-pay.md @@ -4,7 +4,7 @@ SIP Number: to be assigned Title: Stacks Pay: A Payment Request Standard for Stacks Blockchain Payments -Author: [Dan Trevino @dantrevino] +Author: Dan Trevino Consideration: Technical @@ -12,10 +12,14 @@ Type: Standard Status: Draft -Created: 2024-09-24 +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 @@ -25,9 +29,9 @@ This SIP proposes a payment request standard, **Stacks Pay**, for the Stacks blo ## License and Copyright 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/ This SIP’s copyright is held by the Stacks Open Internet Foundation. -## Motivation +## Introduction -As the Stacks ecosystem grows, there's an increasing demand for a standardized method to request and process payments. Currently, there is no unified standard for creating and handling payment requests on the Stacks blockchain, which leads to fragmentation and inconsistent user experiences. Existing payment request standards in other ecosystems offer features like reusable payment requests and enhanced security, but no such standard exists for Stacks. +As the Stacks ecosystem grows, there's an increasing demand for a standardized method to request and process payments. Currently, there is no unified standard for creating and handling payment requests on the Stacks blockchain, which will lead to fragmentation and inconsistent user experiences. Existing payment request standards in other ecosystems offer features like reusable payment requests and enhanced security, but no such standard exists for Stacks. **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. @@ -167,9 +171,33 @@ While Stacks Pay is an application-level standard that does not require changes - **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 around Stacks Pay, contributing to the overall health and diversity of the ecosystem. -## Links +## Activation + +This SIP is considered ratified after: + +1. 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. +1. Reference Implementation: At least one reference implementation of the Stacks Pay standard is developed and made publicly available. +1. Wallet Support: At least one widely-used Stacks wallet implements support for the Stacks Pay URL scheme. +1. Merchant Adoption: At least ten merchants or two service providers integrate Stacks Pay into their platforms. +1. Documentation: Comprehensive documentation is provided, including integration guides and code examples. + +## Reference Implementations + +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](https://github.com/dantrevino/stacks-pay-js) +- **Python**: [stacks-pay-py](https://github.com/dantrevino/stacks-pay-py) +- **Rust**: [stacks-pay-rs](https://github.com/dantrevino/stacks-pay-rs) + +These repositories contain source code demonstrating how to generate and parse Stacks Pay URLs, handle Bech32m encoding, generate `spId`s, and include them in transaction memo fields, in accordance with the specification. + + -### Related Work +## Related Work - **SIP-010: Fungible Tokens**: Defines a standard interface for fungible tokens on the Stacks blockchain. From cfcd542bbf04a0bd42f546abf6d03031ce903611 Mon Sep 17 00:00:00 2001 From: Dan Trevino Date: Sun, 1 Dec 2024 03:16:14 -0600 Subject: [PATCH 3/7] clarify purpose, clarify default functions for mint and transfer --- sips/sip-02x/sip-02x-stacks-pay.md | 302 +++++++++++++++++++++-------- 1 file changed, 220 insertions(+), 82 deletions(-) diff --git a/sips/sip-02x/sip-02x-stacks-pay.md b/sips/sip-02x/sip-02x-stacks-pay.md index 852629b0c..52641b34d 100644 --- a/sips/sip-02x/sip-02x-stacks-pay.md +++ b/sips/sip-02x/sip-02x-stacks-pay.md @@ -20,103 +20,230 @@ License: CC0-1.0: Creative Commons CC0 1.0 Universal Discussion-To: https://github.com/stacksgov/sips -Sign-off: +Sign-off: ## Abstract -This SIP proposes a payment request standard, **Stacks Pay**, for the Stacks blockchain. The standard aims to enable secure, efficient, and flexible payment interactions between payers and recipients by defining a unified method for creating 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. +**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. -## License and Copyright -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/ This SIP’s copyright is held by the Stacks Open Internet Foundation. +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/](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 -As the Stacks ecosystem grows, there's an increasing demand for a standardized method to request and process payments. Currently, there is no unified standard for creating and handling payment requests on the Stacks blockchain, which will lead to fragmentation and inconsistent user experiences. Existing payment request standards in other ecosystems offer features like reusable payment requests and enhanced security, but no such standard exists for Stacks. +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. -## Specification +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', 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. -### Overview +**Parameters to Ignore:** -Stacks Pay defines a standardized method for creating and processing payment requests on the Stacks blockchain using a URL scheme to encode necessary payment information. This allows wallets and applications to parse and handle payments consistently. +contractName, functionName: Wallets MUST ignore these parameters if present. -### Payment Parameters +### `mint` -A Stacks Pay payment request **MUST** include the following parameters: +**Function:** Represents a non-fungible token minting request. -- **`recipient`**: The Stacks address of the payment recipient. -- **`token`**: The type of token used for payment. This **MUST** be either `'STX'` or `'SIP10'`. -- **`description`**: A description providing context for the payment. -- **`spId`**: A unique identifier for the payment request (Stacks Pay ID). +**Required Parameters:** -Optional parameters: +- operation: 'mint' -- **`amount`**: The amount to be paid, in micro-STX or token units. If not provided, the payer **MUST** enter the amount. -- **`contractAddress`**: The contract principal and contract name, separated by a '.'. This field is **REQUIRED** if `token` is `'SIP10'`. -- **`functionName`**: The contract function name (e.g., `transfer`, `mint`). This field is **REQUIRED** if `token` is `'SIP10'`. +- 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 + +- 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) + +| Opertation | 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 - optional +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. -- `'SIP10'`: For payments using SIP-010 compliant fungible tokens. +- '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 `stxpay://`, followed by an `operation` and query parameters encoding the payment details. +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: + ``` -stxpay://?recipient=&token=&description=&spId=[&amount=][&contractAddress=][&functionName=] + +?recipient=&token=&amount=[&additional_params] + ``` -- **`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. +For example, here is the unencoded url using 'STX' token: -**Example:** +``` + +invoice?recipient=SP3FBR...&token=STX&amount=1000&description=Payment%20for%20Services ``` -stxpay://pay?recipient=SP3FBR...&token=STX&description=Payment%20for%20Services&spId=3KMf8...&amount=1000 + +And here is an example using the SIP-010 Nothing Token: + ``` -### Operation Field +invoice?operation=invoice&recipient=SP3FBR...&token=SP32AEEF6WW5Y0NMJ1S8SBSZDAY8R5J32NBZFPKKZ.nope&amount=1000&description=Payment+for+services -The `operation` field **MUST** specify the type of action to be performed. Standard operation types include: +``` -- **`'pay'`**: Initiates a standard payment with specified parameters. -- **`'donate'`**: Allows the payer to specify the amount. -- **`'subscribe'`**: Initiates a subscription or recurring payment. -- **`'invoice'`**: Represents a payment request for an invoice. +- **`operation`**: Specifies the type of action or transaction. It **MUST** be included and be a string value. -Wallets and applications **MUST** recognize and correctly process these standard operation types. +- **Query Parameters**: The payment parameters are appended as URL-encoded query parameters. See specific operation types for which are included for which operations. -### Encoding and Decoding +Example encoded Stack Pay url: + +``` + +stx1wajky2mnw3u8qcte8ghj76twwehkjcm98ahhqetjv96xjmmw845kuan0d93k2fnjv43kjurfv4h8g02n2qe9y4z9xarryv2wxer4zdjzgfd9yd62gar4y46p2sc9gd23xddrjkjgggu5k5jnye6x76m9dc74x4zcyesk6mm4de6r6vfsxqczver9wd3hy6tsw35k7m3a2pshjmt9de6zken0wg4hxetjwe5kxetnyejhsurfwfjhxst585erqv3595cnytfnx92ryve9xdqn2wf9xdqn2w26juk65n + +``` + +And here is an example final encoded URL suitable for sharing as a link or QR Code. + +``` -Stacks Pay URLs **MUST** be encoded using **Bech32m encoding** with the human-readable part (HRP) set to `'stx'`. This ensures compatibility and data integrity, making it suitable for QR codes and platforms with URL limitations. +web+stx:stx1wajky2mnw3u8qcte8ghj76twwehkjcm98ahhqetjv96xjmmw845kuan0d9... -### Including `spId` in the Memo Field +``` -To associate a transaction with its payment request, the `spId` **MUST** be included in the transaction's memo field. +### Encoding and Decoding -- **Generating `spId`**: The `spId` **MUST** be a unique identifier generated using a cryptographically secure random number generator and encoded efficiently (e.g., using Base58 encoding) to fit within the 34-byte memo field limit. -- **Including in Memo**: When constructing the transaction, the payer's wallet **MUST** include the `spId` in the memo field. The memo field **MUST NOT** exceed 34 bytes. +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 asset transfers to ensure that only the intended assets and amounts are transferred. +- **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 publicly visible. -## Backwards Compatibility +- **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. @@ -126,88 +253,97 @@ Stacks Pay is a new specification and does not require changes to the core opera Wallets that support Stacks Pay **MUST** implement the following: -- **URL Handling**: Recognize and parse `stxpay://` URLs, including Bech32m-encoded URLs. +- **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. -- **Memo Field Inclusion**: Include the `spId` in the transaction's memo field. + - **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 and a unique `spId`. +- **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, extracting `spId`s from memo fields, and verifying payments. + +- **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 transactions. +- **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. -- **Ensuring Security**: Generating and storing `spId`s securely and complying with privacy regulations. -## Ratification +## Reference Implementation -This SIP is considered ratified after: +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. -1. **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. -2. **Reference Implementation**: At least one reference implementation of the Stacks Pay standard is developed and made publicly available. -3. **Wallet Support**: At least one widely-used Stacks wallet implements support for the Stacks Pay URL scheme. -4. **Merchant Adoption**: At least ten merchants or two service providers integrate Stacks Pay into their platforms. -5. **Documentation**: Comprehensive documentation is provided, including integration guides and code examples. +### Source Code -## Economics +The reference implementations can be found at the following repositories: -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: +- **TypeScript**: [stacks-pay-js](https://github.com/dantrevino/stacks-pay-js) -- **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, potentially affecting 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 around Stacks Pay, contributing to the overall health and diversity of the ecosystem. +- **Python**: [stacks-pay-py](https://github.com/dantrevino/stacks-pay-py) -## Activation +- **Rust**: [stacks-pay-rs](https://github.com/dantrevino/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: -1. 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. -1. Reference Implementation: At least one reference implementation of the Stacks Pay standard is developed and made publicly available. -1. Wallet Support: At least one widely-used Stacks wallet implements support for the Stacks Pay URL scheme. -1. Merchant Adoption: At least ten merchants or two service providers integrate Stacks Pay into their platforms. -1. Documentation: Comprehensive documentation is provided, including integration guides and code examples. +1. **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 Implementations +2. **Reference Implementation**: At least one reference implementation of the Stacks Pay standard is developed and made publicly available. -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. +3. **Wallet Support**: At least one widely-used Stacks wallet implements support for the Stacks Pay URL scheme. -### Source Code +4. **Merchant Adoption**: At least ten merchants or two service providers integrate Stacks Pay into their sales processes. -The reference implementations can be found at the following repositories: +5. **Documentation**: Comprehensive documentation is provided, including integration guides and code examples. -- **TypeScript**: [stacks-pay-js](https://github.com/dantrevino/stacks-pay-js) -- **Python**: [stacks-pay-py](https://github.com/dantrevino/stacks-pay-py) -- **Rust**: [stacks-pay-rs](https://github.com/dantrevino/stacks-pay-rs) +## Economics -These repositories contain source code demonstrating how to generate and parse Stacks Pay URLs, handle Bech32m encoding, generate `spId`s, and include them in transaction memo fields, in accordance with the specification. +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. -## Related Work +- **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. -- **SIP-010: Fungible Tokens**: Defines a standard interface for fungible tokens on the Stacks blockchain. +## Links + +### Related Work + +- **SIP-009: Non-fungible Tokens**: Defines the standard for non-fungible tokens on the Stacks blockchain. + +- **SIP-010: Fungible Tokens**: Defines the standard for fungible tokens on the Stacks blockchain. - **Bitcoin Payment Protocol (BIP 21)**: A URI scheme for Bitcoin payments, inspiring the use of a custom URI scheme in Stacks Pay. - **Lightning Network Invoices (BOLT-11 and BOLT-12)**: Specify invoice formats for the Lightning Network, supporting features like reusable payment requests and enhanced security. Stacks Pay draws inspiration from these protocols in supporting variable amounts and reusable payment requests. - - **BOLT-11**: Defines a standard for Lightning Network invoices, enabling off-chain transactions with detailed payment information. - - - **BOLT-12**: Introduces offers and invoices that enhance privacy and functionality over BOLT-11, allowing for more flexible payment requests. +- **BOLT-11**: Defines a standard for Lightning Network invoices, enabling off-chain transactions with detailed payment information. + +- **BOLT-12**: Introduces offers and invoices that enhance privacy and functionality over BOLT-11, allowing for more flexible payment requests. - **Ethereum EIP-681**: A standard for representing Ethereum payment requests as URIs, which influences the design of the Stacks Pay URL scheme. @@ -215,9 +351,11 @@ These repositories contain source code demonstrating how to generate and parse S - [RFC 2119 - Key words for use in RFCs to Indicate Requirement Levels](https://www.ietf.org/rfc/rfc2119.txt) -- [Bech32m Specification](https://github.com/bitcoin/bips/blob/master/bip-0350.mediawiki) +- [SIP-009 Specification](https://github.com/stacksgov/sips/blob/main/sips/sip-009/sip-009-nft-standard.md) + +- [SIP-010 Specification](https://github.com/stacksgov/sips/blob/main/sips/sip-010/sip-010-fungible-token-standard.md) -- [SIP-010: Fungible Tokens](https://github.com/blockstack/SIPs/blob/master/sips/sip-010/sip-010.md) +- [Bech32m Specification](https://github.com/bitcoin/bips/blob/master/bip-0350.mediawiki) - [BOLT-11 Specification](https://github.com/lightning/bolts/blob/master/11-payment-encoding.md) From fa5f8ba365c65945f6486cc7721458119f03edd1 Mon Sep 17 00:00:00 2001 From: Dan Trevino Date: Sun, 1 Dec 2024 03:29:55 -0600 Subject: [PATCH 4/7] clarify transfer default, code layout --- sips/sip-02x/sip-02x-stacks-pay.md | 49 +++++++++--------------------- 1 file changed, 15 insertions(+), 34 deletions(-) diff --git a/sips/sip-02x/sip-02x-stacks-pay.md b/sips/sip-02x/sip-02x-stacks-pay.md index 52641b34d..ae6244d9a 100644 --- a/sips/sip-02x/sip-02x-stacks-pay.md +++ b/sips/sip-02x/sip-02x-stacks-pay.md @@ -57,7 +57,8 @@ Stacks Pay defines several standard operations that specify the type of payment - operation: 'support' - recipient: A valid Stacks address. -- if the `token` parameter is not 'STX', functionName defaults to 'transfer' by the wallet. + +- If the token parameter is not 'STX', the functionName defaults to 'transfer' by the wallet. **Optional Parameters:** @@ -127,7 +128,7 @@ contractName, functionName: Wallets MUST ignore these parameters if present. - expiresAt: MAY be included. If included wallets MUST NOT process links after the expiry date/time. -- invoiceNumber +- invoiceNumber: MAY be included by the link creator to track individual requests. - memo: MAY be included. MUST NOT include personal information. @@ -149,16 +150,16 @@ Applications **MAY** define custom operations for specific use cases. Custom ope ### Parameter Table (summary) -| Opertation | 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\* | +| 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 - optional +O - optionalas determined I - ignored O* - custom links are defined on a per application basis ``` @@ -181,27 +182,15 @@ The Stacks Pay URL scheme **MUST** use the custom protocol `web+stx:`, followed Format of the url string prior to encoding: -``` - -?recipient=&token=&amount=[&additional_params] - -``` +`?recipient=&token=&amount=[&additional_params]` For example, here is the unencoded url using 'STX' token: -``` - -invoice?recipient=SP3FBR...&token=STX&amount=1000&description=Payment%20for%20Services - -``` +`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 - -``` +`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. @@ -209,19 +198,11 @@ invoice?operation=invoice&recipient=SP3FBR...&token=SP32AEEF6WW5Y0NMJ1S8SBSZDAY8 Example encoded Stack Pay url: -``` - -stx1wajky2mnw3u8qcte8ghj76twwehkjcm98ahhqetjv96xjmmw845kuan0d93k2fnjv43kjurfv4h8g02n2qe9y4z9xarryv2wxer4zdjzgfd9yd62gar4y46p2sc9gd23xddrjkjgggu5k5jnye6x76m9dc74x4zcyesk6mm4de6r6vfsxqczver9wd3hy6tsw35k7m3a2pshjmt9de6zken0wg4hxetjwe5kxetnyejhsurfwfjhxst585erqv3595cnytfnx92ryve9xdqn2wf9xdqn2w26juk65n - -``` +`stx1wajky2mnw3u8qcte8ghj76twwehkjcm98ahhqetjv96xjmmw845kuan0d93k2fnjv43kjurfv4h8g02n2qe9y4z9xarryv2wxer4zdjzgfd9yd62gar4y46p2sc9gd23xddrjkjgggu5k5jnye6x76m9dc74x4zcyesk6mm4de6r6vfsxqczver9wd3hy6tsw35k7m3a2pshjmt9de6zken0wg4hxetjwe5kxetnyejhsurfwfjhxst585erqv3595cnytfnx92ryve9xdqn2wf9xdqn2w26juk65n` And here is an example final encoded URL suitable for sharing as a link or QR Code. -``` - -web+stx:stx1wajky2mnw3u8qcte8ghj76twwehkjcm98ahhqetjv96xjmmw845kuan0d9... - -``` +`web+stx:stx1wajky2mnw3u8qcte8ghj76twwehkjcm98ahhqetjv96xjmmw845kuan0d9...` ### Encoding and Decoding From dfb954c09a58ea9f6337690376f20791b17e1980 Mon Sep 17 00:00:00 2001 From: Dan Trevino Date: Sun, 8 Jun 2025 02:52:26 -0500 Subject: [PATCH 5/7] resolve comments, clarify encoding process, add appendix --- sips/sip-02x/sip-02x-stacks-pay.md | 448 ++++++++++++++--------------- 1 file changed, 209 insertions(+), 239 deletions(-) diff --git a/sips/sip-02x/sip-02x-stacks-pay.md b/sips/sip-02x/sip-02x-stacks-pay.md index ae6244d9a..b06c9ef53 100644 --- a/sips/sip-02x/sip-02x-stacks-pay.md +++ b/sips/sip-02x/sip-02x-stacks-pay.md @@ -1,343 +1,313 @@ -## Preamble +# Preamble -SIP Number: to be assigned +SIP Number: 029 +Title: Stacks Pay – A Payment-Request Standard for the Stacks Blockchain +Author: [Dan Trevino @dantrevino](mailto:dantrevino@gmail.com) +Type: Standard +Status: Draft +Created: 24 September 2024 +License: CC0-1.0 +Layer: Application +Discussion-To: -Title: Stacks Pay: A Payment Request Standard for Stacks Blockchain Payments - -Author: Dan Trevino - -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/](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 a URL-based payment-request format for the Stacks blockchain. +By standardising how payment information is encoded, decoded, and displayed, it +guarantees that any wallet or application implementing this specification can +interoperate with any other. -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. +Stacks Pay is *purely* an application-layer standard: it introduces **no** changes +to consensus, token emission, or on-chain data structures. +Think of it as a shareable wrapper around an ordinary Stacks +transaction. -### `support` +> **RFC 2119 terminology** +> The key words **MUST**, **MUST NOT**, **REQUIRED**, **SHALL**, **SHALL NOT**, +> **SHOULD**, **SHOULD NOT**, **RECOMMENDED**, **MAY**, and **OPTIONAL** in this +> document are to be interpreted as described in [RFC 2119]. -**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:** +## 1 Introduction -- operation: 'support' +Payment URIs already exist in Bitcoin (BIP-21), Lightning (BOLT-11/12) and +Ethereum (EIP-681). Stacks lacks a comparable, wallet-agnostic standard. Without one, merchants, +DApps, and wallets invent ad-hoc query strings that break as soon as a new field +appears. -- recipient: A valid Stacks address. +Stacks Pay solves this by: -- If the token parameter is not 'STX', the functionName defaults to 'transfer' by the wallet. +* using a **single URI scheme** (`web+stx://`) with Bech32m payloads; +* defining a **small set of operations** (`support`, `invoice`, `mint`); +* listing, for every operation, the **exact parameters that wallets honour**; +* requiring wallets to **ignore everything else**, giving future versions room + to evolve without breaking existing software. -**Optional Parameters:** +--- -- token: Either 'STX' or a valid SIP-010 contract address. If not provided, defaults to 'STX'. +## 2 Common Parameter Types -- description: MAY be included to provide additional context for the payment request. +| Name | Type / Format | Description | +|------|---------------|-------------| +| `recipient` | Stacks c32-address | Address that ultimately receives the payment. | +| `token` | **STX** \| SIP-010 contract address (`SP….`) | Asset used to pay. When omitted wallets **MUST** default to **STX**. | +| `amount` | integer (string) | Amount in µSTX or in the smallest SIP-010 units. | +| `description` | UTF-8 string | Human-readable context shown to the payer. | +| `expiresAt` | ISO-8601 datetime (UTC) | After this moment wallets **MUST NOT** let the user broadcast. | +| `invoiceNumber` | free-form string | Merchant-supplied reference. | +| `dueDate` | ISO-8601 date | Informational; wallets **MAY** surface it. | +| `contractAddress` | `SP….` | SIP-009/-010 contract principal + name. | +| `functionName` | identifier | Clarity function to invoke in `contractAddress`. | -- expiresAt: MAY be included; wallets MUST NOT process payment requests past the expiry time. +**Unknown parameters** – Any query key not listed as *Required* or *Optional* +for the selected `operation` **SHOULD** be ignored. Implementations **MAY** +log or warn, but **MUST NOT** fail. -- memo: MAY be included; MUST NOT include personal information. +--- -**Parameters to Ignore:** +## 3 Operations -- amount, contractName, dueDate, functionName, invoiceNumber. Wallets MUST ignore these parameters if present. +> All examples use the canonical scheme +> `web+stxpay://?` before Bech32m encoding. -### `invoice` +### 3.1 `support` -**Function:** Represents a payment request, such as an invoice for P2P payments or product purchases. +Description of support operation here -**Required Parameters:** +| Category | Parameters | +|----------|------------| +| **Required** | `operation='support'`, `recipient` | +| **Optional** | `token`, `description`, `expiresAt`,`memo` | -- operation: 'invoice' +*Wallet behaviour* -- recipient: A valid Stacks address. +* Wallet **MUST** prompt the payer for the `amount`. +* Wallet **MAY** let the payer override the suggested `token`. -- token: MUST be either 'STX' or a valid SIP-010 contract address. +--- -- amount: The amount to be paid. +### 3.2 `invoice` -**Optional Parameters:** +Description of invoice operation here -- description: MAY be included to provide context for the payment request. +| Category | Parameters | +|----------|------------| +| **Required** | `operation='invoice'`, `recipient`, `token`, `amount` | +| **Optional** | `description`, `expiresAt`, `invoiceNumber`, `dueDate`, `memo` | -- expiresAt: MAY be included; if included, wallets MUST NOT process payment requests past the expiry time. +*Wallet behaviour* -- invoiceNumber: MAY be included as an identifier. +* Wallet **MUST** pre-fill `amount` and **MUST NOT** allow changes unless the + payer explicitly edits it. +* If `expiresAt` is present and in the past the wallet **MUST** refuse to + broadcast. -- dueDate: MAY be included. +--- -- memo: MAY be included. MUST NOT include personal information. +### 3.3 `mint` -**Parameters to Ignore:** +Description of mint operation here. -contractName, functionName: Wallets MUST ignore these parameters if present. +| Category | Parameters | +|----------|------------| +| **Required** | `operation='mint'`, `contractAddress`, `functionName='claim'`, `amount`, `token` | +| **Optional** | `description`, `expiresAt` `memo` | -### `mint` +*Wallet behaviour* -**Function:** Represents a non-fungible token minting request. +* The active wallet address is used as the receiver. +* `amount` **MAY** represent a mint-price; if zero or absent the wallet builds a + zero-STX transaction. +* The wallet **MUST** call `contractAddress.functionName` with any additional + Clarity arguments encoded in the payload (future extension). -**Required Parameters:** +--- -- operation: 'mint' +### 3.4 Custom Operations -- contractName: A valid SIP-009 contract address. +Applications **MAY** register vendor-specific operations using the prefix +`custom:` (e.g. `custom:subscription`). +Wallets that do not recognise the tag **SHOULD** show a warning and **MAY** +refuse to continue. -- functionName: A public contract function, typically `mint` or `claim` +--- -- token: MUST be either 'STX' or a valid SIP-010 contract name. +## URL Scheme & Encoding -- amount: The amount to be paid. +### Data Format +StacksPay uses a structured query string format that is then Bech32m encoded to ensure data integrity and compatibility across platforms. -**Optional Parameters:** +### Encoding Process -- recipient: MAY be included; if present, MUST be a valid Stacks address. The NFT will be minted for the specified address. +1. **Query String Assembly**: Parameters are assembled as URL query parameters according to operation-specific requirements: `?=&=...` -- description: MAY be included to provide context for the payment request +Example: `invoice?recipient=SP2RTE7F21N6GQ6BBZR7JGGRWAT0T5Q3Z9ZHB9KRS&token=STX&amount=1000` -- expiresAt: MAY be included. If included wallets MUST NOT process links after the expiry date/time. +2. **Bech32m Encoding**: The complete query string is encoded using Bech32m with: +- Human-readable part (HRP): `stxpay` +- Encoding limit: 512 +- Result: `stxpay1wajky2mnw3u8qcte8ghj76twwehkjcm98ahhq...` -- invoiceNumber: MAY be included by the link creator to track individual requests. +3. **Protocol Prefix**: Add the protocol scheme to create the final shareable URL: `web+stx:stxpay1wajky2mnw3u8qcte8ghj76twwehkjcm98ahhq...` -- memo: MAY be included. MUST NOT include personal information. +### Decoding Process -**Parameters to Ignore:** +1. **Protocol Validation**: Verify the URL starts with `web+stx:` +2. **Extract Encoded Data**: Remove the `web+stx:` prefix +3. **Bech32m Decoding**: Decode using expected HRP `stxpay` +4. **Parameter Parsing**: Parse the resulting query string to extract operation and parameters -- contractName, functionName, dueDate: Wallets MUST ignore these parameters if present. +### Encoding Requirements -### Custom Operations +Implementations MUST: +- Use Bech32m encoding with human-readable part (HRP) set to `stxpay` +- Validate checksums during decoding +- Support both uppercase and lowercase encoded strings +- Reject URLs with invalid Bech32m encoding +- Reject URLs with incorrect HRP +- Validate all required parameters for the specified operation -Applications **MAY** define custom operations for specific use cases. Custom operation types **MUST** be prefixed to prevent naming conflicts (e.g., `'custom-example'`). +Implementations SHOULD: +- Use uppercase for QR code generation for better scanning reliability +- Use lowercase for text-based sharing +- Provide meaningful error messages for common mistakes -- **Handling Unrecognized Operations**: If a wallet encounters an unrecognized operation type, it **SHOULD**: +Implementations MAY: +- Support visual formatting (spaces/line breaks) in long encoded strings for readability +- Provide error correction suggestions for malformed URLs -- **Warn the User**: Inform the user that the operation type is unrecognized. +### Error Handling -- **Provide Safe Defaults**: Default to a standard payment flow if possible. - -- **Fail Gracefully**: Prevent unexpected behavior or security risks. +Decoders MUST handle the following error cases: +- Invalid protocol prefix +- Malformed Bech32m encoding +- Incorrect HRP +- Missing required parameters +- Invalid parameter values -### Parameter Table (summary) +### Examples -| 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\* | +**Invoice Operation:** ``` -R - required -O - optionalas determined -I - ignored -O* - custom links are defined on a per application basis +Original: invoice?recipient=SP2RTE7F21N6GQ6BBZR7JGGRWAT0T5Q3Z9ZHB9KRS&token=STX&amount=1000 +Encoded: stxpay1qpzry9x8gf2tvdw0s3jn54khce6mua7lmqqqxw4tcy8w6tpdf5qq5g5tnyv9xx6myvf5hgurjd4hhq... +Final URL: web+stx:stxpay1qpzry9x8gf2tvdw0s3jn54khce6mua7lmqqqxw4tcy8w6tpdf5qq5g5tnyv9xx6myvf5hgurjd4hhq... ``` -### 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: - -`?recipient=&token=&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. +**Support Operation:** -- **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. +``` +Original: support?recipient=SP2RTE7F21N6GQ6BBZR7JGGRWAT0T5Q3Z9ZHB9KRS&description=Tip%20for%20great%20content +Encoded: stxpay1qpzgk5q8getf3ts3jn54khce6mua7lmqqqxw4tcy8w6tpdf5qq6x2cvn4dahx2mrvd9xycr6ve5... +Final URL: web+stx:stxpay1qpzgk5q8getf3ts3jn54khce6mua7lmqqqxw4tcy8w6tpdf5qq6x2cvn4dahx2mrvd9xycr6ve5... +``` -### Application Integration -Applications facilitating payments can incorporate Stacks Pay by: +### Custom Operations -- **Providing Payment Links**: Generating Stacks Pay URLs for sharable transactions. +Applications **MAY** define custom operations for specific use cases. -- **Guiding Payment Flows**: Implementing payment flows that guide users through the payment process using Stacks Pay URLs. +Custom operation types **MUST** be prefixed to prevent naming conflicts (e.g., `'custom-example'`). -- **Handling SIP-010 Tokens**: Interacting with token smart contracts when handling SIP-010 tokens. +**Handling Unrecognized Operations**: If a wallet encounters an unrecognized operation type, it **SHOULD**: -## Reference Implementation +- **Warn the User**: Inform the user that the operation type is unrecognized. -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. +- **Provide Safe Defaults**: Default to a standard payment flow if possible. -### Source Code +- **Fail Gracefully**: Prevent unexpected behavior or security risks. +--- -The reference implementations can be found at the following repositories: +## 5 Security Considerations -- **TypeScript**: [stacks-pay-js](https://github.com/dantrevino/stacks-pay-js) +* **Post-conditions** – Wallets **SHOULD** add appropriate post-conditions +limiting the transferred asset/amount. +* **Parameter validation** – All fields **MUST** be type-checked and length-checked. +* **Memo privacy** – Memos are on-chain; wallets **MUST NOT** write sensitive data. -- **Python**: [stacks-pay-py](https://github.com/dantrevino/stacks-pay-py) +--- -- **Rust**: [stacks-pay-rs](https://github.com/dantrevino/stacks-pay-rs) +## 6 Implementation Guidance -These repositories contain source code demonstrating how to generate and parse Stacks Pay URLs, handle Bech32m encoding, in accordance with the specification. +### 6.1 Wallets **MUST** -## Ratification +* Handle `web+stxpay:` links (and QR codes) end-to-end. +* Enforce `expiresAt` if present. +* Default missing `token` to **STX**. +* Ignore unknown parameters. -This SIP is considered ratified after: +### 6.2 Merchants **SHOULD** -1. **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. +* Generate URIs server-side or via libraries listed below. +* Display them as QR codes or clickable links. +* Regenerate a fresh `expiresAt` for time-sensitive invoices. -2. **Reference Implementation**: At least one reference implementation of the Stacks Pay standard is developed and made publicly available. +### 6.3 Reference Implementations -3. **Wallet Support**: At least one widely-used Stacks wallet implements support for the Stacks Pay URL scheme. +| Language | Repository | +|----------|------------| +| TypeScript | | +| Python | | +| Rust | | -4. **Merchant Adoption**: At least ten merchants or two service providers integrate Stacks Pay into their sales processes. +Each library demonstrates URI construction, Bech32m encoding/decoding, and +basic validation. -5. **Documentation**: Comprehensive documentation is provided, including integration guides and code examples. +--- -## Economics +## 7 Ratification Criteria -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: +1. SIP 029 accepted by governance. +2. At least one reference implementation passes test-vectors. +3. A major wallet releases Stacks Pay support. +4. Ten independent merchants (or two payment-service providers) adopt it. -- **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. +## 8 Economics -- **Ecosystem Growth**: Standardizing payment requests can attract more merchants and users to the Stacks ecosystem, fostering economic growth. +Stacks Pay does not alter consensus rules or tokenomics; however, easier +payments **SHOULD** increase transaction throughput, miner fees, and the +utility of STX and SIP-010 assets. -- **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. +--- -## Links +## 9 Related Work -### Related Work +* SIP-010 Fungible Tokens +* BIP-21 (URI scheme) +* BOLT-11 / BOLT-12 (Lightning invoices) +* EIP-681 (Ethereum payment URIs) -- **SIP-009: Non-fungible Tokens**: Defines the standard for non-fungible tokens on the Stacks blockchain. +--- -- **SIP-010: Fungible Tokens**: Defines the standard for fungible tokens on the Stacks blockchain. +### References -- **Bitcoin Payment Protocol (BIP 21)**: A URI scheme for Bitcoin payments, inspiring the use of a custom URI scheme in Stacks Pay. +* RFC 2119 – Key words for use in RFCs to Indicate Requirement Levels +* Bech32m – BIP-350 specification +* SIP-009 – Non-Fungible Token Standard (for `mint` contract references) -- **Lightning Network Invoices (BOLT-11 and BOLT-12)**: Specify invoice formats for the Lightning Network, supporting features like reusable payment requests and enhanced security. Stacks Pay draws inspiration from these protocols in supporting variable amounts and reusable payment requests. +## FAQ -- **BOLT-11**: Defines a standard for Lightning Network invoices, enabling off-chain transactions with detailed payment information. +### Why change the protocol scheme and encoding human readable part? -- **BOLT-12**: Introduces offers and invoices that enhance privacy and functionality over BOLT-11, allowing for more flexible payment requests. +The original SIP specified used `web+stxpay` as the protocol scheme and `stx` as the human readable part of the encoding. While this seemed reasonable to me, we have the opportunity to make the user experience potentially better if future Stacks protocols are defined to be used along with the web2 world. -- **Ethereum EIP-681**: A standard for representing Ethereum payment requests as URIs, which influences the design of the Stacks Pay URL scheme. +`web+stx` as the protocol scheme sets the stage for future Stacks protocols that serve different needs, but could each be easily identified as 'Stacks' protocols by the use of a common scheme. When writing out the un-encoded uri, `stxpay` indicates that this is a StacksPay uri. And together, they make the protocol uri, and hopefully future protocols more easily identifiable. -### Additional Resources +examples: -- [RFC 2119 - Key words for use in RFCs to Indicate Requirement Levels](https://www.ietf.org/rfc/rfc2119.txt) +`web+stx:stxpay.....` <- Oh look! A StacksPay uri -- [SIP-009 Specification](https://github.com/stacksgov/sips/blob/main/sips/sip-009/sip-009-nft-standard.md) +`web+stx:stxfoo....` <- Oh look! A StacksFoo uri -- [SIP-010 Specification](https://github.com/stacksgov/sips/blob/main/sips/sip-010/sip-010-fungible-token-standard.md) +`web+stx:stxbar....` <- Oh look! A StacksBar uri -- [Bech32m Specification](https://github.com/bitcoin/bips/blob/master/bip-0350.mediawiki) +### Why a 'mint' operation? -- [BOLT-11 Specification](https://github.com/lightning/bolts/blob/master/11-payment-encoding.md) +In the interest of starting with low hanging fruit and providing utility to the most users, an NFT mint function seems the obvious choice. And while, as @leopradel pointed out, there is no 'mint' function defined in SIP-009 (nft-mint is a clarity function), the reality is that Gamma's (https://gamma.io)[https://gamma.io] smart contracts are the defacto standard here. Following their lead and implementing a simple, structured 'mint' operation that calls Gamma's nft 'claim' function allows us to specify a controllable, easy-to-use, and useful smart contract payment function while limiting the attack surface area that general smart contract calls would open up. User education is still required here as malicious apps can always leverage fake contracts to steal from users, or even large DEXes. -- [BOLT-12 Specification](https://github.com/lightning/bolts/blob/master/12-offer-encoding.md) From d5d7991c0f23e30c90c6e5acc0619686aeec195d Mon Sep 17 00:00:00 2001 From: Dan Trevino Date: Sun, 8 Jun 2025 02:56:22 -0500 Subject: [PATCH 6/7] learned how to do md urls --- sips/sip-02x/sip-02x-stacks-pay.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/sips/sip-02x/sip-02x-stacks-pay.md b/sips/sip-02x/sip-02x-stacks-pay.md index b06c9ef53..be3468666 100644 --- a/sips/sip-02x/sip-02x-stacks-pay.md +++ b/sips/sip-02x/sip-02x-stacks-pay.md @@ -309,5 +309,5 @@ examples: ### Why a 'mint' operation? -In the interest of starting with low hanging fruit and providing utility to the most users, an NFT mint function seems the obvious choice. And while, as @leopradel pointed out, there is no 'mint' function defined in SIP-009 (nft-mint is a clarity function), the reality is that Gamma's (https://gamma.io)[https://gamma.io] smart contracts are the defacto standard here. Following their lead and implementing a simple, structured 'mint' operation that calls Gamma's nft 'claim' function allows us to specify a controllable, easy-to-use, and useful smart contract payment function while limiting the attack surface area that general smart contract calls would open up. User education is still required here as malicious apps can always leverage fake contracts to steal from users, or even large DEXes. +In the interest of starting with low hanging fruit and providing utility to the most users, an NFT mint function seems the obvious choice. And while, as @leopradel pointed out, there is no 'mint' function defined in SIP-009 (nft-mint is a clarity function), the reality is that Gamma's \([https://gamma.io](https://gamma.io)\) smart contracts are the defacto standard here. Following their lead and implementing a simple, structured 'mint' operation that calls Gamma's nft 'claim' function allows us to specify a controllable, easy-to-use, and useful smart contract payment function while limiting the attack surface area that general smart contract calls would open up. User education is still required here as malicious apps can always leverage fake contracts to steal from users, or even large DEXes. From 915ccf0a35f9eb6264bcdc6aed0a6a0e0283d9d1 Mon Sep 17 00:00:00 2001 From: Dan Trevino Date: Sun, 8 Jun 2025 03:32:42 -0500 Subject: [PATCH 7/7] Added token and amount specification and minor cleanup --- sips/sip-02x/sip-02x-stacks-pay.md | 169 ++++++++++++++++++++++++++++- 1 file changed, 166 insertions(+), 3 deletions(-) diff --git a/sips/sip-02x/sip-02x-stacks-pay.md b/sips/sip-02x/sip-02x-stacks-pay.md index be3468666..b062e1a03 100644 --- a/sips/sip-02x/sip-02x-stacks-pay.md +++ b/sips/sip-02x/sip-02x-stacks-pay.md @@ -135,6 +135,60 @@ refuse to continue. --- +## Token Types and Amount Specification + +### Supported 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. +- Amount MUST be specified in micro-STX (uSTX) +- 1 STX = 1,000,000 uSTX + +**A valid SIP-010 contract address**: For payments using SIP-010 compliant fungible tokens. +- Format: `CONTRACT_PRINCIPLE.CONTRACT_NAME` +- Amount MUST be specified in the token's base unit as defined by its `decimals` field + +### Amount Base Unit Requirement + +All amount values in StacksPay URLs MUST be specified in the token's smallest unit (base unit): + +**For STX:** +- Use micro-STX (uSTX) as the base unit +- 1 STX = 1,000,000 uSTX +- Examples: + - `amount=1000000` = 1 STX + - `amount=500000` = 0.5 STX + - `amount=1` = 0.000001 STX + +**For SIP-010 Tokens:** +- Use the token's base unit as defined by its `decimals` field +- Base unit = 10^decimals +- Examples: + - Token with 6 decimals: `amount=1000000` = 1 token + - Token with 18 decimals: `amount=1000000000000000000` = 1 token + - Token with 0 decimals: `amount=1` = 1 token + +### Rationale + +This approach ensures: +1. **Precision**: No floating-point arithmetic errors +2. **Blockchain Compatibility**: Matches how Stacks transactions work internally +3. **Consistency**: Same pattern that Bitcoin (satoshis) and Stacks (uSTX) utilize in their transaction handling +4. **Universal Support**: Works with any SIP-010 token regardless of decimal places + +### Implementation Notes + +**For Wallet Developers:** +- Convert base units to human-readable format for display +- Example: Show "1 STX" instead of "1000000 uSTX" to users +- Validate that amounts don't exceed token supply limits + +**For Application Developers:** +- Use helper functions to convert from human units to base units +- Example: `STXToMicroSTX(1)` returns `1000000` +- Always validate decimal places match the token specification + ## URL Scheme & Encoding ### Data Format @@ -261,7 +315,7 @@ basic validation. ## 7 Ratification Criteria -1. SIP 029 accepted by governance. +1. SIP accepted by governance. 2. At least one reference implementation passes test-vectors. 3. A major wallet releases Stacks Pay support. 4. Ten independent merchants (or two payment-service providers) adopt it. @@ -271,7 +325,7 @@ basic validation. ## 8 Economics Stacks Pay does not alter consensus rules or tokenomics; however, easier -payments **SHOULD** increase transaction throughput, miner fees, and the +payments may increase transaction throughput, miner fees, and the utility of STX and SIP-010 assets. --- @@ -291,7 +345,7 @@ utility of STX and SIP-010 assets. * Bech32m – BIP-350 specification * SIP-009 – Non-Fungible Token Standard (for `mint` contract references) -## FAQ +## Appendix ### Why change the protocol scheme and encoding human readable part? @@ -311,3 +365,112 @@ examples: In the interest of starting with low hanging fruit and providing utility to the most users, an NFT mint function seems the obvious choice. And while, as @leopradel pointed out, there is no 'mint' function defined in SIP-009 (nft-mint is a clarity function), the reality is that Gamma's \([https://gamma.io](https://gamma.io)\) smart contracts are the defacto standard here. Following their lead and implementing a simple, structured 'mint' operation that calls Gamma's nft 'claim' function allows us to specify a controllable, easy-to-use, and useful smart contract payment function while limiting the attack surface area that general smart contract calls would open up. User education is still required here as malicious apps can always leverage fake contracts to steal from users, or even large DEXes. + +### Integration Simplicity + +#### Comparison to Other Blockchain Payment Standards + +Stacks Pay is designed to be significantly easier to integrate than traditional blockchain payment flows: + +#### Integration Effort Comparison + +| Integration Aspect | Ethereum/Web3 | Stacks Pay | Effort Reduction | +|-------------------|---------------|------------|------------------| +| Setup complexity | High (provider, contracts) | Low (single package) | 80% less | +| Code required | 50-100+ lines | 3-10 lines | 90% less | +| Wallet integration | Complex (multiple protocols) | Simple (URL/QR) | 85% less | +| Error handling | Extensive (gas, reverts, etc.) | Minimal (URL validation) | 75% less | +| Testing required | High (multiple networks) | Low (URL generation) | 70% less | + +**Ethereum/EVM Integration Complexity:** +- Requires web3 provider setup and wallet connection +- Complex smart contract interactions with gas estimation +- Manual transaction building and signing +- Multiple confirmation states to handle +- Network-specific configuration (mainnet, testnets, L2s) + +**Stacks Pay Integration:** +- Single npm package: `npm install stacks-pay` +- Generate payment URL in 3 lines of code +- No wallet connection required for URL generation +- Works with any Stacks-compatible wallet +- Network-agnostic URL format + +#### Integration Examples + +**Creating a payment request (Merchant side):** +```typescript +import { encodeStacksPayURL } from 'stacks-pay'; + +const paymentURL = encodeStacksPayURL({ + operation: 'invoice', + recipient: 'SP2RTE7F21N6GQ6BBZR7JGGRWAT0T5Q3Z9ZHB9KRS', + token: 'STX', + amount: '1000', + description: 'Coffee purchase' +}); + +// Result: Ready-to-share URL or QR code +``` + +**Processing payments (User side):** +- User clicks link or scans QR code +- Wallet opens with pre-filled transaction details +- User confirms payment +- Transaction processes on Stacks blockchain + + +#### Developer Experience Benefits + +1. **No Blockchain Expertise Required**: Developers can integrate cryptocurrency payments without understanding smart contracts or gas mechanics +2. **Universal Compatibility**: Works with any application that can generate URLs or QR codes +3. **Offline Generation**: Payment requests can be created without blockchain connection +4. **Social Media Friendly**: URLs can be shared via email, SMS, social media, or embedded in websites +5. **Mobile-First**: Optimized for mobile wallet scanning and one-tap payments + +#### Real-World Integration Scenarios + +**E-commerce Platform:** + +```typescript +// Add to checkout flow +const checkoutURL = encodeStacksPayURL({ + operation: 'invoice', + recipient: process.env.MERCHANT_ADDRESS, + token: 'STX', + amount: cart.total.toString(), + description: `Order #${order.id}` +}); + +// Display as QR code or payment button + +``` + +**Donation Button:** + +```typescript +// Reusable donation link +const donationURL = encodeStacksPayURL({ + operation: 'support', + recipient: 'SP2RTE7F21N6GQ6BBZR7JGGRWAT0T5Q3Z9ZHB9KRS', + description: 'Support our project' +}); +// Amount left blank for user to specify +``` + +**NFT Marketplace:** + +```typescript +// Dynamic minting +const mintURL = encodeStacksPayURL({ + operation: 'mint', + contractName: 'SP123...my-nft-collection', + functionName: 'mint', + token: 'STX', + amount: '500', + description: 'Mint NFT #1234' +}); + +``` + +This integration simplicity enables rapid adoption across diverse use cases, from simple tip jars to complex marketplace integrations, without requiring specialized blockchain development expertise. \ No newline at end of file