PascalCoin/PIP/PIP-0023.md

  PIP: PIP-23
  Title: JSON RPC PASCURRENCY format
  Type: Backend, Documentation
  Impact: API | Mobile
  Author: Benjamin Ansbach <[email protected]>
  Comments-URI: 
  Status: Draft
  Created: 2018-07-19

Summary

It is proposed to change the JSON RPC API so that all delivered and received currency values follow a common standard.

Motivation

Handling large numbers and especially floating point numbers is a common task in the cryptocurrency world. To make the communication through an interface to the currencies functionalities more consistent and less error prone, it is advised to make sure that:

1. Currency values are formatted in the same way throughout the project. Consistency
2. Currency values are formatted in the smallest available denominator. Ethereum has wei, bitcoin has satoshi -> PascalCoin has molina
3. Currency values are returned (and received) as a string. Depending on the denominator, the resulting value can extend the maximum supported size of an integer and may result in unexpected behavior on the client side. A transaction value of 214748,3648 PASC would already lead to problems 32bit signed

In the JSON RPC API of PascalCoin we have a mixup of 2 different formats: Prices are formated as PASC with 4 decimals. But the information about the price of an account that is for sale is delivered as an integer in the smallest available denomination.

This inconsistency as well as the possible problems that come along with the current way of formatting PascalCoin currency values are motivation enough to change the implementation.

Specification

Each currency value will be returned in molinas (smallest denominator) and as a string. The following Objects and JSON RPC parameters need to be adjusted.

Objects

1. Account Object

   • balance
   • price

2. Block Object

   • reward
   • fee

3. Operation Object

   • amount
   • fee
   • balance
   • senders.*.amount
   • receivers.*.amount
   • changers.*.account_price
   • changers.*.fee
     

4. MultiOperation Object

   • amount
   • fee
   • senders.*.amount
   • receivers.*.amount

5. RawOperations Object

   • amount
   • fee
     

JSON RPC methods params + results

1. getwalletcoins
   • result
2. sendto + signsendto
   • params.amount
   • params.fee
3. changekey + signchangekey
   • params.fee
4. listaccountforsale + signlistaccountforsale
   • params.fee
   • params.price
5. delistaccountforsale + signdelistaccountforsale
   • params.fee
6. buyaccount + signbuyaccount
   • params.amount
   • params.fee
7. changeaccountinfo + signchangeaccountinfo
   • params.fee
8. multioperationaddoperation
   • params.senders.*.amount
   • params.receivers.*.amount
9. operationsdelete
   • result.amount
   • result.fee

Documentation

The documentation of the PASCURRENCY value in the JSON RPC specification will be changed to:

Pascal Coin currency is a string representing the PascalCoin value in the smallest available denomination (1/10000th) which is called Molina.

Homepage

We need to specify the lesser known denomination Molina somewhere on the homepage. This will be discussed.

Rationale

We never know what kind of client works with the JSON-RPC API and how he handles floating point numbers or so called "Big Numbers". This change will make sure that no client will ever face a problem with currencies.

Backwards Compatibility

This change is not backwards compatible and will require a new major version.

Reference Implementation

{
    "fee": "1",
    "amount": "2147483648"
}