CityCoins V2

[LNow]

The goal of this topic is to gather all feedback (good and bad) about current implementation of CityCoins contracts and think what we can, should and must change.

Token

MiamiCoin has been deployed as manually modified version of citycoin-token.clar. This approach was good for single release, however I'm sure it was also a very stressful for @whoabuddy as he had to manually alter contract and deploy it without being 100% sure that it will work as intended.

To avoid that in the future I think we should build V2 as 100% city-wise agnostic, that don't need any manual alteration prior deployment.
Contract should by simple and have no reference for which city it will be used.
We can achieve that by making token initializable, so that all metadata (name, symbol, decimals etc) will be configurable after deployment.

Mining

Mining is working as we expected.
One thing that we could add is the possibility to choose from which block miner wants start mining. Something like:

(define-public (mine-many-starting-at (amountUstx uint) (memo (optional (buff 34))) (startAtHeight uint))
  ;;
)

where startAtHeight would be used only as desired first block user want to start mining at.
If startAtHeight is greater than block-height it will be used as first block otherwise block-height will be used instead.

With this miners will be able to mine over long, continuous period of time, as it will be able to send.

Claiming mining rewards

This is something we need to work on. Sending N separate transactions to claim rewards from multiple blocks is not user friendly.
We can implement automatic block winner selection and hook it up to every single public function call.
This will increase the cost of execution all public functions but at the same time it will decrease number of transactions generated by CityCoins contracts.

Stacking

Staking is working and I don't think we need to change anything in it.

Claiming stacking rewards

We are still in the first in the 1st stacking cycle, however I'm very confident that claiming stacking rewards will work.

Data access

We need to find a way how we can improve data access - research is needed how we can build custom indexer

[Jamil]

First of all, awesome job with the contracts, and I'm just gonna add some initial first thoughts below based on the developer experience of interacting with the contract from the perspective of data retrieval.

Not intended as criticism, just as thoughts based on my experience. And of course as a developer without experience in Clarity, I'm not as aware of the technical limitations.

• Right now, there is no easy way to get a mapping between miner : commitment for each block, from the contract. You either have to go through the transaction history and find when the user called mine-tokens or mine-many, or, if you want to interact with the contract, iterate through all the user IDs and call get-miner-at-block for each of them. It'd be nice to have a get-miners-at-block which returns a list of miners at that block, and how much each of them have committed in that block. The transaction-based calculations will get more and more computationally expensive with each block.

• The behavior of get-block-winner-id and is-block-winner is inconsistent; the former doesn't return anything if the block is unclaimed, while the latter does.

• It'd be nice to hide the concept of the userId completely at the API level; I think for callers of the contract, they'd only ever want to refer to the address/principal, and not the internal ID. For example, get-block-winner-id returns the user ID, but another function call or cache of users is required to resolve that to an actual STX address.

• I don't believe there's a contract call to check how much a user has stacked in the contract; similar to the first point, you'd have to do this based on the transaction history.

I think in (my) ideal world, all the information displayed on miamining.com should be able to be retrieved directly from the contract, with retrieval of the information from each block requiring as few function calls as possible.

Incidentally, also:

• Is there a reason mine-tokens and mine-many are two separate functions? A mine-tokens that takes an (optional) starting block height and number of blocks seems like it'd cover both.

• A claim-all contract function in my opinion would be better than hooking automatic claiming to every public function; a contract call that finds all claimable blocks by the user and claims them.

[LNow]

@Jamil thank you for your feedback. I appreciate it.

First we have understand the difference between blockchain and typical database applications or just any kind of database. They are design with different set of features and priorities in mind. Therefore things that blockchains are good at (decentralization, consensus mechanism, being trust-less) come at cost. Most of the time cost that we pay is how much data we can store in them and how fast and easy read this data.
The more data we want to store in block-chain, and the faster we want to read it the beefier machines we need, and as a consequence decentralization is decreasing. And decentralization is something we want to keep as high as possible.

Because of that we have to look for compromises. So we are trying to store as little data as possible, and as much as it is necessary so that we can implement in contracts all features that we need.
Our main goal is to deliver functionality, make them secure and reliable. And at the same time keep execution costs as low as possible. Ease of data retrieval is almost at the end of our list of priorities.

But don't get me wrong - we care about it, but if we have to choose between nicer API at cost of making transactions 1% more expensive we will pick ugly API almost every single time.

If we want to have a nice API, we have to build custom indexer that will store data in a more accessible way. Something like https://thegraph.com but for Stacks.

• Right now, there is no easy way to get a mapping between miner : commitment for each block, from the contract. You either have to go through the transaction history and find when the user called mine-tokens or mine-many, or, if you want to interact with the contract, iterate through all the user IDs and call get-miner-at-block for each of them. It'd be nice to have a get-miners-at-block which returns a list of miners at that block, and how much each of them have committed in that block. The transaction-based calculations will get more and more computationally expensive with each block.

