diff --git a/.changeset/sixty-olives-perform.md b/.changeset/sixty-olives-perform.md new file mode 100644 index 0000000000..535d07a8b2 --- /dev/null +++ b/.changeset/sixty-olives-perform.md @@ -0,0 +1,5 @@ +--- +"@kadena/docs": patch +--- + +[docs] Replace 10 minute quick start, update Build home page with text changes. diff --git a/packages/apps/docs/public/assets/docs/hello-world-quickstart/devnet-console.png b/packages/apps/docs/public/assets/docs/hello-world-quickstart/devnet-console.png new file mode 100644 index 0000000000..8e16354f51 Binary files /dev/null and b/packages/apps/docs/public/assets/docs/hello-world-quickstart/devnet-console.png differ diff --git a/packages/apps/docs/public/assets/docs/hello-world-quickstart/hello-everyone.png b/packages/apps/docs/public/assets/docs/hello-world-quickstart/hello-everyone.png new file mode 100644 index 0000000000..5e2460282d Binary files /dev/null and b/packages/apps/docs/public/assets/docs/hello-world-quickstart/hello-everyone.png differ diff --git a/packages/apps/docs/public/assets/docs/hello-world-quickstart/raw-response-hello.png b/packages/apps/docs/public/assets/docs/hello-world-quickstart/raw-response-hello.png new file mode 100644 index 0000000000..76288c54b5 Binary files /dev/null and b/packages/apps/docs/public/assets/docs/hello-world-quickstart/raw-response-hello.png differ diff --git a/packages/apps/docs/public/assets/docs/hello-world-quickstart/request-key.png b/packages/apps/docs/public/assets/docs/hello-world-quickstart/request-key.png new file mode 100644 index 0000000000..f91b276c5f Binary files /dev/null and b/packages/apps/docs/public/assets/docs/hello-world-quickstart/request-key.png differ diff --git a/packages/apps/docs/public/assets/docs/hello-world-quickstart/tx-result.png b/packages/apps/docs/public/assets/docs/hello-world-quickstart/tx-result.png new file mode 100644 index 0000000000..a00eaa6de4 Binary files /dev/null and b/packages/apps/docs/public/assets/docs/hello-world-quickstart/tx-result.png differ diff --git a/packages/apps/docs/public/assets/docs/hello-world-quickstart/updated-two-functions.png b/packages/apps/docs/public/assets/docs/hello-world-quickstart/updated-two-functions.png new file mode 100644 index 0000000000..fe1454d33d Binary files /dev/null and b/packages/apps/docs/public/assets/docs/hello-world-quickstart/updated-two-functions.png differ diff --git a/packages/apps/docs/src/pages/build/index.tsx b/packages/apps/docs/src/pages/build/index.tsx index 5d408ca405..98fb1cda90 100644 --- a/packages/apps/docs/src/pages/build/index.tsx +++ b/packages/apps/docs/src/pages/build/index.tsx @@ -36,20 +36,19 @@ const Home: FC = ({ blogPosts, popularPages }) => { - Getting started tutorial + Get started with tutorials - Getting started is simple. Building useful applications on a - blockchain doesn’t have to be hard or expensive. This Developer - Quickstart is designed to remove the friction from onboarding so - that you can understand how to build with Kadena quickly and - easily. + Building applications to run on a blockchain doesn't have + to be hard, time-consuming, or expensive. Get started with the + basics through hands-on tutorials. Learn how to set up a + development network, create and fund a development wallet, + deploy a smart contract, and more. Take the first step by + clicking Quick start. @@ -67,14 +66,14 @@ const Home: FC = ({ blogPosts, popularPages }) => { - 10 minute quick start + Quick start " --predicate "keys-all" + ``` + + In this command, specify the public key for the account you copied from Chainweaver for the `--keys` command-line option. + If the account key you copied includes the `k:` prefix, remove the prefix from the command-line argument. + The combination of the `keys` and `predicate` create a **keyset** that is used to safeguard your account. + You'll learn more about keysets in other tutorials. + +2. Open the [Kadena Block Explorer](http://localhost:8080/explorer/) to search for the transaction using the account you copied from Chainweaver. + +3. In Chainweaver, click **Refresh** to update the account balance. + +## Deploy a contract + +Now that you have a funded account, you can use that account and public key to deploy a simple `hello world` smart contract—written in the Kadena programming language, Pact—on the development network. +You'll learn more about Pact in other tutorials, but for now, you can deploy a predefined smart contract that looks like this: + +```pact +(namespace 'free) +(module hello-world GOVERNANCE + (defcap GOVERNANCE () true) + (defun say-hello(name:string) + (format "Hello, {}! ~ from: ${publicKey}" [name]) + ) +) +``` + +To deploy the smart contract: + +1. Verify you have Chainweaver open in the browser. + +2. Open a terminal shell on your computer. + +1. Change to the root of the `getting-started` repository, if necessary, by running the following command: + + ```shell + cd getting-started + ``` + +3. Deploy the smart contract from the `getting-started` repository by running a command similar to the following: + + ```shell + npm run start -- deploy --keys "" --predicate "keys-all" --sign-manually + ``` + + In the next steps, you copy and paste information between the terminal and the Chainweaver application. + The instructions for signing the transaction using Chainweaver in the browser are also displayed in the terminal. + +1. In Chainweaver, click **SigBuilder** in the navigation panel. + +2. Copy and paste the transaction information displayed in the terminal into the Signature Builder, then click **Review**. + +3. Verify that the hash matches the hash displayed in the terminal to ensure you're signing the transaction you expect to sign, then click **Details**. + +4. Scroll to locate the **Signers** section of the transaction and verify that your public key is listed, then click **Sign**. + +5. Copy the full Command JSON and paste it into the terminal, then click **Done** in Chainweaver to close the Signature Builder. + + After you enter the command in the terminal, you'll see that the terminal displays information about the transaction including a `requestKey`. + You can copy this `requestKey` from the terminal to view information about the transaction in the [Kadena block explorer](http://localhost:8080/explorer). + +To verify the "Hello, World!" contract deployment in the block explorer: + +1. Open the [Kadena block explorer](http://localhost:8080/explorer). + +2. Select **Request Key** as the information you want to search for. + + ![Select Request Key to search for your transaction](/assets/docs/hello-world-quickstart/request-key.png) + +3. Paste the `requestKey` from the terminal, then click **Search** to see transaction results similar to the following: + + ![Deployed smart contract](/assets/docs/hello-world-quickstart/tx-result.png) + +## View the smart contract + +After you deploy the `hello-world` smart contract, you can view and interact with it on the development network using Chainweaver. + +To view the `hello-world` smart contract: + +1. In Chainweaver, click **Contracts** in the navigation panel. + + After you click Contracts, Chainweaver displays two working areas. + The left side displays a sample contract in an editor that you can use to view and edit contract code and execute commands interactively. + The right side provides controls that enable you to navigate between contracts, view contract details, and test operations for contracts you have deployed. + +2. On the right side of Contracts, click **Module Explorer**. + +3. Under Deployed Contracts, search for the `hello-world` contract. + +4. Click **View** to display details about the smart contract. + For example, you can see that this contract has one function—`say-hello`—defined. + +## Execute a read-only command + +On the left side of the Contracts tab, you can write commands you want to execute on the blockchain. +Most commands require you to pay a transaction fee because they change the state of the information stored in the blockchain. +However, you can also write commands that only **read** information from the blockchain. +Read-only commands don't require transaction fees. + +To execute a command using the `hello-world` contract: + +1. In the left side under Contracts, remove the sample contract displayed, then type the following command: + + ```pact + (free.hello-world.say-hello "World") + ``` + +2. Click **Deploy** to display the transaction details, then click **Next**. + +3. Review the signing information, but leave the Signing Key empty because you're executing a read-only command, then click **Next**. + + After you click Next, You'll see an error message that "A 'Gas Payer' has not been selected for this transaction. Are you sure this is correct?" + You can ignore this message because you're executing a read-only command. + +4. Scroll to see the Raw Response: + + ![Deployed "Hello, World!" smart contract](/assets/docs/hello-world-quickstart/raw-response-hello.png) + +## Write to the blockchain + +You've actually already written to the blockchain by deploying your `hello-world` smart contract. +You changed the **state** of the blockchain from not having the `hello-world` contract to having the `hello-world` contract included in a specific block. +However, that state change transaction didn't take place from within the context of the smart contract itself. +No contract logic was executed in the transaction. + +To illustrate how you can change the state of information stored on the blockchain using the logic in a smart contract, you first need to modify the code in the `hello-world` smart contract. +The modified version of the smart contract looks like this: + +```pact +(namespace 'free) +(module hello-world G + (defcap G () true) + + (defschema hello-world-schema + @doc "The schema for hello world" + + text:string) + + (deftable hello-world-table:{hello-world-schema}) + + (defun say-hello(name:string) + (format "Hello, {}!" [name])) + + (defun write-hello(name:string) + (write hello-world-table name + { "text": (say-hello name) })) + +) + +(create-table hello-world-table) +``` + +### Review contract changes + +Before moving on, let's take a closer look at what's changed in the sample `hello-world` contract. + +The updated `hello-world` contract creates a simple schema of what you want deployed on the blockchain. +This schema assigns a value to each key when you execute the `(write { })` command. +Anything between the curly braces (`{ }`) must comply with the schema. + +The schema for this contract is defined in the following lines: + +```pact +(defschema hello-world-schema + @doc "The schema for hello world" + + text:string) +``` + +The updated contract also includes a function that allows you to write to the schema in the following lines: + +```pact +(defun write-hello(name:string) + (write hello-world-table name + { "text": (say-hello name) })) +``` + +### Deploy the modified contract + +After making these changes, you need to redeploy the modified contract. + +To deploy the modified `hello-world` smart contract: + +1. Verify you have Chainweaver open in the browser. + +2. Open a terminal shell on your computer. + +1. Change to the root of the `getting-started` repository, if necessary, by running the following command: + + ```shell + cd getting-started + ``` + +3. Deploy the updated smart contract from the `getting-started` repository by running a command similar to the following: + + ```shell + npm run start -- deploy \ + --keys "" \ + --predicate keys-all \ + --file ./src/pact/hello-world.pact + --sign-manually + ``` + + If the account key includes the `k:` prefix, remove the prefix from the command-line argument. + + As you saw in the previous deployment, you'll copy and paste information between the terminal and the Chainweaver application. + The instructions for signing the transaction using Chainweaver in the browser are also displayed in the terminal. + + - Copy the command displayed in the terminal into the Signature Builder, then click **Review**. + - Verify the information displayed is correct, then click **Sign**. + - Copy the JSON from Signature Builder and paste it into the terminal. + - Copy the `requestKey` from the terminal. + - Open the Kadena block explorer, select Request Key, paste the `requestKey` from the terminal, then click **Search**. + + For the updated `hello-world` contract, you'll see the transaction result is **TableCreated**. + +### View the modified contract + +After you deploy the updated `hello-world` smart contract, you can view and interact with it using Chainweaver. + +To view the `hello-world` smart contract: + +1. In Chainweaver, click **Contracts** in the navigation panel. + +2. Click **Module Explorer**. + +3. Under Deployed Contracts, search for the `hello-world` contract. + +4. Click **View** and note that the new contract has two new functions—`say-hello` and `write-hello`. + + ![Updated "Hello, World!" smart contract](/assets/docs/hello-world-quickstart/updated-two-functions.png) + + The `say-hello` function reads from the table and the `write-hello` function writes to the table. + +### Execute a write function + +1. Click **Contracts** in the Chainweaver navigation panel. + +2. In the editor, type the following code: + + ```pact + (free.hello-world.write-hello "Everyone") + ``` + +3. Click **Deploy**. + +4. In the Configuration section of the Transaction Details: + + - Under Destination, select Chain ID **0**. + - Under Transaction Sender, select account with the public key that matches the account that you funded. + The account format uses a `k:` followed by the public key for your account. + - Use the default settings for the remaining fields. + +5. Click **Next**. + +6. Under Unrestricted Signing Keys, check the public key of your account, then click **Next**. + + After you click Next, the transaction Preview displays a notice that a Gas Payer has not been selected for the transaction. + You can ignore this notice because you have set the unrestricted signer for this transaction to use your public key. + +7. Click **Submit**. + +8. Wait for the transaction result **Successful Server result: "Write succeeded"**, then click **Done**. + +### Read from the table + +Now that you have written to the table, you can read from the table. + +**Note:** This function call is expensive because it isn't something you'd do in a typical transaction. + +1. In the editor, type the following code: + + ```pact + (map (read free.hello-world.hello-world-table) (keys free.hello-world.hello-world-table)) + ``` + +2. Click **Deploy**. + +3. Select the Chain ID **0** because the contract was deployed on Chain 0. + +4. Set the **Gas Limit Units** to `99999`. + +5. Click **Next** to display the transaction signing fields, then click **Next** again. + +6. Check the Raw Response and verify that you see the following: + + ![Updated "Hello, World!" smart contract](/assets/docs/hello-world-quickstart/hello-everyone.png) + +## Reset the development network + +If you want to run through this tutorial more than once, keep in mind that after you deploy a contract it remains on the network. +If you want to experiment with writing and deploying contracts, you should periodically reset the development network to a clean state to avoid errors. +To shut down the development network, you can run the following command: + +```docker +docker stop devnet +``` + +To completely remove the development network from your local computer, you can run commands similar to the following: + +```docker +docker stop +docker rm +docker volume rm kadena_devnet +``` + +## Next steps + +In this tutorial, you learned a little about a lot of topics. +For example, you learned some basic terminology for building on the Kadena blockchain. +You also had some hands-on experience with the following tasks: + +- Setting up a local development network. +- Creating a wallet account with a public and secret key. +- Funding your account with coins from a predefined account application. +- Deploying a simple smart contract. +- Using Chainweaver and the Kadena block explorer to interact with the blockchain and view information about transactions. +- Executing the write and read functions from a smart contract on the blockchain. + +The most important next step from here is to start learning how to write your own smart contracts using the Pact programming language. +The following are the best resources for learning Pact: + +- [Welcome to Pact](https://docs.kadena.io/learn-pact/beginner/welcome-to-pact). +- [Real World Pact](https://github.com/thomashoneyman/real-world-pact#real-world-pact) tutorial series by Thomas Honeyman. +- [Language Reference](https://docs.kadena.io/pact/reference).