Humanity Cash: A Technical Retrospective

Last week the Keyko team put the cap on a pilot project for Humanity Cash and the digital community currency BerkShares. It explores a fully collateralized stablecoin system and accompanying cross-platform mobile payments application.

Last week the Keyko team put the cap on a pilot project for Humanity Cash and the digital community currency BerkShares. It explores a fully collateralized stablecoin system and accompanying cross-platform mobile payments application.


I’m incredibly proud of the technical team that made this project come to life. In less than a year, with only three-ish developers, we built the following:


  • a production-ready scan-to-pay mobile application
  • orchestrated by a novel smart contract suite, using the Celo blockchain
  • a complex traditional API and database
  • and integration with the intricacies of the US ACH banking system


Keyko is no stranger to the Celo ecosystem and at the CeloConnect conference in Barcelona, April 2022, my elevator pitch was eventually honed to “Venmo on Celo”.


Check out our previous posts on the inception and history of the project:



The open-sourcing of a year-long project that was previously internal brings a lot of focus on quality, consistency and legibility. Frankly: is this code ready for the world to see? Developing swiftly, on limited resources and in a permanent crunch leaves a lot of open threads, and before I entered the danger zone I wanted to pull on a few of those threads and see what fell out.


The Stack


A quick recap on the architecture.


Figure 1. Not an IEEE official diagramming standard, it’s a bunch of icons I connected with arrows. You know it, I know it, let’s move on.


The core user interface is a React Native mobile application (Expo framework) with a standard web2-like user/password login orchestrated by AWS Cognito. The application code can be viewed here:


The application content and write actions are all interfaced by a monolithic NodeJS / Typescript (Express framework) REST API. The API is hosted and deployed on AWS using the Elastic Beanstalk CLI. The code is available here:


Why is all this hosted on AWS? Two reasons. One, available developer competencies. Plus, we were fortunate enough to be granted a lot of credits through the AWS Amplify program and Flori Ventures. Ultimately, this stack would work better as a containerized solution and I would encourage anyone wanting to extend this project to start with a set of Helm charts as a good way of understanding all the moving pieces.


We wrote a managed EVM compatible wallet contract suite with a custom stablecoin token that represents Berkshares, i.e. the local currency. That is available here: We host a full archive Celo mainnet node internally to interact with the node RPC endpoint.


A major third-party dependency is the services we had to write to interface with Dwolla, a US payment solutions provider. Unlocking the capacity of Dwolla really was key in getting this project off the ground. Dwolla provides a drop-in US bank account linking process called Instant Account Verification. This allows a user to login to their bank(s) using their regular web login details, where the process retrieves their routing and account information on their behalf. This allowed us to use Dwolla API interactions to both deposit and withdraw from fiat bank accounts on behalf of the customers of the mobile application.


Figure 2. A slightly nicer looking swimlane action diagram, that in my mind shows how we mint dollar-backed stablecoins on the Celo network, but probably requires me explaining it for an hour to make it clear.


Users sign up (mobile application, user/pass), sign into their bank account (Dwolla) and deposit to the BerkShares’ nominated bank account. We get callbacks from Dwolla when this process is completed (we host an endpoint for Dwolla to ping) and mint stablecoins on-chain (web3 + smart contracts) which then appear instantly as scan-to-pay dollars for the user. From that point on, the application acts like a cheaper, faster PayPal. In the other direction, we reverse the functionality. For withdrawals, we instantly burn the stablecoin and then initiate the fiat withdrawal from the participating bank account back to the user.


Slick peer to peer payments on Celo, with a built-in fiat on and off-ramp.


Know Your Compromises


The reality is that the customer base for the BerkShares pilot — the first implementation of this stack — are not crypto-natives. It’s an older, local crowd in upstate Massachusetts. Mnemonic phrases and private keys would have been an absolute non-starter for this cohort and the decision was made very early to abstract that all away.


All deposits (aka minting of new stablecoin), withdrawals (aka burning), and peer to peer transactions (aka transfer) are standard ERC20 functions, signed and managed by a Controller contract on the server side. When the user hits ‘Send’ in the app, we call our API to signal the transaction and we perform it on their behalf (Celo gas fees are effectively nominal). In fact, unless they read into the technical underpinning of the application, blockchain isn’t mentioned at all.


Is this the best representation of the benefits of blockchain in general? No. Is private key management a massive barrier to general audience adoption of crypto technologies? Of course it is. It’s encouraging to see Celo taking the user experience seriously and making some pragmatic in-roads. (See their new encrypted cloud backup seed recovery tool). But for now, our solution works for this use case and it works well.


The best part? We made our part-custodial solution reversible. Every user receives their own on-chain smart contract mini wallet created by a factory, with a transferable controller. Later on, for a different implementation, for a different crowd, we can open up advanced mode and give the user full sovereign control over their local currency stablecoin. This would effectively allow the stablecoin token to be transferred outside our walled garden and would open up market externalities for a different user set.


The lesson: know your audience, know your value proposition, and put aside technological purity tests.


//ToDo: Refactor Early, Refactor Often


There were a number of fairly significant architectural changes along the way that we just took too long to pull the trigger on causing us orders of magnitude more pain later on. Here’s a non-exhaustive list of some designs we had good intentions and compromises on before reality set in.


Figure 3. Some patterns that could have been addressed sooner, or at all.


The lesson: feature momentum is real and if you know you’re traveling too fast and need to stop and change the tires, do it.


Dig In


If you’re in the Berkshires region in Massachusetts, USA, give the live mobile application a try! Available on the Apple Store and Google Play and accepted at an increasing number of local vendors in the area. For some background on the inception of BerkShares local currency, check out the great work of the Schumacher Centre and the BerkShares project.


And if you’re a developer working on related stuff or know a project that could benefit from this tech stack, go check out the code. It’s open source!


Follow us on Medium for more articles like this.