Contents
This Stacker Chat episode provides an overview as to the what and how of CityCoins, and covers some highlights of building an open-source and community-run project. When building extremely complex smart contract protocols, Hiro solutions such as Clarinet were key in controlling compute costs and ensuring the launch could be a smooth one. Clarity and Clarinet combined ensured peace of mind for core contributors Patrick Stanley and Jason Schrader, and the project has put in the groundwork to accelerate engagement with the City of Miami government.
“One thing that was extremely helpful throughout the whole process was the Clarinet tool. It allowed us to do a whole ton of testing. We actually ran over 140 different unit tests. We had about 95% code coverage, mostly because the VRF was random and we couldn't get to that full 100%. Everything we did was done with the mindset that you develop a feature, and then you test and test and test that feature. And then you test everything overall to make sure you're getting those expected results.”
The first CityCoin to launch, MiamiCoin has accrued over $4M USD value in STX for the City of Miami as of 9/6/2021. The full episode is available on YouTube. See the edited transcript below, where we link and highlight resources covered in this chat with Patrick Stanley, Community lead and Jason Schrader, Core Contributor of CityCoins.
— Gina Abrams:
Hello, and welcome to the Founder and Builder series of Stacker Chats, where we connect with amazing founders building on Stacks. My name is Gina Abrams, and today I'm excited to be joined by Patrick Stanley, founder of Freehold and the community lead at CityCoins. We're also joined by Jason Schrader, DevOps engineer at Freehold and a core contributor to CityCoins.
CityCoins is an open source, community-led initiative and we're going to dive into it today. Patrick, I'd love to hear your background and how you fell in love with the crypto world and Bitcoin, and how it's led to where you are today.
— Patrick Stanley:
Yeah, so I was previously the head of growth at Stacks. I spun out, created Freehold, which is a community project where people contribute to their favorite projects. I fell in love with crypto back in 2012 when I discovered Bitcoin. The CityCoins project is really cool because I'm just super into civic engagement and crypto. And this is the perfect place where it matched.
— Gina Abrams:
Very cool. Jason, you've been in the Stacker community for a while. How has that led to your work at Freehold and CityCoins?
— Jason Schrader:
Yeah, definitely. Prior to really diving into the Stacks ecosystem, I owned my own IT company servicing small- and medium-sized businesses and did a whole bunch of work across a lot of different outlets. Over that time, I got this spark and interest in what Stacks was doing. I absolutely loved everything I got to do leading to the launch of Stacks 2.0, including working with some of the working groups. That’s how I met Patrick, in the business models group.
— JS:
I am still active with the governance working group. We used to have a proof of transfer working group. That one is now long gone since we officially launched and things are alive. It’s been an amazing ecosystem to be a part of. When Patrick started Freehold, I reached out to him and said, "Hey, I want to be a part of this." And over time we found that we really enjoy how we worked together and took that to the next level. I've been happy to handle everything on the DevOps and engineering side for Freehold.
— GA:
Awesome. Patrick, how do you describe CityCoins?
— PS:
CityCoins democratizes city engagement and allows you to put cities in your portfolio. How I like to look at them is a third way of voting, in a way.
You can vote with your ballot in city elections. Half the time, you're not really super excited by the results. And even if you do get your candidate that you like, they don't always deliver. The other way you can vote is by voting with your feet, so exiting a city and essentially not being a customer anymore by paying taxes there.
Now the third way is with your coin. So if you're a holder of a CityCoin, you're committed to the city. If you're a buyer of a CityCoin, you're bullish on city leadership. If you're a seller of a CityCoin, you're bearish on city leadership. And developers can build for their city with CityCoins. You can also choose to take things into your own hands and essentially just build for your city as a developer.
— GA:
Excellent. Now the first CityCoin, MiamiCoin, went live just a couple of weeks ago. Can you also provide a bit of background in how that works and how the launch has been?
— PS:
Yeah, for sure. So MiamiCoin was launched by the community. There was no pre-mine, no ICO, no primary issuer. There were 20 individuals that launched it, 20 independent miners that signaled the beginning of mining. Then about 150 blocks later (roughly a day later), mining began. How mining works is it essentially uses a generalized form of proof of transfer, the Stacks consensus mechanism. Although, I think we're starting to just call it recycled proof of work because that is what it is.
How it works is you forward a base currency, like Stacks, into the mining mechanism to compete for the chance to win that block. Right now, on average, there's 20 to 30 miners mining MiamiCoin at any given time. And one person, one miner, wins every block. Their chances of winning is weighted by how much they've sent proportional to the rest of the gang who's been mining that block. So if you sent 100 stacks in, and the rest of the rest of the competitors sent 900 stacks in, you have a 10% chance of winning that block. So people are mining over many blocks and earning MiamiCoin that way.
Now, the base currency doesn't just go into a black hole. It gets forwarded directly to the city's treasury. So for the first 2100 blocks of the CityCoins existence, of MiamiCoin's existence, 100% of what the miners are forwarding to compete gets to the city wallet.
And at the time of this Zoom call (Aug. 18th, 2021), the reserved city wallet that the city can claim is about to hit $2 million. This all happened in 13 days from a standing start, from where there was nothing and no market cap. *Update that as of Sept. 8th, 2021 the City of Miami reserve wallet surpassed $4M.
— PS:
Soon, Stacking MiamiCoin will begin for the first time. Just like how Stacking works on Stacks, where you earn in Bitcoin, when you Stack MiamiCoin, you earn Stacks (STX), which, by the way, you can also Stack to earn Bitcoin. Starting tomorrow, instead of the city getting 100% of the proceeds, they'll start getting 30% of the proceeds. And 70% will go directly to holders of MiamiCoin. So the holders of MiamiCoin will earn Stacks. Was that a good explanation, I hope?
— JS:
Yeah, I just want to add one thing at the end there. So with regard to Stacking, the people who earn through that 30/70 split of the protocol are the MiamiCoin Stackers. So it's not just the MiamiCoin holders in general, but it's those who choose to lock their MiamiCoin up in the contract for a set number of award cycles.
— JS:
One other thing we can note about that is when you go to Stack, you can Stack for one cycle, which is 2100 blocks, about two weeks, as mentioned. And you can actually stack for a maximum of 32 cycles, which would equal about 16 months if we go off an average of a 10 minutes block time. So there's a lot of variability available there. And there is a cool-down cycle between Stacking cycles for MiamiCoin, similar to what we see in Stacks today. So let's say you were to Stack for cycle one and two, you'd be able to claim everything back in cycle three. And you would then be able to Stack from cycle four forward.
— GA:
Thank you. It sounds like MiamiCoin has a potential to really use crypto to create real social impact for ordinary citizens. What specific use cases do you think that cities might use their treasuries for?
— PS:
Yeah, great question. I think they're going to use it to recruit crypto startups so they can essentially attract talent and customers to their city. Those people are all taxable once they move to the city. They might use it to subsidize WiFi in underprivileged homes, disaster relief, combating climate change, like building levies and trying to, essentially, modernize their city. I think some cities will try to do things like UBI.
Mind you, mining coins at a billion dollars is creating, roughly, $40-100 million for the city annually. That's insane, by the way. That is insane. They already earned $2 million in two weeks, and they haven't even claimed their protocol contribution. It hasn't even been listed on an exchange.
— PS:
So that's enough, by the way, to offset their entire municipal debt bond servicing. That's jaw-dropping. MiamiCoin at $10 billion creates enough revenue where, hypothetically, the city wouldn't even have to charge taxes to their residents. The possibilities are really endless in terms of what they can use it for. And I think the market of MiamiCoin holders will largely have a feedback loop with the city in terms of being like, "Yes, I like what they're using these funds on. Or, "No, I don't like what they're using their funds on." So it's a concept of thumbs up or thumbs down.
You can take that a step further, and the city could say, "Hey, we really like that feedback mechanism. We'd love you to be more prescriptive, so we know what you really like. So how about you token holders, you vote on things that you think we should spend the money on. And then we designate 50% of what we earned to go toward things that the token holders vote on. And we trial that out and see how that works." I think that's really cool, and that's direct democracy in a way.
— GA:
That's incredible. It sounds like a ton of upside for cities. What are some potential challenges to this novel concept?
— PS:
It's been pretty smooth so far, I got to say. There are little speed bump sized challenges that you get over immediately, but I'll list maybe one or two. One is that most cities can't hold crypto on their balance sheet. And so what they've got to do is immediately convert their crypto earnings into USD. That's fine. It'd be better if they could hold the crypto on their balance sheet, even better if they can mine their own coin. They're going to want to mine their own coin, by the way. That'd be fortifying their treasury. It would be a fiduciary duty.
That was a little mini hurdle, but that was easily overcome-able. I think a lot of operators of most cities probably don't know how crypto works, but they do know that they want to fund the city. So it's almost like there's an educational onboarding that needs to be done with them before they're like, "Oh, I get it. This is built on Bitcoin. It's hyper secure. It generates income for the city. Developers can program with it. Cool. And also, I can put down the contribution at any time, and essentially end this at any time if we feel like it's not good."
Governments have total power to participate or not participate. So they feel really in control. They're welcoming crypto as a tool to use.
Anything that you would say, Jason, from your perspective?
— JS:
You definitely hit it on the head as far as our relations and what it's been like to go through this process with the first city. We are learning from this, we're also taking that and abstracting it to what it could look like as things expand and change. On the technical side, we ran into some interesting challenges along the way, in regards to Clarity and some of the ways we were doing our testing. But I'm sure we'll talk about that a little later.
— GA:
Yeah, the MiamiCoin Clarity Smart Contract is super complex - likely a number of smart contracts working together in managing the city's treasury, allowing users to register for mining, to claim rewards, configure stacking, and set up a token. So much is being done through the smart contract language for Stacks, Clarity. How has your experience engineering these smart contracts needed for CityCoins? What Clarity features streamlined the process?
— JS:
Yeah, definitely. When you talk about all the different functions that we have, it's interesting to note that when we originally started, we started with a single contract thinking that we could do it all in one piece. It ended up turning into much more of a protocol. We have three contracts that are focused on the city, mostly the core and the token are the widely known ones. And then a general VRF. That actually would be used by all CityCoins, and just computes a random number based on the block height, looking about 100 blocks back.
— JS:
So we've got this system in place. We implemented two Clarity traits, and that was a really helpful feature to say, "Hey, as we launch new cities, or as things follow this protocol, we know that at least they're going to contain the same functions. They're going to have very similar functionality, and they're going to follow a set of rules that we set forward." So in that sense, breaking it up into contracts ended up being a really cool way to look at how these different contracts can call and talk to each other. There was definitely an order of operations when it comes to how they were initialized and before registration began.
Overall, it was a very comfortable process. It takes a little while to get used to the parentheses, but once you do that, and once you start to look at how you actually format your functions, it becomes a very readable and easy to understand language. By the end of it, I've really enjoyed the process of programming in Clarity.
One thing that was extremely, extremely helpful throughout the whole process was the Clarinet tool. And so Clarinet allowed us to do a whole ton of testing. We actually ran over 140 different unit tests. We had about 95% code coverage, mostly because the VRF was random and we couldn't get to that full 100%. But everything we did was done with the mindset that you develop a feature, and then you test and test and test that feature. And then you test everything overall to make sure you're getting those expected results.
— JS:
With that combination of what we had, just through some simple NPM scripts and with using Clarinet as our testing framework, it really made us confident that whatever those outcomes we expected were definitely going to work that way. Another thing that was really useful there was the cost testing that came through Clarinet.
What we didn't realize in the very first version of the contract was that some of what we were trying to do in Clarity was expensive. When I say expensive, there are certain cost constraints that are composed of different contracts and functions as they cover how much they read, how much they write, and what the runtime cost is. Now, if you exceed certain thresholds on these, it means you can only fit a certain amount of transactions in the block.
— JS:
So one thing that we really started going through with Clarinet was checking, "Okay, when you go to mine MiamiCoin, for example, how much does that transaction cost? And how can we reduce those costs to the lowest numbers possible?"
There were a few design patterns that evolved out of that. We actually went from having about a 50% runtime cost, which means it was a giant transaction, took up half the block down, to right near 1% for a single transaction. And that type of change is what allows room for this type of thing to scale and allows more people to participate and just to make it a more open process.
— GA:
Wow. Thank you for that overview. And I'm curious in terms of the user flows and any other tools that you're using within the Stack's ecosystem or tools that have been built by the open source community, how has the feedback been in terms of the user experience? Are there any things that you'd highlight in terms of tools that were super helpful or that you're getting feedback on?
— PS:
The Hiro web wallet was pretty great, wouldn't you say?
— JS:
Yeah, the web wallet with SIP-10 token support already. This token is one of the first SIP-10 tokens to actually exist. I think we're going to push the standard to be ratified based on this launch and everything happening here. With that, it came with just some of that novel nature of things, where it was like, "Hey, this is something that really hasn't been done before on this scale on mainnet."
So far, it's been really cool using the Hiro web wallet to be able to send, receive, and to interact with these smart contracts. Being able to use the Stacks Connect Library was very, very useful with that as well. Because then you can pull in the application, you can have log in, the authentication and everything like that.
— JS:
And of course, Stacks.JS. So you have a ton of libraries there. Mainly network and transactions were the ones we get the most, but there's a lot that you can do both in being able to talk to a contract and to interpret the data from it. Because Clarity has a very strict type system. And based on that, the helpers that were available in those packages made it really easy to, for example, look at the hex of the transaction and be able to break that down and say, "Okay, that was actually somebody submitted an amount for mining and presenting that in UI."
— GA:
Thank you so much. Now, this again is an open source project. It's a community-run initiative. I know there's a number of core contributors. How has that experience been and what are you excited for looking ahead?
— JS:
Yeah.
What was really fun about that was just being able to work with a community effort and to handle things. It was a lot of chatting. It was a lot of late night coding. It was a lot of back and forth on GitHub and doing the peer review back and forth. And I do have to say there were several members of the Stacks ecosystem that were very helpful, even in just answering questions, thinking through theories, looking over pieces of code. And with that, we were able to really take this to the next level.
And what we have now is not only focusing on the success of Miami, and focusing on the success of this as a protocol, but allowing that protocol to grow outside of this as well so that we can see, what does it look like with 2, 3, 5, 10 up to 200 cities online. And those types of ambitious goals really take us to look at what we've done, look at how we can improve, and how to make this the best experience ever.
— GA:
Thank you. The team just kicked off the MiamiCoinMakers Month, a month-long remote hackathon for building public utilities using Miami Coin. I'd love to hear a little bit more about this. And what are some of the products that you'd really be excited to see in the ecosystem?
— PS:
Yeah, sure. So Ryan Hoover from Product Hunt is judging this. I'm actually a judge as well. And another judge is BoredElonMusk, the parody account who's constantly coming up with fun ideas, acting like he's Elon Musk who's just bored coming up with ideas. There's about 100 hackers that have signed up. Some people have started building. One idea was that DAO idea I was mentioning earlier where people can vote on what the government uses their funds for.
— PS:
Another that's pretty cool that's being built is this proof of HODL, proof of holding the coin, proof of HODL, access control to physical spaces. So you essentially have little mini Miami apartments or work areas or cafes, which are only accessible by holding it. Even a small amount of MiamiCoin, a penny worth, one MiamiCoin. That's cool. Instead of signing in with your name, it's sign in with your wallet, sign in with your balance, sign in with your keys. And that's pretty interesting. Conceptually that blends. The line between citizen and stakeholder and city limits, the boundaries of a city, really started to blur with that concept because you could have a MiamiCoin apartment building in Berlin. When you come in here, you're entering Miami in a way. And that's pretty fascinating.
— PS:
It's also calling to mind something I've noticed with this project, is it's not attracting die hard Libertarians or Democrats or Republicans or anything.
I think this is a unity project. People who value civic engagement, value their community, but also value building things and building real useful stuff that generate wealth for society. I think they're all on the same page here.
— PS:
I guess one just random thought was on, you can imagine a world where there's hundreds of CityCoins. And mind you, people who live in cities don't hold municipal debt, but they probably would hold CityCoins. So this is a way for people to become stakeholders in their favorite cities, regardless of whether they live in them.
If you imagine a world where there's hundreds of CityCoins. The customer, the end user, I wouldn't be able to really pinpoint a political ideology on that person. I'd say that person's just interested in making the world better in some way and wants to have skin in the game. That's pretty awesome. And I think I wouldn't say there's a new political party or anything like that. I think it's just people that want to help win essentially, but this is new. There's a new thing that's cropping out of this. This is just people who are fascinated by this and want to get involved.
— GA:
Yeah, absolutely. How should folks get involved if they're interested in starting to hack on a project or being a contributor to MiamiCoinand CityCoin, really?
— PS:
Yeah, there is a chat app on Discord just called Chat.CityCoins.co. There's a huge community that's really active. They're having a ball. They're having a blast. And if you want to vote on which city should be next, I think the community is still figuring out how to launch new cities, how to let the city self-service, and self launch. So providing some input there will be directionally helpful for the community. And you can vote on your favorite city anywhere in the world at citycoins.co. Just go in and vote.
— JS:
Yeah. For the Hackathon, you can go to Miamimakers.co. And that will redirect you to the Eventbrite page for the hackathon. On the development side, I wanted to note, too, that we're trying to make the documentation really the go-to source of truth. The documentation lives within the CityCoins organization on GitHub, but it also lives at docs.citycoins.co. And there's a ton there about the protocol, the different contract functions, how different parts operate, as well as some links back to different Stacks resources around Clarity, and some of those transaction libraries I mentioned earlier. So if it's something you feel called to be involved in, I would say start there. And if there's any questions, we're always available in the chat. We're always looking for more people to contribute.
— GA:
Thank you both so much for your time. That's a wrap on the CityCoins, MiamiCoins episode, but we're definitely going to share some resources down below. Thank you both so much, and we'll see you soon.
— JS:
Thank you!
Follow Hiro Youtube Channel to watch new weekly Stacker Chats!
