PascalCoin/PIP/PIP-0026.md

  PIP: PIP-0026
  Title: URI Scheme
  Type: Frontend
  Impact: None
  Author: Ugochukwu Mmaduekwe 
  Comments-URI: https://discord.gg/sJqcgtD  (channel #pip-0026)
  Status: Draft
  Created: 2018-10-29

Summary This PIP proposes a URI scheme for making PascalCoin payments.

Motivation While PascalCoin is a unique and viable digital assets, one of it's limitations as a currency is lack of channels to use it as a digital currency to pay for goods and services. For this to happen, a standard scheme has to be defined by which payment URIs are deemed valid or not.

The purpose of this URI scheme is to enable users to easily make payments by simply clicking links on webpages or scanning QR Codes.

Specification

General Rules For Handling (IMPORTANT!)

PascalCoin clients MUST NOT act on URIs without getting the user's authorization. They MUST require the user to manually approve each payment individually.

Operating System Integration Graphical PascalCoin clients SHOULD register themselves as the handler for the "pasc:" URI scheme by default, if no other handler is already registered. If there is already a registered handler, they MAY prompt the user to change it once when they first run the client.

General Format

PascalCoin URIs follow the general format for URIs as set forth in RFC 3986. The path component consists of a pascalcoin account (must include the checksum), and the query component provides additional payment options.

Elements of the query component may contain characters outside the valid range. These must first be encoded according to UTF-8 standard, and then each octet of the corresponding UTF-8 sequence must be percent-encoded as described in RFC 3986.

The scheme component ("pasc:") is case-insensitive, and implementations must accept any combination of uppercase and lowercase letters. The rest of the URI is case-sensitive, including the query parameter keys.

Query Keys

name	datatype	description	optional
label	string	(e.g. name of receiver)	true
account	string	the pascalcoin account (must contains the checksum)	false
message	string	(e.g. description of the transaction)	true
amount	double	the amount to be sent. (unit MUST be in PASC)	true

*label: Label for that address (e.g. name of receiver)

*account: pascalcoin account (with checksum): this is validated internally using the pascalcoin account checksum

*message: message that describes the transaction to the user

*amount: amount of pascalcoin units (MUST BE IN PASC).

• (EPSILON = 0.00009) is the delta we use to determine if a value should be treated as zero or not in the URI.
• If amount is zero (i.e amount <= EPSILON), it is ignored and not added to the final URI, so amount must be > 0.
• Negative amounts are not allowed.
• Amounts are formatted to a maximum of 4 decimal places for consistency purposes only in the generated URI. for example 0.000091 => 0.0001, 0.00014 => 0.0001, 0.00015 => 0.0001, 0.00016 => 0.0002.

Additional Query Keys that does not include those stated above but are complete (includes the request and params style fields) are ignored but does not make the URI invalid for now.

Transfer amount

If an amount is provided, it MUST be specified in decimal PASC. All amounts MUST contain no commas and use a period (.) as the separating character to separate whole numbers and decimal fractions. i.e. amount=50.00 or amount=50 is treated as 50 PASC, and amount=50,000.00 is invalid.

PascalCoin clients MUST display the amount in any format so long as it is clear enough not to deceive the user. They SHOULD choose a format that is foremost least confusing, and only after that most reasonable given the amount requested. For example, so long as the majority of users work in PASC units, values should always be displayed in PASC by default, even if molina would otherwise be a more logical interpretation of the amount.

Rationale

Accessibility (URI scheme name) Should someone from the outside happen to see such a URI, the URI scheme name (pasc) already gives a description. A quick search should then do the rest to help them find the resources needed to make their payment.

Backwards Compatibility As this PIP is written, no clients have already implement a pasc: URI scheme similar to this one, so yes this is backwards compatible.

Appendix

Syntax

This section gives a simple overview of the URI.

[foo] means optional, <bar> are placeholders

pasc:<account>[?amount=<amount>][?label=<label>][?message=<message>]

Examples

Just the address:

pasc:0-10

Account with name:

pasc:0-10?label=PascalCoin-Dev

Request 50.30 PASC to "PascalCoin-Dev":

pasc:0-10?amount=50.3&label=PascalCoin-Dev

Request 50 PASC to "Pascalcoin-Dev" with message "Donation For PascalCoin Project":

pasc:0-10?amount=50&label=PascalCoin-Dev&message=Donation%20For%20PascalCoin%20Project

Some version that has variables which are (currently) not understood and required but does not make the URI invalid:

pasc:0-10?somethingweird=100&somethinghaywire=kingkong

Once again, Characters must be URI encoded properly using RFC 3986.

Reference Implementation

• ObjectPascal - https://github.com/Xor-el/PIP-0026/blob/master/PASCPaymentURI/src/UPASCPaymentURI.pas