From 0d62effab9061a192427c6625454dbf9c2c21579 Mon Sep 17 00:00:00 2001 From: bilal Date: Tue, 19 Dec 2023 12:29:04 -0500 Subject: [PATCH] Revert "Add crescendo network" --- .gitignore | 8 +- .../node-ops/nodes/node-operation/FAQ.md | 2 +- .../nodes/node-operation/access-node-setup.md | 2 +- .../machine-existing-operator.md | 2 +- .../nodes/node-operation/node-bootstrap.md | 2 +- .../staking/05-epoch-scripts-events.md | 8 +- .../staking/07-staking-scripts-events.md | 26 +- docs/architecture/staking/09-qc-dkg.md | 10 +- .../staking/10-qc-dkg-scripts-events.md | 18 +- .../staking/11-machine-account.md | 2 +- .../staking/14-staking-collection.md | 50 +- docs/architecture/staking/15-staking-guide.md | 30 +- docs/architecture/staking/index.md | 2 +- .../advanced-concepts/account-abstraction.md | 2 +- .../build/advanced-concepts/metadata-views.md | 2 +- docs/build/basics/blocks.md | 2 +- docs/build/basics/events.md | 2 +- docs/build/basics/fees.md | 2 +- docs/build/flow.md | 6 +- docs/build/guides/nft.md | 6 +- .../best-practices/anti-patterns.md | 8 +- .../best-practices/design-patterns.md | 2 +- .../best-practices/security-best-practices.md | 10 +- docs/build/smart-contracts/deploying.md | 2 +- docs/build/smart-contracts/overview.md | 8 +- docs/build/smart-contracts/testing.md | 2 +- docs/reference/_category_.yml | 2 - .../flow-networks/accessing-crescendo.md | 58 -- docs/reference/flow-networks/index.md | 26 - docs/reference/index.md | 8 - docs/references/_category_.yml | 2 + .../core-contracts/02-fungible-token.md | 1 - .../core-contracts/03-flow-token.md | 1 - .../core-contracts/04-service-account.md | 0 .../core-contracts/05-flow-fees.md | 0 .../06-staking-contract-reference.md | 0 .../07-epoch-contract-reference.md | 0 .../core-contracts/08-non-fungible-token.md | 0 .../core-contracts/09-nft-metadata.md | 0 .../core-contracts/10-nft-storefront.md | 0 .../core-contracts/11-staking-collection.md | 0 .../core-contracts/flow-ecosystem.png | Bin .../flow-ft/ExampleToken/ExampleToken.md | 160 +++++ .../ExampleToken_Administrator.md | 33 + .../ExampleToken/ExampleToken_Burner.md | 24 + .../ExampleToken/ExampleToken_Minter.md | 34 + .../ExampleToken/ExampleToken_Vault.md | 96 +++ .../flow-ft/FungibleToken/FungibleToken.md | 121 ++++ .../FungibleToken/FungibleToken_Balance.md | 40 ++ .../FungibleToken/FungibleToken_Provider.md | 41 ++ .../FungibleToken/FungibleToken_Receiver.md | 27 + .../FungibleToken/FungibleToken_Vault.md | 49 ++ .../FungibleTokenMetadataViews.md | 133 ++++ .../FungibleTokenMetadataViews_FTDisplay.md | 30 + .../FungibleTokenMetadataViews_FTVaultData.md | 34 + .../FungibleTokenMetadataViews_FTView.md | 22 + .../FungibleTokenSwitchboard.md | 91 +++ .../FungibleTokenSwitchboard_Switchboard.md | 144 +++++ ...gibleTokenSwitchboard_SwitchboardPublic.md | 35 + .../core-contracts/flow-ft/index.md | 2 +- .../core-contracts/flow-ft/overview.md | 208 ------ .../flow-nft/ExampleNFT/ExampleNFT.md | 128 ++++ .../ExampleNFT/ExampleNFT_Collection.md | 112 ++++ .../ExampleNFT_ExampleNFTCollectionPublic.md | 41 ++ .../flow-nft/ExampleNFT/ExampleNFT_NFT.md | 63 ++ .../ExampleNFT/ExampleNFT_NFTMinter.md | 27 + .../flow-nft/MetdataViews/MetadataViews.md | 604 ++++++++++++++++++ .../MetdataViews/MetadataViews_Display.md | 23 + .../MetdataViews/MetadataViews_Edition.md | 26 + .../MetdataViews/MetadataViews_Editions.md | 18 + .../MetdataViews/MetadataViews_ExternalURL.md | 20 + .../MetdataViews/MetadataViews_File.md | 18 + .../MetdataViews/MetadataViews_HTTPFile.md | 31 + .../MetdataViews/MetadataViews_IPFSFile.md | 40 ++ .../MetdataViews/MetadataViews_License.md | 19 + .../MetdataViews/MetadataViews_Media.md | 20 + .../MetdataViews/MetadataViews_Medias.md | 18 + .../MetadataViews_NFTCollectionData.md | 32 + .../MetadataViews_NFTCollectionDisplay.md | 30 + .../MetdataViews/MetadataViews_NFTView.md | 34 + .../MetdataViews/MetadataViews_Rarity.md | 24 + .../MetdataViews/MetadataViews_Resolver.md | 27 + .../MetadataViews_ResolverCollection.md | 25 + .../MetdataViews/MetadataViews_Royalties.md | 32 + .../MetdataViews/MetadataViews_Royalty.md | 23 + .../MetdataViews/MetadataViews_Serial.md | 22 + .../MetdataViews/MetadataViews_Trait.md | 26 + .../MetdataViews/MetadataViews_Traits.md | 33 + .../NonFungibleToken/NonFungibleToken.md | 143 +++++ .../NonFungibleToken_Collection.md | 56 ++ .../NonFungibleToken_CollectionPublic.md | 42 ++ .../NonFungibleToken/NonFungibleToken_INFT.md | 42 ++ .../NonFungibleToken/NonFungibleToken_NFT.md | 15 + .../NonFungibleToken_Provider.md | 23 + .../NonFungibleToken_Receiver.md | 21 + .../core-contracts/flow-nft/index.md | 2 +- .../core-contracts/flow-nft/overview.md | 381 ----------- .../core-contracts/index.md | 7 +- .../core-contracts/scenario_1.png | Bin .../core-contracts/token-allocation.png | Bin .../core-contracts/token-distribution.png | Bin .../flow-networks/accessing-mainnet.md | 6 +- .../flow-networks/accessing-testnet.md | 4 +- docs/references/flow-networks/index.md | 18 + .../flow-networks/port-sealed-tx.png | Bin docs/{reference => references}/governance.md | 0 docs/references/index.md | 25 + docs/references/run-and-secure/_category_.yml | 5 + .../run-and-secure/nodes}/faq/_category_.json | 0 .../run-and-secure/nodes}/faq/backers.md | 4 +- .../run-and-secure/nodes}/faq/developers.md | 20 +- .../run-and-secure/nodes}/faq/operators.md | 16 +- .../run-and-secure/nodes}/flow-port/index.md | 12 +- .../nodes}/flow-port/machine-account.png | Bin .../nodes}/flow-port/port-delegate-1.png | Bin .../nodes}/flow-port/port-delegate-2.png | Bin .../nodes}/flow-port/port-delegate-3.png | Bin .../nodes}/flow-port/port-delegate-4.png | Bin .../nodes}/flow-port/port-stake-0-00.png | Bin .../nodes}/flow-port/port-stake-0-01.png | Bin .../nodes}/flow-port/port-stake-0-02.png | Bin .../nodes}/flow-port/port-stake-0-03.png | Bin .../nodes}/flow-port/port-stake-0-04.png | Bin .../nodes}/flow-port/port-stake-0-05.png | Bin .../nodes}/flow-port/port-stake-0-06.png | Bin .../nodes}/flow-port/port-stake-1.png | Bin .../nodes}/flow-port/port-stake-2.png | Bin .../nodes}/flow-port/port-stake-3.png | Bin .../nodes}/flow-port/port-stake-4.png | Bin .../nodes}/flow-port/port-stake-5.png | Bin .../nodes}/flow-port/port-stake-6.png | Bin .../nodes}/flow-port/staking-collection.png | Bin .../nodes}/flow-port/staking-guide.md | 12 +- docs/tools/clients/flow-go-sdk/index.mdx | 2 +- .../tools/flow-cli/flow.json/configuration.md | 2 +- docs/tutorials/smart-contracts.md | 8 +- docusaurus.config.js | 8 +- sidebars.js | 53 +- src/data/data-sources.json | 4 +- vercel.json | 56 +- 140 files changed, 3225 insertions(+), 916 deletions(-) delete mode 100644 docs/reference/_category_.yml delete mode 100644 docs/reference/flow-networks/accessing-crescendo.md delete mode 100644 docs/reference/flow-networks/index.md delete mode 100644 docs/reference/index.md create mode 100644 docs/references/_category_.yml rename docs/{reference => references}/core-contracts/02-fungible-token.md (96%) rename docs/{reference => references}/core-contracts/03-flow-token.md (99%) rename docs/{reference => references}/core-contracts/04-service-account.md (100%) rename docs/{reference => references}/core-contracts/05-flow-fees.md (100%) rename docs/{reference => references}/core-contracts/06-staking-contract-reference.md (100%) rename docs/{reference => references}/core-contracts/07-epoch-contract-reference.md (100%) rename docs/{reference => references}/core-contracts/08-non-fungible-token.md (100%) rename docs/{reference => references}/core-contracts/09-nft-metadata.md (100%) rename docs/{reference => references}/core-contracts/10-nft-storefront.md (100%) rename docs/{reference => references}/core-contracts/11-staking-collection.md (100%) rename docs/{reference => references}/core-contracts/flow-ecosystem.png (100%) create mode 100644 docs/references/core-contracts/flow-ft/ExampleToken/ExampleToken.md create mode 100644 docs/references/core-contracts/flow-ft/ExampleToken/ExampleToken_Administrator.md create mode 100644 docs/references/core-contracts/flow-ft/ExampleToken/ExampleToken_Burner.md create mode 100644 docs/references/core-contracts/flow-ft/ExampleToken/ExampleToken_Minter.md create mode 100644 docs/references/core-contracts/flow-ft/ExampleToken/ExampleToken_Vault.md create mode 100644 docs/references/core-contracts/flow-ft/FungibleToken/FungibleToken.md create mode 100644 docs/references/core-contracts/flow-ft/FungibleToken/FungibleToken_Balance.md create mode 100644 docs/references/core-contracts/flow-ft/FungibleToken/FungibleToken_Provider.md create mode 100644 docs/references/core-contracts/flow-ft/FungibleToken/FungibleToken_Receiver.md create mode 100644 docs/references/core-contracts/flow-ft/FungibleToken/FungibleToken_Vault.md create mode 100644 docs/references/core-contracts/flow-ft/FungibleTokenMetadataViews/FungibleTokenMetadataViews.md create mode 100644 docs/references/core-contracts/flow-ft/FungibleTokenMetadataViews/FungibleTokenMetadataViews_FTDisplay.md create mode 100644 docs/references/core-contracts/flow-ft/FungibleTokenMetadataViews/FungibleTokenMetadataViews_FTVaultData.md create mode 100644 docs/references/core-contracts/flow-ft/FungibleTokenMetadataViews/FungibleTokenMetadataViews_FTView.md create mode 100644 docs/references/core-contracts/flow-ft/FungibleTokenSwitchboard/FungibleTokenSwitchboard.md create mode 100644 docs/references/core-contracts/flow-ft/FungibleTokenSwitchboard/FungibleTokenSwitchboard_Switchboard.md create mode 100644 docs/references/core-contracts/flow-ft/FungibleTokenSwitchboard/FungibleTokenSwitchboard_SwitchboardPublic.md rename docs/{reference => references}/core-contracts/flow-ft/index.md (99%) delete mode 100644 docs/references/core-contracts/flow-ft/overview.md create mode 100644 docs/references/core-contracts/flow-nft/ExampleNFT/ExampleNFT.md create mode 100644 docs/references/core-contracts/flow-nft/ExampleNFT/ExampleNFT_Collection.md create mode 100644 docs/references/core-contracts/flow-nft/ExampleNFT/ExampleNFT_ExampleNFTCollectionPublic.md create mode 100644 docs/references/core-contracts/flow-nft/ExampleNFT/ExampleNFT_NFT.md create mode 100644 docs/references/core-contracts/flow-nft/ExampleNFT/ExampleNFT_NFTMinter.md create mode 100644 docs/references/core-contracts/flow-nft/MetdataViews/MetadataViews.md create mode 100644 docs/references/core-contracts/flow-nft/MetdataViews/MetadataViews_Display.md create mode 100644 docs/references/core-contracts/flow-nft/MetdataViews/MetadataViews_Edition.md create mode 100644 docs/references/core-contracts/flow-nft/MetdataViews/MetadataViews_Editions.md create mode 100644 docs/references/core-contracts/flow-nft/MetdataViews/MetadataViews_ExternalURL.md create mode 100644 docs/references/core-contracts/flow-nft/MetdataViews/MetadataViews_File.md create mode 100644 docs/references/core-contracts/flow-nft/MetdataViews/MetadataViews_HTTPFile.md create mode 100644 docs/references/core-contracts/flow-nft/MetdataViews/MetadataViews_IPFSFile.md create mode 100644 docs/references/core-contracts/flow-nft/MetdataViews/MetadataViews_License.md create mode 100644 docs/references/core-contracts/flow-nft/MetdataViews/MetadataViews_Media.md create mode 100644 docs/references/core-contracts/flow-nft/MetdataViews/MetadataViews_Medias.md create mode 100644 docs/references/core-contracts/flow-nft/MetdataViews/MetadataViews_NFTCollectionData.md create mode 100644 docs/references/core-contracts/flow-nft/MetdataViews/MetadataViews_NFTCollectionDisplay.md create mode 100644 docs/references/core-contracts/flow-nft/MetdataViews/MetadataViews_NFTView.md create mode 100644 docs/references/core-contracts/flow-nft/MetdataViews/MetadataViews_Rarity.md create mode 100644 docs/references/core-contracts/flow-nft/MetdataViews/MetadataViews_Resolver.md create mode 100644 docs/references/core-contracts/flow-nft/MetdataViews/MetadataViews_ResolverCollection.md create mode 100644 docs/references/core-contracts/flow-nft/MetdataViews/MetadataViews_Royalties.md create mode 100644 docs/references/core-contracts/flow-nft/MetdataViews/MetadataViews_Royalty.md create mode 100644 docs/references/core-contracts/flow-nft/MetdataViews/MetadataViews_Serial.md create mode 100644 docs/references/core-contracts/flow-nft/MetdataViews/MetadataViews_Trait.md create mode 100644 docs/references/core-contracts/flow-nft/MetdataViews/MetadataViews_Traits.md create mode 100644 docs/references/core-contracts/flow-nft/NonFungibleToken/NonFungibleToken.md create mode 100644 docs/references/core-contracts/flow-nft/NonFungibleToken/NonFungibleToken_Collection.md create mode 100644 docs/references/core-contracts/flow-nft/NonFungibleToken/NonFungibleToken_CollectionPublic.md create mode 100644 docs/references/core-contracts/flow-nft/NonFungibleToken/NonFungibleToken_INFT.md create mode 100644 docs/references/core-contracts/flow-nft/NonFungibleToken/NonFungibleToken_NFT.md create mode 100644 docs/references/core-contracts/flow-nft/NonFungibleToken/NonFungibleToken_Provider.md create mode 100644 docs/references/core-contracts/flow-nft/NonFungibleToken/NonFungibleToken_Receiver.md rename docs/{reference => references}/core-contracts/flow-nft/index.md (99%) delete mode 100644 docs/references/core-contracts/flow-nft/overview.md rename docs/{reference => references}/core-contracts/index.md (79%) rename docs/{reference => references}/core-contracts/scenario_1.png (100%) rename docs/{reference => references}/core-contracts/token-allocation.png (100%) rename docs/{reference => references}/core-contracts/token-distribution.png (100%) rename docs/{reference => references}/flow-networks/accessing-mainnet.md (90%) rename docs/{reference => references}/flow-networks/accessing-testnet.md (92%) create mode 100644 docs/references/flow-networks/index.md rename docs/{reference => references}/flow-networks/port-sealed-tx.png (100%) rename docs/{reference => references}/governance.md (100%) create mode 100644 docs/references/index.md create mode 100644 docs/references/run-and-secure/_category_.yml rename docs/{reference => references/run-and-secure/nodes}/faq/_category_.json (100%) rename docs/{reference => references/run-and-secure/nodes}/faq/backers.md (89%) rename docs/{reference => references/run-and-secure/nodes}/faq/developers.md (93%) rename docs/{reference => references/run-and-secure/nodes}/faq/operators.md (94%) rename docs/{reference => references/run-and-secure/nodes}/flow-port/index.md (92%) rename docs/{reference => references/run-and-secure/nodes}/flow-port/machine-account.png (100%) rename docs/{reference => references/run-and-secure/nodes}/flow-port/port-delegate-1.png (100%) rename docs/{reference => references/run-and-secure/nodes}/flow-port/port-delegate-2.png (100%) rename docs/{reference => references/run-and-secure/nodes}/flow-port/port-delegate-3.png (100%) rename docs/{reference => references/run-and-secure/nodes}/flow-port/port-delegate-4.png (100%) rename docs/{reference => references/run-and-secure/nodes}/flow-port/port-stake-0-00.png (100%) rename docs/{reference => references/run-and-secure/nodes}/flow-port/port-stake-0-01.png (100%) rename docs/{reference => references/run-and-secure/nodes}/flow-port/port-stake-0-02.png (100%) rename docs/{reference => references/run-and-secure/nodes}/flow-port/port-stake-0-03.png (100%) rename docs/{reference => references/run-and-secure/nodes}/flow-port/port-stake-0-04.png (100%) rename docs/{reference => references/run-and-secure/nodes}/flow-port/port-stake-0-05.png (100%) rename docs/{reference => references/run-and-secure/nodes}/flow-port/port-stake-0-06.png (100%) rename docs/{reference => references/run-and-secure/nodes}/flow-port/port-stake-1.png (100%) rename docs/{reference => references/run-and-secure/nodes}/flow-port/port-stake-2.png (100%) rename docs/{reference => references/run-and-secure/nodes}/flow-port/port-stake-3.png (100%) rename docs/{reference => references/run-and-secure/nodes}/flow-port/port-stake-4.png (100%) rename docs/{reference => references/run-and-secure/nodes}/flow-port/port-stake-5.png (100%) rename docs/{reference => references/run-and-secure/nodes}/flow-port/port-stake-6.png (100%) rename docs/{reference => references/run-and-secure/nodes}/flow-port/staking-collection.png (100%) rename docs/{reference => references/run-and-secure/nodes}/flow-port/staking-guide.md (88%) diff --git a/.gitignore b/.gitignore index 928d5618a4..41c4af600a 100644 --- a/.gitignore +++ b/.gitignore @@ -28,9 +28,9 @@ yarn-error.log* /docs/unsorted .idea/ -docs/reference/core-contracts/flow-ft/* -!docs/reference/core-contracts/flow-ft/index.md -docs/reference/core-contracts/flow-nft/* -!docs/reference/core-contracts/flow-nft/index.md +docs/references/core-contracts/flow-ft/* +!docs/references/core-contracts/flow-ft/index.md +docs/references/core-contracts/flow-nft/* +!docs/references/core-contracts/flow-nft/index.md docs/.obsidian diff --git a/docs/architecture/node-ops/nodes/node-operation/FAQ.md b/docs/architecture/node-ops/nodes/node-operation/FAQ.md index 2c7ce1aab3..8278ca2506 100644 --- a/docs/architecture/node-ops/nodes/node-operation/FAQ.md +++ b/docs/architecture/node-ops/nodes/node-operation/FAQ.md @@ -55,7 +55,7 @@ More on this [here](./node-migration.md) ### Where can I find how many nodes are currently running Flow? -If you are running a node, then you most definitely have this information on your node in the file `/public-root-information/node-infos.pub.json`. If you are not running a node, you can find this information by using a Cadence script to query the [Staking Smart Contract](../../../../reference/core-contracts/06-staking-contract-reference.md) (or check [Flowdiver](https://flowdiver.io/staking/overview)) +If you are running a node, then you most definitely have this information on your node in the file `/public-root-information/node-infos.pub.json`. If you are not running a node, you can find this information by using a Cadence script to query the [Staking Smart Contract](../../../../references/core-contracts/06-staking-contract-reference.md) (or check [Flowdiver](https://flowdiver.io/staking/overview)) ### Why do I need to update my node's ulimit? diff --git a/docs/architecture/node-ops/nodes/node-operation/access-node-setup.md b/docs/architecture/node-ops/nodes/node-operation/access-node-setup.md index 078be83302..11c79f33d5 100644 --- a/docs/architecture/node-ops/nodes/node-operation/access-node-setup.md +++ b/docs/architecture/node-ops/nodes/node-operation/access-node-setup.md @@ -152,7 +152,7 @@ All your private keys should be in the `bootstrap` folder created earlier. Pleas You need to now register the node on chain by staking the node via [Flow Port](https://port.onflow.org/). -[Here](../../../../reference/flow-port/staking-guide.md) is a guide on how to use Flow port if you are not familiar with it. +[Here](../../../../references/run-and-secure/nodes/flow-port/staking-guide.md) is a guide on how to use Flow port if you are not familiar with it. If you are staking via a custody provider or would like to directly submit a staking transaction instead follow this [guide](../../../staking/index.md#how-do-i-stake). Fund you Flow account with at least 100.01 FLOW tokens, which covers the required stake plus the storage deposit. diff --git a/docs/architecture/node-ops/nodes/node-operation/machine-existing-operator.md b/docs/architecture/node-ops/nodes/node-operation/machine-existing-operator.md index f5bec328ee..f562eb3495 100644 --- a/docs/architecture/node-ops/nodes/node-operation/machine-existing-operator.md +++ b/docs/architecture/node-ops/nodes/node-operation/machine-existing-operator.md @@ -70,7 +70,7 @@ $tree ./bootstrap/ ## Create Machine Account You will now need to copy the Machine account public key displayed in the terminal output and -head over to [Flow Port](../../../../reference/flow-port/staking-guide.md#existing-node-operators) to submit a transaction to create a Machine Account. +head over to [Flow Port](../../../../references/run-and-secure/nodes/flow-port/staking-guide.md#existing-node-operators) to submit a transaction to create a Machine Account. For example, from the example above, we would copy `f847...` from this line: ```shell Example diff --git a/docs/architecture/node-ops/nodes/node-operation/node-bootstrap.md b/docs/architecture/node-ops/nodes/node-operation/node-bootstrap.md index 10ba2620fe..23cd5846f4 100644 --- a/docs/architecture/node-ops/nodes/node-operation/node-bootstrap.md +++ b/docs/architecture/node-ops/nodes/node-operation/node-bootstrap.md @@ -251,7 +251,7 @@ Ensure you have configured your node using the [Node Setup guide](./node-setup.m ### Confirming authorization -You can confirm your node's successful registration and authorization by executing a Cadence script to query the [Staking Contract](../../../../reference/core-contracts/06-staking-contract-reference.md#contract). +You can confirm your node's successful registration and authorization by executing a Cadence script to query the [Staking Contract](../../../../references/core-contracts/06-staking-contract-reference.md#contract). At the end of the `Staking Auction Phase`, the members of the Proposed Identity Table are confirmed as authorized participants in the next epoch. Therefore, if your node ID appears in the Proposed Identity Table during the `Staking Auction Phase`, your node will be a participant in the next epoch. diff --git a/docs/architecture/staking/05-epoch-scripts-events.md b/docs/architecture/staking/05-epoch-scripts-events.md index 8c088bfaed..db94924df4 100644 --- a/docs/architecture/staking/05-epoch-scripts-events.md +++ b/docs/architecture/staking/05-epoch-scripts-events.md @@ -175,7 +175,7 @@ pub struct EpochMetadata { The `FlowEpoch` smart contract provides a public function, `FlowEpoch.getEpochMetadata()` to query the metadata for a particular epoch. -You can use the **Get Epoch Metadata**([EP.01](../../reference/core-contracts/07-epoch-contract-reference.md#getting-epoch-info)) script +You can use the **Get Epoch Metadata**([EP.01](../../references/core-contracts/07-epoch-contract-reference.md#getting-epoch-info)) script with the following arguments: | Argument | Type | Description | @@ -207,7 +207,7 @@ pub struct Config { } ``` -You can use the **Get Configurable Metadata**([EP.02](../../reference/core-contracts/07-epoch-contract-reference.md#getting-epoch-info)) script +You can use the **Get Configurable Metadata**([EP.02](../../references/core-contracts/07-epoch-contract-reference.md#getting-epoch-info)) script to get the list of configurable metadata: This script does not require any arguments. @@ -216,7 +216,7 @@ This script does not require any arguments. The `FlowEpoch` smart contract always tracks the counter of the current epoch. -You can use the **Get Epoch Counter**([EP.03](../../reference/core-contracts/07-epoch-contract-reference.md#getting-epoch-info)) script +You can use the **Get Epoch Counter**([EP.03](../../references/core-contracts/07-epoch-contract-reference.md#getting-epoch-info)) script to get the current epoch counter. This script does not require any arguments. @@ -233,7 +233,7 @@ pub enum EpochPhase: UInt8 { } ``` -You can use the **Get Epoch Phase**([EP.04](../../reference/core-contracts/07-epoch-contract-reference.md#getting-epoch-info)) script +You can use the **Get Epoch Phase**([EP.04](../../references/core-contracts/07-epoch-contract-reference.md#getting-epoch-info)) script to get the current epoch phase. This script does not require any arguments. \ No newline at end of file diff --git a/docs/architecture/staking/07-staking-scripts-events.md b/docs/architecture/staking/07-staking-scripts-events.md index e56f471ef6..8c3c9258d2 100644 --- a/docs/architecture/staking/07-staking-scripts-events.md +++ b/docs/architecture/staking/07-staking-scripts-events.md @@ -17,7 +17,7 @@ or you can monitor events that are emitted by the staking contract to be notifie `FlowIDTableStaking.getProposedNodeIDs()`: Returns an array of node IDs for proposed nodes. Proposed nodes are nodes that have enough staked and committed for the next epoch to be above the minimum requirement. -You can use the **Get Proposed Table**([SC.05](../../reference/core-contracts/06-staking-contract-reference.md#getting-staking-info)) script for retrieving this info. +You can use the **Get Proposed Table**([SC.05](../../references/core-contracts/06-staking-contract-reference.md#getting-staking-info)) script for retrieving this info. This script requires no arguments. @@ -26,7 +26,7 @@ This script requires no arguments. `FlowIDTableStaking.getStakedNodeIDs()`: Returns an array of nodeIDs that are currently staked. Staked nodes are nodes that currently have staked tokens above the minimum. -You can use the **Get Current Table**([SC.04](../../reference/core-contracts/06-staking-contract-reference.md#getting-staking-info)) script for retrieving this info. +You can use the **Get Current Table**([SC.04](../../references/core-contracts/06-staking-contract-reference.md#getting-staking-info)) script for retrieving this info. This script requires no arguments. @@ -36,14 +36,14 @@ This script requires no arguments. associated with the specified node ID. You can see the `NodeInfo` definition in the [FlowIDTableStaking smart contract.](https://github.com/onflow/flow-core-contracts/blob/master/contracts/FlowIDTableStaking.cdc#L264) -You can use the **Get Node Info**([SC.08](../../reference/core-contracts/06-staking-contract-reference.md#getting-staking-info)) script +You can use the **Get Node Info**([SC.08](../../references/core-contracts/06-staking-contract-reference.md#getting-staking-info)) script with the following arguments: | Argument | Type | Description | | ---------- | -------- | -------------------------------------- | | **nodeID** | `String` | The node ID of the node to search for. | -You can also query the info from an address by using the **Get Node Info From Address**([SC.26](../../reference/core-contracts/06-staking-contract-reference.md#getting-staking-info)) script +You can also query the info from an address by using the **Get Node Info From Address**([SC.26](../../references/core-contracts/06-staking-contract-reference.md#getting-staking-info)) script with the following arguments: | Argument | Type | Description | @@ -55,7 +55,7 @@ with the following arguments: `FlowIDTableStaking.NodeInfo(_ nodeID: String).totalCommittedWithDelegators()`: Returns the total committed balance for a node, which is their total tokens staked + committed, plus all of the staked + committed tokens of all their delegators. -You can use the **Get Node Total Commitment**([SC.09](../../reference/core-contracts/06-staking-contract-reference.md#getting-staking-info)) script +You can use the **Get Node Total Commitment**([SC.09](../../references/core-contracts/06-staking-contract-reference.md#getting-staking-info)) script with the following argument: | Argument | Type | Description | @@ -67,7 +67,7 @@ with the following argument: `FlowIDTableStaking.NodeInfo(_ nodeID: String).totalCommittedWithoutDelegators()`: Returns the total committed balance for a node, which is their total tokens staked + committed, plus all of the staked + committed tokens of all their delegators. -You can use the **Get Only Node Total Commitment**([SC.09](../../reference/core-contracts/06-staking-contract-reference.md#getting-staking-info)) script +You can use the **Get Only Node Total Commitment**([SC.09](../../references/core-contracts/06-staking-contract-reference.md#getting-staking-info)) script with the following argument: | Argument | Type | Description | @@ -80,7 +80,7 @@ with the following argument: associated with the specified node ID and delegator ID. You can see the `DelegatorInfo` definition in the [FlowIDTableStaking smart contract.](https://github.com/onflow/flow-core-contracts/blob/master/contracts/FlowIDTableStaking.cdc#L348) -You can use the **Get Delegator Info**([SC.10](../../reference/core-contracts/06-staking-contract-reference.md#getting-staking-info)) +You can use the **Get Delegator Info**([SC.10](../../references/core-contracts/06-staking-contract-reference.md#getting-staking-info)) script with the following arguments: | Argument | Type | Description | @@ -88,7 +88,7 @@ script with the following arguments: | **nodeID** | `String` | The node ID that the delegator delegates to. | | **delegatorID** | `String` | The ID of the delegator to search for. | -You can also query the info from an address by using the **Get Delegator Info From Address**([SC.27](../../reference/core-contracts/06-staking-contract-reference.md#getting-staking-info)) script +You can also query the info from an address by using the **Get Delegator Info From Address**([SC.27](../../references/core-contracts/06-staking-contract-reference.md#getting-staking-info)) script with the following arguments: | Argument | Type | Description | @@ -99,7 +99,7 @@ with the following arguments: `FlowIDTableStaking.getRewardCutPercentage(): UFix64`: Returns a `UFix64` number for the cut of delegator rewards that each node operator takes. -You can use the **Get Cut Percentage**([SC.01](../../reference/core-contracts/06-staking-contract-reference.md#getting-staking-info)) script to retrieve this info. +You can use the **Get Cut Percentage**([SC.01](../../references/core-contracts/06-staking-contract-reference.md#getting-staking-info)) script to retrieve this info. This script requires no arguments. @@ -108,7 +108,7 @@ This script requires no arguments. `FlowIDTableStaking.getMinimumStakeRequirements(): {UInt8: UFix64}`: Returns a mapping for the stake requirements for each node type. -You can use the **Get stake requirements**([SC.02](../../reference/core-contracts/06-staking-contract-reference.md#getting-staking-info)) script to retrieve this info. +You can use the **Get stake requirements**([SC.02](../../references/core-contracts/06-staking-contract-reference.md#getting-staking-info)) script to retrieve this info. This script requires no arguments. @@ -116,19 +116,19 @@ This script requires no arguments. `FlowIDTableStaking.getEpochTokenPayout(): UFix64`: Returns a `UFix64` value for the total number of FLOW paid out each epoch (week). -You can use the **Get weekly payout**([SC.03](../../reference/core-contracts/06-staking-contract-reference.md#getting-staking-info)) script to retrieve this info. +You can use the **Get weekly payout**([SC.03](../../references/core-contracts/06-staking-contract-reference.md#getting-staking-info)) script to retrieve this info. This script requires no arguments. ## Get the total FLOW staked: -You can use the **Get total FLOW staked**([SC.06](../../reference/core-contracts/06-staking-contract-reference.md#getting-staking-info)) script to retrieve this info. +You can use the **Get total FLOW staked**([SC.06](../../references/core-contracts/06-staking-contract-reference.md#getting-staking-info)) script to retrieve this info. This script requires no arguments. ## Get the total FLOW staked by all the nodes of a single node role: -You can use the **Get total FLOW staked by node type**([SC.07](../../reference/core-contracts/06-staking-contract-reference.md#getting-staking-info)) script +You can use the **Get total FLOW staked by node type**([SC.07](../../references/core-contracts/06-staking-contract-reference.md#getting-staking-info)) script with the following arguments: | Argument | Type | Description | diff --git a/docs/architecture/staking/09-qc-dkg.md b/docs/architecture/staking/09-qc-dkg.md index 238e6a8da8..54c2644551 100644 --- a/docs/architecture/staking/09-qc-dkg.md +++ b/docs/architecture/staking/09-qc-dkg.md @@ -72,14 +72,14 @@ It also creates a machine account for the QC object. If a user already has a registered node with the staking collection, but hasn't created their QC Voter object yet, they can use the [`create_machine_account.cdc` transaction.](./14-staking-collection.md#create-a-machine-account-for-an-existing-node) -If a user is not using the staking collection, they can use the **Create QC Voter** ([QC.01](../../reference/core-contracts/07-epoch-contract-reference.md#quorum-certificate-transactions-and-scripts)) +If a user is not using the staking collection, they can use the **Create QC Voter** ([QC.01](../../references/core-contracts/07-epoch-contract-reference.md#quorum-certificate-transactions-and-scripts)) transaction. This will only store the QC Voter object in the account that stores the `NodeStaker` object. It does not create a machine account or store it elsewhere, so it is not recommended to use. We encourage to use the staking collection instead. ### Submit Vote During the Epoch Setup Phase, the node software should submit the votes for the QC generation -automatically using the **Submit QC Vote** ([QC.02](../../reference/core-contracts/07-epoch-contract-reference.md#quorum-certificate-transactions-and-scripts)) +automatically using the **Submit QC Vote** ([QC.02](../../references/core-contracts/07-epoch-contract-reference.md#quorum-certificate-transactions-and-scripts)) transaction with the following arguments. | Argument | Type | Description | @@ -113,7 +113,7 @@ It also creates a machine account for the DKG Object. If a user already has a registered node with the staking collection, but hasn't created their DKG Participant object yet, they can use the [`create_machine_account.cdc` transaction.](./14-staking-collection.md#create-a-machine-account-for-an-existing-node) -If a user is not using the staking collection, they can use the **Create DKG Participant** ([DKG.01](../../reference/core-contracts/07-epoch-contract-reference.md#dkg-transactions-and-scripts)) +If a user is not using the staking collection, they can use the **Create DKG Participant** ([DKG.01](../../references/core-contracts/07-epoch-contract-reference.md#dkg-transactions-and-scripts)) transaction. This will only store the DKG Participant object in the account that stores the `NodeStaker` object. It does not create a machine account or store it elsewhere, so it is not recommended to use. The staking collection is the recommended method. @@ -121,7 +121,7 @@ The staking collection is the recommended method. ### Post Whiteboard Message During the Epoch Setup Phase, the node software should post whiteboard messages to the DKG -automatically using the **Post Whiteboard Message** ([DKG.02](../../reference/core-contracts/07-epoch-contract-reference.md#dkg-transactions-and-scripts)) +automatically using the **Post Whiteboard Message** ([DKG.02](../../references/core-contracts/07-epoch-contract-reference.md#dkg-transactions-and-scripts)) transaction with the following arguments. | Argument | Type | Description | @@ -131,7 +131,7 @@ transaction with the following arguments. ### Send Final Submission During the Epoch Setup Phase, the node software should send its final submission for the DKG -automatically using the **Send Final Submission** ([DKG.03](../../reference/core-contracts/07-epoch-contract-reference.md#dkg-transactions-and-scripts)) +automatically using the **Send Final Submission** ([DKG.03](../../references/core-contracts/07-epoch-contract-reference.md#dkg-transactions-and-scripts)) transaction with the following arguments. | Argument | Type | Description | diff --git a/docs/architecture/staking/10-qc-dkg-scripts-events.md b/docs/architecture/staking/10-qc-dkg-scripts-events.md index bf2d2784b6..d733103d1d 100644 --- a/docs/architecture/staking/10-qc-dkg-scripts-events.md +++ b/docs/architecture/staking/10-qc-dkg-scripts-events.md @@ -23,7 +23,7 @@ These scripts allow anyone to query information about the state of the QC contra ### Get Clusters To return a struct representing the information associated with a collector cluster, -can use the **Get Cluster** ([QC.03](../../reference/core-contracts/07-epoch-contract-reference.md#quorum-certificate-transactions-and-scripts)) script with the following argument: +can use the **Get Cluster** ([QC.03](../../references/core-contracts/07-epoch-contract-reference.md#quorum-certificate-transactions-and-scripts)) script with the following argument: | Argument | Type | Description | |------------------|----------|-------------| @@ -32,12 +32,12 @@ can use the **Get Cluster** ([QC.03](../../reference/core-contracts/07-epoch-con ### Get QC Enabled To return a boolean representing if the QC is enabled, -can use the **Get QC Enabled** ([QC.04](../../reference/core-contracts/07-epoch-contract-reference.md#quorum-certificate-transactions-and-scripts)) script with no arguments. +can use the **Get QC Enabled** ([QC.04](../../references/core-contracts/07-epoch-contract-reference.md#quorum-certificate-transactions-and-scripts)) script with no arguments. ### Get Node Has Voted To return a boolean representing if a node has voted for the current QC, you -can use the **Get Node Has Voted** ([QC.05](../../reference/core-contracts/07-epoch-contract-reference.md#quorum-certificate-transactions-and-scripts)) script with the following argument: +can use the **Get Node Has Voted** ([QC.05](../../references/core-contracts/07-epoch-contract-reference.md#quorum-certificate-transactions-and-scripts)) script with the following argument: | Argument | Type | Description | |------------------|----------|-------------| @@ -47,7 +47,7 @@ can use the **Get Node Has Voted** ([QC.05](../../reference/core-contracts/07-ep ### Get Voting Complete To return a boolean representing if the voting for the QC phase is complete, -can use the **Get Voting Complete** ([QC.06](../../reference/core-contracts/07-epoch-contract-reference.md#quorum-certificate-transactions-and-scripts)) script with no arguments. +can use the **Get Voting Complete** ([QC.06](../../references/core-contracts/07-epoch-contract-reference.md#quorum-certificate-transactions-and-scripts)) script with no arguments. ## QC Events @@ -58,27 +58,27 @@ Documentation coming soon ### Get DKG Enabled To return a boolean representing if the DKG is enabled, you -can use the **Get DKG Enabled** ([DKG.04](../../reference/core-contracts/07-epoch-contract-reference.md#dkg-transactions-and-scripts)) script with no arguments. +can use the **Get DKG Enabled** ([DKG.04](../../references/core-contracts/07-epoch-contract-reference.md#dkg-transactions-and-scripts)) script with no arguments. ### Get DKG Completed To return a boolean representing if the dkg is complete, you -can use the **Get DKG Complete** ([DKG.05](../../reference/core-contracts/07-epoch-contract-reference.md#dkg-transactions-and-scripts)) script with no arguments. +can use the **Get DKG Complete** ([DKG.05](../../references/core-contracts/07-epoch-contract-reference.md#dkg-transactions-and-scripts)) script with no arguments. ### Get Whiteboard Messages To return an array of structs representing all the whiteboard messages, you -can use the **Get DKG Whiteboard Messages** ([DKG.06](../../reference/core-contracts/07-epoch-contract-reference.md#dkg-transactions-and-scripts)) script with no arguments. +can use the **Get DKG Whiteboard Messages** ([DKG.06](../../references/core-contracts/07-epoch-contract-reference.md#dkg-transactions-and-scripts)) script with no arguments. ### Get Final Submissions To return an array of key vectors for the nodes' final submissions, you -can use the **Get Final Submissions** ([DKG.07](../../reference/core-contracts/07-epoch-contract-reference.md#dkg-transactions-and-scripts)) script with no arguments. +can use the **Get Final Submissions** ([DKG.07](../../references/core-contracts/07-epoch-contract-reference.md#dkg-transactions-and-scripts)) script with no arguments. ### Get Node Has Submitted To return a boolean representing if a node has sent their final submission for the DKG, you -can use the **Get Node Has Submitted** ([DKG.08](../../reference/core-contracts/07-epoch-contract-reference.md#dkg-transactions-and-scripts)) script with the following argument: +can use the **Get Node Has Submitted** ([DKG.08](../../references/core-contracts/07-epoch-contract-reference.md#dkg-transactions-and-scripts)) script with the following argument: | Argument | Type | Description | |------------------|----------|-------------| diff --git a/docs/architecture/staking/11-machine-account.md b/docs/architecture/staking/11-machine-account.md index 06413ccfd9..5452c07175 100644 --- a/docs/architecture/staking/11-machine-account.md +++ b/docs/architecture/staking/11-machine-account.md @@ -23,7 +23,7 @@ Currently Machine Accounts are required only for `collection` and `consensus` no #### Creation -For new node operators, Machine Accounts are created during the [staking process](../../reference/flow-port/staking-guide.md) in Flow Port. +For new node operators, Machine Accounts are created during the [staking process](../../references/run-and-secure/nodes/flow-port/staking-guide.md) in Flow Port. For node operators who initially staked prior to the introduction of Machine Accounts, Machine Accounts can be created for your staked nodes by following [this guide](../node-ops/nodes/node-operation/machine-existing-operator.md). diff --git a/docs/architecture/staking/14-staking-collection.md b/docs/architecture/staking/14-staking-collection.md index b105897343..25178c4ff0 100644 --- a/docs/architecture/staking/14-staking-collection.md +++ b/docs/architecture/staking/14-staking-collection.md @@ -4,8 +4,8 @@ sidebar_label: Staking Collection Guide --- This document outlines the steps a token holder can take to stake -using [the `FlowIDTableStaking` contract](../../reference/core-contracts/06-staking-contract-reference.md) -and [the `FlowStakingCollection` contract.](../../reference/core-contracts/11-staking-collection.md) +using [the `FlowIDTableStaking` contract](../../references/core-contracts/06-staking-contract-reference.md) +and [the `FlowStakingCollection` contract.](../../references/core-contracts/11-staking-collection.md) This is the recommended and most supported way to stake FLOW. It supports any number of nodes and delegators per account, supports locked and unlocked FLOW, and supports easily interaction with a node's machine account for collector and consensus nodes. @@ -131,7 +131,7 @@ There is a standard set of transactions provided with the staking collection. ### Setup a Staking Collection -To set up a Staking Collection, you must run the **Setup Staking Collection** ([SCO.01](../../reference/core-contracts/11-staking-collection.md)) transaction. +To set up a Staking Collection, you must run the **Setup Staking Collection** ([SCO.01](../../references/core-contracts/11-staking-collection.md)) transaction. This transaction requires no arguments and will perform the following actions: 1. Create private capabilities for the unlocked vault and locked vault (if applicable). @@ -153,7 +153,7 @@ meaning that they don't already have an associated machine account. These nodes need a new transaction to create the machine account for the node and save it to the staking collection. To create a machine account for a node that doesn't already have one, -you must submit the **Create Machine Account** ([SCO.03](../../reference/core-contracts/11-staking-collection.md)) +you must submit the **Create Machine Account** ([SCO.03](../../references/core-contracts/11-staking-collection.md)) transaction with the following arguments: | Argument | Type | Description | @@ -170,7 +170,7 @@ If no public keys are provided, the transaction will fail. ### Register a New Staked Node -To register a new staked node, you must submit the **Register Node** ([SCO.03](../../reference/core-contracts/11-staking-collection.md)) +To register a new staked node, you must submit the **Register Node** ([SCO.03](../../references/core-contracts/11-staking-collection.md)) transaction with the following arguments: | Argument | Type | Description | @@ -201,7 +201,7 @@ assuming they have the correct number of tokens to perform the action. ### Register a New Staked Delegator -To register a new delegator, you must submit the **Register Delegator** ([SCO.02](../../reference/core-contracts/11-staking-collection.md)) +To register a new delegator, you must submit the **Register Delegator** ([SCO.02](../../references/core-contracts/11-staking-collection.md)) transaction with the following arguments: | Argument | Type | Description | @@ -229,7 +229,7 @@ Most of them will only succeed during the Staking Auction phase of the epoch. The Staking Collection can stake additional tokens for any Node or Delegator managed by it at any time. -The owner of a Staking Collection can use the **Stake New Tokens** ([SCO.06](../../reference/core-contracts/11-staking-collection.md)) +The owner of a Staking Collection can use the **Stake New Tokens** ([SCO.06](../../references/core-contracts/11-staking-collection.md)) transaction with the following arguments: | Argument | Type | Description | @@ -252,7 +252,7 @@ The amount may be any number of tokens up to the sum of an accounts locked and u After tokens become unstaked, the owner of a Staking Collection can choose to re-stake the unstaked tokens to the same Node or Delegator. -The owner of a Staking Collection can use the **Stake Unstaked Tokens** ([SCO.08](../../reference/core-contracts/11-staking-collection.md)) +The owner of a Staking Collection can use the **Stake Unstaked Tokens** ([SCO.08](../../references/core-contracts/11-staking-collection.md)) transaction with the following arguments: | Argument | Type | Description | @@ -272,7 +272,7 @@ If staking for a delegator, delegatorID should be the delegator ID you ar After earning rewards from staking, the owner of a Staking Collection can choose to re-stake the rewarded tokens to the same node or delegator. -The owner of a Staking Collection can use the **Stake Unstaked Tokens** ([SCO.07](../../reference/core-contracts/11-staking-collection.md)) +The owner of a Staking Collection can use the **Stake Unstaked Tokens** ([SCO.07](../../references/core-contracts/11-staking-collection.md)) transaction with the following arguments: | Argument | Type | Description | @@ -294,7 +294,7 @@ If the tokens aren't staked yet, they will be uncommitted and available to withd _Note: unstaked tokens will be held by the central staking contract until the end of the following epoch._ _Once the tokens are released (unstaked), they can be claimed via the [Withdraw Unstaked Tokens](#withdraw-unstaked-tokens) action below._ -The owner of a Staking Collection can use the **Unstake Tokens** ([SCO.05](../../reference/core-contracts/11-staking-collection.md)) +The owner of a Staking Collection can use the **Unstake Tokens** ([SCO.05](../../references/core-contracts/11-staking-collection.md)) transaction with the following arguments: | Argument | Type | Description | @@ -309,7 +309,7 @@ To unstake tokens from an active node, leave the delegatorID arguement as ### Unstake All Tokens -The owner of a Staking Collection can use the **Unstake All** ([SCO.09](../../reference/core-contracts/11-staking-collection.md)) +The owner of a Staking Collection can use the **Unstake All** ([SCO.09](../../references/core-contracts/11-staking-collection.md)) transaction with the following arguments: | Argument | Type | Description | @@ -322,7 +322,7 @@ transaction with the following arguments: After tokens for an active Node or Delegator become unstaked, the ownder of Staking Collection can withdraw them from the central staking contract. -The owner of a Staking Collection can use the **Withdraw Unstaked Tokens** ([SCO.11](../../reference/core-contracts/11-staking-collection.md)) +The owner of a Staking Collection can use the **Withdraw Unstaked Tokens** ([SCO.11](../../references/core-contracts/11-staking-collection.md)) transaction with the following arguments: | Argument | Type | Description | @@ -339,7 +339,7 @@ To withdraw unstaked tokens from an active node, leave the delegatorID ar After earning rewards from staking, the token holder can withdraw them from the central staking contract. -The owner of a Staking Collection can use the **Withdraw Rewarded Tokens** ([SCO.10](../../reference/core-contracts/11-staking-collection.md)) +The owner of a Staking Collection can use the **Withdraw Rewarded Tokens** ([SCO.10](../../references/core-contracts/11-staking-collection.md)) transaction with the following arguments: | Argument | Type | Description | @@ -365,7 +365,7 @@ It then destroys the NodeStaker or NodeDelegator object from within the Staking _Note: Once a Node or Delegator has been closed, it cannot be accessed again,_ _and no staking or delegation actions can be further preformed on it._ -The owner of a Staking Collection can use the **Close Stake** ([SCO.12](../../reference/core-contracts/11-staking-collection.md)) +The owner of a Staking Collection can use the **Close Stake** ([SCO.12](../../references/core-contracts/11-staking-collection.md)) transaction with the following arguments: | Argument | Type | Description | @@ -393,7 +393,7 @@ _As well, all staked tokens will be considered staked by the receiver's Staking Transferring a Node will result in loss of custody of any Staked tokens for the sender. -The owner of a Staking Collection can use the **Transfer Node** ([SCO.13](../../reference/core-contracts/11-staking-collection.md)) +The owner of a Staking Collection can use the **Transfer Node** ([SCO.13](../../references/core-contracts/11-staking-collection.md)) transaction with the following arguments: | Argument | Type | Description | @@ -417,7 +417,7 @@ _As well, all staked tokens will be considered staked by the receiver's Staking Transferring a Delegator will result in loss of custody of any Staked tokens for the sender. -The owner of a Staking Collection can use the **Transfer Delegator** ([SCO.14](../../reference/core-contracts/11-staking-collection.md)) +The owner of a Staking Collection can use the **Transfer Delegator** ([SCO.14](../../references/core-contracts/11-staking-collection.md)) transaction with the following arguments: | Argument | Type | Description | @@ -438,7 +438,7 @@ _what is stored in the protocol state for the node, the node will not be able to _Only update your networking address if you have already confirmed with the Flow team that you can._ _This restriction will be removed once fully automated epochs are completely implemented_ -The owner of a Staking Collection can use the **Update Networking Address** ([SCO.22](../../reference/core-contracts/11-staking-collection.md)) +The owner of a Staking Collection can use the **Update Networking Address** ([SCO.22](../../references/core-contracts/11-staking-collection.md)) transaction with the following arguments: | Argument | Type | Description | @@ -454,7 +454,7 @@ These scripts allow anyone to query information about an account's staking colle ### Get All Node Info To return an array of structs representing the information associated with each node managed by an account's Staking Collection, anyone -can use the **Get All Node Info** ([SCO.15](../../reference/core-contracts/11-staking-collection.md)) script with the following arguments: +can use the **Get All Node Info** ([SCO.15](../../references/core-contracts/11-staking-collection.md)) script with the following arguments: | Argument | Type | Description | |-------------|------------|-------------| @@ -466,7 +466,7 @@ representing the nodes managed by an accounts Staking Collection. ### Get All Delegator Info To return an array of structs representing the information associated with each delegator managed by an account's Staking Collection, anyone -can use the **Get All Delegator Info** ([SCO.16](../../reference/core-contracts/11-staking-collection.md)) script with the following arguments: +can use the **Get All Delegator Info** ([SCO.16](../../references/core-contracts/11-staking-collection.md)) script with the following arguments: | Argument | Type | Description | |-------------|------------|-------------| @@ -478,7 +478,7 @@ representing the delegators managed by an accounts Staking Collection. ### Get All Node Ids To return an array of Strings representing the ids associated with each node managed by an account's Staking Collection, anyone -can use the **Get All Node Ids** ([SCO.17](../../reference/core-contracts/11-staking-collection.md)) script with the following arguments: +can use the **Get All Node Ids** ([SCO.17](../../references/core-contracts/11-staking-collection.md)) script with the following arguments: | Argument | Type | Description | |-------------|------------|-------------| @@ -490,7 +490,7 @@ representing each id of each node managed by an accounts Staking Collection. ### Get All Delegator Ids To return an array of structs representing the delegator ids associated with each delegation managed by an account's Staking Collection, anyone -can use the **Get All Delegator Ids** ([SCO.16](../../reference/core-contracts/11-staking-collection.md)) script with the following arguments: +can use the **Get All Delegator Ids** ([SCO.16](../../references/core-contracts/11-staking-collection.md)) script with the following arguments: | Argument | Type | Description | |-------------|------------|-------------| @@ -502,7 +502,7 @@ representing the delegator Ids of each delegator managed by an accounts Staking ### Get Locked Tokens Used To query how many Locked FLOW tokens an account has staked using their Staking Collection, anyone -can use the **Get Locked Tokens Used** ([SCO.19](../../reference/core-contracts/11-staking-collection.md)) script with the following arguments: +can use the **Get Locked Tokens Used** ([SCO.19](../../references/core-contracts/11-staking-collection.md)) script with the following arguments: | Argument | Type | Description | |-------------|------------|-------------| @@ -517,7 +517,7 @@ Note: This number does not include Locked FLOW tokens staked not through an acco ### Get Unlocked Tokens Used To query how many Unlocked FLOW tokens an account has staked using their Staking Collection, anyone -can use the **Get Unlocked Tokens Used** ([SCO.20](../../reference/core-contracts/11-staking-collection.md)) script with the following arguments: +can use the **Get Unlocked Tokens Used** ([SCO.20](../../references/core-contracts/11-staking-collection.md)) script with the following arguments: | Argument | Type | Description | |-------------|------------|-------------| @@ -532,7 +532,7 @@ Note: This number does not include Unlocked FLOW tokens staked not through an ac ### Get Does Stake Exist To query if a Node or Delegator is managed by an accounts Staking Collection, anyone -can use the **Get Does Node Exist** ([SCO.21](../../reference/core-contracts/11-staking-collection.md)) script with the following arguments: +can use the **Get Does Node Exist** ([SCO.21](../../references/core-contracts/11-staking-collection.md)) script with the following arguments: | Argument | Type | Description | |-------------------------|--------------------|-------------| @@ -550,7 +550,7 @@ Otherwise, fill it in with the delegatorID of the Delegator. ### Get Machine Account Info To query the machine account information for an account's staking collection, anyone -can use the **Get Machine Account Info** ([SCO.21](../../reference/core-contracts/11-staking-collection.md)) script with the following arguments: +can use the **Get Machine Account Info** ([SCO.21](../../references/core-contracts/11-staking-collection.md)) script with the following arguments: | Argument | Type | Description | |-------------------------|--------------------|-------------| diff --git a/docs/architecture/staking/15-staking-guide.md b/docs/architecture/staking/15-staking-guide.md index 9d22f98985..c430abc401 100644 --- a/docs/architecture/staking/15-staking-guide.md +++ b/docs/architecture/staking/15-staking-guide.md @@ -19,7 +19,7 @@ This guide covers staking with **FLOW tokens**. ### Register a New Staked Node -To register as a node operator with FLOW, the token holder can use the **Register Node** ([SC.11](../../reference/core-contracts/06-staking-contract-reference.md#staking)) +To register as a node operator with FLOW, the token holder can use the **Register Node** ([SC.11](../../references/core-contracts/06-staking-contract-reference.md#staking)) transaction with the following arguments: | Argument | Type | Description | @@ -48,7 +48,7 @@ The token holder can stake additional tokens at any time. _Note: this transaction stakes additional tokens to the same node that was registered in the setup phase._ -To stake tokens, the token holder can use the **Stake FLOW** ([SC.12](../../reference/core-contracts/06-staking-contract-reference.md#staking)) +To stake tokens, the token holder can use the **Stake FLOW** ([SC.12](../../references/core-contracts/06-staking-contract-reference.md#staking)) transaction with the following arguments: | Argument | Type | Description | @@ -61,7 +61,7 @@ This transaction commits tokens to stake from the token holder's account. After tokens become unstaked, the token holder can choose to re-stake the unstaked tokens to the same node. -To staked unstaked tokens, the token holder can use the **Re-stake Unstaked FLOW** ([SC.13](../../reference/core-contracts/06-staking-contract-reference.md#staking)) +To staked unstaked tokens, the token holder can use the **Re-stake Unstaked FLOW** ([SC.13](../../references/core-contracts/06-staking-contract-reference.md#staking)) transaction with the following arguments: | Argument | Type | Description | @@ -72,7 +72,7 @@ transaction with the following arguments: After earning rewards from staking, the token holder can choose to re-stake the rewarded tokens to the same node. -To stake rewarded tokens, the token holder can use the **Re-stake Rewarded FLOW** ([SC.14](../../reference/core-contracts/06-staking-contract-reference.md#staking)) +To stake rewarded tokens, the token holder can use the **Re-stake Rewarded FLOW** ([SC.14](../../references/core-contracts/06-staking-contract-reference.md#staking)) transaction with the following arguments: | Argument | Type | Description | @@ -85,7 +85,7 @@ The token holder can submit a request to unstake some of their tokens at any tim If the tokens aren't staked yet, they will be uncommitted and available to withdraw. To request to unstake staked tokens, the token holder can use -the **Request Unstaking** ([SC.15](../../reference/core-contracts/06-staking-contract-reference.md#staking)) transaction. +the **Request Unstaking** ([SC.15](../../references/core-contracts/06-staking-contract-reference.md#staking)) transaction. | Argument | Type | Description | |------------|----------|-------------| @@ -105,7 +105,7 @@ The token holder can submit a request to unstake all their tokens at any time. If the tokens aren't staked yet, they will be uncommitted and available to withdraw. To unstake all staked tokens, the token holder can use -the **Unstake All FLOW** ([SC.16](../../reference/core-contracts/06-staking-contract-reference.md#staking)) transaction. +the **Unstake All FLOW** ([SC.16](../../references/core-contracts/06-staking-contract-reference.md#staking)) transaction. This transaction requires no arguments. @@ -117,7 +117,7 @@ from users that are delegating FLOW to the node.** After tokens become unstaked, the token holder can withdraw them from the central staking contract. To withdraw unstaked tokens, -the token holder can use the **Withdraw Unstaked FLOW** ([SC.17](../../reference/core-contracts/06-staking-contract-reference.md#staking)) +the token holder can use the **Withdraw Unstaked FLOW** ([SC.17](../../references/core-contracts/06-staking-contract-reference.md#staking)) transaction with the following arguments: | Argument | Type | Description | @@ -131,7 +131,7 @@ This transaction moves the unstaked tokens back into the `FlowToken.Vault` owned After earning rewards from staking, the token holder can withdraw them from the central staking contract. To withdraw rewarded tokens, -the token holder can use the **Withdraw Rewarded FLOW** ([SC.18](../../reference/core-contracts/06-staking-contract-reference.md#staking)) +the token holder can use the **Withdraw Rewarded FLOW** ([SC.18](../../references/core-contracts/06-staking-contract-reference.md#staking)) transaction with the following arguments: | Argument | Type | Description | @@ -157,7 +157,7 @@ but this would require small changes to these transactions to use the new storag ## Register as a Delegator -To register as a delegator, the token holder can use the **Register Delegator** ([SC.19](../../reference/core-contracts/06-staking-contract-reference.md#delegating)) +To register as a delegator, the token holder can use the **Register Delegator** ([SC.19](../../references/core-contracts/06-staking-contract-reference.md#delegating)) transaction with the following arguments: | Argument | Type | Description | @@ -176,7 +176,7 @@ The token holder can delegate additional tokens after registering as a delegator _Note: this transaction delegates additional tokens to the same node that was registered in the setup phase._ To delegate new tokens, -the token holder can use the **Delegate New FLOW** ([SC.20](../../reference/core-contracts/06-staking-contract-reference.md#delegating)) +the token holder can use the **Delegate New FLOW** ([SC.20](../../references/core-contracts/06-staking-contract-reference.md#delegating)) transaction with the following arguments: | Argument | Type | Description | @@ -188,7 +188,7 @@ transaction with the following arguments: After delegated tokens become unstaked, the token holder can choose to re-delegate the unstaked tokens to the same node. To delegate unstaked tokens, -the token holder can use the **Re-delegate Unstaked FLOW** ([SC.21](../../reference/core-contracts/06-staking-contract-reference.md#delegating)) +the token holder can use the **Re-delegate Unstaked FLOW** ([SC.21](../../references/core-contracts/06-staking-contract-reference.md#delegating)) transaction with the following arguments: | Argument | Type | Description | @@ -200,7 +200,7 @@ transaction with the following arguments: After earning rewards from delegation, the token holder can choose to re-delegate the rewarded tokens to the same node. To delegate rewarded tokens, -the token holder can use the **Re-delegate Rewarded FLOW** ([SC.22](../../reference/core-contracts/06-staking-contract-reference.md#delegating)) +the token holder can use the **Re-delegate Rewarded FLOW** ([SC.22](../../references/core-contracts/06-staking-contract-reference.md#delegating)) transaction with the following arguments: | Argument | Type | Description | @@ -213,7 +213,7 @@ The token holder can submit a request to unstake their delegated tokens at any t If the tokens aren't staked yet, they will be uncommitted and available to withdraw. To unstake delegated tokens, -the token holder can use the **Unstake Delegated FOW** ([SC.23](../../reference/core-contracts/06-staking-contract-reference.md#delegating)) +the token holder can use the **Unstake Delegated FOW** ([SC.23](../../references/core-contracts/06-staking-contract-reference.md#delegating)) transaction with the following arguments: | Argument | Type | Description | @@ -230,7 +230,7 @@ they can be claimed via the [Withdraw Unstaked Tokens](#withdraw-unstaked-tokens After delegated tokens become unstaked, the token holder can withdraw them from the central staking contract. To withdraw unstaked tokens, -the token holder can use the **Withdraw Unstaked FLOW** ([SC.24](../../reference/core-contracts/06-staking-contract-reference.md#delegating)) +the token holder can use the **Withdraw Unstaked FLOW** ([SC.24](../../references/core-contracts/06-staking-contract-reference.md#delegating)) transaction with the following arguments: | Argument | Type | Description | @@ -244,7 +244,7 @@ This transaction moves the unstaked tokens back into the `FlowToken.Vault` owned After earning rewards from delegation, the token holder can withdraw them from the central staking contract. To withdraw rewarded tokens, -the token holder can use the **Withdraw Rewarded FLOW** ([SC.25](../../reference/core-contracts/06-staking-contract-reference.md#delegating)) +the token holder can use the **Withdraw Rewarded FLOW** ([SC.25](../../references/core-contracts/06-staking-contract-reference.md#delegating)) transaction with the following arguments: | Argument | Type | Description | diff --git a/docs/architecture/staking/index.md b/docs/architecture/staking/index.md index 230a60abe6..744b4bf2fd 100644 --- a/docs/architecture/staking/index.md +++ b/docs/architecture/staking/index.md @@ -139,7 +139,7 @@ is compatible with Flow Port. If you created your account using [Flow Port](https://port.onflow.org/), you can also stake and earn rewards using the Flow Port. -Follow this [step-by-step guide](../../reference/flow-port/staking-guide.md) to stake using Flow Port. +Follow this [step-by-step guide](../../references/run-and-secure/nodes/flow-port/staking-guide.md) to stake using Flow Port. Flow Port currently supports staking as a node, delegating, and reward withdrawal using **Blocto**, **Ledger**, **Lilico**, and **NuFi** accounts / wallets. diff --git a/docs/build/advanced-concepts/account-abstraction.md b/docs/build/advanced-concepts/account-abstraction.md index 40d2d6f7c0..316557c23f 100644 --- a/docs/build/advanced-concepts/account-abstraction.md +++ b/docs/build/advanced-concepts/account-abstraction.md @@ -54,4 +54,4 @@ These improvements are especially notable on mobile, where users are typically m | Account Abstraction | Flow | | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| Developers can build new features that streamline the user experience of Web3 apps, such as ‘session keys’ that pre-approve transactions for a period of time or setting custom limits on transaction volume or network fees. | Since all accounts are smart contracts, Flow has support for these new controls that enable apps to sign pre-approved transactions based on user controls and preference. | +| Developers can build new features that streamline the user experience of Web3 apps, such as ‘session keys’ that pre-approve transactions for a period of time or setting custom limits on transaction volume or network fees. | Since all accounts are smart contracts, Flow has support for these new controls that enable apps to sign pre-approved transactions based on user controls and preferences. | diff --git a/docs/build/advanced-concepts/metadata-views.md b/docs/build/advanced-concepts/metadata-views.md index 66b57633f7..065ce87caa 100644 --- a/docs/build/advanced-concepts/metadata-views.md +++ b/docs/build/advanced-concepts/metadata-views.md @@ -221,6 +221,6 @@ In the example above, the `NFTCollectionDisplay` not only offers fundamental met Understanding `MetadataViews` and the core functions associated with it is crucial for developers aiming to deploy NFTs on Flow. With these views and functions, NFTs can maintain a consistent presentation across various platforms and marketplaces and foster interoperability between contracts and applications in the Flow ecosystem. To gain a deeper understanding of implementing the MetadataView standard, Check out our documentation on "How to Create an NFT Project on Flow". It provides an introduction to integrating these standards into your NFT contracts. -- See the [API reference for a complete list of Metadata functions](https://developers.flow.com/reference/core-contracts/flow-nft/MetdataViews/MetadataViews) +- See the [API reference for a complete list of Metadata functions](https://developers.flow.com/references/core-contracts/flow-nft/MetdataViews/MetadataViews) - Check out [an Example NFT project](https://github.com/onflow/flow-nft/blob/master/contracts/ExampleNFT.cdc) implementing `MetadataViews` - Read [the NFT Guide](../guides/nft.md) for an introduction to implementation \ No newline at end of file diff --git a/docs/build/basics/blocks.md b/docs/build/basics/blocks.md index 9bbc0d517b..5e5dfc915d 100644 --- a/docs/build/basics/blocks.md +++ b/docs/build/basics/blocks.md @@ -35,7 +35,7 @@ The Block header contains the following fields: The block payload contains the following fields: - **Collection Guarantees** is a list of collection IDs with the signatures from the collection nodes that produced the collections. This acts as a guarantee by collection nodes that [transaction data](./transactions.md) in the collection will be available on the collection node if requested by other nodes at a later time. Flow purposely skips including transaction data in a block, making blocks as small as possible, and the production of new blocks by consensus nodes fast, that is because consensus nodes have to sync the proposed block between nodes, and that data should be the smallest possible. The consensus nodes don’t really care what will a transaction do as long as it’s valid, they only need to define an order of those transactions in a block. -- **Block Seals** is the attestation by verification nodes that the transactions in a previously executed block have been verified. This seals a previous block referenced by the block ID. It also reference the result ID and execution root hash. It contains signatures of the verification nodes that produced the seal. +- **Block Seals** is the attestation by verification nodes that the transactions in a previously executed block have been verified. This seals a previous block referenced by the block ID. It also references the result ID and execution root hash. It contains signatures of the verification nodes that produced the seal. ## Lifecycle and Status diff --git a/docs/build/basics/events.md b/docs/build/basics/events.md index f7719d12c3..15431c7cef 100644 --- a/docs/build/basics/events.md +++ b/docs/build/basics/events.md @@ -59,7 +59,7 @@ There is an unlimited amount of events that can be defined on Flow, but you shou ### FLOW Token Events -The FLOW Token contract uses the [fungible token standard on Flow](../../reference/core-contracts/03-flow-token.md) and is the contract that issues a core FLOW token. As with any contract, it can emit events when interacted with. When we transfer the FLOW token, events are emitted. You can find a lot of details on the events emitted in the [FLOW Token documentation](../../reference/core-contracts/03-flow-token.md). +The FLOW Token contract uses the [fungible token standard on Flow](../../references/core-contracts/03-flow-token.md) and is the contract that issues a core FLOW token. As with any contract, it can emit events when interacted with. When we transfer the FLOW token, events are emitted. You can find a lot of details on the events emitted in the [FLOW Token documentation](../../references/core-contracts/03-flow-token.md). The most common events are when tokens are transferred which is accomplished with two actions: withdrawing tokens from the payer and depositing tokens in the receiver. Each of those action has a corresponding event: diff --git a/docs/build/basics/fees.md b/docs/build/basics/fees.md index c81407a3af..121b92a1bf 100644 --- a/docs/build/basics/fees.md +++ b/docs/build/basics/fees.md @@ -294,7 +294,7 @@ pub fun add(_ a: Int, _ b: Int): Int { **Avoid excessive load and save operations** -Avoid costly loading and storage operations and [borrow reference](../smart-contracts/best-practices/design-patterns.md#avoid-excessive-load-and-save-storage-operations-prefer-in-place-mutations) where possible, for example: +Avoid costly loading and storage operations and [borrow references](../smart-contracts/best-practices/design-patterns.md#avoid-excessive-load-and-save-storage-operations-prefer-in-place-mutations) where possible, for example: ```cadence transaction { diff --git a/docs/build/flow.md b/docs/build/flow.md index bc82b2f6e8..1c78d5120c 100644 --- a/docs/build/flow.md +++ b/docs/build/flow.md @@ -31,7 +31,7 @@ The [development guide](../tutorials/intro.md) covers the Flow core concepts, in ## Core Contracts -The Flow blockchain implements core functionality using its own smart contract language, [Cadence](https://cadence-lang.org/docs/language/). The core functionality is split into a set of contracts, so-called [core contracts](../reference/core-contracts/index.md): +The Flow blockchain implements core functionality using its own smart contract language, [Cadence](https://cadence-lang.org/docs/language/). The core functionality is split into a set of contracts, so-called [core contracts](../references/core-contracts/index.md): - **Fungible Token:** The FungibleToken contract implements the Fungible Token Standard. It is the second contract ever deployed on Flow. - **Flow Token:** The FlowToken contract defines the FLOW network token. @@ -42,7 +42,7 @@ The Flow blockchain implements core functionality using its own smart contract l ## FLOW Token -The [FLOW](../reference/core-contracts/03-flow-token.md) token is the native currency for the Flow network. Developers and users can use FLOW to transact on the network. Developers can integrate FLOW directly into their apps for peer-to-peer payments, service charges, or consumer rewards. FLOW can be held, transferred, or transacted peer-to-peer. +The [FLOW](../references/core-contracts/03-flow-token.md) token is the native currency for the Flow network. Developers and users can use FLOW to transact on the network. Developers can integrate FLOW directly into their apps for peer-to-peer payments, service charges, or consumer rewards. FLOW can be held, transferred, or transacted peer-to-peer. ## Technical Background @@ -53,7 +53,7 @@ The [FLOW](../reference/core-contracts/03-flow-token.md) token is the native cur ## Tokenomics - To understand more about Flow's Token Economics, and the **FLOW token**, you can read the [Flow Token Economics](https://www.onflow.org/flow-token-economics) guide. -- FLOW tokens are Flow's native Fungible Token. To learn more about how to work with them in your applications, go [here](../reference/core-contracts/03-flow-token.md). +- FLOW tokens are Flow's native Fungible Token. To learn more about how to work with them in your applications, go [here](../references/core-contracts/03-flow-token.md). ## More Concepts diff --git a/docs/build/guides/nft.md b/docs/build/guides/nft.md index 94c9794034..8577fe4190 100644 --- a/docs/build/guides/nft.md +++ b/docs/build/guides/nft.md @@ -606,11 +606,11 @@ flow scripts execute cadence/scripts/GetNFTs.cdc 0x123 Many NFT projects include metadata associated with the NFT, such as a name, description, or image. However, different projects might store this metadata in various formats. To ensure compatibility across the Flow ecosystem, Flow uses `MetadataViews` to standardize the representation of this metadata. -There are two types of Metadata Views: NFT level and contract level. In this guide, we’ll show you how to implement the most basic display, but for a deeper dive into what is possible, check out the [MetadataViews API doc](../../reference/core-contracts/flow-nft/MetdataViews/MetadataViews.md). +There are two types of Metadata Views: NFT level and contract level. In this guide, we’ll show you how to implement the most basic display, but for a deeper dive into what is possible, check out the [MetadataViews API doc](../../references/core-contracts/flow-nft/MetdataViews/MetadataViews.md). ### NFT Metadata -For the NFT metadata, you'll add a simple `MetadataView` called `Display`, which includes a `name`, `description`, and `thumbnail`. This format is common for many NFT projects. (For more details, refer to the [Display documentation](../../reference/core-contracts/flow-nft/MetdataViews/MetadataViews.md#display)). +For the NFT metadata, you'll add a simple `MetadataView` called `Display`, which includes a `name`, `description`, and `thumbnail`. This format is common for many NFT projects. (For more details, refer to the [Display documentation](../../references/core-contracts/flow-nft/MetdataViews/MetadataViews.md#display)). Start by importing the `MetadataViews` contract into your `FooBar` contract: @@ -741,5 +741,5 @@ Congrats, you did it! You’re now ready to launch the next fun NFT project on F - Explore [an example NFT repository](https://github.com/nvdtf/flow-nft-scaffold/blob/main/cadence/contracts/exampleNFT/ExampleNFT.cdc) - Watch a [video tutorial on creating an NFT project in the Flow Playground](https://www.youtube.com/watch?v=bQVXSpg6GE8) - Dive into the details of [the NFT Standard](https://github.com/onflow/flow-nft) -- For a deeper dive into `MetadataViews`, consult the [introduction guide](../advanced-concepts/metadata-views.md), [API documentation](https://developers.flow.com/reference/core-contracts/flow-nft/MetdataViews/MetadataViews#docusaurus_skipToContent_fallback) or [the FLIP that introduced this feature](https://github.com/onflow/flips/blob/main/application/20210916-nft-metadata.md). +- For a deeper dive into `MetadataViews`, consult the [introduction guide](../advanced-concepts/metadata-views.md), [API documentation](https://developers.flow.com/references/core-contracts/flow-nft/MetdataViews/MetadataViews#docusaurus_skipToContent_fallback) or [the FLIP that introduced this feature](https://github.com/onflow/flips/blob/main/application/20210916-nft-metadata.md). - Use a [no code tool for creating NFT projects on Flow](https://www.touchstone.city/) \ No newline at end of file diff --git a/docs/build/smart-contracts/best-practices/anti-patterns.md b/docs/build/smart-contracts/best-practices/anti-patterns.md index d08e985e9e..654934ad74 100644 --- a/docs/build/smart-contracts/best-practices/anti-patterns.md +++ b/docs/build/smart-contracts/best-practices/anti-patterns.md @@ -74,15 +74,15 @@ rather than inside contract utility functions. There are some scenarios where using an `AuthAccount` object is necessary, such as a cold storage multi-sig, but those cases are extremely rare and `AuthAccount` usage should still be avoided unless absolutely necessary. -## Auth reference and capabilities should be avoided +## Auth references and capabilities should be avoided ### Problem -[Authorized reference](https://cadence-lang.org/docs/language/reference) allow downcasting restricted +[Authorized references](https://cadence-lang.org/docs/language/references) allow downcasting restricted types to their unrestricted type and should be avoided unless necessary. The type that is being restricted could expose functionality that was not intended to be exposed. -If the `auth` keyword is used on local variables they will be reference. -Reference are ephemeral and cannot be stored. +If the `auth` keyword is used on local variables they will be references. +References are ephemeral and cannot be stored. This prevents any reference casting to be stored under account storage. Additionally, if the `auth` keyword is used to store a public capability, serious harm could happen since the value could be downcasted to a type diff --git a/docs/build/smart-contracts/best-practices/design-patterns.md b/docs/build/smart-contracts/best-practices/design-patterns.md index 9c1cda4721..0f291f77f7 100644 --- a/docs/build/smart-contracts/best-practices/design-patterns.md +++ b/docs/build/smart-contracts/best-practices/design-patterns.md @@ -266,7 +266,7 @@ When specifying type constraints for capabilities or borrows, concrete types oft making it unclear if the developer actually intended it to be unspecified or not. Paths also use a shared namespace between contracts, so an account may have stored a different object in a path that you would expect to be used for something else. -Therefore, it is important to be explicit when getting objects or reference to resources. +Therefore, it is important to be explicit when getting objects or references to resources. ### Solution diff --git a/docs/build/smart-contracts/best-practices/security-best-practices.md b/docs/build/smart-contracts/best-practices/security-best-practices.md index e9c4ec72c8..328eb030c3 100644 --- a/docs/build/smart-contracts/best-practices/security-best-practices.md +++ b/docs/build/smart-contracts/best-practices/security-best-practices.md @@ -8,15 +8,15 @@ This is an opinionated list of best practices Cadence developers should follow t Some practices listed below might overlap with advice in the [Cadence Anti-Patterns](./design-patterns.md) section, which is a recommended read as well. -## Reference +## References -[Reference](https://cadence-lang.org/docs/language/reference) are ephemeral values and cannot be stored. If persistence is required, store a capability and borrow it when needed. +[References](https://cadence-lang.org/docs/language/references) are ephemeral values and cannot be stored. If persistence is required, store a capability and borrow it when needed. -Authorized reference (reference with the `auth` keyword) allow downcasting, e.g. a restricted type to its unrestricted type and should only be used in some specific cases. +Authorized references (references with the `auth` keyword) allow downcasting, e.g. a restricted type to its unrestricted type and should only be used in some specific cases. -When exposing functionality, provide the least access necessary. Do not use authorized reference, as they can be downcasted, potentially allowing a user to gain access to supposedly restricted functionality. For example, the fungible token standard provides an interface to get the balance of a vault, without exposing the withdrawal functionality. +When exposing functionality, provide the least access necessary. Do not use authorized references, as they can be downcasted, potentially allowing a user to gain access to supposedly restricted functionality. For example, the fungible token standard provides an interface to get the balance of a vault, without exposing the withdrawal functionality. -Be aware that the subtype or unrestricted type could expose functionality that was not intended to be exposed. Do not use authorized reference when exposing functionality. For example, the fungible token standard provides an interface to get the balance of a vault, without exposing the withdrawal functionality. +Be aware that the subtype or unrestricted type could expose functionality that was not intended to be exposed. Do not use authorized references when exposing functionality. For example, the fungible token standard provides an interface to get the balance of a vault, without exposing the withdrawal functionality. ## Account Storage diff --git a/docs/build/smart-contracts/deploying.md b/docs/build/smart-contracts/deploying.md index 25981f4382..566bc51628 100644 --- a/docs/build/smart-contracts/deploying.md +++ b/docs/build/smart-contracts/deploying.md @@ -85,7 +85,7 @@ Make sure Flow project was initialized in the previous step and the `flow.json` ### Making Use of Core Contracts -Flow Testnet comes with some useful contracts already deployed, called **core contracts.** More information and import addresses for the [core contracts](../../reference/core-contracts/index.md). +Flow Testnet comes with some useful contracts already deployed, called **core contracts.** More information and import addresses for the [core contracts](../../references/core-contracts/index.md). Once your accounts are set up and you're ready to develop, you can look over [some code examples from the Flow Go SDK](https://github.com/onflow/flow-go-sdk/tree/master/examples). diff --git a/docs/build/smart-contracts/overview.md b/docs/build/smart-contracts/overview.md index af00894689..7574f8631e 100644 --- a/docs/build/smart-contracts/overview.md +++ b/docs/build/smart-contracts/overview.md @@ -60,9 +60,9 @@ The Flow blockchain has existing smart contract standards for both fungible and ### Non-Fungible Tokens (NFTs) -All NFTs on the Flow blockchain implement the [NonFungibleToken](../../reference/core-contracts/08-non-fungible-token.md) interface, allowing them to be compatible with wallets, marketplaces and other cross-app experiences. +All NFTs on the Flow blockchain implement the [NonFungibleToken](../../references/core-contracts/08-non-fungible-token.md) interface, allowing them to be compatible with wallets, marketplaces and other cross-app experiences. -- [Non-Fungible Token (NFT) contract interface](../../reference/core-contracts/08-non-fungible-token.md) +- [Non-Fungible Token (NFT) contract interface](../../references/core-contracts/08-non-fungible-token.md) ### NFT Sales and Trading @@ -72,6 +72,6 @@ Flow has a standard contract to facilitate both the direct sales and peer-to-pee ### Fungible Tokens -Fungible tokens (i.e. coins, currencies) on the Flow blockchain, including the default cryptocurrency token FLOW, implement the [FungibleToken](../../reference/core-contracts/02-fungible-token.md) interface. +Fungible tokens (i.e. coins, currencies) on the Flow blockchain, including the default cryptocurrency token FLOW, implement the [FungibleToken](../../references/core-contracts/02-fungible-token.md) interface. -- [Fungible Token contract interface](../../reference/core-contracts/02-fungible-token.md) +- [Fungible Token contract interface](../../references/core-contracts/02-fungible-token.md) diff --git a/docs/build/smart-contracts/testing.md b/docs/build/smart-contracts/testing.md index ce2b33ccfa..7c7f3347de 100644 --- a/docs/build/smart-contracts/testing.md +++ b/docs/build/smart-contracts/testing.md @@ -273,7 +273,7 @@ Get familiar with the [Cadence anti-patterns](./best-practices/anti-patterns.md) -## Reference +## References - [Reference documentation for Cadence testing](https://cadence-lang.org/docs/testing-framework) - [Overflow](https://github.com/bjartek/overflow) is a powerful Golang-based DSL for efficient testing and execution of blockchain interactions diff --git a/docs/reference/_category_.yml b/docs/reference/_category_.yml deleted file mode 100644 index 262a790ea7..0000000000 --- a/docs/reference/_category_.yml +++ /dev/null @@ -1,2 +0,0 @@ -label: Reference -position: 5 \ No newline at end of file diff --git a/docs/reference/flow-networks/accessing-crescendo.md b/docs/reference/flow-networks/accessing-crescendo.md deleted file mode 100644 index 2a1f9a9a70..0000000000 --- a/docs/reference/flow-networks/accessing-crescendo.md +++ /dev/null @@ -1,58 +0,0 @@ ---- -title: Flow Crescendo -sidebar_position: 4 -description: Guide to Crescendo access ---- - -## About Flow Crescendo -Flow Crescendo is Flow's official testing and development network. It is intended to provide a staging and testing environment for dApp developers. -It aims to balance similarity with Mainnet with being a productive development environment, resulting in the following key differences: -- Crescendo has significantly fewer validator nodes, resulting in a faster block rate compared to Mainnet -- Crescendo is configured with shorter epochs (about 12 hours, compared to 7 days on Mainnet) -- Crescendo receives software upgrades up to 2 weeks before Mainnet - -## Accessing Flow Crescendo - -Flow Crescendo is available for access at this URL: - -``` -access.crescendo.nodes.onflow.org:9000 -``` - -For example, to access the network using the [Flow Go SDK](https://github.com/onflow/flow-go-sdk): - -```go -import "github.com/onflow/flow-go-sdk/client" - -func main() { - flowAccessAddress := "access.crescendo.nodes.onflow.org:9000" - flowClient, _ := client.New(flowAccessAddress, grpc.WithInsecure()) - // ... -} -``` - -### Generating Crescendo key pair - -You can generate a new key pair with the [Flow CLI](https://github.com/onflow/flow-cli) as follows: - -```sh -> flow keys generate - -🙏 If you want to create an account on Crescendo with the generated keys use this link: -https://crescendo-faucet.onflow.org/?key= cc1c3d72... - - -🔴️ Store private key safely and don't share with anyone! -Private Key 246256f3... -Public Key cc1c3d72... -``` - -**Note: By default, this command generates an ECDSA key pair on the P-256 curve. Keep in mind, the CLI is intended for development purposes only and is not recommended for production use. Handling keys using a Key Management Service is the best practice.** - -## Account creation and token funding requests - -Accounts and tokens for testing can be obtained through the [crescendo faucet](https://crescendo-faucet.onflow.org/). If you generated the keypair through the CLI, you can click on the URL provided to create an account and request crescendo FLOW tokens. - -## Important smart contract addresses - -You can review [all available core contracts](../../reference/core-contracts/index.md) deployed to the Crescendo to identify which ones you want to import. diff --git a/docs/reference/flow-networks/index.md b/docs/reference/flow-networks/index.md deleted file mode 100644 index f3c63d46b7..0000000000 --- a/docs/reference/flow-networks/index.md +++ /dev/null @@ -1,26 +0,0 @@ ---- -title: Flow Networks -sidebar_position: 1 ---- - -## Flow Networks - -Other than the Flow mainnet network, Flow testnet can be used to test applications and contracts before deployment to mainnet. - -During a round of network upgrade, Flow testnet is updated first. Hence, testnet can be used to test against the latest node software, Cadence and core contract changes which will eventually be available to mainnet. - -### How to access these networks? - -- [Flow Testnet](./accessing-testnet.md) -- [Flow Mainnet](./accessing-mainnet.md) -- [Flow Crescendo](./accessing-crescendo.md) - -### Network -Get Flow blockchain data from Access Nodes, both REST and gRPC endpoints are available. Get the current status of mainnet and testnet networks. - -- [Flow Access API](../../architecture/node-ops/nodes/access-api.md) - - [Mainnet](./accessing-mainnet.md): `access.mainnet.nodes.onflow.org:9000` - - [Testnet](./accessing-testnet.md): `access.devnet.nodes.onflow.org:9000` - - [Crescendo](./accessing-crescendo.md): `access.crescendo.nodes.onflow.org:9000` -- [Status Page](https://status.onflow.org/) - Network status page - diff --git a/docs/reference/index.md b/docs/reference/index.md deleted file mode 100644 index 352f5324c3..0000000000 --- a/docs/reference/index.md +++ /dev/null @@ -1,8 +0,0 @@ ---- -title: Reference -sidebar_position: 1 ---- - -# Reference -Quick reference to very helpful parts of developer documentation. Languages to code up your applications and Network access points to pull blockchain data form Flow. - diff --git a/docs/references/_category_.yml b/docs/references/_category_.yml new file mode 100644 index 0000000000..ab5d8aec2a --- /dev/null +++ b/docs/references/_category_.yml @@ -0,0 +1,2 @@ +label: References +position: 5 \ No newline at end of file diff --git a/docs/reference/core-contracts/02-fungible-token.md b/docs/references/core-contracts/02-fungible-token.md similarity index 96% rename from docs/reference/core-contracts/02-fungible-token.md rename to docs/references/core-contracts/02-fungible-token.md index 88862e00d7..8fe4ad93a0 100644 --- a/docs/reference/core-contracts/02-fungible-token.md +++ b/docs/references/core-contracts/02-fungible-token.md @@ -1,7 +1,6 @@ --- title: Fungible Token Contract sidebar_label: Fungible Token -sidebar_position: 4 --- The `FungibleToken` contract implements the Fungible Token Standard. It is the second contract ever deployed on Flow. diff --git a/docs/reference/core-contracts/03-flow-token.md b/docs/references/core-contracts/03-flow-token.md similarity index 99% rename from docs/reference/core-contracts/03-flow-token.md rename to docs/references/core-contracts/03-flow-token.md index bec6a50641..50ea82b801 100644 --- a/docs/reference/core-contracts/03-flow-token.md +++ b/docs/references/core-contracts/03-flow-token.md @@ -1,7 +1,6 @@ --- title: Flow Token Contract sidebar_label: Flow Token -sidebar_position: 4 --- The `FlowToken` contract defines the FLOW network token. diff --git a/docs/reference/core-contracts/04-service-account.md b/docs/references/core-contracts/04-service-account.md similarity index 100% rename from docs/reference/core-contracts/04-service-account.md rename to docs/references/core-contracts/04-service-account.md diff --git a/docs/reference/core-contracts/05-flow-fees.md b/docs/references/core-contracts/05-flow-fees.md similarity index 100% rename from docs/reference/core-contracts/05-flow-fees.md rename to docs/references/core-contracts/05-flow-fees.md diff --git a/docs/reference/core-contracts/06-staking-contract-reference.md b/docs/references/core-contracts/06-staking-contract-reference.md similarity index 100% rename from docs/reference/core-contracts/06-staking-contract-reference.md rename to docs/references/core-contracts/06-staking-contract-reference.md diff --git a/docs/reference/core-contracts/07-epoch-contract-reference.md b/docs/references/core-contracts/07-epoch-contract-reference.md similarity index 100% rename from docs/reference/core-contracts/07-epoch-contract-reference.md rename to docs/references/core-contracts/07-epoch-contract-reference.md diff --git a/docs/reference/core-contracts/08-non-fungible-token.md b/docs/references/core-contracts/08-non-fungible-token.md similarity index 100% rename from docs/reference/core-contracts/08-non-fungible-token.md rename to docs/references/core-contracts/08-non-fungible-token.md diff --git a/docs/reference/core-contracts/09-nft-metadata.md b/docs/references/core-contracts/09-nft-metadata.md similarity index 100% rename from docs/reference/core-contracts/09-nft-metadata.md rename to docs/references/core-contracts/09-nft-metadata.md diff --git a/docs/reference/core-contracts/10-nft-storefront.md b/docs/references/core-contracts/10-nft-storefront.md similarity index 100% rename from docs/reference/core-contracts/10-nft-storefront.md rename to docs/references/core-contracts/10-nft-storefront.md diff --git a/docs/reference/core-contracts/11-staking-collection.md b/docs/references/core-contracts/11-staking-collection.md similarity index 100% rename from docs/reference/core-contracts/11-staking-collection.md rename to docs/references/core-contracts/11-staking-collection.md diff --git a/docs/reference/core-contracts/flow-ecosystem.png b/docs/references/core-contracts/flow-ecosystem.png similarity index 100% rename from docs/reference/core-contracts/flow-ecosystem.png rename to docs/references/core-contracts/flow-ecosystem.png diff --git a/docs/references/core-contracts/flow-ft/ExampleToken/ExampleToken.md b/docs/references/core-contracts/flow-ft/ExampleToken/ExampleToken.md new file mode 100644 index 0000000000..353c3c663a --- /dev/null +++ b/docs/references/core-contracts/flow-ft/ExampleToken/ExampleToken.md @@ -0,0 +1,160 @@ +# Contract `ExampleToken` + +```cadence +contract ExampleToken { + + totalSupply: UFix64 + + VaultStoragePath: StoragePath + + ReceiverPublicPath: PublicPath + + VaultPublicPath: PublicPath + + AdminStoragePath: StoragePath +} +``` + + +Implemented Interfaces: + - `FungibleToken` + +## Structs & Resources + +### resource `Vault` + +```cadence +resource Vault { + + balance: UFix64 +} +``` +Each user stores an instance of only the Vault in their storage +The functions in the Vault and governed by the pre and post conditions +in FungibleToken when they are called. +The checks happen at runtime whenever a function is called. + +Resources can only be created in the context of the contract that they +are defined in, so there is no way for a malicious user to create Vaults +out of thin air. A special Minter resource needs to be defined to mint +new tokens. + +[More...](ExampleToken_Vault.md) + +--- + +### resource `Administrator` + +```cadence +resource Administrator { +} +``` + +[More...](ExampleToken_Administrator.md) + +--- + +### resource `Minter` + +```cadence +resource Minter { + + allowedAmount: UFix64 +} +``` +Resource object that token admin accounts can hold to mint new tokens. + +[More...](ExampleToken_Minter.md) + +--- + +### resource `Burner` + +```cadence +resource Burner { +} +``` +Resource object that token admin accounts can hold to burn tokens. + +[More...](ExampleToken_Burner.md) + +--- +## Functions + +### fun `createEmptyVault()` + +```cadence +func createEmptyVault(): Vault +``` +Function that creates a new Vault with a balance of zero +and returns it to the calling context. A user must call this function +and store the returned Vault in their storage in order to allow their +account to be able to receive deposits of this token type. + +Returns: The new Vault resource + +--- +## Events + +### event `TokensInitialized` + +```cadence +event TokensInitialized(initialSupply UFix64) +``` +The event that is emitted when the contract is created + +--- + +### event `TokensWithdrawn` + +```cadence +event TokensWithdrawn(amount UFix64, from Address?) +``` +The event that is emitted when tokens are withdrawn from a Vault + +--- + +### event `TokensDeposited` + +```cadence +event TokensDeposited(amount UFix64, to Address?) +``` +The event that is emitted when tokens are deposited to a Vault + +--- + +### event `TokensMinted` + +```cadence +event TokensMinted(amount UFix64) +``` +The event that is emitted when new tokens are minted + +--- + +### event `TokensBurned` + +```cadence +event TokensBurned(amount UFix64) +``` +The event that is emitted when tokens are destroyed + +--- + +### event `MinterCreated` + +```cadence +event MinterCreated(allowedAmount UFix64) +``` +The event that is emitted when a new minter resource is created + +--- + +### event `BurnerCreated` + +```cadence +event BurnerCreated() +``` +The event that is emitted when a new burner resource is created + +--- diff --git a/docs/references/core-contracts/flow-ft/ExampleToken/ExampleToken_Administrator.md b/docs/references/core-contracts/flow-ft/ExampleToken/ExampleToken_Administrator.md new file mode 100644 index 0000000000..c375b5f0e2 --- /dev/null +++ b/docs/references/core-contracts/flow-ft/ExampleToken/ExampleToken_Administrator.md @@ -0,0 +1,33 @@ +# Resource `Administrator` + +```cadence +resource Administrator { +} +``` + +## Functions + +### fun `createNewMinter()` + +```cadence +func createNewMinter(allowedAmount UFix64): Minter +``` +Function that creates and returns a new minter resource + +Parameters: + - allowedAmount : _The maximum quantity of tokens that the minter could create_ + +Returns: The Minter resource that would allow to mint tokens + +--- + +### fun `createNewBurner()` + +```cadence +func createNewBurner(): Burner +``` +Function that creates and returns a new burner resource + +Returns: The Burner resource + +--- diff --git a/docs/references/core-contracts/flow-ft/ExampleToken/ExampleToken_Burner.md b/docs/references/core-contracts/flow-ft/ExampleToken/ExampleToken_Burner.md new file mode 100644 index 0000000000..c5f0b7618d --- /dev/null +++ b/docs/references/core-contracts/flow-ft/ExampleToken/ExampleToken_Burner.md @@ -0,0 +1,24 @@ +# Resource `Burner` + +```cadence +resource Burner { +} +``` + +Resource object that token admin accounts can hold to burn tokens. +## Functions + +### fun `burnTokens()` + +```cadence +func burnTokens(from FungibleToken.Vault) +``` +Function that destroys a Vault instance, effectively burning the tokens. + +Note: the burned tokens are automatically subtracted from the +total supply in the Vault destructor. + +Parameters: + - from : _The Vault resource containing the tokens to burn_ + +--- diff --git a/docs/references/core-contracts/flow-ft/ExampleToken/ExampleToken_Minter.md b/docs/references/core-contracts/flow-ft/ExampleToken/ExampleToken_Minter.md new file mode 100644 index 0000000000..2f5ee34388 --- /dev/null +++ b/docs/references/core-contracts/flow-ft/ExampleToken/ExampleToken_Minter.md @@ -0,0 +1,34 @@ +# Resource `Minter` + +```cadence +resource Minter { + + allowedAmount: UFix64 +} +``` + +Resource object that token admin accounts can hold to mint new tokens. + +### Initializer + +```cadence +func init(allowedAmount UFix64) +``` + + +## Functions + +### fun `mintTokens()` + +```cadence +func mintTokens(amount UFix64): ExampleToken.Vault +``` +Function that mints new tokens, adds them to the total supply, +and returns them to the calling context. + +Parameters: + - amount : _The quantity of tokens to mint_ + +Returns: The Vault resource containing the minted tokens + +--- diff --git a/docs/references/core-contracts/flow-ft/ExampleToken/ExampleToken_Vault.md b/docs/references/core-contracts/flow-ft/ExampleToken/ExampleToken_Vault.md new file mode 100644 index 0000000000..1d3985131f --- /dev/null +++ b/docs/references/core-contracts/flow-ft/ExampleToken/ExampleToken_Vault.md @@ -0,0 +1,96 @@ +# Resource `Vault` + +```cadence +resource Vault { + + balance: UFix64 +} +``` + +Each user stores an instance of only the Vault in their storage +The functions in the Vault and governed by the pre and post conditions +in FungibleToken when they are called. +The checks happen at runtime whenever a function is called. + +Resources can only be created in the context of the contract that they +are defined in, so there is no way for a malicious user to create Vaults +out of thin air. A special Minter resource needs to be defined to mint +new tokens. + +Implemented Interfaces: + - `FungibleToken.Provider` + - `FungibleToken.Receiver` + - `FungibleToken.Balance` + - `MetadataViews.Resolver` + + +### Initializer + +```cadence +func init(balance UFix64) +``` + + +## Functions + +### fun `withdraw()` + +```cadence +func withdraw(amount UFix64): FungibleToken.Vault +``` +Function that takes an amount as an argument +and withdraws that amount from the Vault. +It creates a new temporary Vault that is used to hold +the money that is being transferred. It returns the newly +created Vault to the context that called so it can be deposited +elsewhere. + +Parameters: + - amount : _The amount of tokens to be withdrawn from the vault_ + +Returns: The Vault resource containing the withdrawn funds + +--- + +### fun `deposit()` + +```cadence +func deposit(from FungibleToken.Vault) +``` +Function that takes a Vault object as an argument and adds +its balance to the balance of the owners Vault. +It is allowed to destroy the sent Vault because the Vault +was a temporary holder of the tokens. The Vault's balance has +been consumed and therefore can be destroyed. + +Parameters: + - from : _The Vault resource containing the funds that will be deposited_ + +--- + +### fun `getViews()` + +```cadence +func getViews(): [Type] +``` +The way of getting all the Metadata Views implemented by ExampleToken + +developers to know which parameter to pass to the resolveView() method. + +Returns: An array of Types defining the implemented views. This value will be used by + +--- + +### fun `resolveView()` + +```cadence +func resolveView(_ Type): AnyStruct? +``` +The way of getting a Metadata View out of the ExampleToken + +Parameters: + - view : _The Type of the desired view._ + +Returns: A structure representing the requested view. + +--- diff --git a/docs/references/core-contracts/flow-ft/FungibleToken/FungibleToken.md b/docs/references/core-contracts/flow-ft/FungibleToken/FungibleToken.md new file mode 100644 index 0000000000..298d13b590 --- /dev/null +++ b/docs/references/core-contracts/flow-ft/FungibleToken/FungibleToken.md @@ -0,0 +1,121 @@ +# Contract Interface `FungibleToken` + +```cadence +contract interface FungibleToken { + + totalSupply: UFix64 +} +``` + +The interface that Fungible Token contracts implement. +## Interfaces + +### resource interface `Provider` + +```cadence +resource interface Provider { +} +``` +The interface that enforces the requirements for withdrawing +tokens from the implementing type. + +It does not enforce requirements on `balance` here, +because it leaves open the possibility of creating custom providers +that do not necessarily need their own balance. + +[More...](FungibleToken_Provider.md) + +--- + +### resource interface `Receiver` + +```cadence +resource interface Receiver { +} +``` +The interface that enforces the requirements for depositing +tokens into the implementing type. + +We do not include a condition that checks the balance because +we want to give users the ability to make custom receivers that +can do custom things with the tokens, like split them up and +send them to different places. + +[More...](FungibleToken_Receiver.md) + +--- + +### resource interface `Balance` + +```cadence +resource interface Balance { + + balance: UFix64 +} +``` +The interface that contains the `balance` field of the Vault +and enforces that when new Vaults are created, the balance +is initialized correctly. + +[More...](FungibleToken_Balance.md) + +--- +## Structs & Resources + +### resource `Vault` + +```cadence +resource Vault { + + balance: UFix64 +} +``` +The resource that contains the functions to send and receive tokens. +The declaration of a concrete type in a contract interface means that +every Fungible Token contract that implements the FungibleToken interface +must define a concrete `Vault` resource that conforms to the `Provider`, `Receiver`, +and `Balance` interfaces, and declares their required fields and functions + +[More...](FungibleToken_Vault.md) + +--- +## Functions + +### fun `createEmptyVault()` + +```cadence +func createEmptyVault(): Vault +``` +Allows any user to create a new Vault that has a zero balance + +Returns: The new Vault resource + +--- +## Events + +### event `TokensInitialized` + +```cadence +event TokensInitialized(initialSupply UFix64) +``` +The event that is emitted when the contract is created + +--- + +### event `TokensWithdrawn` + +```cadence +event TokensWithdrawn(amount UFix64, from Address?) +``` +The event that is emitted when tokens are withdrawn from a Vault + +--- + +### event `TokensDeposited` + +```cadence +event TokensDeposited(amount UFix64, to Address?) +``` +The event that is emitted when tokens are deposited into a Vault + +--- diff --git a/docs/references/core-contracts/flow-ft/FungibleToken/FungibleToken_Balance.md b/docs/references/core-contracts/flow-ft/FungibleToken/FungibleToken_Balance.md new file mode 100644 index 0000000000..90529705db --- /dev/null +++ b/docs/references/core-contracts/flow-ft/FungibleToken/FungibleToken_Balance.md @@ -0,0 +1,40 @@ +# Resource Interface `Balance` + +```cadence +resource interface Balance { + + balance: UFix64 +} +``` + +The interface that contains the `balance` field of the Vault +and enforces that when new Vaults are created, the balance +is initialized correctly. +## Functions + +### fun `getViews()` + +```cadence +func getViews(): [Type] +``` +Function that returns all the Metadata Views implemented by a Fungible Token + +developers to know which parameter to pass to the resolveView() method. + +Returns: An array of Types defining the implemented views. This value will be used by + +--- + +### fun `resolveView()` + +```cadence +func resolveView(_ Type): AnyStruct? +``` +Function that resolves a metadata view for this fungible token by type. + +Parameters: + - view : _The Type of the desired view._ + +Returns: A structure representing the requested view. + +--- diff --git a/docs/references/core-contracts/flow-ft/FungibleToken/FungibleToken_Provider.md b/docs/references/core-contracts/flow-ft/FungibleToken/FungibleToken_Provider.md new file mode 100644 index 0000000000..fa47e733d8 --- /dev/null +++ b/docs/references/core-contracts/flow-ft/FungibleToken/FungibleToken_Provider.md @@ -0,0 +1,41 @@ +# Resource Interface `Provider` + +```cadence +resource interface Provider { +} +``` + +The interface that enforces the requirements for withdrawing +tokens from the implementing type. + +It does not enforce requirements on `balance` here, +because it leaves open the possibility of creating custom providers +that do not necessarily need their own balance. +## Functions + +### fun `withdraw()` + +```cadence +func withdraw(amount UFix64): Vault +``` +Subtracts tokens from the owner's Vault +and returns a Vault with the removed tokens. + +The function's access level is public, but this is not a problem +because only the owner storing the resource in their account +can initially call this function. + +The owner may grant other accounts access by creating a private +capability that allows specific other users to access +the provider resource through a reference. + +The owner may also grant all accounts access by creating a public +capability that allows all users to access the provider +resource through a reference. + +Parameters: + - amount : _The amount of tokens to be withdrawn from the vault_ + +Returns: The Vault resource containing the withdrawn funds + +--- diff --git a/docs/references/core-contracts/flow-ft/FungibleToken/FungibleToken_Receiver.md b/docs/references/core-contracts/flow-ft/FungibleToken/FungibleToken_Receiver.md new file mode 100644 index 0000000000..8e3c86bf9e --- /dev/null +++ b/docs/references/core-contracts/flow-ft/FungibleToken/FungibleToken_Receiver.md @@ -0,0 +1,27 @@ +# Resource Interface `Receiver` + +```cadence +resource interface Receiver { +} +``` + +The interface that enforces the requirements for depositing +tokens into the implementing type. + +We do not include a condition that checks the balance because +we want to give users the ability to make custom receivers that +can do custom things with the tokens, like split them up and +send them to different places. +## Functions + +### fun `deposit()` + +```cadence +func deposit(from Vault) +``` +Takes a Vault and deposits it into the implementing resource type + +Parameters: + - from : _The Vault resource containing the funds that will be deposited_ + +--- diff --git a/docs/references/core-contracts/flow-ft/FungibleToken/FungibleToken_Vault.md b/docs/references/core-contracts/flow-ft/FungibleToken/FungibleToken_Vault.md new file mode 100644 index 0000000000..07ca726890 --- /dev/null +++ b/docs/references/core-contracts/flow-ft/FungibleToken/FungibleToken_Vault.md @@ -0,0 +1,49 @@ +# Resource `Vault` + +```cadence +resource Vault { + + balance: UFix64 +} +``` + +The resource that contains the functions to send and receive tokens. +The declaration of a concrete type in a contract interface means that +every Fungible Token contract that implements the FungibleToken interface +must define a concrete `Vault` resource that conforms to the `Provider`, `Receiver`, +and `Balance` interfaces, and declares their required fields and functions + +Implemented Interfaces: + - `Provider` + - `Receiver` + - `Balance` + + +### Initializer + +```cadence +func init(balance UFix64) +``` + + +## Functions + +### fun `withdraw()` + +```cadence +func withdraw(amount UFix64): Vault +``` + +--- + +### fun `deposit()` + +```cadence +func deposit(from Vault) +``` +Takes a Vault and deposits it into the implementing resource type + +Parameters: + - from : _The Vault resource containing the funds that will be deposited_ + +--- diff --git a/docs/references/core-contracts/flow-ft/FungibleTokenMetadataViews/FungibleTokenMetadataViews.md b/docs/references/core-contracts/flow-ft/FungibleTokenMetadataViews/FungibleTokenMetadataViews.md new file mode 100644 index 0000000000..da2bcd57d7 --- /dev/null +++ b/docs/references/core-contracts/flow-ft/FungibleTokenMetadataViews/FungibleTokenMetadataViews.md @@ -0,0 +1,133 @@ +# Contract `FungibleTokenMetadataViews` + +```cadence +contract FungibleTokenMetadataViews { +} +``` + +This contract implements the metadata standard proposed +in FLIP-1087. + +Ref: https://github.com/onflow/flips/blob/main/application/20220811-fungible-tokens-metadata.md + +Structs and resources can implement one or more +metadata types, called views. Each view type represents +a different kind of metadata. +## Structs & Resources + +### struct `FTView` + +```cadence +struct FTView { + + ftDisplay: FTDisplay? + + ftVaultData: FTVaultData? +} +``` +FTView wraps FTDisplay and FTVaultData, and is used to give a complete +picture of a Fungible Token. Most Fungible Token contracts should +implement this view. + +[More...](FungibleTokenMetadataViews_FTView.md) + +--- + +### struct `FTDisplay` + +```cadence +struct FTDisplay { + + name: String + + symbol: String + + description: String + + externalURL: MetadataViews.ExternalURL + + logos: MetadataViews.Medias + + socials: {String: MetadataViews.ExternalURL} +} +``` +View to expose the information needed to showcase this FT. +This can be used by applications to give an overview and +graphics of the FT. + +[More...](FungibleTokenMetadataViews_FTDisplay.md) + +--- + +### struct `FTVaultData` + +```cadence +struct FTVaultData { + + storagePath: StoragePath + + receiverPath: PublicPath + + metadataPath: PublicPath + + providerPath: PrivatePath + + receiverLinkedType: Type + + metadataLinkedType: Type + + providerLinkedType: Type + + createEmptyVault: ((): @FungibleToken.Vault) +} +``` +View to expose the information needed store and interact with a FT vault. +This can be used by applications to setup a FT vault with proper +storage and public capabilities. + +[More...](FungibleTokenMetadataViews_FTVaultData.md) + +--- +## Functions + +### fun `getFTView()` + +```cadence +func getFTView(viewResolver &{MetadataViews.Resolver}): FTView +``` +Helper to get a FT view. + +Parameters: + - viewResolver : _A reference to the resolver resource_ + +Returns: A FTView struct + +--- + +### fun `getFTDisplay()` + +```cadence +func getFTDisplay(_ &{MetadataViews.Resolver}): FTDisplay? +``` +Helper to get FTDisplay in a way that will return a typed optional. + +Parameters: + - viewResolver : _A reference to the resolver resource_ + +Returns: An optional FTDisplay struct + +--- + +### fun `getFTVaultData()` + +```cadence +func getFTVaultData(_ &{MetadataViews.Resolver}): FTVaultData? +``` +Helper to get FTVaultData in a way that will return a typed Optional. + +Parameters: + - viewResolver : _A reference to the resolver resource_ + +Returns: A optional FTVaultData struct + +--- diff --git a/docs/references/core-contracts/flow-ft/FungibleTokenMetadataViews/FungibleTokenMetadataViews_FTDisplay.md b/docs/references/core-contracts/flow-ft/FungibleTokenMetadataViews/FungibleTokenMetadataViews_FTDisplay.md new file mode 100644 index 0000000000..28653aa258 --- /dev/null +++ b/docs/references/core-contracts/flow-ft/FungibleTokenMetadataViews/FungibleTokenMetadataViews_FTDisplay.md @@ -0,0 +1,30 @@ +# Struct `FTDisplay` + +```cadence +struct FTDisplay { + + name: String + + symbol: String + + description: String + + externalURL: MetadataViews.ExternalURL + + logos: MetadataViews.Medias + + socials: {String: MetadataViews.ExternalURL} +} +``` + +View to expose the information needed to showcase this FT. +This can be used by applications to give an overview and +graphics of the FT. + +### Initializer + +```cadence +func init(name String, symbol String, description String, externalURL MetadataViews.ExternalURL, logos MetadataViews.Medias, socials {String: MetadataViews.ExternalURL}) +``` + + diff --git a/docs/references/core-contracts/flow-ft/FungibleTokenMetadataViews/FungibleTokenMetadataViews_FTVaultData.md b/docs/references/core-contracts/flow-ft/FungibleTokenMetadataViews/FungibleTokenMetadataViews_FTVaultData.md new file mode 100644 index 0000000000..7a23819e57 --- /dev/null +++ b/docs/references/core-contracts/flow-ft/FungibleTokenMetadataViews/FungibleTokenMetadataViews_FTVaultData.md @@ -0,0 +1,34 @@ +# Struct `FTVaultData` + +```cadence +struct FTVaultData { + + storagePath: StoragePath + + receiverPath: PublicPath + + metadataPath: PublicPath + + providerPath: PrivatePath + + receiverLinkedType: Type + + metadataLinkedType: Type + + providerLinkedType: Type + + createEmptyVault: ((): @FungibleToken.Vault) +} +``` + +View to expose the information needed store and interact with a FT vault. +This can be used by applications to setup a FT vault with proper +storage and public capabilities. + +### Initializer + +```cadence +func init(storagePath StoragePath, receiverPath PublicPath, metadataPath PublicPath, providerPath PrivatePath, receiverLinkedType Type, metadataLinkedType Type, providerLinkedType Type, createEmptyVaultFunction ((): @FungibleToken.Vault)) +``` + + diff --git a/docs/references/core-contracts/flow-ft/FungibleTokenMetadataViews/FungibleTokenMetadataViews_FTView.md b/docs/references/core-contracts/flow-ft/FungibleTokenMetadataViews/FungibleTokenMetadataViews_FTView.md new file mode 100644 index 0000000000..0bb2b7168b --- /dev/null +++ b/docs/references/core-contracts/flow-ft/FungibleTokenMetadataViews/FungibleTokenMetadataViews_FTView.md @@ -0,0 +1,22 @@ +# Struct `FTView` + +```cadence +struct FTView { + + ftDisplay: FTDisplay? + + ftVaultData: FTVaultData? +} +``` + +FTView wraps FTDisplay and FTVaultData, and is used to give a complete +picture of a Fungible Token. Most Fungible Token contracts should +implement this view. + +### Initializer + +```cadence +func init(ftDisplay FTDisplay?, ftVaultData FTVaultData?) +``` + + diff --git a/docs/references/core-contracts/flow-ft/FungibleTokenSwitchboard/FungibleTokenSwitchboard.md b/docs/references/core-contracts/flow-ft/FungibleTokenSwitchboard/FungibleTokenSwitchboard.md new file mode 100644 index 0000000000..77922ecad7 --- /dev/null +++ b/docs/references/core-contracts/flow-ft/FungibleTokenSwitchboard/FungibleTokenSwitchboard.md @@ -0,0 +1,91 @@ +# Contract `FungibleTokenSwitchboard` + +```cadence +contract FungibleTokenSwitchboard { + + StoragePath: StoragePath + + PublicPath: PublicPath + + ReceiverPublicPath: PublicPath +} +``` + +The contract that allows an account to receive payments in multiple fungible +tokens using a single `{FungibleToken.Receiver}` capability. +This capability should ideally be stored at the +`FungibleTokenSwitchboard.ReceiverPublicPath = /public/GenericFTReceiver` +but it can be stored anywhere. +## Interfaces + +### resource interface `SwitchboardPublic` + +```cadence +resource interface SwitchboardPublic { +} +``` +The interface that enforces the method to allow anyone to check on the +available capabilities of a switchboard resource and also exposes the +deposit methods to deposit funds on it. + +[More...](FungibleTokenSwitchboard_SwitchboardPublic.md) + +--- +## Structs & Resources + +### resource `Switchboard` + +```cadence +resource Switchboard { + + receiverCapabilities: {Type: Capability<&{FungibleToken.Receiver}>} +} +``` +The resource that stores the multiple fungible token receiver +capabilities, allowing the owner to add and remove them and anyone to +deposit any fungible token among the available types. + +[More...](FungibleTokenSwitchboard_Switchboard.md) + +--- +## Functions + +### fun `createSwitchboard()` + +```cadence +func createSwitchboard(): Switchboard +``` +Function that allows to create a new blank switchboard. A user must call +this function and store the returned resource in their storage. + +--- +## Events + +### event `VaultCapabilityAdded` + +```cadence +event VaultCapabilityAdded(type Type, switchboardOwner Address?, capabilityOwner Address?) +``` +The event that is emitted when a new vault capability is added to a +switchboard resource. + +--- + +### event `VaultCapabilityRemoved` + +```cadence +event VaultCapabilityRemoved(type Type, switchboardOwner Address?, capabilityOwner Address?) +``` +The event that is emitted when a vault capability is removed from a +switchboard resource. + +--- + +### event `NotCompletedDeposit` + +```cadence +event NotCompletedDeposit(type Type, amount UFix64, switchboardOwner Address?) +``` +The event that is emitted when a deposit can not be completed. + +--- diff --git a/docs/references/core-contracts/flow-ft/FungibleTokenSwitchboard/FungibleTokenSwitchboard_Switchboard.md b/docs/references/core-contracts/flow-ft/FungibleTokenSwitchboard/FungibleTokenSwitchboard_Switchboard.md new file mode 100644 index 0000000000..0d61b834c2 --- /dev/null +++ b/docs/references/core-contracts/flow-ft/FungibleTokenSwitchboard/FungibleTokenSwitchboard_Switchboard.md @@ -0,0 +1,144 @@ +# Resource `Switchboard` + +```cadence +resource Switchboard { + + receiverCapabilities: {Type: Capability<&{FungibleToken.Receiver}>} +} +``` + +The resource that stores the multiple fungible token receiver +capabilities, allowing the owner to add and remove them and anyone to +deposit any fungible token among the available types. + +Implemented Interfaces: + - `FungibleToken.Receiver` + - `SwitchboardPublic` + + +### Initializer + +```cadence +func init() +``` + + +## Functions + +### fun `addNewVault()` + +```cadence +func addNewVault(capability Capability<&{FungibleToken.Receiver}>) +``` +Adds a new fungible token receiver capability to the switchboard +resource. + +token vault deposit function through `{FungibleToken.Receiver}` that +will be added to the switchboard. + +Parameters: + - capability : _The capability to expose a certain fungible_ + +--- + +### fun `addNewVaultsByPath()` + +```cadence +func addNewVaultsByPath(paths [PublicPath], address Address) +``` +Adds a number of new fungible token receiver capabilities by using +the paths where they are stored. + +Parameters: + - paths : _The paths where the public capabilities are stored._ + - address : _The address of the owner of the capabilities._ + +--- + +### fun `addNewVaultWrapper()` + +```cadence +func addNewVaultWrapper(capability Capability<&{FungibleToken.Receiver}>, type Type) +``` +Adds a new fungible token receiver capability to the switchboard +resource specifying which `Type`of `@FungibleToken.Vault` can be +deposited to it. Use it to include in your switchboard "wrapper" +receivers such as a `@TokenForwarding.Forwarder`. It can also be +used to overwrite the type attached to a certain capability without +having to remove that capability first. + +token vault deposit function through `{FungibleToken.Receiver}` that +will be added to the switchboard. + +capability, rather than the `Type` from the reference borrowed from +said capability + +Parameters: + - capability : _The capability to expose a certain fungible_ + - type : _The type of fungible token that can be deposited to that_ + +--- + +### fun `removeVault()` + +```cadence +func removeVault(capability Capability<&{FungibleToken.Receiver}>) +``` +Removes a fungible token receiver capability from the switchboard +resource. + +removed from the switchboard. + +Parameters: + - capability : _The capability to a fungible token vault to be_ + +--- + +### fun `deposit()` + +```cadence +func deposit(from FungibleToken.Vault) +``` +Takes a fungible token vault and routes it to the proper fungible +token receiver capability for depositing it. + +Parameters: + - from : _The deposited fungible token vault resource._ + +--- + +### fun `safeDeposit()` + +```cadence +func safeDeposit(from FungibleToken.Vault): FungibleToken.Vault? +``` +Takes a fungible token vault and tries to route it to the proper +fungible token receiver capability for depositing the funds, +avoiding panicking if the vault is not available. + +deposited. + +funds if the deposit was successful, or still containing the funds +if the reference to the needed vault was not found. + +Parameters: + - vaultType : _The type of the ft vault that wants to be_ + +Returns: The deposited fungible token vault resource, without the + +--- + +### fun `getVaultTypes()` + +```cadence +func getVaultTypes(): [Type] +``` +A getter function to know which tokens a certain switchboard +resource is prepared to receive. + +`{FungibleToken.Receiver}` capabilities that can be effectively +borrowed. + +Returns: The keys from the dictionary of stored + +--- diff --git a/docs/references/core-contracts/flow-ft/FungibleTokenSwitchboard/FungibleTokenSwitchboard_SwitchboardPublic.md b/docs/references/core-contracts/flow-ft/FungibleTokenSwitchboard/FungibleTokenSwitchboard_SwitchboardPublic.md new file mode 100644 index 0000000000..5065f1211b --- /dev/null +++ b/docs/references/core-contracts/flow-ft/FungibleTokenSwitchboard/FungibleTokenSwitchboard_SwitchboardPublic.md @@ -0,0 +1,35 @@ +# Resource Interface `SwitchboardPublic` + +```cadence +resource interface SwitchboardPublic { +} +``` + +The interface that enforces the method to allow anyone to check on the +available capabilities of a switchboard resource and also exposes the +deposit methods to deposit funds on it. +## Functions + +### fun `getVaultTypes()` + +```cadence +func getVaultTypes(): [Type] +``` + +--- + +### fun `deposit()` + +```cadence +func deposit(from FungibleToken.Vault) +``` + +--- + +### fun `safeDeposit()` + +```cadence +func safeDeposit(from FungibleToken.Vault): FungibleToken.Vault? +``` + +--- diff --git a/docs/reference/core-contracts/flow-ft/index.md b/docs/references/core-contracts/flow-ft/index.md similarity index 99% rename from docs/reference/core-contracts/flow-ft/index.md rename to docs/references/core-contracts/flow-ft/index.md index c6155885a2..4b0ed0cb33 100644 --- a/docs/reference/core-contracts/flow-ft/index.md +++ b/docs/references/core-contracts/flow-ft/index.md @@ -1,6 +1,6 @@ --- title: Fungible Token (FT) Standard -sidebar_position: 2 +sidebar_position: 1 --- This is a description of the Flow standard for fungible token contracts. It is meant to contain the minimum requirements to implement a safe, secure, easy to understand, and easy to use fungible token contract. It also includes an example implementation to show how a concrete smart contract would actually implement the interface. diff --git a/docs/references/core-contracts/flow-ft/overview.md b/docs/references/core-contracts/flow-ft/overview.md deleted file mode 100644 index 9d3e43bacd..0000000000 --- a/docs/references/core-contracts/flow-ft/overview.md +++ /dev/null @@ -1,208 +0,0 @@ -# Fungible Token Standard - -This is a description of the Flow standard for fungible token contracts. It is meant to contain the minimum requirements to implement a safe, secure, easy to understand, and easy to use fungible token contract. It also includes an example implementation to show how a concrete smart contract would actually implement the interface. - -## What is Flow? - -Flow is a new blockchain for open worlds. Read more about it [here](https://flow.com/). - -## What is Cadence? - -Cadence is a new Resource-oriented programming language -for developing smart contracts for the Flow Blockchain. -Read more about it [here](https://developers.flow.com/) and see its implementation [here](https://github.com/onflow/cadence) - -We recommend that anyone who is reading this should have already -completed the [Cadence Tutorials](https://developers.flow.com/cadence/tutorial/01-first-steps) -so they can build a basic understanding of the programming language. - -Resource-oriented programming, and by extension Cadence, -is the perfect programming environment for currencies, because users are able -to store their tokens directly in their accounts and transact -peer-to-peer. Please see the [blog post about resources](https://medium.com/dapperlabs/resource-oriented-programming-bee4d69c8f8e) -to understand why they are perfect for digital assets. - -## Feedback - -Flow and Cadence are both still in development, so this standard will still -be going through a lot of changes as the protocol and language evolves, -and as we receive feedback from the community about the standard. - -We'd love to hear from anyone who has feedback. -Main feedback we are looking for is: - -The feedback we are looking for is: - -- Are there any features that are missing from the standard? -- Are the features that we have included defined in the best way possible? -- Are there any pre and post conditions for functions that are missing? -- Are the pre and post conditions defined well enough? Error messages? -- Are there any other actions that need an event defined for them? -- Are the current event definitions clear enough and do they provide enough information for apps and other actors a clear look into what is happening? -- Are the variable, function, and parameter names descriptive enough? -- Are there any openings for bugs or vulnerabilities that we are not noticing? -- Is the documentation/comments clear and concise and organized in a coherent manner? - -## Basics of the Standard: - -The code for the standard is in `contracts/FungibleToken.cdc`. An example implementation of the standard that simulates what a simple token would be like is in `contracts/ExampleToken.cdc`. - -The exact smart contract that is used for the official Flow Network Token is in `contracts/FlowToken.cdc` - -Example transactions that users could use to interact with fungible tokens are located in the `transactions/` directory. These templates are mostly generic and can be used with any fungible token implementation by providing the correct addresses, names, and values. - -The standard consists of a contract interface called `FungibleToken` that requires implementing contracts to define a `Vault` resource that represents the tokens that an account owns. Each account that owns tokens will have a `Vault` stored in its account storage. Users call functions on each other's `Vault`s to send and receive tokens. - -Right now we are using unsigned 64-bit fixed point numbers `UFix64` as the type to represent token balance information. This type has 8 decimal places and cannot represent negative numbers. - -## Core Features (All contained in the main FungibleToken interface) - -1- Getting metadata for the token smart contract via the fields of the contract: - -- `pub var totalSupply: UFix64` - - The only required field of the contract. It would be incremented when new tokens are minted and decremented when they are destroyed. -- Event that gets emitted when the contract is initialized - - `pub event TokensInitialized(initialSupply: UFix64)` - -2- Retrieving the token fields of a `Vault` in an account that owns tokens. - -- Balance interface - - `pub var balance: UFix64` - - The only required field of the `Vault` type - -3- Withdrawing a specific amount of tokens *amount* using the *withdraw* function of the owner's `Vault` - -- Provider interface - - `pub fun withdraw(amount: UFix64): @FungibleToken.Vault` - - Conditions - - the returned Vault's balance must equal the amount withdrawn - - The amount withdrawn must be less than or equal to the balance - - The resulting balance must equal the initial balance - amount - - Users can give other accounts a reference to their `Vault` cast as a `Provider` to allow them to withdraw and send tokens for them. A contract can define any custom logic to govern the amount of tokens that can be withdrawn at a time with a `Provider`. This can mimic the `approve`, `transferFrom` functionality of ERC20. -- withdraw event - - Indicates how much was withdrawn and from what account the `Vault` is stored in. - If the `Vault` is not in account storage when the event is emitted, - `from` will be `nil`. - - `pub event TokensWithdrawn(amount: UFix64, from: Address?)` - -4 - Depositing a specific amount of tokens *from* using the *deposit* function of the recipient's `Vault` - -- `Receiver` interface - - `pub fun deposit(from: @FungibleToken.Vault)` - - Conditions - - `from` balance must be non-zero - - The resulting balance must be equal to the initial balance + the balance of `from` -- deposit event - - Indicates how much was deposited and to what account the `Vault` is stored in. - If the `Vault` is not in account storage when the event is emitted, - `to` will be `nil`. - - `pub event TokensDeposited(amount: UFix64, to: Address?)` -- Users could create custom `Receiver`s to trigger special code when transfers to them happen, like forwarding the tokens - to another account, splitting them up, and much more. - -- It is important that if you are making your own implementation of the fungible token interface that - you cast the input to `deposit` as the type of your token. - `let vault <- from as! @ExampleToken.Vault` - The interface specifies the argument as `@FungibleToken.Vault`, any resource that satisfies this can be sent to the deposit function. The interface checks that the concrete types match, but you'll still need to cast the `Vault` before storing it. - -5 - Creating an empty Vault resource - -- `pub fun createEmptyVault(): @FungibleToken.Vault` -- Defined in the contract - To create an empty `Vault`, the caller calls the function in the contract and stores the Vault in their storage. -- Conditions: - - the balance of the returned Vault must be 0 - -6 - Destroying a Vault - -If a `Vault` is explicitly destroyed using Cadence's `destroy` keyword, the balance of the destroyed vault must be subracted from the total supply. - -7 - Standard for Token Metadata - -- not sure what this should be yet -- Could be a dictionary, could be an IPFS hash, could be json, etc. -- need suggestions! - - -## Comparison to Similar Standards in Ethereum - -This spec covers much of the same ground that a spec like ERC-20 covers, but without most of the downsides. - -- Tokens cannot be sent to accounts or contracts that don't have owners or don't understand how to use them, because an account has to have a `Vault` in its storage to receive tokens. No `safetransfer` is needed. -- If the recipient is a contract that has a stored `Vault`, the tokens can just be deposited to that Vault without having to do a clunky `approve`, `transferFrom` -- Events are defined in the contract for withdrawing and depositing, so a recipient will always be notified that someone has sent them tokens with the deposit event. -- The `approve`, `transferFrom` pattern is not included, so double spends are not permitted -- Transfers can trigger actions because users can define custom `Receivers` to execute certain code when a token is sent. -- Cadence integer types protect against overflow and underflow, so a `SafeMath`-equivalent library is not needed. - -### Metadata - -A standard for token metadata is still an unsolved problem in the general blockchain world and we are still thinking about ways to solve it in Cadence. We hope to be able to store all metadata on-chain and are open to any ideas or feedback on how this could be implemented. - - -## Bonus Features - -**Minting and Burning are not included in the standard but are included in the FlowToken example contract to illustrate what minting and burning might look like for a token in Flow.** - -8 - Minting or Burning a specific amount of tokens using a specific minter resource that an owner can control - -- `MintandBurn` Resource - - function to mintTokens - - tokens minted event - - Each minter has a set amount of tokens that they are allowed to mint. This cannot be changed and a new minter needs to be created to add more allowance. - - function to burnTokens - - tokens Burnt event - - Each time tokens are minted or burnt, that value is added or subtracted to or from the total supply. - - -**The following features could each be defined as a separate interface. It would be good to make standards for these, but not necessary to include in the main standard interface and are not currently defined in this example.** - -9 - Withdrawing a specific amount of tokens from someone else's `Vault` by using their `provider` reference. - -- approved withdraw event -- Providing a resource that only approves an account to send a specific amount per transaction or per day/month/etc. -- Returning the amount of tokens that an account can send for another account. -- Reading the balance of the account that you have permission to send tokens for -- Owner is able to increase and decrease the approval at will, or revoke it completely - - This is much harder than anticipated - -11 - Pausing Token transfers (maybe a way to prevent the contract from being imported) - -12 - Cloning the token to create a new token with the same distribution - -13 - Restricted ownership (For accredited investors and such) -- allowlisting -- denylisting - -# How to use the Fungible Token contract - -To use the Flow Token contract as is, you need to follow these steps: - -1. If you are using the Playground, you need to deploy the `FungibleToken` definition to account 1 yourself and import it in `ExampleToken`. It is a predeployed interface in the emulator, testnet, and mainnet and you can import definition from those accounts: - - `0xee82856bf20e2aa6` on emulator - - `0x9a0766d93b6608b7` on testnet - - `0xf233dcee88fe0abe` on mainnet -2. Deploy the `ExampleToken` definition -3. You can use the `get_balance.cdc` or `get_supply.cdc` scripts to read the - balance of a user's `Vault` or the total supply of all tokens, respectively. -4. Use the `setupAccount.cdc` on any account to set up the account to be able to - use `FlowTokens`. -5. Use the `transfer_tokens.cdc` transaction file to send tokens from one user with - a `Vault` in their account storage to another user with a `Vault` in their account storage. -6. Use the `mint_tokens.cdc` transaction with the admin account to mint new tokens. -7. Use the `burn_tokens.cdc` transaction with the admin account to burn tokens. -8. Use the `create_minter.cdc` transaction to create a new MintandBurn resource - and store it in a new Admin's account. - - -# Running Automated Tests - -You can find automated tests in the `lib/go/test/token_test.go` file. It uses the transaction templates that are contained in the `lib/go/templates/transaction_templates.go` file. Currently, these rely on a dependency from a private dapper labs repository to run, so external users will not be able to run them. We are working on making all of this public so anyone can run tests, but haven't completed this work yet. - -## License - -The works in these folders are under the [Unlicense](https://github.com/onflow/flow-ft/blob/master/LICENSE): - -- [/contracts](https://github.com/onflow/flow-ft/blob/master/contracts/) - - diff --git a/docs/references/core-contracts/flow-nft/ExampleNFT/ExampleNFT.md b/docs/references/core-contracts/flow-nft/ExampleNFT/ExampleNFT.md new file mode 100644 index 0000000000..68504ae446 --- /dev/null +++ b/docs/references/core-contracts/flow-nft/ExampleNFT/ExampleNFT.md @@ -0,0 +1,128 @@ +# Contract `ExampleNFT` + +```cadence +contract ExampleNFT { + + totalSupply: UInt64 + + CollectionStoragePath: StoragePath + + CollectionPublicPath: PublicPath + + MinterStoragePath: StoragePath +} +``` + + +Implemented Interfaces: + - `NonFungibleToken` + +## Interfaces + +### resource interface `ExampleNFTCollectionPublic` + +```cadence +resource interface ExampleNFTCollectionPublic { +} +``` +Defines the methods that are particular to this NFT contract collection + +[More...](ExampleNFT_ExampleNFTCollectionPublic.md) + +--- +## Structs & Resources + +### resource `NFT` + +```cadence +resource NFT { + + id: UInt64 + + name: String + + description: String + + thumbnail: String + + royalties: [MetadataViews.Royalty] + + metadata: {String: AnyStruct} +} +``` +The core resource that represents a Non Fungible Token. +New instances will be created using the NFTMinter resource +and stored in the Collection resource + +[More...](ExampleNFT_NFT.md) + +--- + +### resource `Collection` + +```cadence +resource Collection { + + ownedNFTs: {UInt64: NonFungibleToken.NFT} +} +``` +The resource that will be holding the NFTs inside any account. +In order to be able to manage NFTs any account will need to create +an empty collection first + +[More...](ExampleNFT_Collection.md) + +--- + +### resource `NFTMinter` + +```cadence +resource NFTMinter { +} +``` +Resource that an admin or something similar would own to be +able to mint new NFTs + +[More...](ExampleNFT_NFTMinter.md) + +--- +## Functions + +### fun `createEmptyCollection()` + +```cadence +func createEmptyCollection(): NonFungibleToken.Collection +``` +Allows anyone to create a new empty collection + +Returns: The new Collection resource + +--- +## Events + +### event `ContractInitialized` + +```cadence +event ContractInitialized() +``` +The event that is emitted when the contract is created + +--- + +### event `Withdraw` + +```cadence +event Withdraw(id UInt64, from Address?) +``` +The event that is emitted when an NFT is withdrawn from a Collection + +--- + +### event `Deposit` + +```cadence +event Deposit(id UInt64, to Address?) +``` +The event that is emitted when an NFT is deposited to a Collection + +--- diff --git a/docs/references/core-contracts/flow-nft/ExampleNFT/ExampleNFT_Collection.md b/docs/references/core-contracts/flow-nft/ExampleNFT/ExampleNFT_Collection.md new file mode 100644 index 0000000000..c3fa3d62f2 --- /dev/null +++ b/docs/references/core-contracts/flow-nft/ExampleNFT/ExampleNFT_Collection.md @@ -0,0 +1,112 @@ +# Resource `Collection` + +```cadence +resource Collection { + + ownedNFTs: {UInt64: NonFungibleToken.NFT} +} +``` + +The resource that will be holding the NFTs inside any account. +In order to be able to manage NFTs any account will need to create +an empty collection first + +Implemented Interfaces: + - `ExampleNFTCollectionPublic` + - `NonFungibleToken.Provider` + - `NonFungibleToken.Receiver` + - `NonFungibleToken.CollectionPublic` + - `MetadataViews.ResolverCollection` + + +### Initializer + +```cadence +func init() +``` + + +## Functions + +### fun `withdraw()` + +```cadence +func withdraw(withdrawID UInt64): NonFungibleToken.NFT +``` +Removes an NFT from the collection and moves it to the caller + +Parameters: + - withdrawID : _The ID of the NFT that wants to be withdrawn_ + +Returns: The NFT resource that has been taken out of the collection + +--- + +### fun `deposit()` + +```cadence +func deposit(token NonFungibleToken.NFT) +``` +Adds an NFT to the collections dictionary and adds the ID to the id array + +Parameters: + - token : _The NFT resource to be included in the collection_ + +--- + +### fun `getIDs()` + +```cadence +func getIDs(): [UInt64] +``` +Helper method for getting the collection IDs + +Returns: An array containing the IDs of the NFTs in the collection + +--- + +### fun `borrowNFT()` + +```cadence +func borrowNFT(id UInt64): &NonFungibleToken.NFT +``` +Gets a reference to an NFT in the collection so that +the caller can read its metadata and call its methods + +Parameters: + - id : _The ID of the wanted NFT_ + +Returns: A reference to the wanted NFT resource + +--- + +### fun `borrowExampleNFT()` + +```cadence +func borrowExampleNFT(id UInt64): &ExampleNFT.NFT? +``` +Gets a reference to an NFT in the collection so that +the caller can read its metadata and call its methods + +Parameters: + - id : _The ID of the wanted NFT_ + +Returns: A reference to the wanted NFT resource + +--- + +### fun `borrowViewResolver()` + +```cadence +func borrowViewResolver(id UInt64): &AnyResource{MetadataViews.Resolver} +``` +Gets a reference to the NFT only conforming to the `{MetadataViews.Resolver}` +interface so that the caller can retrieve the views that the NFT +is implementing and resolve them + +Parameters: + - id : _The ID of the wanted NFT_ + +Returns: The resource reference conforming to the Resolver interface + +--- diff --git a/docs/references/core-contracts/flow-nft/ExampleNFT/ExampleNFT_ExampleNFTCollectionPublic.md b/docs/references/core-contracts/flow-nft/ExampleNFT/ExampleNFT_ExampleNFTCollectionPublic.md new file mode 100644 index 0000000000..26f6583c64 --- /dev/null +++ b/docs/references/core-contracts/flow-nft/ExampleNFT/ExampleNFT_ExampleNFTCollectionPublic.md @@ -0,0 +1,41 @@ +# Resource Interface `ExampleNFTCollectionPublic` + +```cadence +resource interface ExampleNFTCollectionPublic { +} +``` + +Defines the methods that are particular to this NFT contract collection +## Functions + +### fun `deposit()` + +```cadence +func deposit(token NonFungibleToken.NFT) +``` + +--- + +### fun `getIDs()` + +```cadence +func getIDs(): [UInt64] +``` + +--- + +### fun `borrowNFT()` + +```cadence +func borrowNFT(id UInt64): &NonFungibleToken.NFT +``` + +--- + +### fun `borrowExampleNFT()` + +```cadence +func borrowExampleNFT(id UInt64): &ExampleNFT.NFT? +``` + +--- diff --git a/docs/references/core-contracts/flow-nft/ExampleNFT/ExampleNFT_NFT.md b/docs/references/core-contracts/flow-nft/ExampleNFT/ExampleNFT_NFT.md new file mode 100644 index 0000000000..cb27f69c0a --- /dev/null +++ b/docs/references/core-contracts/flow-nft/ExampleNFT/ExampleNFT_NFT.md @@ -0,0 +1,63 @@ +# Resource `NFT` + +```cadence +resource NFT { + + id: UInt64 + + name: String + + description: String + + thumbnail: String + + royalties: [MetadataViews.Royalty] + + metadata: {String: AnyStruct} +} +``` + +The core resource that represents a Non Fungible Token. +New instances will be created using the NFTMinter resource +and stored in the Collection resource + +Implemented Interfaces: + - `NonFungibleToken.INFT` + - `MetadataViews.Resolver` + + +### Initializer + +```cadence +func init(id UInt64, name String, description String, thumbnail String, royalties [MetadataViews.Royalty], metadata {String: AnyStruct}) +``` + + +## Functions + +### fun `getViews()` + +```cadence +func getViews(): [Type] +``` +Function that returns all the Metadata Views implemented by a Non Fungible Token + +developers to know which parameter to pass to the resolveView() method. + +Returns: An array of Types defining the implemented views. This value will be used by + +--- + +### fun `resolveView()` + +```cadence +func resolveView(_ Type): AnyStruct? +``` +Function that resolves a metadata view for this token. + +Parameters: + - view : _The Type of the desired view._ + +Returns: A structure representing the requested view. + +--- diff --git a/docs/references/core-contracts/flow-nft/ExampleNFT/ExampleNFT_NFTMinter.md b/docs/references/core-contracts/flow-nft/ExampleNFT/ExampleNFT_NFTMinter.md new file mode 100644 index 0000000000..4d02246459 --- /dev/null +++ b/docs/references/core-contracts/flow-nft/ExampleNFT/ExampleNFT_NFTMinter.md @@ -0,0 +1,27 @@ +# Resource `NFTMinter` + +```cadence +resource NFTMinter { +} +``` + +Resource that an admin or something similar would own to be +able to mint new NFTs +## Functions + +### fun `mintNFT()` + +```cadence +func mintNFT(recipient &{NonFungibleToken.CollectionPublic}, name String, description String, thumbnail String, royalties [MetadataViews.Royalty]) +``` +Mints a new NFT with a new ID and deposit it in the +recipients collection using their collection reference + +Parameters: + - recipient : _A capability to the collection where the new NFT will be deposited_ + - name : _The name for the NFT metadata_ + - description : _The description for the NFT metadata_ + - thumbnail : _The thumbnail for the NFT metadata_ + - royalties : _An array of Royalty structs, see MetadataViews docs_ + +--- diff --git a/docs/references/core-contracts/flow-nft/MetdataViews/MetadataViews.md b/docs/references/core-contracts/flow-nft/MetdataViews/MetadataViews.md new file mode 100644 index 0000000000..3777284f9e --- /dev/null +++ b/docs/references/core-contracts/flow-nft/MetdataViews/MetadataViews.md @@ -0,0 +1,604 @@ +# Contract `MetadataViews` + +```cadence +pub contract MetadataViews { +} +``` + +This contract implements the metadata standard proposed +in FLIP-0636. + +Ref: https://github.com/onflow/flips/blob/main/application/20210916-nft-metadata.md + +Structs and resources can implement one or more +metadata types, called views. Each view type represents +a different kind of metadata, such as a creator biography +or a JPEG image file. +## Interfaces + +### `Resolver` + +```cadence +pub resource interface Resolver { +} +``` +Provides access to a set of metadata views. A struct or +resource (e.g. an NFT) can implement this interface to provide access to +the views that it supports. + +[More...](MetadataViews_Resolver.md) + +--- + +### `ResolverCollection` + +```cadence +pub resource interface ResolverCollection { +} +``` +A group of view resolvers indexed by ID. + +[More...](MetadataViews_ResolverCollection.md) + +--- + +### `File` + +```cadence +pub struct interface File { +} +``` +Generic interface that represents a file stored on or off chain. Files +can be used to references images, videos and other media. + +[More...](MetadataViews_File.md) + +--- +## Structs & Resources + +### `NFTView` + +```cadence +pub struct NFTView { + + pub let id: UInt64 + + pub let uuid: UInt64 + + pub let display: Display? + + pub let externalURL: ExternalURL? + + pub let collectionData: NFTCollectionData? + + pub let collectionDisplay: NFTCollectionDisplay? + + pub let royalties: Royalties? + + pub let traits: Traits? +} +``` +NFTView wraps all Core views along `id` and `uuid` fields, and is used +to give a complete picture of an NFT. Most NFTs should implement this +view. + +[More...](MetadataViews_NFTView.md) + +--- + +### `Display` + +```cadence +pub struct Display { + + pub let name: String + + pub let description: String + + pub let thumbnail: AnyStruct{File} +} +``` +Display is a basic view that includes the name, description and +thumbnail for an object. Most objects should implement this view. + +[More...](MetadataViews_Display.md) + +--- + +### `HTTPFile` + +```cadence +pub struct HTTPFile { + + pub let url: String +} +``` +View to expose a file that is accessible at an HTTP (or HTTPS) URL. + +[More...](MetadataViews_HTTPFile.md) + +--- + +### `IPFSFile` + +```cadence +pub struct IPFSFile { + + pub let cid: String + + pub let path: String? +} +``` +View to expose a file stored on IPFS. +IPFS images are referenced by their content identifier (CID) +rather than a direct URI. A client application can use this CID +to find and load the image via an IPFS gateway. + +[More...](MetadataViews_IPFSFile.md) + +--- + +### `Edition` + +```cadence +pub struct Edition { + + pub let name: String? + + pub let number: UInt64 + + pub let max: UInt64? +} +``` +Optional view for collections that issue multiple objects +with the same or similar metadata, for example an X of 100 set. This +information is useful for wallets and marketplaces. +An NFT might be part of multiple editions, which is why the edition +information is returned as an arbitrary sized array + +[More...](MetadataViews_Edition.md) + +--- + +### `Editions` + +```cadence +pub struct Editions { + + pub let infoList: [Edition] +} +``` +Wrapper view for multiple Edition views + +[More...](MetadataViews_Editions.md) + +--- + +### `Serial` + +```cadence +pub struct Serial { + + pub let number: UInt64 +} +``` +View representing a project-defined serial number for a specific NFT +Projects have different definitions for what a serial number should be +Some may use the NFTs regular ID and some may use a different +classification system. The serial number is expected to be unique among +other NFTs within that project + +[More...](MetadataViews_Serial.md) + +--- + +### `Royalty` + +```cadence +pub struct Royalty { + + pub let receiver: Capability<&AnyResource{FungibleToken.Receiver}> + + pub let cut: UFix64 + + pub let description: String +} +``` +View that defines the composable royalty standard that gives marketplaces a +unified interface to support NFT royalties. + +[More...](MetadataViews_Royalty.md) + +--- + +### `Royalties` + +```cadence +pub struct Royalties { + + priv let cutInfos: [Royalty] +} +``` +Wrapper view for multiple Royalty views. +Marketplaces can query this `Royalties` struct from NFTs +and are expected to pay royalties based on these specifications. + +[More...](MetadataViews_Royalties.md) + +--- + +### `Media` + +```cadence +pub struct Media { + + pub let file: AnyStruct{File} + + pub let mediaType: String +} +``` +View to represent, a file with an correspoiding mediaType. + +[More...](MetadataViews_Media.md) + +--- + +### `Medias` + +```cadence +pub struct Medias { + + pub let items: [Media] +} +``` +Wrapper view for multiple media views + +[More...](MetadataViews_Medias.md) + +--- + +### `License` + +```cadence +pub struct License { + + pub let spdxIdentifier: String +} +``` +View to represent a license according to https://spdx.org/licenses/ +This view can be used if the content of an NFT is licensed. + +[More...](MetadataViews_License.md) + +--- + +### `ExternalURL` + +```cadence +pub struct ExternalURL { + + pub let url: String +} +``` +View to expose a URL to this item on an external site. +This can be used by applications like .find and Blocto to direct users +to the original link for an NFT. + +[More...](MetadataViews_ExternalURL.md) + +--- + +### `NFTCollectionData` + +```cadence +pub struct NFTCollectionData { + + pub let storagePath: StoragePath + + pub let publicPath: PublicPath + + pub let providerPath: PrivatePath + + pub let publicCollection: Type + + pub let publicLinkedType: Type + + pub let providerLinkedType: Type + + pub let createEmptyCollection: ((): @NonFungibleToken.Collection) +} +``` +View to expose the information needed store and retrieve an NFT. +This can be used by applications to setup a NFT collection with proper +storage and public capabilities. + +[More...](MetadataViews_NFTCollectionData.md) + +--- + +### `NFTCollectionDisplay` + +```cadence +pub struct NFTCollectionDisplay { + + pub let name: String + + pub let description: String + + pub let externalURL: ExternalURL + + pub let squareImage: Media + + pub let bannerImage: Media + + pub let socials: {String: ExternalURL} +} +``` +View to expose the information needed to showcase this NFT's +collection. This can be used by applications to give an overview and +graphics of the NFT collection this NFT belongs to. + +[More...](MetadataViews_NFTCollectionDisplay.md) + +--- + +### `Rarity` + +```cadence +pub struct Rarity { + + pub let score: UFix64? + + pub let max: UFix64? + + pub let description: String? +} +``` +View to expose rarity information for a single rarity +Note that a rarity needs to have either score or description but it can +have both + +[More...](MetadataViews_Rarity.md) + +--- + +### `Trait` + +```cadence +pub struct Trait { + + pub let name: String + + pub let value: AnyStruct + + pub let displayType: String? + + pub let rarity: Rarity? +} +``` +View to represent a single field of metadata on an NFT. +This is used to get traits of individual key/value pairs along with some +contextualized data about the trait + +[More...](MetadataViews_Trait.md) + +--- + +### `Traits` + +```cadence +pub struct Traits { + + pub let traits: [Trait] +} +``` +Wrapper view to return all the traits on an NFT. +This is used to return traits as individual key/value pairs along with +some contextualized data about each trait. + +[More...](MetadataViews_Traits.md) + +--- +## Functions + +### `getNFTView()` + +```cadence +fun getNFTView(id: UInt64, viewResolver: &{Resolver}): NFTView +``` +Helper to get an NFT view + +Parameters: + - id : _The NFT id_ + - viewResolver : _A reference to the resolver resource_ + +Returns: A NFTView struct + +--- + +### `getDisplay()` + +```cadence +fun getDisplay(_: &{Resolver}): Display? +``` +Helper to get Display in a typesafe way + +Parameters: + - viewResolver : _A reference to the resolver resource_ + +Returns: An optional Display struct + +--- + +### `getEditions()` + +```cadence +fun getEditions(_: &{Resolver}): Editions? +``` +Helper to get Editions in a typesafe way + +Parameters: + - viewResolver : _A reference to the resolver resource_ + +Returns: An optional Editions struct + +--- + +### `getSerial()` + +```cadence +fun getSerial(_: &{Resolver}): Serial? +``` +Helper to get Serial in a typesafe way + +Parameters: + - viewResolver : _A reference to the resolver resource_ + +Returns: An optional Serial struct + +--- + +### `getRoyalties()` + +```cadence +fun getRoyalties(_: &{Resolver}): Royalties? +``` +Helper to get Royalties in a typesafe way + +Parameters: + - viewResolver : _A reference to the resolver resource_ + +Returns: A optional Royalties struct + +--- + +### `getRoyaltyReceiverPublicPath()` + +```cadence +fun getRoyaltyReceiverPublicPath(): PublicPath +``` +Get the path that should be used for receiving royalties +This is a path that will eventually be used for a generic switchboard receiver, +hence the name but will only be used for royalties for now. + +Returns: The PublicPath for the generic FT receiver + +--- + +### `getMedias()` + +```cadence +fun getMedias(_: &{Resolver}): Medias? +``` +Helper to get Medias in a typesafe way + +Parameters: + - viewResolver : _A reference to the resolver resource_ + +Returns: A optional Medias struct + +--- + +### `getLicense()` + +```cadence +fun getLicense(_: &{Resolver}): License? +``` +Helper to get License in a typesafe way + +Parameters: + - viewResolver : _A reference to the resolver resource_ + +Returns: A optional License struct + +--- + +### `getExternalURL()` + +```cadence +fun getExternalURL(_: &{Resolver}): ExternalURL? +``` +Helper to get ExternalURL in a typesafe way + +Parameters: + - viewResolver : _A reference to the resolver resource_ + +Returns: A optional ExternalURL struct + +--- + +### `getNFTCollectionData()` + +```cadence +fun getNFTCollectionData(_: &{Resolver}): NFTCollectionData? +``` +Helper to get NFTCollectionData in a way that will return an typed Optional + +Parameters: + - viewResolver : _A reference to the resolver resource_ + +Returns: A optional NFTCollectionData struct + +--- + +### `getNFTCollectionDisplay()` + +```cadence +fun getNFTCollectionDisplay(_: &{Resolver}): NFTCollectionDisplay? +``` +Helper to get NFTCollectionDisplay in a way that will return a typed +Optional + +Parameters: + - viewResolver : _A reference to the resolver resource_ + +Returns: A optional NFTCollection struct + +--- + +### `getRarity()` + +```cadence +fun getRarity(_: &{Resolver}): Rarity? +``` +Helper to get Rarity view in a typesafe way + +Parameters: + - viewResolver : _A reference to the resolver resource_ + +Returns: A optional Rarity struct + +--- + +### `getTraits()` + +```cadence +fun getTraits(_: &{Resolver}): Traits? +``` +Helper to get Traits view in a typesafe way + +Parameters: + - viewResolver : _A reference to the resolver resource_ + +Returns: A optional Traits struct + +--- + +### `dictToTraits()` + +```cadence +fun dictToTraits(dict: {String: AnyStruct}, excludedNames: [String]?): Traits +``` +Helper function to easily convert a dictionary to traits. For NFT +collections that do not need either of the optional values of a Trait, +this method should suffice to give them an array of valid traits. + +keys that are not wanted to become `Traits` + +Parameters: + - dict : _The dictionary to be converted to Traits_ + - excludedNames : _An optional String array specifying the `dict`_ + +Returns: The generated Traits view + +--- diff --git a/docs/references/core-contracts/flow-nft/MetdataViews/MetadataViews_Display.md b/docs/references/core-contracts/flow-nft/MetdataViews/MetadataViews_Display.md new file mode 100644 index 0000000000..20317c783e --- /dev/null +++ b/docs/references/core-contracts/flow-nft/MetdataViews/MetadataViews_Display.md @@ -0,0 +1,23 @@ +# Struct `Display` + +```cadence +pub struct Display { + + pub let name: String + + pub let description: String + + pub let thumbnail: AnyStruct{File} +} +``` + +Display is a basic view that includes the name, description and +thumbnail for an object. Most objects should implement this view. + +### Initializer + +```cadence +init(name: String, description: String, thumbnail: AnyStruct{File}) +``` + + diff --git a/docs/references/core-contracts/flow-nft/MetdataViews/MetadataViews_Edition.md b/docs/references/core-contracts/flow-nft/MetdataViews/MetadataViews_Edition.md new file mode 100644 index 0000000000..a78ab4d259 --- /dev/null +++ b/docs/references/core-contracts/flow-nft/MetdataViews/MetadataViews_Edition.md @@ -0,0 +1,26 @@ +# Struct `Edition` + +```cadence +pub struct Edition { + + pub let name: String? + + pub let number: UInt64 + + pub let max: UInt64? +} +``` + +Optional view for collections that issue multiple objects +with the same or similar metadata, for example an X of 100 set. This +information is useful for wallets and marketplaces. +An NFT might be part of multiple editions, which is why the edition +information is returned as an arbitrary sized array + +### Initializer + +```cadence +init(name: String?, number: UInt64, max: UInt64?) +``` + + diff --git a/docs/references/core-contracts/flow-nft/MetdataViews/MetadataViews_Editions.md b/docs/references/core-contracts/flow-nft/MetdataViews/MetadataViews_Editions.md new file mode 100644 index 0000000000..aea84b99b3 --- /dev/null +++ b/docs/references/core-contracts/flow-nft/MetdataViews/MetadataViews_Editions.md @@ -0,0 +1,18 @@ +# Struct `Editions` + +```cadence +pub struct Editions { + + pub let infoList: [Edition] +} +``` + +Wrapper view for multiple Edition views + +### Initializer + +```cadence +init(_: [Edition]) +``` + + diff --git a/docs/references/core-contracts/flow-nft/MetdataViews/MetadataViews_ExternalURL.md b/docs/references/core-contracts/flow-nft/MetdataViews/MetadataViews_ExternalURL.md new file mode 100644 index 0000000000..a0d58d153f --- /dev/null +++ b/docs/references/core-contracts/flow-nft/MetdataViews/MetadataViews_ExternalURL.md @@ -0,0 +1,20 @@ +# Struct `ExternalURL` + +```cadence +pub struct ExternalURL { + + pub let url: String +} +``` + +View to expose a URL to this item on an external site. +This can be used by applications like .find and Blocto to direct users +to the original link for an NFT. + +### Initializer + +```cadence +init(_: String) +``` + + diff --git a/docs/references/core-contracts/flow-nft/MetdataViews/MetadataViews_File.md b/docs/references/core-contracts/flow-nft/MetdataViews/MetadataViews_File.md new file mode 100644 index 0000000000..7850170d2a --- /dev/null +++ b/docs/references/core-contracts/flow-nft/MetdataViews/MetadataViews_File.md @@ -0,0 +1,18 @@ +# Struct Interface `File` + +```cadence +pub struct interface File { +} +``` + +Generic interface that represents a file stored on or off chain. Files +can be used to references images, videos and other media. +## Functions + +### `uri()` + +```cadence +fun uri(): String +``` + +--- diff --git a/docs/references/core-contracts/flow-nft/MetdataViews/MetadataViews_HTTPFile.md b/docs/references/core-contracts/flow-nft/MetdataViews/MetadataViews_HTTPFile.md new file mode 100644 index 0000000000..f8c8f75286 --- /dev/null +++ b/docs/references/core-contracts/flow-nft/MetdataViews/MetadataViews_HTTPFile.md @@ -0,0 +1,31 @@ +# Struct `HTTPFile` + +```cadence +pub struct HTTPFile { + + pub let url: String +} +``` + +View to expose a file that is accessible at an HTTP (or HTTPS) URL. + +Implemented Interfaces: + - `File` + + +### Initializer + +```cadence +init(url: String) +``` + + +## Functions + +### `uri()` + +```cadence +fun uri(): String +``` + +--- diff --git a/docs/references/core-contracts/flow-nft/MetdataViews/MetadataViews_IPFSFile.md b/docs/references/core-contracts/flow-nft/MetdataViews/MetadataViews_IPFSFile.md new file mode 100644 index 0000000000..a2f0972335 --- /dev/null +++ b/docs/references/core-contracts/flow-nft/MetdataViews/MetadataViews_IPFSFile.md @@ -0,0 +1,40 @@ +# Struct `IPFSFile` + +```cadence +pub struct IPFSFile { + + pub let cid: String + + pub let path: String? +} +``` + +View to expose a file stored on IPFS. +IPFS images are referenced by their content identifier (CID) +rather than a direct URI. A client application can use this CID +to find and load the image via an IPFS gateway. + +Implemented Interfaces: + - `File` + + +### Initializer + +```cadence +init(cid: String, path: String?) +``` + + +## Functions + +### `uri()` + +```cadence +fun uri(): String +``` +This function returns the IPFS native URL for this file. +Ref: https://docs.ipfs.io/how-to/address-ipfs-on-web/#native-urls + +Returns: The string containing the file uri + +--- diff --git a/docs/references/core-contracts/flow-nft/MetdataViews/MetadataViews_License.md b/docs/references/core-contracts/flow-nft/MetdataViews/MetadataViews_License.md new file mode 100644 index 0000000000..5017d304a5 --- /dev/null +++ b/docs/references/core-contracts/flow-nft/MetdataViews/MetadataViews_License.md @@ -0,0 +1,19 @@ +# Struct `License` + +```cadence +pub struct License { + + pub let spdxIdentifier: String +} +``` + +View to represent a license according to https://spdx.org/licenses/ +This view can be used if the content of an NFT is licensed. + +### Initializer + +```cadence +init(_: String) +``` + + diff --git a/docs/references/core-contracts/flow-nft/MetdataViews/MetadataViews_Media.md b/docs/references/core-contracts/flow-nft/MetdataViews/MetadataViews_Media.md new file mode 100644 index 0000000000..ad08a90868 --- /dev/null +++ b/docs/references/core-contracts/flow-nft/MetdataViews/MetadataViews_Media.md @@ -0,0 +1,20 @@ +# Struct `Media` + +```cadence +pub struct Media { + + pub let file: AnyStruct{File} + + pub let mediaType: String +} +``` + +View to represent, a file with an correspoiding mediaType. + +### Initializer + +```cadence +init(file: AnyStruct{File}, mediaType: String) +``` + + diff --git a/docs/references/core-contracts/flow-nft/MetdataViews/MetadataViews_Medias.md b/docs/references/core-contracts/flow-nft/MetdataViews/MetadataViews_Medias.md new file mode 100644 index 0000000000..35e450e4c2 --- /dev/null +++ b/docs/references/core-contracts/flow-nft/MetdataViews/MetadataViews_Medias.md @@ -0,0 +1,18 @@ +# Struct `Medias` + +```cadence +pub struct Medias { + + pub let items: [Media] +} +``` + +Wrapper view for multiple media views + +### Initializer + +```cadence +init(_: [Media]) +``` + + diff --git a/docs/references/core-contracts/flow-nft/MetdataViews/MetadataViews_NFTCollectionData.md b/docs/references/core-contracts/flow-nft/MetdataViews/MetadataViews_NFTCollectionData.md new file mode 100644 index 0000000000..887c8df82b --- /dev/null +++ b/docs/references/core-contracts/flow-nft/MetdataViews/MetadataViews_NFTCollectionData.md @@ -0,0 +1,32 @@ +# Struct `NFTCollectionData` + +```cadence +pub struct NFTCollectionData { + + pub let storagePath: StoragePath + + pub let publicPath: PublicPath + + pub let providerPath: PrivatePath + + pub let publicCollection: Type + + pub let publicLinkedType: Type + + pub let providerLinkedType: Type + + pub let createEmptyCollection: ((): @NonFungibleToken.Collection) +} +``` + +View to expose the information needed store and retrieve an NFT. +This can be used by applications to setup a NFT collection with proper +storage and public capabilities. + +### Initializer + +```cadence +init(storagePath: StoragePath, publicPath: PublicPath, providerPath: PrivatePath, publicCollection: Type, publicLinkedType: Type, providerLinkedType: Type, createEmptyCollectionFunction: ((): @NonFungibleToken.Collection)) +``` + + diff --git a/docs/references/core-contracts/flow-nft/MetdataViews/MetadataViews_NFTCollectionDisplay.md b/docs/references/core-contracts/flow-nft/MetdataViews/MetadataViews_NFTCollectionDisplay.md new file mode 100644 index 0000000000..c29a6ebcbf --- /dev/null +++ b/docs/references/core-contracts/flow-nft/MetdataViews/MetadataViews_NFTCollectionDisplay.md @@ -0,0 +1,30 @@ +# Struct `NFTCollectionDisplay` + +```cadence +pub struct NFTCollectionDisplay { + + pub let name: String + + pub let description: String + + pub let externalURL: ExternalURL + + pub let squareImage: Media + + pub let bannerImage: Media + + pub let socials: {String: ExternalURL} +} +``` + +View to expose the information needed to showcase this NFT's +collection. This can be used by applications to give an overview and +graphics of the NFT collection this NFT belongs to. + +### Initializer + +```cadence +init(name: String, description: String, externalURL: ExternalURL, squareImage: Media, bannerImage: Media, socials: {String: ExternalURL}) +``` + + diff --git a/docs/references/core-contracts/flow-nft/MetdataViews/MetadataViews_NFTView.md b/docs/references/core-contracts/flow-nft/MetdataViews/MetadataViews_NFTView.md new file mode 100644 index 0000000000..1613bbf1fd --- /dev/null +++ b/docs/references/core-contracts/flow-nft/MetdataViews/MetadataViews_NFTView.md @@ -0,0 +1,34 @@ +# Struct `NFTView` + +```cadence +pub struct NFTView { + + pub let id: UInt64 + + pub let uuid: UInt64 + + pub let display: Display? + + pub let externalURL: ExternalURL? + + pub let collectionData: NFTCollectionData? + + pub let collectionDisplay: NFTCollectionDisplay? + + pub let royalties: Royalties? + + pub let traits: Traits? +} +``` + +NFTView wraps all Core views along `id` and `uuid` fields, and is used +to give a complete picture of an NFT. Most NFTs should implement this +view. + +### Initializer + +```cadence +init(id: UInt64, uuid: UInt64, display: Display?, externalURL: ExternalURL?, collectionData: NFTCollectionData?, collectionDisplay: NFTCollectionDisplay?, royalties: Royalties?, traits: Traits?) +``` + + diff --git a/docs/references/core-contracts/flow-nft/MetdataViews/MetadataViews_Rarity.md b/docs/references/core-contracts/flow-nft/MetdataViews/MetadataViews_Rarity.md new file mode 100644 index 0000000000..5400ebc773 --- /dev/null +++ b/docs/references/core-contracts/flow-nft/MetdataViews/MetadataViews_Rarity.md @@ -0,0 +1,24 @@ +# Struct `Rarity` + +```cadence +pub struct Rarity { + + pub let score: UFix64? + + pub let max: UFix64? + + pub let description: String? +} +``` + +View to expose rarity information for a single rarity +Note that a rarity needs to have either score or description but it can +have both + +### Initializer + +```cadence +init(score: UFix64?, max: UFix64?, description: String?) +``` + + diff --git a/docs/references/core-contracts/flow-nft/MetdataViews/MetadataViews_Resolver.md b/docs/references/core-contracts/flow-nft/MetdataViews/MetadataViews_Resolver.md new file mode 100644 index 0000000000..12d16a0968 --- /dev/null +++ b/docs/references/core-contracts/flow-nft/MetdataViews/MetadataViews_Resolver.md @@ -0,0 +1,27 @@ +# Resource Interface `Resolver` + +```cadence +pub resource interface Resolver { +} +``` + +Provides access to a set of metadata views. A struct or +resource (e.g. an NFT) can implement this interface to provide access to +the views that it supports. +## Functions + +### `getViews()` + +```cadence +fun getViews(): [Type] +``` + +--- + +### `resolveView()` + +```cadence +fun resolveView(_: Type): AnyStruct? +``` + +--- diff --git a/docs/references/core-contracts/flow-nft/MetdataViews/MetadataViews_ResolverCollection.md b/docs/references/core-contracts/flow-nft/MetdataViews/MetadataViews_ResolverCollection.md new file mode 100644 index 0000000000..6371efffab --- /dev/null +++ b/docs/references/core-contracts/flow-nft/MetdataViews/MetadataViews_ResolverCollection.md @@ -0,0 +1,25 @@ +# Resource Interface `ResolverCollection` + +```cadence +pub resource interface ResolverCollection { +} +``` + +A group of view resolvers indexed by ID. +## Functions + +### `borrowViewResolver()` + +```cadence +fun borrowViewResolver(id: UInt64): &{Resolver} +``` + +--- + +### `getIDs()` + +```cadence +fun getIDs(): [UInt64] +``` + +--- diff --git a/docs/references/core-contracts/flow-nft/MetdataViews/MetadataViews_Royalties.md b/docs/references/core-contracts/flow-nft/MetdataViews/MetadataViews_Royalties.md new file mode 100644 index 0000000000..14cecdbae2 --- /dev/null +++ b/docs/references/core-contracts/flow-nft/MetdataViews/MetadataViews_Royalties.md @@ -0,0 +1,32 @@ +# Struct `Royalties` + +```cadence +pub struct Royalties { + + priv let cutInfos: [Royalty] +} +``` + +Wrapper view for multiple Royalty views. +Marketplaces can query this `Royalties` struct from NFTs +and are expected to pay royalties based on these specifications. + +### Initializer + +```cadence +init(_: [Royalty]) +``` + + +## Functions + +### `getRoyalties()` + +```cadence +fun getRoyalties(): [Royalty] +``` +Return the cutInfos list + +Returns: An array containing all the royalties structs + +--- diff --git a/docs/references/core-contracts/flow-nft/MetdataViews/MetadataViews_Royalty.md b/docs/references/core-contracts/flow-nft/MetdataViews/MetadataViews_Royalty.md new file mode 100644 index 0000000000..54c98c2ebb --- /dev/null +++ b/docs/references/core-contracts/flow-nft/MetdataViews/MetadataViews_Royalty.md @@ -0,0 +1,23 @@ +# Struct `Royalty` + +```cadence +pub struct Royalty { + + pub let receiver: Capability<&AnyResource{FungibleToken.Receiver}> + + pub let cut: UFix64 + + pub let description: String +} +``` + +View that defines the composable royalty standard that gives marketplaces a +unified interface to support NFT royalties. + +### Initializer + +```cadence +init(receiver: Capability<&AnyResource{FungibleToken.Receiver}>, cut: UFix64, description: String) +``` + + diff --git a/docs/references/core-contracts/flow-nft/MetdataViews/MetadataViews_Serial.md b/docs/references/core-contracts/flow-nft/MetdataViews/MetadataViews_Serial.md new file mode 100644 index 0000000000..c5ab8d7f4f --- /dev/null +++ b/docs/references/core-contracts/flow-nft/MetdataViews/MetadataViews_Serial.md @@ -0,0 +1,22 @@ +# Struct `Serial` + +```cadence +pub struct Serial { + + pub let number: UInt64 +} +``` + +View representing a project-defined serial number for a specific NFT +Projects have different definitions for what a serial number should be +Some may use the NFTs regular ID and some may use a different +classification system. The serial number is expected to be unique among +other NFTs within that project + +### Initializer + +```cadence +init(_: UInt64) +``` + + diff --git a/docs/references/core-contracts/flow-nft/MetdataViews/MetadataViews_Trait.md b/docs/references/core-contracts/flow-nft/MetdataViews/MetadataViews_Trait.md new file mode 100644 index 0000000000..7e140a4522 --- /dev/null +++ b/docs/references/core-contracts/flow-nft/MetdataViews/MetadataViews_Trait.md @@ -0,0 +1,26 @@ +# Struct `Trait` + +```cadence +pub struct Trait { + + pub let name: String + + pub let value: AnyStruct + + pub let displayType: String? + + pub let rarity: Rarity? +} +``` + +View to represent a single field of metadata on an NFT. +This is used to get traits of individual key/value pairs along with some +contextualized data about the trait + +### Initializer + +```cadence +init(name: String, value: AnyStruct, displayType: String?, rarity: Rarity?) +``` + + diff --git a/docs/references/core-contracts/flow-nft/MetdataViews/MetadataViews_Traits.md b/docs/references/core-contracts/flow-nft/MetdataViews/MetadataViews_Traits.md new file mode 100644 index 0000000000..ff0db7fbc2 --- /dev/null +++ b/docs/references/core-contracts/flow-nft/MetdataViews/MetadataViews_Traits.md @@ -0,0 +1,33 @@ +# Struct `Traits` + +```cadence +pub struct Traits { + + pub let traits: [Trait] +} +``` + +Wrapper view to return all the traits on an NFT. +This is used to return traits as individual key/value pairs along with +some contextualized data about each trait. + +### Initializer + +```cadence +init(_: [Trait]) +``` + + +## Functions + +### `addTrait()` + +```cadence +fun addTrait(_: Trait) +``` +Adds a single Trait to the Traits view + +Parameters: + - Trait : _The trait struct to be added_ + +--- diff --git a/docs/references/core-contracts/flow-nft/NonFungibleToken/NonFungibleToken.md b/docs/references/core-contracts/flow-nft/NonFungibleToken/NonFungibleToken.md new file mode 100644 index 0000000000..b4a4cf3a58 --- /dev/null +++ b/docs/references/core-contracts/flow-nft/NonFungibleToken/NonFungibleToken.md @@ -0,0 +1,143 @@ +# Contract Interface `NonFungibleToken` + +```cadence +pub contract interface NonFungibleToken { + + pub var totalSupply: UInt64 +} +``` + +The main NFT contract interface. Other NFT contracts will +import and implement this interface +## Interfaces + +### `INFT` + +```cadence +pub resource interface INFT { + + pub let id: UInt64 +} +``` +Interface that the NFTs have to conform to +The metadata views methods are included here temporarily +because enforcing the metadata interfaces in the standard +would break many contracts in an upgrade. Those breaking changes +are being saved for the stable cadence milestone + +[More...](NonFungibleToken_INFT.md) + +--- + +### `Provider` + +```cadence +pub resource interface Provider { +} +``` +Interface to mediate withdraws from the Collection + +[More...](NonFungibleToken_Provider.md) + +--- + +### `Receiver` + +```cadence +pub resource interface Receiver { +} +``` +Interface to mediate deposits to the Collection + +[More...](NonFungibleToken_Receiver.md) + +--- + +### `CollectionPublic` + +```cadence +pub resource interface CollectionPublic { +} +``` +Interface that an account would commonly +publish for their collection + +[More...](NonFungibleToken_CollectionPublic.md) + +--- +## Structs & Resources + +### `NFT` + +```cadence +pub resource NFT { + + pub let id: UInt64 +} +``` +Requirement that all conforming NFT smart contracts have +to define a resource called NFT that conforms to INFT + +[More...](NonFungibleToken_NFT.md) + +--- + +### `Collection` + +```cadence +pub resource Collection { + + pub var ownedNFTs: {UInt64: NFT} +} +``` +Requirement for the concrete resource type +to be declared in the implementing contract + +[More...](NonFungibleToken_Collection.md) + +--- +## Functions + +### `createEmptyCollection()` + +```cadence +fun createEmptyCollection(): Collection +``` +Creates an empty Collection and returns it to the caller so that they can own NFTs + +Returns: A new Collection resource + +--- +## Events + +### `ContractInitialized` + +```cadence +pub event ContractInitialized() +``` +Event that emitted when the NFT contract is initialized + +--- + +### `Withdraw` + +```cadence +pub event Withdraw(id: UInt64, from: Address?) +``` +Event that is emitted when a token is withdrawn, +indicating the owner of the collection that it was withdrawn from. + +If the collection is not in an account's storage, `from` will be `nil`. + +--- + +### `Deposit` + +```cadence +pub event Deposit(id: UInt64, to: Address?) +``` +Event that emitted when a token is deposited to a collection. + +It indicates the owner of the collection that it was deposited to. + +--- diff --git a/docs/references/core-contracts/flow-nft/NonFungibleToken/NonFungibleToken_Collection.md b/docs/references/core-contracts/flow-nft/NonFungibleToken/NonFungibleToken_Collection.md new file mode 100644 index 0000000000..cb0dd6cd06 --- /dev/null +++ b/docs/references/core-contracts/flow-nft/NonFungibleToken/NonFungibleToken_Collection.md @@ -0,0 +1,56 @@ +# Resource `Collection` + +```cadence +pub resource Collection { + + pub var ownedNFTs: {UInt64: NFT} +} +``` + +Requirement for the concrete resource type +to be declared in the implementing contract + +Implemented Interfaces: + - `Provider` + - `Receiver` + - `CollectionPublic` + +## Functions + +### `withdraw()` + +```cadence +fun withdraw(withdrawID: UInt64): NFT +``` +Removes an NFT from the collection and moves it to the caller + +Parameters: + - withdrawID : _The ID of the NFT that will be withdrawn_ + +Returns: The resource containing the desired NFT + +--- + +### `deposit()` + +```cadence +fun deposit(token: NFT) +``` + +--- + +### `getIDs()` + +```cadence +fun getIDs(): [UInt64] +``` + +--- + +### `borrowNFT()` + +```cadence +fun borrowNFT(id: UInt64): &NFT +``` + +--- diff --git a/docs/references/core-contracts/flow-nft/NonFungibleToken/NonFungibleToken_CollectionPublic.md b/docs/references/core-contracts/flow-nft/NonFungibleToken/NonFungibleToken_CollectionPublic.md new file mode 100644 index 0000000000..19517fea6a --- /dev/null +++ b/docs/references/core-contracts/flow-nft/NonFungibleToken/NonFungibleToken_CollectionPublic.md @@ -0,0 +1,42 @@ +# Resource Interface `CollectionPublic` + +```cadence +pub resource interface CollectionPublic { +} +``` + +Interface that an account would commonly +publish for their collection +## Functions + +### `deposit()` + +```cadence +fun deposit(token: NFT) +``` + +--- + +### `getIDs()` + +```cadence +fun getIDs(): [UInt64] +``` + +--- + +### `borrowNFT()` + +```cadence +fun borrowNFT(id: UInt64): &NFT +``` + +--- + +### `borrowNFTSafe()` + +```cadence +fun borrowNFTSafe(id: UInt64): &NFT? +``` + +--- diff --git a/docs/references/core-contracts/flow-nft/NonFungibleToken/NonFungibleToken_INFT.md b/docs/references/core-contracts/flow-nft/NonFungibleToken/NonFungibleToken_INFT.md new file mode 100644 index 0000000000..36116a6e1e --- /dev/null +++ b/docs/references/core-contracts/flow-nft/NonFungibleToken/NonFungibleToken_INFT.md @@ -0,0 +1,42 @@ +# Resource Interface `INFT` + +```cadence +pub resource interface INFT { + + pub let id: UInt64 +} +``` + +Interface that the NFTs have to conform to +The metadata views methods are included here temporarily +because enforcing the metadata interfaces in the standard +would break many contracts in an upgrade. Those breaking changes +are being saved for the stable cadence milestone +## Functions + +### `getViews()` + +```cadence +fun getViews(): [Type] +``` +Function that returns all the Metadata Views implemented by a Non Fungible Token + +developers to know which parameter to pass to the resolveView() method. + +Returns: An array of Types defining the implemented views. This value will be used by + +--- + +### `resolveView()` + +```cadence +fun resolveView(_: Type): AnyStruct? +``` +Function that resolves a metadata view for this token. + +Parameters: + - view : _The Type of the desired view._ + +Returns: A structure representing the requested view. + +--- diff --git a/docs/references/core-contracts/flow-nft/NonFungibleToken/NonFungibleToken_NFT.md b/docs/references/core-contracts/flow-nft/NonFungibleToken/NonFungibleToken_NFT.md new file mode 100644 index 0000000000..e5e9c58147 --- /dev/null +++ b/docs/references/core-contracts/flow-nft/NonFungibleToken/NonFungibleToken_NFT.md @@ -0,0 +1,15 @@ +# Resource `NFT` + +```cadence +pub resource NFT { + + pub let id: UInt64 +} +``` + +Requirement that all conforming NFT smart contracts have +to define a resource called NFT that conforms to INFT + +Implemented Interfaces: + - `INFT` + diff --git a/docs/references/core-contracts/flow-nft/NonFungibleToken/NonFungibleToken_Provider.md b/docs/references/core-contracts/flow-nft/NonFungibleToken/NonFungibleToken_Provider.md new file mode 100644 index 0000000000..32c95d138b --- /dev/null +++ b/docs/references/core-contracts/flow-nft/NonFungibleToken/NonFungibleToken_Provider.md @@ -0,0 +1,23 @@ +# Resource Interface `Provider` + +```cadence +pub resource interface Provider { +} +``` + +Interface to mediate withdraws from the Collection +## Functions + +### `withdraw()` + +```cadence +fun withdraw(withdrawID: UInt64): NFT +``` +Removes an NFT from the resource implementing it and moves it to the caller + +Parameters: + - withdrawID : _The ID of the NFT that will be removed_ + +Returns: The NFT resource removed from the implementing resource + +--- diff --git a/docs/references/core-contracts/flow-nft/NonFungibleToken/NonFungibleToken_Receiver.md b/docs/references/core-contracts/flow-nft/NonFungibleToken/NonFungibleToken_Receiver.md new file mode 100644 index 0000000000..3883c6fdd0 --- /dev/null +++ b/docs/references/core-contracts/flow-nft/NonFungibleToken/NonFungibleToken_Receiver.md @@ -0,0 +1,21 @@ +# Resource Interface `Receiver` + +```cadence +pub resource interface Receiver { +} +``` + +Interface to mediate deposits to the Collection +## Functions + +### `deposit()` + +```cadence +fun deposit(token: NFT) +``` +Adds an NFT to the resource implementing it + +Parameters: + - token : _The NFT resource that will be deposited_ + +--- diff --git a/docs/reference/core-contracts/flow-nft/index.md b/docs/references/core-contracts/flow-nft/index.md similarity index 99% rename from docs/reference/core-contracts/flow-nft/index.md rename to docs/references/core-contracts/flow-nft/index.md index d9c64264c4..7403ddbcdd 100644 --- a/docs/reference/core-contracts/flow-nft/index.md +++ b/docs/references/core-contracts/flow-nft/index.md @@ -1,5 +1,5 @@ --- -sidebar_position: 3 +sidebar_position: 1 --- # Flow Non-Fungible Token (NFT) Standard diff --git a/docs/references/core-contracts/flow-nft/overview.md b/docs/references/core-contracts/flow-nft/overview.md deleted file mode 100644 index 449ca451f6..0000000000 --- a/docs/references/core-contracts/flow-nft/overview.md +++ /dev/null @@ -1,381 +0,0 @@ -# Flow Non-Fungible Token Standard - -This standard defines the minimum functionality required to -implement a safe, secure, and easy-to-use non-fungible token -contract on the [Flow blockchain](https://www.onflow.org/). - -## What is Cadence? - -[Cadence is the resource-oriented programming language](https://docs.onflow.org/cadence) -for developing smart contracts on Flow. - -Before reading this standard, -we recommend completing the [Cadence tutorials](https://docs.onflow.org/cadence/tutorial/01-first-steps/) -to build a basic understanding of the programming language. - -Resource-oriented programming, and by extension Cadence, -provides an ideal programming model for non-fungible tokens (NFTs). -Users are able to store their NFT objects directly in their accounts and transact -peer-to-peer. Learn more in this [blog post about resources](https://medium.com/dapperlabs/resource-oriented-programming-bee4d69c8f8e). - -## Core features - -The `NonFungibleToken` contract defines the following set of functionality -that must be included in each implementation. - -Contracts that implement the `NonFungibleToken` interface are required to implement two resource interfaces: - -- `NFT` - A resource that describes the structure of a single NFT. -- `Collection` - A resource that can hold multiple NFTs of the same type. - - Users typically store one collection per NFT type, saved at a well-known location in their account storage. - - For example, all NBA Top Shot Moments owned by a single user are held in a [`TopShot.Collection`](https://github.com/dapperlabs/nba-smart-contracts/blob/master/contracts/TopShot.cdc#L605) stored in their account at the path `/storage/MomentCollection`. - -### Create a new NFT collection - -Create a new collection using the `createEmptyCollection` function. - -This function MUST return an empty collection that contains no NFTs. - -Users typically save new collections to a well-known location in their account -and link the `NonFungibleToken.CollectionPublic` interface as a public capability. - -```swift -let collection <- ExampleNFT.createEmptyCollection() - -account.save(<-collection, to: /storage/ExampleNFTCollection) - -// create a public capability for the collection -account.link<&{NonFungibleToken.CollectionPublic}>( - /public/ExampleNFTCollection, - target: /storage/ExampleNFTCollection -) -``` - -### Withdraw an NFT - -Withdraw an `NFT` from a `Collection` using the [`withdraw`](https://github.com/onflow/flow-nft/blob/master/contracts/ExampleNFT.cdc#L36-L42) function. -This function emits the [`Withdraw`](https://github.com/onflow/flow-nft/blob/master/contracts/ExampleNFT.cdc#L12) event. - -```swift -let collectionRef = account.borrow<&ExampleNFT.Collection>(from: /storage/ExampleNFTCollection) - ?? panic("Could not borrow a reference to the owner's collection") - -// withdraw the NFT from the owner's collection -let nft <- collectionRef.withdraw(withdrawID: 42) -``` - -### Deposit an NFT - -Deposit an `NFT` into a `Collection` using the [`deposit`](https://github.com/onflow/flow-nft/blob/master/contracts/ExampleNFT.cdc#L46-L57) function. -This function emits the [`Deposit`](https://github.com/onflow/flow-nft/blob/master/contracts/ExampleNFT.cdc#L13) event. - -This function is available on the `NonFungibleToken.CollectionPublic` interface, -which accounts publish as public capability. -This capability allows anybody to deposit an NFT into a collection -without accessing the entire collection. - -```swift -let nft: ExampleNFT.NFT - -// ... - -let collection = account.getCapability(/public/ExampleNFTCollection) - .borrow<&{NonFungibleToken.CollectionPublic}>() - ?? panic("Could not borrow a reference to the receiver's collection") - -collection.deposit(token: <-nft) -``` - -#### ⚠️ Important - -In order to comply with the deposit function in the interface, -an implementation MUST take a `@NonFungibleToken.NFT` resource as an argument. -This means that anyone can send a resource object that conforms to `@NonFungibleToken.NFT` to a deposit function. -In an implementation, you MUST cast the `token` as your specific token type before depositing it or you will -deposit another token type into your collection. For example: - -```swift -let token <- token as! @ExampleNFT.NFT -``` - -### List NFTs in an account - -Return a list of NFTs in a `Collection` using the [`getIDs`](https://github.com/onflow/flow-nft/blob/master/contracts/ExampleNFT.cdc#L59-L62) function. - -This function is available on the `NonFungibleToken.CollectionPublic` interface, -which accounts publish as public capability. - -```swift -let collection = account.getCapability(/public/ExampleNFTCollection) - .borrow<&{NonFungibleToken.CollectionPublic}>() - ?? panic("Could not borrow a reference to the receiver's collection") - -let ids = collection.getIDs() -``` - -## NFT Metadata - -NFT metadata is represented in a flexible and modular way using -the [standard proposed in FLIP-0636](https://github.com/onflow/flow/blob/master/flips/20210916-nft-metadata.md). - -When writing an NFT contract, -you should implement the [`MetadataViews.Resolver`](https://github.com/onflow/flow-nft/blob/master/contracts/MetadataViews.cdc#L3-L6)interface, -which allows your NFT to implement one or more metadata types called views. - -Each view represents a different type of metadata, -such as an on-chain creator biography or an off-chain video clip. -Views do not specify or require how to store your metadata, they only specify -the format to query and return them, so projects can still be flexible with how they store their data. - -### How to read metadata - -This example shows how to read basic information about an NFT -including the name, description, image and owner. - -**Source: [get_nft_metadata.cdc](https://github.com/onflow/flow-nft/blob/master/scripts/get_nft_metadata.cdc)** - -```swift -import ExampleNFT from "..." -import MetadataViews from "..." - -// ... - -// Get the regular public capability -let collection = account.getCapability(ExampleNFT.CollectionPublicPath) - .borrow<&{ExampleNFT.ExampleNFTCollectionPublic}>() - ?? panic("Could not borrow a reference to the collection") - -// Borrow a reference to the NFT as usual -let nft = collection.borrowExampleNFT(id: 42) - ?? panic("Could not borrow a reference to the NFT") - -// Call the resolveView method -// Provide the type of the view that you want to resolve -// View types are defined in the MetadataViews contract -// You can see if an NFT supports a specific view type by using the `getViews()` method -if let view = nft.resolveView(Type()) { - let display = view as! MetadataViews.Display - - log(display.name) - log(display.description) - log(display.thumbnail) -} - -// The owner is stored directly on the NFT object -let owner: Address = nft.owner!.address! - -// Inspect the type of this NFT to verify its origin -let nftType = nft.getType() - -// `nftType.identifier` is `A.e03daebed8ca0615.ExampleNFT.NFT` -``` - -### How to implement metadata - -The [example NFT contract](https://github.com/onflow/flow-nft/blob/master/contracts/ExampleNFT.cdc) shows how to implement metadata views. - -### List of common views - -| Name | Purpose | Status | Source | -| ----------- | ------------------------------------------ | ----------- | --------------------------------------------------------------------------------------------------------- | -| `Display` | Return the basic representation of an NFT. | Implemented | [MetadataViews.cdc](https://github.com/onflow/flow-nft/blob/master/contracts/MetadataViews.cdc#L35-L70) | -| `HTTPFile` | A file available at an HTTP(S) URL. | Implemented | [MetadataViews.cdc](https://github.com/onflow/flow-nft/blob/master/contracts/MetadataViews.cdc#L80-L92) | -| `IPFSFile` | A file stored in IPFS. | Implemented | [MetadataViews.cdc](https://github.com/onflow/flow-nft/blob/master/contracts/MetadataViews.cdc#L94-L133) | -| `Royalties` | An array of Royalty Cuts for a given NFT. | Implemented | [MetadataViews.cdc](https://github.com/onflow/flow-nft/blob/master/contracts/MetadataViews.cdc#L136-L208) | - -## Royalty View - -The `MetadataViews` contract also includes [a standard view for Royalties](https://github.com/onflow/flow-nft/blob/master/contracts/MetadataViews.cdc#L136-L208). - -This view is meant to be used by 3rd party marketplaces to take a cut of the proceeds of an NFT sale -and send it to the author of a certain NFT. Each NFT can have its own royalty view: - -```cadence -pub struct Royalties { - - /// Array that tracks the individual royalties - access(self) let cutInfos: [Royalty] -} -``` - -and the royalty can indicate whatever fungible token it wants to accept via the type of the generic `{FungibleToken.Reciever}` capability that it specifies: - -```cadence -pub struct Royalty { - /// Generic FungibleToken Receiver for the beneficiary of the royalty - /// Can get the concrete type of the receiver with receiver.getType() - /// Recommendation - Users should create a new link for a FlowToken receiver for this using `getRoyaltyReceiverPublicPath()`, - /// and not use the default FlowToken receiver. - /// This will allow users to update the capability in the future to use a more generic capability - pub let receiver: Capability<&AnyResource{FungibleToken.Receiver}> - - /// Multiplier used to calculate the amount of sale value transferred to royalty receiver. - /// Note - It should be between 0.0 and 1.0 - /// Ex - If the sale value is x and multiplier is 0.56 then the royalty value would be 0.56 * x. - /// - /// Generally percentage get represented in terms of basis points - /// in solidity based smart contracts while cadence offers `UFix64` that already supports - /// the basis points use case because its operations - /// are entirely deterministic integer operations and support up to 8 points of precision. - pub let cut: UFix64 -} -``` - -If someone wants to make a listing for their NFT on a marketplace, -the marketplace can check to see if the royalty receiver accepts the seller's desired fungible token -by checking the concrete type of the reference. -If the concrete type is not the same as the type of token the seller wants to accept, -the marketplace has a few options. -They could either get the address of the receiver by using the -`receiver.owner.address` field and check to see if the account has a receiver for the desired token, -they could perform the sale without a royalty cut, or they could abort the sale -since the token type isn't accepted by the royalty beneficiary. - -You can see example implementations of royalties in the `ExampleNFT` contract -and the associated transactions and scripts. - -======= -| Name | Purpose | Status | Source | -| ----------- | ------------------------------------------ | ----------- | -------------------------------------------------------------------------------------------------------- | -| `Display` | Return the basic representation of an NFT. | Implemented | [MetadataViews.cdc](https://github.com/onflow/flow-nft/blob/master/contracts/MetadataViews.cdc#L35-L70) | -| `HTTPFile` | A file available at an HTTP(S) URL. | Implemented | [MetadataViews.cdc](https://github.com/onflow/flow-nft/blob/master/contracts/MetadataViews.cdc#L80-L92) | -| `IPFSFile` | A file stored in IPFS. | Implemented | [MetadataViews.cdc](https://github.com/onflow/flow-nft/blob/master/contracts/MetadataViews.cdc#L94-L133) | -| `Royalties` | An array of Royalty Cuts for a given NFT. | Implemented | [MetadataViews.cdc](https://github.com/onflow/flow-nft/blob/master/contracts/MetadataViews.cdc#L136-L208) | -| `Edition` | Return information about one or more editions for an NFT. | Implemented | [MetadataViews.cdc](https://github.com/onflow/flow-nft/blob/master/contracts/MetadataViews.cdc#L246-L266) | -| `NFTCollectionData` | Provides storage and retrieval information of an NFT | Implemented | [MetadataViews.cdc](https://github.com/onflow/flow-nft/blob/master/contracts/MetadataViews.cdc#L243-L299) | -| `NFTCollectionDisplay` | Returns the basic representation of an NFT's Collection. | Implemented | [MetadataViews.cdc](https://github.com/onflow/flow-nft/blob/master/contracts/MetadataViews.cdc#L301-L328) | - -#### Important Royalty Instructions for Royalty Receivers - -If you plan to set your account as a receiver of royalties, you'll likely want to be able to accept -as many token types as possible. This won't be immediately possible at first, but eventually, -we will also design a contract that can act as a sort of switchboard for fungible tokens. -It will accept any generic fungible token and route it to the correct vault in your account. -This hasn't been built yet, but you can still set up your account to be ready for it in the future. -Therefore, if you want to receive royalties, you should set up your account with the -[`setup_account_to_receive_royalty.cdc` transaction](https://github.com/onflow/flow-nft/blob/c13545c37be4d1e63605c5d76340fb188923d997/transactions/setup_account_to_receive_royalty.cdc). - -This will link generic public path from `MetadataViews.getRoyaltyReceiverPublicPath()` -to your chosen fungible token for now. Then, use that public path for your royalty receiver -and in the future, you will be able to easily update the link at that path to use the -fungible token switchboard instead. - -## How to propose a new view - -Please open a pull request to propose a new metadata view or changes to an existing view. - -## Feedback - -As Flow and Cadence are still new, -we expect this standard to evolve based on feedback -from both developers and users. - -We'd love to hear from anyone who has feedback. For example: - -- Are there any features that are missing from the standard? -- Are the current features defined in the best way possible? -- Are there any pre and post conditions that are missing? -- Are the pre and post conditions defined well enough? Error messages? -- Are there any other actions that need an event defined for them? -- Are the current event definitions clear enough and do they provide enough information? -- Are the variable, function, and parameter names descriptive enough? -- Are there any openings for bugs or vulnerabilities that we are not noticing? - -Please create an issue in this repository if there is a feature that -you believe needs discussing or changing. - -## Comparison to other standards on Ethereum - -This standard covers much of the same ground as ERC-721 and ERC-1155, -but without most of the downsides. - -- Tokens cannot be sent to contracts that don't understand how to use them, because an account needs to have a `Receiver` or `Collection` in its storage to receive tokens. -- If the recipient is a contract that has a stored `Collection`, the tokens can just be deposited to that Collection without having to do a clunky `approve`, `transferFrom`. -- Events are defined in the contract for withdrawing and depositing, so a recipient will always be notified that someone has sent them tokens with their own deposit event. -- This version can support batch transfers of NFTs. Even though it isn't explicitly defined in the contract, a batch transfer can be done within a transaction by just withdrawing all the tokens to transfer, then depositing them wherever they need to be, all atomically. -- Transfers can trigger actions because users can define custom `Receivers` to execute certain code when a token is sent. -- Easy ownership indexing: rathing than iterating through all tokens to find which ones you own, you have them all stored in your account's collection and can get the list of the ones you own instantly. - -## How to test the standard - -If you want to test out these contracts, we recommend either testing them -with the [Flow Playground](https://play.onflow.org) -or with the [Visual Studio Code Extension](https://developers.flow.com/tools/vscode-extension). - -The steps to follow are: - -1. Deploy `NonFungibleToken.cdc` -2. Deploy `ExampleNFT.cdc`, importing `NonFungibleToken` from the address you deployed it to. - -Then you can experiment with some of the other transactions and scripts in `transactions/` -or even write your own. You'll need to replace some of the import address placeholders with addresses that you deploy to, as well as some of the transaction arguments. - -## Running automated tests - -You can find automated tests in the `lib/go/test/nft_test.go` file. It uses the transaction templates that are contained in the `lib/go/templates/templates.go` file. - -Tests have also been written in JavaScript and can be found in `lib/js/test/tests/nft_test.js`. Similar to the tests written in Go, test helper functions can be found in `lib/js/test/templates/` directory. - -Entering the `make test` command from the root directory will run both Go and JavaScript test suites. If you'd like to run just one test suite, you can run `make test` from the test suite's `test/` directory (e.g. running `make test` from `lib/js/test` will run just your JavaScript tests). - -## Bonus features - -### NFT Forwarding - -While this utility contract is not a standard, it is a demonstration of how an account could be configured to forward NFTs to a specified forwarding recipient's collection. - -The NFTForwarder resource itself can be referenced like any `NonFungibleToken.Receiver` resource, allowing a sender to deposit NFT's as they usually would. However, `deposit()` as implemented in this resource forwards the deposited NFT to the designated recipient's collection. - -Several transactions are included in this repo to demonstrate how to interact with the `NFTForwarder` resource. Those are: -* `create_forwarder.cdc` - Creates the NFTForwarder resource and links the capability to `ExampleNFT.CollectionPublicPath`, where an Example NFT Collection would expect to be found. -* `transfer_nft_to_receiver.cdc` - Transfers an NFT to the forwarder by way of `deposit()` found in NonFungibleToken.Receiver` interface. By construction of the NFTForwarder resource, the NFT deposited by the signer is further forwarded to the forwarding recipient designated in the NFTForwarder resource. -* `change_forwarder_recipient.cdc` - Changes the designated recipient collection to which NFT will be forwarded. -* `unlink_forwarder_link_collection.cdc` - Unlinks the forwarder resource from `ExampleNFT.CollectionPublicPath`, restoring the accounts CollectionPublic capability. - -**(These could each be defined as a separate interface and standard and are probably not part of the main standard) They are not implemented in this repository yet** - -10- Withdrawing tokens from someone else's Collection by using their `Provider` reference. - -- approved withdraw event -- Providing a resource that only approves an account to withdraw a specific amount per transaction or per day/month/etc. -- Returning the list of tokens that an account can withdraw for another account. -- Reading the balance of the account that you have permission to send tokens for -- Owner is able to increase and decrease the approval at will, or revoke it completely - - This is much harder than anticipated - -11 - Standard for Composability/Extensibility - -12 - Minting a specific amount of tokens using a specific minter resource that an owner can control - -- tokens minted event -- Setting a cap on the total number of tokens that can be minted at a time or overall -- Setting a time frame where this is allowed - -13 - Burning a specific amount of tokens using a specific burner resource that an owner controls - -- tokens burnt event -- Setting a cap on the number of tokens that can be burned at a time or overall -- Setting a time frame where this is allowed - -14 - Pausing Token transfers (maybe a way to prevent the contract from being imported? probably not a good idea) - -15 - Cloning the token to create a new token with the same distribution - -## License - -The works in these files: - -- [ExampleNFT.cdc](https://github.com/onflow/flow-nft/blob/master/contracts/ExampleNFT.cdc) -- [NonFungibleToken.cdc](https://github.com/onflow/flow-nft/blob/master/contracts/NonFungibleToken.cdc) - -are under the [Unlicense](https://github.com/onflow/flow-nft/blob/master/LICENSE). - -## Deploying updates - -### Testnet - -```sh -TESTNET_PRIVATE_KEY=xxxx flow project deploy --update --network testnet -``` diff --git a/docs/reference/core-contracts/index.md b/docs/references/core-contracts/index.md similarity index 79% rename from docs/reference/core-contracts/index.md rename to docs/references/core-contracts/index.md index d4b6e011c8..3d4a974e39 100644 --- a/docs/reference/core-contracts/index.md +++ b/docs/references/core-contracts/index.md @@ -1,8 +1,11 @@ --- title: Flow Core Contracts description: The smart contracts that power the Flow protocol -sidebar_position: 1 -sidebar_label: Core Smart Contracts +sidebar_label: Core Protocol Smart Contracts +sidebar_position: 3 +sidebar_custom_props: + icon: 📝 + description: Explore the foundational contracts driving the Flow blockchain and learn how to utilize these vital building blocks for your own smart contract development. --- Flow relies on a set of core contracts that define key portions of the diff --git a/docs/reference/core-contracts/scenario_1.png b/docs/references/core-contracts/scenario_1.png similarity index 100% rename from docs/reference/core-contracts/scenario_1.png rename to docs/references/core-contracts/scenario_1.png diff --git a/docs/reference/core-contracts/token-allocation.png b/docs/references/core-contracts/token-allocation.png similarity index 100% rename from docs/reference/core-contracts/token-allocation.png rename to docs/references/core-contracts/token-allocation.png diff --git a/docs/reference/core-contracts/token-distribution.png b/docs/references/core-contracts/token-distribution.png similarity index 100% rename from docs/reference/core-contracts/token-distribution.png rename to docs/references/core-contracts/token-distribution.png diff --git a/docs/reference/flow-networks/accessing-mainnet.md b/docs/references/flow-networks/accessing-mainnet.md similarity index 90% rename from docs/reference/flow-networks/accessing-mainnet.md rename to docs/references/flow-networks/accessing-mainnet.md index 81e37b6f90..0477d872d1 100644 --- a/docs/reference/flow-networks/accessing-mainnet.md +++ b/docs/references/flow-networks/accessing-mainnet.md @@ -1,6 +1,6 @@ --- title: Flow Mainnet -sidebar_position: 2 +sidebar_position: 1 description: Guide to mainnet access --- @@ -26,7 +26,7 @@ func main() { ## Account creation -You can follow the [Flow Port account creation steps](../../reference/flow-port/index.md#blocto) to create a new mainnet account. +You can follow the [Flow Port account creation steps](../../references/run-and-secure/nodes/flow-port/index.md#blocto) to create a new mainnet account. If you prefer watching a video, check out this tutorial: @@ -72,4 +72,4 @@ Make sure to take a note of the address. If you want to verify the public key fo ## Important Mainnet Smart Contract Addresses -You can review [all available core contracts](../../reference/core-contracts/index.md) deployed to the mainnet to identify which ones you want to import. \ No newline at end of file +You can review [all available core contracts](../../references/core-contracts/index.md) deployed to the mainnet to identify which ones you want to import. \ No newline at end of file diff --git a/docs/reference/flow-networks/accessing-testnet.md b/docs/references/flow-networks/accessing-testnet.md similarity index 92% rename from docs/reference/flow-networks/accessing-testnet.md rename to docs/references/flow-networks/accessing-testnet.md index b6be0fb90e..b08375711e 100644 --- a/docs/reference/flow-networks/accessing-testnet.md +++ b/docs/references/flow-networks/accessing-testnet.md @@ -1,6 +1,6 @@ --- title: Flow Testnet -sidebar_position: 3 +sidebar_position: 2 description: Guide to Testnet access --- @@ -55,4 +55,4 @@ Accounts and tokens for testing can be obtained through the [testnet faucet](htt ## Important smart contract addresses -You can review [all available core contracts](../../reference/core-contracts/index.md) deployed to the Testnet to identify which ones you want to import. +You can review [all available core contracts](../../references/core-contracts/index.md) deployed to the Testnet to identify which ones you want to import. diff --git a/docs/references/flow-networks/index.md b/docs/references/flow-networks/index.md new file mode 100644 index 0000000000..7bbc2a6860 --- /dev/null +++ b/docs/references/flow-networks/index.md @@ -0,0 +1,18 @@ +--- +title: Flow Networks +sidebar_position: 2 +sidebar_custom_props: + description: Develop on Flow Testnet and deploy to Mainnet when production ready. + icon: 🌐 +--- + +# Flow Networks + +Other than the Flow mainnet network, Flow testnet can be used to test applications and contracts before deployment to mainnet. + +During a round of network upgrade, Flow testnet is updated first. Hence, testnet can be used to test against the latest node software, Cadence and core contract changes which will eventually be available to mainnet. + +## How to access these networks? + +[Flow Testnet](./accessing-testnet.md) +[Flow Mainnet](./accessing-mainnet.md) diff --git a/docs/reference/flow-networks/port-sealed-tx.png b/docs/references/flow-networks/port-sealed-tx.png similarity index 100% rename from docs/reference/flow-networks/port-sealed-tx.png rename to docs/references/flow-networks/port-sealed-tx.png diff --git a/docs/reference/governance.md b/docs/references/governance.md similarity index 100% rename from docs/reference/governance.md rename to docs/references/governance.md diff --git a/docs/references/index.md b/docs/references/index.md new file mode 100644 index 0000000000..7cfd9fc123 --- /dev/null +++ b/docs/references/index.md @@ -0,0 +1,25 @@ +--- +title: References +sidebar_position: 1 +--- + +# References +Quick references to very helpful parts of developer documentation. Languages to code up your applications and Network access points to pull blockchain data form Flow. +## Languages + +- [HTTP API](/http-api) - Access node API +- [FCL JS](../tools/clients/fcl-js/api.md) - Flow Client Library (javascript and typescript) +- Flow SDKs + - [FCL SDK](../tools/clients/fcl-js/sdk-guidelines.mdx) - Flow Client Library SDK + - [Flow Go SDK](../tools/clients/flow-go-sdk/index.mdx) - Golang Flow Client SDK + - [Flow Unity SDK](https://unity-flow-sdk-api-docs.vercel.app/) - For gaming use the Unity SDK +- [Cadence](https://cadence-lang.org/docs/language/functions) - Flow blockchain Smart Contract language, Cadence + +## Network +Get Flow blockchain data from Access Nodes, both REST and gRPC endpoints are available. Get the current status of mainnet and testnet networks. + +- [Flow Access API](../architecture/node-ops/nodes/access-api.md) + - [Mainnet](./flow-networks/accessing-mainnet.md): `access.mainnet.nodes.onflow.org:9000` + - [Testnet](./flow-networks/accessing-testnet.md): `access.devnet.nodes.onflow.org:9000` +- [Status Page](https://status.onflow.org/) - Network status page + diff --git a/docs/references/run-and-secure/_category_.yml b/docs/references/run-and-secure/_category_.yml new file mode 100644 index 0000000000..7b339a5cf3 --- /dev/null +++ b/docs/references/run-and-secure/_category_.yml @@ -0,0 +1,5 @@ +label: Running and Securing Flow +position: 4 +customProps: + icon: 🔐 + description: Learn about the four Flow node types, and how you can help secure and maintain the Flow blockchain. \ No newline at end of file diff --git a/docs/reference/faq/_category_.json b/docs/references/run-and-secure/nodes/faq/_category_.json similarity index 100% rename from docs/reference/faq/_category_.json rename to docs/references/run-and-secure/nodes/faq/_category_.json diff --git a/docs/reference/faq/backers.md b/docs/references/run-and-secure/nodes/faq/backers.md similarity index 89% rename from docs/reference/faq/backers.md rename to docs/references/run-and-secure/nodes/faq/backers.md index 19e5f6fef2..a4b473880c 100644 --- a/docs/reference/faq/backers.md +++ b/docs/references/run-and-secure/nodes/faq/backers.md @@ -25,8 +25,8 @@ Accounts are created with associated keys. There can be multiple keys on an acco FLOW supports a variety of signature schemes for adding keys to an account. -Details: [concepts/accounts-and-keys](../../build/basics/accounts.md) +Details: [concepts/accounts-and-keys](../../../../build/basics/accounts.md) ## How do I create a Flow account if I do not have a service account? -Instructions to generate an address are here: [flow-go-sdk/creating-accounts](../../tools/clients/flow-go-sdk/index.mdx#create-accounts). You don't need a service account. +Instructions to generate an address are here: [flow-go-sdk/creating-accounts](../../../../tools/clients/flow-go-sdk/index.mdx#create-accounts). You don't need a service account. diff --git a/docs/reference/faq/developers.md b/docs/references/run-and-secure/nodes/faq/developers.md similarity index 93% rename from docs/reference/faq/developers.md rename to docs/references/run-and-secure/nodes/faq/developers.md index d541476277..a94f588b3e 100644 --- a/docs/reference/faq/developers.md +++ b/docs/references/run-and-secure/nodes/faq/developers.md @@ -37,7 +37,7 @@ You can query historical data and fetch contract code using the SDKs. Flow allows you to actively query the state of the blockchain using scripts written in the Cadence programming language. You can find out more about Cadence here: -[cadence](../../build/smart-contracts/cadence.md) +[cadence](../../../../build/smart-contracts/cadence.md) Running scripts and parsing their output is supported by the SDKs. @@ -52,7 +52,7 @@ You can download FCL (Flow Client Library) here: [https://github.com/onflow/fcl-js](https://github.com/onflow/fcl-js) To connect to an access node you will need to provide a URL to the SDK. -[testnet and mainnet](../../architecture/node-ops/nodes/access-api.md) +[testnet and mainnet](../../../../architecture/node-ops/nodes/access-api.md) Here are examples of querying an access node at the bottom of this page: @@ -109,7 +109,7 @@ You can find out more about events in Cadence here: As an example of the kinds of information events can contain, see the documentation of the events that the staking protocol emits: -[staking/events](../../architecture/staking/07-staking-scripts-events.md) +[staking/events](../../../../architecture/staking/07-staking-scripts-events.md) ### Consuming Events @@ -171,7 +171,7 @@ Starting on October 16, 2021 at 7:30am PT (2:30pm UTC), there will be a flat fee ## How can I deploy a contract? -To deploy a contract, please follow the steps outlined in the [Dapp Deployment guide](../../tools/flow-cli/accounts/account-add-contract.md). +To deploy a contract, please follow the steps outlined in the [Dapp Deployment guide](../../../../tools/flow-cli/accounts/account-add-contract.md). ## How can I create my first account for mainnet? @@ -179,15 +179,15 @@ New accounts can be created using Flow Port. You can [follow these guidelines to ## How can I deploy a contract to mainnet? -Please review the [Dapp Deployment guide](../../tools/flow-cli/accounts/account-add-contract.md) for all details. +Please review the [Dapp Deployment guide](../../../../tools/flow-cli/accounts/account-add-contract.md) for all details. ## Is there a testnet/devnet? -There is an access node for you to develop against on the testnet/devnet. You can learn more about it [here](../../reference/flow-networks) +There is an access node for you to develop against on the testnet/devnet. You can learn more about it [here](../../../../references/flow-networks) ## Is there a public node? -Yes, an access node is publicly accessible to submit transactions and read data from the blockchain. If you’d like to access the devnet access node to build against, you can do so [here](../../reference/flow-networks/accessing-testnet.md#accessing-flow-testnet) +Yes, an access node is publicly accessible to submit transactions and read data from the blockchain. If you’d like to access the devnet access node to build against, you can do so [here](../../../../references/flow-networks/accessing-testnet.md#accessing-flow-testnet) ## Is it possible to add multiple public keys to a given account/address so that it can be controlled by more than one private key? @@ -200,7 +200,7 @@ Accounts are created with associated keys. There can be multiple keys on an acco FLOW supports a variety of signature schemes for adding keys to an account. -Details: [concepts/accounts-and-keys](../../build/basics/accounts.md) +Details: [concepts/accounts-and-keys](../../../../build/basics/accounts.md) ## How can I see what Fungible-Tokens an account has? @@ -216,11 +216,11 @@ Flow doesn't yet provide functionality to inspect all of the resources on an acc ## How do I create a Flow account if I do not have a service account? -Instructions to generate an address are here: [flow-go-sdk#create-accounts](../../tools/clients/flow-go-sdk/index.mdx#create-accounts). You don't need a service account. +Instructions to generate an address are here: [flow-go-sdk#create-accounts](../../../../tools/clients/flow-go-sdk/index.mdx#create-accounts). You don't need a service account. ## Is there a tutorial about how to access flow testnet? From scratch, getting testnet, Flow token etc..? -Yes: [testnet-deployment](../../build/smart-contracts/deploying.md) +Yes: [testnet-deployment](../../../../build/smart-contracts/deploying.md) ## Can you query events between a block range? diff --git a/docs/reference/faq/operators.md b/docs/references/run-and-secure/nodes/faq/operators.md similarity index 94% rename from docs/reference/faq/operators.md rename to docs/references/run-and-secure/nodes/faq/operators.md index a73d088703..0ee7d1afe6 100644 --- a/docs/reference/faq/operators.md +++ b/docs/references/run-and-secure/nodes/faq/operators.md @@ -41,7 +41,7 @@ You can query historical data and fetch contract code using the SDKs. Flow allows you to actively query the state of the blockchain using scripts written in the Cadence programming language. You can find out more about Cadence here: -[cadence](../../build/smart-contracts/cadence.md) +[cadence](../../../../build/smart-contracts/cadence.md) Running scripts and parsing their output is supported by the SDKs. @@ -56,7 +56,7 @@ You can download the FCL (Flow Client Library) here: [https://github.com/onflow/fcl-js](https://github.com/onflow/fcl-js) To connect to an access node you will need to provide a URL to the SDK. -[access node urls](../../architecture/node-ops/nodes/access-api.md) +[access node urls](../../../../architecture/node-ops/nodes/access-api.md) Here are examples of querying an access node at the bottom of this page: @@ -113,7 +113,7 @@ You can find out more about events in Cadence here: As an example of the kinds of information events can contain, see the documentation of the events that the staking protocol emits: -[staking/events](../../architecture/staking/07-staking-scripts-events.md) +[staking/events](../../../../architecture/staking/07-staking-scripts-events.md) ### Consuming Events @@ -160,11 +160,11 @@ No errors should be considered acceptable. If there are errors that are constant ## Is there a testnet/devnet? -There is an access node for you to develop against on the testnet/devnet. You can learn more about it here [testnet-deployment#accessing-flow-testnet](../../build/smart-contracts/deploying.md#accessing-flow-testnet) +There is an access node for you to develop against on the testnet/devnet. You can learn more about it here [testnet-deployment#accessing-flow-testnet](../../../../build/smart-contracts/deploying.md#accessing-flow-testnet) ## Is there a public node? -Yes, an access node is publicly accessible to submit transactions and read data from the blockchain. If you’d like to access the devnet access node to build against, you can do so [here](../flow-networks/accessing-testnet.md) +Yes, an access node is publicly accessible to submit transactions and read data from the blockchain. If you’d like to access the devnet access node to build against, you can do so [here](../../../flow-networks/accessing-testnet.md) ## Is it possible to add multiple public keys to a given account/address so that it can be controlled by more than one private key? @@ -177,11 +177,11 @@ Accounts are created with associated keys. There can be multiple keys on an acco FLOW supports a variety of signature schemes for adding keys to an account. -Details: [concepts/accounts-and-keys](../../build/basics/accounts.md) +Details: [concepts/accounts-and-keys](../../../../build/basics/accounts.md) ## How do I create a Flow account if I do not have a service account? -Instructions to generate an address are here: [flow-go-sdk#create-accounts](../../tools/clients/flow-go-sdk/index.mdx#create-accounts). You don't need a service account. +Instructions to generate an address are here: [flow-go-sdk#create-accounts](../../../../tools/clients/flow-go-sdk/index.mdx#create-accounts). You don't need a service account. ## Can you query events between a block range? @@ -192,4 +192,4 @@ You can query the access API to get events for a block range. See Access API spe You can follow Flow node software releases here: [https://github.com/onflow/flow-go/releases](https://github.com/onflow/flow-go/releases). ## How do I run a Flow node and become a node operator? -See the dedicated section on node operation: [nodes/node-operation/](../../architecture/node-ops/index.md) +See the dedicated section on node operation: [nodes/node-operation/](../../../../architecture/node-ops/index.md) diff --git a/docs/reference/flow-port/index.md b/docs/references/run-and-secure/nodes/flow-port/index.md similarity index 92% rename from docs/reference/flow-port/index.md rename to docs/references/run-and-secure/nodes/flow-port/index.md index 534c672451..44c2ec3ce7 100644 --- a/docs/reference/flow-port/index.md +++ b/docs/references/run-and-secure/nodes/flow-port/index.md @@ -75,14 +75,14 @@ So you have decided you want to be a part of the Flow Network. Welcome! You are If you are using a custody provider who controls your account and private keys for you, such as Kraken, Finoa, or Coinlist, they all have different policies and processes for what you need to do to stake your tokens, the rewards you receive, and the fees that they take from your staking rewards. ### Starting a Manual Staking Transaction - 1. You need to have FLOW in order to stake. Please see the [FLOW Token](../core-contracts/03-flow-token.md) reference for information on how to become a FLOW holder. + 1. You need to have FLOW in order to stake. Please see the [FLOW Token](../../../core-contracts/03-flow-token.md) reference for information on how to become a FLOW holder. 2. Once you have FLOW tokens in your account, you can start staking through [Flow Port](https://port.onflow.org/) or, if applicable, with your [custody provider](#staking-via-a-custody-provider). 3. If you are using Flow Port, log-in with your Flow account address and navigate to the Stake/Delegate page. See the Manual Staking/Delegating section below for more information about what to do next. ### Manual Staking/Delegating -If you are not using a custody provider, there is more responsibility that you have to accept, because you have complete control of your tokens. You need to ensure that you are well informed about the staking process and potentially node operation process because you will have to manage those on your own. Please read the [staking documentation](../../architecture/staking/index.md) before continuing with this guide. +If you are not using a custody provider, there is more responsibility that you have to accept, because you have complete control of your tokens. You need to ensure that you are well informed about the staking process and potentially node operation process because you will have to manage those on your own. Please read the [staking documentation](../../../../architecture/staking/index.md) before continuing with this guide. Below are the various options you can choose. Please be aware, that at this time you can only have 1 stake or 1 delegate per account. This means that if you want to do multiple stakes, multiple delegates, or a mixture of stakes and delegates, you will need to create multiple accounts to do so. Please read them carefully as it will help you understand which route is best for your situation: - Staking your own Node: You are responsible for running and maintaining a Flow Node. You are also solely responsible for providing the minimum stake for your selected node (minimum 135,000 FLOW) and you have the technical know-how and bandwidth to run and operate a node in the Flow protocol. @@ -97,7 +97,7 @@ Please see a list [here](https://github.com/onflow/flow/blob/master/nodeoperator 3. Input the amount of Flow you wish to stake with that node. You must stake at least the minimum in order for your stake request to be successfully processed. You are able to provide the minimum stake across multiple transactions. Meaning, you could execute your stake transaction with half of the minumum required. Then, before the next epoch, you can choose to 'Add Flow' to that pending stake to get it to the minimum stake required. - 4. Run the [bootstrapping instructions](../../architecture/node-ops/nodes/node-operation/node-bootstrap.md) and provide the remaining technical details needed to stake a node. + 4. Run the [bootstrapping instructions](../../../../architecture/node-ops/nodes/node-operation/node-bootstrap.md) and provide the remaining technical details needed to stake a node. ### Delegating 1. Once you have navigated to the staking/delegating page in Flow Port, click on the Delegate option. @@ -109,13 +109,13 @@ Please see a list [here](https://github.com/onflow/flow/blob/master/nodeoperator 4. At this point, you can also cancel the pending delegation. On the pending delegation, you will see an `X` that you can click to initiate the cancelation transaction. ## I have successfully executed a Stake Transaction, now what? - - Now that you have executed a stake transaction in either Flow Port or your custody provider’s portal, that transaction will sit in a pending status until it is processed, which will be at the next [Epoch](../../architecture/staking/index.md#epochs) Date (which is currently weekly). - - During the next [Epoch](../../architecture/staking/index.md#epochs), the transaction will be processed. If successful, the provided FLOW will be staked and the associated Node would be either **a)** included in the network protocol if it is a new node or **b)** continue to operate as is in the network protocol. + - Now that you have executed a stake transaction in either Flow Port or your custody provider’s portal, that transaction will sit in a pending status until it is processed, which will be at the next [Epoch](../../../../architecture/staking/index.md#epochs) Date (which is currently weekly). + - During the next [Epoch](../../../../architecture/staking/index.md#epochs), the transaction will be processed. If successful, the provided FLOW will be staked and the associated Node would be either **a)** included in the network protocol if it is a new node or **b)** continue to operate as is in the network protocol. - You are now a part of Flow, and will begin to earn rewards for being a valued member of the network! ## What else can I do? - Add additional stake to your existing stake. Any added FLOW will again sit in a pending status and be processed at the next epoch. - - Withdraw/re-stake your earned rewards. If you decide to withdraw your rewards, this action will happen instantly. If you decide to re-stake your rewards, the request will again sit in a pending status and will be processed at the next [Epoch](../../architecture/staking/index.md#epochs). + - Withdraw/re-stake your earned rewards. If you decide to withdraw your rewards, this action will happen instantly. If you decide to re-stake your rewards, the request will again sit in a pending status and will be processed at the next [Epoch](../../../../architecture/staking/index.md#epochs). - Withdraw Rewards and send your earnings to other accounts. If you decide that you want to withdraw your rewards and send those earnings to other accounts via the 'Send FLOW' function, you should first withdraw your rewards. Once in your account, you can send these funds to any other account via the 'Send FLOW' option. - Request to be unstaked from the network. The unstake request will sit in a pending status for two epochs. Once it is processed, the amount that has been unstaked will sit in your unstaked FLOW amount and can now be withdrawn or re-staked. - Change the node you are staked/delegated to. If your staked/delegated node has no FLOW actively staked and you have completely withdrawn all unstaked amounts and rewards associated with the node, then you can move your stake to a different node. Click on the `Change Node` button to initiate this process. Please note that this feature is only visible once you get your active stake/delegate into the appropriate status. diff --git a/docs/reference/flow-port/machine-account.png b/docs/references/run-and-secure/nodes/flow-port/machine-account.png similarity index 100% rename from docs/reference/flow-port/machine-account.png rename to docs/references/run-and-secure/nodes/flow-port/machine-account.png diff --git a/docs/reference/flow-port/port-delegate-1.png b/docs/references/run-and-secure/nodes/flow-port/port-delegate-1.png similarity index 100% rename from docs/reference/flow-port/port-delegate-1.png rename to docs/references/run-and-secure/nodes/flow-port/port-delegate-1.png diff --git a/docs/reference/flow-port/port-delegate-2.png b/docs/references/run-and-secure/nodes/flow-port/port-delegate-2.png similarity index 100% rename from docs/reference/flow-port/port-delegate-2.png rename to docs/references/run-and-secure/nodes/flow-port/port-delegate-2.png diff --git a/docs/reference/flow-port/port-delegate-3.png b/docs/references/run-and-secure/nodes/flow-port/port-delegate-3.png similarity index 100% rename from docs/reference/flow-port/port-delegate-3.png rename to docs/references/run-and-secure/nodes/flow-port/port-delegate-3.png diff --git a/docs/reference/flow-port/port-delegate-4.png b/docs/references/run-and-secure/nodes/flow-port/port-delegate-4.png similarity index 100% rename from docs/reference/flow-port/port-delegate-4.png rename to docs/references/run-and-secure/nodes/flow-port/port-delegate-4.png diff --git a/docs/reference/flow-port/port-stake-0-00.png b/docs/references/run-and-secure/nodes/flow-port/port-stake-0-00.png similarity index 100% rename from docs/reference/flow-port/port-stake-0-00.png rename to docs/references/run-and-secure/nodes/flow-port/port-stake-0-00.png diff --git a/docs/reference/flow-port/port-stake-0-01.png b/docs/references/run-and-secure/nodes/flow-port/port-stake-0-01.png similarity index 100% rename from docs/reference/flow-port/port-stake-0-01.png rename to docs/references/run-and-secure/nodes/flow-port/port-stake-0-01.png diff --git a/docs/reference/flow-port/port-stake-0-02.png b/docs/references/run-and-secure/nodes/flow-port/port-stake-0-02.png similarity index 100% rename from docs/reference/flow-port/port-stake-0-02.png rename to docs/references/run-and-secure/nodes/flow-port/port-stake-0-02.png diff --git a/docs/reference/flow-port/port-stake-0-03.png b/docs/references/run-and-secure/nodes/flow-port/port-stake-0-03.png similarity index 100% rename from docs/reference/flow-port/port-stake-0-03.png rename to docs/references/run-and-secure/nodes/flow-port/port-stake-0-03.png diff --git a/docs/reference/flow-port/port-stake-0-04.png b/docs/references/run-and-secure/nodes/flow-port/port-stake-0-04.png similarity index 100% rename from docs/reference/flow-port/port-stake-0-04.png rename to docs/references/run-and-secure/nodes/flow-port/port-stake-0-04.png diff --git a/docs/reference/flow-port/port-stake-0-05.png b/docs/references/run-and-secure/nodes/flow-port/port-stake-0-05.png similarity index 100% rename from docs/reference/flow-port/port-stake-0-05.png rename to docs/references/run-and-secure/nodes/flow-port/port-stake-0-05.png diff --git a/docs/reference/flow-port/port-stake-0-06.png b/docs/references/run-and-secure/nodes/flow-port/port-stake-0-06.png similarity index 100% rename from docs/reference/flow-port/port-stake-0-06.png rename to docs/references/run-and-secure/nodes/flow-port/port-stake-0-06.png diff --git a/docs/reference/flow-port/port-stake-1.png b/docs/references/run-and-secure/nodes/flow-port/port-stake-1.png similarity index 100% rename from docs/reference/flow-port/port-stake-1.png rename to docs/references/run-and-secure/nodes/flow-port/port-stake-1.png diff --git a/docs/reference/flow-port/port-stake-2.png b/docs/references/run-and-secure/nodes/flow-port/port-stake-2.png similarity index 100% rename from docs/reference/flow-port/port-stake-2.png rename to docs/references/run-and-secure/nodes/flow-port/port-stake-2.png diff --git a/docs/reference/flow-port/port-stake-3.png b/docs/references/run-and-secure/nodes/flow-port/port-stake-3.png similarity index 100% rename from docs/reference/flow-port/port-stake-3.png rename to docs/references/run-and-secure/nodes/flow-port/port-stake-3.png diff --git a/docs/reference/flow-port/port-stake-4.png b/docs/references/run-and-secure/nodes/flow-port/port-stake-4.png similarity index 100% rename from docs/reference/flow-port/port-stake-4.png rename to docs/references/run-and-secure/nodes/flow-port/port-stake-4.png diff --git a/docs/reference/flow-port/port-stake-5.png b/docs/references/run-and-secure/nodes/flow-port/port-stake-5.png similarity index 100% rename from docs/reference/flow-port/port-stake-5.png rename to docs/references/run-and-secure/nodes/flow-port/port-stake-5.png diff --git a/docs/reference/flow-port/port-stake-6.png b/docs/references/run-and-secure/nodes/flow-port/port-stake-6.png similarity index 100% rename from docs/reference/flow-port/port-stake-6.png rename to docs/references/run-and-secure/nodes/flow-port/port-stake-6.png diff --git a/docs/reference/flow-port/staking-collection.png b/docs/references/run-and-secure/nodes/flow-port/staking-collection.png similarity index 100% rename from docs/reference/flow-port/staking-collection.png rename to docs/references/run-and-secure/nodes/flow-port/staking-collection.png diff --git a/docs/reference/flow-port/staking-guide.md b/docs/references/run-and-secure/nodes/flow-port/staking-guide.md similarity index 88% rename from docs/reference/flow-port/staking-guide.md rename to docs/references/run-and-secure/nodes/flow-port/staking-guide.md index d09274fd1d..823d3aeb05 100644 --- a/docs/reference/flow-port/staking-guide.md +++ b/docs/references/run-and-secure/nodes/flow-port/staking-guide.md @@ -1,10 +1,10 @@ --- -title: Staking Guide +title: Flow Port Staking Guide --- This guide provides step-by-step instructions for using the Flow Port to stake your FLOW tokens and start earning rewards. Currently, Flow Port only supports staking or delegating using tokens held in Blocto or Ledger wallets. -If you're new to the concepts of staking and delegating you can [read this guide](../../architecture/staking/index.md) to learn more. +If you're new to the concepts of staking and delegating you can [read this guide](../../../../architecture/staking/index.md) to learn more. ## First Step @@ -32,7 +32,7 @@ You'll also need the following information about your node: - Staking Key - Machine Account Public Key (for collection/consensus nodes only) -If you don't have this information, go [here](../../architecture/node-ops/nodes/node-operation/node-bootstrap.md#step-1---run-genesis-bootstrap) for instructions on how to acquire it. +If you don't have this information, go [here](../../../../architecture/node-ops/nodes/node-operation/node-bootstrap.md#step-1---run-genesis-bootstrap) for instructions on how to acquire it. ### Begin Staking @@ -46,7 +46,7 @@ but you may stake as much as you like beyond that. Here's the screen you should ![Flow Port Staking](port-stake-0-03.png) Clicking next will take you to the final screen, where you'll need to enter information about your node you previously obtained. -If you don't have this information, go [here](../../architecture/node-ops/nodes/node-operation/node-bootstrap.md#step-1---run-genesis-bootstrap) for instructions on how to acquire it. +If you don't have this information, go [here](../../../../architecture/node-ops/nodes/node-operation/node-bootstrap.md#step-1---run-genesis-bootstrap) for instructions on how to acquire it. Here's the screen you should see: ![Flow Port Staking](port-stake-0-04.png) @@ -68,11 +68,11 @@ If you are already a node operator with a staked node, you will first need to up ![Flow Port Staking](staking-collection.png) -Once this is done, you can now create a [Machine Account](../../architecture/node-ops/nodes/node-operation/machine-existing-operator.md) by clicking the "Upgrade Node" button on the Stake & Delegate page. +Once this is done, you can now create a [Machine Account](../../../../architecture/node-ops/nodes/node-operation/machine-existing-operator.md) by clicking the "Upgrade Node" button on the Stake & Delegate page. ![Flow Port Staking](machine-account.png) -You can follow the guide [here](../../architecture/node-ops/nodes/node-operation/machine-existing-operator.md) to create your Machine Account. +You can follow the guide [here](../../../../architecture/node-ops/nodes/node-operation/machine-existing-operator.md) to create your Machine Account. ## Delegating diff --git a/docs/tools/clients/flow-go-sdk/index.mdx b/docs/tools/clients/flow-go-sdk/index.mdx index 19bd35f407..47618542a9 100644 --- a/docs/tools/clients/flow-go-sdk/index.mdx +++ b/docs/tools/clients/flow-go-sdk/index.mdx @@ -303,7 +303,7 @@ Retrieve events by a given type in a specified block height range or through a l A.{contract address}.{contract name}.{event name} ``` -Please read more about [events in the documentation](../../../reference/core-contracts/03-flow-token.md). The exception to this standard are +Please read more about [events in the documentation](../../../references/core-contracts/03-flow-token.md). The exception to this standard are core events, and you should read more about them in [this document](https://cadence-lang.org/docs/language/core-events). 📖 **Block height range** expresses the height of the start and end block in the chain. diff --git a/docs/tools/flow-cli/flow.json/configuration.md b/docs/tools/flow-cli/flow.json/configuration.md index 578f3e5bd5..9f1dd65593 100644 --- a/docs/tools/flow-cli/flow.json/configuration.md +++ b/docs/tools/flow-cli/flow.json/configuration.md @@ -120,7 +120,7 @@ The advanced format allows us to specify aliases for each network. Using advanced format we can define `aliases`. Aliases define an address where the contract is already deployed for that specific network. In the example scenario below the contract `FungibleToken` would be imported from the address `9a0766d93b6608b7` when deploying to testnet network and address `ee82856bf20e2aa6` when deploying to the Flow emulator. -We can specify aliases for each network we have defined. When deploying to testnet it is always a good idea to specify aliases for all the [common contracts](../../../reference/core-contracts/index.md) that have already been deployed to the testnet. +We can specify aliases for each network we have defined. When deploying to testnet it is always a good idea to specify aliases for all the [common contracts](../../../references/core-contracts/index.md) that have already been deployed to the testnet. ⚠️ If we use an alias for the contract we should not specify it in the `deployment` section for that network. diff --git a/docs/tutorials/smart-contracts.md b/docs/tutorials/smart-contracts.md index ab485b079e..08a59affb5 100644 --- a/docs/tutorials/smart-contracts.md +++ b/docs/tutorials/smart-contracts.md @@ -57,9 +57,9 @@ The Flow blockchain has existing smart contract standards for both fungible and ### Non-Fungible Tokens (NFTs) -All NFTs on the Flow blockchain implement the [NonFungibleToken](../reference/core-contracts/08-non-fungible-token.md) interface, allowing them to be compatible with wallets, marketplaces and other cross-app experiences. +All NFTs on the Flow blockchain implement the [NonFungibleToken](../references/core-contracts/08-non-fungible-token.md) interface, allowing them to be compatible with wallets, marketplaces and other cross-app experiences. -- [Non-Fungible Token (NFT) contract interface](../reference/core-contracts/08-non-fungible-token.md) +- [Non-Fungible Token (NFT) contract interface](../references/core-contracts/08-non-fungible-token.md) ### NFT Sales and Trading @@ -69,6 +69,6 @@ Flow has a standard contract to facilitate both the direct sales and peer-to-pee ### Fungible Tokens -Fungible tokens (i.e. coins, currencies) on the Flow blockchain, including the default cryptocurrency token FLOW, implement the [FungibleToken](../reference/core-contracts/02-fungible-token.md) interface. +Fungible tokens (i.e. coins, currencies) on the Flow blockchain, including the default cryptocurrency token FLOW, implement the [FungibleToken](../references/core-contracts/02-fungible-token.md) interface. -- [Fungible Token contract interface](../reference/core-contracts/02-fungible-token.md) +- [Fungible Token contract interface](../references/core-contracts/02-fungible-token.md) diff --git a/docusaurus.config.js b/docusaurus.config.js index c18bf1d99b..cc56e73c0b 100644 --- a/docusaurus.config.js +++ b/docusaurus.config.js @@ -279,10 +279,10 @@ const config = { activeBasePath: '/architecture', }, { - to: 'reference/flow-networks', + to: 'references', position: 'left', - label: 'Reference', - activeBasePath: '/reference', + label: 'References', + activeBasePath: '/references', }, { to: 'community-resources', @@ -401,7 +401,7 @@ const config = { label: 'Cadence Cookbook', }, { - to: '/reference/core-contracts/', + to: '/references/core-contracts/', label: 'Core Contracts & Standards', }, { diff --git a/sidebars.js b/sidebars.js index ff20ebeb06..8f3e2af482 100644 --- a/sidebars.js +++ b/sidebars.js @@ -61,58 +61,7 @@ const sidebars = { nodeOps: [{ type: 'autogenerated', dirName: 'node-ops' }], tutorials: [{ type: 'autogenerated', dirName: 'tutorials' }], tools: [{ type: 'autogenerated', dirName: 'tools' }], - reference: [ - 'reference/index', - { - type: 'category', - label: 'Flow Networks', - link: { type: 'doc', id: 'reference/flow-networks/index' }, - items: [ - { - type: 'autogenerated', - dirName: 'reference/flow-networks', - }, - ], - }, - { - type: 'link', - label: 'HTTP API', - href: 'https://developers.flow.com/http-api', - }, - { - type: 'category', - label: 'Core Smart Contracts', - link: { type: 'doc', id: 'reference/core-contracts/index' }, - items: [ - { - type: 'autogenerated', - dirName: 'reference/core-contracts', - }, - ], - }, - { - type: 'category', - label: 'Flow Port', - link: { type: 'doc', id: 'reference/flow-port/index' }, - items: [ - { - type: 'autogenerated', - dirName: 'reference/flow-port', - }, - ], - }, - 'reference/governance', - { - type: 'category', - label: 'FAQ', - items: [ - { - type: 'autogenerated', - dirName: 'reference/faq', - }, - ], - }, - ], + references: [{ type: 'autogenerated', dirName: 'references' }], communityResources: [ { type: 'autogenerated', dirName: 'community-resources' }, ], diff --git a/src/data/data-sources.json b/src/data/data-sources.json index 40da603228..ff961d1db6 100644 --- a/src/data/data-sources.json +++ b/src/data/data-sources.json @@ -7,7 +7,7 @@ "data": [ { "source": "docs/", - "destination": "reference/core-contracts/flow-ft/", + "destination": "references/core-contracts/flow-ft/", "doCopy": true } ] @@ -21,7 +21,7 @@ "data": [ { "source": "docs/", - "destination": "reference/core-contracts/flow-nft/", + "destination": "references/core-contracts/flow-nft/", "doCopy": true } ] diff --git a/vercel.json b/vercel.json index 6f18e41c39..0a9e37f8b9 100644 --- a/vercel.json +++ b/vercel.json @@ -19,12 +19,12 @@ }, { "source": "/concepts/core-contracts/nft-standard", - "destination": "/reference/core-contracts/flow-nft", + "destination": "/references/core-contracts/flow-nft", "permanent": true }, { "source": "/flow/core-contracts/:path*", - "destination": "/reference/core-contracts/:path*", + "destination": "/references/core-contracts/:path*", "permanent": true }, { @@ -104,17 +104,17 @@ }, { "source": "/learn/concepts/accessing-mainnet", - "destination": "/reference/flow-networks/accessing-mainnet", + "destination": "/references/flow-networks/accessing-mainnet", "permanent": true }, { "source": "/learn/concepts/accessing-sandboxnet", - "destination": "/reference/flow-networks/accessing-sandboxnet", + "destination": "/references/flow-networks/accessing-sandboxnet", "permanent": true }, { "source": "/learn/concepts/accessing-testnet", - "destination": "/reference/flow-networks/accessing-testnet", + "destination": "/references/flow-networks/accessing-testnet", "permanent": true }, { @@ -134,7 +134,7 @@ }, { "source": "/learn/concepts/networks", - "destination": "/reference/flow-networks", + "destination": "/references/flow-networks", "permanent": true }, { @@ -214,7 +214,7 @@ }, { "source": "/nodes/flow-port/staking-guide", - "destination": "/reference/flow-port/staking-guide", + "destination": "/references/run-and-secure/nodes/flow-port/staking-guide", "permanent": true }, { @@ -274,7 +274,7 @@ }, { "source": "/flow/faq", - "destination": "/reference/faq/backers", + "destination": "/references/run-and-secure/nodes/faq/backers", "permanent": true }, { @@ -289,7 +289,7 @@ }, { "source": "/flow-token/backers", - "destination": "/reference/faq/backers", + "destination": "/references/run-and-secure/nodes/faq/backers", "permanent": true }, { @@ -319,7 +319,7 @@ }, { "source": "/flow-port/:path*", - "destination": "/reference/flow-port/:path*", + "destination": "/references/run-and-secure/nodes/flow-port/:path*", "permanent": true }, { @@ -424,7 +424,7 @@ }, { "source": "/core-contracts/:path*", - "destination": "/reference/core-contracts/:path*", + "destination": "/references/core-contracts/:path*", "permanent": true }, { @@ -838,7 +838,7 @@ }, { "source": "/concepts/flow-networks", - "destination": "/reference/flow-networks", + "destination": "/references/flow-networks", "permanent": true }, { @@ -858,12 +858,12 @@ }, { "source": "/build/core-contracts/:path*", - "destination": "/reference/core-contracts/:path*", + "destination": "/references/core-contracts/:path*", "permanent": true }, { "source": "/build/flow-networks/:path*", - "destination": "/reference/flow-networks/:path*", + "destination": "/references/flow-networks/:path*", "permanent": true }, { @@ -871,6 +871,11 @@ "destination": "/architecture/node-ops/nodes/slashing", "permanent": true }, + { + "source": "/build/run-and-secure/:path*", + "destination": "/references/run-and-secure/:path*", + "permanent": true + }, { "source": "/node-ops/node-operation/:path*", "destination": "/architecture/node-ops/nodes/node-operation/:path*", @@ -881,6 +886,11 @@ "destination": "/architecture/node-ops/nodes/node-operation", "permanent": true }, + { + "source": "/references/run-and-secure/nodes/node-operation/:path*", + "destination": "/architecture/node-ops/nodes/node-operation/:path*", + "permanent": true + }, { "source": "/overview/getting-started/block-explorers", "destination": "/community-resources/block-explorers", @@ -913,7 +923,7 @@ }, { "source": "/overview/dive-in/governance", - "destination": "/reference/governance", + "destination": "/references/governance", "permanent": true }, { @@ -952,13 +962,13 @@ "permanent": true }, { - "source": "/reference/flow-port/:path*", - "destination": "/reference/flow-port/:path*", + "source": "/references/run-and-secure/flow-port/:path*", + "destination": "/references/run-and-secure/nodes/flow-port/:path*", "permanent": true }, { "source": "/flow/faq/:path*", - "destination": "/reference/faq/:path*", + "destination": "/references/run-and-secure/nodes/faq/:path*", "permanent": true }, { @@ -1000,6 +1010,16 @@ "source": "/next/:path*", "destination": "/:path*", "permanent": true + }, + { + "source": "/references/run-and-secure/nodes", + "destination": "/architecture/node-ops", + "permanent": true + }, + { + "source": "/references/run-and-secure/node-operation/:path*", + "destination": "/architecture/node-ops/nodes/node-operation/:path*", + "permanent": true } ] } \ No newline at end of file