Indeed, right now it is quite difficult to obtain such data mainly due to how we store it. The good news that it possible that we gonna change some of our data structures to make it a bit more easier without paying any penalty in form of higher execution cost.
get-miners-at-block is something we can think about, but it won't be a dumb function - you will have to supply to it a very specific set of arguments (easy and fast to create)

• The behavior of get-block-winner-id and is-block-winner is inconsistent; the former doesn't return anything if the block is unclaimed, while the latter does.

get-block-winner-id returns winner id only if we know who is the winner of a specific block. If we don't know who is the winner, we return (none). We could return 0 as user ID but that would be a bit misleading.

is-block-winner checks if very specific user is a block winner
Because there is no easy way to obtain list of all miners who participated in a single block we couldn't make get-block-winner-id more user friendly. With modified data architecture I mentioned earlier this might change for better.

• It'd be nice to hide the concept of the userId completely at the API level; I think for callers of the contract, they'd only ever want to refer to the address/principal, and not the internal ID. For example, get-block-winner-id returns the user ID, but another function call or cache of users is required to resolve that to an actual STX address.

We use userId defined as uint to save space and reduce execution costs. It was a deliberate decision that we've made during our 2nd or 3rd cutting costs sessions.
uint takes 16 bytes and standard principal 21 bytes (if I remember correctly). At first glance the difference is very small, but if you multiply it by number of miners and stackers, thousands blocks and dozens of cycles the choice will become obvious.

• I don't believe there's a contract call to check how much a user has stacked in the contract; similar to the first point, you'd have to do this based on the transaction history.

Great observation. This is definitely something we could add. Unless someone creates an indexer first ;)

I think in (my) ideal world, all the information displayed on miamining.com should be able to be retrieved directly from the contract, with retrieval of the information from each block requiring as few function calls as possible.

I share your view about how our ideal world could and should look like. Stacks ecosystem is still very young and there are many missing pieces that we all would love to have. It takes time but I'm sure we'll get there, and in the future reading contract data will be as easy as running plain old fashion SQL statements.

• Is there a reason mine-tokens and mine-many are two separate functions? A mine-tokens that takes an (optional) starting block height and number of blocks seems like it'd cover both.

• A claim-all contract function in my opinion would be better than hooking automatic claiming to every public function; a contract call that finds all claimable blocks by the user and claims them.

You can supply mine-tokens with optional memo that will be emitted as print event. mine-many can't do that.
Although under the hood both functions does the same thing, if you want to mine only one block mine-tokens is cheaper.

claim-all won't happen in the nearest future. Too complex, and too expensive. More likely is that we'll add claim-multiple-mining-rewards to which you'll have to supply list of blocks from which you want to claim reward.
But first we need to see some changes in how executions costs are calculated.

[Jamil]

Thank you for the thorough reply! Appreciate it, and I understand completely the principle of deferring computational costs to the client instead of having that on-contract. Right now any information that we need is computable on chain given a record of transactions since the original mining block, so there's no loss or hiding of information. It seems like the best approach is to generalize many of the high-level operations that I mentioned into client-side/off-chain logic.

[Zk2u]

Yes. The contract needs to be as optimised as possible. Indexing and other things for UX generally have to be moved offchain.

[whoabuddy]

Love the fact we're starting a discussion on this, thanks @LNow !!

In programming the UI and in reviewing the contract with fresh eyes, there are a couple things I'd list:

• function names don't have standardized inputs, sometimes its the userId first, sometimes not, etc. this can be seen in the docs with get-stacker-at-cycle and get-stacking-reward, and makes it a little harder to wire up each function in the UI
  • I think userId should always come first when present, and we could decide a similar hierarchy for all functions to help with consistency
• I'm on the fence if read-only functions should return errors instead of default values, consider something like is-block-winner - it could automatically check if the claim is too soon, and it could check if the user mined in the block. slightly higher execution costs, but using functions that already exist in the contract and provides clearer responses to the UI.
  • One thing that negates this is it's pretty convenient to use the -or-default options in the UI since you can conditionally display something or take an action based on the value coming back as 0.

I'm sure there's more, now at least I have a place to list them as they come up!

[whoabuddy]

Another thought: more printing from the contract. This could be useful in a variety of ways, but one simple idea was printing the number of blocks mined for in a mine-many transaction. Counting the values manually can be a challenge especially on the 150-200 block calls!

[LNow]

I like this idea.
We could also use it for stacking function and print tuple with information about first and last stacking cycle ie.

{ stacking-from: u2, stacking-to: u15 }

[whoabuddy]

