Merge pull request #134 from Techworker/master

PIP-23

PIP/PIP-0023.md

@@ -0,0 +1,115 @@
+<pre>
+  PIP: PIP-23
+  Title: JSON RPC PASCURRENCY format
+  Type: Backend, Documentation
+  Impact: API | Mobile
+  Author: Benjamin Ansbach <i>&lt;[email protected]&gt;</i>
+  Comments-URI: 
+  Status: Draft
+  Created: 2018-07-19
+</pre>
+
+## 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
+
+```json
+{
+    "fee": "1",
+    "amount": "2147483648"
+}
+```