FATIP-2 Pegged Asset Token Standard

.gitignore

@@ -0,0 +1,10 @@
+# Ignore common artifacts of editing
+#
+# Binaries for programs and plugins, merges, tools
+*.idea
+*.dat
+*.orig
+*.txt
+
+# Goland
+.idea/*

FATIPS.md

@@ -2,7 +2,7 @@
 
 # Factom Asset Token Improvement Proposals :gear:
 
-[![](https://img.shields.io/badge/FAT%20Standards-5-brightgreen.svg?style=for-the-badge)](FATIPS.md)
+[![](https://img.shields.io/badge/FAT%20Standards-7-brightgreen.svg?style=for-the-badge)](FATIPS.md)
 
 [![Discord](https://img.shields.io/discord/479606362507313152.svg?style=for-the-badge)](https://discord.gg/8ADPfSc)
 
@@ -28,9 +28,9 @@ defines the FATIP process.
 
 ## Work In Progress
 
-| FATIP | Name | Category |
-| ----- | ---- | -------- |
-|       |      |          |
+| FATIP | Name                        | Category       |
+| ----- | --------------------------- | -------------- |
+| 2     | Pegged Asset Token Standard | Token Standard |
 
 
 ## Draft

README.md

@@ -125,6 +125,12 @@ A non-fungible asset token standard.
   - Every token is unique, and can have unique properties
   - Tokens have a history of the addresses they've resided at
 
+### [**FAT-2**](fatips/2.md)
+
+Pegnet: Pegged Asset Token Standard
+
+
+
 
 # Getting Started
 

fatips/2.md

@@ -0,0 +1,276 @@
+| FATIP | Title                       | Status | Category       | Author               | Created   |
+| ----- | --------------------------- | ------ | -------------- | -------------------- | --------- |
+| 2     | Pegged Asset Token Standard | WIP    | Token Standard | Pegnet Working Group | 7-17-2019 |
+
+
+
+# Summary
+
+From the [PegNet Whitepaper](https://docs.google.com/document/d/1yv1UaOXjJLEYOvPUT_a8RowRqPX_ofBTJuPHmq6mQGQ/edit#heading=h.b48un57wbewg):
+
+> PegNet is a Pegged Token Network that leverages simple game theory to create a set of pegged assets that reinforce each other.  The network provides a mechanism for managing payments, treasury allocations, and budgets across jurisdictions without requiring expensive and slow processes through external parties such as financial institutions, payment processors, exchanges, etc.  
+
+
+
+# Motivation
+
+From the Pegnet Whitepaper:
+
+> Pegged tokens are generally useful for payments, treasury management, exchanges, and wealth preservation.  A Pegged Token network defines a set of pegged tokens, which reflect real market assets such as currencies, precious metals, other cryptocurrency assets, commodities, etc.  For example, a token pegged to USD can be used to make USD purchases, and both the buyer and seller can be assured of the payment with the pegged value will be very close to equal to the dollar equivalent.  For companies holding cryptocurrency assets, the ability to convert parts of those assets into a dollar peg can help to preserve capital when the cryptocurrency market is low.  
+>
+> [...]
+>
+> Pegging to cryptocurrencies can facilitate transactions representing Bitcoin or other cryptocurrency values without the transaction limitations that might exist on the those  blockchains.  Pegging values to other commodities or assets are possible, expanding the use cases for a Pegged Token Network.
+
+# Specification
+
+### Token Model
+
+The pegged asset token standard ("Pegnet") describes an interconnected ecosystem of pegged fungible tokens. Pegged tokens are atomically convertible to each other at exchange rates determined for that block by the OPR grading algorithm.
+
+Pegged tokens are "virtual" in nature, as opposed to regular FAT-0 tokens which have their own issuances and chains. Pegged tokens have no dedicated chain or issuance datastructure as they have no issuers. Pegnet token balances are calculated using a combination of mined OPRs, transactions, conversions, and burning of FCT.
+
+
+
+### Pegged Assets (PARTIAL LIST)
+
+The following assets are supported or will be supported by the pegged asset token system, detailed via Factom mainnet activation height on Pegnet.
+
+| Asset Name       | [ISO 4217](https://en.wikipedia.org/wiki/ISO_4217) Symbol | Pegnet Symbol | Activation Height |
+| ---------------- | --------------------------------------------------------- | ------------- | ----------------- |
+| PegNet           | -                                                         | PEG           | 0                 |
+| US Dollar        | USD                                                       | pUSD          | 0                 |
+| Euro             | EUR                                                       | pEUR          | 0                 |
+| Japanese Yen     | JPY                                                       | pJPY          | 0                 |
+| Pound Sterling   | GBP                                                       | pGBP          | 0                 |
+| Canadian Dollar  | CAD                                                       | pCAD          | 0                 |
+| Swiss Franc      | CHF                                                       | pCHF          | 0                 |
+| Indian Rupee     | INR                                                       | pINR          | 0                 |
+| Singapore Dollar | SGD                                                       | pSGD          | 0                 |
+| Chinese Yuan     | CNY                                                       | pCNY          | 0                 |
+| Hong Kong Dollar | HKD                                                       | pHKD          | 0                 |
+|                  |                                                           |               |                   |
+
+
+
+### Pegged Asset Onramps
+
+Pegged asset onramps are necessary to inject value into the pegged asset token system. Typically this is achieved by burning or locking up the underlying pegged asset.
+
+#### Factom
+
+Creation of pegged Factom ("pFCT") tokens is described by conducting a 0 Entry Credit purchase on the host Factom network to the following addresses to fund the respective virtual Pegnet networks:
+
+- TestNet - `EC2BURNFCT2PEGNETooo1oooo1oooo1oooo1oooo1oooo19wthin`
+- MainNet - `EC2BURNFCT2TESTxoooo1oooo1oooo1oooo1oooo1oooo1EoyM6d`
+
+The specified input amount describes the quantity of pFCT credited to the purchasing Factoid address on the pegged asset token system at a fixed rate of 1 FCT = 1 pFCT.
+
+
+
+### Oracle Price Records (OPR)
+
+The pegged asset token system uses Oracle Price Record entries, or OPRs, as the main vehicle for oraclizing and forming consensus on exchange rates. An OPR is composed of several core components:
+
+- An answer to a proof of work question
+- Asset exchange rates, relative to USD, as witnessed by the miner
+- A payout address for rewards
+
+Miners submit valid OPRs to the OPR chain each block in hopes of winning a competitive proof of work problem against other miners that rewards in the base token: PEG.
+
+#### OPR Chain
+
+A single Factom chain is defined to house OPR entries depending on test or production chains, defined as the chain with hex encoded External IDs in zero-indexed order:
+
+##### TestNet for Milestone 1
+- `5065674e6574` - "PegNet" in ascii
+- `546573744e65742d704d31` - "TestNet-pM1" in ascii. 
+- `4f7261636c6550726963655265636f726473` - "OraclePriceRecords" in ascii
+
+Corresponding to chain ID `13de39548b56de06a0c4637f6b16852db6fc56749cbd71692ef9af61a2da3247`
+
+##### MainNet
+- `5065674e6574` - "PegNet" in ascii
+- `4d61696e4e6574` - "MainNet" in ascii. 
+- `4f7261636c6550726963655265636f726473` - "OraclePriceRecords" in ascii
+
+Corresponding to chain ID `a642a8674f46696cc47fdb6b65f9c87b2a19c5ea8123b3d2f0c13b6f33a9d5ef`
+
+#### OPR Proof of Work Calculation
+
+Each OPR contains a set bytes in ExtId[0] called the nonce. To evaluate the proof of work result ("difficulty"), the Grading algorithm takes the SHA-256 hash of the entry's content, appends it with the nonce, and LXR-Hashes it. The first 8 bytes of the resulting hash are converted to an unsigned 64 bit integer in Big Endian order. A higher value is considered a better difficulty, with 0 being the worst and `2^64 - 1` being the best.
+
+```
+TODO: NEED HEIGHT-CHALLENGE-SOLUTION EXAMPLE
+```
+
+#### OPR Entry
+
+##### ExtIDs
+
+| ID | Type | Description | 
+|---|---|---|
+| 0 | byte array | The OPR's nonce for the PoW calculation |
+| 1 | 64-bit unsigned integer| Self-reported difficulty: the result of that OPR's PoW calculation |
+| 2 | 8-bit unsigned integer | Version id |
+
+#####  Content Example & Validation
+
+##### Version: 1
+
+```json
+{
+  "height":104981,
+  "winners": [
+    "ba98d1bc839877a6",
+    "450b0e3cf82c44a1",
+    "d836f7dd1bd35cea",
+    "622999fc9cd69d04",
+    "1445e65cb2950df5",
+    "ccc624f717fd404c",
+    "63ffab6aa79e290d",
+    "261495af94840ccd",
+    "f341e51eb9573352",
+    "e73d7efe8baa5cca"
+  ],
+  "coinbase": "FA1zT4aFpEvcnPqPCigB3fvGu4Q4mTXY22iiuV69DqE1pNhdF2MC",
+  "miner": "identity-placeholder",
+  "assets": {
+    "PNT": 0,
+    "USD": 1.0109,
+    "EUR": 0.9147,
+    "JPY": 110.7317,
+    "XBC": 339.839,
+    "FCT": 4.2861
+  }
+}
+```
+
+| Name       | Type   | Description                                                  | Validation                                                   | Required |
+| ---------- | ------ | ------------------------------------------------------------ | ------------------------------------------------------------ | -------- |
+| `height`   | number | The Factom block height this OPR was mined at                | Must be a valid integer. Greater than zero.                  | Y        |
+| `winners`  | array  | Previous winning OPR Factom short entry hashes               | Values must be 10 valid entry hashes that correspond to the previous OPR winning entries in order. The genesis OPR has no previous winning entries | Y        |
+| `coinbase` | string | The public Factoid address to credit the PEG mining reward to | Must be a valid public Factoid address.                      | Y        |
+| `miner`    | string | Stub for future development. The identity of the miner that mined this OPR. | To be a Valid DID chain; initially a arbitrary string. Max length 64 chars if present. | N        |
+| `assets`   | object | The witnessed exchange rates by the miner                    | Keys must be pegnet currency symbols, values must be numbers greater than or equal to `0`  (initially the PEG value can be zero) | Y        |
+
+
+#### OPR Grading Algorithms
+
+##### Version 1 (Activation Height: 0)
+
+To grade, a block must have at least 10 valid OPRs.
+
+With each block, OPRs submitted to the Oracle Price Record chain are graded for the purpose of distributing the 
+block reward.  The highest graded OPR also provides the pricing for the Pegged assets for that block.
+
+[Grading](https://docs.google.com/document/d/1yv1UaOXjJLEYOvPUT_a8RowRqPX_ofBTJuPHmq6mQGQ/edit#bookmark=id.4nst6v3fi9ki) is done as follows:
+
+* Sort all valid OPR by their difficulty.
+* If less than 10, no OPR records are valid.
+* If more than 50 are valid, take the top 50, and reduce the valid OPRs by repeated passes until only 10 OPR records remain:
+  * Compute the average value for each pegged asset as reported by all 50 OPRs 
+  * For each remaining valid OPR 
+    * Compute the grade for the opr 
+        * For each asset in the OPR
+            * Calculate the difference of that OPR's price from the average price reported by all OPRs
+            * Add to the OPR grade the square of the square of the difference 
+    * Sort OPRs by their grades, and remove the OPR with the highest grade 
+* The final 10 are sorted primary by grade and secondary by proof of work.
+
+
+##### Rewards:
+The best graded 10 OPR records 
+ * Best graded OPR gets 16% (800 PEG)
+ * Second best OPR gets 12% (600 PEG)
+ * All Other OPRs get 9% each (450 PEG)
+
+
+
+### Conversion Transactions
+
+Conversions represent a specialized type of transaction that atomically converts one terminal pegged FAT-0 asset into another at the current OPR based exchange rate. Conversions may also move tokens between addresses without conversion.
+
+#### Conversion Rate
+
+All conversions use the exchange rate defined in the OPR with the highest grade inside that block. If a conversion is written to a block that has no winners, the conversions are evaluated using the highest grade of the following block with winners.
+
+#### Conversion Transaction Chain
+
+Each pegged network shall have its own conversion chain, defined using the same network string as the OPR chain. For example, the Testnet conversion chain is defined as the following hex encoded External IDs:
+
+- `5065674e6574` - "Pegnet" in ascii
+- `546573744e6574` - "Testnet" in ascii. Can be "Mainnet" for production
+- `436F6E76657273696F6E73` - "Conversions" in ascii
+
+#### Conversion Transaction Entry
+
+##### Content Example & Validation
+
+```json
+{
+	"from": "PEG",
+    "input": "FA1zT4aFpEvcnPqPCigB3fvGu4Q4mTXY22iiuV69DqE1pNhdF2MC",
+    "to": "FCT",
+    "output": "FA1zT4aFpEvcnPqPCigB3fvGu4Q4mTXY22iiuV69DqE1pNhdF2MC",
+    "amount": 10.021,
+	"origin": true,
+    "metadata": "I want Factom!"
+}
+```
+
+| Name       | Type    | Description                                                  | Validation                                          | Required |
+| ---------- | ------- | ------------------------------------------------------------ | --------------------------------------------------- | -------- |
+| `from`     | string  | The pegged asset token ID to convert from                    | Must be a valid pegged token symbol                 | Y        |
+| `input`    | string  | The Public Factoid address to us as an input for `from` type of pegged token | Must be a valid public Factoid address              | Y        |
+| `to`       | string  | The pegged asset token ID to convert to from `from`          | Must be a valid pegged token symbol                 | Y        |
+| `output`   | string  | The Public Factoid address to us as an output for `to` type of pegged token | Must be a valid public Factoid address              | Y        |
+| `amount`   | number  | The amount of `from` to use as an input to the conversion    | Must be greater than `0`                            | Y        |
+| `origin`   | boolean | Whether to apply `amount` as the input amount of the conversion. `amount` is applied as the conversion output amount of `to` by default. | Valid boolean. May be omitted for default behavior. | N        |
+| `metadata` | any     | Arbitrary user defined metadata for the conversion           | Must be valid JSON                                  | N        |
+
+##### Signing
+
+Conversions are signed according to [FATIP-103](103.md). The signing set is
+the key corresponding to `input` field. The conversion must include an RCD/Signature pair for the source address of the conversion. Signatures and RCDs are defined in the External IDs of the conversion entry as laid out in FATIP-103.
+
+#### Conversion Transaction Validation
+
+Conversions must meet all of the following criteria to be valid.
+
+General Criteria:
+
+- The content of the entry must be a single well-formed JSON.
+- The JSON must contain all required fields listed in the above table, all fields and their members must be of the correct type. No unspecified fields may be present. No duplicate field names are allowed.
+- The entry hash of the conversion entry must be unique among all
+  previously valid conversions of the pegged asset token.
+- The External IDs must follow the cryptographic and structural
+  requirements defined by [FATIP-103](103.md) for the `address` input
+
+Specific Criteria:
+
+- If `origin` is true, `input` must own at least `amount` of pegged token `from` for the conversion to be valid
+- If `origin` is false or omitted, `input` must own at least `amount` of pegged token `from` at current ORP exchange rate for the conversion to be valid
+
+
+
+If all criteria is met, the following occurs as a single atomic operation:
+
+- `amount` (or equivalent at current OPR exchange rate if `origin` is true) of token `from` is burnt (destroyed) in address `input`
+- `from` is converted to PEG (interim) at the OPR exchange rate
+- Interim PEG is expended to create `to`  via coinbase transaction to `output` at the current OPR exchange rate
+
+The conversion is complete.
+
+
+
+# Implementation
+
+[Pegnet Project](https://github.com/pegnet/pegnet)
+
+
+
+# Copyright
+
+Copyright and related rights waived via
+[CC0](https://creativecommons.org/publicdomain/zero/1.0/).