# Mining ## Overview Anyone can create a user interface for mining a CityCoin, one examples being [minecitycoins.com](https://minecitycoins.com). Mining CityCoins happens by calling one of two functions in the contract: [`mine-tokens`](#mine-tokens) and [`mine-many`](#mine-many). {% hint style="warning" %} Miners can only participate once per block. Once STX are sent for mining a CityCoin **they are not returned,** they are distributed to the city's wallet and CityCoin Stackers. {% endhint %} A nominal transaction fee is required in order to send this transaction, paid in STX, and in a single mining transaction you can optionally include a memo that will be recorded on-chain. ## Details To mine for a single block with `mine-tokens`: * enter the amount you would like to bid for the block * (optionally) enter a memo to be recorded on chain * submit the transaction to the smart contract To mine for multiple blocks with `mine-many`: * select the number of blocks you would like to mine for * enter the amount for each of the number of blocks selected * submit the transaction to the smart contract ## Contract Functions ### [API Ref: Mining](https://api.citycoins.co/docs#tag/Mining) ### get-mining-stats-at-block Type: Read-only Function Input: `stacksHeight as uint` Returns: `(some MiningStatsAtBlock) as a tuple` or `none` Returns the mining stats at a given block height, including: * `minersCount` - total miners * `amount` - total amount committed * `amountToCity` - amount transferred to city wallet * `amountToStackers` - amount transferred to $MIA Stackers * `rewardClaimed` - true/false if reward was claimed ### get-mining-stats-at-block-or-default Type: Read-only Function Input: `stacksHeight as uint` Returns: `(some MiningStatsAtBlock) as a tuple, or defaults` Returns the same as `get-mining-stats-at-block` above, except if no entry is found, returns the default structure of: * `minersCount: 0` * `amount: 0` * `amountToCity: 0` * `amountToStackers: 0` * `rewardClaimed: false` ### has-mined-at-block Type: Read-only Function Input: `stacksHeight as uint` and `userId as uint` Returns: `true` or `false` Returns a boolean value indicating if the user's ID mined at a given block height. ### get-miner-at-block Type: Read-only Function Input: `stacksHeight as uint` and `userId as uint` Returns: `(some MinersAtBlock) as a tuple` or `(none)` Returns the mining stats for a given user ID and block height, including: * `ustx` - total commitment in uSTX * `lowValue` - used by VRF to determine winner * `highValue` - used by VRF to determine winner * `winner` - true/false updated *after* miner claims the reward ### get-miner-at-block-or-default Type: Read-only Function Input: `stacksHeight as uint` and `userId as uint` Returns: `(some MinersAtBlock) as a tuple, or defaults` Returns the same as `get-miner-at-block` above, except if no entry is found, returns the default structure of: * `ustx: 0` * `lowValue: 0` * `highValue: 0` * `winner: false` ### get-last-high-value-at-block Type: Read-only Function Input: `stacksHeight as uint` Returns:`highValue as uint, or default (u0)` Returns the last high value at a given block height, which is incremented with each miners' total commitment. ### get-block-winner-id Type: Read-only Function Input: `stacksHeight as uint` Returns: `(some userId) as uint` or `none` Returns the user ID of the block winner *after* the miner claims the reward. ### mine-tokens Type: Public Function Input: `amountUstx as uint` and `memo as buff 34 (optional)` Success: `(ok true)` Errors: * `ERR_CONTRACT_NOT_ACTIVATED u1005` * `ERR_USER_ALREADY_MINED u1006` * `ERR_INSUFFICIENT_COMMITMENT u1007` * `ERR_INSUFFICIENT_BALANCE u1008` * `ERR_STACKING_NOT_AVAILABLE u1015` Mining for a single block happens through calling the `mine-tokens` function in the contract, which optionally accepts up to 34 characters as a memo to record on-chain. ### mine-many Type: Public Function Input: `amounts as list of uints, up to 200` Success: `(ok true)` Errors: * `ERR_CONTRACT_NOT_ACTIVATED u1005` * `ERR_USER_ALREADY_MINED u1006` * `ERR_INSUFFICIENT_COMMITMENT u1007` * `ERR_INSUFFICIENT_BALANCE u1008` * `ERR_STACKING_NOT_AVAILABLE u1015` Mining for many blocks happens through calling the `mine-many` function in the contract, which accepts a list of amounts up to 200 items in length. --- # Agent Instructions: Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter: ``` GET https://docs.citycoins.co/contract-functions/mining.md?ask= ``` The question should be specific, self-contained, and written in natural language. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.