diff --git a/src/components/Layout.jsx b/src/components/Layout.jsx index c948aee1d..833bf4fac 100644 --- a/src/components/Layout.jsx +++ b/src/components/Layout.jsx @@ -268,16 +268,20 @@ const tutorialNavigation = [ title: 'Tutorials', links: [ { - title: 'Originating a contract', - href: '/tutorials/originate-your-first-smart-contract/smartpy', + title: 'Deploy a smart contract', + href: '/tutorials/deploy-your-first-smart-contract', children: [ { title: 'SmartPy', - href: '/tutorials/originate-your-first-smart-contract/smartpy', + href: '/tutorials/deploy-your-first-smart-contract/smartpy', }, { - title: 'LIGO', - href: '/tutorials/originate-your-first-smart-contract/ligo', + title: 'CameLIGO', + href: '/tutorials/deploy-your-first-smart-contract/ligo', + }, + { + title: 'jsLIGO', + href: '/tutorials/deploy-your-first-smart-contract/jsligo', }, ], }, diff --git a/src/pages/index.md b/src/pages/index.md index 0f05a8c14..72d9a7293 100644 --- a/src/pages/index.md +++ b/src/pages/index.md @@ -21,7 +21,7 @@ Welcome to the Tezos Documentation Portal. We're currently in _beta_. Please sha {% quick-link title="Get and Install Tezos" icon="installation" href="/tezos-basics/get-started-with-octez" description="Get started with the Tezos client, Octez" /%} -{% quick-link title="Originate your First Smart Contract" icon="deploy" href="/tutorials/originate-your-first-smart-contract/smartpy" description="How to originate your first smart contract" isTutorial=true /%} +{% quick-link title="Deploy your First Smart Contract" icon="deploy" href="/tutorials/deploy-your-first-smart-contract/smartpy" description="Deploy your first smart contract on Tezos" isTutorial=true /%} {% quick-link title="Tezos Protocol & Shell" icon="protocol" href="/tezos-basics/tezos-protocol-and-shell" description="Understanding the Tezos Protocol & Shell" /%} diff --git a/src/pages/tezos-basics/tezos-blockchain-overview/index.md b/src/pages/tezos-basics/tezos-blockchain-overview/index.md index 4d2d7d8df..fbd58f7ad 100644 --- a/src/pages/tezos-basics/tezos-blockchain-overview/index.md +++ b/src/pages/tezos-basics/tezos-blockchain-overview/index.md @@ -1,7 +1,7 @@ --- id: tezos-blockchain-overview title: An Overview of Tezos -lastUpdated: 5th June 2023 +lastUpdated: 11th September 2023 --- # History @@ -9,21 +9,35 @@ lastUpdated: 5th June 2023 Tezos is an open-source, decentralized blockchain [created in 2014](https://tezos.com/whitepaper.pdf) by Arthur and Kathleen Breitman. It raised awareness and support in 2017 with its crowdfunding and launched the following year. Since its inception, Tezos has gone through multiple iterations of upgrades and development, staying true to its ethos -- "a blockchain designed to evolve". -# What Makes Tezos Different? +# What makes Tezos different? -Tezos stands apart from other blockchains in its capability to upgrade, allowing the network to evolve without requiring a hard fork. Anyone building on Tezos can propose a new protocol upgrade and have it adopted by the network without compromising the platform's stability or causing fragmentation. This makes Tezos adaptable to new technologies and able to address user needs where other blockchains struggle to make changes. +Here are some of the features that make Tezos different from other blockchains: -Tezos is unique in its governance model. All stakeholders can participate in the decision-making processes that impact the future direction of the network. Holders of XTZ —-the chain’s native token-— can propose changes to the protocol and bakers vote on them, such as changes to gas fees, reduction in block times, adding new features such as smart rollups, and even changing the consensus mechanism itself. +## Tezos can upgrade itself -The use of formal verification is a powerful feature where the code can be mathematically proven to be correct without side effects. The rigorous process of formal verification ensures that the smart contracts and other components function as intended, reducing the likelihood of errors, bugs, and security vulnerabilities. This approach gives Tezos an edge in security and reliability. +Tezos has a built-in capability to upgrade itself, which allows the network to evolve without requiring a hard fork. Anyone can propose an upgrade to the protocol and have it adopted by the network without compromising the platform's stability or causing fragmentation. This feature allows Tezos to adapt to new technologies and to address user needs rapidly. -Tezos’ proof-of-stake consensus model eliminates the need for high-energy use, making it the “green” choice for blockchains. Tezos' mechanism is known as baking and features optional delegation, allowing any stakeholder to participate in consensus without giving up custody of their tokens. Tezos' approach to consensus has been described as [Liquid Proof of Stake](https://medium.com/tezos/liquid-proof-of-stake-aec2f7ef1da7). Tezos allows its stakers \(i.e. delegators\) to earn rewards by delegating their tez coins without any lock-in or freeze mechanism. This gives the "liquid" nature to Tezos's proof-of-stake implementation. +## Stakeholders participate in governance -Proof-of-stake improves scalability and encourages incentive alignment. It also increases the cost of 51% attacks and avoids environmentally wasteful proof-of-work. Tezos launched in June 2018 as one of the first major Proof-of-Stake networks. +Anyone who holds XTZ — the chain's native token — can propose changes to how Tezos works, such as changes to gas fees and block times, new features such as smart rollups, or even major changes like how the consensus mechanism works. + +## Formal verification ensures trust and code quality + +*Formal verification* is a process that ensures that a smart contract does what it says it does and has no side effects. Formal verification reduces errors, bugs, and security vulnerabilities in contracts and allows users to trust them. For more information, see [Formal Verification on Tezos](../../advanced-topics/formal-verification/formal-verification-on-tezos). + +## Tezos uses proof of stake + +The proof-of-stake consensus model consensus model eliminates the need for high energy use, making it the "green" choice for blockchains. Instead of competing to achieve consensus as in proof-of-work models, Tezos nodes (called *bakers*) stake Tezos tokens to earn the right to create blocks and receive rewards. Users who want to participate without running a node themselves can delegate tokens to a baker for a share of the rewards. The bakers and delegators keep control of their tokens and can remove them at any time. Tezos's approach to consensus has been described as [Liquid Proof of Stake](https://medium.com/tezos/liquid-proof-of-stake-aec2f7ef1da7). + +The proof-of-stake model improves scalability and encourages incentive alignment. It also increases the cost of 51% attacks and avoids environmentally wasteful proof-of-work. Tezos launched in June 2018 as one of the first major proof-of-stake networks. + +## Tezos accepts multiple languages + +Tezos lets developers use languages that make sense for their use case, including versions of Python and JavaScript/TypeScript. For more information, see [An Introduction to Smart Contracts](../../smart-contracts/smart-contract-languages/). # The Tezos Ecosystem -Tezos has robust applications ranging from NFTs, DeFi, and gaming to enterprise and government use cases. +Tezos has robust applications ranging from NFTs, DeFi, and gaming to enterprise and government use cases. ## NFTs on Tezos @@ -35,13 +49,13 @@ Tezos is also being used for other NFT-related projects, such as [MoneyTrack](ht ## Enterprise and Government Uses of Tezos -Enterprises and regulatory bodies have been adopting Tezos as well. +Enterprises and regulatory bodies have been adopting Tezos as well. Tezos is being used by the French Armies and Gendarmerie's Information Center to [validate judicial expenses](https://cointelegraph.com/news/french-cybercrime-division-uses-smart-contacts-on-tezos-blockchain) incurred during investigations and record them on Tezos. In recent years, the concept of Central Bank Digital Currencies (CBDCs) has gained traction, with several countries around the world exploring their own CBDC projects. Société Générale carried out a series of successful tests [using Tezos](https://decrypt.co/112127/societe-generales-crypto-division-lands-regulatory-approval-france) to explore the potential of CBDCs. In September 2020, the bank announced that it had completed a pilot program using a custom-built version of the Tezos blockchain to simulate the issuance and circulation of CBDCs. The pilot involved testing the technology's ability to handle transactions, make payments, and settle transactions in a digital environment. -The Califonia DMV is also using Tezos for its project to [put car titles on the blockchain](https://fortune.com/crypto/2023/01/26/california-announces-dmv-run-blockchain-through-partnership-with-tezos/). +The Califonia DMV is also using Tezos for its project to [put car titles on the blockchain](https://fortune.com/crypto/2023/01/26/california-announces-dmv-run-blockchain-through-partnership-with-tezos/). [Sword Group](https://www.sword-group.com/2020/09/28/sword-launches-tezos-digisign/) an international technology company, launched DigiSign, an open-source tool built on Tezos that enables users to digitally sign, certify, and verify the authenticity of digital documents. diff --git a/src/pages/tutorials/deploy-your-first-smart-contract/index.md b/src/pages/tutorials/deploy-your-first-smart-contract/index.md new file mode 100644 index 000000000..554a453b4 --- /dev/null +++ b/src/pages/tutorials/deploy-your-first-smart-contract/index.md @@ -0,0 +1,28 @@ +--- +id: first-smart-contract-ov +title: Deploy a smart contract +authors: Tim McMackin +lastUpdated: 14th September 2023 +--- + +This tutorial covers using the Octez command-line client to deploy a smart contract to Tezos. +It covers how to: + +- Connect the Octez client to a testnet +- Create a wallet +- Get tokens from a faucet +- Code a contract, including: + - Defining the storage for the contract + - Defining entrypoints in the contract + - Writing code to run when the entrypoints are called +- Deploy (or originate) the contract to Tezos and set its starting storage value +- Look up the current state of the contract +- Call the contract from the command line + +This tutorial has different versions for different programming languages. +You can run the tutorial with the version of the language you are most familiar with or want to learn. +You do not need an experience in these languages to run the tutorial. + +- To use SmartPy, a language similar to Python, see [Deploy a smart contract with SmartPy](./smartpy) +- To use jsLIGO, a language similar to JavaScript and TypeScript, see [Deploy a smart contract with jsLIGO](./jsligo) +- To use CameLIGO, a language similar to OCaml, see [Deploy a smart contract with CameLIGO](./ligo) diff --git a/src/pages/tutorials/deploy-your-first-smart-contract/jsligo/index.md b/src/pages/tutorials/deploy-your-first-smart-contract/jsligo/index.md new file mode 100644 index 000000000..ed3176da8 --- /dev/null +++ b/src/pages/tutorials/deploy-your-first-smart-contract/jsligo/index.md @@ -0,0 +1,371 @@ +--- +id: first-smart-contract-jsligo +title: Deploy a smart contract with jsLIGO +authors: 'John Joubert, Sasha Aldrick, Claude Barde, Tim McMackin' +lastUpdated: 14th September 2023 +--- + +This tutorial covers using the Octez command-line client to deploy a smart contract to Tezos. +The tutorial uses the LIGO programming language, which is one of the languages that you can write Tezos smart contracts in. +Specifically, this tutorial uses the jsLIGO version of LIGO, which has syntax similar to JavaScript, but you don't need any experience with JavaScript or LIGO to do this tutorial. + +- If you are more familiar with Python, try [Deploy a smart contract with SmartPy](/tutorials/deploy-your-first-smart-contract/smartpy). +- If you are more familiar with OCaml, try [Deploy a smart contract with CameLIGO](/tutorials/deploy-your-first-smart-contract/ligo). + +In this tutorial, you will learn how to: + +- Connect the Octez client to a testnet +- Create a wallet +- Get tokens from a faucet +- Code a contract in LIGO, including: + - Defining the storage for the contract + - Defining entrypoints in the contract + - Writing code to run when the entrypoints are called +- Deploy (or originate) the contract to Tezos and set its starting storage value +- Look up the current state of the contract +- Call the contract from the command line + +## Tutorial contract + +The contract that you deploy in this tutorial stores a single integer. +It provides entrypoints that clients can call to change the value of that integer: + +- The `increment` endpoint accepts an integer as a parameter and adds that integer to the value in storage +- The `decrement` endpoint accepts an integer as a parameter and subtracts that integer to the value in storage +- The `reset` endpoint takes no parameters and resets the value in storage to 0 + +After you deploy the contract, you or any other user can call it through Octez or a distributed application (dApp). + +## Prerequisites + +To run this tutorial, you need the Octez client and LIGO. + +- To install the LIGO programming language, see . +You can verify that LIGO is installed by running this command: + + ```bash + ligo version + ``` + + If you see a message with the version of LIGO you have installed, LIGO is installed correctly. + +- To install the Octez client, which allows you to send transactions to the Tezos blockchain, follow the instructions to install the `tezos-client` package on your system on this site: . +You need only the `tezos-client` packages, not the other Octez packages such as `tezos-node`. + + You can verify that the Octez client is installed by running this command: + + ```bash + octez-client --version + ``` + + If you see a message with the version of Octez that you have installed, the Octez client is installed correctly. + For help on Octez, run `octez-client --help` or see . + +LIGO is a high-level programming language created by Marigold to write smart contracts for the Tezos blockchain. + +It abstracts away the complexity of using Michelson (the smart contract language directly available on-chain) and provides different syntaxes that make it easier to write smart contracts on Tezos. + +LIGO provides two syntaxes: *jsLigo*, a syntax similar to TypeScript, and *CameLigo*, a syntax similar to OCaml. +This tutorial uses jsLigo, but you do not need any experience with JavaScript or TypeScript to run it. + +## Create a project folder + +Follow these steps to create a LIGO project: + +1. On the command-line terminal, create a folder for the project and open it. +You can name your project anything you want, such as `example-smart-contract-jsligo`. + + ```bash + mkdir example-smart-contract-jsligo + cd example-smart-contract-jsligo + ``` + +1. Create a file named `increment.jsligo` in the project folder. +This is where the contract code goes. + + ```bash + touch increment.jsligo + ``` + +## Switch to a testnet + +Before you deploy your contract to the main Tezos network (referred to as *mainnet*), you can deploy it to a testnet. +Testnets are useful for testing Tezos operations because testnets provide tokens for free so you can work with them without spending real tokens. + +Tezos testnets are listed on this site: . + +The [Ghostnet](https://teztnets.xyz/ghostnet-about) testnet is a good choice for testing because it is intended to be long-lived, as opposed to shorter-term testnets that allow people to test new Tezos features. + +Follow these steps to set your Octez client to use a testnet instead of the main network: + +1. On , click the testnet to use, such as Ghostnet. + +1. Copy the one of the testnet's public RPC endpoints, such as `https://rpc.ghostnet.teztnets.xyz`. + +1. Set your Octez client to use this testnet by running this command on the command line, replacing the testnet RPC URL with the URL that you copied: + + ```bash + octez-client --endpoint https://rpc.ghostnet.teztnets.xyz config update + ``` + + Octez shows a warning that you are using a testnet instead of mainnet. + +1. Verify that you are using a testnet by running this command: + + ```bash + octez-client config show + ``` + + The response from Octez includes the URL of the testnet. + +## Create a local wallet + +Deploying and using a smart contract costs fees, so you need a local wallet and XTZ tokens. +The Octez client can manage a local wallet for you, and you can get XTZ tokens on testnets from faucets. + +1. Run the following command to generate a local wallet, replacing `local_wallet` with a name for your wallet: + + ```bash + octez-client gen keys local_wallet + ``` + +1. Get the address for the wallet by running this command, again replacing `local_wallet` with the name of your local wallet. + + ```bash + octez-client show address local_wallet + ``` + + The Octez client prints a warning that you are using a testnet and the address of the new wallet in the `hash` field. + The wallet address begins with `tz1`, `tz2`, or `tz3`, as in this example: + + ```bash + Warning: + + This is NOT the Tezos Mainnet. + + Do NOT use your fundraiser keys on this network. + + Hash: tz1dW9Mk...........H67L + Public Key: edp.............................bjbeDj + ``` + + You need the wallet address to send funds to the wallet, to deploy the contract, and to send transactions to the contract. + +1. On the testnets page at , click the faucet link for the testnet you are using. +For example, the Ghostnet faucet is at . + +1. On the faucet page, paste your wallet address into the input field labeled "Or fund any address" and click the button for the amount of XTZ to add to your wallet. +It may take a few minutes for the faucet to send the tokens and for those tokens to appear in your wallet. + + You can use the faucet as much as you need to get tokens on the testnet, but those tokens are worthless and cannot be used on mainnet. + + ![Fund your wallet using the Ghostnet Faucet](/images/wallet-funding.png) + +1. Run this command to check the balance of your wallet: + + ```bash + octez-client get balance for local_wallet + ``` + +If your wallet is set up correctly and the faucet has sent tokens to it, the Octez client prints the balance of your wallet, as in this example: + +``` +100 ꜩ +``` + +## Create the contract + +The contract that you will create has these basic parts: + +- A type that describes the contract's storage, in this case an integer. +The storage can be a primitive type such as an integer, string, or timestamp, or a complex data type that contains multiple values. +For more information on contract data types, see [Smart contract concepts](../../../smart-contracts/smart-contracts-concepts/). + +- Internal functions called entrypoints that run code when clients call the contract. + +- A type that describes the return value of the entrypoints. + +Follow these steps to create the code for the contract: + +1. Open the `increment.jsligo` file in any text editor. + +1. Create a namespace named `Counter` to hold the code for the contract: + + ```ts + namespace Counter { + + } + ``` + +1. Inside the namespace, create a TypeScript type to set the storage type to an integer: + + ```ts + type storage = int; + ``` + +1. Add this code to define the return type for the endpoints. +Tezos entrypoints return two values: a list of other operations to call and the new value of the contract's storage. + + ```ts + type returnValue = [list, storage]; + ``` + +1. Add the code for the increment and decrement entrypoints: + + ```ts + // Increment entrypoint + @entry + const increment = (delta : int, store : storage) : returnValue => + [list([]), store + delta]; + + // Decrement entrypoint + @entry + const decrement = (delta : int, store : storage) : returnValue => + [list([]), store - delta]; + ``` + + These functions begin with the `@entry` annotation to indicate that they are entrypoints. + They accept two parameters: the change in the storage value (an integer) and the current value of the storage (in the `storage` type that you created earlier in the code). + They return a value of the type `returnValue` that you created in the previous step. + + Each function returns an empty list of other operations to call and the new value of the storage. + +1. Add this code for the reset entrypoint: + + ```ts + // Reset entrypoint + @entry + const reset = (_ : unit, _ : storage) : returnValue => + [list([]), 0]; + ``` + + This function is similar to the others, but it does not take the current value of the storage into account. + It always returns an empty list of operations and 0. + +The complete contract code looks like this: + +```ts +namespace Counter { + type storage = int; + type returnValue = [list, storage]; + + // Increment entrypoint + @entry + const increment = (delta : int, store : storage) : returnValue => + [list([]), store + delta]; + + // Decrement entrypoint + @entry + const decrement = (delta : int, store : storage) : returnValue => + [list([]), store - delta]; + + // Reset entrypoint + @entry + const reset = (_ : unit, _ : storage) : returnValue => + [list([]), 0]; +} +``` + +## Test and compile the contract + +Before you can deploy the contract to Tezos, you must compile it to Michelson, the base language of Tezos contracts. + +1. Test the contract by passing parameters and the storage value to the LIGO `dry-run` command. +For example, this command sets the storage at 10 and increments it by 32: + + ```bash + ligo run dry-run increment.jsligo -m Counter -e increment "Increment(32)" "10" + ``` + + The terminal should show the response `(LIST_EMPTY(), 42)`. + This response means that the contract did not call any other contracts, so the list of operations is empty. + Then it shows the new value of the storage. + You can test the decrement and reset functions in the same way. + +1. Run this command to compile the contract: + + ```bash + ligo compile contract increment.jsligo -m Counter -o increment.tz + ``` + + If the compilation succeeds, no messages are shown in the terminal. + If you see error messages, verify that your contract code matches the code in the previous section. + +Now you can deploy the contract. + +## Deploying (originating) to the testnet + +Deploying a contract to the network is called "originating." +Originating the contract requires a small amount of Tezos tokens as a fee. + +1. Run the following command to originate the smart contract, changing `$MY_TZ_ADDRESS` to the address or local name of the wallet that you created earlier in the tutorial: + + ```bash + octez-client originate contract my-counter \ + transferring 0 from $MY_TZ_ADDRESS \ + running increment.tz \ + --init 10 --burn-cap 0.1 --force + ``` + + This command includes these parts: + + - It uses the Octez client `originate contract` command to originate the contract and assigns the local name `my-counter` to the contract + - It includes 0 tokens from your wallet with the transaction, but the `--burn-cap` argument allows the transaction to take up to 0.1 XTZ from your wallet for fees. + - It sets the initial value of the contract storage to 10 with the `--init` argument. + + If the contract deploys successfully, Octez shows the address of the new contract, as in this example: + + ```bash + New contract KT1Nnk.................UFsJrq originated. + The operation has only been included 0 blocks ago. + We recommend to wait more. + ``` + +1. Copy the contract address, which starts with `KT1`. + +1. Optional: Run the command `octez-client get balance for local_wallet` to get the updated balance of your wallet. + +1. Verify that the contract deployed successfully by finding it on a block explorer: + + 1. Open a Tezos block explorer such as [TzKT](https://tzkt.io) or [Better Call Dev](https://better-call.dev/). + + 1. Set the explorer to Ghostnet instead of mainnet. + + 1. Paste the contract address, which starts with `KT1`, into the search field and press Enter. + + 1. Go to the Storage tab to see that the initial value of the storage is 10. + +## Calling the contract + +Now you can call the contract from any Tezos client, including Octez. + +To increment the current storage by a certain value, call the `increment` entrypoint, as in this example, again changing `$MY_TZ_ADDRESS` to the address or local name of the wallet that you created earlier in the tutorial: + +```bash +octez-client --wait none transfer 0 from $MY_TZ_ADDRESS to my-counter --entrypoint 'increment' --arg '5' --burn-cap 0.1 +``` + +The previous example uses the local name `my-counter`. +You can also specify the contract address. + +To decrement the current storage by a certain value, call the `decrement` entrypoint, as in this example: + +```bash +octez-client --wait none transfer 0 from $MY_TZ_ADDRESS to my-counter --entrypoint 'decrement' --arg '6' --burn-cap 0.1 +``` + +Finally, to reset the current storage to zero, call the `reset` entrypoint, as in this example: + +```bash +octez-client --wait none transfer 0 from $MY_TZ_ADDRESS to my-counter --entrypoint 'reset' --arg 'Unit' --burn-cap 0.1 +``` + +You can go back to the block explorer to verify that the storage of the contract changed. + +## Summary + +Now the contract is running on the Tezos blockchain. +You or any other user can call it from any source that can send transactions to Tezos, including Octez, dApps, and other contracts. + +If you want to continue working with this contract, try creating a dApp to call it from a web application, similar to the dApp that you create in the tutorial [Build your first app on Tezos](../../build-your-first-app/). +You can also try adding your own endpoints and originating a new contract, but you cannot update the existing contract after it is deployed. diff --git a/src/pages/tutorials/deploy-your-first-smart-contract/ligo/index.md b/src/pages/tutorials/deploy-your-first-smart-contract/ligo/index.md new file mode 100644 index 000000000..549c10c8c --- /dev/null +++ b/src/pages/tutorials/deploy-your-first-smart-contract/ligo/index.md @@ -0,0 +1,356 @@ +--- +id: first-smart-contract-ligo +title: Deploy a smart contract with CameLIGO +authors: 'John Joubert, Sasha Aldrick, Claude Barde, Tim McMackin' +lastUpdated: 13th September 2023 +--- + +This tutorial covers using the Octez command-line client to deploy a smart contract to Tezos. +The tutorial uses the LIGO programming language, which is one of the languages that you can write Tezos smart contracts in. +Specifically, this tutorial uses the CameLIGO version of LIGO, which has syntax similar to OCaml, but you don't need any experience with OCaml or LIGO to do this tutorial. + +- If you are more familiar with JavaScript, try [Deploy a smart contract with jsLIGO](/tutorials/deploy-your-first-smart-contract/jsligo). +- If you are more familiar with Python, try [Deploy a smart contract with SmartPy](/tutorials/deploy-your-first-smart-contract/smartpy). + +In this tutorial, you will learn how to: + +- Connect the Octez client to a testnet +- Create a wallet +- Get tokens from a faucet +- Code a contract in LIGO, including: + - Defining the storage for the contract + - Defining entrypoints in the contract + - Writing code to run when the entrypoints are called +- Deploy (or originate) the contract to Tezos and set its starting storage value +- Look up the current state of the contract +- Call the contract from the command line + +## Tutorial contract + +The contract that you deploy in this tutorial stores a single integer. +It provides entrypoints that clients can call to change the value of that integer: + +- The `increment` endpoint accepts an integer as a parameter and adds that integer to the value in storage +- The `decrement` endpoint accepts an integer as a parameter and subtracts that integer to the value in storage +- The `reset` endpoint takes no parameters and resets the value in storage to 0 + +After you deploy the contract, you or any other user can call it through Octez or a distributed application (dApp). + +## Prerequisites + +To run this tutorial, you need the Octez client and LIGO. + +- To install the LIGO programming language, see . +You can verify that LIGO is installed by running this command: + + ```bash + ligo version + ``` + + If you see a message with the version of LIGO you have installed, LIGO is installed correctly. + +- To install the Octez client, which allows you to send transactions to the Tezos blockchain, follow the instructions to install the `tezos-client` package on your system on this site: . +You need only the `tezos-client` packages, not the other Octez packages such as `tezos-node`. + + You can verify that the Octez client is installed by running this command: + + ```bash + octez-client --version + ``` + + If you see a message with the version of Octez that you have installed, the Octez client is installed correctly. + For help on Octez, run `octez-client --help` or see . + +LIGO is a high-level programming language created by Marigold to write smart contracts for the Tezos blockchain. + +It abstracts away the complexity of using Michelson (the smart contract language directly available on-chain) and provides different syntaxes that make it easier to write smart contracts on Tezos. + +LIGO provides two syntaxes: *jsLigo*, a syntax similar to TypeScript, and *CameLigo*, a syntax similar to OCaml. +This tutorial uses CameLigo, but you do not need any experience with OCaml to run it. + +## Create a project folder + +Follow these steps to create a LIGO project: + +1. On the command-line terminal, create a folder for the project and open it. +You can name your project anything you want, such as `example-smart-contract-cameligo`. + + ```bash + mkdir example-smart-contract-cameligo + cd example-smart-contract-cameligo + ``` + +1. Create a file named `increment.mligo` in the project folder. +This is where the contract code goes. + + ```bash + touch increment.mligo + ``` + +## Switch to a testnet + +Before you deploy your contract to the main Tezos network (referred to as *mainnet*), you can deploy it to a testnet. +Testnets are useful for testing Tezos operations because testnets provide tokens for free so you can work with them without spending real tokens. + +Tezos testnets are listed on this site: . + +The [Ghostnet](https://teztnets.xyz/ghostnet-about) testnet is a good choice for testing because it is intended to be long-lived, as opposed to shorter-term testnets that allow people to test new Tezos features. + +Follow these steps to set your Octez client to use a testnet instead of the main network: + +1. On , click the testnet to use, such as Ghostnet. + +1. Copy the one of the testnet's public RPC endpoints, such as `https://rpc.ghostnet.teztnets.xyz`. + +1. Set your Octez client to use this testnet by running this command on the command line, replacing the testnet RPC URL with the URL that you copied: + + ```bash + octez-client --endpoint https://rpc.ghostnet.teztnets.xyz config update + ``` + + Octez shows a warning that you are using a testnet instead of mainnet. + +1. Verify that you are using a testnet by running this command: + + ```bash + octez-client config show + ``` + + The response from Octez includes the URL of the testnet. + +## Create a local wallet + +Deploying and using a smart contract costs fees, so you need a local wallet and XTZ tokens. +The Octez client can manage a local wallet for you, and you can get XTZ tokens on testnets from faucets. + +1. Run the following command to generate a local wallet, replacing `local_wallet` with a name for your wallet: + + ```bash + octez-client gen keys local_wallet + ``` + +1. Get the address for the wallet by running this command, again replacing `local_wallet` with the name of your local wallet. + + ```bash + octez-client show address local_wallet + ``` + + The Octez client prints a warning that you are using a testnet and the address of the new wallet in the `hash` field. + The wallet address begins with `tz1`, `tz2`, or `tz3`, as in this example: + + ```bash + Warning: + + This is NOT the Tezos Mainnet. + + Do NOT use your fundraiser keys on this network. + + Hash: tz1dW9Mk...........H67L + Public Key: edp.............................bjbeDj + ``` + + You need the wallet address to send funds to the wallet, to deploy the contract, and to send transactions to the contract. + +1. On the testnets page at , click the faucet link for the testnet you are using. +For example, the Ghostnet faucet is at . + +1. On the faucet page, paste your wallet address into the input field labeled "Or fund any address" and click the button for the amount of XTZ to add to your wallet. +It may take a few minutes for the faucet to send the tokens and for those tokens to appear in your wallet. + + You can use the faucet as much as you need to get tokens on the testnet, but those tokens are worthless and cannot be used on mainnet. + + ![Fund your wallet using the Ghostnet Faucet](/images/wallet-funding.png) + +1. Run this command to check the balance of your wallet: + + ```bash + octez-client get balance for local_wallet + ``` + +If your wallet is set up correctly and the faucet has sent tokens to it, the Octez client prints the balance of your wallet, as in this example: + +``` +100 ꜩ +``` + +## Create the contract + +The contract that you will create has these basic parts: + +- A type that describes the contract's storage, in this case an integer. +The storage can be a primitive type such as an integer, string, or timestamp, or a complex data type that contains multiple values. +For more information on contract data types, see [Smart contract concepts](../../../smart-contracts/smart-contracts-concepts/). + +- Internal functions called entrypoints that run code when clients call the contract. + +- A type that describes the return value of the entrypoints. + +Follow these steps to create the code for the contract: + +1. Open the `increment.mligo` file in any text editor. + +1. Add this line of code to set the storage type to an integer: + + ```ocaml + type storage = int + ``` + +1. Add this code to define the return type for the endpoints. +Tezos entrypoints return two values: a list of other operations to call and the new value of the contract's storage. + + ```ocaml + type returnValue = operation list * storage + ``` + +1. Add the code for the increment and decrement entrypoints: + + ```ocaml + // Increment entrypoint + [@entry] let increment (delta : int) (store : storage) : returnValue = + [], store + delta + + // Decrement entrypoint + [@entry] let decrement (delta : int) (store : storage) : returnValue = + [], store - delta + ``` + + These functions begin with the `@entry` annotation to indicate that they are entrypoints. + They accept two parameters: the change in the storage value (an integer) and the current value of the storage (in the `storage` type that you created earlier in the code). + They return a value of the type `returnValue` that you created in the previous step. + + Each function returns an empty list of other operations to call and the new value of the storage. + +1. Add this code for the reset entrypoint: + + ```ocaml + // Reset entrypoint + [@entry] let reset (() : unit) (_ : storage) : returnValue = + [], 0 + ``` + + This function is similar to the others, but it does not take the current value of the storage into account. + It always returns an empty list of operations and 0. + +The complete contract code looks like this: + +```ocaml +type storage = int + +type returnValue = operation list * storage + +// Increment entrypoint +[@entry] let increment (delta : int) (store : storage) : returnValue = + [], store + delta + +// Decrement entrypoint +[@entry] let decrement (delta : int) (store : storage) : returnValue = + [], store - delta + +// Reset entrypoint +[@entry] let reset (() : unit) (_ : storage) : returnValue = + [], 0 +``` + +## Test and compile the contract + +Before you can deploy the contract to Tezos, you must compile it to Michelson, the base language of Tezos contracts. + +1. Test the contract by passing parameters and the storage value to the LIGO `dry-run` command. +For example, this command sets the storage at 10 and increments it by 32: + + ```bash + ligo run dry-run increment.mligo "Increment(32)" "10" + ``` + + The terminal should show the response `(LIST_EMPTY(), 42)`. + This response means that the contract did not call any other contracts, so the list of operations is empty. + Then it shows the new value of the storage. + You can test the decrement and reset functions in the same way. + +1. Run this command to compile the contract: + + ```bash + ligo compile contract increment.mligo -o increment.tz + ``` + + If the compilation succeeds, no messages are shown in the terminal. + If you see error messages, verify that your contract code matches the code in the previous section. + +Now you can deploy the contract. + +## Deploying (originating) to the testnet + +Deploying a contract to the network is called "originating." +Originating the contract requires a small amount of Tezos tokens as a fee. + +1. Run the following command to originate the smart contract, changing `$MY_TZ_ADDRESS` to the address or local name of the wallet that you created earlier in the tutorial: + + ```bash + octez-client originate contract my-counter \ + transferring 0 from $MY_TZ_ADDRESS \ + running increment.tz \ + --init 10 --burn-cap 0.1 --force + ``` + + This command includes these parts: + + - It uses the Octez client `originate contract` command to originate the contract and assigns the local name `my-counter` to the contract + - It includes 0 tokens from your wallet with the transaction, but the `--burn-cap` argument allows the transaction to take up to 0.1 XTZ from your wallet for fees. + - It sets the initial value of the contract storage to 10 with the `--init` argument. + + If the contract deploys successfully, Octez shows the address of the new contract, as in this example: + + ```bash + New contract KT1Nnk.................UFsJrq originated. + The operation has only been included 0 blocks ago. + We recommend to wait more. + ``` + +1. Copy the contract address, which starts with `KT1`. + +1. Optional: Run the command `octez-client get balance for local_wallet` to get the updated balance of your wallet. + +1. Verify that the contract deployed successfully by finding it on a block explorer: + + 1. Open a Tezos block explorer such as [TzKT](https://tzkt.io) or [Better Call Dev](https://better-call.dev/). + + 1. Set the explorer to Ghostnet instead of mainnet. + + 1. Paste the contract address, which starts with `KT1`, into the search field and press Enter. + + 1. Go to the Storage tab to see that the initial value of the storage is 10. + +## Calling the contract + +Now you can call the contract from any Tezos client, including Octez. + +To increment the current storage by a certain value, call the `increment` entrypoint, as in this example, again changing `$MY_TZ_ADDRESS` to the address or local name of the wallet that you created earlier in the tutorial: + +```bash +octez-client --wait none transfer 0 from $MY_TZ_ADDRESS to my-counter --entrypoint 'increment' --arg '5' --burn-cap 0.1 +``` + +The previous example uses the local name `my-counter`. +You can also specify the contract address. + +To decrement the current storage by a certain value, call the `decrement` entrypoint, as in this example: + +```bash +octez-client --wait none transfer 0 from $MY_TZ_ADDRESS to my-counter --entrypoint 'decrement' --arg '6' --burn-cap 0.1 +``` + +Finally, to reset the current storage to zero, call the `reset` entrypoint, as in this example: + +```bash +octez-client --wait none transfer 0 from $MY_TZ_ADDRESS to my-counter --entrypoint 'reset' --arg 'Unit' --burn-cap 0.1 +``` + +You can go back to the block explorer to verify that the storage of the contract changed. + +## Summary + +Now the contract is running on the Tezos blockchain. +You or any other user can call it from any source that can send transactions to Tezos, including Octez, dApps, and other contracts. + +If you want to continue working with this contract, try creating a dApp to call it from a web application, similar to the dApp that you create in the tutorial [Build your first app on Tezos](../../build-your-first-app/). +You can also try adding your own endpoints and originating a new contract, but you cannot update the existing contract after it is deployed. diff --git a/src/pages/tutorials/deploy-your-first-smart-contract/smartpy/index.md b/src/pages/tutorials/deploy-your-first-smart-contract/smartpy/index.md new file mode 100644 index 000000000..d92784824 --- /dev/null +++ b/src/pages/tutorials/deploy-your-first-smart-contract/smartpy/index.md @@ -0,0 +1,379 @@ +--- +id: first-smart-contract-smartpy +title: Deploy a smart contract with SmartPy +authors: 'John Joubert, Sasha Aldrick, Tim McMackin' +lastUpdated: 13th September 2023 +--- + +This tutorial covers using the Octez command-line client to deploy a smart contract to Tezos. +The tutorial uses the SmartPy programming language, which is one of the languages that you can write Tezos smart contracts in. +SmartPy has syntax similar to Python, but you don't need any experience with Python or SmartPy to do this tutorial. + +- If you are more familiar with OCaml, try [Deploy a smart contract with CameLIGO](/tutorials/deploy-your-first-smart-contract/ligo). +- If you are more familiar with JavaScript, try [Deploy a smart contract with jsLIGO](/tutorials/deploy-your-first-smart-contract/jsligo). + +In this tutorial, you will learn how to: + +- Connect the Octez client to a testnet +- Create a wallet +- Get tokens from a faucet +- Code a contract in SmartPy, including: + - Defining the storage for the contract + - Defining entrypoints in the contract + - Writing code to run when the entrypoints are called +- Deploy (or originate) the contract to Tezos and set its starting storage value +- Look up the current state of the contract +- Call the contract from the command line + +## Tutorial contract + +The contract that you deploy in this tutorial stores a string value. +It provides entrypoints that clients can call to change the value of that string: + +- The `replace` endpoint accepts a new string as a parameter and stores that string, replacing the existing string. +- The `append` endpoint accepts a new string as a parameter and appends it to the existing string. + +After you deploy the contract, you or any other user can call it through Octez or a distributed application (dApp). + +## Prerequisites + +To run this tutorial, you need the Octez client, Docker, and SmartPy. + +- SmartPy requires Docker, so see to install Docker. + +- To install the SmartPy programming language, see . + +- To install the Octez client, which allows you to send transactions to the Tezos blockchain, follow the instructions to install the `tezos-client` package on your system on this site: . +You need only the `tezos-client` packages, not the other Octez packages such as `tezos-node`. + + You can verify that the Octez client is installed by running this command: + + ```bash + octez-client --version + ``` + + If you see a message with the version of Octez that you have installed, the Octez client is installed correctly. + For help on Octez, run `octez-client --help` or see . + +## Prerequisites + +To run this tutorial, you need the Octez client, Docker, and SmartPy. + +- SmartPy requires Docker, so see to install Docker. + +- To install the SmartPy programming language, see . + +- To install the Octez client, which allows you to send transactions to the Tezos blockchain, follow the instructions to install the `tezos-client` package on your system on this site: . +You need only the `tezos-client` packages, not the other Octez packages such as `tezos-node`. + + You can verify that the Octez client is installed by running this command: + + ```bash + octez-client --version + ``` + + If you see a message with the version of Octez that you have installed, the Octez client is installed correctly. + For help on Octez, run `octez-client --help` or see . + +## Tutorial contract + +The contract that you deploy in this tutorial stores a string value. +It provides entrypoints that clients can call to change the value of that string: + +- The `replace` endpoint accepts a new string as a parameter and stores that string, replacing the existing string. +- The `append` endpoint accepts a new string as a parameter and appends it to the existing string. + +After you deploy the contract, you or any other user can call it through Octez or a distributed application (dApp). + +## Prerequisites + +To run this tutorial, you need the Octez client, Docker, and SmartPy. + +- SmartPy requires Docker Desktop, so see to install Docker Desktop. + +- To install the SmartPy programming language, see . + +- To install the Octez client, which allows you to send transactions to the Tezos blockchain, follow the instructions to install the `tezos-client` package on your system on this site: . +You need only the `tezos-client` packages, not the other Octez packages such as `tezos-node`. + + You can verify that the Octez client is installed by running this command: + + ```bash + octez-client --version + ``` + + If you see a message with the version of Octez that you have installed, the Octez client is installed correctly. + For help on Octez, run `octez-client --help` or see . + +SmartPy is a high-level programming language that you can use to write smart contracts for the Tezos blockchain. + +It abstracts away the complexity of using Michelson (the smart contract language directly available on-chain) and provides different syntaxes that make it easier to write smart contracts on Tezos. + +## Create a project folder + +Follow these steps to create a SmartPy project: + +1. On the command-line terminal, create a folder for the project and open it. +You can name your project anything you want, such as `example-smart-contract-smartpy`. + + ```bash + mkdir example-smart-contract-smartpy + cd example-smart-contract-smartpy + ``` + +1. Create a file named `store_greeting.py` in the project folder. +This is where the contract code goes. + + ```bash + touch store_greeting.py + ``` + +## Switch to a testnet + +Before you deploy your contract to the main Tezos network (referred to as *mainnet*), you can deploy it to a testnet. +Testnets are useful for testing Tezos operations because testnets provide tokens for free so you can work with them without spending real tokens. + +Tezos testnets are listed on this site: . + +The [Ghostnet](https://teztnets.xyz/ghostnet-about) testnet is a good choice for testing because it is intended to be long-lived, as opposed to shorter-term testnets that allow people to test new Tezos features. + +Follow these steps to set your Octez client to use a testnet instead of the main network: + +1. On , click the testnet to use, such as Ghostnet. + +1. Copy the one of the testnet's public RPC endpoints, such as `https://rpc.ghostnet.teztnets.xyz`. + +1. Set your Octez client to use this testnet by running this command on the command line, replacing the testnet RPC URL with the URL that you copied: + + ```bash + octez-client --endpoint https://rpc.ghostnet.teztnets.xyz config update + ``` + + Octez shows a warning that you are using a testnet instead of mainnet. + +1. Verify that you are using a testnet by running this command: + + ```bash + octez-client config show + ``` + + The response from Octez includes the URL of the testnet. + +## Create a local wallet + +Deploying and using a smart contract costs fees, so you need a local wallet and XTZ tokens. +The Octez client can manage a local wallet for you, and you can get XTZ tokens on testnets from faucets. + +1. Run the following command to generate a local wallet, replacing `local_wallet` with a name for your wallet: + + ```bash + octez-client gen keys local_wallet + ``` + +1. Get the address for the wallet by running this command, again replacing `local_wallet` with the name of your local wallet. + + ```bash + octez-client show address local_wallet + ``` + + The Octez client prints a warning that you are using a testnet and the address of the new wallet in the `hash` field. + The wallet address begins with `tz1`, `tz2`, or `tz3`, as in this example: + + ```bash + Warning: + + This is NOT the Tezos Mainnet. + + Do NOT use your fundraiser keys on this network. + + Hash: tz1dW9Mk...........H67L + Public Key: edp.............................bjbeDj + ``` + + You need the wallet address to send funds to the wallet, to deploy the contract, and to send transactions to the contract. + +1. On the testnets page at , click the faucet link for the testnet you are using. +For example, the Ghostnet faucet is at . + +1. On the faucet page, paste your wallet address into the input field labeled "Or fund any address" and click the button for the amount of XTZ to add to your wallet. +It may take a few minutes for the faucet to send the tokens and for those tokens to appear in your wallet. + + You can use the faucet as much as you need to get tokens on the testnet, but those tokens are worthless and cannot be used on mainnet. + + ![Fund your wallet using the Ghostnet Faucet](/images/wallet-funding.png) + +1. Run this command to check the balance of your wallet: + + ```bash + octez-client get balance for local_wallet + ``` + +If your wallet is set up correctly and the faucet has sent tokens to it, the Octez client prints the balance of your wallet, as in this example: + +``` +100 ꜩ +``` + +## Create the contract + +The contract that you will create has these basic parts: + +- A function that initializes the contract and sets the starting value for it storage. + +- Internal functions called entrypoints that run code when clients call the contract. + +- Automated tests that verify that the contract works as expected. + +Follow these steps to create the code for the contract: + +1. Open the `store_greeting.py` in any text editor. + +1. Add this line of code to import SmartPy: + + ```python + import smartpy as sp + ``` + +1. Add this code that creates the entrypoints: + + ```python + @sp.module + def main(): + class StoreGreeting(sp.Contract): + def __init__(self, greeting): # Note the indentation + self.data.greeting = greeting + + @sp.entrypoint # Note the indentation + def replace(self, params): + self.data.greeting = params.text + + @sp.entrypoint # Note the indentation + def append(self, params): + self.data.greeting += params.text + ``` + + Indentation is significant in Python, so make sure that your indentation matches this code. + + The first two lines create a SmartPy module, which indicates that the code is SmartPy instead of ordinary Python. + + Then the code creates a class named StoreGreeting, which represents the smart contract. + The contract has an `__init__` function, which runs when the contract is deployed. + In this case, the function sets the initial value of the storage to a parameter that you pass when you deploy the contract. + This storage value is a string, but the storage can be another primitive type such as an integer or timestamp, or a complex data type that contains multiple values. + For more information on contract data types, see [Smart contract concepts](../../../smart-contracts/smart-contracts-concepts/). + +1. Add this code that creates the tests: + + ```python + @sp.add_test(name = "StoreGreeting") + def test(): + scenario = sp.test_scenario(main) + scenario.h1("StoreGreeting") + + contract = main.StoreGreeting("Hello") + scenario += contract + + scenario.verify(contract.data.greeting == "Hello") + + contract.replace(text = "Hi") + contract.append(text = ", there!") + scenario.verify(contract.data.greeting == "Hi, there!") + ``` + + These tests run automatically on compilation to verify that the replace and append endpoints work. + For more information about SmartPy and tests, see the [SmartPy documentation](https://smartpy.io/). + +## Test and compile the contract + +Before you can deploy the contract to Tezos, you must compile it to Michelson, the base language of Tezos contracts. +The compilation process automatically runs the tests in the `store_greeting.py` file. + +1. Run this command to compile the contract: + + ```bash + ./smartpy test store_greeting.py store_greeting/ + ``` + +If the compilation succeeds, no messages are shown in the terminal and SmartPy creates a compiled smart contract in the `store_greeting/StoreGreeting` folder. +If you see error messages, verify that your contract code matches the code in the previous section. + +The output includes JSON Michelson in `.json` files and [Micheline Michelson](https://tezos.gitlab.io/shell/micheline.html) in `.tz` files. +The most important file is named `step_002_cont_0_contract.tz`. +This is the Michelson file that you will use to deploy the contract to the testnet. + +## Deploying (originating) to the testnet + +Deploying a contract to the network is called "originating." +Originating the contract requires a small amount of Tezos tokens as a fee. + +1. Go to the the `store_greeting/StoreGreeting` folder: + + ```bash + cd store_greeting/StoreGreeting + ``` + +1. Run the following command to originate the smart contract, changing `$MY_TZ_ADDRESS` to the address of the wallet that you created earlier in the tutorial: + + ```bash + octez-client originate contract storeGreeting \ + transferring 0 from $MY_TZ_ADDRESS \ + running step_002_cont_0_contract.tz \ + --init '"Hello"' --burn-cap 0.1 + ``` + + This command includes these parts: + + - It uses the Octez client `originate contract` command to originate the contract and assigns the local name `storeGreeting` to the contract + - It includes 0 tokens from your wallet with the transaction, but the `--burn-cap` argument allows the transaction to take up to 0.1 XTZ from your wallet for fees. + - It sets the initial value of the contract storage to "Hello" with the `--init` argument. + + If the contract deploys successfully, Octez shows the address of the new contract, as in this example: + + ```bash + New contract KT1Nnk.................UFsJrq originated. + The operation has only been included 0 blocks ago. + We recommend to wait more. + ``` + +1. Copy the contract address, which starts with `KT1`. + +1. Optional: Run the command `octez-client get balance for local_wallet` to get the updated balance of your wallet. + +1. Verify that the contract deployed successfully by finding it on a block explorer: + + 1. Open a Tezos block explorer such as [TzKT](https://tzkt.io) or [Better Call Dev](https://better-call.dev/). + + 1. Set the explorer to Ghostnet instead of mainnet. + + 1. Paste the contract address, which starts with `KT1`, into the search field and press Enter. + + 1. Go to the Storage tab to see that the initial value of the storage is "Hello". + +![Confirmation that all worked correctly](/images/storage_success.png) + +## Calling the contract + +Now you can call the contract from any Tezos client, including Octez. + +To replace the string in storage, call the `replace` entrypoint and pass a new string value, again changing `$MY_TZ_ADDRESS` to the address or local name of the wallet that you created earlier in the tutorial: + +```bash +octez-client --wait none transfer 0 from $MY_TZ_ADDRESS to storeGreeting --entrypoint 'replace' --arg '"Hi there!"' --burn-cap 0.1 +``` + +The previous example uses the local name `storeGreeting`. +You can also specify the contract address. + +To append text to the string in storage, pass the string to append to the `append` entrypoint: + +```bash +octez-client --wait none transfer 0 from $MY_TZ_ADDRESS to storeGreeting --entrypoint 'append' --arg '" Appended Greeting"' --burn-cap 0.1 +``` + +## Summary + +Now the contract is running on the Tezos blockchain. +You or any other user can call it from any source that can send transactions to Tezos, including Octez, dApps, and other contracts. + +If you want to continue working with this contract, try creating a dApp to call it from a web application, similar to the dApp that you create in the tutorial [Build your first app on Tezos](../../build-your-first-app/). +You can also try adding your own endpoints and originating a new contract, but you cannot update the existing contract after it is deployed. diff --git a/src/pages/tutorials/index.md b/src/pages/tutorials/index.md index ad8000369..3a6f585ec 100644 --- a/src/pages/tutorials/index.md +++ b/src/pages/tutorials/index.md @@ -11,7 +11,7 @@ Welcome to the Tezos Documentation Tutorials Portal. We're currently in _beta_. {% lg-links %} -{% lg-link title="Originating your first smart contract" icon="deploy" href="/tutorials/originate-your-first-smart-contract/smartpy/" description="In 15 minutes, go from zero to hero and originate your first smart contract with SmartPy/LIGO" /%} +{% lg-link title="Deploy your first smart contract" icon="deploy" href="/tutorials/deploy-your-first-smart-contract/" description="In 15 minutes, go from zero to hero and deploy your first smart contract with SmartPy/LIGO" /%} {% lg-link title="Smart Rollups" icon="quickstart" href="/tutorials/smart-rollups" description="Get started by deploying your own smart rollup with our onboarding tutorial" /%} diff --git a/src/pages/tutorials/originate-your-first-smart-contract/ligo/index.md b/src/pages/tutorials/originate-your-first-smart-contract/ligo/index.md deleted file mode 100644 index 4c5488532..000000000 --- a/src/pages/tutorials/originate-your-first-smart-contract/ligo/index.md +++ /dev/null @@ -1,360 +0,0 @@ ---- -id: first-smart-contract-ligo -title: Originate your First Smart Contract with LIGO -authors: 'John Joubert, Sasha Aldrick, Claude Barde' -lastUpdated: 7th July 2023 ---- - ---- - -{% callout type="note" title="Want to use SmartPy?" %} -Click [here](/tutorials/originate-your-first-smart-contract/smartpy) to find out how to originate your first smart contract using SmartPy. -{% /callout %} - -## Prerequisites - -| Dependency | Installation instructions | -| ------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| Ligo | Follow the _Installation_ steps in this [guide](https://ligolang.org/docs/tutorials/getting-started/?lang=cameligo#install-ligo) | - -{% callout type="warning" title="Note" %} -Make sure you have **installed** the above CLI tools before getting started. -{% /callout %} - -Now that you have installed the [_octez-client_](https://opentezos.com/tezos-basics/cli-and-rpc/#how-to-install-the-octez-client) and [_Ligo_](https://ligolang.org/docs/tutorials/getting-started/?lang=cameligo#install-ligo), we'll go ahead and dive right in. - -Ligo is a high-level programming language created by Marigold to write smart contracts for the Tezos blockchain. - -It abstracts away the complexity of using Michelson (the smart contract language directly available on-chain) and provides different syntaxes that make it easier to write smart contracts on Tezos. - -The 2 syntaxes that are available at the moment are *JsLigo*, a syntax similar to TypeScript, and *CameLigo*, a syntax similar to OCaml. The following article will introduce CameLigo. - -## Create a project folder - -Now we can go ahead and create a folder somewhere on our local drive with the name of the project. Let's call it `example-smart-contract`. - -```bash -mkdir example-smart-contract -``` - -```bash -cd example-smart-contract -``` - -## Create a project file - -Inside the `example-smart-contract` folder, let's create a file called `increment.mligo` and save it. We'll need this file later. - -```bash -touch increment.mligo -``` - -## Confirm your setup -### Ligo - -You can run -```bash -./ligo version -``` -or -```bash -ligo version -``` -according to your setup to check if Ligo is properly installed. You should see something like: -``` sh -Protocol built-in: lima -0.60.0 -``` - -### Octez-client - -We can check that it's correctly installed by running the following command: - -``` sh -octez-client -``` - -And we should see something like this returned: - -``` sh -Usage: - octez-client [global options] command [command options] - octez-client --help (for global options) - octez-client [global options] command --help (for command options) - octez-client --version (for version information) - -To browse the documentation: - octez-client [global options] man (for a list of commands) - octez-client [global options] man -v 3 (for the full manual) - -Global options (must come before the command): - -d --base-dir : client data directory (absent: TEZOS_CLIENT_DIR env) - -c --config-file : configuration file - -t --timings: show RPC request times - --chain : chain on which to apply contextual commands (commands dependent on the context associated with the specified chain). Possible tags are 'main' and 'test'. - -b --block : block on which to apply contextual commands (commands dependent on the context associated with the specified block). Possible tags include 'head' and 'genesis' +/- an optional offset (e.g. "octez-client -b head-1 get timestamp"). Note that block queried must exist in node's storage. - -w --wait >: how many confirmation blocks are needed before an operation is considered included - -p --protocol : use commands of a specific protocol - -l --log-requests: log all requests to the node - --better-errors: Error reporting is more detailed. Can be used if a call to an RPC fails or if you don't know the input accepted by the RPC. It may happen that the RPC calls take more time however. - -A --addr : [DEPRECATED: use --endpoint instead] IP address of the node - -P --port : [DEPRECATED: use --endpoint instead] RPC port of the node - -S --tls: [DEPRECATED: use --endpoint instead] use TLS to connect to node. - -m --media-type : Sets the "media-type" value for the "accept" header for RPC requests to the node. The media accept header indicates to the node which format of data serialisation is supported. Use the value "json" for serialisation to the JSON format. - -E --endpoint : HTTP(S) endpoint of the node RPC interface; e.g. 'http://localhost:8732' - -s --sources : path to JSON file containing sources for --mode light. Example file content: {"min_agreement": 1.0, "uris": ["http://localhost:8732", "https://localhost:8733"]} - -R --remote-signer : URI of the remote signer - -f --password-filename : path to the password filename - -M --mode : how to interact with the node - -``` - -## Switch to a Testnet - -Before going further let's make sure we're working on a [Testnet](https://teztnets.xyz). - -View the available Testnets: - -``` sh -https://teztnets.xyz -``` - -The [Ghostnet](https://teztnets.xyz/ghostnet-about) might be a good choice for this guide (at the time of writing). - -Copy the _Public RPC endpoint_ which looks something like this: - -``` sh -https://rpc.ghostnet.teztnets.xyz -``` - -Make sure we use this endpoint by running: - -```bash -octez-client --endpoint https://rpc.ghostnet.teztnets.xyz config update -``` - -You should then see something like this returned: - -``` sh -Warning: - - This is NOT the Tezos Mainnet. - - Do NOT use your fundraiser keys on this network. -``` - -## Create a local wallet - -We're now going to create a local wallet to use throughout this guide. - -Run the following command to generate a local wallet with _octez-client_, making sure to replace `` with a name of your choosing: - -```bash -octez-client gen keys local_wallet -``` - -Let's get the address for this wallet because we'll need it later: - -```bash -octez-client show address local_wallet -``` - -Which will return something like this: - -``` sh -Warning: - - This is NOT the Tezos Mainnet. - - Do NOT use your fundraiser keys on this network. - -Hash: tz1dW9Mk...........H67L -Public Key: edp.............................bjbeDj -``` - -We'll want to copy the Hash that starts with `tz` to your clipboard: - -``` sh -tz1dW9Mk...........H67L -``` - -## Fund your test wallet - -Tezos provides a [faucet](https://faucet.ghostnet.teztnets.xyz) to allow you to use the Testnet for free (has no value and can't be used on the Mainnet). - -Let's go ahead and fund our wallet through the [Ghostnet Faucet](https://faucet.ghostnet.teztnets.xyz). Paste the hash you copied earlier into the input field for "Or fund any address" and select the amount you'd like to add to your wallet. - -![Fund your wallet using the Ghostnet Faucet](/images/wallet-funding.png) - -Wait a minute or two and you can then run the following command to check that your wallet has funds in it: - -``` sh - octez-client get balance for local_wallet -``` - -Which will return something like this: - -``` sh -100 ꜩ -``` - -## Use Ligo to create the contract - -For this introduction to Ligo, you will write a very simple contract that increments, decrements, or resets a number in its storage. - -A contract is made of 3 main parts: -- a parameter type to update the storage -- a storage type to describe how values are stored -- a piece of code that controls the update of the storage - -The purpose of a smart contract is to write code that will use the values passed as a parameter to manipulate and update the storage in the intended way. - -The contract will store an integer: - -``` sh -type storage = int -``` - -The parameter to update the contract storage is a *variant*, similar to a TypeScript enum: - -``` sh -type parameter = -| Increment of int -| Decrement of int -| Reset -``` - -You can use the different branches of the variant to simulate entrypoints for your contract. In this case, there is an **Increment** entrypoint, a **Decrement** entrypoint, and a **Reset** entrypoint. - -Next, you declare a function called `main` that will receive the parameter value and the storage when the contract is called. This function returns a tuple with a list of operations on the left and the new storage on the right: - -``` sh -let main (action, store : parameter * storage) : operation list * storage = -``` - -You can return an empty list of operations from the beginning, then use pattern matching to match the targetted entrypoint: -``` sh -([] : operation list), - (match action with - | Increment (n) -> add (store, n) - | Decrement (n) -> sub (store, n) - | Reset -> 0) -``` - -The **Increment** branch redirects to an `add` function that takes a tuple as a parameter made of the current storage and the value used to increment the storage. - -The **Decrement** branch redirects to a `sub` function that takes a tuple as a parameter made of the current storage and the value used to decrement the storage. - -The **Reset** branch only returns `0`, the new storage. - -The `add` function: - -```bash -let add (store, inc : storage * int) : storage = store + inc -``` -takes a tuple with the current storage on the left and the value to increment it on the right. These 2 values are added and returned as the new storage. - -The `sub` function: - -```bash -let sub (store, dec : storage * int) : storage = store - dec -``` -takes a tuple with the current storage on the left and the value to subtract from it on the right. The passed value is subtracted from the current storage and the new storage is returned. - -``` sh -type storage = int - -type parameter = -| Increment of int -| Decrement of int -| Reset - -// Increment entrypoint -let add (store, inc : storage * int) : storage = store + inc -// Decrement entrypoint -let sub (store, dec : storage * int) : storage = store - dec - -let main (action, store : parameter * storage) : operation list * storage = - ([] : operation list), // No operations - (match action with - | Increment (n) -> add (store, n) - | Decrement (n) -> sub (store, n) - | Reset -> 0) - -``` - -## Compile the smart contract to Michelson - -You can now compile the contract to Michelson directly from the terminal with the following command: - -```bash -ligo compile contract increment.mligo -o increment.tz -``` - -You can also test that the contract works by calling one of its entrypoints with this command: - -```bash -ligo run dry-run increment.mligo "Increment(32)" "10" -``` - -This should return `(LIST_EMPTY(), 42)` if everything is correct. - -## Originate to the Testnet - -Run the following command to originate the smart contract: -```bash -octez-client originate contract increment \ - transferring 0 from \ - running increment.tz \ - --init 10 --burn-cap 0.1 --force -``` - -This will originate the contract with an initial storage of `10`. - -You should get a confirmation that your smart contract has been originated: - -```bash -New contract KT1Nnk.................UFsJrq originated. -The operation has only been included 0 blocks ago. -We recommend to wait more. -``` - -Make sure you copy the contract address for the next step! - -## Confirm that all worked as expected - -To interact with the contract and confirm that all went as expected, you can use an Explorer such as: [TzKT](https://tzkt.io) or [Better Call Dev](https://better-call.dev/). - -Make sure you have switched to [Ghostnet](https://ghostnet.tzkt.io) before you start looking. - -Then paste the contract address (starting with KT1) `KT1Nnk.................UFsJrq` into the search field and hit `enter` to find it. - -Then navigate to the `Storage` tab to see your initial value of `10`. - -## Calling the entrypoints - -Now that we've successfully originated our smart contract, let's test out the three entrypoints that we created: `increment`, `decrement`, and `reset`. - -#### Increment - -To increment the current storage by a certain value, you can call the `increment` entrypoint: - -```bash -octez-client --wait none transfer 0 from local_wallet to increment --entrypoint 'increment' --arg '5' --burn-cap 0.1 -``` - -#### Decrement - -To decrement the current storage by a certain value, you can call the `decrement` entrypoint: - -```bash -octez-client --wait none transfer 0 from local_wallet to increment --entrypoint 'decrement' --arg '6' --burn-cap 0.1 -``` - -#### Reset - -Finally, to reset the current storage to zero, you can call the `reset` entrypoint: - -```bash -octez-client --wait none transfer 0 from local_wallet to increment --entrypoint 'reset' --arg 'Unit' --burn-cap 0.1 -``` diff --git a/src/pages/tutorials/originate-your-first-smart-contract/smartpy/index.md b/src/pages/tutorials/originate-your-first-smart-contract/smartpy/index.md deleted file mode 100644 index 3b7574730..000000000 --- a/src/pages/tutorials/originate-your-first-smart-contract/smartpy/index.md +++ /dev/null @@ -1,331 +0,0 @@ ---- -id: first-smart-contract-smartpy -title: Originate your First Smart Contract with SmartPy -authors: 'John Joubert, Sasha Aldrick' -lastUpdated: 7th July 2023 ---- - -{% callout type="note" title="Want to use LIGO?" %} -Click [here](/tutorials/originate-your-first-smart-contract/ligo) to find out how to originate your first smart contract using LIGO. -{% /callout %} - -## Prerequisites - -| Dependency | Installation instructions | -| ------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| SmartPy | Follow the _Installation_ steps in this [guide](https://smartpy.dev/docs/manual/introduction/installation). SmartPy requires Docker to run. For MacOS and Linux, it is recommended to install [Docker Desktop](https://www.docker.com/products/docker-desktop/). | -| _octez-client_ CLI | Follow the _How to install the octez-client_ steps [here](/tezos-basics/get-started-with-octez/). | - -{% callout type="warning" title="Note" %} -Make sure you have **installed** the above CLI tools before getting started. -{% /callout %} - -Now that you have installed the [_octez-client_](https://opentezos.com/tezos-basics/cli-and-rpc/#how-to-install-the-octez-client) and [_Smartpy_](https://smartpy.io/docs/cli/#installation), we'll go ahead and dive right in. - -## Create a project folder - -Now we can go ahead and create a folder somewhere on our local drive with the name of the project. Let's call it `example-smart-contract`. - -```bash -mkdir example-smart-contract -``` - -```bash -cd example-smart-contract -``` - -## Create a project file - -Inside the `example-smart-contract` folder, let's create a file called `store_greeting.py` and save it. We'll need this file later. - -```bash -touch store_greeting.py -``` - -## Confirm your setup - -### Smartpy - -The preferred way of running SmartPy is via the `smartPy` wrapper. To obtain the SmartPy executable within your local project folder: - -```bash -wget smartpy.io/smartpy -chmod a+x smartpy -``` - -If you are missing `wget` on MacOS, you can use `brew install wget` or the package manager of your choice. - -This creates a local executable file named `smartpy` which we will use to to compile our contract. - -We can check that it's correctly installed by running the following command: - -```bash -./smartpy -``` - -And we should see something like this returned: - -``` -./smartpy -Usage: - ./smartpy test