diff --git a/docs/language/accounts/contracts.mdx b/docs/language/accounts/contracts.mdx index 61fcef6..95dcb9a 100644 --- a/docs/language/accounts/contracts.mdx +++ b/docs/language/accounts/contracts.mdx @@ -264,7 +264,8 @@ then the function aborts the program. When the update succeeded, the function returns the [deployed contract](#deployed-contract). - +:::warning + The `update` function does **not** run the initializer of the contract again. Updating a contract does **not** change the contract instance and its existing stored data. @@ -272,7 +273,8 @@ A contract update only changes the code a contract. Is only possible to update contracts in ways that keep data consistency. [Certain restrictions apply](../contract-updatability.md). - + +::: For example, assuming that a contract named `Test` is already deployed to the account, and it should be updated with the following contract code: diff --git a/docs/language/accounts/inbox.mdx b/docs/language/accounts/inbox.mdx index e9c4eb7..c0337db 100644 --- a/docs/language/accounts/inbox.mdx +++ b/docs/language/accounts/inbox.mdx @@ -94,9 +94,11 @@ the function returns `nil`. If the borrow type of the capability is not a subtype of the provided type argument, the program aborts. - +:::tip + It is only possible to claim a capability once. - + +::: Calling function `claim` function emits an event, `InboxValueClaimed`, that includes the address of both the provider and the recipient, diff --git a/docs/language/accounts/keys.mdx b/docs/language/accounts/keys.mdx index e85f875..94c7556 100644 --- a/docs/language/accounts/keys.mdx +++ b/docs/language/accounts/keys.mdx @@ -120,10 +120,12 @@ For each key of the account, the `forEach` function calls the given callback, pa When the callback function returns `true` the iteration continues, and when it returns `false`, iteration stops. - - The `keys.get` and `keys.forEach` functions include revoked keys, - which have the `isRevoked` field set to `true`. - +:::warning + +The `keys.get` and `keys.forEach` functions include revoked keys, +which have the `isRevoked` field set to `true`. + +::: ```cadence access(all) diff --git a/docs/language/accounts/storage.mdx b/docs/language/accounts/storage.mdx index 7ae7c2f..25a69ce 100644 --- a/docs/language/accounts/storage.mdx +++ b/docs/language/accounts/storage.mdx @@ -419,14 +419,17 @@ If the callback function returns `false`, the iteration function stops. The specific order in which the objects are iterated over is undefined, as is the behavior when a path is added or removed from storage. - - The iteration functions skip broken objects. +:::warning - An object could be broken due to invalid types associated with the stored value. - For example, the contract for the stored object might have syntactic or semantic errors. - +The iteration functions skip broken objects. + +An object could be broken due to invalid types associated with the stored value. +For example, the contract for the stored object might have syntactic or semantic errors. + +::: + +:::warning - The order of iteration is undefined. Do not rely on any particular behavior. Saving an object to a path or loading an object from storage during iteration @@ -458,7 +461,7 @@ account.storage.forEachStored(fun (path: StoragePath, type: Type): Bool { }) ``` - +::: ## Storage limit diff --git a/docs/language/built-in-functions.mdx b/docs/language/built-in-functions.mdx index 4d6d8ad..cf8d729 100644 --- a/docs/language/built-in-functions.mdx +++ b/docs/language/built-in-functions.mdx @@ -61,13 +61,13 @@ and [FLIP120](https://github.com/onflow/flips/pull/120) for more details. Nevertheless, developers need to be mindful to use `revertibleRandom()` correctly: - +:::warning A transaction can atomically revert all its action. It is possible for a transaction submitted by an untrusted party to post-select favorable results and revert the transaction for unfavorable results. - +::: The function usage remains safe when called by a trusted party that does not perform post-selection on the returned random numbers. diff --git a/docs/language/glossary.mdx b/docs/language/glossary.mdx index 3c3ef8a..9e85136 100644 --- a/docs/language/glossary.mdx +++ b/docs/language/glossary.mdx @@ -4,9 +4,11 @@ sidebar_position: 32 --- - +:::tip + Tip: CTRL/⌘ + F and type in the symbol or operator you want to look up. - + +::: ## `&` (ampersand) diff --git a/docs/language/interfaces.mdx b/docs/language/interfaces.mdx index 9306196..00fe5db 100644 --- a/docs/language/interfaces.mdx +++ b/docs/language/interfaces.mdx @@ -458,11 +458,11 @@ shape.area // is `54` ## Interface Nesting - +:::warning[🚧 Status] -🚧 Status: Currently only contracts and contract interfaces support nested interfaces. +Currently only contracts and contract interfaces support nested interfaces. - +::: Interfaces can be arbitrarily nested. Declaring an interface inside another does not require implementing types diff --git a/docs/language/references.mdx b/docs/language/references.mdx index 030b869..f75e9b0 100644 --- a/docs/language/references.mdx +++ b/docs/language/references.mdx @@ -414,9 +414,11 @@ let r2 <- r ref.id = 2 ``` - +:::tip + Invalidations of storage references are not statically caught, but only at run-time. - + +::: ## Dereferencing values diff --git a/docs/language/resources.mdx b/docs/language/resources.mdx index 1023a40..92a15ad 100644 --- a/docs/language/resources.mdx +++ b/docs/language/resources.mdx @@ -604,11 +604,13 @@ id2 != id3 // true id3 != id1 // true ``` - +:::warning + The details of how the identifiers are generated is an implementation detail. Do not rely on or assume any particular behaviour in Cadence programs. - + +::: ## Resource Owner diff --git a/docs/language/values-and-types.mdx b/docs/language/values-and-types.mdx index ecbf56a..ef9aac0 100644 --- a/docs/language/values-and-types.mdx +++ b/docs/language/values-and-types.mdx @@ -246,12 +246,12 @@ All integer types support the following functions: ## Fixed-Point Numbers - +:::warning[🚧 Status] -🚧 Status: Currently only the 64-bit wide `Fix64` and `UFix64` types are available. +Currently only the 64-bit wide `Fix64` and `UFix64` types are available. More fixed-point number types will be added in a future release. - +::: Fixed-point numbers are useful for representing fractional values. They have a fixed number of digits after decimal point. diff --git a/docs/testing-framework.mdx b/docs/testing-framework.mdx index cdbd9f4..1e43bd9 100644 --- a/docs/testing-framework.mdx +++ b/docs/testing-framework.mdx @@ -6,9 +6,11 @@ sidebar_label: Testing The Cadence testing framework provides a convenient way to write tests for Cadence programs in Cadence. This functionality is provided by the built-in `Test` contract. - +:::tip + The testing framework can only be used off-chain, e.g. by using the [Flow CLI](https://developers.flow.com/tools/flow-cli). - + +::: Tests must be written in the form of a Cadence script. A test script may contain testing functions that starts with the `test` prefix, @@ -1154,10 +1156,12 @@ struct Configuration { } ``` - +:::tip + The `Blockchain.useConfiguration` is a run-time alternative for [statically defining contract addresses in the flow.json config file](https://developers.flow.com/tools/flow-cli/flow.json/configuration.md#advanced-format). - + +::: The configurations can be specified during the test setup as a best-practice. diff --git a/docs/tutorial/01-first-steps.md b/docs/tutorial/01-first-steps.md index 97a88bc..0dde6ed 100644 --- a/docs/tutorial/01-first-steps.md +++ b/docs/tutorial/01-first-steps.md @@ -45,15 +45,17 @@ in the sidebar here and click the link in the callout box at the beginning of th The callout boxes should look like this: - - Open the starter code for this tutorial in the Flow Playground:
- - https://play.flow.com/ - - +:::tip + +Open the starter code for this tutorial in the Flow Playground:
+ + https://play.flow.com/ + + +::: When you click on one of these links, the tutorial code will open in a new tab and the contracts, transactions, and scripts will be loaded diff --git a/docs/tutorial/02-hello-world.md b/docs/tutorial/02-hello-world.md index 4bf1aa5..a947af9 100644 --- a/docs/tutorial/02-hello-world.md +++ b/docs/tutorial/02-hello-world.md @@ -20,23 +20,27 @@ socialImageDescription: Hello world smart contract image. In this tutorial, we'll write and deploy our first smart contract! - - Open the starter code for this tutorial in the Flow Playground:
- - https://play.flow.com/483b2f33-9e71-40aa-924a-2c5f0ead77aa - - The tutorial will ask you to take various actions to interact with this code. - - - - Instructions that require you to take action are always included in a callout - box like this one. These highlighted actions are all that you need to do to - get your code running, but reading the rest is necessary to understand the - language's design. - +:::tip + +Open the starter code for this tutorial in the Flow Playground:
+ + https://play.flow.com/483b2f33-9e71-40aa-924a-2c5f0ead77aa + +The tutorial will ask you to take various actions to interact with this code. + +::: + +:::info[Action] + +Instructions that require you to take action are always included in a callout +box like this one. These highlighted actions are all that you need to do to +get your code running, but reading the rest is necessary to understand the +language's design. + +::: This tutorial will walk you through an example of a smart contract that implements basic Cadence features, including accounts, transactions, and signers. @@ -86,7 +90,7 @@ Each account can have zero or more contracts and/or contract interfaces. A contract can be freely added, removed, or updated (with some restrictions) by the owner of the account. Now let's look at the `HelloWorld` contract that you'll be working through in this tutorial. - +:::info[Action] If you haven't already, you'll need to follow this link to open a playground session with the Hello World contracts, transactions, and scripts pre-loaded: @@ -98,17 +102,17 @@ If you haven't already, you'll need to follow this link to open a playground ses https://play.flow.com/483b2f33-9e71-40aa-924a-2c5f0ead77aa - +::: ![Playground Intro](playground-intro.png) - +:::info[Action] Open the Account `0x06` tab with the file called `HelloWorld.cdc` in the Contract 1 space.
`HelloWorld.cdc` should contain this code: - +::: ```cadence HelloWorld.cdc // HelloWorld.cdc @@ -190,13 +194,13 @@ In this tutorial, we use the account with the address `0x06` to store our `Hello Now that you know what an account is in a Cadence context, you can deploy the `HelloWorld` contract to your account. - +:::info[Action] Make sure that the account `0x06` tab is selected and that the `HelloWorld.cdc` file is in the editor.
Click the deploy button to deploy the contents of the editor to account `0x06`. - +::: ![Deploy Contract](deploybox.png) @@ -223,12 +227,12 @@ In addition to being able to access the authorizer's private assets, transactions can also read and call functions in public contracts, and access public functions in other users' accounts. For this tutorial, we use a transaction to call our `hello()` function. - +:::info[Action] Open the transaction named `Simple Transaction`
`Simple Transaction` should contain this code: - +::: ```cadence SayHello.cdc import HelloWorld from 0x06 @@ -266,12 +270,12 @@ Transactions are divided into two main phases, `prepare` and `execute`. This executes the `hello()` function in the `HelloWorld` contract and logs the result(`log(HelloWorld.hello())`) to the console. - +:::info[Action] In the box at the bottom right of the editor, select Account `0x06` as the transaction signer.
Click the `Send` button to submit the transaction - +::: You should see something like this in the transaction results at the bottom of the screen: diff --git a/docs/tutorial/03-resources.md b/docs/tutorial/03-resources.md index 7c807f7..4fb2b0f 100644 --- a/docs/tutorial/03-resources.md +++ b/docs/tutorial/03-resources.md @@ -21,23 +21,27 @@ socialImageDescription: Resource smart contract image. ## Overview - - Open the starter code for this tutorial in the Flow Playground:
- - https://play.flow.com/ddf0177e-81c8-4512-ac2e-28036b1a3f89 - - The tutorial will ask you to take various actions to interact with this code. - - - - Instructions that require you to take action are always included in a callout - box like this one. These highlighted actions are all that you need to do to - get your code running, but reading the rest is necessary to understand the - language's design. - +:::tip + +Open the starter code for this tutorial in the Flow Playground:
+ + https://play.flow.com/ddf0177e-81c8-4512-ac2e-28036b1a3f89 + +The tutorial will ask you to take various actions to interact with this code. + +::: + +:::info[Action] + +Instructions that require you to take action are always included in a callout +box like this one. These highlighted actions are all that you need to do to +get your code running, but reading the rest is necessary to understand the +language's design. + +::: This tutorial builds on the previous `Hello World` tutorial. Before beginning this tutorial, you should understand : @@ -108,12 +112,12 @@ being _moved_ from one place to another. The old variable or location that was h it will no longer be valid after the move. This is one of the ways that Cadence ensures that any given resource only exists in one place at a time. - +:::info[Action] Open the Account `0x06` tab with file named `HelloWorldResource.cdc`.
`HelloWorldResource.cdc` should contain the following code: - +::: ```cadence HelloWorldResource.cdc access(all) contract HelloWorld { @@ -136,11 +140,11 @@ access(all) contract HelloWorld { } ``` - +:::info[Action] Deploy this code to account `0x06` using the `Deploy` button. - +::: We start by declaring a new `HelloWorld` contract in account `0x06`, inside this new `HelloWorld` contract we: @@ -234,15 +238,13 @@ Resources can only exist in one location at a time, so movement must be explicit Now we're going to use a transaction to that calls the `createHelloAsset()` function and saves a `HelloAsset` resource to the account's storage. - +:::info[Action] Open the transaction named `Create Hello`. -
- `Create Hello` should contain the following code: - +::: ```cadence create_hello.cdc /// create_hello.cdc @@ -348,12 +350,12 @@ Finally, in the execute phase we log the phrase `"Saved Hello Resource to accoun log("Saved Hello Resource to account.") ``` - +:::info[Action] Select account `0x06` as the only signer. Click the `Send` button to submit the transaction. - +::: You should see something like this: @@ -361,18 +363,18 @@ You should see something like this: "Saved Hello Resource to account." ``` - +:::info[Action] You can also try removing the line of code that saves `newHello` to storage. -
You should see an error for `newHello` that says `loss of resource`. This means that you are not handling the resource properly. If you ever see this error in any of your programs, it means there is a resource somewhere that is not being explicitly stored or destroyed, meaning the program is invalid. -
+ Add the line back to make the transaction check properly. - + +::: In this case, this is the first time we have saved anything with the selected account, so we know that the storage spot at `/storage/HelloAssetTutorial` is empty. @@ -428,15 +430,13 @@ with the ability to use FlowToken assets. You don't have to worry about those fo Now we're going to use a transaction to call the `hello()` method from the `HelloAsset` resource. - +:::info[Action] Open the transaction named `Load Hello`. -
- `Load Hello` should contain the following code: - +::: ```cadence load_hello.cdc import HelloWorld from 0x06 @@ -557,12 +557,12 @@ Next, we use `save` again to put the object back in storage in the same spot: acct.storage.save(<-helloResource, to: /storage/HelloAssetTutorial) ``` - +:::info[Action] Select account `0x06` as the only signer. Click the `Send` button to submit the transaction. - +::: You should see something like this: diff --git a/docs/tutorial/04-capabilities.md b/docs/tutorial/04-capabilities.md index b18331f..5f2ca07 100644 --- a/docs/tutorial/04-capabilities.md +++ b/docs/tutorial/04-capabilities.md @@ -19,23 +19,28 @@ socialImageTitle: Cadence Resources socialImageDescription: Capability smart contract image. --- ## Overview - - Open the starter code for this tutorial in the Flow Playground. It is the same code that was in the previous tutorial:
- - https://play.flow.com/47d92bae-5234-463c-ae14-3dbd452a004f - - The tutorial will ask you to take various actions to interact with this code. - - - - Instructions that require you to take action are always included in a callout - box like this one. These highlighted actions are all that you need to do to - get your code running, but reading the rest is necessary to understand the - language's design. - + +:::tip + +Open the starter code for this tutorial in the Flow Playground. It is the same code that was in the previous tutorial:
+ + https://play.flow.com/47d92bae-5234-463c-ae14-3dbd452a004f + +The tutorial will ask you to take various actions to interact with this code. + +::: + +:::info[Action] + +Instructions that require you to take action are always included in a callout +box like this one. These highlighted actions are all that you need to do to +get your code running, but reading the rest is necessary to understand the +language's design. + +::: This tutorial builds on the [previous `Resource` tutorial](./03-resources.md). Before beginning this tutorial, you should have an idea of @@ -86,12 +91,12 @@ In this tutorial, you will: Before following this tutorial, you should have the `HelloWorld` contract deployed in account `0x06`, just like in the [previous `Resource` contract tutorial](./03-resources.md). - +:::info[Action] -Open the Account `0x06` tab with file named `HelloWorldResource.cdc`.
+Open the Account `0x06` tab with file named `HelloWorldResource.cdc`. `HelloWorldResource.cdc` should contain the following code: - +::: ```cadence HelloWorldResource-2.cdc access(all) contract HelloWorld { @@ -114,17 +119,17 @@ access(all) contract HelloWorld { } ``` - +:::info[Action] Deploy this code to account `0x06` using the `Deploy` button. - +::: - +:::info[Action] Click on the `Create Hello` transaction and send it with `0x06` as the signer. - +::: The contract and transaction above creates and stores the resource we'll be using in this tutorial. For a more detailed breakdown of the contract and transactions, @@ -146,15 +151,13 @@ to the underlying object and call the `hello()` function. A detailed explanation of what is happening in this transaction is below the transaction code so, if you feel lost, keep reading! - +:::info[Action] Open the transaction named `Create Link`. -
- `Create Link` should contain the following code: - +::: ```cadence create_link.cdc import HelloWorld from 0x06 @@ -200,12 +203,13 @@ transaction { } ``` - +:::info[Action] + +Ensure account `0x06` is still selected as a transaction signer. -Ensure account `0x06` is still selected as a transaction signer.
Click the `Send` button to send the transaction. - +::: In this transaction, we use the prepare phase to: 1. Create a capability with the `account.capabilities.storage.issue` method to the stored object `HelloWorld.HelloAsset` from the account path `/storage/HelloAssetTutorial` @@ -330,15 +334,13 @@ To execute a script, write a function called `access(all) fun main()`. You can click the execute script button to run the script. The result of the script will be printed to the console output. - +:::info[Action] Open the file `Get Greeting`. -
- `Get Greeting` should look like the following: - +::: ```cadence get_greeting.cdc import HelloWorld from 0x06 @@ -393,11 +395,11 @@ Then, the script uses the reference to call the `hello()` function and returns t Let's execute the script to see it run correctly. - +:::info[Action] Click the `Execute` button in the playground. - +::: diff --git a/docs/tutorial/05-non-fungible-tokens-1.md b/docs/tutorial/05-non-fungible-tokens-1.md index b271a64..80aba59 100644 --- a/docs/tutorial/05-non-fungible-tokens-1.md +++ b/docs/tutorial/05-non-fungible-tokens-1.md @@ -27,7 +27,7 @@ In this tutorial, we're going to deploy, store, and transfer **Non-Fungible Toke --- - +:::tip Open the starter code for this tutorial in the Flow Playground: @@ -36,13 +36,16 @@ Open the starter code for this tutorial in the Flow Playground: https://play.flow.com/dde1e2a4-aae6-4eda-86fd-f0b0b3f53f7e The tutorial will ask you to take various actions to interact with this code. - - +::: + +:::info[Action] + Instructions that require you to take action are always included in a callout box like this one. These highlighted actions are all that you need to do to get your code running, but reading the rest is necessary to understand the language's design. - + +::: The NFT is an integral part of blockchain technology. An NFT is a digital asset that represents ownership of a unique asset. @@ -86,13 +89,15 @@ To get you comfortable using NFTs, this tutorial will teach you to: 7. Transfer an NFT from one account to another. 8. Use a script to see what NFTs are stored in each account's collection. - - It is important to remember that while this tutorial implements a working - non-fungible token, it has been simplified for educational purposes and is not - what any project should use in production. See the - Flow Fungible Token standard - for the standard interface and example implementation. - +:::warning + +It is important to remember that while this tutorial implements a working +non-fungible token, it has been simplified for educational purposes and is not +what any project should use in production. See the +Flow Fungible Token standard +for the standard interface and example implementation. + +::: **Before proceeding with this tutorial**, we highly recommend following the instructions in [Getting Started](./01-first-steps.md), @@ -151,7 +156,7 @@ The contract will: This contract relies on the [account storage API](../language/accounts/storage.mdx) to save NFTs in the account. - +:::info[Action] First, you'll need to follow this link to open a playground session with the Non-Fungible Token contracts, transactions, and scripts pre-loaded: @@ -160,14 +165,14 @@ with the Non-Fungible Token contracts, transactions, and scripts pre-loaded: https://play.flow.com/dde1e2a4-aae6-4eda-86fd-f0b0b3f53f7e - +::: - +:::info[Action] Open Account `0x06` to see `BasicNFT.cdc`. `BasicNFT.cdc` should contain the following code: - +::: ```cadence BasicNFT.cdc access(all) contract BasicNFT { @@ -240,20 +245,21 @@ Here we access the storage object of the account that the contract is deployed t We also create the NFT in the same line and pass it as the first argument to `save`. We save it to the `/storage/` domain, where objects are meant to be stored. - +:::info[Action] Deploy `BasicNFT` by clicking the Deploy button in the top right of the editor. - +::: You should now have an NFT in your account. Let's run a transaction to check. - +:::info[Action] + +Open the `NFT Exists` transaction, select account `0x06` as the only signer, and send the transaction. -Open the `NFT Exists` transaction, select account `0x06` as the only signer, and send the transaction.
`NFT Exists` should look like this: - +::: ```cadence NFTExists.cdc import BasicNFT from 0x06 @@ -287,12 +293,13 @@ but we'll show the simplest one first. This will also be an opportunity for you to try to write some of your own code! - +:::info[Action] + +Open the `Basic Transfer` transaction. -Open the `Basic Transfer` transaction.
`Basic Transfer` should look like this: - +::: ```cadence import BasicNFT from 0x06 @@ -363,13 +370,13 @@ transaction { } ``` - +:::info[Action] Select both Account `0x06` and Account `0x07` as the signers. Make sure account `0x06` is the first signer.
Click the "Send" button to send the transaction. - +::: Now, the NFT should be stored in the storage of Account `0x07`! You should be able to run the "NFT Exists" transaction again with `0x07` as the signer diff --git a/docs/tutorial/05-non-fungible-tokens-2.md b/docs/tutorial/05-non-fungible-tokens-2.md index 3a69bf8..a8200de 100644 --- a/docs/tutorial/05-non-fungible-tokens-2.md +++ b/docs/tutorial/05-non-fungible-tokens-2.md @@ -28,23 +28,26 @@ a full implementation for **Non-Fungible Tokens (NFTs)**. --- - - Open the starter code for this tutorial in the Flow Playground: - - https://play.flow.com/63d827b3-0b49-48d5-91ba-4b222c23e217 - - The tutorial will ask you to take various actions to interact with this code. - - - +:::tip + +Open the starter code for this tutorial in the Flow Playground: + +https://play.flow.com/63d827b3-0b49-48d5-91ba-4b222c23e217 + +The tutorial will ask you to take various actions to interact with this code. + +::: + +:::info[Action] + Instructions that require you to take action are always included in a callout box like this one. These highlighted actions are all that you need to do to get your code running, but reading the rest is necessary to understand the language's design. - +::: ## Storing Multiple NFTs in a Collection @@ -120,14 +123,16 @@ This contract expands on the `BasicNFT` we looked at by adding: This contract introduces a few new concepts, we'll look at the new contract, then break down all the new concepts this contract introduces. - +:::info[Action] + +Open the `ExampleNFT` contract. + +Deploy the contract by clicking the Deploy button in the bottom right of the editor. -Open the `ExampleNFT` contract.
-Deploy the contract by clicking the Deploy button in the bottom right of the editor.
`ExampleNFT.cdc` should contain the code below. It contains what was already in `BasicNFT.cdc` plus additional resource declarations in the contract body. - +::: ```cadence ExampleNFT.cdc /// ExampleNFT.cdc @@ -385,12 +390,12 @@ Let's confirm this is true by running a script! Scripts in Cadence are simple transactions that run without any account permissions and only read information from the blockchain. - +:::info[Action] Open the script file named `Print 0x06 NFTs`. `Print 0x06 NFTs` should contain the following code: - +::: ```cadence import ExampleNFT from 0x06 @@ -415,12 +420,13 @@ access(all) fun main(): [UInt64] { } ``` - +:::info[Action] + +Execute `Print 0x06 NFTs` by clicking the Execute button in the top right of the editor box. -Execute `Print 0x06 NFTs` by clicking the Execute button in the top right of the editor box.
This script returns a list of the NFTs that account `0x06` owns. - +::: Because account `0x06` currently doesn't own any in its collection, it will just print an empty array: @@ -526,13 +532,14 @@ This would restrict minting, because the owner of this resource is the only one You can see an example of this in the [Marketplace tutorial](./08-marketplace-compose.md). - +:::info[Action] Open the file named `Mint NFT`. -Select account `0x06` as the only signer and send the transaction.
+Select account `0x06` as the only signer and send the transaction. + This transaction deposits the minted NFT into the account owner's NFT collection: - +::: ```cadence mint_nft.cdc import ExampleNFT from 0x06 @@ -568,12 +575,12 @@ transaction { } ``` - +:::info[Action] Reopen `Print 0x06 NFTs` and execute the script. This prints a list of the NFTs that account `0x06` owns. - +::: ```cadence print_06_nfts.cdc import ExampleNFT from 0x06 @@ -612,11 +619,11 @@ You should see that account `0x06` owns the NFT with `id = 1` Before we are able to transfer an NFT to another account, we need to set up that account with an NFTCollection of their own so they are able to receive NFTs. - +:::info[Action] Open the file named `Setup Account` and submit the transaction, using account `0x07` as the only signer. - +::: ```cadence SetupAccount.cdc import ExampleNFT from 0x06 @@ -647,12 +654,13 @@ transaction { Account `0x07` should now have an empty `Collection` resource stored in its account storage. It has also created and stored a capability to the collection in its `/public/` domain. - +:::info[Action] + +Open the file named `Transfer`, select account `0x06` as the only signer, and send the transaction. -Open the file named `Transfer`, select account `0x06` as the only signer, and send the transaction.
This transaction transfers a token from account `0x06` to account `0x07`. - +::: ```cadence transfer_nft.cdc import ExampleNFT from 0x06 @@ -707,11 +715,11 @@ that needs to sign a transaction to transfer a token is the one who is sending t Now we can check both accounts' collections to make sure that account `0x07` owns the token and account `0x06` has nothing. - +:::info[Action] Execute the script `Print all NFTs` to see the tokens in each account: - +::: ```cadence print_all_owned_nfts.cdc import ExampleNFT from 0x06 diff --git a/docs/tutorial/06-fungible-tokens.md b/docs/tutorial/06-fungible-tokens.md index 1dd48da..e4365d3 100644 --- a/docs/tutorial/06-fungible-tokens.md +++ b/docs/tutorial/06-fungible-tokens.md @@ -26,24 +26,28 @@ In this tutorial, we're going to deploy, store, and transfer fungible tokens. --- - - Open the starter code for this tutorial in the Flow Playground: -
- - https://play.flow.com/65b44962-32c8-49c4-8a69-e96475d5a780 - - The tutorial will ask you to take various actions to interact with this code. - - - - Instructions that require you to take action are always included in a callout - box like this one. These highlighted actions are all that you need to do to - get your code running, but reading the rest is necessary to understand the - language's design. - +:::tip + +Open the starter code for this tutorial in the Flow Playground: + + +https://play.flow.com/65b44962-32c8-49c4-8a69-e96475d5a780 + +The tutorial will ask you to take various actions to interact with this code. + +::: + +:::info[Action] + +Instructions that require you to take action are always included in a callout +box like this one. These highlighted actions are all that you need to do to +get your code running, but reading the rest is necessary to understand the +language's design. + +::: Some of the most popular contract classes on blockchains today are fungible tokens. These contracts create homogeneous tokens that can be transferred to other users and spent as currency (e.g., ERC-20 on Ethereum). @@ -80,15 +84,17 @@ using a smart contract similar to the one in this tutorial. There are special transactions and hooks that allow it to be used for transaction execution fees, storage fees, and staking, but besides that, developers and users are able to treat it and use it just like any other token in the network! - - It is important to remember that while this tutorial implements a working - fungible token, it has been simplified for educational purposes and is not - what any project should use in production. See the - Flow Fungible Token standard - for the standard interface and example implementation. You can also see the - Fungible Token Developer Guide - for a guide for how to create a production ready version of a Fungible Token contract. - +:::warning + +It is important to remember that while this tutorial implements a working +fungible token, it has been simplified for educational purposes and is not +what any project should use in production. See the +Flow Fungible Token standard +for the standard interface and example implementation. You can also see the +Fungible Token Developer Guide +for a guide for how to create a production ready version of a Fungible Token contract. + +::: We're going to take you through these steps to get comfortable with the fungible token: @@ -106,25 +112,27 @@ and [Hello, World!](./02-hello-world.md) to learn the basics of the language and --- - - First, you'll need to follow this link to open a playground session with the - Fungible Token contracts, transactions, and scripts pre-loaded:{" "} - - https://play.flow.com/65b44962-32c8-49c4-8a69-e96475d5a780 - - +:::info[Action] + +First, you'll need to follow this link to open a playground session with the +Fungible Token contracts, transactions, and scripts pre-loaded:{" "} + +https://play.flow.com/65b44962-32c8-49c4-8a69-e96475d5a780 + - +::: + +:::info[Action] Open the account `0x06` tab to see the file named `BasicToken.cdc`. `BasicToken.cdc` should contain the full code for the fungible token, which provides the core functionality to store fungible tokens in your account and transfer to and accept tokens from other users. - +::: The concepts involved in implementing a fungible token in Cadence can be unfamiliar at first. If you haven't completed and understood the previous tutorials, @@ -344,13 +352,13 @@ unless the developer has specifically overridden the requirement in the funtion Now that you have read about how the Fungible Token works, we can deploy a basic version of it to your account and send some transactions to interact with it. - +:::info[Action] Make sure that you have opened the Fungible Token templates in the playground by following the link at the top of this page. You should have Account `0x06` open and should see the code below. - +::: ```cadence /// BasicToken.cdc @@ -456,11 +464,11 @@ access(all) contract BasicToken { } ``` - +:::info[Action] Click the `Deploy` button at the top right of the editor to deploy the code. - +::: ![Deploy BasicToken on 0x06](./deploy_basic_token.png) @@ -505,12 +513,13 @@ In Cadence, you have to first withdraw tokens from your vault, then deposit them that you want to transfer to. We'll start a simple transaction that withdraws tokens from a vault and deposits them back into the same vault. - +:::info[Action] + +Open the transaction named `Basic Transfer`. -Open the transaction named `Basic Transfer`.
`Basic Transfer` should contain the following code for withdrawing and depositing with a stored Vault: - +::: ```cadence BasicTransfer.cdc // Basic Transfer @@ -543,13 +552,18 @@ transaction(amount: UFix64) { } ``` - - Select account `0x06` as the only signer.
- You can enter any number less than 30.0 for the amount of tokens to transfer.
- Click the `Send` button to submit the transaction.
- This transaction withdraws tokens from the main vault and deposits them back - to it. - +:::info[Action] + +Select account `0x06` as the only signer. + +You can enter any number less than 30.0 for the amount of tokens to transfer. + +Click the `Send` button to submit the transaction. + +This transaction withdraws tokens from the main vault and deposits them back +to it. + +::: This transaction is a basic example of a transfer within an account. It withdraws tokens from the main vault and deposits back to the main vault. @@ -755,25 +769,27 @@ the `deposit` function will be there since it is in the `ExampleToken.Receiver` Let's create capabilities to your `Vault` so that a separate account can send tokens to you. - +:::info[Action] -Before we submit a transaction interacting with ExampleToken resources, we'll need to deploy the contract to account `0x07`:
-1. Select `ExampleToken` in the playground sidebar
-2. Make sure that signer `0x07` is selected as the deploying address
+Before we submit a transaction interacting with ExampleToken resources, we'll need to deploy the contract to account `0x07`: + +1. Select `ExampleToken` in the playground sidebar +2. Make sure that signer `0x07` is selected as the deploying address 3. Click "Deploy" - +::: ![Deploy ExampleToken to 0x07](./deploy_example_token.png) Now we can continue on to configure Capabilities on the ExampleToken Vault. - +:::info[Action] + +Open the transaction named `Issue Capability`. -Open the transaction named `Issue Capability`.
`Issue Capability` should contain the following code for creating a reference to the stored Vault: - +::: ```cadence issue_capability.cdc import ExampleToken from 0x07 @@ -856,16 +872,16 @@ The `post` phase is for ensuring that certain conditions are met after the trans Here, we are getting the capability from its public path and calling its `check` function to ensure that the capability contains a valid link to a valid object in storage that is the specified type. - +:::info[Action] -Now that we understand the transaction, time to submit it:
+Now that we understand the transaction, time to submit it: -1. Select account `0x07` as the only signer.
-2. Click the `Send` button to submit the transaction.
+1. Select account `0x07` as the only signer. +2. Click the `Send` button to submit the transaction. 3. This transaction creates a new public capability to your `Vault` and checks that it was created correctly. - +::: ## Transfer Tokens to Another User @@ -876,15 +892,15 @@ We will do this by calling the `withdraw` function on account `0x07`'s Vault, which creates a temporary Vault object for moving the tokens, then deposits those tokens into account `0x08`'s vault by calling the `deposit` function on their vault. - +:::info[Action] Account `0x08` has not been set up to receive tokens, so we will do that now: -1. Open the transaction `Setup Account`.
-2. Select account `0x08` as the only signer.
+1. Open the transaction `Setup Account`. +2. Select account `0x08` as the only signer. 3. Click the `Send` button to set up account `0x08` so that it can receive tokens. - +::: ```cadence SetupAccount.cdc // Setup Account @@ -945,12 +961,12 @@ and not even include the `VaultMinter` in the contract. In the next transaction, account `0x07` will mint 30 new tokens and deposit them into account `0x08`'s newly created Vault. - +:::info[Action] -1. Open the `Mint Tokens` transaction.
+1. Open the `Mint Tokens` transaction. 2. Select only account `0x07` as a signer and send `Mint Tokens` to mint 30 tokens for account `0x08`. - +::: `Mint Tokens` should contain the code below. @@ -1036,11 +1052,11 @@ You can use scripts to access an account's public state. Scripts aren't signed b In this example, we will query the balance of each account's vault. The following will print out the balance of each account in the emulator. - +:::info[Action] Open the script named `Get Balances` in the scripts pane. - +::: `Get Balances` should contain the following code: @@ -1081,11 +1097,11 @@ fun main() { } ``` - +:::info[Action] Execute `Get Balances` by clicking the Execute button. - +::: This should ensure the following: @@ -1109,13 +1125,13 @@ To restart the playground, close your current session and open the link at the t Now that we have two accounts, each with a `Vault`, we can see how they transfer tokens to each other! - +:::info[Action] -1. Open the transaction named `Transfer Tokens`.
-2. Select account `0x08` as a signer and send the transaction.
+1. Open the transaction named `Transfer Tokens`. +2. Select account `0x08` as a signer and send the transaction. 3. `Transfer Tokens` should contain the following code for sending tokens to another user: - +::: ```cadence transfer_tokens.cdc // Transfer Tokens @@ -1185,11 +1201,11 @@ Separating the two also allows us to take advantage of being able to statically verify which parts of accounts can be modified in the `prepare` section of a transaction, which will help users have peace of mind when getting fed transactions to sign from an app. - +:::info[Action] Execute `Get Balances` again. - +::: If correct, you should see the following lines indicating that account `0x07`'s balance is 40 and account `0x08`'s balance is 20: diff --git a/docs/tutorial/07-marketplace-setup.md b/docs/tutorial/07-marketplace-setup.md index 53dd8f4..9be79c6 100644 --- a/docs/tutorial/07-marketplace-setup.md +++ b/docs/tutorial/07-marketplace-setup.md @@ -12,16 +12,18 @@ for an example of a production ready marketplace that you can use right now on t --- - - Open the starter code for this tutorial in the Flow Playground: - - https://play.flow.com/7355d51c-066b-46be-adab-a3da6c28b645 - - The tutorial will be asking you to take various actions to interact with this code. - +:::info[Action] + +Open the starter code for this tutorial in the Flow Playground: + + https://play.flow.com/7355d51c-066b-46be-adab-a3da6c28b645 + +The tutorial will be asking you to take various actions to interact with this code. + +::: If you have already completed the Marketplace tutorial, please move on to [Composable Resources: Kitty Hats](./10-resources-compose.md). @@ -31,11 +33,13 @@ to allow users to buy and sell NFTs with fungible tokens. --- - - Some of the code in these setup instructions has intentional errors built into it. - You should understand enough about Cadence to be able to fix these tutorials on your own. - All of the errors involve concepts that you have learned in previous tutorials - +:::info[Action] + +Some of the code in these setup instructions has intentional errors built into it. +You should understand enough about Cadence to be able to fix these tutorials on your own. +All of the errors involve concepts that you have learned in previous tutorials + +::: 1. Open the `ExampleToken` contract. This is the same contract from the fungible token tutorial. 2. Deploy the `ExampleToken` code to account `0x06`. diff --git a/docs/tutorial/08-marketplace-compose.md b/docs/tutorial/08-marketplace-compose.md index 38cc172..c4fcaca 100644 --- a/docs/tutorial/08-marketplace-compose.md +++ b/docs/tutorial/08-marketplace-compose.md @@ -10,23 +10,27 @@ This contract is already deployed to testnet and mainnet and can be used by anyo --- - - Open the starter code for this tutorial in the Flow Playground: - - https://play.flow.com/7355d51c-066b-46be-adab-a3da6c28b645 - - The tutorial will be asking you to take various actions to interact with this code. - [The marketplace setup guide](./07-marketplace-setup.md) shows you how to get the playground set up to do this tutorial. - - - +:::info[Action] + +Open the starter code for this tutorial in the Flow Playground: + +https://play.flow.com/7355d51c-066b-46be-adab-a3da6c28b645 + +The tutorial will be asking you to take various actions to interact with this code. +[The marketplace setup guide](./07-marketplace-setup.md) shows you how to get the playground set up to do this tutorial. + +::: + +:::info[Action] + Instructions that require you to take action are always included in a callout box like this one. These highlighted actions are all that you need to do to get your code running, but reading the rest is necessary to understand the language's design. - + +::: Marketplaces are a popular application of blockchain technology and smart contracts. When there are NFTs in existence, users usually want to be able to buy and sell them with their fungible tokens. @@ -45,13 +49,13 @@ Flow is designed to enable composability because of the way that interfaces, res The combination of these allows developers to do more with less, re-using known safe code and design patterns to create new, powerful, and unique interactions! - +:::info[Action] At some point before or after this tutorial, you should definitely check out the formal documentation linked above about interfaces, resources, and capabilities. It will help complete your understanding of these complex, but powerful features. - +::: To create a marketplace, we need to integrate the functionality of both fungible and non-fungible tokens into a single contract that gives users control over their money and assets. @@ -82,22 +86,24 @@ Then, users could either provide a link to their sale to an application that can or to a central sale aggregator smart contract if they want the entire transaction to stay on-chain. This way, the owner of the token keeps custody of their token while it is on sale. - +:::info[Action] + +Before we start, we need to confirm the state of your accounts. -Before we start, we need to confirm the state of your accounts.
If you haven't already, please perform the steps in the [marketplace setup guide](./07-marketplace-setup.md) -to ensure that the Fungible Token and Non-Fungible Token contracts are deployed to account 6 and 2 and own some tokens.
+to ensure that the Fungible Token and Non-Fungible Token contracts are deployed to account 6 and 2 and own some tokens. + Your accounts should look like this: - +::: - +:::info[Action] You can run the `1. Check Setup` script to ensure that your accounts are correctly set up: - +::: ```cadence CheckSetupScript.cdc // CheckSetupScript.cdc @@ -215,12 +221,12 @@ Every user who wants to sell an NFT will store an instance of a `@SaleCollection Time to deploy the marketplace contract: - +:::info[Action] -1. Switch to the ExampleMarketplace contract (Contract 3).
+1. Switch to the ExampleMarketplace contract (Contract 3). 2. With `ExampleMarketplace.cdc` open, select account `0x08` from the deployment modal in the bottom right and deploy. - +::: `ExampleMarketplace.cdc` should contain the following contract definition: @@ -578,12 +584,12 @@ Account `0x06` should have an NFT in their collection and the `ExampleMarketplac You can create a `SaleCollection` and list account `0x06`'s token for sale by following these steps: - +:::info[Action] -1. Open Transaction 4, `Create Sale`
+1. Open Transaction 4, `Create Sale` 2. Select account `0x06` as the only signer and click the `Send` button to submit the transaction. - +::: ```cadence Transaction4.cdc // CreateSale.cdc @@ -676,12 +682,12 @@ This script should complete and print something like this: The buyer can now purchase the seller's NFT by using the transaction in `Transaction2.cdc`: - +:::info[Action] -1. Open Transaction 5: `PurchaseSale.cdc` file
+1. Open Transaction 5: `PurchaseSale.cdc` file 2. Select account `0x07` as the only signer and click the `Send` button - +::: ```cadence PurchaseSale.cdc // PurchaseSale.cdc @@ -755,12 +761,12 @@ You can run now run a script to verify that the NFT was purchased correctly beca To run a script that verifies the NFT was purchased correctly, follow these steps: - +:::info[Action] -1. Open Script 3: `VerifyAfterPurchase.cdc`
+1. Open Script 3: `VerifyAfterPurchase.cdc` 2. Click the `Execute` button - +::: `VerifyAfterPurchase.cdc` should contain the following code: diff --git a/docs/tutorial/09-voting.md b/docs/tutorial/09-voting.md index 476f4a2..782c50a 100644 --- a/docs/tutorial/09-voting.md +++ b/docs/tutorial/09-voting.md @@ -6,22 +6,26 @@ In this tutorial, we're going to deploy a contract that allows users to vote on --- - - Open the starter code for this tutorial in the Flow Playground: - - https://play.flow.com/e8e2af39-370d-4a52-9f0b-bfb3b12c7eff - - The tutorial will be asking you to take various actions to interact with this code. - - - +:::info + +Open the starter code for this tutorial in the Flow Playground: + +https://play.flow.com/e8e2af39-370d-4a52-9f0b-bfb3b12c7eff + +The tutorial will be asking you to take various actions to interact with this code. + +::: + +:::info[Action] + Instructions that require you to take action are always included in a callout box like this one. These highlighted actions are all that you need to do to get your code running, but reading the rest is necessary to understand the language's design. - + +::: With the advent of blockchain technology and smart contracts, it has become popular to try to create decentralized voting mechanisms that allow large groups of users to vote completely on chain. @@ -53,11 +57,11 @@ inherent to resources. Time to see the contract we'll be working with: - +:::info[Action] -1. Open Contract 1 - the `ApprovalVoting` contract.
+1. Open Contract 1 - the `ApprovalVoting` contract. - +::: The contract should have the following contents: @@ -134,11 +138,12 @@ Once you're done, share your project with the Flow community in the Flow discord ## Deploy the Contract - -1. In the bottom right deployment modal, press the arrow to expand and make sure account `0x06` is selected as the signer.
+:::info[Action] + +1. In the bottom right deployment modal, press the arrow to expand and make sure account `0x06` is selected as the signer. 2. Click the Deploy button to deploy it to account `0x06` - +::: ## Perform Voting @@ -151,12 +156,12 @@ Performing the common actions in this voting contract only takes three types of We have a transaction for each step that we provide a skeleton of for you. With the `ApprovalVoting` contract deployed to account `0x06`: - +:::info[Action] -1. Open Transaction 1 which should have `Create Proposals`
+1. Open Transaction 1 which should have `Create Proposals` 2. Submit the transaction with account `0x06` selected as the only signer. - +::: ```cadence CreateProposals.cdc import ApprovalVoting from 0x06 @@ -204,13 +209,13 @@ without having to deploy a new contract for each one! Here, we're just exposing the create ballot function through a public capability for simplicity, so lets use the transaction for a voter to create a ballot. - +:::info[Action] -1. Open the `Create Ballot` transaction.
-2. Select account `0x07` as a signer.
+1. Open the `Create Ballot` transaction. +2. Select account `0x07` as a signer. 3. Submit the transaction by clicking the `Send` button - +::: ```cadence CreateBallot.cdc @@ -247,13 +252,13 @@ Now that account `0x07` has a `Ballot` in their storage, they can cast their vot To do this, they will call the `vote` method on their stored resource, then cast that `Ballot` by passing it to the `cast` function in the main smart contract. - +:::info[Action] -1. Open the `Cast Ballot` transaction.
-2. Select account `0x07` as the only transaction signer.
+1. Open the `Cast Ballot` transaction. +2. Select account `0x07` as the only transaction signer. 3. Click the `send` button to submit the transaction. - +::: ```cadence CastBallot.cdc import ApprovalVoting from 0x06 @@ -288,12 +293,12 @@ their votes on their own ballot and then sending the capability. At any time, anyone could read the current tally of votes by directly reading the fields of the contract. You can use a script to do that, since it does not need to modify storage. - +:::info[Action] -1. Open the `Get Votes` script.
+1. Open the `Get Votes` script. 2. Click the `execute` button to run the script. - +::: ```cadence GetVotes.cdc import ApprovalVoting from 0x06 diff --git a/docs/tutorial/10-resources-compose.md b/docs/tutorial/10-resources-compose.md index 8f20482..036e19a 100644 --- a/docs/tutorial/10-resources-compose.md +++ b/docs/tutorial/10-resources-compose.md @@ -6,10 +6,12 @@ In this tutorial, we're going to walk through how resources can own other resour --- - +:::info[Action] + This tutorial just includes example code. It does not have an associated playground project. You are still welcome to copy this code and paste it to the playground to test it out though! - + +::: Resources owning other resources is a powerful feature in the world of blockchain and smart contracts. diff --git a/versioned_docs/version-0.42/anti-patterns.md b/versioned_docs/version-0.42/anti-patterns.md index cb2b24a..4c92162 100644 --- a/versioned_docs/version-0.42/anti-patterns.md +++ b/versioned_docs/version-0.42/anti-patterns.md @@ -184,11 +184,11 @@ For public access to a capability, place it in an accounts public area so this e ## Array or dictionary fields should be private - +:::tip This anti-pattern has been addressed with [FLIP #703](https://github.com/onflow/flips/blob/main/cadence/20211129-cadence-mutability-restrictions.md) - +::: ### Problem diff --git a/versioned_docs/version-0.42/language/accounts.mdx b/versioned_docs/version-0.42/language/accounts.mdx index 009a41b..72ea5df 100644 --- a/versioned_docs/version-0.42/language/accounts.mdx +++ b/versioned_docs/version-0.42/language/accounts.mdx @@ -525,7 +525,8 @@ transaction(publicKey: [UInt8]) { } ``` - +:::tip + ⚠️ Note: Keys can also be added using the `addPublicKey` function. However, this method is currently deprecated and is available only for the backward compatibility. The `addPublicKey` method accepts the public key encoded together with their signature algorithm, @@ -539,7 +540,8 @@ transaction(key: [UInt8]) { } } ``` - + +::: #### Get Account Keys @@ -577,10 +579,12 @@ transaction() { } ``` - +:::tip + ⚠️ Note: Keys can also be removed using the `removePublicKey` function. However, this method is deprecated and is available only for the backward compatibility. - + +::: ## Account Inbox @@ -979,7 +983,8 @@ while `false` will terminate iteration. The specific order in which the objects are iterated over is undefined, as is the behavior when a path is added or removed from storage. - +:::warning + The order of iteration is undefined. Do not rely on any particular behaviour. Saving to or removing from storage during iteration can cause the order in which values are stored to change arbitrarily. @@ -1003,13 +1008,16 @@ account.forEachStored(fun (path: StoragePath, type: Type): Bool { return true }) ``` - - - The iteration will skip any broken elements in the storage. - An element could be broken due to invalid types associated with the stored value. - e.g: A value belongs to type `T` of a contract with syntax/semantic errors. - +::: + +:::warning + +The iteration will skip any broken elements in the storage. +An element could be broken due to invalid types associated with the stored value. +e.g: A value belongs to type `T` of a contract with syntax/semantic errors. + +::: ## Storage limit diff --git a/versioned_docs/version-0.42/language/attachments.mdx b/versioned_docs/version-0.42/language/attachments.mdx index e4fb948..da8178f 100644 --- a/versioned_docs/version-0.42/language/attachments.mdx +++ b/versioned_docs/version-0.42/language/attachments.mdx @@ -3,9 +3,11 @@ title: Attachments sidebar_position: 21 --- - +:::warning + ⚠️ This section describes a feature that is not yet released on Mainnet. - + +::: Attachments are a feature of Cadence designed to allow developers to extend a struct or resource type (even one that they did not declare) with new functionality, diff --git a/versioned_docs/version-0.42/language/built-in-functions.mdx b/versioned_docs/version-0.42/language/built-in-functions.mdx index 3603dec..f7d9d55 100644 --- a/versioned_docs/version-0.42/language/built-in-functions.mdx +++ b/versioned_docs/version-0.42/language/built-in-functions.mdx @@ -53,13 +53,13 @@ and [FLIP120](https://github.com/onflow/flips/pull/120) for more details. Nevertheless, developers need to be mindful to use `revertibleRandom()` correctly: - +:::warning A transaction can atomically revert all its action. It is possible for a transaction submitted by an untrusted party to post-select favorable results and revert the transaction for unfavorable results. - +::: The function usage remains safe when called by a trusted party that does not perform post-selection on the returned random numbers. @@ -81,11 +81,12 @@ This function is superseded by `revertibleRandom()`. it is called unsafe. The name is retained for downwards compatibility despite it technically being no longer unsafe (see `revertibleRandom()` for details). - +:::warning + `unsafeRandom` is deprecated and will be removed in an upcoming release of Cadence. Use `revertibleRandom()` instead. - +::: ## RLP diff --git a/versioned_docs/version-0.42/language/contracts.mdx b/versioned_docs/version-0.42/language/contracts.mdx index 5c8beed..051ded0 100644 --- a/versioned_docs/version-0.42/language/contracts.mdx +++ b/versioned_docs/version-0.42/language/contracts.mdx @@ -326,14 +326,14 @@ signer.contracts.add( ### Updating a Deployed Contract - +:::warning[🚧 Status] -🚧 Status: Updating contracts is **experimental**. +Updating contracts is **experimental**. Updating contracts is currently limited to maintain data consistency. [Certain restrictions are imposed](./contract-updatability.md). - +::: A deployed contract can be updated using the `update__experimental` function: diff --git a/versioned_docs/version-0.42/language/glossary.mdx b/versioned_docs/version-0.42/language/glossary.mdx index 817ccd1..62b8096 100644 --- a/versioned_docs/version-0.42/language/glossary.mdx +++ b/versioned_docs/version-0.42/language/glossary.mdx @@ -4,9 +4,11 @@ sidebar_position: 32 --- - -Tip: CTRL/⌘ + F and type in the symbol or operator you want to look up. - +:::tip + +CTRL/⌘ + F and type in the symbol or operator you want to look up. + +::: ## `&` (ampersand) diff --git a/versioned_docs/version-0.42/language/interfaces.mdx b/versioned_docs/version-0.42/language/interfaces.mdx index b1704ae..d949e5d 100644 --- a/versioned_docs/version-0.42/language/interfaces.mdx +++ b/versioned_docs/version-0.42/language/interfaces.mdx @@ -432,11 +432,11 @@ shape.area // is `54` ## Interface Nesting - +:::warning[🚧 Status] -🚧 Status: Currently only contracts and contract interfaces support nested interfaces. +Currently only contracts and contract interfaces support nested interfaces. - +::: Interfaces can be arbitrarily nested. Declaring an interface inside another does not require implementing types @@ -512,11 +512,11 @@ Only one conformance may provide a default function. ## Nested Type Requirements - +:::warning[🚧 Status] -🚧 Status: Currently only contracts and contract interfaces support nested type requirements. +Currently only contracts and contract interfaces support nested type requirements. - +::: Interfaces can require implementing types to provide concrete nested types. For example, a resource interface may require an implementing type to provide a resource type. diff --git a/versioned_docs/version-0.42/language/resources.mdx b/versioned_docs/version-0.42/language/resources.mdx index 17e2dda..5cb4068 100644 --- a/versioned_docs/version-0.42/language/resources.mdx +++ b/versioned_docs/version-0.42/language/resources.mdx @@ -591,11 +591,13 @@ id2 != id3 // true id3 != id1 // true ``` - +:::warning + The details of how the identifiers are generated is an implementation detail. Do not rely on or assume any particular behaviour in Cadence programs. - + +::: ## Resource Owner diff --git a/versioned_docs/version-0.42/language/values-and-types.mdx b/versioned_docs/version-0.42/language/values-and-types.mdx index 39b4763..dace180 100644 --- a/versioned_docs/version-0.42/language/values-and-types.mdx +++ b/versioned_docs/version-0.42/language/values-and-types.mdx @@ -244,12 +244,12 @@ All integer types support the following functions: ## Fixed-Point Numbers - +:::warning[🚧 Status] -🚧 Status: Currently only the 64-bit wide `Fix64` and `UFix64` types are available. +Currently only the 64-bit wide `Fix64` and `UFix64` types are available. More fixed-point number types will be added in a future release. - +::: Fixed-point numbers are useful for representing fractional values. They have a fixed number of digits after decimal point. diff --git a/versioned_docs/version-0.42/testing-framework.mdx b/versioned_docs/version-0.42/testing-framework.mdx index fe5fffc..bfbbbbe 100644 --- a/versioned_docs/version-0.42/testing-framework.mdx +++ b/versioned_docs/version-0.42/testing-framework.mdx @@ -6,9 +6,11 @@ sidebar_label: Testing The Cadence testing framework provides a convenient way to write tests for Cadence programs in Cadence. This functionality is provided by the built-in `Test` contract. - +:::tip + The testing framework can only be used off-chain, e.g. by using the [Flow CLI](https://developers.flow.com/tools/flow-cli/tests/run-tests). - + +::: Tests must be written in the form of a Cadence script. A test script may contain testing functions that starts with the `test` prefix, @@ -1032,10 +1034,12 @@ access(all) struct Configuration { } ``` - +:::tip + The `Blockchain.useConfiguration` is a run-time alternative for [statically defining contract addresses in the flow.json config file](https://developers.flow.com/tools/flow-cli/flow.json/configuration.md#advanced-format). - + +::: The configurations can be specified during the test setup as a best-practice. diff --git a/versioned_docs/version-0.42/tutorial/02-hello-world.md b/versioned_docs/version-0.42/tutorial/02-hello-world.md index 64ff2b6..3c6e7ad 100644 --- a/versioned_docs/version-0.42/tutorial/02-hello-world.md +++ b/versioned_docs/version-0.42/tutorial/02-hello-world.md @@ -20,30 +20,36 @@ socialImageDescription: Hello world smart contract image. In this tutorial, we'll write and deploy our first smart contract! - - Open the starter code for this tutorial in the Flow Playground:
- - https://play.onflow.org/af7aba31-dee9-4477-9e1d-7b46e958468e - -
- The tutorial will ask you to take various actions to interact with this code. - - - - The playground code that is linked uses Cadence 0.42, but the examples - use Cadence 1.0 to show how each contract, transaction and script - is implemented Cadence 1.0. The link will still work with the current version of the playground, but when the playground is updated to Cadence 1.0, the link will be replaced with a 1.0-compatible version. - - - - Instructions that require you to take action are always included in a callout - box like this one. These highlighted actions are all that you need to do to - get your code running, but reading the rest is necessary to understand the - language's design. - +:::tip + +Open the starter code for this tutorial in the Flow Playground:
+ + https://play.onflow.org/af7aba31-dee9-4477-9e1d-7b46e958468e + +
+The tutorial will ask you to take various actions to interact with this code. + +::: + +:::warning + +The playground code that is linked uses Cadence 0.42, but the examples +use Cadence 1.0 to show how each contract, transaction and script +is implemented Cadence 1.0. The link will still work with the current version of the playground, but when the playground is updated to Cadence 1.0, the link will be replaced with a 1.0-compatible version. + +::: + +:::info[Action] + +Instructions that require you to take action are always included in a callout +box like this one. These highlighted actions are all that you need to do to +get your code running, but reading the rest is necessary to understand the +language's design. + +::: ## What is a smart contract? @@ -109,7 +115,7 @@ Each account can have zero or more contracts and/or contract interfaces. A contract can be freely added, removed, or updated (with some restrictions) by the owner of the account. Now let's look at the `HelloWorld` contract that you'll be working through in this tutorial. - +:::info[Action] If you haven't already, you'll need to follow this link to open a playground session with the Hello World contracts, transactions, and scripts pre-loaded: @@ -121,17 +127,17 @@ If you haven't already, you'll need to follow this link to open a playground ses https://play.onflow.org/dbc06b40-d0b1-42da-9e0d-686bc9972e65 - +::: ![Playground Intro](playground-intro.png) - +:::info[Action] Open the Account `0x01` tab with the file called `HelloWorld.cdc` in the Contract 1 space.
`HelloWorld.cdc` should contain this code: - +::: ```cadence HelloWorld.cdc // HelloWorld.cdc @@ -220,13 +226,13 @@ Outside the Playground context, account addresses on Flow are completely unique. Now that you know what an account is in a Cadence context, you can deploy the `HelloWorld` contract to your account. - +:::info[Action] Make sure that the account `0x01` tab is selected and that the `HelloWorld.cdc` file is in the editor.
Click the deploy button to deploy the contents of the editor to account `0x01`. - +::: ![Deploy Contract](deploybox.png) @@ -253,12 +259,12 @@ In addition to being able to access the authorizer's private assets, transactions can also read and call functions in public contracts, and access public domains in other users' accounts. For this tutorial, we use a transaction to call our `hello()` function. - +:::info[Action] Open the transaction named `Simple Transaction`
`Simple Transaction` should contain this code: - +::: ```cadence SayHello.cdc import HelloWorld from 0x01 @@ -295,12 +301,12 @@ Transactions are divided into two main phases, `prepare` and `execute`. It can call functions on external contracts and objects and perform operations on data that was initialized in the transaction. In this example, the `execute` phase calls `HelloWorld.hello()` which calls the `hello()` function in the `HelloWorld` contract and logs the result(`log(HelloWorld.hello())`) to the console. - +:::info[Action] In the box at the bottom right of the editor, select Account `0x01` as the transaction signer.
Click the `Send` button to submit the transaction - +::: You should see something like this in the transaction results at the bottom of the screen: diff --git a/versioned_docs/version-0.42/tutorial/03-resources.md b/versioned_docs/version-0.42/tutorial/03-resources.md index e31de60..0d35aa7 100644 --- a/versioned_docs/version-0.42/tutorial/03-resources.md +++ b/versioned_docs/version-0.42/tutorial/03-resources.md @@ -21,30 +21,36 @@ socialImageDescription: Resource smart contract image. ## Overview - - Open the starter code for this tutorial in the Flow Playground:
- - https://play.onflow.org/b70199ae-6488-4e58-ae58-9f4ffecbd66a - -
- The tutorial will ask you to take various actions to interact with this code. - - - - The playground code that is linked uses Cadence 0.42, but the examples - use Cadence 1.0 to show how each contract, transaction and script - is implemented Cadence 1.0. The link will still work with the current version of the playground, but when the playground is updated to Cadence 1.0, the link will be replaced with a 1.0-compatible version. - - - - Instructions that require you to take action are always included in a callout - box like this one. These highlighted actions are all that you need to do to - get your code running, but reading the rest is necessary to understand the - language's design. - +:::tip + +Open the starter code for this tutorial in the Flow Playground:
+ + https://play.onflow.org/b70199ae-6488-4e58-ae58-9f4ffecbd66a + +
+The tutorial will ask you to take various actions to interact with this code. + +::: + +:::warning + +The playground code that is linked uses Cadence 0.42, but the examples +use Cadence 1.0 to show how each contract, transaction and script +is implemented Cadence 1.0. The link will still work with the current version of the playground, but when the playground is updated to Cadence 1.0, the link will be replaced with a 1.0-compatible version. + +::: + +:::info[Action] + +Instructions that require you to take action are always included in a callout +box like this one. These highlighted actions are all that you need to do to +get your code running, but reading the rest is necessary to understand the +language's design. + +::: This tutorial builds on the previous `Hello World` tutorial. Before beginning this tutorial, you should understand : @@ -104,12 +110,12 @@ The move operator `<-` is used to move a resource into a variable. You cannot use the assignment operator `=` with resources, so when you initialize a resource you will need to use the move operator `<-`. - +:::info[Action] Open the Account `0x01` tab with file named `HelloWorldResource.cdc`.
`HelloWorldResource.cdc` should contain the following code: - +::: ```cadence HelloWorldResource.cdc access(all) @@ -140,11 +146,11 @@ contract HelloWorld { } ``` - +:::info[Action] Deploy this code to account `0x01` using the `Deploy` button. - +::: We start by declaring a new `HelloWorld` contract in account `0x01`, inside this new `HelloWorld` contract we: @@ -258,7 +264,7 @@ Resources can only exist in one location at a time, so movement must be explicit Now we're going to use a transaction to that calls the `createHelloAsset()` function and saves a `HelloAsset` resource to the account's storage. - +:::info[Action] Open the transaction named `Create Hello`. @@ -266,7 +272,7 @@ Open the transaction named `Create Hello`. `Create Hello` should contain the following code: - +::: ```cadence CreateHello.cdc // Transaction1.cdc @@ -358,12 +364,12 @@ Finally, in the execute phase we log the phrase `"Saved Hello Resource to accoun log("Saved Hello Resource to account.") ``` - +:::info[Action] Select account `0x01` as the only signer. Click the `Send` button to submit the transaction. - +::: You should see something like this: @@ -371,7 +377,7 @@ You should see something like this: "Saved Hello Resource to account." ``` - +:::info[Action] You can also try removing the line of code that saves `newHello` to storage. @@ -382,7 +388,8 @@ If you ever see this error in any of your programs, it means there is a resource somewhere that is not being explicitly stored or destroyed, meaning the program is invalid.
Add the line back to make the transaction checks properly. - + +::: In this case, this is the first time we have saved anything with the selected account, so we know that the storage spot at `/storage/HelloAssetTutorial` is empty. @@ -436,7 +443,7 @@ Account Storage: Now we're going to use a transaction to call the `hello()` method from the `HelloAsset` resource. - +:::info[Action] Open the transaction named `Load Hello`. @@ -444,7 +451,7 @@ Open the transaction named `Load Hello`. `Load Hello` should contain the following code: - +::: ```cadence LoadHello.cdc import HelloWorld from 0x01 @@ -550,12 +557,12 @@ would defeat the purpose of the whole transaction, then the force-unwrap operato Refer to [Optionals In Cadence](../language/values-and-types.mdx#optionals) to learn more about optionals and how they are used. - +:::info[Action] Select account `0x01` as the only signer. Click the `Send` button to submit the transaction. - +::: You should see something like this: diff --git a/versioned_docs/version-0.42/tutorial/04-capabilities.md b/versioned_docs/version-0.42/tutorial/04-capabilities.md index 913b391..8c9d4a3 100644 --- a/versioned_docs/version-0.42/tutorial/04-capabilities.md +++ b/versioned_docs/version-0.42/tutorial/04-capabilities.md @@ -19,30 +19,37 @@ socialImageTitle: Cadence Resources socialImageDescription: Capability smart contract image. --- ## Overview - - Open the starter code for this tutorial in the Flow Playground. It is the same code that was in the previous tutorial:
- - https://play.onflow.org/a7f45bcd-8fda-45f6-b443-4b77302a1687 - -
- The tutorial will ask you to take various actions to interact with this code. - - - - The playground code that is linked uses Cadence 0.42, but the examples - use Cadence 1.0 to show how each contract, transaction and script - is implemented Cadence 1.0. The link will still work with the current version of the playground, but when the playground is updated to Cadence 1.0, the link will be replaced with a 1.0-compatible version. - - - - Instructions that require you to take action are always included in a callout - box like this one. These highlighted actions are all that you need to do to - get your code running, but reading the rest is necessary to understand the - language's design. - + +:::tip + +Open the starter code for this tutorial in the Flow Playground. It is the same code that was in the previous tutorial:
+ + https://play.onflow.org/a7f45bcd-8fda-45f6-b443-4b77302a1687 + +
+The tutorial will ask you to take various actions to interact with this code. + +::: + +:::info[Action] + +The playground code that is linked uses Cadence 0.42, but the examples +use Cadence 1.0 to show how each contract, transaction and script +is implemented Cadence 1.0. The link will still work with the current version of the playground, but when the playground is updated to Cadence 1.0, the link will be replaced with a 1.0-compatible version. + +::: + +:::info[Action] + +Instructions that require you to take action are always included in a callout +box like this one. These highlighted actions are all that you need to do to +get your code running, but reading the rest is necessary to understand the +language's design. + +::: This tutorial builds on the [previous `Resource` tutorial](./03-resources.md). Before beginning this tutorial, you should have an idea of @@ -88,12 +95,12 @@ In this tutorial, you will: Before following this tutorial, you should have the `HelloWorld` contract deployed in account `0x01`, just like in the [previous `Resource` contract tutorial](./03-resources.md). - +:::info[Action] Open the Account `0x01` tab with file named `HelloWorldResource.cdc`.
`HelloWorldResource.cdc` should contain the following code: - +::: ```cadence HelloWorldResource-2.cdc access(all) @@ -124,17 +131,17 @@ contract HelloWorld { } ``` - +:::info[Action] Deploy this code to account `0x01` using the `Deploy` button. - +::: - +:::info[Action] Click on the `Create Hello` transaction and send it with `0x01` as the signer. - +::: The contract and transaction above creates and stores the resource we'll be using in this tutorial. For a more detailed breakdown of the contract, have a look at the [previous tutorial](./03-resources.md). @@ -155,7 +162,7 @@ to the underlying object and call the `hello()` function. A detailed explanation of what is happening in this transaction is below the transaction code so, if you feel lost, keep reading! - +:::info[Action] Open the transaction named `Create Link`. @@ -163,7 +170,7 @@ Open the transaction named `Create Link`. `Create Link` should contain the following code: - +::: ```cadence CreateLink import HelloWorld from 0x01 @@ -210,12 +217,12 @@ transaction { } ``` - +:::info[Action] Ensure account `0x01` is still selected as a transaction signer.
Click the `Send` button to send the transaction. - +::: In this transaction, we use the prepare phase to: 1. Create a capability with the `account.capabilities.storage.issue` method to the stored object `HelloWorld.HelloAsset` from the account path `/storage/HelloAssetTutorial` @@ -341,7 +348,7 @@ To execute a script, write a function called `access(all) fun main()`. You can click the execute script button to run the script. The result of the script will be printed to the console output. - +:::info[Action] Open the file `Script1.cdc`. @@ -349,7 +356,7 @@ Open the file `Script1.cdc`. `Script1.cdc` should look like the following: - +::: ```cadence Script1.cdc import HelloWorld from 0x01 @@ -406,11 +413,11 @@ Then, the script uses the reference to call the `hello()` function and prints th Let's execute the script to see it run correctly. - +:::info[Action] Click the `Execute` button in the playground. - +::: diff --git a/versioned_docs/version-0.42/tutorial/05-non-fungible-tokens-1.md b/versioned_docs/version-0.42/tutorial/05-non-fungible-tokens-1.md index 5255efd..f9187d1 100644 --- a/versioned_docs/version-0.42/tutorial/05-non-fungible-tokens-1.md +++ b/versioned_docs/version-0.42/tutorial/05-non-fungible-tokens-1.md @@ -27,7 +27,7 @@ In this tutorial, we're going to deploy, store, and transfer **Non-Fungible Toke --- - +:::tip Open the starter code for this tutorial in the Flow Playground: @@ -37,18 +37,23 @@ Open the starter code for this tutorial in the Flow Playground:
The tutorial will ask you to take various actions to interact with this code. - - - The code in this tutorial and in the playground uses Cadence 0.42. The link will still work with the current version of the playground, but when the playground is updated to Cadence 1.0, the link will be replaced with a 1.0-compatible version. It is recommended that since - Flow is so close to upgrading to Cadence 1.0, that you learn Cadence 1.0 features and syntax. - +::: + +:::warning + +The code in this tutorial and in the playground uses Cadence 0.42. The link will still work with the current version of the playground, but when the playground is updated to Cadence 1.0, the link will be replaced with a 1.0-compatible version. It is recommended that since +Flow is so close to upgrading to Cadence 1.0, that you learn Cadence 1.0 features and syntax. + +::: + +:::info[Action] - Instructions that require you to take action are always included in a callout box like this one. These highlighted actions are all that you need to do to get your code running, but reading the rest is necessary to understand the language's design. - + +::: The NFT is an integral part of blockchain technology. An NFT is a digital asset that represents ownership of a unique asset. @@ -89,13 +94,15 @@ To get you comfortable using NFTs, this tutorial will teach you to: 7. Transfer an NFT from one account to another. 8. Use a script to see what NFTs are stored in each account's collection. - - It is important to remember that while this tutorial implements a working - non-fungible token, it has been simplified for educational purposes and is not - what any project should use in production. See the - Flow Fungible Token standard - for the standard interface and example implementation. - +:::warning + +It is important to remember that while this tutorial implements a working +non-fungible token, it has been simplified for educational purposes and is not +what any project should use in production. See the +Flow Fungible Token standard +for the standard interface and example implementation. + +::: **Before proceeding with this tutorial**, we highly recommend following the instructions in [Getting Started](./01-first-steps.md), @@ -140,7 +147,7 @@ The contract will: This contract relies on the [account storage API](https://cadence-lang.org/docs/1.0/language/accounts/storage) to save NFTs in the account. - +:::info[Action] First, you'll need to follow this link to open a playground session with the Non-Fungible Token contracts, transactions, and scripts pre-loaded: @@ -149,14 +156,14 @@ with the Non-Fungible Token contracts, transactions, and scripts pre-loaded: https://play.onflow.org/ae2f2a83-6698-4e03-93cf-70d35627e28e - +::: - +:::info[Action] Open Account `0x01` to see `BasicNFT.cdc`. `BasicNFT.cdc` should contain the following code: - +::: ```cadence BasicNFT.cdc access(all) @@ -215,20 +222,20 @@ Here we access the storage object of the account that the contract is deployed t We also create the NFT in the same line and pass it as the first argument to `save`. We save it to the `/storage` domain, where objects are meant to be stored. - +:::info[Action] Deploy `NFTv1` by clicking the Deploy button in the top right of the editor. - +::: You should now have an NFT in your account. Let's run a transaction to check. - +:::info[Action] Open the `NFT Exists` transaction, select account `0x01` as the only signer, and send the transaction.
`NFT Exists` should look like this: - +::: ```cadence NFTExists.cdc import BasicNFT from 0x01 @@ -262,12 +269,12 @@ but we'll show the simplest one first. This will also be an opportunity for you to try to write some of your own code! - +:::info[Action] Open the `Basic Transfer` transaction.
`Basic Transfer` should look like this: - +::: ```cadence import BasicNFT from 0x01 @@ -338,12 +345,12 @@ transaction { } ``` - +:::info[Action] Select both Account `0x01` and Account `0x02` as the signers.
Click the "Send" button to send the transaction. - +::: Now, the NFT should be stored in the storage of Account `0x02`! You should be able to run the "NFT Exists" transaction again with `0x02` as the signer diff --git a/versioned_docs/version-0.42/tutorial/05-non-fungible-tokens-2.md b/versioned_docs/version-0.42/tutorial/05-non-fungible-tokens-2.md index d687fa4..3f995dc 100644 --- a/versioned_docs/version-0.42/tutorial/05-non-fungible-tokens-2.md +++ b/versioned_docs/version-0.42/tutorial/05-non-fungible-tokens-2.md @@ -28,28 +28,34 @@ a full implementation for **Non-Fungible Tokens (NFTs)**. --- - - Open the starter code for this tutorial in the Flow Playground: - - https://play.onflow.org/f08e8e0d-d28e-4cbe-8d72-3afe2349c629 - -
- The tutorial will ask you to take various actions to interact with this code. - - - - The code in this tutorial and in the playground uses Cadence 0.42. The link will still work with the current version of the playground, but when the playground is updated to Cadence 1.0, the link will be replaced with a 1.0-compatible version. It is recommended that since - Flow is so close to upgrading to Cadence 1.0, that you learn Cadence 1.0 features and syntax. - - - +:::tip + +Open the starter code for this tutorial in the Flow Playground: + +https://play.onflow.org/f08e8e0d-d28e-4cbe-8d72-3afe2349c629 + +
+The tutorial will ask you to take various actions to interact with this code. + +::: + +:::warning + +The code in this tutorial and in the playground uses Cadence 0.42. The link will still work with the current version of the playground, but when the playground is updated to Cadence 1.0, the link will be replaced with a 1.0-compatible version. It is recommended that since +Flow is so close to upgrading to Cadence 1.0, that you learn Cadence 1.0 features and syntax. + +::: + +:::info[Action] + Instructions that require you to take action are always included in a callout box like this one. These highlighted actions are all that you need to do to get your code running, but reading the rest is necessary to understand the language's design. - + +::: ## Storing Multiple NFTs in a Collection @@ -125,14 +131,14 @@ and saves a minter resource to account storage. This contract introduces a few new concepts, we'll look at the new contract, then break down all the new concepts this contract introduces. - +:::info[Action] Open Account `0x01` to see `ExampleNFT.cdc`.
Deploy the contract by clicking the Deploy button in the bottom right of the editor.
`ExampleNFT.cdc` should contain the code below. It contains what was already in `BasicNFT.cdc` plus additional resource declarations in the contract body. - +::: ```cadence ExampleNFT.cdc // ExampleNFT.cdc @@ -430,12 +436,12 @@ Let's confirm this is true by running a script! Scripts in Cadence are simple transactions that run without any account permissions and only read information from the blockchain. - +:::info[Action] Open the script file named `Print 0x01 NFTs`. `Print 0x01 NFTs` should contain the following code: - +::: ```cadence import ExampleNFT from 0x01 @@ -457,12 +463,12 @@ fun main() { } ``` - +:::info[Action] Execute `Print 0x01 NFTs` by clicking the Execute button in the top right of the editor box.
This script prints a list of the NFTs that account `0x01` owns. - +::: Because account `0x01` currently doesn't own any in its collection, it will just print an empty array: @@ -486,13 +492,13 @@ This would restrict minting, because the owner of this resource is the only one You can see an example of this in the [Marketplace tutorial](./08-marketplace-compose.md). - +:::info[Action] Open the file named `Mint NFT`. Select account `0x01` as the only signer and send the transaction.
This transaction deposits the minted NFT into the account owner's NFT collection: - +::: ```cadence MintNFT.cdc import ExampleNFT from 0x01 @@ -524,12 +530,12 @@ transaction { } ``` - +:::info[Action] Reopen `Print 0x01 NFTs` and execute the script. This prints a list of the NFTs that account `0x01` owns. - +::: ```cadence Print0x01NFTs.cdc import ExampleNFT from 0x01 @@ -566,11 +572,11 @@ You should see that account `0x01` owns the NFT with `id = 1` Before we are able to transfer an NFT to another account, we need to set up that account with an NFTCollection of their own so they are able to receive NFTs. - +:::info[Action] Open the file named `Setup Account` and submit the transaction, using account `0x02` as the only signer. - +::: ```cadence SetupAccount.cdc import ExampleNFT from 0x01 @@ -601,12 +607,12 @@ transaction { Account `0x02` should now have an empty `Collection` resource stored in its account storage. It has also created and stored a capability to the collection in its `/public/` domain. - +:::info[Action] Open the file named `Transfer`, select account `0x01` as the only signer, and send the transaction.
This transaction transfers a token from account `0x01` to account `0x02`. - +::: ```cadence Transfer.cdc import ExampleNFT from 0x01 @@ -651,11 +657,11 @@ transaction { Now we can check both accounts' collections to make sure that account `0x02` owns the token and account `0x01` has nothing. - +:::info[Action] Execute the script `Print all NFTs` to see the tokens in each account: - +::: ```cadence Script2.cdc import ExampleNFT from 0x01 diff --git a/versioned_docs/version-0.42/tutorial/06-fungible-tokens.md b/versioned_docs/version-0.42/tutorial/06-fungible-tokens.md index 5687f2f..fdaba99 100644 --- a/versioned_docs/version-0.42/tutorial/06-fungible-tokens.md +++ b/versioned_docs/version-0.42/tutorial/06-fungible-tokens.md @@ -6,30 +6,36 @@ In this tutorial, we're going to deploy, store, and transfer fungible tokens. --- - - Open the starter code for this tutorial in the Flow Playground: -
- - https://play.onflow.org/e63bfce9-3324-4385-9542-626845ae0363 - -
- The tutorial will ask you to take various actions to interact with this code. - - - - The code in this tutorial and in the playground uses Cadence 0.42. The link will still work with the current version of the playground, but when the playground is updated to Cadence 1.0, the link will be replaced with a 1.0-compatible version. It is recommended that since - Flow is so close to upgrading to Cadence 1.0, that you learn Cadence 1.0 features and syntax. - - - - Instructions that require you to take action are always included in a callout - box like this one. These highlighted actions are all that you need to do to - get your code running, but reading the rest is necessary to understand the - language's design. - +:::tip + +Open the starter code for this tutorial in the Flow Playground: +
+ + https://play.onflow.org/e63bfce9-3324-4385-9542-626845ae0363 + +
+The tutorial will ask you to take various actions to interact with this code. + +::: + +:::warning + +The code in this tutorial and in the playground uses Cadence 0.42. The link will still work with the current version of the playground, but when the playground is updated to Cadence 1.0, the link will be replaced with a 1.0-compatible version. It is recommended that since +Flow is so close to upgrading to Cadence 1.0, that you learn Cadence 1.0 features and syntax. + +::: + +:::info[Action] + +Instructions that require you to take action are always included in a callout +box like this one. These highlighted actions are all that you need to do to +get your code running, but reading the rest is necessary to understand the +language's design. + +::: ## Follow Along! Developer advocate Kim dives deep on an array of topics, building on top of the information she shared in the Hello World tutorial. Learn core concepts such as creating a fungible token smart contract by using resources, resource interfaces, and using transactions to mint and transfer tokens! @@ -73,13 +79,15 @@ using a smart contract similar to the one in this tutorial. There are special transactions and hooks that allow it to be used for transaction execution fees, storage fees, and staking, but besides that, developers and users are able to treat it and use it just like any other token in the network! - - It is important to remember that while this tutorial implements a working - fungible token, it has been simplified for educational purposes and is not - what any project should use in production. See the - Flow Fungible Token standard - for the standard interface and example implementation. - +:::warning + +It is important to remember that while this tutorial implements a working +fungible token, it has been simplified for educational purposes and is not +what any project should use in production. See the +Flow Fungible Token standard +for the standard interface and example implementation. + +::: We're going to take you through these steps to get comfortable with the fungible token: @@ -97,25 +105,27 @@ and [Hello, World!](./02-hello-world.md) to learn the basics of the language and --- - - First, you'll need to follow this link to open a playground session with the - Fungible Token contracts, transactions, and scripts pre-loaded:{" "} - - https://play.onflow.org/e63bfce9-3324-4385-9542-626845ae0363 - - +:::tip + +First, you'll need to follow this link to open a playground session with the +Fungible Token contracts, transactions, and scripts pre-loaded:{" "} + + https://play.onflow.org/e63bfce9-3324-4385-9542-626845ae0363 + + +::: - +:::info[Action] Open the account `0x01` tab to see the file named `BasicToken.cdc`. `BasicToken.cdc` should contain the full code for the fungible token, which provides the core functionality to store fungible tokens in your account and transfer to and accept tokens from other users. - +::: The concepts involved in implementing a fungible token in Cadence can be unfamiliar at first. For an in-depth explanation of this functionality and code, continue reading the next section. @@ -327,13 +337,13 @@ unless the developer has specifically overridden the requirement in the funtion Now that you have read about how the Fungible Token works, we can deploy a basic version of it to your account and send some transactions to interact with it. - +:::info[Action] Make sure that you have opened the Fungible Token templates in the playground by following the link at the top of this page. You should have Account `0x01` open and should see the code below. - +::: ```cadence // BasicToken.cdc @@ -431,11 +441,11 @@ contract BasicToken { } ``` - +:::info[Action] Click the `Deploy` button at the top right of the editor to deploy the code. - +::: ![Deploy BasicToken on 0x01](./deploy_basic_token.png) @@ -479,12 +489,12 @@ In Cadence, you have to first withdraw tokens from your vault, then deposit them that you want to transfer to. We'll start a simple transaction that withdraws tokens from a vault and deposits them back into the same vault. - +:::info[Action] Open the transaction named `Basic Transfer`.
`Basic Transfer` should contain the following code for withdrawing and depositing with a stored Vault: - +::: ```cadence BasicTransfer.cdc // Basic Transfer @@ -511,12 +521,14 @@ transaction { } ``` - - Select account `0x01` as the only signer.
- Click the `Send` button to submit the transaction.
- This transaction withdraws tokens from the main vault and deposits them back - to it. - +:::info[Action] + +Select account `0x01` as the only signer.
+Click the `Send` button to submit the transaction.
+This transaction withdraws tokens from the main vault and deposits them back +to it. + +::: This transaction is a basic example of a transfer within an account. It withdraws tokens from the main vault and deposits back to the main vault. @@ -624,14 +636,16 @@ This does bring up an important security consideration though. While we have made all our fields and functions public here, it is actually recommended to default to making fields private unless it is explicitly needed to be public. - - This is especially important for array and dictionary types, - which can have their contents maliciously mutated if they are made public. - This is one of THE MOST COMMON security mistakes that Cadence developers make, - so it is vitally important to be aware of this. +:::warning + +This is especially important for array and dictionary types, +which can have their contents maliciously mutated if they are made public. +This is one of THE MOST COMMON security mistakes that Cadence developers make, +so it is vitally important to be aware of this. + +See the [Cadence Best Practices document](../anti-patterns.md#array-or-dictionary-fields-should-be-private) for more details. - See the [Cadence Best Practices document](../anti-patterns.md#array-or-dictionary-fields-should-be-private) for more details. - +::: ## Adding Interfaces to Our Fungible Token @@ -715,25 +729,25 @@ the `deposit` function will be there since it is in the `ExampleToken.Receiver` Let's create capabilities to your `Vault` so that a separate account can send tokens to you. - +:::info[Action] Before we submit a transaction interacting with ExampleToken resources, we'll need to deploy the contract to account `0x02`:
1. Select Contract 2 in the playground sidebar (the ExampleToken contract)
2. Make sure that signer `0x02` is selected as the deploying address
3. Click "Deploy" - +::: ![Deploy ExampleToken to 0x02](./deploy_example_token.png) Now we can continue on to configure Capabilities on the ExampleToken Vault. - +:::info[Action] Open the transaction named `Create Link`.
`Create Link` should contain the following code for creating a reference to the stored Vault: - +::: ```cadence CreateLink.cdc // Create Link @@ -813,7 +827,7 @@ The `post` phase is for ensuring that certain conditions are met after the trans Here, we are getting the capability from its public path and calling its `check` function to ensure that the capability contains a valid link to a valid object in storage that is the specified type. - +:::info[Action] Now that we understand the transaction, time to submit it:
@@ -821,7 +835,7 @@ Now that we understand the transaction, time to submit it:
2. Click the `Send` button to submit the transaction.
3. This transaction creates a new public reference to your `Vault` and checks that it was created correctly. - +::: ## Transfer Tokens to Another User @@ -836,7 +850,7 @@ Here we encounter another safety feature that Cadence introduces. Owning tokens so if anyone tries to send tokens to an account who isn't prepared to receive them, the transaction will fail. This way, Cadence protects the user if they accidentally enter the account address incorrectly when sending tokens. - +:::info[Action] Account `0x03` has not been set up to receive tokens, so we will do that now: @@ -844,7 +858,7 @@ Account `0x03` has not been set up to receive tokens, so we will do that now: 2. Select account `0x03` as the only signer.
3. Click the `Send` button to set up account `0x03` so that it can receive tokens. - +::: ```cadence SetupAccount.cdc // Setup Account @@ -899,12 +913,12 @@ and not even include the `VaultMinter` in the contract. In the next transaction, account `0x02` will mint 30 new tokens and deposit them into account `0x03`'s newly created Vault. - +:::info[Action] 1. Open the `Mint Tokens` transaction.
2. Select only account `0x02` as a signer and send `Mint Tokens` to mint 30 tokens for account `0x03`. - +::: `Mint Tokens` should contain the code below. @@ -989,11 +1003,11 @@ You can use scripts to access an account's public state. Scripts aren't signed b In this example, we will query the balance of each account's vault. The following will print out the balance of each account in the emulator. - +:::info[Action] Open the script named `Get Balances` in the scripts pane. - +::: `Get Balances` should contain the following code: @@ -1028,11 +1042,11 @@ fun main() { ``` - +:::info[Action] Execute `Get Balances` by clicking the Execute button. - +::: This should ensure the following: @@ -1056,13 +1070,13 @@ To restart the playground, close your current session and open the link at the t Now that we have two accounts, each with a `Vault`, we can see how they transfer tokens to each other! - +:::info[Action] 1. Open the transaction named `Transfer Tokens`.
2. Select account `0x03` as a signer and send the transaction.
3. `Transfer Tokens` should contain the following code for sending tokens to another user: - +::: ```cadence TransferTokens.cdc // Transfer Tokens @@ -1125,11 +1139,11 @@ Separating the two also allows us to take advantage of being able to statically verify which parts of accounts can be modified in the `prepare` section of a transaction, which will help users have peace of mind when getting fed transactions to sign from an app. - +:::info[Action] Execute `Get Balances` again. - +::: If correct, you should see the following lines indicating that account `0x02`'s balance is 40 and account `0x03`'s balance is 20: diff --git a/versioned_docs/version-0.42/tutorial/07-marketplace-setup.md b/versioned_docs/version-0.42/tutorial/07-marketplace-setup.md index aa52693..2f06f33 100644 --- a/versioned_docs/version-0.42/tutorial/07-marketplace-setup.md +++ b/versioned_docs/version-0.42/tutorial/07-marketplace-setup.md @@ -12,22 +12,26 @@ for an example of a production ready marketplace that you can use right now on t --- - - Open the starter code for this tutorial in the Flow Playground: - - https://play.onflow.org/49ec2856-1258-4675-bac3-850b4bae1929 - -
- The tutorial will be asking you to take various actions to interact with this code. - - - - The code in this tutorial and in the playground uses Cadence 0.42. The link will still work with the current version of the playground, but when the playground is updated to Cadence 1.0, the link will be replaced with a 1.0-compatible version. It is recommended that since - Flow is so close to upgrading to Cadence 1.0, that you learn Cadence 1.0 features and syntax. - +:::tip + +Open the starter code for this tutorial in the Flow Playground: + + https://play.onflow.org/49ec2856-1258-4675-bac3-850b4bae1929 + +
+The tutorial will be asking you to take various actions to interact with this code. + +::: + +:::info[Action] + +The code in this tutorial and in the playground uses Cadence 0.42. The link will still work with the current version of the playground, but when the playground is updated to Cadence 1.0, the link will be replaced with a 1.0-compatible version. It is recommended that since +Flow is so close to upgrading to Cadence 1.0, that you learn Cadence 1.0 features and syntax. + +::: If you have already completed the Marketplace tutorial, please move on to [Composable Resources: Kitty Hats](./10-resources-compose.md). diff --git a/versioned_docs/version-0.42/tutorial/08-marketplace-compose.md b/versioned_docs/version-0.42/tutorial/08-marketplace-compose.md index f434281..70e8f76 100644 --- a/versioned_docs/version-0.42/tutorial/08-marketplace-compose.md +++ b/versioned_docs/version-0.42/tutorial/08-marketplace-compose.md @@ -10,29 +10,35 @@ This contract is already deployed to testnet and mainnet and can be used by anyo --- - - Open the starter code for this tutorial in the Flow Playground: - - https://play.onflow.org/49ec2856-1258-4675-bac3-850b4bae1929 - -
- The tutorial will be asking you to take various actions to interact with this code. - [The marketplace setup guide](./07-marketplace-setup.md) shows you how to get the playground set up to do this tutorial. - - - - The code in this tutorial and in the playground uses Cadence 0.42. The link will still work with the current version of the playground, but when the playground is updated to Cadence 1.0, the link will be replaced with a 1.0-compatible version. It is recommended that since - Flow is so close to upgrading to Cadence 1.0, that you learn Cadence 1.0 features and syntax. - - - +:::tip + +Open the starter code for this tutorial in the Flow Playground: + +https://play.onflow.org/49ec2856-1258-4675-bac3-850b4bae1929 + +
+The tutorial will be asking you to take various actions to interact with this code. +[The marketplace setup guide](./07-marketplace-setup.md) shows you how to get the playground set up to do this tutorial. + +::: + +:::info[Action] + +The code in this tutorial and in the playground uses Cadence 0.42. The link will still work with the current version of the playground, but when the playground is updated to Cadence 1.0, the link will be replaced with a 1.0-compatible version. It is recommended that since +Flow is so close to upgrading to Cadence 1.0, that you learn Cadence 1.0 features and syntax. + +::: + +:::info[Action] + Instructions that require you to take action are always included in a callout box like this one. These highlighted actions are all that you need to do to get your code running, but reading the rest is necessary to understand the language's design. - + +::: Marketplaces are a popular application of blockchain technology and smart contracts. When there are NFTs in existence, users usually want to be able to buy and sell them with their fungible tokens. @@ -51,13 +57,13 @@ Flow is designed to enable composability because of the way that interfaces, res The combination of these allows developers to do more with less, re-using known safe code and design patterns to create new, powerful, and unique interactions! - +:::info[Action] At some point before or after this tutorial, you should definitely check out the formal documentation linked above about interfaces, resources, and capabilities. It will help complete your understanding of these complex, but powerful features. - +::: To create a marketplace, we need to integrate the functionality of both fungible and non-fungible tokens into a single contract that gives users control over their money and assets. @@ -88,22 +94,22 @@ Then, users could either provide a link to their sale to an application that can or to a central sale aggregator smart contract if they want the entire transaction to stay on-chain. This way, the owner of the token keeps custody of their token while it is on sale. - +:::info[Action] Before we start, we need to confirm the state of your accounts.
If you haven't already, please perform the steps in the [marketplace setup guide](./07-marketplace-setup.md) to ensure that the Fungible Token and Non-Fungible Token contracts are deployed to account 1 and 2 and own some tokens.
Your accounts should look like this: - +::: - +:::info[Action] You can run the `1. CheckSetupScript.cdc` script to ensure that your accounts are correctly set up: - +::: ```cadence CheckSetupScript.cdc // CheckSetupScript.cdc @@ -197,12 +203,12 @@ Every user who wants to sell an NFT will store an instance of a `SaleCollection` Time to deploy the marketplace contract: - +:::info[Action] 1. Switch to the ExampleMarketplace contract (Contract 3).
2. With `ExampleMarketplace.cdc` open, select account `0x03` from the deployment modal in the bottom right and deploy. - +::: `ExampleMarketplace.cdc` should contain the following contract definition: @@ -556,12 +562,12 @@ Account `0x01` should have an NFT in their collection and the `ExampleMarketplac You can create a `SaleCollection` and list account `0x01`'s token for sale by following these steps: - +:::info[Action] 1. Open Transaction 4, `CreateSale.cdc`
2. Select account `0x01` as the only signer and click the `Send` button to submit the transaction. - +::: ```cadence Transaction4.cdc // CreateSale.cdc @@ -656,12 +662,12 @@ This script should complete and print something like this: The buyer can now purchase the seller's NFT by using the transaction in `Transaction2.cdc`: - +:::info[Action] 1. Open Transaction 5: `PurchaseSale.cdc` file
2. Select account `0x02` as the only signer and click the `Send` button - +::: ```cadence PurchaseSale.cdc // PurchaseSale.cdc @@ -731,12 +737,12 @@ You can run now run a script to verify that the NFT was purchased correctly beca To run a script that verifies the NFT was purchased correctly, follow these steps: - +:::info[Action] 1. Open Script 3: `VerifyAfterPurchase.cdc`
2. Click the `Execute` button - +::: `VerifyAfterPurchase.cdc` should contain the following code: diff --git a/versioned_docs/version-0.42/tutorial/09-voting.mdx b/versioned_docs/version-0.42/tutorial/09-voting.mdx index 2c69834..be138b3 100644 --- a/versioned_docs/version-0.42/tutorial/09-voting.mdx +++ b/versioned_docs/version-0.42/tutorial/09-voting.mdx @@ -6,7 +6,8 @@ In this tutorial, we're going to deploy a contract that allows users to vote on --- - +:::tip + Open the starter code for this tutorial in the Flow Playground:
The tutorial will be asking you to take various actions to interact with this code. - - - The code in this tutorial and in the playground uses Cadence 0.42. The link will still work with the current version of the playground, but when the playground is updated to Cadence 1.0, the link will be replaced with a 1.0-compatible version. It is recommended that since - Flow is so close to upgrading to Cadence 1.0, that you learn Cadence 1.0 features and syntax. - +::: + +:::info[Action] + +The code in this tutorial and in the playground uses Cadence 0.42. The link will still work with the current version of the playground, but when the playground is updated to Cadence 1.0, the link will be replaced with a 1.0-compatible version. It is recommended that since +Flow is so close to upgrading to Cadence 1.0, that you learn Cadence 1.0 features and syntax. + +::: + +:::info[Action] - Instructions that require you to take action are always included in a callout box like this one. These highlighted actions are all that you need to do to get your code running, but reading the rest is necessary to understand the language's design. - + +::: With the advent of blockchain technology and smart contracts, it has become popular to try to create decentralized voting mechanisms that allow large groups of users to vote completely on chain. @@ -59,13 +65,13 @@ inherent to resources. Time to deploy the contract we'll be working with: - +:::info[Action] 1. Open Contract 1 - the `ApprovalVoting` contract.
2. In the bottom right deployment modal, press the arrow to expand and make sure account `0x01` is selected as the signer.
3. Click the Deploy button to deploy it to account `0x01` - +:::info[Action] ![Deploy ApprovalVoting to account 0x01](deploy_approval_voting.png) @@ -268,12 +274,12 @@ Performing the common actions in this voting contract only takes three types of We have a transaction for each step that we provide for you. With the `ApprovalVoting` contract to account `0x01`: - +:::info[Action] 1. Open Transaction 1 which should have `Transaction1.cdc`
2. Submit the transaction with account `0x01` selected as the only signer. - +::: ```cadence Transaction1.cdc import ApprovalVoting from 0x01 @@ -322,13 +328,13 @@ To select multiple signers, you first need to include two arguments in the `prep The playground will give you an error if the number of selected signers is different than the number of arguments to the prepare block. The playground also maps the accounts you select as signers to the arguments in the order that you select them. The first account you select will be the first argument, and the second account you select is the second argument. - +:::info[Action] 1. Open Transaction 2 which should have `Transaction2.cdc`.
2. Select account `0x01` as a signer first, then also select account `0x02`.
3. Submit the transaction by clicking the `Send` button - +::: ```cadence Transaction2.cdc @@ -368,13 +374,13 @@ Account `0x02` should now have a `Ballot` resource object in its account storage Now that account `0x02` has a `Ballot` in their storage, they can cast their vote. To do this, they will call the `vote` method on their stored resource, then cast that `Ballot` by passing it to the `cast` function in the main smart contract. - +:::info[Action] 1. Open Transaction 3 which should contain `Transaction3.cdc`.
2. Select account `0x02` as the only transaction signer.
3. Click the `send` button to submit the transaction. - +::: ```cadence Transaction3.cdc import ApprovalVoting from 0x01 @@ -406,12 +412,12 @@ In this transaction, the user votes for one of the proposals, and then moves the At any time, anyone could read the current tally of votes by directly reading the fields of the contract. You can use a script to do that, since it does not need to modify storage. - +:::info[Action] 1. Open a Script 1 which should contain the code below.
2. Click the `execute` button to run the script. - +::: ```cadence Script1.cdc import ApprovalVoting from 0x01 diff --git a/versioned_docs/version-0.42/tutorial/10-resources-compose.md b/versioned_docs/version-0.42/tutorial/10-resources-compose.md index 154ab43..a3e6b09 100644 --- a/versioned_docs/version-0.42/tutorial/10-resources-compose.md +++ b/versioned_docs/version-0.42/tutorial/10-resources-compose.md @@ -6,28 +6,34 @@ In this tutorial, we're going to walk through how resources can own other resour --- - - Open the starter code for this tutorial in the Flow Playground: - - https://play.onflow.org/01f812d7-799a-42fd-b9cb-9ffe556e02ad - -
- The tutorial will be asking you do take various actions to interact with this code. - - - - The code in this tutorial and in the playground uses Cadence 0.42. The link will still work with the current version of the playground, but when the playground is updated to Cadence 1.0, the link will be replaced with a 1.0-compatible version. It is recommended that since - Flow is so close to upgrading to Cadence 1.0, that you learn Cadence 1.0 features and syntax. - - - +:::tip + +Open the starter code for this tutorial in the Flow Playground: + +https://play.onflow.org/01f812d7-799a-42fd-b9cb-9ffe556e02ad + +
+The tutorial will be asking you do take various actions to interact with this code. + +::: + +:::info[Action] + +The code in this tutorial and in the playground uses Cadence 0.42. The link will still work with the current version of the playground, but when the playground is updated to Cadence 1.0, the link will be replaced with a 1.0-compatible version. It is recommended that since +Flow is so close to upgrading to Cadence 1.0, that you learn Cadence 1.0 features and syntax. + +::: + +:::info[Action] + Instructions that require you to take action are always included in a callout box like this one. These highlighted actions are all that you need to do to get your code running, but reading the rest is necessary to understand the language's design. - + +::: Resources owning other resources is a powerful feature in the world of blockchain and smart contracts. To showcase how this feature works on Flow, this tutorial will take you through these steps with a composable NFT: @@ -70,13 +76,13 @@ Even though the original contract didn't include specific support for CryptoKitt Here is a basic example of how we can replicate this feature in Cadence: - +:::info[Action] 1. Open Contract 1, the `KittyVerse.cdc` contract
2. In the bottom right deployment modal, press the arrow to expand and make sure account `0x01` is selected as the signer.
3. Click the Deploy button to deploy the contract to account `0x01` - +::: ![Deploy KittyVerse to account 0x01](deploy_kittyverse.png) @@ -241,13 +247,13 @@ You should see an output that looks something like this: Now we can run a transaction to move the Kitty along with its hat, remove the cowboy hat from the Kitty, then make the Kitty tip its hat. - +:::info[Action] 1. Open `Transaction2.cdc`.
2. Select account `0x01` as the only signer.
3. Send the transaction. - +::: In this transaction, we executed the following code: