Remove irrelevant content

adding tags

See merge request grassrootseconomics/cic-docs!14

spec/011_Reserve_Proof_Spec.md

@@ -0,0 +1,103 @@
+# PROOF FORMAT FOR REAL-WORLD RESERVE ASSETS 
+
+This is draft status
+
+
+A collection of proofs represents contracts describing real and virtual assets posted as reserve for a specific token issuance.
+
+The underlying resources for the proofs may be documents, recordings, photos, crypto transactions.
+
+sha256sum is calculated on files. crypto transaction hashes are used as-is. All data is is left-padded to 512 bit vectors.
+
+The hashes are ordered in sequence of their big-endian numerical value and sha256sum is calculated on the sequence. This is the collateral proof.
+
+--
+
+The proof should be signed by the key performing the initial reserve transaction and made available. The following options should be considered:
+
+- A secp256k1 ECC signature on the proof
+- A ethereum blockchain transaction to a well-known address, with the proof in the data field
+- An ENS record
+
+Additional signatures may optionally be added.
+
+
+---
+
+The proof, signature and underlyding digital resources must be disseminated to a selection of storers whose role is to provide data availability on demand.
+
+With the eventual maturity of decentralized storage, additional data availability guarantees can come from these.
+
+---
+
+metadata structures can be added to provide metadata and context for the digial resources in the proof.
+
+This structure can also allow alternate hash representations of the data, aswell as additional signatures.
+
+Lastly it can include a list of locations where the resources can be obtained. The resources should be available on querying the proof hash, responding with the resources in a well-known achive format, and optionally providing a human readable index of the files (the client can choose using the 'Accept' HTTP header)
+
+---
+
+example:
+
+A contract for a token reserve consists of a written document A, a video recording B and a crypto transaction C.
+
+sha256(A), sha256(B) are calculated. They result in Ah = 0x56.., Bh = 0x12. C = 0x34..
+
+sha256 is calculated on the ordered sequence to obtain the proof; sha256(Bh, C, Ah) = Ph 
+
+Token T is minted by sending reserve from account K. Ph is signed by the same key; secp256k1.ec_sign(K, Ph) = Ks
+
+The proof is encapsulated by metadata:
+
+```
+{
+	'version': 0,
+	'token': <token address>,
+	'proofs': {
+		'default': {
+			'digest': <Ph>,
+			'signatures': [
+				<Ks>,
+			],
+		},
+		'foo-algo': [
+			'digest': <Ph2>,
+			'signatures': [
+				...,
+			],
+		],
+	},
+	'resources': [
+		{
+			'type': 'file',
+			'proof': {
+				'default': {
+					'digest': <...>,
+				}
+			},
+			'metadata': {
+				'mime-type': 'application/pdf',
+				'filename': 'foo.pdf',
+			},
+		},
+		{
+			'type': 'ethereum-transaction',
+			'proof': {
+				'default': {
+					'digest': <...>,
+				}
+			},
+		},
+	],
+	'locations': [
+		'ftp://ftp.grassrootseconomics.org/reserve-resources',
+		'https://redcross.com/grassrootseconomics/reserve-resources',
+		...
+	]
+}
+```
+
+---
+
+Another possiblity is to host the proofs on DNS TXT records by well-known actors. This means, for example, if _<Ph>_resource_proofs.grassrootsconomics.org could returns the token address (or the other way around), that means GE considers the proof valid for the token. A list of DNS hosts can be established to decentralize this certification.

spec/012_multitoken_platform_api_extension.md

@@ -1,70 +0,0 @@
-# API EXTENSIONS FOR EXTERNALLY CREATED BLOCKCHAIN RESOURCES
-
-At time of writing, apis are registered under `/api/v2`. This will change.
-
-## NOMENCLATURE
-
-Values enclosed with `<>` are _required_.
-
-Values enclosed with `[]` means _optional_.
-
-No enclosure means _literal_.
-
-## CHANGED METHODS
-
-Endpoints _modified_ are found under /api/v1/
-
-Changes will be submitted upstream.
-
-### `/api/v1/organisation`
-
-### **POST**
-
-One item is added to data payload:
-
-```
-{
-	account_address: [address],
-}
-```
-
-If specified, the organisation will be bound to the specified blockchain account, and _will not_ create a new account on instantiation.
-
-## ADDED METHODS
-
-Endpoints _added_ are found under /api/ext/
-
-### `/api/ext/exchange/register`
-
-#### **POST**
-
-Creates a new entry in `exchange_contract` table in database.
-
-Requires token addresses to be registered in advance on `/api/v1/token/`
-
-Request payload:
-```
-{
-	reserve_address: <address>,
-	token_address: <address>,
-	converter_address: <address>,
-	registry_address: <address>,
-	connector_weight: <uint>,
-}
-```
-
-Response payload on success:
-```
-{
-	message: 'Exchange added',
-	data: {
-		exchange: (exchange schema dump, TODO specify)
-	}
-}
-```
-
-Returns:
-```
-201 - exchange record created
-400 - token addresses not known to platform
-```