Yes, exactly! This type of info could supplement what's available through the API, and help with those using the API to pull data rather than directly calling the contract functions. It'd also be nice to scope out a data model for what's printed so that things stay consistent and are easier to consume.

[whoabuddy]

In v1.0.1 we now have it printing tuples on mining/stacking txs, noting it might be worth adding the total blocks for mine-many. Example:

(tuple (firstBlock u37460) (lastBlock u37541))

change to:

(tuple (totalBlocks u81) (firstBlock u37460) (lastBlock u37541))

[unclemantis]

I have a better and more random way to generate the number used to choose the winner of the block. Will post an example tonight. Just wanted to let you all know.

[Zk2u]

Improved VRF? Let's see :3

[LNow]

@unclemantis have you made any progress with that?

[AP3045]

Hi Gentlemen,

I wanted to leave some feedback from a mining perspective in the event you found it useful. In the current structure based on the sample sets I've reviewed, bidding the top position compared to other miners doesn’t yield a better ratio very often. You’re paying a premium for the increased odds of winning more blocks. That feels like what you’d expect. I believe a small change to this could amplify the use of the Stacks & MIA ecosystem, which clearly revolve around stacks consumption, stacking, and yield. Add a very minor reward for winning a block in the top bid position. This could result in increased competitiveness in mining, increased yield for MIA stackers, and an improved price floor on MIA (from a mining cost perspective) by encouraging higher bids for reasons other than mining for pure cost per unit efficiency. Good or bad, I didn’t want the feedback to go to waste.

Thanks for what you all do on this project.

[whoabuddy]

@FriendsFerdinand asked in Discord why the burn function isn't exposed in the token contract. Originally, it was thought that mint and burn would both only be accessible by the core contract, and at this time burn is not implemented so the only way to effectively do the same thing would be to transfer tokens to a burn address.

One downside is that without burn it will not decrease the total supply returned by get-total-supply, however, this also holds true if tokens are inaccessible due to lost private keys or faulty contract code.

It would be interesting to re-evaluate if burn should be accessible to all rather than guarded, especially if there's a way it could provide added utility. What would be some good use cases for burning a CityCoin?

[FriendsFerdinand]

I just don't see why an owner shouldn't be allowed to burn their own tokens if they wish. It would also make accounting for burned MIA harder because the AssetsMap doesn't get updated automatically.

[whoabuddy]

Users are tracked in the contract and associated with a user ID, but it would be nice if there was some distinction between what different users have done in the contract, e.g.

• did they register in the first 20?
• did they mine at all?
• did they stack at all?

The current implementation was refactored to use a single map for users, and it takes some trickery to try and figure out the information above. Did the user only Stack tokens? Did every registered address mine? etc.

We could look at either adding a data point with boolean values for each action (costs allowing), or modifying it so separate maps are used (but then different IDs?).

Open to more input on this one.

[LNow]

Do you have any specific contract logic that would require such data?

[whoabuddy]

No, it would be for monitoring activity after launch. I'm trying to compile stats and these are the three ways someone can register as a user in the contract.

I could say if userId <= 20 then they registered/activated the contract. After that, it's hard to say whether someone uses the contract to mine, stack, or both.

[FriendsFerdinand]

Maybe I'm not understanding correctly, but the auth contract will have to be upgraded if we want to use the more general arguments, correct? From what I can tell, Jobs can only be used to upgrade the core contract, update the city-wallet and update the approvers' principal.

I am aware of there being a possibility to update the split amount between stackers and the city. So, the way to do this would be to call a jobs-contract that can only be called from auth? Then the jobs contract has ifs that'll match to the function we want to call?

[LNow]

auth contract is not upgradable.

Jobs are empty shells that have name, target and named arguments. They are used to store on-chain information about things that we want to vote on. In case of CityCoins - thing that selected approvers can vote on.
target is a principal that is allowed to mark specific job as executed.

Jobs have no internal logic, no knowledge which function will be used to "execute" them, or anything similar.

You can read more about this concept here: #119

I am aware of there being a possibility to update the split amount between stackers and the city. So, the way to do this would be to call a jobs-contract that can only be called from auth? Then the jobs contract has ifs that'll match to the function we want to call?

At this moment updating the split would be possible only if we would decide to add it to core contract and replace with it the current one ;)
But let's assume we did so and it is possible. Executing such change could look like this:

1. One of the approved wallets would create a job and define which contract is allowed to mark it as executed
2. Same approver would add all arguments needed to execute this job and activate voting on it.
3. Approvers vote on Job
4. If Job got enough approvals, anyone can call a function in target to execute it.

[FriendsFerdinand]

Ok, I get it. I think what was confusing me is that the core contract as it is right now, doesn't use Jobs but in the future it could.

It's very clever. Thank you.

[Zk2u]

important points

