Technical Overview
Work in Progress
Excluding services accessed through external providers such as the SMS gateway, Sempo consists of four main components:
- business-logic managed through a server
- an administrator dashboard accessible through a web browser
- an Android App for recipients and vendors
- a smart contract hosted on the Ethereum Blockchain for transaction processing
- React
- React Native for Android Phones
- Redux and Sagas
- Pusher for real-time updates
- Python 3
- Python Flask
- PostgreSQL on AWS RDS
- Microservice Task Queue using Celery and Redis
- uWSGI Web Server through an NGINX Reverse Proxy
- Multicontainer docker hosted on AWS Elastic Beanstalk and deployed via Elastic Container Service
- Encrypted S3 buckets for Secrets Storage
- Ethereum ERC20 Smart Contracts:
- Infura Gateway
- Web3.py
- Pyethereum EVM
- Programmable SMS gateway via Messagebird, Twilio, USSD Providers such as Africa's Talking
- Contactless payment NFC cards/stickers using the Mifare Ultralight ev2 chip for offline scenarios
Server-side infrastructure is built to operate inside Docker containers, which means the platform can be launched on a variety of operating systems without significant modification, be it through providers such as Amazon Web Services (AWS), or local servers in the field. In general, we use the AWS platform because it provides an effective way of handling scaling. In such cases, each deployment of Sempo is launched inside its own Virtual Private Cloud (VPC), which has the effect of completely isolating Personal Identifiable Information (PII) and other critical access data. We are able to store data in specific geographies according to client requirements.
Inside the VPC, Sempo consists of a main server, and a set of workers that manage the scaling of asynchronous tasks such as synchronisation of transactions on the blockchain.
Sempo uses two forms of data persistence - a pair of private Postgresql databases and the public (“mainnet”) Ethereum blockchain.
The internal databases serve two main purposes:
- The 'app' database acts as a location to store sensitive user data that could not safely be stored on a public blockchain.
- The 'eth worker' database stores data required to reliably make custodial transactions on the ethereum blockchain, such as nonces, transaction records, and hosted-wallet private keys
The data-model of the 'app' database currently uses 4 core objects: User, Transfer Account, and Credit Transfer:
The User object represents an individual, and is used purely for identification and authorisation purposes. Users can be identified through a number of public and private facing identifiers such as phone number, email address or other unique serial number. Users make credit transfers via the associated transfer account.
Key properties
- First Name
- Last Name
- Phone Number
- Public Serial Number
- NFC Serial Number
- Password (Hashed and Salted)
- Authorisation Levels [Admin, Recipient, View Only…]
- KYC Status
- Custom Attributes
- Transfer Account (relationship)
The Transfer Account object links transfers and balances to users and blockchain addresses. Transfer Accounts are seperate objects to Users, because several Users may have access to the same transfer account. For example, Vendors can have multiple users (cashiers) who all accept payments into the same account.
Key properties
- Balance
- Blockchain Address
- Blockchain Private Key (Secondarily Encrypted)
- Credit Transfers (relationship)
- Users (relationship)
Credit Transfers are a record of transfers of funds or credits between different transfer accounts. While a transfer is primarily thought of as something that occurs between two Transfer Accounts, whenever a transfer is made, the individual users involved in the transfer are also recorded if possible.
Key properties
- Created Datetime
- Resolved Datetime
- Transfer amount
- Sender transfer account
- Recipient transfer account
- Sender user
- Recipient user
- Blockchain transactions (relationship)
- Transfer metadata (modality, usage etc)
A given credit transfer may be associated with multiple blockchain transactions; disbursements involve multiple initialisations transactions, and occasionally transactions fail and must be retried.
Key properties
- Submitted Datetime
- Added Datetime
- Transaction Hash
- Status
Ethereum Blockchain The core component of Sempo’s blockchain infrastructure is an ERC20 token. This is used to record transfers of credits between anonymous addresses (reconciled with identities using the internal database). ERC20 is technical standard for smart contracts running on the Ethereum Blockchain, commonly used for tracking the ownership and transfer of tokens between parties.
In addition to providing a standardised way for blockchain applications to track token ownership, ERC20 guarantees consistent access to several functions such as:
- transferFrom: transfer tokens from one address to another.
- approve: approve a third-party address to transfer tokens from your address, up to a specified amount.
In order to meet deployment specific requirements, Sempo is able to swap its blockchain infrastructure to use any tokens conforming to the ERC20 standard. This includes the Dai Stablecoin, along with a token created by Sempo that is not a cryptocurrency, and so can be used in jurisdictions where cryptocurrencies are illegal.
Sempo supports transfers over a number of modalities including: Android App, Contactless (NFC) Payment Cards, SMS, and Facebook messenger. The NFC Card is able to operate in cases where the entire community has only intermittent internet connectivity; transfers are cached on vendors’ Android phones, and reconciled whenever an internet connection is available (for example, when a hotspot is provided once a fortnight). The NFC card includes a cryptographic module that prevents recipients from double spending funds.
The following section outlines key payment processes between a vendor and recipient who both have Android phones. Other processes are similar from a technical implementation point of view.
-
Account creation: The NGO partner enrolls a recipient by providing key details such as name and phone number. The NGO partner selects whether to create a new Transfer Account, or bind the User to an existing Transfer Account. If User is bound to an existing Transfer Account, they share their balance with any other Users bound to that account. When a Transfer Account is created, the enrollment process generates a public-private key pair for the blockchain, which is stored in the internal database. Each Private Key is encrypted so that even those with direct access to the database cannot easily access the Key.
-
Preparing blockchain credits: If a cryptocurrency such as Dai is being used, funds to be distributed are sent to a master wallet. If the blockchain backend is being used for tracking purposes only, the Sempo Smart Contract automatically manages the creation of credits.
-
Internal disbursement: The NGO partner selects how many credits to disburse to a User (or bound transfer account). The system checks the balance of the master wallet on the blockchain, and subtracts the value of any pending disbursements that are found in the internal database but have not yet been committed to a block on the blockchain. If this amount [current minus pending] is greater than the amount that must be disbursed, the system has reasonable belief that the transaction submitted to the blockchain will succeed, even once pending transactions have been accounted for. The system records this transfer in the internal database using the Credit Transfer object. The recipient user can then immediately see the new credits using the Android App, or the “check balance” SMS request, even though the transfer is yet to complete on the blockchain. A task is sent to the blockchain worker queue containing:
- The amount to be disbursed
- The public key of the recipient wallet
- The encrypted private key of the recipient wallet
- The Credit Transfer id
-
Blockchain worker task identification The next available blockchain worker removes the task from the queue. The worker loads in the decryption key from the external S3 bucket and uses this to access the private key of the recipient address.
-
Blockchain disbursement of credits The worker uses the private key of the master wallet (stored in the S3 bucket) to send a request to the smart contract credits to the address to the recipient. Once the request is submitted and a transaction hash has been obtained, the worker sends a message back to the main server to attach the transaction hash the associated Credit Transfer, with a status of “Pending”. The worker then periodically checks the transaction on the blockchain to determine whether it has succeeded or not. In between checking, the worker is free to begin other tasks. Once the transaction has succeeded (or failed outright), the worker sends another message to the main server to announce the completion status. If the transaction fails, retries are attempted at exponentially increasing intervals up to a specified number of retries.
-
Blockchain transfer of Ether for approval transaction The worker once again uses the private key of the master wallet, this time to send a small amount of ether to the recipient. This transaction goes through the same update process as described in Step 5.
-
Approval of master wallet to make transfers on behalf of recipient The worker uses the private key of the recipient to send a request to the Smart Contract’s “Approve” function. This means that the master wallet (and by extension the Sempo platform) will now be able to make requests to the Smart Contract to transfer credits on behalf of the recipient, without needing any further access to the recipient's private key. This transaction goes through the same update process as described in Step 5.
-
QR Code Generation: The Vendor uses the Sempo app on their Android phone to generate a QR code that specifies the price they wish to charge for goods or services provided. In addition to the price, QR code includes the Vendor User ID, and the name of the Vendor.
-
Paying User Confirmation The paying user scans the QR code using their own Android App. The Android App then displays the amount to be charged, the name of the Vendor, and how much balance the paying user will have after the transaction. If the paying user has insufficient balance, the transaction fails immediately. If the paying user wishes to confirm the transaction, they do so by clicking the “tick” button. This sends a request to the server.
-
Internal Credit Transfer The server checks the local database to determine whether the paying user account has sufficient balance, and if so completes the transaction locally. Alerts are sent to both the paying user’s Android App, along with the Android App belonging to the Vendor.
-
Blockchain Transaction An asynchronous task is added to the blockchain worker queue, which is picked up by the next available worker. Unlike the disbursement step, the task does not contain the private key of the paying user, but rather the paying user address, the recipient address and the transfer amount. The worker user the master wallet private key to send a “Transfer From” transaction request to the blockchain. This transaction goes through the same update process as described in Step 5 of the Disbursement Flow.
It is not uncommon for paying users to have access to internet on their phone intermittently - their data plan may run out, or they may only have access while connected to Wifi at home or a community center.
-
Initial Handshake When a paying user logs onto the Sempo App via their Android phone, they are given a unique secret key that is also stored on the server.
-
Paying User QR Code Generation To make a payment without access to internet, the user types in the amount they wish to transfer. This amount is then hashed (HMAC is used, in order to protect against Length Extension attacks) along with the user secret and a timestamp in order to generate a 6 character one-time password. The raw amount, user ID and the one-time password is then used to generate a QR code.
-
Vendor request for payment The vendor scans this QR code and sends the data to the server. The server then uses its own copy of the user’s unique secret key to reconstruct the one-time password. If it matches that provided by the vendor, then the server can be confident that the vendor did not tamper with the data (for example by changing the amount) provided by the paying user. The data timestamp is also checked, to prevent the vendor from photographing the QR code and using it to make unauthorised payments at a later date.
-
Transfer Completion The rest of the transfer process proceeds as specified in the previous section.