# Stacking ## Overview Anyone can create a user interface for Stacking CityCoins, one example being [minecitycoins.com](https://minecitycoins.com). Stacking CityCoins happens by calling the contract function [`stack-tokens`](#stack-tokens). {% hint style="warning" %} You cannot Stack in the currently active reward cycle, only for the next reward cycle. *e.g. if you select to Stack in a block height in reward cycle 1 then Stacking will begin in reward cycle 2.* {% endhint %} A nominal transaction fee is required in order to send this transaction, paid in STX. ## Details The current reward cycle for a given block height can be found by calling [`get-reward-cycle`](#get-reward-cycle) in the core contract and supplying the block height. Stacking statistics for a given cycle are available through [`get-stacking-stats-at-cycle`](#get-stacking-stats-at-cycle), and individual account Stacking details are available through [`get-stacker-at-cycle`](#get-stacker-at-cycle). {% hint style="info" %} Both functions for Stacking information also include a `-or-default` version that returns empty default values instead of `some` or `none` Clarity types. {% endhint %} To Stack CityCoins for a user with `stack-tokens`: * enter the amount of CityCoins to Stack * enter the number of reward cycles to Stack for * submit the transaction to the smart contract ## Contract Functions ### [API Ref: Stacking](https://api.citycoins.co/docs#tag/Stacking) ### get-stacking-stats-at-cycle Type: Read-only Function Input: `rewardCycle as uint` Returns: `(some StackingStatsAtCycle) as a tuple` or `(none)` Returns the stacking stats at a given reward cycle, including: * `amountUstx` - total rewards from miners in uSTX * `amountToken` - total CityCoins Stacked ### get-stacking-stats-at-cycle-or-default Type: Read-only Function Input: `rewardCycle as uint` Returns: `(some StackingStatsAtCycle) as a tuple, or defaults` Returns the same as `get-stacking-stats-at-cycle` above, except if no entry is found, returns the default structure of: * `amountUstx: 0` * `amountToken: 0` ### get-stacker-at-cycle Type: Read-only Function Input: `rewardCycle as uint` and `userId as uint` Returns: `(some StackerAtCycle) as a tuple` or `(none)` Returns the stacking stats for a given user ID and reward cycle, including: * `amountStacked` - the total amount of CityCoins Stacked * `toReturn` - the total amount of CityCoins that can be reclaimed from the contract ### get-stacker-at-cycle-or-default Type: Read-only Function Input: `rewardCycle as uint` and `userId as uint` Returns: `(some StackerAtCycle) as a tuple, or defaults` Returns the same as `get-stacker-at-cycle` above, except if no entry is found, returns the default structure of: * `amountStacked: 0` * `toReturn: 0` ### get-reward-cycle Type: Read-only Function Input: `stacksHeight as uint` Returns: `(some rewardCycle) as uint` or `(none)` Returns the active reward cycle for a given block height. ### stacking-active-at-cycle Type: Read-only Function Input: `rewardCycle as uint` Returns: `true` or `false` Returns a boolean value indicating if stacking is active at a given reward cycle, meaning a positive number of CityCoins are Stacked for that cycle. ### get-first-stacks-block-in-reward-cycle Type: Read-only Function Input: `rewardCycle as uint` Returns: `firstBlockInCycle as uint` Returns the starting Stacks block height for a given reward cycle. ### stack-tokens Type: Public Function Input: `amountTokens as uint` and `lockPeriod as uint` Success: `(ok true)` Errors: * `ERR_CONTRACT_NOT_ACTIVATED u1005` * `ERR_STACKING_NOT_AVAILABLE u1015` * `ERR_CANNOT_STACK u1016` Stacking happens through calling the `stack-tokens` function in the contract, which accepts an amount of CityCoins to Stack in addition to a number of reward cycles to Stack them for. --- # 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/stacking.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.