spec/013_locations_api_extension.md

@@ -1,102 +0,0 @@
-# API EXTENSIONS FOR MANIPULATING LOCATIONS RECORDS
-
-## NOMENCLATURE
-
-Values enclosed with `<>` are _required_.
-
-Values enclosed with `[]` means _optional_.
-
-No enclosure means _literal_.
-
-## ADDED METHODS
-
-Endpoints _added_ are found under /api/ext/
-
-### `/api/ext/geolocation/`
-
-#### **POST**
-
-Adds a location entry to the database
-
-Request payload:
-```
-{
-	common_name: <string>,
-	latitude: <float>,
-	longitude: <float>,
-	parent_id: [uint],
-}
-
-```
-
-`parent_id` is the location table id of the location record for the greater area encapsulating the location being registered.
-
-### `/api/ext/geolocation/<path_string>/`
-
-#### **GET**
-
-Retrieves a location record based on the given `path_string`. Every part of the given path string must match the value in the location hierarchy. A path string must have minimum one part.
-
-Example, given database has `foo/bar` and `foo/baz`: A search of `foo/bar` will only match `foo/bar`. A search of `foo` will match both `foo/bar` and `foo/baz`.
-
-Response payload:
-
-```
-{
-	id: <uint>,
-	common_name: <string>,
-	path: <string>,
-	latitude: <float>,
-	longitude: <float>,
-}
-
-```
-
-`common_name` is the location leaf name.
-
-`path` is the full hierarchical path string.
-
-### `/api/ext/geolocation/<ext_type>/<ext_id>/`
-
-
-#### **GET**
-
-Queries the `location_external` table for a matching value, and returns the `location` object associated with it. 
-
-Currently only `OSM` is supported as `ext_type`. The value given matches a `place_id` entry in the external table.
-
-Data format returned the same as `GET /api/ext/geolocation/<path_string>/`
-
-### `/api/ext/user/<user_id>/geolocation/`
-
-#### **PUT**
-
-Sets the location of the affected user
-
-Data payload:
-
-```
-{
-	location_id: <uint>
-}
-```
-
-#### **GET**
-
-Retrieves full objects for the hierarchical path of the user location.
-
-Response payload:
-
-```
-{
-	user_id: user_id,
-	location: [
-		{
-			common_name: <string>,
-			longitude: <float>,
-			latitude: <float>,
-		},
-		...
-	],
-}
-```

spec/015_accounts_api_extension.md

@@ -1,80 +0,0 @@
-# API EXTENSIONS FOR INDEPENDENT TRANSFER ACCOUNTS
-
-At time of writing, apis are registered under `/api/v2`. This will change.
-
-## NOMENCLATURE
-
-Values enclosed with `<>` are _required_.
-
-Values enclosed with `[]` means _optional_.
-
-No enclosure means _literal_.
-
-## ADDED METHODS
-
-Endpoints _added_ are found under /api/ext/
-
-### `/api/ext/transfer_account/register/`
-
-#### **POST**
-
-Create a new transfer_account bound to an organisation.
-
-Request payload:
-```
-{
-	address: <address>,
-	organisation_id: <uint>,
-}
-```
-
-Response payload on success:
-```
-{
-	message: 'Created',
-	data: {
-		id: <uint>
-	},
-}
-```
-
-`id` is the id of the newly created transfer account
-
-Returns:
-```
-201 - transfer account is added
-400 - address or organisation data invalid
-404 - organisation not found
-```
-
-### `/api/ext/user/`
-
-#### **POST**
-
-Add a new user without transfer account. The user will be associated with the organisation in the API session context.
-
-Request payload:
-```
-{
-	phone: <string>,
-	first_name: <string>,
-	last_name: <string>,
-}
-```
-
-Response payload on success:
-```
-{
-	data: {
-		id: <uint>
-	},	
-}
-```
-
-`id` is the id of the newly created user.
-
-Returns:
-```
-201 - user created
-400 - organisation context missing
-```

spec/016_cic_token_platform_registration.md

