Merge branch 'willruddick-master-patch-44374' into 'master'

license

See merge request grassrootseconomics/cic-docs!113

README.md

@@ -1,7 +1,9 @@
 ## Community Inclusion Currencies (CICs) Documentation
 Community Inclusion Currency (CIC) technology seeks to give organizations and communities the ability to issue, use and manage CICs in order to build resilient and connected economies.
+
+ ## General Documentation
  + [White Paper](https://gitlab.com/grassrootseconomics/cic-docs/-/blob/master/CIC-White-Paper.pdf)
- + [Training Materials](https://docs.google.com/document/d/1CI-Xz9R3FgZ70uWgq81U5uwfaYrm9f6Ji4f7dL2-V90/edit?usp=sharing) 
+ + [Training Materials](https://gitlab.com/grassrootseconomics/cic-docs/-/blob/master/CIC_Training_Guide_Kenya.pdf) 
  + [Frequently Asked Questions](https://docs.google.com/document/d/1qtlOEL4pqW1vOL893BaXH9OqRSAO3k0q2eWbVIkxEvU/edit?usp=sharing) 
  + [Blog](https://www.grassrootseconomics.org/blog)
  + [MOOC](https://www.grassrootseconomics.org/mooc) - Very old (paper based systems)
@@ -9,91 +11,87 @@ Community Inclusion Currency (CIC) technology seeks to give organizations and co
  + [Transaction Data CSVs](https://www.grassrootseconomics.org/research): Transaction Datasets and Research
  + [Live Data Dashboard](https://dashboard.sarafu.network)
  + [Animated Explainer Video](https://www.youtube.com/watch?v=vJL9-FFleow)
+ + [Jam Board](https://jamboard.google.com/d/1PcowWC7UNCOtfpaeUT2hu8_GoEU-kwzmcHYLvplUFOM/edit?usp=sharing)
+ + [Preso](https://drive.google.com/file/d/1qLfNgIBkhnrxesAJd2Sn9eCxsAzctSqV/view?usp=sharing)
  
  
- ## Open source code
+ ## CIC-Commons - Open source code
- + [Managment Platform](https://gitlab.com/grassrootseconomics/cic-platform)
+ + **CIC-Charter**, Charter and top level code desctiption ([CIC Charter](https://gitlab.com/grassrootseconomics/cic-docs/-/blob/master/cic-charter.md))  
+ + **Base components**, containing all necessary provisions for services and tooling. ([Chaintools](https://gitlab.com/chaintool))
+ + **Generic services components**, libraries, daemons and services making up the custodial engine. ([cicnet](https://gitlab.com/chaintool))
+ + **Deployment components**, which facilitates deployment of the custodial engine, as well as seeding data for development, demonstration and migration. ([GrassrootsEconomics](https://gitlab.com/grassrootseconomics/)) 
  + [Dashboard](https://github.com/GrassrootsEconomics/Accdash) [Dashboard API](https://github.com/GrassrootsEconomics/Accap)
- + [Blockchain Smart Contract](https://github.com/bancorprotocol/contracts) 
+ + [Demurrage Smart Contract](https://gitlab.com/cicnet/erc20-demurrage-token) 
 
-## CIC full system vision ##
+## CIC full system notes ##
+See ([CIC Engine](https://gitlab.com/grassrootseconomics/cic-docs/-/blob/master/cic-engine.md)) for our vision mission and community statement
  * Blockchain
-   * Currently: We are on a public blockchain (Layer 2 side chain) called [xDAI](https://www.xdaichain.com/) 
+   * Currently: To ensure decentralization, censor proofing and fair gas prices we work on Humanitarian Blockchains like bloxberg.org.
-   * Goal: To ensure decentralization, censor proofing and fair gas prices we plan to setup a validation node on this chain and look into possible Humanitarian Blockchains.
+     * Blockchain 1st vs database
+     * Any interface can be developed without central control
+     * A blockchain where gas prices can be kept to zero. 
+     * A Proof of Authority chain where nodes can be elected democratically or Proof of Stake where the Token Issuers have Stake
+     * A blockchain that enables easy and secure bridging to other chains. 
  * Blockchain Contracts
-   * Bridge - in order to move between the xDAI side chain (Layer 2) and the Ethereum main net we need a bridge (hard spoon).
+   * [Demurrage token](https://gitlab.com/cicnet/erc20-demurrage-token) - Network / Basic Income token - Mints tokens that include a demurrage.
-     * Currently: We connect to the Ethereum Main net using the xDAI to DAI bridge.
+   * Bridge - in order to move between the side chains (Layer 2) we use a bridge 
-     * Goal: To have options to bridge to a variety of potential reserves
+     * Currently: We have no connections to Ethereum Mainnet 
-   * Bonding Curves - Enable us to add collateral (aka Reserves to CICs) as well as connect CICs to each other in a safe way.
+     * Goal: To have options to bridge to a variety of other tokens - possibly Cosmos Protocol
-     * Currently: Bancor Protocol v1 - [Blockchain Smart Contract](https://github.com/bancorprotocol/contracts)
+   * Liquidty Pools - Enable connection of Sarafu and CICs to each other and outside networks
-     * Goal: Researching Bancor Protocol v2 and other options
+     * Currently not in use. 
+     * Goal" A variety of options for connecting CICs and other tokens, such as [Static and Bonded Liquidity pools](https://www.grassrootseconomics.org/post/static-vs-bonded-liquidity-pools-for-cics)
    * Contract Deployment (Currency Creation service)
-     * Currently: We currently deploy the Bancor Contract suite manually via Command line
+     * Currently: We currently deploy all contracts via Command line
-     * Goal: Both a USSD based and a web based interface for organizations and communities to create their own tokens
+     * Goal: A web based interface for organizations and communities to create their own tokens and other contracts (DAO)
 * CIC Token Creation system 
-     * Currently: Manual contract deployment (command line)
+     * Currently: Manual contract deployment (command line) and paper based agreements with communities.
-     * Registered organizations can submit an application to be an issuer, they must have:
+     * Goal: Registered organizations can submit an application to be an issuer, they must have:
-        * an audited and legally binding backing commitment signed by local government to back the total amount of a CIC .
+        * an audited and legally binding backing commitment signed by local guarentors to back the total amount of a CIC .
-        * A collateral fund of at 25% of the tokens they want to create. 
+        * The CIC issuers should also choose to add thier CIC to a liquidity pool with Sarafu or other CICs for connections
-          * This collateral can be pulled out of any CIC (such as those provided by an Aid CIC) or purchased 
+     * Longer term goal: DAOs
-        * These new CIC tokens are created and the converter contract is given the sole ability to create and destroy them based on a bonding curve equation THe converter also holds the collateral (reserve or pool) of xDAI 
 * Cloud server - is where we host all of our systems, Platform, Dashboard, future blockchain node.  
-   * Currently: We are using AWS for instances and data storgage along with postgress databases - Transactions are done here first then synced with blockchain
+   * Currently: We are using Digital Ocean for instances and data storgage along with postgress databases - Transactions are done here first then synced with blockchain
-   * Goal: Moving toward a webased wallet and cloud storage
+   * Goal: Migrating servers to Digital Ocean using Kubernetes. 
+     * Moving toward a web-based wallet and decentralized data storage with self-soverign data (certificate based)
+ * Simulations 
+   * Currently: We started with a home grown Village Market Simulator and are currently are developing and using a cadCAD based [modeling](https://gitlab.com/grassrootseconomics/cic-modeling) simulation built by BlockScience
+   * Goal: To build on this simulation to validate and stress test economic models and to provide predictive analysis based on data
  * Dashboard
    * Currently: [Our dashboard](https://dashboard.sarafu.network) uses a D3 javascript we also have an internal dashboard for CIC platform administrators. 
      * We are pulling data from an internal postgres database on the CIC Mgmt Platform as well as blockchain transaction data from BlockScout
    * Goal: To have system related information available to field officers and users on Android phones and to pull data from our own blockchain node.
      * To allow donors to give directly and measure the impact of their giving
      * To visualize trade and the health of economies and communities
- * Simulations 
+     * To pull transaction and user meta data from blockchain directly (also used in marketplace)
-   * Currently: We started with a home grown Village Market Simulator and are currently are developing and using a cadCAD based [modeling](https://gitlab.com/grassrootseconomics/cic-modeling) simulation built by BlockScience
-   * Goal: To build on this simulation to validate and stress test economic models and to provide predictive analysis based on data
  * Marketplace
-   * Currently: Mostly word of mouth but Grassroots Economics provides limited signage to users and marketing of products in the network is done by word of mouth, SMS messaging and a phone support team.
+   * Currently: Word of mouth but Grassroots Economics provides limited signage to users and marketing of products in the network is done by word of mouth, SMS messaging and a phone support team.
    * Goal: A web based interface for organizations and communities to share projects, event offers and wants using CICs
- * CIC Management Platform 
+     * Self-sovergin [certificates](https://gitlab.com/grassrootseconomics/cic-docs/-/blob/master/spec/020_redeemable_certifcate.md) (NFTs) form the basis for the marketplace 
+     * A USSD marketplace (Directory) system that can be searchable and likned to regional areas
+ * CIC Administration Dashboard (CICADA) - Management Platform 
      * Currently: System admins (GE staff) are able to assist users to reset pins, reverse transactions, create new users. The system is build on React and Flask in Python and uses postgres for data stroage.
-     * Goal: Stabilization of the platform and synchronization to blockchain, and eventual migration to a webBased wallet system with cloud storage with minimal need.
+     * Goal: Migration to Angular and stabilization of the platform and synchronization to blockchain, and eventual migration to a webBased wallet system with cloud storage with minimal need.
  * Wallet:
      * Currently: Users connect via USSD through AfricasTalking to connect with their wallet on the CIC Mgmt Platform, private keys are held by Grassroots Economics for these phones
      * Goal: 
-       * WebApp 
+       * Telegram Chat bot
-       * Non custodial
+       * [WebApp](https://gitlab.com/grassrootseconomics/cic-docs/-/blob/master/spec/010_Web_Wallet.md) 
-       * Social account recovery
-       * Cloud data storage (Swarm/IPFS) - opt in data, with an option sharing and for 3rd party validation
-       * Market Place linkages
-       * Auto-conversion – so you only have one (CIC) token (your community token) - all other tokens auto convert
-       * CIC aware 
-         * you can change your home token to another
-         * You can see the stats of any CIC you want to trade with or change to
-         * You can see the effect of cashing in and cashing out on the CIC
-       * Payment Rails
-         * Ability to add National currency (Mpesa) – in order to create/buy more CIC
-         * Ability to liquidate a CIC for National Currency (Mpesa)
  * Fiat On-ramp / off-ramp - In order to enable users and donors to interact with CICs we need a way to move fiat on and off the blockchain
-   * Currently: the float account is in no way linked to blockchain and handled manually (bank transfers)
+   * Currently: any connection to national currency is handled manually (eMoney / bank transfers)
-     * We currently move Fiat (USD/EUR) on an off the blockchains we use via exchanges such as BitCoinSwiss and local cryptos connected to Banks as well as eMoney
+   * Goal: To connect to / create API driven liquidity pools to fiat (eMoney) 
-     * You can send Mpesa (eMoney) to our lipa na Mpesa account – GE sees that and sends back tokens
+     * To make credit card another other payment on and offramps available and streamline our fiat to token processes.
-     * You can also send tokens to GE and GE sends back Mpesa from the float account (this currently very restricted)
+     * Exchange Rates will be variable based on the CIC → KSH rate (depends on the liquidity pool maths) 
-   * Goal: To make credit card another other payment on and offramps available and streamline our fiat to token processes ... blockchain integration
+ * Blockchain interaction (once bridged)
-   * Goal: As there is imbalance in the float account – Tokens can be burnt (xDAI extracted – bridged to DAI  (eg see xDAI.io) → converted to Eth and sold for KSH (BitcoinSuisse  ~2% fee)
+   * Anyone who can obtain or create any CIC token can send it to a liquidity pool if avalaible for conversion and bridging. 
-     * If there is too much KSH – we would send it to (BitcoinSuisse ~2% fee) to convert to Eth then make DAI with it and bridge to xDAI (eg see xDAI.io)
+ * Data /ID System - 
-     * The float account balancing would happen on a monthly cycle (ideally) – initially manual and eventually automated
-     * Exchange Rates will be variable based on the CIC → xDAI rate (depends on amount of collateral) Spot price: P  = 4R/S (R= reserve S = Supply) but they will also take into account FX fees.
- * Blockchain interaction (once connected to xDAI reserves)
-   * Anyone who can obtain Eth or DAI can create xDAI and send it directly to any CIC converter blockchain contract. They will mint an amount of that CIC based on the bonding curve equation. 
-   * Anyone can also send a CIC to the same contract to liquidate it and pull out the xDAI and convert to DAI or ETH. Note that there are markets to cash out ETH in Kenya such as LocalCryptos as well but at high costs (~10%).
-   * Note that you can also buy Eth in Kenya with Mpesa on local cryptos and could convert it to xDAI then add it to a CIC reserve.
- * ID System - 
    * Currently: Each user has a sim card and the Telecom provides KYC services - users are asked a pin number to access the account on USSD 
-   * Goal: Creating a more robust ID system for users with and without sim cards. Possibly adding brightID social ID  - like technologies with confidence scoring or 3rd party biometrics
+   * Goal: Creating a more robust ID system for users with and without sim cards. Possibly adding brightID social ID  - like technologies with confidence scoring 
-     * Non custodial data ownership on cloud where users can specify what data tehy want to make avalible
+     * Non custodial data ownership on cloud where users can specify what data they want to make avalible
- * Rewards and Incentives - [see specifications](./spec/001_platform_incentives.md)
+     * Move toward a 'claims' based system where CIC are claims against redemption with endorsments and data and other claims can be created and endorsed - such as product offering, carbon offseting, SDG Impacts.
-     * Currently: These incentive systems are a mixture of manual and CIC Mgmt Platform base, such as initial user air drop, referral bonuses and holding fees.
+ * Rewards and Incentives
-     * Currently: We are using a CIC by the name of Sarafu that is backed by Grassroots Economics' (donor funds). Users get a Sarafu for free and groups will be able to create their own CICs by pulling the xDAI out of Sarafu
+     * Currently: These incentive systems are manual, such as initial user air drop, referral bonuses and holding fees.
-     * Goal: Any org developing a CIC can easily establish various rules and policies
+     * Currently: We are using a CIC by the name of Sarafu that is not backed by anything. Users get a Sarafu for free and groups will be able to create their own CICs backed by local goods and services and connect to eachother.
+     * Goal: Any org developing a CIC can easily establish various rules and policies - these should be built into the token contracts.
  * Training Materials:
-   * Currently: We are developing curriculum, games and materials for training communities and CIC issuers 
+   * Currently: We have minimal documentation curriculum, games and materials for training communities and CIC issuers 
-    
+   * Goal: Better curriculum and verious multi-media materials
- 

TransactionDatasets.md

@@ -1,30 +1,36 @@
 # TransactionDatasets
-Data Sets from Blockchain Transactions and User Demographics found at 
+Data Sets from Blockchain Transactions and User Meta Data found at 
 [grassecon.org/research](http://grassecon.org/research) in csv format and also shown on [dashboard.sarafu.network](https://dashboard.sarafu.network)
 
 Datasets prior to 2020 are pulled from the POA blockchain for each user ex. https://blockscout.com/poa/core/address/0xcb55fc893000a984a5ad73011f93d1540a5f0895/tokens
 As well as user generated data and field surveys collected in Kenya. Fields described below.
 
-Datasets Starting 2020 are pulled from the POA (xDAI) blockchain for each user ex. https://blockscout.com/poa/core/address/0xcb55fc893000a984a5ad73011f93d1540a5f0895/tokens
+Datasets Starting 2020 are pulled from the xDAI blockchain for each user ex. https://blockscout.com/poa/core/address/0xcb55fc893000a984a5ad73011f93d1540a5f0895/tokens
 As well as user generated data and field surveys collected in Kenya. Fields described below.
 
-Brief description: Using a simple feature phone interface with USSD each user (people living below the poverty line in Kenya) starts with 400 Tokens and adverstises what they sell on a digital market place avalaible on the same interface. There are no transaction fees. The tokens are used often as a top-up to missing Kenyan shillings. Certian users / vendors were allowed to send 50% of their tokens to Grassroots Economics (GE) in return for Kenyan Shillings on a monthly basis (see Agent transactions). Each user only has one token assigned to them by GE based on where they live (Currently we have moved all users to the Sarafu token while we prepare for the next phase). When a user sends a token to another user that holds a different token a conversion is made automatically after receipt. This conversion uses a bonding curve (based on the Bancor Protocol) to adjust the token prices relative to eachother. Conversions can be seen as transactions to a contract address then that contract address sending the new token to the user. While the exchange rate information is avaliable to users, practially all the tokens are curently considered ~1:1 with the national currency as well as with eachother. For more information please contact us https://www.grassrootseconomics.org/contact
+**Brief description:** 
+Using a simple feature phone interface with USSD each user (people living below the poverty line in Kenya) starts with an allottment of initial tokens and adverstises what they sell to neighbors and on a digital market place avalaible on the same interface (USSD). There are no transaction fees. The tokens are used often as a top-up to missing Kenyan shillings.   <br />
+**Pre 2020** - each user only has one token assigned to them by GE based on where they live.   <br />
+**Post 2020** - all users moved to the Sarafu token while we prepare for user generated tokens again.   <br /> 
+**Pre 2020 with multiple tokens** - When a user sends a token to another user that holds a different token a conversion is made automatically after receipt. This conversion uses a bonding curve (based on the Bancor Protocol) to adjust the token prices relative to each other. Conversions can be seen as transactions to a contract address then that contract address sending the new token to the user.   <br />
+In 2020 the Sarafu token which all users held is considered ~1:1 with the national currency.   <br />
+For more information please contact us https://www.grassrootseconomics.org/contact
 
 
 --------
 
-Post 2020 xDAI data (current)
+# Post 2020 xDAI data (current)
 The Transaction csv fields:
 
 1. id - internal transaction ID number
 1. timeset - date and time of transaction
-1. transfer_subtype - internal typing: DISBURSMENT = from Grassroots Economics, RECLAMATION = Back to GE, STANDARD =  a trade between users, AGENT = when a group account is cashing out (see held_roles) below
+1. transfer_subtype - internal typing: 
-1. transfer_use - The category the sender marked the transaction as - used for 'confidence' later for the user category - note this will be changed to boolean
+     -  DISBURSMENT = from Grassroots Economics Foundation, 
-1. tx_hash - hashed transaction address on blockchain (not currently shown)
+     -  RECLAMATION = Back to GE, 
+     -  STANDARD =  a trade between users, 
+     -  AGENT = when a group account is cashing out (see held_roles) below
 1. source - wallet ID of sender 
-1. s_comm_tkn - Short name of Token that the source uses (each user should only have 1 token) - note that currently all users have Sarafu only
 1. target - wallet ID of recipent 
-1. t_comm_tkn
 1. token_name - the token that was traded
 1. token_address - the blockchain address of token that was traded
 1. weight - How many tokens were traded
@@ -32,33 +38,39 @@ The Transaction csv fields:
 The user summary csv fields:
 
 1. id - Internal user id number
+1. start - day and time of first transaction (when the user account was setup)
 1. xDAI_blockchain_address - Wallet ID on POA xDAI Blockchain 
-1. old_POA__blockchain_address - Wallet ID on POA Blockchain if they had one
+1. old_POA__blockchain_address - Wallet ID on the older POA Blockchain (pre 2020) if they had one
-1. comm_tkn - Their token name (each user only has 1 token) currenlty only Sarafu
+1. final_bal - current balance of Sarafu as of file date
-1. bal - current balance of [comm_tkn] as of file date
+1. area_name - Regional area in Kenya (generalized from private user data)
-1. location_path - The smallest to largest region names on Open Street Maps for that users physical location
+1. area_type - Rural, Peri urban or Urban (generalized from private user data)
-1. location_lat - The smallest region latitude
+1. held_roles - 
-1. location_lon - The smallest region longitude
+    - BENEFICIARY, standard user / standard transactions
-1. held_roles - Standard transactions are between Beneficiaries, anything to an Admin is a Reclemation or from and Admin is a Disbursment and anything to a Agent is a Agent_out
+    - GROUP_ACCOUNT, local savings and loans groups (Chamas) 
+    - ADMIN, account of Grassroots Economics staff 
+    - TOKEN_AGENT, account used to cash out tokens to Mpesa
+    - VENDOR - to be deleted
 1. gender - user input gender
 1. business_type - Input by GE staff based on what the users sell
+
+**Additional User Statistics:**
 1. ovol_in - total number of tokens that came into this account from non-STANDARD transactions
-1. ovol_out
+1. ovol_out - total number of tokens that left this account from non-STANDARD transactions
 1. otxns_in - number of transactions incomming from non-STANDARD transactions
 1. otxns_out
 1. ounique_in - number of uniquie transactions incomming from non-STANDARD transactions
-1. ounique_in
+1. ounique_out
 1. svol_in - total number of tokens that came into this account from STANDARD transactions
 1. svol_out
 1. stxns_in - number of transactions incomming from STANDARD transactions
 1. stxns_out
 1. sunique_in - number of uniquie transactions incomming from STANDARD transactions
-1. sunique_in
+1. sunique_out
-1. start - day and time of first transaction (when the user account was setup)
 
-----
 
-Pre 2020 POA
+-----------------------------------------------------------------------------------------
+
+# Pre 2020 POA
 The Transaction csv fields:
 1. timeset - date and time of transaction
 1. tx_hash - hashed transaction on blockchain can be found on https://blockscout.com/poa/core/a
@@ -87,6 +99,8 @@ The user summary csv fields:
 1. gender
 1. business_type - Input by staff based on what they sell
 1. directory - input by user a specific item they sell
+
+**Additional User Statistics:**
 1. vol_trans_in - total number of tokens that came into this account
 1. vol_trans_out
 1. n_trans_in - number of transactions incomming

cic-charter.md

@@ -0,0 +1,154 @@
+# CIC Commons Charter
+
+## Vision
+The Community Inclusion Currency (CIC) Commons sees a world where communities are in control of their own currency technology as an essential ingredient for economic liberty and empowerment.
+
+## Mission
+
+The CIC Commons presents a collection of tools to create community inclusion currencies, and to enable interactions between any community created currency and blockchain technologies. The CIC Commons enables people to choose and implement software that is flexible to meet their needs and comprehension. Communities can use these tools to create currencies on different blockchain technologies and networks. In turn, they use these tools and networks to create their own applications and services that provide, connect, serve and protect the currencies they have created.
+
+## How
+
+- Identify and define concepts that are common across the bulk of existing cryptocurrency and community currency technologies
+- Turn these concepts into low-cost, highly available, blockchain agnostic tooling for CIC creation
+- Contribute to node infrastructure that can be run on any devices, especially low-end ones
+- Counteract centralization of blockchain node infrastructure by making nodes as localized as possible
+- Treat technology implementers as contributors not just consumers
+- Reduce the cost of moving a currency systems between technologies
+- Improve on the privacy properties of cash in digital currency transactions
+- Create a global knowledge base of community currency implementations and best practices
+- Ensure that any software services are not monopolized and that communities are empowered to run their own services
+
+## Community Statement
+The CIC Commons is an open group that identifies key roles that make up the community: software engineers, practitioners, community groups, field & support engineers, designers and artists, system administrators, web designers, writers, speakers, translators, volunteers and more.Organizations such as [Grassroots Economics Foundation](http://grassecon.org) identify employees and community bounty programs to support the CIC Commons based on avalible funding from grants. Community members are extreemly important to the CIC commons as they are the commons - your imput and support is needed to make these tools useful.
+
+### Elinor Östrom’s Commons Governance Rules. 
+ 1. Who is part of the CIC Commons and who is not? What are the rules for joining? (Define clear group boundaries.)
+	1. Anyone that wants to contribute to CIC Software, learnings, best practics, research implementation is welcome 
+ 1. Are the rules governing the CIC Commons and usage appropriate? (Match rules governing groups and the use of community resources to local needs and conditions.)
+    1. Currently only a few lead architects approve pull requests and merges. They have been assigned by Grassroots Economics Foundation so far but are in the process of self defining and establishing rules for self-governance.
+ 1. Who can participate in modifying those rules? (Ensure that those affected by the rules can participate in modifying the rules.)
+    1. To be developed. Anyone can discuss the rules for modifying the software or fork the code base. 
+ 1. How are CIC Commons rules legitimate outside the community or group creating them? (Make sure the rule-making rights of the community members are respected by outside authorities.)
+    1. CIC Implementers like Grassroots Economics Foundation are supported to ensure security and as much legal compliance as is possible.
+ 1. How are CIC Commons member behaviours and rule compliance monitored? (Develop a system, carried out by the community to monitor member’s behaviour such as trade balance.)
+    1. Software modififications are required to have oversight and pass test coverage.
+ 1. How are disputes resolved in the community? (Provide accessible low-cost means for dispute resolution.)
+    1. To be developed
+ 1. What kind of governance layers are there for maintaining the CIC Commons? (Build responsibility for governing the common resource in nested tiers from the base level to the entire ecosystem.)
+    1. To be developed
+
+## CIC Summary
+CIC is a custodial wallet and blockchain bidirectional interface engine for community inclusion currencies
+
+- Fully Open source GPL 3.0 License
+- Automates the full lifecycle of blockchain transactions
+- Chain agnostic by design
+- Introduces a new chain library toolset written from scratch
+- Modular design with fully standalone but recombinable components
+- Includes a broad collection CLI tools for most common chain and engine operations
+- Empowers implementers to choose their level of abstraction
+- Supports both local, containerized and decentralized environments
+- Support last mile front-end apis and integrations
+
+## System parts
+
+- **Base components**, containing all necessary provisions for services and tooling. ([Chaintools](https://gitlab.com/chaintool))
+- **Generic services components**, libraries, daemons and services making up the custodial engine. ([cicnet](https://gitlab.com/chaintool))
+- **Deployment components**, which facilitates deployment of the custodial engine, as well as seeding data for development, demonstration and migration. ([GrassrootsEconomics](https://gitlab.com/grassrootseconomics/)) 
+
+
+### Base components
+
+- **Queue handling** ([chainqueue](https://gitlab.com/chaintool/chainqueue)): Makes sure that a transaction sent on behalf of a user is sent, resubmitted if stalled, and whose execution is verified by quering the network state. 
+- **Chain syncing**, ([chainsyncer](https://gitlab.com/chaintool/chainsyncer)): Retrieves all state changes from the network and executes an arbitary number of code fragments per transaction. 
+- **RPC (Remote Procedure Call) interface**, which divides in two parts:
+	1. **Generic interface** ([chainlib](https://gitlab.com/chaintool/chainlib)): Concepts common to all chain-like RPCs, and provides a thread-safe interaction framework.
+	1. **Ethereum interface** ([chainlib-eth](https://gitlab.com/chaintool/chainlib-eth)): An extension of the former for the Ethereum/EVM network.
+- **Chain tooling** ([chainlib](https://gitlab.com/chaintool/chainlib), [chainlib-eth](https://gitlab.com/chaintool/chainlib-eth)): Granular access to all conceptual layers of chain interaction, including binary serializations and application interfaces, along with CLI (Command Line Interface) tooling framework.
+- **Signer**, ([crypto-dev-signer](https://gitlab.com/chaintool/crypto-dev-signer)) Low-security keystore and signer which is easily usable in both production (provided that no external access is possible) and in any development environment.
+- **Configuration** ([confini](https://gitlab.com/nolash/python-confini)): Incrementally merging configuration definition from multiple modules, and easily overriding them with command line flags and environment variables.
+
+
+### Generic services components
+
+- All smart contract wrappers in the [cicnet](https://gitlab.com/cicnet) repository.
+- **CIC Contract registry** ([cic-eth-registry](https://gitlab.com/grassrootseconomics/cic-eth-registry)): Defines token and resource pointer lookup and authentication resources.
+- Daemons and microservices in the **apps** subdirectories in the [cic-internal-integration](https://gitlab.com/grassrootseconomics/cic-internal-integration) monorepo, specifically:
+	* **cic-eth**: Massively parallell and fault-tolerant implementation of the custodial signer/queuer/syncer engine, accepting tasks from end-users via middleware.
+	* **cic-cache**: Cache syncer and database fetching and storing details on transactions of interest.
+	* **cic-ussd**: State machine, microservices and gateway for end-users using the USSD (Unstructured Supplementary Service Data) interface via telcos.
+	* **cic-notify**: Pluggable notification engine, initially used only for SMS notifications to end-users.
+
+
+### Deployment components
+
+- Data seeding and/or migrations for new development deployments. Located in the **apps/data-seeding** subdirectory of [cic-internal-integration](https://gitlab.com/grassrootseconomics/cic-internal-integration).
+- Deployment and initialization of network resources (smart contracts etc) and initialization of the custodial engine. Located in the **apps/contract-migrations** subdirectory of [cic-internal-integration](https://gitlab.com/grassrootseconomics/cic-internal-integration).
+
+
+## Design principles
+
+The guiding principles for this new system are described as subsections below.
+
+
+### Massively scalable
+
+The queueing and syncing engine should be able to queue and sync state change requests and state queries to the full capacity of the integrated networks, without any loss of data and with minimum middleware latency for the end-user.
+
+
+### Avoid lock-ins
+
+.. whether by opacity, complexity or license terms.
+
+No part of the system should rely on and/or integrate with libraries or services that cannot be reasonably understood and/or adapted.
+
+Nor should the work required to replace a component be unreasonable large as a result of external dependencies.
+
+It should also be straightforward for services implementers to choose their own services dependencies (like chains, chain nodes, SaaS deferrals etc).
+
+
+### Lean dependency graph
+
+The base components should make use of primitives and standard libraries as much as possible.
+
+The services components written for Grassroots Economics specifically should only rely on generic base components.
+
+
+### Network state as the source of truth
+
+Changes to state is sent to network immediately.
+
+State queries made through the engine always retrieve state from network before being adjusted.
+
+
+### Split engine into reusable modules
+
+Which in essence is practical implementation of the "system parts" chapter below.
+
+
+### No soft lock-in to virtual environments
+
+Too many modern software projects only provides reasonable ease of use through mechanisms like Docker or similar frameworks.
+
+Care should be taken to incur minimum penalty for using the application and tooling in a local host environment.
+
+Documentation must exist and be maintained to facilitate this.
+
+Furthermore, there should exist local-only alternate services of the underlying base components. Example of this is the [chaind](https://gitlab.com/chaintool/chaind) / [chaind-eth](https://gitlab.com/chaintool/chaind-eth) pair which enables queue/sync dynamics in a local services (e.g. systemd) environment for an independent wallet.
+
+
+### Coherent configurations regardless of entry-point
+
+Merged ini-format configuration files constitue configuration schemas and overrides, translating to a configuration directive vocabulary overrideable by environment variables of the same name.
+
+
+### CLI tooling framework
+
+Layered definitions of command line arguments, so that concepts common for each layer is only defined in one place.
+
+Full and intuitive control of overriding configuration directives with command line arguments and flags.
+
+Easy generation of base resource objects (such as rpc, wallet) directly from rendered configurations.
+
+Faciliate and encourage use of chainable commands (e.g. UNIX pipelines).

misc-commands.md

@@ -1 +1,79 @@
+# Environment
+deploy contracts
+set up system accounts
+throw some gas and tokens around for system accounts
+start all services
+
+git clone https://gitlab.com/grassrootseconomics/cic-internal-integration/
+
+sudo RUN_MASK=3 COMPOSE_DOCKER_CLI_BUILD=1 DOCKER_BUILDKIT=1 DEV_FAUCET_AMOUNT=100000000 TOKEN_TYPE=erc20_demurrage_token CIC_DEFAULT_TOKEN_SYMBOL=SARAFU docker-compose up --build
+that should set you up, and then you need to determine when the setup is done by running:
+
+sudo docker logs -f cic-internal-integration_contract-migration_1
+when that logs exits, you're good
+
+# Create users
+https://gitlab.com/grassrootseconomics/cic-internal-integration/-/tree/lash/migration-fix/apps/data-seeding#alternative-3-ussd-import-cic_ussd
+
+
+# Token Creation
+
 git clone https://gitlab.com/nolash/grassroots-app
+
+
+## Setup:
+sudo docker-compose down -v
+
+sudo RUN_MASK=3 COMPOSE_DOCKER_CLI_BUILD=1 DOCKER_BUILDKIT=1 DEV_FAUCET_AMOUNT=100000000 TOKEN_TYPE=erc20_demurrage_token CIC_DEFAULT_TOKEN_SYMBOL=SARAFU docker-compose up --build
+
+sudo RUN_MASK=3 docker-compose up –build
+
+## Deploy token
+erc20-demurrage-token-deploy –help
+
+(venv) wor@gecon:~/src/ge/erc20-demurrage-token/python$ PYTHONPATH=. python erc20_demurrage_token/runnable/deploy.py -p http://localhost:63545 -y /home/wor/src/ge/cic-internal-integration/apps/contract-migration/keystore/UTC--2021-01-08T17-18-44.521011372Z--eb3907ecad74a0013c259d5874ae7f22dcbcc95c -i evm:bloxberg:8996 --name "Chama Token" --symbol "CHM" -vv -ww -c config --supply-limit 1000000
+
+(venv) wor@gecon:~/src/ge/erc20-demurrage-token/python$ eth-get -p http://localhost:63545 0xcf38135da34784a9db226772dcf740089f466241ba82ab4a2f4b5265fcb23a4d 
+
+
+giftable-token-gift -p http://localhost:63545 -y ./keystore/UTC--2021-01-08T17-18-44.521011372Z--eb3907ecad74a0013c259d5874ae7f22dcbcc95c -i evm:bloxberg:8996 -vv -w -a <token_address> --recipient <recipient_address> <amount>
+
+giftable-token-gift -p http://localhost:63545  -y /home/wor/src/ge/cic-internal-integration/apps/contract-migration/keystore/UTC--2021-01-08T17-18-44.521011372Z--eb3907ecad74a0013c259d5874ae7f22dcbcc95c -i evm:bloxberg:8996 -vv -w -a 0x6ca3cb14aa6f761712e1c18646afba4d5ae249e8 100
+
+
+(venv) wor@gecon:~/src/ge/erc20-demurrage-token/python$ erc20-balance -p http://localhost:63545 -a 0x6Ca3cB14aA6F761712E1C18646AfBA4d5Ae249E8 0xEb3907eCad74a0013c259D5874AE7f22DcBcC95C
+Chama Token (CHM): 0.000100
+
+# Batch Transactions
+from: https://gitlab.com/chaintool/chaind-eth/-/tree/lash/sendscript
+
+1. Start or connect to your node: sudo docker-compose up eth  
+1. Contract Migration: sudo COMPOSE_DOCKER_CLI_BUILD=1 DOCKER_BUILDKIT=1 RUN_MASK=1 docker-compose up --build contract-migration
+git clone https://gitlab.com/chaintool/chaind
+cd chaind
+python -m venv .venv
+. .venv/bin/activate
+pip install --extra-index-url https://pip.grassrootseconomics.net:8433 -r requirements.txt
+# the following will set up your database in ~/.local/share/chaind/eth/chaind.sqlite
+PYTHONPATH=. CHAIND_DOMAIN=eth DATABASE_ENGINE=sqlite python scripts/migrate.py #creates the db for the querer syncer and chaind
+
+
+1. Create a file:
+set +a
+export DATABASE_ENGINE=sqlite
+export RPC_PROVIDER=http://localhost:63545
+export RPC_HTTP_PROVIDER=http://localhost:63545
+export CHAIN_SPEC=evm:bloxberg:8996
+set -a 
+
+1. Start: chaind-eth-server --session-id testsession -vv
+1. Start syncer: chaind-eth-syncer
+#testing key file with no password
+echo
+{"address":"eb3907ecad74a0013c259d5874ae7f22dcbcc95c","crypto":{"cipher":"aes-128-ctr","ciphertext":"b0f70a8af4071faff2267374e2423cbc7a71012096fd2215866d8de7445cc215","cipherparams":{"iv":"9ac89383a7793226446dcb7e1b45cdf3"},"kdf":"scrypt","kdfparams":{"dklen":32,"n":262144,"p":1,"r":8,"salt":"299f7b5df1d08a0a7b7f9c9eb44fe4798683b78da3513fcf9603fd913ab3336f"},"mac":"6f4ed36c11345a9a48353cd2f93f1f92958c96df15f3112a192bc994250e8d03"},"id":"61a9dd88-24a9-495c-9a51-152bd1bfaa5b","version":3}
+> test.json
+export WALLET_KEY_FILE=test.json
+
+#address of the registry for token index (on my computer)
+eth-token-index-list -e 0xa579d6AbE59a87f5b23f674cD4967A55754A0864 
+

roadmap.md

@@ -0,0 +1,37 @@
+# Misc Tech
+1. SaaS systems – deployment templates
+1. Humanitarian Chain
+1. Migration to tendermint (cosmos)
+1. Impact Claim (NFTs) creation
+1. Zero Knowledge Proofs (anon txns)
+1. Decentralized Data Storage (Swarm)
+1. Simulation & Modeling (Training & Prediction)
+1. Security / Tech Audits
+1. Token (CIC) Creation DAO
+1. CIC usage (Fund/tax (re)allocation) DAO
+
+# UX
+1. Custodial USSD 
+1. Custodial Front end (Telegram/Discord)
+1. Custodial Front end (Web)
+1. Non-Custodial Wallet
+1. Market Place (products) Directory
+1. Impact Claim (NFT) Market Place
+1. Data explorers (Dashboards / Reporting)
+1. Social Password Recovery
+
+# Scaling
+1. Scaling Plan
+1. Operations / Managment
+1. Community Management
+1. Tech training (on boarding)
+1. Implementation Training (Field / Client onboarding)
+1. CIC Creation Agreement (text)
+1. Library/Docs Coordination (packaging/searchable)
+
+# Partnerships (Decentralized Utility)
+1. Mesh Networks
+1. IoT / Tokenization
+1. Foundational Utilities
+1. Infrastructure
+1. Agro Forestry / Carbon

spec/001_platform_incentives.md

@@ -4,41 +4,22 @@
 valid status values are: Pre-draft|Draft|Proposal|Accepted
 -->
 * Authors: Will Ruddick <willruddick@gmail.com> (grassecon.org)
-* Date: 2020.04.22
+* Date: 2021.02.23
 * Version: 1
 * Status: Pre-draft
 
 ## Rationale
-The current system seeks to maximize circulation in order to fill market gaps and help CIC users to support eachother.
+The current Sarafu system seeks to maximize circulation in order to fill market gaps and help CIC users to support eachother.
 
 ## Currently - bonding CIC issuance to a reserve with no market value.
-Grassroots Economics created a pool of 16 Million Sarafu tokens (which they value 1:1 with Kenyan Shillings ala buy backs - see below). 
+Grassroots Economics created a pool of 16 Million Sarafu tokens (which they value 1:1 with Kenyan Shillings ala buy-backs - see below). 
-Of which 60% will have been distributed to users as below by mid May 2020. 
+The following are all rules are platform (statemachine) based (not blockchain contract based). Note that these rules are for the Sarafu CIC only and are not meant to be the rules for other CIC creators.
-The following are all rules are platform based (not blockchain contract based). Note that these rules are for the Sarafu CIC only and are not meant to be the rules for other CIC creators.
 1. Outgoing Sarafu
-   1. **airdrop-selfservice**: New users get 50 Sarafu (a CIC) (Shown as Disbursement in database)
+   1. **airdrop-full-profile**: New users that have filled out their profiles (name, business, location, gender) get 100 Sarafu (Shown as Disbursement in database)
-   1. **airdrop-full-profile**: New users that have traded outward and fill out their profiles (name, business, location, gender) get additional 350 Sarafu (a CIC)  (Shown as Disbursement in database)
+   1. **usage reward**: Users get weekly Sarafu bonues if they have made any trade  that week.(Shown as Disbursement in database (transaction meta-data)) - this is a redistribution of the demurrage amount
-   1. **referral**: Users that are the 1st to send a new user at least 20 tokens get 100 Sarafu - after that new user has begun to trade with another user (not the referrer) (Shown as Disbursement in database)
-   1. **chama bonus**: Savings Groups (aka Chamas are groups of users that save and give loans to eachother) get 10,000 Sarafu divided between their members after 2 months of trading (done by office manually).(Shown as Disbursement in database)
-   1. **basic income / usage bonus**: Users get a daily or weekly Sarafu bonues depending on how they trade. They are ranked by the number of other people they trade above 20 Sarafu with and awarded based on their percentage of such overall trade. (Possibly moving to k-cycle centrality).(Shown as Disbursement in database)
-   1. **donation bonues** Anyone with Mpesa or Bonga points (National Currency eMoney) can send them to Grassroots Economics to receive additional Sarafu (Shown as Disbursement in database) Donors can give Grassroots Economics funds to support the Sarafu buy-back and operations
 1. Incomming Sarafu 
-   1. **holding Fee**: If an account if dormant (no trades in or out) for 30 days 100 Sarafu are deducted and added back to the pool. (Shown as Reclaimation in database)
+   1.  **holding fee/demurrage**: Users get a monthly deduction of 2% of their Sarafu balance - which is added to the user reward pool.  (Shown as Reclaimation in database). 
-   1. **chama redemption**: Savings Groups can redeem 50% of their Sarafu balance for Kenyan Shillings up to a maximum of 30k Sarafu each month but must have spent (and/or given loans) of at least as much as they want to cash out. (Shown as Agent_out in database) Cashing out is done using donor funds by Grassroots Economics Foundation and Sarafu is valued 1:1 with Kenyan shilligns using eMoney (Mpesa).
+   1. **minting/creating**: 100 Sarafu is minted (supply increase) when new users join and are validated
-   1. **minting/creating**: Currently the Sarafu supply is bonded to a virtual reserve token with no market value so there are no restrictions on the supply of Sarafu
-
-## After - bonding to a reserve is market value.
-After the migration to xDAI as reserve - see [migration spec](https://gitlab.com/grassrootseconomics/cic-docs/-/blob/master/spec/002_xdai_migration.md).
-anyone (with access to blockchain) in the world can contribute reserve in the form of xDAI. xDAI is a stable token to the US dollar and can be purchased with USD. 
-With a reserve in xDAI each Sarafu token will now have spot price or excahnge price to xDAI given by P = R/(S*TRR)
-Where R = the amount of xDAI in reserve, S= the total supply of Sarafu, and TRR = Target Reserve Ratio = that ratio of R/S such that the echange price is 1:1.
-1. **Off chain incentives** - Grassroots Economics will continue with all the above incentives for Sarafu and to buy the vouchers off on a regular basis 1:1 from Savings groups.
-1. **Adding Reserve off bonding curve - depth bump** - Donors can choose to increase the reserve amount and mint tokens without chaning the excahnge price - see [Depth Bump SPec](https://gitlab.com/grassrootseconomics/cic-docs/-/blob/master/spec/003_depth_bump.md)
-1. **Adding Reserve via bonding curve** - Anyone with access to the blockchain (via a webApp or MetaMask) can add xDAI and mint more Sarafu (+) increase the value of all Sarafu
-  1. As the reserve of Sarafu is depleted and the exchange price drops Grassroots Economics as well as other donors will add more reserve and mint more tokens to distribute.
-1. **Liquidating CICs** - Anyone with access to the blockchain (via a webApp or MetaMask) can add send Sarafu to the converter contract to destroy it and withdraw reserve (-) decreasing the value of all Sarafu.
-  1. **Usage of on-chain reserves** - Grassroots Economics will liquidate Sarafu it collects to pull out excess reserve and convert it (xDAI) to Kenyan shillings to continue with Savings Group buy backs.
-1. **Conversion fee** - A % fee on conversion between reserve and supply in both directions (minting or liquidating tokens) is done on blockchain and added to the reserve.
 
 
 ## Implementation

spec/002_dai_reserve_migration.md

@@ -6,7 +6,7 @@ valid status values are: Pre-draft
 * Authors: Will Ruddick <will@grassecon.org>
 * Date: 2020.04.22
 * Version: 1
-* Status: Pre-draft
+* Status: Depricated
 
 ## Rationale
 We want to give donors and community members a way to contribute to and cash-out from Community Inclusion Currencies with National Currency. 

spec/004_Platform_Roles.md

@@ -1,4 +1,3 @@
-
 # Public View Only
 
 1. View public data only and no ability to edit
@@ -14,9 +13,10 @@ Private data inlcudes, names, phone numbers, location
 1. See private data
 1. Add users
 1. Edit user fields
-1. Pin reset
+1. Pin reset (in future this will need admin approval)
-1. Initial Disbursement only (1 time per user with a max of 400)
+1. Initial Disbursement only (1 time per user with a max of 350)
 1. Disbursement (besides initial) and reclamation (with approval of Admin)
+1. Reversal (with approval of Admin)
 
 # Admin
 
@@ -24,12 +24,12 @@ Private data inlcudes, names, phone numbers, location
 1. Add users
 1. Edit user fields
 1. Pin reset
-1. Disbursement and reclamation (without approval)
+1. Disbursement and reclamation and Reversal (without approval)
 1. Give approval to Enrollers
 
 # Super Admin
 
-1. Assign the roles (Suber Admin, Enroller, View Only)
+1. Assign the roles (Super Admin, Enroller, View Only)
 1. See private data
 1. Add users
 1. Edit user fields

spec/007_eMoney_integration.md

@@ -1,75 +1,53 @@
-## Incoming Sarafu ##
+## Notes ##
-When users exchange CIC <> National Currency we have to manually send them Mpesa or CIC.
+Users have no way to automate the excahnge of CIC <> National Currency. Can people be encouraged to be liquidity providers and develop pools containing CIC and National Currency or other token? Creating a on-chain liquidity pool still requires on and off-boarding crypto to fiat.
-We would like to automate this.
+
 
 ## Solution ##
-Configure - using our own system AfricasTalking API to automatically send CIC / Mpesa based on rules:
+Using AfricasTalking API to automatically send Mpesa from a business account when CIC is received (Blockchain account triggered):
+Using RPC endpoints and contract calls to automatically send CIC when KSH is received (MPesa call back triggered)
+
+A liquidity pool can be created off-chain where a liquidity provider simply monitors two (float) accounts one of CIC and another of Mpesa.
+
 - CIC - > Mpesa 
-   - CICs are converted to reserve on-chain and the xDAI is held in a GE account (xDAI Float)
+   - CICs are added to the float account account triggering Mpesa to be released from the mpesa (float)
-   - We send back an equivalent amount of Mpesa to the user from out MPESA float account
+   - We send back an amount of Mpesa to the user from out MPESA float account (this amount can be based on a bonding curve)
 - Mpesa -> CIC
    - Mpesa are added to our float Mpesa account.
-   - xDAI from our xDAI float account is added to the reserve of the CIC (Home CIC of the user) and new CICs are minted and sent to the user
+   - CIC from our Sarafu float account is sent to the user (this amount can be based on a bonding curve)
 
 
-### Variables ###
+### Variables for excahnge rates ###
- - blockchain_CIC_Supply = the total supply of the CIC on the blockchain
+ - float_CIC_Supply = the total supply of the CIC on the float account
- - blockchain_CIC_reserve = the total reserve (xDAI) of the CIC on the blockchain
+ - float_CIC_reserve = the total supply of Mpesa in the float account
- - trr = the connector weight on blockchain converter between supply and reserve
+ - trr = the connector weight on blockchain converter between supply and reserve (assuming 50%)
- - FLoat xDAI: THe amount of xDAI we have in our master wallet
+ - CIC_excahnge_amount = the amount of CIC the user has sent to exhange for Mpesa
- - FLoat Mpesa: THe amount of Mpesa supply we have in our PayBill account
+ - Mpesa_excahnge_amount = the amount of MPesa the user has sent to exhange for CIC
- - CIC_excahnge_amount = the amount of CIC they user has sent to exhange
+ - Rate: CIC -> KSH
- - Mpesa_excahnge_amount = the amount of MPesa the user has sent to exhange
+ - Rate: KSH -> CIC
- - Rate: USD -> KSH
- - Rate: KSH -> USD
  - Fees: Sarafu to Mpesa FeeCC2M = 2%
  - Fees: Sarafu to Mpesa FeeM2CC = 2%
- - The account to which CIC are sent should be a Agent account
+ - Alert on float balance and excahnge rate levels
- - The cash-out rules for a chama (minimum and time limit)
- - Alert balance levels
  
 ### Incoming CIC Rules - MPESA out ###
- - *white list* The chama (group accounts only but eventually anyone) can cash out - note the chama limits
+ The amount of Mpesa given should be calculated as follows:
- - *amount* See KYC_limit max, supply_max
- - *mpesa given* The amount of Mpesa given should be calculated as follows:
  - CIC_excahnge_amount = the amount of CIC the user wants to excahnge
 
-The Reserve (xDAI) to be pulled out (reported):
+Quotation: The Reserve (Mpesa) to be pulled out (reported):
 
-- reserveOut_xDAI_reported = the amount of xDAI that would be pulled from the reserve on-chain (by getting a quote on-chain)
+Assuming a (trr=50%) connector weight:  return (float_CIC_reserve x CIC_exchange_amount ) / (float_CIC_reserve + CIC_excahnge_amount)
-- reserveOut_Mpesa = reserveOut_xDAI_reported **USD => KSH** rate
+- reserveOut_Mpesa_reported = the the above amount of Mpesa that would be pulled from the Mpesa float account minus any fees (FeeM2CC)
-- reserveOut_Mpesa_reported = reserveOut_xDAI_reported **USD => KSH** rate
 
-After the user confirms:
+Note that this should be the minimum amount the user will get - if they confirm (not the max)
-
-The Reserve (xDAI) actually pulled out 
-- reserveOut_xDAI = the amount of xDAI actually pulled from the reserve on-chain
--  **Mpesa_out** = reserveOut_Mpesa_reported (this is actually given to the user) - **and GE takes on the Mpesa risk**
-  -  reserveOut_Mpesa = reserveOut_xDAI **USD => KSH** rate (this is from our MPESA float account)
-  -  Mpesa_risk = Mpesa_out - reserveOut_Mpesa - this should me monitored and recorded for each transactions
 
+After the user confirms the quotation - and executes the conversion: they should get out a minimum of reserveOut_Mpesa_reported
 
 ### Outgoing Sarafu Rules - MPESA In ###
- - *white list* Only users sending via paybill receive Sarafu. Non users receive a invitation to join Sarafu sms (alert to admins there was a donation).
+inverse of the above
- - *amount* The max sarafu out is 20,000 Sarafu per user, KYC_limit max, supply_max
- - *time* No limit
- - *Mpesa_excahnge_amount* The amount of CIC given should be calculated as follows:
- - reserveIn_xDAI = (Mpesa_excahnge_amount - Mpesa_excahnge_amount* fee) **KSH => USD** rate (this will come out of the xDAI float account)
-    
-The CIC to be created (reported for quote): 
-
-  - CIC_Created_reported = the amount of CIC to be created on chain by adding the reserveIn_xDAI (quote from blockchain)
-    
-After the user confirms:
-
-  - CIC_Created = the actualy amount of CIC created on chain by adding the reserveIn_xDAI 
-  - **CIC_given** = CIC_Created_reported
-     -  CIC_risk =  CIC_given - CIC_Created - this should be monitored and recorded for each transaction
  
 ### Exchange Rate ###
 
 When dislaying the SPOT price or excahnge rate to a user we should use the following formula:
-> Exchange Price = CIC_reserve / (CIC_supply * trr) -> this is pulled from blockchain and should be sent back as a SMS
+> Exchange Price = float_CIC_reserve / (float_CIC_supply * trr) -> this is pulled from blockchain and should be sent back as a SMS
 
 
 ### USSD Interface ###

spec/008_Trade_Limits.md

@@ -26,16 +26,10 @@ What is the current state of the described topic?
 How will things be different after this has been done?
 -->
 ### All User Limits
-1. KYC LImits for max amount of trade per week for 
+1. KYC LImits for max amount of outward trade per week for 
-   1. phone verification = 50,000 Tokens
+   1. phone verification and all info filled out = 20,000 Tokens
-   1. ID verification = 100,000 Tokens
+   1. National ID number verification (via api) = 50,000 Tokens
-   1. secondary ID verification = 500,000 Tokens
+   1. Photo of Person and them with National ID = 250,000 Tokens
-
-1. Incentive Limits
-   1. Max exchange to fiat 30,000 tokens
-   1. Max number of excahnges per month = 1
-   1. Min amount of trade before excahnge = amount being cashed out
-   1. Max % of Balance = 50%
 
 
 ## Implementation

spec/010_Web_Wallet.md

@@ -3,34 +3,38 @@
 <!--
 valid status values are: Pre-draft|Draft|Proposal|Accepted
 -->
-* Authors: Gustav Friis
+* Authors: Will Ruddick, Gustav Friis
-* Date: 2020.07.28
+* Date: 2021-april-16, 2020.07.28
-* Version: 0.1
+* Version: 0.2
 * Status: Pre-draft
 
 
 
 ## Purpose
 
-Build a non-custodial wallet infrastructure designed to enable Kenyan end-users to use xDAI and / or Bloxberg blockchain based Community Inclusion Currencies (CICs) from a smartphone and / or desktop.
+Build a non-custodial wallet infrastructure designed to enable Kenyan end-users to use Bloxberg blockchain based Community Inclusion Currencies (CICs) from a smartphone and / or desktop.
 
 ## Target group
 
-Existing or new Kenyan CIC end-users, who are individuals or small businesses using CICs to pay for goods and services. From the user-interviews with B4H we’ve found that these users are certainly not web3 savvy and to a varying degree are web2 savvy either. He/she just wants to interact with his/her wallet funds (displaying balance, paying & receiving) in the community currency (which value let's remember is equivalent to Kenyan Shilling).
+Existing or new Kenyan CIC end-users, who are individuals or small businesses using CICs to pay for goods and services. From the user- in interviews we’ve found that these users are certainly not web3 savvy and to a varying degree are web2 savvy either. He/she just wants to interact with his/her wallet funds (displaying balance, paying & receiving) in the community currency (which value let's remember is equivalent to Kenyan Shilling).
-
-## User-stories
-
 
+## User-stories MVP
 
 - Get directed to web wallet via URL
 
 - Signing up
 
-- Choosing a reference currency
-
 - Displaying balance
 
-- Send payment to known contact
+- Send payment to known contact (via phone number or blockchain address)
+
+- Transaction details
+
+- Transaction history overview
+
+- password recovery - assign a private key custodian?
+
+## User-stories Advanced
 
 - Send payment to unknown receiver (referral link)
 
@@ -44,12 +48,12 @@ Existing or new Kenyan CIC end-users, who are individuals or small businesses us
 
 - Payment notification
 
-- Transaction details
-
-- Transaction history overview
-
 - Cash in and out from CICs to M-Pesa 
 
+- Choosing a reference currency (Eventually not Sarafu)
+
+- Social password recovery
+
 **Settings including**
 
 - Backup wallet
@@ -64,7 +68,7 @@ Existing or new Kenyan CIC end-users, who are individuals or small businesses us
 
 ### Wallet creation
 
-Using BIP39 HD and secp256k1
+??Using BIP39 HD and secp256k1
 
 ### Wallet authentication and recovery
 
@@ -83,8 +87,8 @@ From the Portis Whitepaper allowing SMS / Email / Password authenticated and rec
 ### Interface with the existing Grassroots Economics Platform
 
 
-Existing USSD users
+Existing USSD users (phone to blockchain address mapping)
-Gas fees on xDAI
+Auto top-up of Gas fees on BloxBerg (Bergs)
 AfricasTalking API 
 
 
@@ -115,7 +119,3 @@ Migrate to Gnosis Safe smart-contract wallet
 User facing decentralized exchange
 User facing on-the ground marketplace
 Native implementation of P2P platforms like Mylocalcrypto
-
-
-
-

spec/014_notification_api_extension.md

@@ -0,0 +1,41 @@
+# API EXTENSIONS FOR VIEWING NOTIFICATION DATABASE
+
+
+## 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/sms/` `/api/ext/sms/user/<user_id>/` `/api/ext/sms/<phone_number>/`
+
+#### **GET**
+
+Returns a list of latest sms notifications sent by the platform.
+
+If `user_id` or `phone_number` is given, only entries for the affected user will be returned.
+
+Accepts one query string:
+
+```
+	limit: [uint] - maximum items to return (default: 100)
+```
+
+Response payload:
+
+```
+[
+	{
+		datetime: <string>,
+		number: <string>,
+		message: <string>,	
+	},
+	...
+]
+```

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)
+-->
+

spec/018_Mgmt Platform Spec.md

@@ -0,0 +1,76 @@
+# CIC Management Platform Spec
+
+This document describes the components and steps involved to create a CIC management platform.
+
+## TAGS
+
+1. Basic MVP Functions
+   1. Pin Reset. -> eventually USSD/Wallet Social Pin Reset (set friend(s) as guarantors)
+   1. Delete / Cancel users
+   1. Create new users
+   1. Searching for a user (clickable to see trades and other data)
+   1. Change user details, roles (group), locations, default tokens, auto-conversion
+   1. Disburse and reclaim tokens
+   1. Convert tokens
+   1. View transactions for whole system as they come in
+   1. View transaction details of a user (clickable / searchable) lists / dashboard
+   
+2. Advanced
+   1. Assigning admins/viewers ....  permissions roles, phone support / super admin ...  (see spec)
+   1. Send to external wallet address (can be CLI)
+   1. Special tables (sortable for volume, balances, pin reset needs)
+   1. Mpesa integration 
+   1. Airtime integration 
+   1. Airtime integration 
+   1. Donor integration (Donor interfaces)
+   1. Hide PII data from Viewers - In general data protection
+   1. Enable KYC - storage of user data and photos (ID) and limit system usage without proper KYC
+   
+
+
+
+## RATIONALE
+
+Enable the management and customer support personnel of the CIC platform to track platform usage by end users and provide troubleshooting capabilities.
+
+
+## OVERVIEW
+
+The system gives the personnel various functionalities that allow them to be able to view and control the CIC ecosystem.
+They have to be involved in all parts of the user's interaction with the system in order to be able to give timely assistance.
+
+Some functionality enabled by the system are:
+* Register personnel and assign permissions.
+* View all user in the system and be able to create new users.
+* View and change user details, delete users or reset user pin.
+* Disburse and reclaim tokens from users and convert tokens on behalf of users.
+* View all transactions and individual transaction details.
+
+## USER STORIES
+
+* Register personnel - Give an interface for personnel to register (invite only is fine) or sign in if already a user.
+* Assign personnel permissions - A super admin will be able to assign permissions to other personnel based on their clearance level (Viewer | Enroller | Admin | Super Admin) pursuant to the [Platform Roles Spec](https://gitlab.com/grassrootseconomics/cic-docs/-/blob/master/spec/004_Platform_Roles.md).
+* View users - Get all users in the system and filter according to user categories.
+* View user details - View a user's details and all their transactions.
+* Create new users - Add users to the system and set user type - see [Platform Smoke Testing Spec](https://gitlab.com/grassrootseconomics/cic-docs/-/blob/master/spec/005_Platform_Smoke_Testing.md), User Types section.
+* Set user token - Create a token for Chama accounts only (requires admin privileges) or set a user's community token - see [Self Service Token Spec](https://gitlab.com/grassrootseconomics/cic-docs/-/blob/master/spec/006_Self_Service_Token.md), token creation and join token sections.
+* Change user details - Set new details for users such as roles (group), locations, default tokens, auto-conversion, e.t.c.
+* Delete users - Delete or cancel users.
+* Reset user pin - Change a user's pin on request. Eventually the user will be able to set a recovery account with which the pin can be reset from (preferably a friend or family member as a guarantor). 
+* Disburse and reclaim tokens - Disburse tokens to users on registering for the platform, referrals or meeting certain parameters and reclaiming tokens for dormant accounts - see [Platform Incentives Spec](https://gitlab.com/grassrootseconomics/cic-docs/-/blob/master/spec/001_platform_incentives.md).
+* Convert tokens - Convert a user's tokens from one community token to another on request.
+* View transactions - Get all transactions  in the system and filter according to the transaction category.
+* View transaction details - View an individual transaction, and the users who participated in the transaction.
+* Donor interface - A dashboard showing platform usage metadata such as transaction volume and user registration against time. The dashboard will contain public data only.
+* Mpesa integration - Initiate transactions from and to Mpesa allowing for minting of new tokens by adding to the reserve or redemption of tokens for local currency.
+
+   
+### CODE
+
+### SCHEMA
+
+
+### SEMPO PLATFORM INTEGRATION
+
+### RESOURCES
+

spec/019_wallet_soft_limit.md

@@ -0,0 +1,69 @@
+# Soft Balance Limits
+
+<!--
+valid status values are: Pre-draft|Draft|Proposal|Accepted
+-->
+* Authors: Will Ruddick <willruddick@gmail.com> (grassecon.org)
+* Date: 2021.5.29
+* Version: 1
+* Status: Pre-draft
+
+## Rationale
+<!--
+Why are you proposing this?
+-->
+1. Some businesses want to ensure they will nto accept too much of a certian token. We want to remind users to not accept more Sarafu than they are willing to and in some cases enforce this. Hence we want to give them the choice to set their own soft limit of how many of a token (i.e. Sarafu) that they have in their wallet.
+Users are given a default inital limit of 10,000 (after which there will be an error when trying to add more tokens). 
+The user can set this to any nonzero integer - as a profile setting
+1. We also wish to be able to enforce a abalance limit on users - similar to volume limits of old
+
+## Before 
+<!--
+What is the current state of the described topic?
+-->
+1. no ability to set a max balance limit for the active token - some users get encouraged to collect too many tokens.
+
+## After
+<!--
+How will things be different after this has been done?
+-->
+1. ability to set a max balance limit for the Active Token (which can be adjusted). Note that each token can have a differetn balance limit.
+1. This can be set in USSD, CICADA as well as CLI
+
+
+## Implementation
+All transactions going to that wallet in that users Active token should check this Balance Limit.
+If the transaction will cause the reciever to go over their Balance limit on the Active token a message should be sent to both parties.
+Sender "XXX user can't accept more TOKEN_Name please help them spend it"
+Reciever "XXX user tried to send YYY TOKEN_NAME but can't because of your Balance Limit of XXX. To change this limit choose My Profile then Balance Limit.
+<!--
+Here is the description of how these changes should be implemented.
+Please use subheadings to improve readability.
+Some suggestions:
+
+### Workflow
+
+### Variables
+
+### Interface
+-->
+
+
+## USSD Menu
+1. My Profile
+  1. Balance Limit
+    1. Check Balance Limit (Asks pin and show current limit for active token)
+    1. Set Balance Limit (Asks for a non zero integer and a confirmation screen and pin on request)
+
+## Testing
+<!--
+Please describe what test vectors that are required for this implementation
+-->
+
+## Changelog
+<!--
+Please remember to describe every change to this document in the changelog using 
+serial number:
+
+* version 1:
+-->

spec/020_redeemable_certifcate.md

@@ -0,0 +1,89 @@
+# Redeemable Certificate Contract spec
+A generic redeemable certification contract that records certification information as well as forms of evidence and validations (credentials) which  can be interacted with by a marketplaces and redeemers that seek to use the information and or reward the recipient for the certificate. In effect this certificate can act as its own ledgar - and used by marketplace applications that connect clients / rewarders with certificate holders.
+
+We are working with vulnerable communities and individuals to accredit them for noteworthy activities: Supporting their community, working on environmental programs, passing an online course and selling local products. 
+
+#Certificates:
+  * These accreditations or certificates should be self-sovereign (owned by the receiver) deletable and non-transferable and able to be endorsed or validated by individuals and organizations. 
+  * The owner should be able to choose who can read the certificate as they may contain private information and large datasets of credentialing information.
+  * Viewers should be able to support the owner and write their support onto the certificate itself. 
+
+#Marketplace:
+  * Certificate owners could choose to share with a marketplace with the role to aggregate and provide indexes and assessments against them - while allowing for 3rd parties to support certificate holders.
+
+# Example 1 Course Certification (Proof of Action)
+After completing an online course the course creator issues a Certificate to the student and endorses it. 
+The student can accept the certificate by signing it. The student can also delete it. The student can also choose who can see the details of the certificate, which can include credentals, course topics, as well as any txhashes or other data references.
+A optional value in some currency can be placed on the certificate – this can be based on the duration of the course, cost of internet and so on.
+The student may allow certian individuals or marketplaces to view the data (such as private informationa nd credentials) in the certificate. Anyone can redeem the Cert. Say a business offered the student a voucher for their store with a stated value in some currency. If the Student executes an AcceptRedemption the interaction will be appended to the certificate which can be seen by future redeemers and marketplaces.
+
+# Example 2 Product Certification (Merchant Star Ratings)
+A merchant selling shoes creates a certificate claiming he sells shoes and self signs/endorses it and accepts it.
+The merchant can also choose who can see the details of the certificate (or it can be made fully open), which can include where the shoes are made, how, brands etc. as well as any txhashes or other data references.
+A optional value in some currency can be placed on the certificate – this can be the price of the shoes he is selling.
+Anyone can endorse or revoke endorsment on the certificate - these endorsments can be processed for a rating system using in a marketplace. 
+Anyone can redeem the Cert. Say somone buying shoes. Is the merchant executes an AcceptRedemption the interaction will be appended to the certificate which can be seen by future redeemers and marketplaces.
+
+# Usages
+* Personal Data: ex. Certifying that the recipent is a mother.
+* Merchant Data: ex. Endorsing a merchant (start ratings) after purchasing a product.
+* Enviromental Data: ex. Certifying that the recipent is a farmer who is mulching their land or using regnerative practices. Soil quality testing etc.
+* Transactional Data: ex. Certifying that the recipent is paying for school fees. The school could be a validator. If using CIC the transaction hashes themselves could add evidence.
+
+# Schema
+1. Issuer: <wallet address>
+1. Issued to: <wallet address>
+1. Acceptance: <signature of receiver>
+1. Date Issued: 
+1. Viewers: [] (who can access/read the details of the Cert.)
+1. Details: [] (note that no Public Identifying Information (PII) should be here - most data will be on decentralized storage accesibile to those {viewers} with view access given by the owner))
+   1. Link to details/credentials: 
+      1. Info: {description:’’, duration:’’,topics:’’, quality:’’} (non-PII)
+      1. Location: {GPS, Country, Area} (non-PII)
+      1. Transactions: []
+          1. Description of data/transactions
+          1. Hashes: []
+      1. Suggested Value:
+          1. Currency Name
+          1. Currency <contract address>
+          1. Suggested Value (amount of currency specified)
+1. Validations/Endorsments: [] *appendable*
+   1. Validated by
+        1. Name
+        1. Website
+        1. Wallet address
+1. Redemptions/Purchases: [] *appendable*
+   1. Redemption
+        1. Acceptance status
+        1. Name of Redemer
+        1. Website
+        1. Wallet address
+        1. Type: Product, Voucher, Cash, Service
+        1. Description: 
+        1. Currency
+        1. Value
+
+# Contract Functions:
+    * Issue: Anyone can issue a Cert (this specifies all the informaion and the recipient) - note there is no transfer function. Once issued to the reciever (the owner) they can no longer send it to anyone else. 
+    * AcceptCert: The receiver can choose to accept the Certificate 
+    * GiveViewAccess: The owner can assign who can view the certificate details
+    * RevokeViewAccess: The owner can revoke view access
+    * Destroy: The receiver can delete – remove data and send to 0x000
+    * Validate/endorse: Anyone can validate a Cert
+    * Unvalidate/unendorse: Anyone can revoke their endorsement of a Cert
+    * Redeem: Anyone can redeem the cert (note that the certificate stays with the owner)
+    * AcceptRedemption: The receiver can accept a redemption. 
+
+# Marketplace:
+The certificate owner would have to give the market place or anyone access to view their certificate details.
+A market place application should be able to read these certificates and support rating and redemption. 
+Certificates can be aggregated and sorted by type, area, gender and so on. 
+Recipients can go here to choose to delete their certs, share them with others or approve a redemption
+
+# Risks & Questions
+* Someone may potentially recieve many bogus certificates 
+   * these should not be 'accepted' by the receiver and can also be Destroyed.
+   * Validators should also have certifications 
+* Personal Identifying Information written into the Cert is avalible to anyone that can read the Cert.
+   * The reciever can have the option to encrypt the data or parts of the data/details
+   * Zero knowlege proofs... tbt ... even if someone can't access the data for the credentials or certificate information they could validate it exists.

spec/021_manual_token_creation.md

@@ -0,0 +1,91 @@
+# Manual Token Creation spec
+
+<!--
+valid status values are: Pre-draft|Draft|Proposal|Accepted
+-->
+* Authors: Will Ruddick <willruddick@gmail.com> (grassecon.org)
+* Date: 2021.05.11
+* Version: 2
+* Status: Pre-draft
+
+## Rationale
+Enabeling users to create their own tokens is one of the main goals of CICs. This spec goves of the token creation process 
+
+## Intro 
+* Today users only receive Sarafu created by Grassroots Economics
+* This means Users have very little ownership or feel the need to accept or back the token.
+* We want users to be able to create their tokens to create more ownership and diffusion.
+* A CIC primarliy represents the goods and services committed by the Issuer.
+
+## Sarafu Network – Sarafu and New Token Minting – User Flow:
+
+1. Users create a token issuance agreement (for Sarafu or their own token) [(Sarafu Network Application)](https://gitlab.com/grassrootseconomics/cic-docs/-/blob/master/Sarafu_Network_Member_App_-_Draft__en_.pdf)
+2. The token creation application is audited and signed by all parties (paper form)
+3. All users in the agreement dial the USSD code and setup an account (with 0 initial balance for new accounts). If they have existing tokens those will simply stay there in their account. *Note that Users with multiple tokens in their account should have an option to switch their active token to trade the other tokens. (see milti-token-env spec)
+4. GE creates the new token (or mints more Sarafu) and sends it to the users as per the agreement. Also changing their Active token to the new token if one was created.
+5. n.b. Initally conversion between tokens will not be allowed 
+
+## Inputs
+
+1. Signed Membership Application
+1. if not Sarafu
+   1. Accounts (walllet address) of all users in membership application
+   1. Token Long Name - 128 character limit
+   1. Token short name no more than 6 Character - must be unique
+   1. A maximum supply should be set to the token supply.
+   1. Demurrage set to accumulate to 2% a month
+1. Token Supply to be minted
+1. All blockchain wallet addresses in application
+
+
+## Token creation process - Backend Command line and In-Person process
+
+1. Ensure TOKEN_Name is unique
+1. Create / mint the token supply
+1. sarafu-token-deploy 
+1. eth-token-index-add
+1. eth-address-declarator-add
+1. to discover the contract addresses on the network you use:
+   1. eth-contract-registry-list
+1. Put the TOKEN_NAME tokens into the Users wallet (as per agreement)
+1. All members in the agreement should have their active token set to TOKEN_NAME (see multi-token spec)
+
+## Token creation Interface - UX
+
+### Command Line - CLI
+1. Process Inputs on command line
+1. Confirmation please type the token name to proceed
+1. Ability to send specific ammounts of the token to addresses in the agreement (csv)
+
+### CIC Mgmt Platform - GUI
+1. On a user account there should be a button for Create Token - - this required super admin privlages
+2. The next page comes up with the inputs above
+5. Confirmation please type the token name to proceed
+
+
+
+## Testing
+
+## Action items
+
+## Implementation
+
+### Workflow
+
+### Variables
+
+### Interface
+
+
+
+## Security
+1. 
+
+
+## Changelog
+<!--
+Please remember to describe every change to this document in the changelog using 
+serial number:
+
+* version 1:
+-->

spec/022_multi_token_env.md

@@ -0,0 +1,110 @@
+# Multi Token Environment (Vouchers Menu)
+
+<!--
+valid status values are: Pre-draft|Draft|Proposal|Accepted
+-->
+* Authors: Will Ruddick <willruddick@gmail.com> (grassecon.org)
+* Date: 2021.05.29
+* Version: 1
+* Status: Pre-draft
+
+## Rationale
+Enabeling users to hold and trade multiple tokens- will allows various chamas and token issuers to be connected to eachother as well as other tokens such as rewards.
+
+## Intro 
+* Today users only hold one token aka Sarafu - created by Grassroots Economics. This means that users can't interact with other tokens at all.
+* We want users to create and be able to interact with other CICs and tokens.
+
+## Multi-Token – User Flow:
+
+1. A users is given (via trade or token creation) multiple tokens (These tokens must all be registered on Sarafu Network)
+2. The user should be able to see these tokens and their balances (if non-zero) in a 'My Tokens' Menu item (top level) - as many as possible on USSD with the highest balalances at the top.
+3. The user should be able to switch which token is their Active Token. This will be used for sending, as well as default balance checks and mini statement. 
+
+## USSD Menu: 
+Top level menu item called: Vouchers (Voucha in Kiswahili)
+
+### 1 (advancedmenu)
+Type the symbol for the voucher you want to choose:
+0: Back
+
+#### XYZ
+
+
+### 1 (advancedmenu)
+Choose Voucher: (Chagua Voucha)
+1. Sarafu 100
+2. YOMA 50
+3. Afya 223
+
+0: Back
+
+### 2
+Your voucher will be set to:
+([Token info](https://gitlab.com/grassrootseconomics/cic-docs/-/blob/master/spec/024_token_info.md) for XYZ displayed here) 
+
+Please enter your PIN to confirm: 
+     
+0: Back
+9: Main Menu
+
+### 3
+Success! All transactions will now be in XYZ.
+
+0: Back
+9: Main Menu
+
+
+### Main Menu
+Balance 223 XYZ
+1. Send
+2. Help
+
+
+
+### CICADA Mgmt Platform - GUI
+1. On the user info page you should be able to set their Active Voucher - via a drop down
+1. You should be able to see balances in all the tokens/vouchers they have
+
+## Active Token 
+1. Each user needs to be assigned a default active token/voucher - they start with Sarafu by default.
+
+## (not used)  Accept other Tokens
+1. If this is on and someone attempts to send another token (other than their active token) to that user the sender will recieve an error as well as the reciever similar to the Balance Limit Error https://gitlab.com/grassrootseconomics/cic-docs/-/blob/master/spec/019_wallet_soft_limit.md
+
+## Interfaces - UX
+
+### Command Line - CLI Set Active Token
+1. Inputs: User ID and Name or ID of the token - ensure it is a valid token (ability to batch this with csv)
+
+
+### USSD feature phones - Set Active Token
+- New user dials ussd session code where she selects -) Vouchers
+- Their Voucher sorterd by balances they have in their wallet are shown with an option to select the number of the token they want to choose
+- Confirmation message and entry of pin number to Confirm
+- Future transactions send from this account will try to send that token
+
+## Testing
+
+## Action items
+
+## Implementation
+
+### Workflow
+
+### Variables
+
+### Interface
+
+
+
+## Security
+1. 
+
+## Changelog
+<!--
+Please remember to describe every change to this document in the changelog using 
+serial number:
+
+* version 1:
+-->

spec/023_token_conversion.md

@@ -0,0 +1,100 @@
+# Token Conversion
+
+<!--
+valid status values are: Pre-draft|Draft|Proposal|Accepted
+-->
+* Authors: Will Ruddick <willruddick@gmail.com> (grassecon.org)
+* Date: 2021.05.29
+* Version: 1
+* Status: Pre-draft
+
+## Rationale
+Enabeling users to convert between them various tokens should make usage easier between villages and also out to 3rd party tokens
+
+## Intro 
+* Today users only hold one token aka Sarafu (and eventually they will hold multiple tokens) but they can't convert between them
+* We want users to be able to choose to convert and even auto-convert between various tokens 
+* We also would like supporters to be able to contribute toward liquidity pools to support communities
+
+## Multi-Token – User Flow:
+
+1. A users is given (via trade or token creation) multiple tokens (These tokens must all be registered on Sarafu Network)
+5. Conversion 
+   1. MVP - Initally conversion between tokens will not be allowed (see conversion below)
+   1. If Auto-Convert is selected then all tokens that are able to convert to their Active token will automatically attempt to convert as much as possible to that token. Note that not all tokens will be convertible and conversion in some cases might involve changing rates.
+   1. The office with CICADA can help to convert tokens in future for users.
+
+## USSD Menu
+
+1. My Sarafu (top level)
+   1. Show tokens
+   1. Set Active Token
+   1. Convert Tokens
+   1. Auto-Convert Tokens (on/off) default is off 
+   
+
+## Conversion 
+
+### Manual Conversion
+Note that GE may also act as a manual exchange by holding a supply of several tokens. This would need both CLI and CICADA support.
+
+### Liquidity Pools
+If users want automated conversion between tokens, then a pool must be created. With a supply of any two tokens on the network that they want to convert to – a static (1:1) liquidity pool connecting those tokens will be created with that given supply of each tokens. 
+
+If the amount in the liquidity pool is insufficient for a trade – the sending user will get an error message and not be able to trade. This should also alert the owner of the liquidity pool – and possibly trigger a community process to refill the pool. 
+
+### Conversion User Flow
+User Bob chooses to send 40 B tokens to Sally who has S as her Active token. 
+The system 1st checks to see if there is a liquidity pool (or path between pools) with sufficient supply to 
+give back 40 S ….. if less than 40 S are available (or there is a bonded pool) it will tell Bob the most he can receive (quotation and he could specify the minimum he wants in return to allow an exchange). 
+
+If there is sufficient liquidity in the pool(s) then his 40 B will be added to the pool and 40 S removed and given to Sally. 
+
+## Liquidity pool creation process 
+1. GE holding 2 tokens will add a supply of both to a liquiditiy pool with a 1:1 excahnge rate. 
+1. The pool needs to be added it to the registry
+1. A static pool will/can become empty on one side and will stop to function in that director of conversion
+
+
+## Auto convert
+1. We want to avoid having multiple tokens in user wallets
+1. When a user recieves a token we automatically try to convert that token into her Active token
+2. We should be able to turn this feature off for selected users (like admins)
+3. If users have multiple tokens in their wallet - it is a sign conversion failed - we need some process to retry failed conversions and to altert admins
+
+## Manual convert
+1. For admin accounts we may want to convert from and to specific tokens via the Managment Platform
+2. Admins may also want to convert a users tokens who are failing to auto convert
+
+
+## Testing
+1. Ensure conversions are working between tokens when liquidity pools exist and not when they dont
+2. Test out auto-conversion - one user gets sent a foreign token ... try to convert
+
+
+## Action items
+
+## Implementation
+
+### Workflow
+
+### Variables
+
+### Interface
+
+
+
+## Security
+1. Liquidity pool supply and value Alerts
+1. For bonded pools: Whenever the token is converted to another token and the price changes more than 10% an alter is sent to the token issuer
+1. For Bonded Pools: 1. Message Alert your excahnge value of TOKEN_NAME tokens have changed in +X% / -X% value 
+1. Note that the receipt messages for token transfers that include a conversion should also show the tokens exchange value 
+
+
+## Changelog
+<!--
+Please remember to describe every change to this document in the changelog using 
+serial number:
+
+* version 1:
+-->

spec/024_token_info.md

@@ -0,0 +1,81 @@
+# Token Info
+
+<!--
+valid status values are: Pre-draft|Draft|Proposal|Accepted
+-->
+* Authors: Will Ruddick <willruddick@gmail.com> (grassecon.org)
+* Date: 2021.07.16
+* Version: 1
+* Status: Pre-draft
+
+## Rationale
+Enabeling users to query the info for a particular token. e.g. after choosing it as their active token.
+
+## Intro 
+* Users should have some information about the tokens they are using and holding
+
+## Token-Info – User Flow:
+
+1. A user is sent or given a new token for the first time - even during registration or when choosing to change token.
+1. The user gets a USSD message showing the following info:
+1. Token Info:
+   1. name, 
+   1. symbol 
+   1. holding fee (% aggregated to monthly - calculation needed based on data from contract), =(1-(1-Demurage)^43800) (43800 munites ina  months) ... if demurrage is 0.00000046124891913883 ... then the monthly demurage here is  =(1-(1-0.00000046124891913883)^43800)=0.02 ... 2%  ... 
+      1. note that to calculate a minute by minute demurrage based on a monthly target demurrage of 2% =1- (1-0.02)^(1/43800
+) = 0.00000046124891913883
+1. Stats:
+   1. total supply, (from contract)
+   1. Circulation (total minus the supply of balance of the issuer) (from contract and balance of sink account)
+   1. Number of token holders (calculated: advanced not for mvp)
+   1. GINI Coefficent (against all holders including the issuer balance) (calculated: advanced not for mvp)
+1. Issuer Info (this is the sink account holder)
+   1. Name 
+   1. phone number 
+   1. product offering
+   1. location
+
+## ex:
+1. Give It Up For Sally, GIUFS, holding fee: 2% monthly, 
+1. Supply: 100,000, Circulation: 20,000
+1. Sally Chama, +254727865533, Group Farm, Machakos
+
+
+## USSD Menu
+
+1. Token Info (can be selected under Help)
+The info also comes whenever a new token is send to a receipent for the first time.
+
+
+## Testing
+1. Check info is correct
+
+
+## Action items
+
+## Implementation
+
+A service would need to update this information daily? for each token.
+
+### Workflow
+
+### Variables
+
+### Interface
+
+
+
+## Security
+1. Liquidity pool supply and value Alerts
+1. For bonded pools: Whenever the token is converted to another token and the price changes more than 10% an alter is sent to the token issuer
+1. For Bonded Pools: 1. Message Alert your excahnge value of TOKEN_NAME tokens have changed in +X% / -X% value 
+1. Note that the receipt messages for token transfers that include a conversion should also show the tokens exchange value 
+
+
+## Changelog
+<!--
+Please remember to describe every change to this document in the changelog using 
+serial number:
+
+* version 1:
+-->