Stacks Pay

Stacks Pay is a proposed payment request standard for the Stacks blockchain. It provides a standardized method for encoding, decoding, and processing payment requests, ensuring interoperability between wallets and applications within the Stacks ecosystem.

Features

• Supports Multiple Operations: support, invoice, mint, and custom operations.
• Bech32m Encoding: Ensures compatibility and data integrity, suitable for QR codes and URL sharing.
• Comprehensive Validation: Ensures all parameters meet required formats and constraints.
• Extensible: Allows for custom operations tailored to specific use cases.

Installation

npm install stacks-pay

Usage

Importing functions

import { encodeStacksPayURL, decodeStacksPayURL } from "stacks-pay";
import {
  InvoiceOperation,
  SupportOperation,
  MintOperation,
  CommonParameters,
} from "stacks-pay/dist/types";

Encoding a payment request

Invoice Operation

import { encodeStacksPayURL, InvoiceOperation } from "stacks-pay";

const invoiceParams: InvoiceOperation = {
  operation: "invoice",
  recipient: "SP2RTE7F21N6GQ6BBZR7JGGRWAT0T5Q3Z9ZHB9KRS",
  token: "STX",
  amount: "1000",
  description: "Payment for services rendered",
  expiresAt: "2024-12-31T23:59:59Z",
};

const encodedURL = encodeStacksPayURL(invoiceParams);
console.log("Encoded Invoice URL:", encodedURL);

Support Operation

import { encodeStacksPayURL, SupportOperation } from "stacks-pay";

const supportParams: SupportOperation = {
  operation: "support",
  recipient: "SP2RTE7F21N6GQ6BBZR7JGGRWAT0T5Q3Z9ZHB9KRS",
  description: "Support for ongoing development",
  memo: "Thank you for your support!",
};

const encodedURL = encodeStacksPayURL(supportParams);
console.log("Encoded Support URL:", encodedURL);

Mint Operation

import { encodeStacksPayURL, MintOperation } from "stacks-pay";

const mintParams: MintOperation = {
  operation: "mint",
  contractName: "my-nft-contract",
  functionName: "mint",
  token: "STX",
  amount: "500",
  recipient: "SP2RTE7F21N6GQ6BBZR7JGGRWAT0T5Q3Z9ZHB9KRS",
  description: "Minting a new NFT",
  expiresAt: "2024-12-31T23:59:59Z",
};

const encodedURL = encodeStacksPayURL(mintParams);
console.log("Encoded Mint URL:", encodedURL);

Custom Operations

import { encodeStacksPayURL, CommonParameters } from "stacks-pay";

const customParams: CommonParameters = {
  operation: "custom-action",
  contractName: "SP2RTE7F21N6GQ6BBZR7JGGRWAT0T5Q3Z9ZHB9KRS",
  funcionName: "public-dao-function",
  memo: "Memo for special action",
  data: "Custom action parameters",
};

const encodedURL = encodeStacksPayURL(customParams);
console.log("Encoded Custom Operation URL:", encodedURL);

Decoding a payment request

import { decodeStacksPayURL } from "stacks-pay";

const fullURL =
  "web+stx:stx1wajky2mnw3u8qcte8ghj76twwehkjcm98ahhqetjv96xjmmw845kuan0d93k2fnjv43kjurfv4h8g02n2qe9y4z9xarryv2wxer4zdjzgfd9yd62gar4y46p2sc9gd23xddrjkjgggu5k5jnye6x76m9dc74x4zcyesk6mm4de6r6vfsxqczver9wd3hy6tsw35k7m3a2pshjmt9de6zken0wg4hxetjwe5kxetnyejhsurfwfjhxst585erqv3595cnytfnx92ryve9xdqn2wf9xdqn2w26juk65n";

const decodedParams = decodeStacksPayURL(fullURL);
console.log("Decoded Parameters:", decodedParams);

// output:
// {
//  "operation": "invoice",
//  "recipient": "SP2RTE7F21N6GQ6BBZR7JGGRWAT0T5Q3Z9ZHB9KRS",
//  "token": "STX",
//  "amount": "1000",
//  "description": "Payment for services rendered",
//  "expiresAt": "2024-12-31T23:59:59Z"
// }

Handling Custom Operations

Custom operations allow you to extend the standard set of operations (support, invoice, mint) with your own defined actions. Here's how to handle them:

Encoding Custom Operations

When encoding a custom operation, include any additional parameters relevant to your use case:

import { encodeStacksPayURL, CommonParameters } from "stacks-pay";

const customParams: CommonParameters = {
  operation: "custom-action",
  recipient: "SP2RTE7F21N6GQ6BBZR7JGGRWAT0T5Q3Z9ZHB9KRS",
  memo: "Custom memo for special action",
  data: "Some custom data related to the action",
};

