FATIP-201 Address Workflow Standard

FATIPS.md

@@ -28,10 +28,11 @@ defines the FATIP process.
 
 ## Work In Progress
 
-| FATIP                | Name                    | Category       |
-| -------------------- | ----------------------- | -------------- |
-| [13](fatips/13.md)   | Mineable Token Standard | Token Standard |
-| [102](fatips/102.md) | FAT Index Standard      | Meta           |
+| FATIP                | Name                      | Category       |
+| -------------------- | ------------------------- | -------------- |
+| [13](fatips/13.md)   | Mineable Token Standard   | Token Standard |
+| [102](fatips/102.md) | FAT Index Standard        | Meta           |
+| [201](fatips/201.md) | Address Workflow Standard | Core           |
 
 
 ## Draft

fatips/201.md

@@ -0,0 +1,200 @@
+| FATIP | Title                     | Status | Category | Author                            | Created   |
+| ----- | ------------------------- | ------ | -------- | --------------------------------- | --------- |
+| 201   | Address Workflow Standard | WIP    | Core     | Devon Katz\<<devonk@dbgrow.com>\> | 10-1-2018 |
+
+[TOC]
+
+# Summary
+
+This standard defines a mechanism to classify addresses, and restrict address class interactions. The standard uses a basic graph data structure to model class interaction restrictions.
+
+# Motivation
+
+No previous FATIP standard addresses use cases where restricting who can receive and trade tokens is critical.
+
+ For example, certain securities tokens are illegal to transfer to unaccredited investors. Perhaps you want to ensure that recipients of aid programs cannot easily form black markets by restricting trade between registered addresses. This standard proposes a structure to solve these issues, while providing compatibility with any token system that uses Factoid addresses for trading tokens.
+
+# Specification
+
+This standard defines Factoid address roles, address role relationships, and membership of Factoid addresses to address roles & metadata. Address roles and interactions are defined using a simple directed graph data structure where:
+
+- **Address Roles** are vertices (`vertices`)
+- **Address Role Relationships** are directed edges between vertices (`edges`)
+- **Factoid Address => Address Role** mapping is metadata held in a map (`addresses`)
+
+The spec allows address role relationships in the graph to be self cycles (e.g. A => B => B => ... => B => C) to denote that a role can trade with addresses of the same role, and traditional cycles (e.g. A => B => C => A ) to denote that one or more middlemen must be included in the token's lifecycle for tokens to return to their original holder.
+
+
+
+## Example
+
+ In this vusual example & following technical example we'll be modeling an aid program that defines a token workflow to help curb corruption and unexpected market dynamics:
+
+
+![](../assets/fatip-201-example-graph.png)
+
+(where solid black lines are transfers of tokens by a role. note: off chain redemption & settlement between parties not shown in workflow chart)
+
+This model is meant to simulate a program where an authority party such as an aid program or government issues tokens directly to aid recipients. Aid recipients are able to spend the tokens at stores for goods or services. Stores may then redeem the tokens with the government for settlement are barred from trading the tokens with other aid recipients to create a targeted model. for goods and services. Shops may only send tokens to the government for redemption & settlement.
+
+This is just a simple example. It's possible to model a wide variety of market dynamics using this standard.
+
+
+
+## Token Issuance Chain
+
+This standard uses the implementing token standard's issuance chain for it's entries.
+
+To be valid and secure, this standard requires FATIP-201 data is signed by the issuing identity(For example, using FATIP-101).
+
+### Initial Valid Token Issuance Entry
+
+The implementing is expected use the standard field name `FATIP201` under the root of it's content JSON. To be valid, the first valid issuance entry in any implementation of this standard must declare an an initial workflow under the aforementioned `FATIP201` field in it's root.
+
+
+
+#### Example Initial Valid Issuance Data Structure & Field Summary
+
+```json
+"FATIP201": {
+    "vertexes": {
+        "v0": {
+            "role" : "Aid Recipient",
+            "balanceLimit": 400,
+            "actions": ["coinbase"]
+        },
+        "v1": {
+            "role" : "Store"
+        },
+        "v2": {
+            "role" : "Government",
+             "actions": ["burn"]
+        }
+    },
+    "edges": {
+        "e0": {
+        	"from": "v0",
+            "to": "v1",
+            "metadata":{
+                "description": "From Aid Recipient To Store"
+            }
+        },
+        "e1": {
+        	"from": "v1",
+            "to": "v2",
+             "metadata":{
+                "description": "From Store To Government"
+            }
+        },
+         "e2": {
+        	"from": "v2",
+            "to": "v0",
+              "metadata":{
+                "description": "From Government To Aid Recipient"
+            }
+        }
+    },
+    "addresses": {
+        "FA3aECpw3gEZ7CMQvRNxEtKBGKAos3922oqYLcHQ9NqXHudC6YBM": {
+    		"vertex": "v0",
+            "balanceLimit": 400
+		},
+        "FA3ZxKyN3HHoJftdGbFp5PRvi12jPvQ3SgGNTDQya2D5jwFrtLqZ": {
+    		"vertex": "v1",
+            "metadata": {
+                "storeId": "cNF293nf1kll1!v1d2valksldaius"
+            }
+		}
+    }
+}
+```
+
+| Name                                 | Type   | Description                                                  | Validation                                                  | Required |
+| ------------------------------------ | ------ | ------------------------------------------------------------ | ----------------------------------------------------------- | -------- |
+| `vertexes`                           | object | The map of unique vertex Ids to vertexes. Each vertex represents a role in the workflow. |                                                             | Y        |
+| `vertexes[<vertex id>]`              | object | The vertex (role) definition                                 |                                                             | Y        |
+| `vertexes[<vertex id>].role`         | string | The name of the role                                         | User defined name                                           | Y        |
+| `vertexes[<vertex id>].balanceLimit` | number | The maximum token balance that can be achieved by addresses belonging to the role. If omitted, no upper limit is enforced. | Positive nonzero integer                                    | N        |
+| `vertexes[<vertex id>].actions`      | array  | Array of additional actions members of the role may take. Se below for action descriptions. |                                                             | N        |
+| `vertexes[<vertex id>].actions[n]`   | string | `burn` - The role has the ability to send tokens to the burn address. `coinbase` - The role can receive transactions directly from the issuer via a coinbase transaction. See below for more information. | Must be one of [`coinbase`, `burn`] if `actions.length` > 0 | N        |
+|                                      |        |                                                              |                                                             |          |
+| `edges`                              | object | The map of unique edge Ids to directed edge definitions between vertices. Each edge represents an allowed directed trade relationship between roles |                                                             | Y        |
+| `edges[<edge id>]`                   | object | The directed edge (role relationship) definition             |                                                             | Y        |
+| `edges[<edge id>].from`              | string | The vertex id that the edge originates from                  | `vertexes[<from>]` must exist                               | Y        |
+| `edges[<edge id>].to`                | string | The vertex id that the edge terminates at                    | `vertexes[<to>]` must exist                                 | Y        |
+| `edges[<edge id>].metadata`          | object | Free space for user defined key value pairs                  |                                                             | N        |
+|                                      |        |                                                              |                                                             |          |
+| `addresses`                          | object | The collection of approved addresses                         |                                                             | Y        |
+| `addresses[<address>]`               | object | The data describing the approved Factoid address `<address>` | `<address>` must be a valid Factoid address                 | Y        |
+| `addresses[<address>].vertex`        | string | The vertex id of the role `<address>` belongs to             | `vertexes[<vertex>]` must exist                             | Y        |
+| `addresses[<address>].balanceLimit`  | number | The maximum token balance this address can hold. Overrides `classes[<class>].balanceLimit` on a address by address basis | positive nonzero integer                                    | N        |
+| `addresses[<address>].metadata`      | object | Free space for user defined key value pairs                  |                                                             | N        |
+
+
+
+#### Reserved Role: `general` 
+
+The role name `general` (`vertexes[<vertex id>].role`) is reserved for special usage. The `general` role encompasses all Factoid addresses that are not explicitly approved in the `addresses` data structure. This allows including the general public in workflow models without having to approve or register large quantities of addresses.
+
+By default the `general` role is omitted from `vertexes`, meaning that tokens may not be traded to non approved addresses in the general public. You may override the `general` role in the `vertexes`  data structures to define `general`'s place in your workflow.
+
+
+
+#### Action: `coinbase`
+
+The `coinbase` action represents the ability for a role to accept tokens from FAT's designated coinbase address, The 0th Factoid Address: `FA1y5ZGuHSLmf2TqNf6hVMkPiNGyQpQDTFJvDLRkKQaoPo4bmbgu` representing a private key with all zeros. Only roles that have this action may accept coinbase transactions which birth new coins into circulation. This is useful for defining "entry routes" tokens must take to enter circulation.
+
+ If no `coinbase` action is defined among all roles(vertexes), coinbase regulation is disabled for the workflow and any role can accept coinbase transactions.
+
+
+
+#### Action: `burn`
+
+The `burn` action represents the ability for a role to burn tokens by sending them to FAT's designated burn address, The 0th Factoid Address: `FA1y5ZGuHSLmf2TqNf6hVMkPiNGyQpQDTFJvDLRkKQaoPo4bmbgu` representing a private key with all zeros.
+
+If no `burn` action is defined among all roles(vertexes), token holders can not formally, permanently burn tokens.
+
+
+
+### Workflow Update Entry
+
+It's unreasonable to expect a single issuance entry to define all addresses, roles, metadata, and more in a single 10KB entry for a workflow. Entries on the issuance chain following the initial valid issuance entry serve as update entries for modifying address classes, approved addresses, and more. 
+
+
+
+A simple update syntax is defined to perform updates, and the same standard `FATIP201` field name is used to contain the update:
+
+
+
+#### Example Workflow Update Entry Content & Field Summary
+
+```json
+"FATIP201": {
+    "update":{
+		"$setAddress": {
+			"FA3sdfsZxKyN3fn34iufn3i4n29292SgsdfGNTDQya2D5dddj": {
+            	"vertex": "v0"
+            }
+     	}
+    }
+}
+```
+
+| Name                                 | Type   | Description                                                  | Validation                                                   | Required |
+| ------------------------------------ | ------ | ------------------------------------------------------------ | ------------------------------------------------------------ | -------- |
+| `update`                             | object | The update to apply to the workflow implementation           |                                                              | Y        |
+| `update[<operator>]`                 | object | The collection of `<operator>` type updates to apply.        | `<operator>` must be a valid operator                        | Y        |
+|                                      |        |                                                              |                                                              |          |
+| `update["$setVertex"][<vertex id>]`  | object | Update or add an object describing a role vertex by vertex ID. Value Equivalent to `vertexes[<vertex id>]` | Equivalent to `vertexes[<vertex id>]`                        | Y        |
+| `update["$setEdge"][<edge id>]`      | object | Update or add an object describing a edge between role vertexes by edge ID edges b belonging to a class. Value Equivalent to `edges[<edge id>]` | Equivalent to `edges[<edge id>]`                             | Y        |
+| `update["$setAddress"][<address>]`   | object | The object describing the address's class, metadata, etc. Value Equivalent to `addresses[<address>]` | `<address>` must be a valid Factoid address. Equivalent to `addresses[<address>]` | Y        |
+| `update["$unsetAddress"][<address>]` | -      | Remove an approved address                                   | `<address>` must be a valid Factoid address. The value of the key must be non null | Y        |
+
+# Implementation
+
+
+
+# Copyright
+
+Copyright and related rights waived via
+[CC0](https://creativecommons.org/publicdomain/zero/1.0/).