Compare commits

..

No commits in common. "master" and "lash/review-xdai-migration" have entirely different histories.

30 changed files with 214 additions and 1509 deletions

Binary file not shown.

Binary file not shown.

Binary file not shown.

Binary file not shown.

136
README.md
View File

@ -1,97 +1,97 @@
## 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://gitlab.com/grassrootseconomics/cic-docs/-/blob/master/CIC_Training_Guide_Kenya.pdf)
+ [Training Materials](https://docs.google.com/document/d/1CI-Xz9R3FgZ70uWgq81U5uwfaYrm9f6Ji4f7dL2-V90/edit?usp=sharing)
+ [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)
+ [Blog](https://grassecon.org/blog)
+ [MOOC](https://grassecon.org/mooc) - Very old (paper based systems)
+ [Village Market Simulator series](https://www.youtube.com/playlist?list=PLPUExzwZAUpbEInJy_8Wj_c_mDsw7-qXe)
+ [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)
## CIC-Commons - Open source code
+ **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/))
## Open source code
+ [Managment Platform](https://gitlab.com/grassrootseconomics/cic-platform)
+ [Dashboard](https://github.com/GrassrootsEconomics/Accdash) [Dashboard API](https://github.com/GrassrootsEconomics/Accap)
+ [Demurrage Smart Contract](https://gitlab.com/cicnet/erc20-demurrage-token)
+ [Blockchain Smart Contract](https://github.com/bancorprotocol/contracts)
## 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
## CIC full system vision ##
* Blockchain
* Currently: To ensure decentralization, censor proofing and fair gas prices we work on Humanitarian Blockchains like bloxberg.org.
* 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.
* Currently: We are on a public blockchain (Layer 2 side chain) called [xDAI](https://www.xdaichain.com/)
* 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 Contracts
* [Demurrage token](https://gitlab.com/cicnet/erc20-demurrage-token) - Network / Basic Income token - Mints tokens that include a demurrage.
* Bridge - in order to move between the side chains (Layer 2) we use a bridge
* Currently: We have no connections to Ethereum Mainnet
* Goal: To have options to bridge to a variety of other tokens - possibly Cosmos Protocol
* Liquidty Pools - Enable connection of Sarafu and CICs to each other and outside networks
* 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)
* Bridge - in order to move between the xDAI side chain (Layer 2) and the Ethereum main net we need a bridge (hard spoon).
* Currently: We connect to the Ethereum Main net using the xDAI to DAI bridge.
* Goal: To have options to bridge to a variety of potential reserves
* Bonding Curves - Enable us to add collateral (aka Reserves to CICs) as well as connect CICs to each other in a safe way.
* Currently: Bancor Protocol v1 - [Blockchain Smart Contract](https://github.com/bancorprotocol/contracts)
* Goal: Researching Bancor Protocol v2 and other options
* Contract Deployment (Currency Creation service)
* Currently: We currently deploy all contracts via Command line
* 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) and paper based agreements with communities.
* Goal: Registered organizations can submit an application to be an issuer, they must have:
* an audited and legally binding backing commitment signed by local guarentors to back the total amount of a CIC .
* The CIC issuers should also choose to add thier CIC to a liquidity pool with Sarafu or other CICs for connections
* Longer term goal: DAOs
* Currently: We currently deploy the Bancor Contract suite manually via Command line
* Goal: Both a USSD based and a web based interface for organizations and communities to create their own tokens
* CIC Token Creation system
* Currently: Manual contract deployment (command line)
* 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 .
* A collateral fund of at 25% of the tokens they want to create.
* This collateral can be pulled out of any CIC (such as those provided by an Aid CIC) or purchased
* 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 Digital Ocean for instances and data storgage along with postgress databases - Transactions are done here first then synced with blockchain
* 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
* Currently: We are using AWS 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
* 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
* To pull transaction and user meta data from blockchain directly (also used in marketplace)
* 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
* Marketplace
* 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.
* 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.
* Goal: A web based interface for organizations and communities to share projects, event offers and wants using CICs
* 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
* CIC 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: 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.
* Goal: 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:
* Telegram Chat bot
* [WebApp](https://gitlab.com/grassrootseconomics/cic-docs/-/blob/master/spec/010_Web_Wallet.md)
* WebApp
* Non custodial
* 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: any connection to national currency is handled manually (eMoney / bank transfers)
* Goal: To connect to / create API driven liquidity pools to fiat (eMoney)
* To make credit card another other payment on and offramps available and streamline our fiat to token processes.
* Exchange Rates will be variable based on the CIC → KSH rate (depends on the liquidity pool maths)
* Blockchain interaction (once bridged)
* Anyone who can obtain or create any CIC token can send it to a liquidity pool if avalaible for conversion and bridging.
* Data /ID System -
* Currently: the float account is in no way linked to blockchain and handled manually (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
* You can send Mpesa (eMoney) to our lipa na Mpesa account GE sees that and sends back tokens
* You can also send tokens to GE and GE sends back Mpesa from the float account (this currently very restricted)
* Goal: To make credit card another other payment on and offramps available and streamline our fiat to token processes ... blockchain integration
* 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)
* 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)
* 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
* Non custodial data ownership on cloud where users can specify what data they want to make avalible
* 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.
* Rewards and Incentives
* Currently: These incentive systems are manual, such as initial user air drop, referral bonuses and holding fees.
* 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.
* 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
* Non custodial data ownership on cloud where users can specify what data tehy want to make avalible
* Rewards and Incentives - [see specifications](./spec/001_platform_incentives.md)
* 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.
* 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
* Goal: Any org developing a CIC can easily establish various rules and policies
* Training Materials:
* Currently: We have minimal documentation curriculum, games and materials for training communities and CIC issuers
* Goal: Better curriculum and verious multi-media materials
* Currently: We are developing curriculum, games and materials for training communities and CIC issuers

View File

@ -1,36 +1,35 @@
# TransactionDatasets
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)
Data Sets from Blockchain Transactions and User Demographics
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 xDAI blockchain for each user ex. https://blockscout.com/poa/core/address/0xcb55fc893000a984a5ad73011f93d1540a5f0895/tokens
Datasets Starting 2020 are pulled from the POA (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 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
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. 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
--------
# Post 2020 xDAI data (current)
Post 2020 xDAI
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 Foundation,
- 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: DISBURSMENT = from Grassroots Economics, RECLEMATION = Back to GE, STANDARD = a trade between users, AGENT = when a group account is cashing out (see held_roles) below
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
1. tx_hash - hashed transaction address on blockchain
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. s_gender - From user input
1. s_location - Village name, From user input
1. s_business_type - Entered by GE staff based on user inputed products or services
1. target - wallet ID of recipent
1. t_comm_tkn
1. t_gender
1. t_location
1. t_business_type
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
@ -38,39 +37,32 @@ 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 the older POA Blockchain (pre 2020) if they had one
1. final_bal - current balance of Sarafu as of file date
1. area_name - Regional area in Kenya (generalized from private user data)
1. area_type - Rural, Peri urban or Urban (generalized from private user data)
1. held_roles -
- BENEFICIARY, standard user / standard transactions
- 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. old_POA__blockchain_address - Wallet ID on POA Blockchain if they had one
1. comm_tkn - Their token name (each user only has 1 token) currenlty only Sarafu
1. bal - current balance of [comm_tkn] as of file date
1. location - User input (village name)
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
1. 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 - total number of tokens that left this account from non-STANDARD transactions
1. ovol_out
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_out
1. ounique_in
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_out
1. sunique_in
1. start - day and time of first transaction (when the user account was setup)
1. confidence - based on how many other purchasing users agree with the business_type
----
-----------------------------------------------------------------------------------------
# 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
@ -99,8 +91,6 @@ 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

View File

@ -1,154 +0,0 @@
# 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 Östroms 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 members 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).

Binary file not shown.

View File

@ -1,79 +1 @@
# 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

View File

@ -1,37 +0,0 @@
# 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

View File

@ -4,22 +4,41 @@
valid status values are: Pre-draft|Draft|Proposal|Accepted
-->
* Authors: Will Ruddick <willruddick@gmail.com> (grassecon.org)
* Date: 2021.02.23
* Date: 2020.04.22
* Version: 1
* Status: Pre-draft
## Rationale
The current Sarafu system seeks to maximize circulation in order to fill market gaps and help CIC users to support eachother.
The current 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).
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.
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 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-full-profile**: New users that have filled out their profiles (name, business, location, gender) get 100 Sarafu (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. **airdrop-selfservice**: New users get 50 Sarafu (a CIC) (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. **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/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. **minting/creating**: 100 Sarafu is minted (supply increase) when new users join and are validated
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. **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**: 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

View File

@ -1,4 +1,4 @@
# x/bDAI Migration spec
# xDAI Migration spec
<!--
valid status values are: Pre-draft
@ -6,50 +6,52 @@ valid status values are: Pre-draft
* Authors: Will Ruddick <will@grassecon.org>
* Date: 2020.04.22
* Version: 1
* Status: Depricated
* Status: Pre-draft
## Rationale
We want to give donors and community members a way to contribute to and cash-out from Community Inclusion Currencies with National Currency.
By connecting to a reserve that is stable to the US dollar called x/bDAI we bring some stability and the ability for many to support local communities.
We also enable any CICs that have bDAI as a reserve to convert to any other CIC with bDAI as reserve.
By connecting to a reserve that is stable to the US dollar called xDAI we bring some stability and the ability for many to support local communities.
We also enable any CICs that have xDAI as a reserve to convert to any other CIC with xDAI as reserve.
## Before
Currently we are using a virtual reserve a generic ERC20 token. We have 2 Million of those reserve tokens against 8 Million Sarafu issued (the current Kenyan CIC). (Call those Sarafu_1 or S1)
## After
We have 40,000 DAI to bridge to a bDAI token and put as the reserve and are looking at minting (16Million) tokens (called Sarafu_2 S2)
We have 40,000 xDAI to put as the reserve and are looking at minting (16Million) tokens (called Sarafu_2 S2)
with a connector weight (target Reserve Ratio) of 0.25 (25%) and an inital price of roughly 100 Sarafu to 1 xDAI (USD stable)
(Note that the 100 Sarafu to 1 xDAI will approximate the Kenyan Shillings to USD rate)
## Implementation
Each existing user should have a completley new wallet and private key for security reasons and be given the same balances they currently have with the new (bDAI reserve) Sarafu. Roughly 8Million Sarafu_1 in wallet will be replaced with Sarafu_2
Each existing user should have a completley new wallet and private key for security reasons and be given the same balances they currently have with the new (xDAI reserve) Sarafu. Roughly 8Million Sarafu_1 in wallet will be replaced with Sarafu_2
### Workflow
1. Bridge bDAI to DAI on BloxBerg
1. Setup an onserver node on BloxBerg
> lash: what's meant by public and private functions here?
> lash: private keys: should we take the opportunity of setting up deterministic wallets? perhaps even on the platform we may want to shuffle private keys once in awhile.
> lash: what is a "facilitator address"?
1. Synch db <->Blockchain - ensure synronization between our db (USSD interface) and blockchain
1. (delayed) Finalize any contract changes to Bancor Suite (such as [Depth Bump](https://gitlab.com/grassrootseconomics/cic-docs/-/blob/master/spec/003_depth_bump.md))
1. Understand all Public vs Private (owner owned) Functions - Make all contracts as permissionless as possible
1. Create group of govenors on a multi-sig wallet with the power to assign the facilitator address of all blockchain contracts (Bancor Suite).
1. Security checkes
1. Finalize any contract changes to Bancor Suite (such as [Depth Bump](https://gitlab.com/grassrootseconomics/cic-docs/-/blob/master/spec/003_depth_bump.md))
1. Create Public vs Private Functions - Contracts as permissionless as possible
1. Create group of govenors on a multi-sig wallet with the power to assign the facilitator address of all blockchain contracts (Bancor Suite).
1. Deploy contracts to create Sarafu_2, set inital variables - deposit reserve and mint tokens
1. Migration - New wallets for users - Replicate user accounts with new token Sarafu_2 - ensure private keys are safely stored
1. Can our own xDAI node process transactions?
### Variables
1. Synch variables, - synch frequency - and limitations
2. Contract variables (reserve ratio (0.25), reserve amount (40k bDAI), number of Sarafu_2 (16Million), convert fee 0.005 (0.5%))
2. Contract variables (reserve ratio (0.25), reserve amount (40k xDAI), number of Sarafu_2 (16Million), convert fee 0.005 (0.5%))
3. Migration speed - how often is synching done between USSD db and blockchain
4. 3rd party Fiat <-> bDAI conversion costs and speed
4. 3rd party Fiat <-> xDAI conversion costs and speed
### Interface
This migration will all be done at code and command line level, while some testing can be done on the platform gui
## Testing
1. Check bDAI to DAI on bridge on BloxBerg
1. Test observer node on BloxBerg for dashboard
1. Check db<->blockchain synch - verify they are synched and we can do external transactions and handle RPC failure
1. Token Governance
1. Contract deplyment - conversions, transfers all work as expected

View File

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

View File

@ -1,100 +1,36 @@
## Notes ##
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.
## Incoming Sarafu ##
When chama (group accounts) exchange Sarafu each month for National Currency we have to manually send them Mpesa.
We would like to automate this.
## Outgoing Sarafu ##
When anyone sends us Mpesa on our paybill we have to manuall send them Sarafu
## Solution ##
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 added to the float account account triggering Mpesa to be released from the mpesa (float)
- 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.
- CIC from our Sarafu float account is sent to the user (this amount can be based on a bonding curve)
### Variables for excahnge rates ###
- float_CIC_Supply = the total supply of the CIC on the float account
- float_CIC_reserve = the total supply of Mpesa in the float account
- trr = the connector weight on blockchain converter between supply and reserve (assuming 50%)
- CIC_excahnge_amount = the amount of CIC the user has sent to exhange for Mpesa
- Mpesa_excahnge_amount = the amount of MPesa the user has sent to exhange for CIC
- Rate: CIC -> KSH
- Rate: KSH -> CIC
- Fees: Sarafu to Mpesa FeeCC2M = 2%
- Fees: Sarafu to Mpesa FeeM2CC = 2%
- Alert on float balance and excahnge rate levels
Configure - using our own system AfricasTalking API to automatically send Sarafu / Mpesa based on rules:
### Incoming CIC Rules - MPESA out ###
The amount of Mpesa given should be calculated as follows:
- CIC_excahnge_amount = the amount of CIC the user wants to excahnge
Quotation: The Reserve (Mpesa) to be pulled out (reported):
Assuming a (trr=50%) connector weight: return (float_CIC_reserve x CIC_exchange_amount ) / (float_CIC_reserve + CIC_excahnge_amount)
- reserveOut_Mpesa_reported = the the above amount of Mpesa that would be pulled from the Mpesa float account minus any fees (FeeM2CC)
Note that this should be the minimum amount the user will get - if they confirm (not the max)
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 ###
inverse of the above
### Exchange Rate ###
When dislaying the SPOT price or excahnge rate to a user we should use the following formula:
> Exchange Price = float_CIC_reserve / (float_CIC_supply * trr) -> this is pulled from blockchain and should be sent back as a SMS
### Incoming Sarafu Rules ###
- *white list* The chama (group accounts only) must only be able to cash out - using the exchange option to an Agent account
- *amount* The max cash out is the minimum of (30,000 Sarafu, half their balance, their total amount of outward trade volume to other users (standard transactions)
- *time* They can only cash out once per month
- *rate* The Sarafu to Mpesa rate should be a config variable set to 1.0 -> a 0% cash out fee. i.e. For 100 Sarafu you get 100 Mpesa. This rate will vary manual based on promotion periods and available Mpesa
### USSD Interface ###
- Option #4 Exchange
- #1 Get Exchange Rate
- #2 Confirm Exchange
- User chooses Exchange Menu option #1 Get Exchange Rate - then chooses the direction of the exchange
- #1 [CIC] -> Mpesa
- Enter the amount of [CIC] you wish to redeem (limited to their balance)
- #2 Mpesa -> [CIC]
- Enter the amount of Mpesa you wish to contribute
- Enter pin to confirm
- You will recieve a SMS shortly
- perhpas for MVP we can just spit this back out on USSD.
- SMS: You will receive at least 800 KSH for 1000 CIC. This quotation is stored for the user but only valid for a period of time (1 hour?)
- User chooses Exchange Menu option #2 Confirm Exchange - if they don't have an active quotation they must goto option #1 first.
If the quotation is for CIC->Mpesa then:
- Show the last quotation message
- Enter your pin to confirm
- You will recieve a SMS shortly
If the quotation is for Mpesa-> then:
- Show the last quotation. message - which includes instruction for sending on paybill
### Credit Clearing ###
Weekly or after alterts we will rebalance our xDAI and Mpesa float accounts.
As our float account gets more and more full of xDAI (and mpesa float shrinks) - we will convert the xDAI to Mpesa
via xdai.io to get ETH - then using localcryptos or BitCoinSuisse to get Kenyan Shilllings / Mpesa (note there are MANY fees along this path)
If we get a large amount of Mpesa and want to convert to xDAI -> CIC ... then we send the Mpesa eitheir to localCryptos or bitcoinSwuiss to get ETH
then we use xdai.io to convert that ETH to xDAI ... then we add that to our xDAI float
### Outgoing Sarafu Rules ###
- *white list* Only users sending via paybill receive Sarafu. Non users receive a invitation to join Sarafu sms
- *amount* The max sarafu out is 20,000 Sarafu per user
- *time* No limit
- *rate* The Mpesa to Sarafu rate should be a config variable set to 1.2 -> a 20% cash in bonus. i.e. For 100 Mpesa you get 120 Sarafu. This rate will vary manual based on promotion periods and available Sarafu
### Security ###
- Balance alerts: On both Mpesa and CIC balances: The paybill from which Sarafu is sent needs to send a sms and email alert when low
- Balance alerts: The paybill from which Sarafu is sent needs to send a sms and email alert when low
- Failure alerts: If the API session fails an sms and email alert should be sent
- Reject on not enough Mpesa balance: If there is not enough Mpesa (on incoming Sarafu) the transaction should be rejected and an email sent to admin along with a SMS to admin and user (Sarafu should not be taken from user). (message should be visible also on mgmt platform txn view and user view and admin view).
- Reject on not enough Sarafu balance: If there is not enough Sarafu (on incoming Mpesa) the transaction should be rejected and an email sent to admin along with a SMS to admin and user (Mpesa should not be taken from user). (message should be visible also on mgmt platform txn view and user view and admin view).
### Variables ###
- The account from which Sarafu is sent should be a Agent account
- The cash-out rules for a chama (minimum and time limit)
- Alert balance levels
- Rate: Mpesa to Sarafu
- Rate: Sarafu to Mpesa

View File

@ -26,10 +26,16 @@ 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 outward trade per week for
1. phone verification and all info filled out = 20,000 Tokens
1. National ID number verification (via api) = 50,000 Tokens
1. Photo of Person and them with National ID = 250,000 Tokens
1. KYC LImits for max amount of trade per week for
1. phone verification = 50,000 Tokens
1. ID verification = 100,000 Tokens
1. secondary ID verification = 500,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

View File

@ -1,121 +1,50 @@
# CIC Wallet Infrastructure
# Title
<!--
valid status values are: Pre-draft|Draft|Proposal|Accepted
-->
* Authors: Will Ruddick, Gustav Friis
* Date: 2021-april-16, 2020.07.28
* Version: 0.2
* Authors: Firstname Lastname <email> (url)
* Date: YYYY.MM.DD
* Version: 1
* Status: Pre-draft
## Rationale
<!--
Why are you proposing this?
-->
## Before
<!--
What is the current state of the described topic?
-->
## Purpose
## After
<!--
How will things be different after this has been done?
-->
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.
## Implementation
<!--
Here is the description of how these changes should be implemented.
Please use subheadings to improve readability.
Some suggestions:
## Target group
### Workflow
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 weve 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).
### Variables
## User-stories MVP
### Interface
-->
- Get directed to web wallet via URL
## Testing
<!--
Please describe what test vectors that are required for this implementation
-->
- Signing up
## Changelog
<!--
Please remember to describe every change to this document in the changelog using
serial number:
- Displaying balance
- 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)
- Initiate payment by scanning QR code
- Receive payment via QR code
- Receive payment via link
- Claim payment link
- Payment notification
- Cash in and out from CICs to M-Pesa
- Choosing a reference currency (Eventually not Sarafu)
- Social password recovery
**Settings including**
- Backup wallet
- Change base currency
- Support
- Social media
- Sign out
- Share with friends
## Technical implementation
### Wallet creation
??Using BIP39 HD and secp256k1
### Wallet authentication and recovery
Based on an open-source fork of Portis https://assets.portis.io/white-paper/latest.pdf, but instead of relying only on email as a string it can be any identifier which Grassroots Economica already has in place for its users.
The current PoC implementation of this can be found here:
https://github.com/multiplycharity/multiply-monorepo/tree/master/packages/sdk
https://github.com/multiplycharity/multiply-monorepo/blob/master/packages/server/src/controllers/accounts.js
From the Portis Whitepaper allowing SMS / Email / Password authenticated and recovery:
“Portis lets users create an encryption key on their Client, so once they generate blockchain wallets on their devices, they will be able to encrypt them using said encryption key, and store the encrypted wallets on the Portis servers. All cryptographic keys are generated and managed by the user on their devices, and all encryption is done locally in the Client. Portis servers are never in the position of learning your cryptographic keys. When the already encrypted data travels between the users device and our servers, it is encrypted and authenticated by TLS. All of the users sensitive data is encrypted when they create their account using 64 random bytes generated on the Client, protected using a password that they select. Nobody on earth knows this password besides them as it never leaves the Client. Using a KDF algorithm, a Backup Recovery Phrase is derived from the password, to offer users a means of resetting their password in case they forget it.”
### Interface with the existing Grassroots Economics Platform
Existing USSD users (phone to blockchain address mapping)
Auto top-up of Gas fees on BloxBerg (Bergs)
AfricasTalking API
### Claimable transactions
Using the open-source Linkdrop SDK
## Tech stack
Expo
React Native
MongoDB
Node.js
## Portability
Portability into native mobile apps and desktop apps following this pattern https://www.youtube.com/watch?v=ykBxY01j_rA
## Future developments
Migrate to Gnosis Safe smart-contract wallet
User facing decentralized exchange
User facing on-the ground marketplace
Native implementation of P2P platforms like Mylocalcrypto
* version 1:
-->

View File

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

View File

@ -1,41 +0,0 @@
# 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>,
},
...
]
```

View File

@ -1,121 +0,0 @@
# 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)

View File

@ -1,27 +0,0 @@
# 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)
-->

View File

@ -1,76 +0,0 @@
# 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

View File

@ -1,69 +0,0 @@
# 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:
-->

View File

@ -1,89 +0,0 @@
# 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.

View File

@ -1,91 +0,0 @@
# 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:
-->

View File

@ -1,110 +0,0 @@
# 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:
-->

View File

@ -1,100 +0,0 @@
# 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:
-->

View File

@ -1,81 +0,0 @@
# 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:
-->