• make sure auth is not controlled by 5 admins. it needs to be a dao. complete revamp
• change pox token from stx to native btc, make city wallet a bitcoin wallet instead

[LNow]

How DAO should be formed? How governance tokens should be distributed? Who should get it and how much?

Can you write more about changing the poxl token to BTC? How this would work?

[Zk2u]

spoke to other guys about this. looks like next token (ATX) with be pretty identical to MIA in the GenI citycoins

my points would then regard GenII citycoins. will follow some more details later on

[Zk2u]

important points

• make sure auth is not controlled by 5 admins. it needs to be a dao. complete revamp
• change pox token from stx to native btc, make city wallet a bitcoin wallet instead

[whoabuddy]

Found a tiny inconsistency in get-city-wallet, wondering if there are any others:

in core, returns var

;; returns set city wallet principal
(define-read-only (get-city-wallet)
  (var-get cityWallet)
)

in auth, returns (ok var)

;; returns city wallet principal
(define-read-only (get-city-wallet)
  (ok (var-get cityWallet))
)

From the UI side it's nice if these are consistent across contracts.

[LNow]

Good catch!!
Indeed we should make them consistent with each other.

[friedger]

Keep token in wallet while stacked. The token could be implemented as two native tokens: one for liquid tokens, one for stacked tokens.

[Zk2u]

you disable transfers of the token of the amount they have stacked, keeping token in user's wallet but unusable

[whoabuddy]

We had a similar thought, and it could easily be a SIP for delegated FT stacking.

One way could be to track a map of locked vs unlocked tokens per user, and limit the transfer function to only use unlocked tokens.

I'm also curious the best way to track what's stacked when, and return relevant info for the user. We've seen similar challenges with CityCoins and there is probably a nice balance between data storage, execution costs, and exposing useful data.

[friedger]

Use two native tokens that are burnt and minted during stacking and unstacking like https://github.com/friedger/clarity-smart-contracts/blob/master/contracts/tokens/hodl-token.clar

[whoabuddy]

I like that, but what about reporting balance? The balance of one token minus the balance of the other as part of get-balance?

My concern would be wallet support showing more than one token - there's gonna be enough with DEXs and the like coming online, plus all the FRIE action.

[friedger]

Wallets would show liquid tokens and stacked tokens, exactly what I would expect.

[unclemantis]

How would that work?

…

On Sat, Nov 6, 2021, 6:51 PM LNow ***@***.***> wrote: Interesting idea. How would that work? — You are receiving this because you were mentioned. Reply to this email directly, view it on GitHub <#145 (reply in thread)>, or unsubscribe <https://github.com/notifications/unsubscribe-auth/AAFPO3MSYWFDCEQJU26CSC3UKWWNPANCNFSM5DME6POA> .

[whoabuddy]

Adding a comment from 냐아아옹#2481 in Discord:

Suggestion : Hello! when we receive the claim, we have to find the won block and request the claim separately. it is very inconvenient for user. if you can change the system, i suggest to improve the system that we can receive the claim at once.

[whoabuddy]

Adding some comments from Discord regarding stacking/unstacking at will versus the current model with set cycles.

From MattOC#2168

I'm not sure if anyone has asked CC core team this before - but the issue of discrete stacking (ie stacking for 4 cycles) I think is actually a problem for city coins long term adoption and usage.

1. Multiple platforms such as Arkadiko already don't want to add city coins liquidity pools, because the returns from LP pools can't possibly get as high as stacking returns, so who would provide liquidity when they can stack? Either you want to buy CC, sell CC, or stack CC - but you won't ever make expected higher returns to post both CC and STX in AMM LP pools than to stack them.

2. When your city coins are stacked, you may still want to be able to use them for tools cities are building such as voter engagement platforms, city governance votes, etc

So currently, both liquidity and utility are mutually exclusive with stacking - a way to fix this would be a Lido type platform for STX, where someone deposits a token to a smart contract vault which stacks it, and issues a "st" stacked token (ie stNYC) on 1:1 basis, which can redeemed for the underlying token at any time. This allows for both utility and liquidity of stacked assets.

That said, to work with such a model, CC's current discrete stacking model would require either:
i) issuing a different stToken for each unique combination of asset and unlock block, -or-
ii) have users sometime encounter a situation where stToken's are not available to immediately redeem

Both those are rather terrible user experiences, but neither of these problem exist if city coins is can be stacked/unstacked whenever someone wants.

[cargocultscience]

One possible thought, what if we leave the existing mechanics largely in place (stacking duration, number of cycles, etc) and issue stCC when a person locks up for N cycles. This stCC would only be used on the last claim that does the unlock of the CC itself and sent into the contract. This would then allow for stCC to be used in a continuous fashion (eg LPs and loans) in aggregate since there are a large number of ecosystem players which would presumably all be on differing cycle end locks.