@@ -0,0 +1,121 @@
+# CIC TOKEN PLATFORM REGISTRATION
+
+This document describes the components and steps involved to announce a token registration to the network.
+
+
+## RATIONALE
+
+Although registering a new token on the Bancor contracts will emit events upon which CIC client code can act upon, the information available is limited to the token itself and the exchange only. Therefore, a way to specify additional metadata for the entity that should be associated with the token must be provided.
+
+
+## OVERVIEW
+
+The system consists of two smart contracts and a metadata schema. The schema describes the actual metadata, and the contracts provide the announcement of the token metadata availability, and a mechanism to locate where the metadata can be retrieved from.
+
+A separate, more formal document will be written as a request for comment for decentralized metadata dissemination for institutionally identifiable information.
+
+
+### CONTRACTS
+
+The `DecentralizedStorageResolver` contract facilitates multiplexing of data resource locations across web2 and web3 networks. It is a separately maintained project with its own documentation. Its utility here is to let an entity specify one or more locations where the metadata for the registration can be retrieved.
+
+The `CICRegistration` contract announces the availability of metadata for a given token. In essence it is a simple chain of mappings (names do not match contract properties):
+
+```
+{
+	'token_address': {
+		'token_announcer_address': {
+			'resolver_address': <address>,
+			'resolver_type': <bytes32>,
+			'resolver_chain': <bytes32>,
+		}
+	}
+}
+
+```
+
+The `resolver_type` is a sha256 hash of a custom resolver id. The only three recognized values at current time are:
+* `sha256(DecentralizedStorageResolver)`, the resolver mentioned above
+* `sha256(ENS1)` - first generation ENS
+* `sha256(ENS2)` - second generation ENS , which refers to the aforementioned contract. 
+
+`resolver_chain` is a custom chain identifier string, which identifies which and what type of decentralized consensus resource holds the resolver record. It has the following format:
+
+```
+<platform>:<version>:<network>:<chain>
+```
+
+Example values are:
+
+* `ethereum:1:bloxberg:8995`
+* `ethereum:1:main:1`
+
+### SCHEMA
+
+The schema defines how the metadata must be formatted. The data type is json, and has the following layout:
+
+(TODO: write in official schema spec language instead if exists)
+
+```
+{
+	"schema_version": 1,
+	"network": "bancor",
+	"token": "<hex>",
+	"identities": {
+		"default": "<rfc-2426, must be unencrypted>",
+		"[recipient_hint]": "<rfc-2426, optionally encrypted>",
+		...
+	},
+}
+
+[] = optional value
+<hex> = 0x-prefixed hexadecimal value
+[recipient_hint] = (optional) arbitrary value that can be announced off-band to specific consumers, in order to instruct how to decrypt the values. Cannot be "default"
+<entity> = arbitrary string specifying an organisation or person to associate with the token.
+```
+
+The actual organisation and person detail records are given in RFC-6350 vcard format. The **MINIMUM** amount of data the default entity can contain is:
+
+```
+BEGIN:VCARD
+ORG: <organisation_name_to_register>
+X-COUNTRY-CODE: <ISO 639-1 country_ode>
+TZ:<tzdata>
+END:VCARD
+```
+
+### SEMPO PLATFORM INTEGRATION
+
+To register all necessary information for a new token with associated organisation and exchange, we require the following items of information:
+
+- bancor registry address
+- token address
+- organisation name
+- organisation country
+- organisation timezone
+- admin email
+
+A new blockchain listener component is needed that monitors the `CICRegistration` contract for `TokenRegistration` events. The first iteration will have these limitations:
+
+* Will only work with `DecentralizedStorageResolver`.
+* Expect the record in the `DecentralizedStorageResolver` to already be available at time of announcement.
+* Only use the default identity. 
+* Only read the minimum of entries required (see below). Any additional fields in the VCARD will be ignored for now.
+* No encryption supported.
+
+The minimum content of the VCARD for Sempo platform token metadata registration is:
+
+```
+BEGIN:VCARD
+ORG: Acme Inc.
+X-COUNTRY-CODE: ke
+TZ:Africa/Nairobi
+EMAIL: admin@acme.org
+END:VCARD
+```
+
+### RESOURCES
+
+* [CICRegistration contract](https://gitlab.com/grassrootseconomics/cic-contracts/-/blob/master/cic-registration/contracts/CICRegistration.sol)
+* [DecentralizedStorageResolver contract](https://gitlab.com/nolash/resolvemux/-/blob/master/Resolver.sol)
+* [RFC 6350](https://tools.ietf.org/html/rfc6350)

spec/017_CIC Deployment.md

@@ -0,0 +1,27 @@
+# CIC TOKEN TOOLING
+
+This document is WIP.
+
+## RATIONALE
+
+Simplify execution of network deployment, token deployment.
+
+
+
+The tooling should faciliate the following functions:
+
+* Bootstrap network
+* Deploy new CIC token/converter pair
+* List tokens in network
+* Query registry for contracts in network
+* Query CIC token supply
+* Query converter stats (weight, supply, fee)
+* Mint additional tokens
+* Burn tokens
+
+<!--all: simplify code (use web3 arg builders rather than manual ones)
+1. 1+2: connect to wallet using jsonrpc
+1. 2: enable initial tx to deposit reserve and first mint
+1. 2+3: connect with my metadata registry contract (deduplication of token symbols)
+-->
+