{"id":13731642,"url":"https://github.com/onflow/flow-core-contracts","last_synced_at":"2025-05-16T18:04:05.358Z","repository":{"id":37020225,"uuid":"274220376","full_name":"onflow/flow-core-contracts","owner":"onflow","description":"Cadence smart contracts that define core functionality of the Flow protocol","archived":false,"fork":false,"pushed_at":"2025-03-13T15:46:24.000Z","size":14024,"stargazers_count":88,"open_issues_count":16,"forks_count":50,"subscribers_count":42,"default_branch":"master","last_synced_at":"2025-04-12T16:53:42.067Z","etag":null,"topics":["blockchain","cryptocurrency","smart-contracts"],"latest_commit_sha":null,"homepage":"https://onflow.org","language":"Go","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"unlicense","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/onflow.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":"CODE_OF_CONDUCT.md","threat_model":null,"audit":null,"citation":null,"codeowners":".github/CODEOWNERS","security":"SECURITY.md","support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2020-06-22T19:03:37.000Z","updated_at":"2025-03-07T15:06:21.000Z","dependencies_parsed_at":"2023-01-17T13:45:24.665Z","dependency_job_id":"3a06e352-3550-428b-940a-3e612e502ce8","html_url":"https://github.com/onflow/flow-core-contracts","commit_stats":null,"previous_names":[],"tags_count":84,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/onflow%2Fflow-core-contracts","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/onflow%2Fflow-core-contracts/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/onflow%2Fflow-core-contracts/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/onflow%2Fflow-core-contracts/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/onflow","download_url":"https://codeload.github.com/onflow/flow-core-contracts/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":254582902,"owners_count":22095518,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["blockchain","cryptocurrency","smart-contracts"],"created_at":"2024-08-03T02:01:34.647Z","updated_at":"2025-05-16T18:04:05.245Z","avatar_url":"https://github.com/onflow.png","language":"Go","funding_links":[],"categories":["Go"],"sub_categories":[],"readme":"# Flow Core Smart Contracts\n\nThese are the smart contracts that define the core functionality of the Flow protocol.\n\nThe version of the contracts in the `master` branch is the\nCadence 1.0 version of the contracts and is not the same\nas the ones that are currently deployed to testnet and mainnet.\nSee the `cadence-0.42` branch for the currently deployed versions.\n\n# What is Flow?\n\nFlow is a new blockchain for open worlds. Read more about it [here](https://www.onflow.org/).\n\n# What is Cadence?\n\nCadence is a new Resource-oriented programming language\nfor developing smart contracts for the Flow Blockchain.\nRead more about it [here](https://www.docs.onflow.org)\n\nWe recommend that anyone who is reading this should have already\ncompleted the [Cadence Tutorials](https://docs.onflow.org/docs/getting-started-1)\nso they can build a basic understanding of the programming language.\n\n## FlowToken\n\n`contracts/FlowToken.cdc`\n\n| Network  | Contract Address     |\n| ---------| -------------------- |\n| Emulator | `0x0ae53cb6e3f42a79` |\n| Testnet  | `0x7e60df042a9c0868` |\n| Mainnet  | `0x1654653399040a61` |\n\nThis is the contract that defines the network token for Flow.\nThis token is used for account creation fees, transaction fees, staking, and more. It is\nimplemented as a regular smart contract so that it can be easily used\njust like any other token in the network. See the [flow fungible token repository](https://github.com/onflow/flow-ft)\nfor more information.\n\nYou can find transactions for using the Flow Token in the `transactions/flowToken` directory.\n\n## Flow Transaction Fee Contract\n\n`contracts/FlowFees.cdc`\n\n| Network  | Contract Address     |\n| ---------| -------------------- |\n| Emulator | `0xe5a8b7f23e8b548f` |\n| Testnet  | `0x912d5440f7e3769e` |\n| Mainnet  | `0xf919ee77447b7497` |\n\nThis contract defines fees that are spent for executing transactions and creating accounts.\n\n## Storage Fee Contract\n\n`contracts/FlowStorageFees.cdc`\n\n| Network  | Contract Address     |\n| ---------| -------------------- |\n| Emulator | `0xf8d6e0586b0a20c7` |\n| Testnet  | `0x8c5303eaa26202d6` |\n| Mainnet  | `0xe467b9dd11fa00df` |\n\nThis contract defines fees that are spent to pay for the storage that an account uses.\nThere is a minimum balance that an account needs to maintain in its main `FlowToken` Vault\nin order to pay for the storage it uses.\nYou can see [more docs about storage capacity and fees here.](https://docs.onflow.org/concepts/storage/#overview)\n\n## Service Account Contract\n\n`contracts/FlowServiceAccount.cdc`\n\n| Network  | Contract Address     |\n| ---------| -------------------- |\n| Emulator | `0xf8d6e0586b0a20c7` |\n| Testnet  | `0x8c5303eaa26202d6` |\n| Mainnet  | `0xe467b9dd11fa00df` |\n\nThis contract manages account creation and flow token initialization. It enforces temporary\nrequirements for which accounts are allowed to create other accounts, and provides common\nfunctionality for flow tokens.\n\nYou can find transactions for interacting with the service account contract in the `transactions/FlowServiceAccount` directory.\n\n## Random Beacon History Contract\n\n`contracts/RandomBeaconHistory.cdc`\n\n| Network  | Contract Address     |\n| ---------| -------------------- |\n| Emulator | `0xf8d6e0586b0a20c7` |\n| Testnet  | `0x8c5303eaa26202d6` |\n| Mainnet  | `0xe467b9dd11fa00df` |\n\nThis contract stores the history of random sources generated by\nthe Flow network. The defined Heartbeat resource is\nupdated by the Flow Service Account at the end of every block\nwith that block's source of randomness.\n\nYou can find transactions for interacting with the random beacon\n history contract in the `transactions/randomBeaconHistory` directory.\n\n## Node Version Beacon Contract\n\n`contracts/NodeVersionBeacon.cdc`\n\n| Network  | Contract Address     |\n| ---------| -------------------- |\n| Emulator | `0xf8d6e0586b0a20c7` |\n| Testnet  | `0x8c5303eaa26202d6` |\n| Mainnet  | `0xe467b9dd11fa00df` |\n\nThe `NodeVersionBeacon` contract holds the past\nand future protocol versions that should be used\nto execute/handle blocks at a given block height.\n\nYou can find transactions for interacting with the node version beacon\nhistory contract in the `transactions/nodeVersionBeacon` directory.\n\n## Flow Epochs, Identity Table, and Staking Contracts\n\n`contracts/FlowIDTableStaking.cdc`\n`contracts/epochs/FlowEpoch.cdc`\n\n| Network  | Contract Address     |\n| ---------| -------------------- |\n| Emulator | `0xf8d6e0586b0a20c7` |\n| Testnet  | `0x9eca2b38b18b5dfe` |\n| Mainnet  | `0x8624b52f9ddcd04a` |\n\nThese contract manages the list of identities that correspond to node operators in the Flow network\nas well as the process for adding and removing nodes from the network via Epochs.\nEach node identity stakes tokens with these contracts, and also gets paid rewards with their contracts.\nThis contract also manages the logic for users to delegate their tokens to a node operator\nand receive their own rewards. You can see an explanation of this process in the staking section\nof the [Flow Docs website](https://docs.onflow.org/token/staking/).\n\nYou can find all the transactions for interacting with the IDTableStaking contract with unlocked FLOW\nin the `transactions/idTableStaking` directory, though it is recommended to use the staking collection\ntransactions instead. These are described in the \"Flow Staking Collection\" section below.\n\nYou can also find transactions and scripts for interacting\nwith all the epoch smart contracts in the following directories:\n`transactions/epoch/`\n`transactions/dkg/`\n`transactions/quorumCertificate/`\n\nYou can also find scripts for querying info about staking and stakers in the `transactions/idTableStaking/scripts/` directory.\nThese scripts are documented in the [staking scripts section of the docs](https://docs.onflow.org/staking/scripts/)\n\n## Flow Locked Tokens contract\n\n`contracts/LockedTokens.cdc`\n\n| Network  | Contract Address     |\n| ---------| -------------------- |\n| Emulator | `0xf8d6e0586b0a20c7` |\n| Testnet  | `0x95e019a17d0e23d7` |\n| Mainnet  | `0x8d0e87b65159ae63` |\n\nThis contract manages the two year lockup of Flow tokens that backers purchased in the initial\ntoken sale in October of 2020. See more documentation about `LockedTokens` [here.](https://docs.onflow.org/flow-token/locked-account-setup/)\n\n## Flow Staking Collection Contract\n\n`contracts/FlowStakingCollection.cdc`\n\nThe `StakingCollection` contract has the same import addresses\nas the `LockedTokens` contract on all the networks.\n\nA Staking Collection is a resource that allows its owner to manage multiple staking\nobjects in a single account via a single storage path, and perform staking and delegation actions using both locked and unlocked Flow.\n\nBefore the staking collection, accounts could use the instructions in [the unlocked staking guide](https://docs.onflow.org/staking/unlocked-staking-guide/)\nto stake with tokens. This was a bit restrictive, because that guide (and the corresponding transactions) only supports one node and one delegator object\nper account. If a user wanted to have more than one per account, they would either have to use custom transactions with custom storage paths for each object,\nor they would have had to use multiple accounts, which comes with many hassles of its own.\n\nThe same applies to the [locked tokens staking guide](https://docs.onflow.org/staking/locked-staking-guide/).\nWe only built in support for one node and one delegator per account.\n\nThe staking collection is a solution to both of these deficiencies. When an account is set up to use a staking collection,\nthe staking collection recognizes the existing locked account capabilities (if they exist) and unlocked account staking objects,\nand incorporates their functionality so any user can stake for a node or delegator through a single common interface, regardless of\nif they have a brand new account, or have been staking through the locked account or unlocked account before.\n\n### Is the staking collection mandatory\n\nFlow Port uses staking collection transaction by default other services are encouraged\nto use it instead of any of the other account staking setups.\nIf you provide a staking service for [Ledger](https://www.ledger.com/) or [Blocto](https://blocto.io/download) users, you will need to upgrade\nto this if you want to give your users access to the entire functionality of their account\nif they are also using Flow Port. If their entire interaction with staking is through Flow Port,\nthen all the changes are handled for them and there is nothing for you to worry about.\n\n### Staking Collection Technical features\n\n* The staking collection contract stores [a dictionary of staking objects](https://github.com/onflow/flow-core-contracts/blob/master/contracts/FlowStakingCollection.cdc#L68) from the staking contract that are used to manage the stakers tokens. Since they are dictionaries, there can be as many node or delegator objects per account as the user wants.\n* The resource only has one set of staking methods, which route the call to the correct staking object based on the arguments that the caller specifies. (nodeID, delegatorID)\n* The contract also stores an [optional capability to the locked token vault](https://github.com/onflow/flow-core-contracts/blob/master/contracts/FlowStakingCollection.cdc#L63) and [locked tokens `TokenHolder` resource](https://github.com/onflow/flow-core-contracts/blob/master/ontracts/FlowStakingCollection.cdc#L73). This is only used if the user already has a locked account. The staking collection does not change the locked account setup at all, it only has access to it and to the locked vault.\n* The collection makes the staking objects and vault capability fields private, because since it has access to the locked tokens, it needs to mediate access to the staking objects so users cannot withdraw tokens that are still locked from the sale. The resource has fields `unlockedTokensUsed` and `lockedTokensUsed`, to keep track of how many locked and unlocked tokens are being used for staking in order to allow the user to withdraw the correct amount when they choose to.\n* The staking collection contract is a brand new contract that will be deployed to the same account as the existing locked tokens contract. A few of the fields on the `LockedTokens` contract have been updated to have `access(account)` visibility instead of `access(self)` because the staking collection contract needs to be able to access to them in order to work properly.\n* We also included a public interface and getters in the contract so you can easily query it with an address to get node or delegator information from a collection.\n\nLooking for feedback on design decisions, implementation details, any events that would be useful to include in the contract, and whatever you feel is important!\n\nWe intend for this to be the method that all Flow Port users (ledger, blocto, etc) use for the forseeable future. When we enable it in Flow Port, we will ask every user to run a transaction to set up their account to use the staking collection from then on.\n\n## Linear Code Address Generator\n\n`contracts/LinearCodeAddressGenerator.cdc`\n\nThe linear code address generator contract allows translating an address index to an address,\nand and address back to an address index.\nIt implements the same address generation logic as used on all Flow networks.\n\n# Testing\n\nTo run the tests in the repo, use `make test`.\n\nThese tests need to utilize the transaction templates that are contained in `transactions/`.\n\n# Audit\n\nFlow Core Contracts were audited by Quantstamp in July 2021: [final report](https://certificate.quantstamp.com/full/epoch-functionality-contracts.pdf).\n\n# Getting Transaction Templates\n\nIf you need to use the contracts and transaction templates we have provided in an app, you don't necessarily\nneed to copy and paste them into your code. We plan on providing packages for different\nlanguages to import in order to use the transactions instead of copying and pasting.\n\nWe currently include the `lib/go/templates` package for getting templates in the Go programming language.\nTo use this package, run `go get github.com/onflow/flow-core-contracts/lib/go/templates@{latest version}`\nin your Go project direcory. To use it in your Go code, you can simply call one of the many\ntemplate getters in one of the `*_templates.go` files.\n\n### Packages in other languages\n\nWe would like to add new packages for other popular languages to get transaction templates.\nIf you would like to contribute to add one of these new packages, please reach out\nto the team and we would be happy to help!\n\n## License\n\nThe works in these folders are under the [Unlicense](https://github.com/onflow/flow-core-contracts/blob/master/LICENSE):\n\n- [src/contracts](https://github.com/onflow/flow-core-contracts/tree/master/contracts)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fonflow%2Fflow-core-contracts","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fonflow%2Fflow-core-contracts","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fonflow%2Fflow-core-contracts/lists"}