const encodedURL = encodeStacksPayURL(customParams);
console.log("Encoded Custom Operation URL:", encodedURL);

Decoding Custom Operations

Upon decoding, all custom parameters will be included in the resulting object:

import { decodeStacksPayURL } from "stacks-pay";

const fullURL = "web+stx:stx1..."; // Your encoded custom operation URL

const decodedParams = decodeStacksPayURL(fullURL);
console.log("Decoded Custom Operation Parameters:", decodedParams);
// output:
//{
//  "operation": "custom-action",
//  "recipient": "SP2RTE7F21N6GQ6BBZR7JGGRWAT0T5Q3Z9ZHB9KRS",
//  "memo": "Custom memo for special action",
//  "data": "Some custom data related to the action"
//}

API Reference

encodeStacksPayURL(params: CommonParameters): string

Description:
Encodes the provided payment parameters into a Stacks Pay URL using Bech32m encoding.

Parameters:

• params (CommonParameters): An object containing the payment parameters. Must include the operation field and any other required fields based on the operation type.

Returns:

• string: The encoded Stacks Pay URL.

Throws:

• Error if required parameters are missing or invalid.

Example:

const encodedURL = encodeStacksPayURL(invoiceParams);

decodeStacksPayURL(fullURL: string): CommonParameters

Description:
Decodes a Stacks Pay URL back into its constituent payment parameters.

Parameters:

• fullURL (string): The complete Stacks Pay URL to decode.

Returns:

• CommonParameters: An object containing the decoded payment parameters.

Throws:

• Error if the URL has an invalid protocol or encoding, or if required parameters are missing/invalid.

Example:

const decodedParams = decodeStacksPayURL(fullURL);

CommonParameters Interface

Defines the structure of payment parameters used in encoding and decoding.

export interface CommonParameters {
  operation: OperationType;
  recipient?: string;
  token?: string;
  amount?: string;
  description?: string;
  memo?: string;
  expiresAt?: string;
  invoiceNumber?: string;
  dueDate?: string;
  contractAddress?: string;
  contractName?: string;
  functionName?: string;
  [key: string]: string | undefined; // Allows additional custom parameters
}

Fields:

• operation (OperationType): The type of operation (support, invoice, mint, or custom).
• recipient (string, optional): The recipient's Stacks address.
• token (string, optional): The token type (e.g., STX).
• amount (string, optional): The amount to be transferred.
• description (string, optional): A description of the payment.
• memo (string, optional): An optional memo for the payment.
• expiresAt (string, optional): Expiration timestamp in ISO format.
• invoiceNumber (string, optional): Invoice number for tracking.
• dueDate (string, optional): Due date for the invoice.
• contractAddress (string, optional): Address of the smart contract (for mint operations).
• contractName (string, optional): Name of the smart contract (for mint operations).
• functionName (string, optional): Function name in the smart contract (for mint operations).
• [key: string]: string | undefined;
  Allows inclusion of additional custom parameters for custom operations.

Testing

Ensure that all functionalities work as expected by running the test suite.

Run Tests

npm test

Test Coverage

The package includes basic unit tests covering:

• Encoding and decoding of standard operations (support, invoice, mint).
• Handling of custom operations with arbitrary parameters.
• Validation of required and optional parameters.
• Error handling for invalid inputs and malformed URLs.

Contributing

Contributions are welcome! Whether it's improving the documentation, fixing bugs, or adding new features, your input is valuable.

How to Contribute

1. Fork the Repository

   Click the "Fork" button at the top right of the repository page to create your own copy.

2. Clone Your Fork

   git clone https://github.com/your-username/stacks-pay-js.git
   cd stacks-pay-js

3. Create a New Branch

   git checkout -b feature/YourFeatureName

4. Make Changes

   Implement your changes, ensuring that the code adheres to the existing style and passes all tests.

5. Commit Your Changes

   git commit -m "Add feature: YourFeatureName"

6. Push to Your Fork

   git push origin feature/YourFeatureName

7. Open a Pull Request

   Navigate to the original repository and click "Compare & pull request" to submit your changes for review.

Guidelines

• Code Quality: Ensure your code is clean, well-documented, and follows TypeScript best practices.
• Testing: Add tests for new features or bug fixes to maintain high test coverage.
• Documentation: Update the README and other documentation as necessary to reflect your changes.

License

This project is licensed under the MIT license.

Contact

For any questions, suggestions, or support, please reach out:

• GitHub Issues: stacks-pay-js/issues

Repository

Access the source code and contribute on GitHub:

• GitHub Repository: https://github.com/dantrevino/stacks-pay-js

Additional Resources

• Stacks Pay SIP: Stacks Pay SIP on GitHub
• Bech32m Specification: BIP-350
• Stacks Documentation: Stacks Docs