From e876b1ad461d44ceafc29f27c9f2de12e67cf12d Mon Sep 17 00:00:00 2001 From: Jessie Mongeon Date: Wed, 18 Dec 2024 16:02:09 -0600 Subject: [PATCH] Update Motoko project READMEs --- archive/motoko/persistent-storage/README.md | 3 +- motoko/basic_bitcoin/README.md | 26 ++--- motoko/basic_dao/README.md | 27 ++--- motoko/canister_logs/README.md | 64 +++++------ motoko/cert-var/README.md | 36 +++--- motoko/classes/README.md | 25 ++-- motoko/composite_query/README.md | 39 +++---- motoko/counter/README.md | 23 ++-- motoko/encrypted-notes-dapp-vetkd/README.md | 64 +++++------ motoko/encrypted-notes-dapp/README.md | 47 ++++---- motoko/hello_cycles/README.md | 33 +++--- motoko/ic-pos/README.md | 50 ++++---- motoko/icrc2-swap/README.md | 56 ++++----- .../internet_identity_integration/README.md | 47 ++++---- motoko/life/README.md | 22 ++-- motoko/minimal-counter-dapp/README.md | 27 ++--- motoko/parallel_calls/README.md | 30 ++--- motoko/pub-sub/README.md | 22 ++-- motoko/random_maze/README.md | 20 ++-- motoko/send_http_get/README.md | 18 --- motoko/send_http_post/README.md | 18 --- motoko/superheroes/README.md | 26 ++--- motoko/threshold-ecdsa/README.md | 55 ++++----- motoko/threshold-schnorr/README.md | 40 +++---- motoko/token_transfer/README.md | 88 +++++--------- motoko/token_transfer_from/README.md | 108 ++++++++---------- motoko/vetkd/README.md | 41 +++---- motoko/whoami/README.md | 25 ++-- 28 files changed, 429 insertions(+), 651 deletions(-) diff --git a/archive/motoko/persistent-storage/README.md b/archive/motoko/persistent-storage/README.md index a56e2b4ee..5ba84e19f 100644 --- a/archive/motoko/persistent-storage/README.md +++ b/archive/motoko/persistent-storage/README.md @@ -33,7 +33,8 @@ This example requires an installation of: Begin by opening a terminal window. -### Step 1: Navigate into the folder containing the project's files and start a local instance of the Internet Computer with the command: +### Step 1: Navigate into the folder containing the project's files and start a local instance of the Internet Computer with the commands: + ```bash cd examples/motoko/persistent-storage diff --git a/motoko/basic_bitcoin/README.md b/motoko/basic_bitcoin/README.md index f1857f9d9..5896c1da6 100644 --- a/motoko/basic_bitcoin/README.md +++ b/motoko/basic_bitcoin/README.md @@ -1,12 +1,5 @@ ---- -keywords: [advanced, motoko, bitcoin, bitcoin integration, btc] ---- - # Basic Bitcoin -[View this sample's code on GitHub](https://github.com/dfinity/examples/tree/master/motoko/basic_bitcoin) - -## Overview This tutorial will walk you through how to deploy a sample [canister smart contract](https://wiki.internetcomputer.org/wiki/Canister_smart_contract) **that can send and receive Bitcoin** on the Internet Computer. ## Architecture @@ -21,22 +14,23 @@ For a deeper understanding of the ICP < > BTC integration, see the [Bitcoin inte ## Prerequisites -* [x] Install the [IC - SDK](https://internetcomputer.org/docs/current/developer-docs/setup/install/index.mdx). For local testing, `dfx >= 0.22.0` is required. +- [x] Install the [IC + SDK](https://internetcomputer.org/docs/current/developer-docs/getting-started/install). For local testing, `dfx >= 0.22.0` is required. +- [x] Clone the example dapp project: `git clone https://github.com/dfinity/examples` + +> [!WARNING] +> This example is designed to be deployed on the mainnet. It will return errors when deployed locally; these errors are expected. -:::info -This example is designed to be deployed on the mainnet. It will return errors when deployed locally; these errors are expected. -::: +Begin by opening a terminal window. -## Step 1: Building and deploying sample code +## Step 1: Setup the project environment -### Clone the smart contract +Navigate into the folder containing the project's files and start a local instance of the Internet Computer with the commands: -To clone and build the smart contract in **Motoko**: ```bash -git clone https://github.com/dfinity/examples cd examples/motoko/basic_bitcoin +dfx start --background ``` ### Install MOPS diff --git a/motoko/basic_dao/README.md b/motoko/basic_dao/README.md index 0941966f2..01cc7ad80 100644 --- a/motoko/basic_dao/README.md +++ b/motoko/basic_dao/README.md @@ -1,15 +1,7 @@ ---- -keywords: [advanced, motoko, dao, decentralized organization, decentralized org] ---- - # Basic DAO -[View this sample's code on GitHub](https://github.com/dfinity/examples/tree/master/motoko/basic_dao) - This sample project demonstrates a basic [decentralized autonomous organization](https://en.wikipedia.org/wiki/Decentralized_autonomous_organization) (DAO) that can be deployed to the [Internet Computer](https://github.com/dfinity/ic). The basic DAO sample code is available in [Motoko](https://github.com/dfinity/examples/tree/master/motoko/basic_dao) and [Rust](https://github.com/dfinity/examples/tree/master/rust/basic_dao). You can see a quick introduction on [YouTube](https://youtu.be/3IcYlieA-EE). -## Overview - A `basic_dao` can be initialized with a set of accounts: mappings from principal IDs to a number of tokens. Account owners can query their account balance by calling `account_balance` and transfer tokens to other accounts by calling `transfer`. Anyone can call `list_accounts` to view all accounts. Account owners can submit proposals by calling `submit_proposal`. A proposal specifies a canister, method, and arguments for this method. Account owners can cast votes (either `Yes` or `No`) on a proposal by calling `vote`. The amount of votes cast is equal to the amount of tokens the account owner has. If enough `Yes` votes are cast, `basic_dao` will execute the proposal by calling the proposal’s given method with the given args against the given canister. If enough `No` votes are cast, the proposal is not executed, and is instead marked as `Rejected`. @@ -19,30 +11,35 @@ This workflow is demonstrated below. View the [canister service definition](https://github.com/dfinity/examples/blob/master/rust/basic_dao/src/basic_dao/src/basic_dao.did) for more details. -### Prerequisites -This example requires an installation of: +## Prerequisites -- [x] Install the [IC SDK](https://internetcomputer.org/docs/current/developer-docs/setup/install/). +- [x] Install the [IC + SDK](https://internetcomputer.org/docs/current/developer-docs/getting-started/install). For local testing, `dfx >= 0.22.0` is required. - [x] To run the test scripts, you need to download [ic-repl](https://github.com/chenyan2002/ic-repl/releases). - [x] Clone the example dapp project: `git clone https://github.com/dfinity/examples` Begin by opening a terminal window. - ### Step 1: Navigate into the folder containing the project's files and start a local instance of the Internet Computer with the command: +## Step 1: Setup the project environment + +Navigate into the folder containing the project's files and start a local instance of the Internet Computer with the commands: + ```bash cd examples/motoko/basic_dao dfx start --background ``` - ### Step 2: Create test identities with the commands: +## Step 2: Create identities + +Create test identities with the commands: ```bash dfx identity new Alice --disable-encryption; dfx identity use Alice; export ALICE=$(dfx identity get-principal); dfx identity new Bob --disable-encryption; dfx identity use Bob; export BOB=$(dfx identity get-principal); ``` - ### Step 3: Deploy `basic_dao` with initial test accounts. +## Step 3: Deploy `basic_dao` with initial test accounts ```bash dfx deploy --argument "(record { @@ -57,7 +54,7 @@ dfx deploy --argument "(record { })" ``` - ### Step 4: Run the ic-repl test scripts: +## Step 4: Run the `ic-repl` test scripts: ```bash ic-repl tests/account.test.sh diff --git a/motoko/canister_logs/README.md b/motoko/canister_logs/README.md index ad69e31b5..32e3da531 100644 --- a/motoko/canister_logs/README.md +++ b/motoko/canister_logs/README.md @@ -1,66 +1,64 @@ ---- -keywords: [beginner, motoko, canister logs, logging] ---- - # Canister logs -[View this sample's code on GitHub](https://github.com/dfinity/examples/tree/master/motoko/canister_logs) - ## Prerequisites -This example requires an installation of: -- [x] DFX version 0.19.0 or newer -- [x] Install the [IC SDK](https://internetcomputer.org/docs/current/developer-docs/setup/install/). -- [x] Download the following project files from GitHub: `git clone https://github.com/dfinity/examples/` +- [x] Install the [IC + SDK](https://internetcomputer.org/docs/current/developer-docs/getting-started/install). For local testing, `dfx >= 0.22.0` is required. +- [x] Clone the example dapp project: `git clone https://github.com/dfinity/examples` -You will need to have 3 terminal windows: -- Terminal A: Running a DFX instance and separating its output from anything else -- Terminal B: Deploying a canister and seeing its output -- Terminal C: Reading logs interactively +## Step 1: Setup project environment + +Navigate into the folder containing the project's files and start a local instance of the replica with the command: -### Step 1: Navigate into the folder containing the project's files and start a local instance of the replica with the command: +```shell +dfx start --clean +``` + +You will need to have 3 terminal windows: +- Terminal A: Running a `dfx` instance and separating its output from anything else. +- Terminal B: Deploying a canister and seeing its output. +- Terminal C: Reading logs interactively. ```shell # Terminal A -- for running DFX and separating its output from anything else. -$ cd examples/motoko/canister_logs -$ dfx start --clean +cd examples/motoko/canister_logs # Terminal B -- for deploying the canister and calling its methods. -$ cd examples/motoko/canister_logs +cd examples/motoko/canister_logs # Terminal C -- for polling logs. -$ cd examples/motoko/canister_logs +cd examples/motoko/canister_logs ``` -### Step 2: Deploy the canister: +## Step 2: Deploy the canister ```shell # Terminal B -$ dfx deploy +dfx deploy ``` -### Step 3: Check canister logs: +## Step 3: Check canister logs Expect to see logs from timer traps. ```shell # Terminal B -$ dfx canister logs CanisterLogs +dfx canister logs CanisterLogs [0. 2024-05-23T08:32:26.203980235Z]: right before timer trap [1. 2024-05-23T08:32:26.203980235Z]: [TRAP]: timer trap [2. 2024-05-23T08:32:31.836721763Z]: right before timer trap [3. 2024-05-23T08:32:31.836721763Z]: [TRAP]: timer trap ``` -### Step 4: Call `print` method and check the logs: +## Step 4: Call `print` method and check the logs ```shell # Terminal B -$ dfx canister call CanisterLogs print hi +dfx canister call CanisterLogs print hi () # Expect to see new log entry. -$ dfx canister logs CanisterLogs +dfx canister logs CanisterLogs ... [8. 2024-05-23T08:32:46.598972616Z]: right before timer trap [9. 2024-05-23T08:32:46.598972616Z]: [TRAP]: timer trap @@ -70,7 +68,7 @@ $ dfx canister logs CanisterLogs ... ``` -### Step 5: Start constantly polling logs: +## Step 5: Start constantly polling logs In order not to call `dfx canister logs CanisterLogs` after every canister call in a separate terminal window/pane C start a script that will constantly poll logs: @@ -86,25 +84,25 @@ $ ./poll_logs.sh ... ``` -### Step 6: Call `print`, `trap` and other canister methods: +## Step 6: Call `print`, `trap` and other canister methods ```shell # Terminal B -$ dfx canister call CanisterLogs print hi! +dfx canister call CanisterLogs print hi! () -$ dfx canister call CanisterLogs print hello! +dfx canister call CanisterLogs print hello! () -$ dfx canister call CanisterLogs print yey! +dfx canister call CanisterLogs print yey! () -$ dfx canister call CanisterLogs trap oops! +dfx canister call CanisterLogs trap oops! Error: Failed update call. Caused by: Failed update call. The replica returned a rejection error: reject code CanisterError, reject message Canister bkyz2-fmaaa-aaaaa-qaaaq-cai trapped explicitly: oops!, error code None -$ dfx canister call CanisterLogs memory_oob +dfx canister call CanisterLogs memory_oob Error: Failed update call. Caused by: Failed update call. The replica returned a rejection error: reject code CanisterError, reject message Canister bkyz2-fmaaa-aaaaa-qaaaq-cai trapped explicitly: StableMemory range out of bounds, error code None diff --git a/motoko/cert-var/README.md b/motoko/cert-var/README.md index a0db5f6a8..b0d985766 100644 --- a/motoko/cert-var/README.md +++ b/motoko/cert-var/README.md @@ -1,12 +1,5 @@ ---- -keywords: [intermediate, motoko, cert var, certified variables] ---- - # Certified variables -[View this sample's code on GitHub](https://github.com/dfinity/examples/tree/master/motoko/cert-var) - -## Overview This example demonstrates the use of a single cryptographically certified variable, as supported by the Internet Computer. In a nutshell, this example code demonstrates "response certification" for a canister that holds a single 32-bit variable. It has two sides: @@ -49,32 +42,39 @@ This is a Motoko example that does not currently have a Rust variant. ## Prerequisites This example requires an installation of: -- [x] Install the [IC SDK](https://internetcomputer.org/docs/current/developer-docs/setup/install/index.mdx). -- [x] Download [npm](https://nodejs.org/en/download/). +## Prerequisites + +- [x] Install the [IC + SDK](https://internetcomputer.org/docs/current/developer-docs/getting-started/install). For local testing, `dfx >= 0.22.0` is required. - [x] Clone the example dapp project: `git clone https://github.com/dfinity/examples` Begin by opening a terminal window. -### Step 1: Navigate into the folder containing the project's files and start a local instance of the Internet Computer with the command: +## Step 1: Setup the project environment + +Navigate into the folder containing the project's files and start a local instance of the Internet Computer with the commands: + ```bash cd examples/motoko/cert-var dfx start --background ``` -### Step 2: Install the front-end dependencies: +## Step 2: Install the front-end dependencies ```bash npm install ``` -### Step 3: Deploy the canister: +## Step 3: Deploy the canister ```bash dfx deploy ``` -### Step 4: Next, open the `webpack.config.js` file and replace the contents with the following: +## Step 4: Next, open the `webpack.config.js` file. + +Replace the contents with the following: ```javascript const path = require("path"); @@ -188,7 +188,9 @@ module.exports = { }; ``` -### Step 5: Create a new file called `server.js` with the following content: +## Step 5: Create a new file called `server.js`. + +Add the following content: ```javascript var express = require('express'); @@ -203,7 +205,7 @@ app.listen(8000, function () { }); ``` -### Step 6: Replace the content of the `src/cert_var_assets/src/index.html` with the following content: +## Step 6: Replace the content of the `src/cert_var_assets/src/index.html` with the following: ```html @@ -230,14 +232,14 @@ app.listen(8000, function () { ``` -### Step 7: Start a local web server that hosts the frontend. +## Step 7: Start a local web server that hosts the frontend ```bash npm start ``` -### Step 8: Visit the frontend, and interact with the demo there: +## Step 8: Visit the frontend, and interact with application ```bash http://localhost:8080/ diff --git a/motoko/classes/README.md b/motoko/classes/README.md index 8f3f8d14c..0d3f70416 100644 --- a/motoko/classes/README.md +++ b/motoko/classes/README.md @@ -1,13 +1,5 @@ ---- -keywords: [beginner, motoko, classes, actor classes] ---- - # Classes -[View this sample's code on GitHub](https://github.com/dfinity/examples/tree/master/motoko/classes) - -## Overview - This example demonstrates a simple use of actor classes, allowing a program to dynamically install new actors (that is, canisters). It also demonstrates a multi-canister project, and actors using inter-actor communication through shared functions. The example defines two Motoko actors, `Map` and `Test`. @@ -26,29 +18,32 @@ The `Test.mo` actor imports the (installed) `Map` canister, using `Maps` Candid This is a Motoko example that does not currently have a Rust variant. - ## Prerequisites -This example requires an installation of: -- [x] Install the [IC SDK](https://internetcomputer.org/docs/current/developer-docs/setup/install/). +- [x] Install the [IC + SDK](https://internetcomputer.org/docs/current/developer-docs/getting-started/install). For local testing, `dfx >= 0.22.0` is required. - [x] Clone the example dapp project: `git clone https://github.com/dfinity/examples` Begin by opening a terminal window. -### Step 1: Navigate into the folder containing the project's files and start a local instance of the Internet Computer with the command: +## Step 1: Setup the project environment + +Navigate into the folder containing the project's files and start a local instance of the Internet Computer with the commands: + ```bash cd examples/motoko/classes dfx start --background ``` -### Step 2: Deploy the canisters `Map` and `Test`: +## Step 2: Deploy the canisters `Map` and `Test` ```bash -dfx deploy +dfx deploy Map +dfx deploy Test ``` -### Step 3: Invoke the run method of canister Test: +## Step 3: Invoke the run method of canister `Test` ```bash dfx canister call Test run '()' diff --git a/motoko/composite_query/README.md b/motoko/composite_query/README.md index 4b5b69601..025a12da7 100644 --- a/motoko/composite_query/README.md +++ b/motoko/composite_query/README.md @@ -1,13 +1,5 @@ ---- -keywords: [beginner, motoko, composite queries, queries] ---- - # Composite queries -[View this sample's code on GitHub](https://github.com/dfinity/examples/tree/master/motoko/composite_query) - -## Overview - This example modifies the simple actor class example to demonstrate the implementation of composite queries. The original example demonstrates a simple use of actor classes, allowing a program to dynamically install new actors (that is, canisters). It also demonstrates a multi-canister project, and actors using inter-actor communication through `shared` functions. @@ -37,38 +29,35 @@ Each new `Bucket` must be provisioned with enough cycles to pay for its installa ## Prerequisites -Verify the following before running this demo: +- [x] Install the [IC + SDK](https://internetcomputer.org/docs/current/developer-docs/getting-started/install). For local testing, `dfx >= 0.22.0` is required. +- [x] Clone the example dapp project: `git clone https://github.com/dfinity/examples` -- [x] You have downloaded and installed [dfx](https://sdk.dfinity.org). +Begin by opening a terminal window. -- [x] You have stopped any process that would create a port conflict on `8000`. +## Step 1: Setup the project environment -- [x] Clone the example dapp project: `git clone https://github.com/dfinity/examples` +Navigate into the folder containing the project's files and start a local instance of the Internet Computer with the commands: -## Install - -### Step 1: Start a local internet computer. ```bash -dfx start +cd examples/motoko/composite_query +dfx start --background ``` -### Step 2: Open a new terminal window. - -### Step 3: Deploy the `Map` canister: +## Step 2: Deploy the `Map` canister ```bash -cd examples/motoko/composite_query -dfx deploy +dfx deploy Map ``` -### Step 4: Invoke the `test` method of canister `Map` to add some entries: +## Step 3: Invoke the `test` method of canister `Map` to add some entries ```bash dfx canister call Map test '()' ``` -### Step 5: Observe the following result. +## Step 4: Observe the following result ```bash debug.print: putting: (0, "0") @@ -90,13 +79,13 @@ debug.print: putting: (15, "15") () ``` -### Step 6: Invoke the `get` composite query method of canister `Main`: +## Step 5: Invoke the `get` composite query method of canister `Main` ```bash dfx canister call --query Map get '(15)' ``` -### Step 7: Observe the following result: +### Step 6: Observe the result ```bash (opt "15") diff --git a/motoko/counter/README.md b/motoko/counter/README.md index a48fb5a34..3982192df 100644 --- a/motoko/counter/README.md +++ b/motoko/counter/README.md @@ -1,13 +1,5 @@ ---- -keywords: [beginner, motoko, counter, count] ---- - # Counter -[View this sample's code on GitHub](https://github.com/dfinity/examples/tree/master/motoko/counter) - -## Overview - This example demonstrates a counter application. It uses an orthogonally persistent counter variable to store an arbitrary precision natural number that represents the current value of the counter. By using the Motoko keyword stable when declaring the counter variable, the value of this variable will automatically be preserved whenever your canister code is upgraded. Without the stable keyword, a variable is deemed flexible, and its value is reinitialized on every canister upgrade, i.e. whenever new code is deployed to the canister. @@ -26,32 +18,35 @@ This example requires an installation of: Begin by opening a terminal window. - ### Step 1: Navigate into the folder containing the project's files and start a local instance of the Internet Computer with the command: +## Step 1: Setup the project environment + +Navigate into the folder containing the project's files and start a local instance of the Internet Computer with the commands: + ```bash cd examples/motoko/counter dfx start --background ``` - ### Step 2: Deploy the canister: +## Step 2: Deploy the canister ```bash dfx deploy ``` - ### Step 3: Set the value of the counter: + ## Step 3: Set the value of the counter ```bash dfx canister call counter set '(7)' ``` - ### Step 4: Increment the value of the counter: +## Step 4: Increment the value of the counter ```bash dfx canister call counter inc ``` - ### Step 5: Get the value of the counter: +## Step 5: Get the value of the counter ```bash dfx canister call counter get @@ -63,7 +58,7 @@ The following output should be returned: (8 : nat) ``` -### Resources +## Resources To learn more about these features of Motoko, see: - [Orthogonal persistence](https://internetcomputer.org/docs/current/motoko/main/motoko#orthogonal-persistence). diff --git a/motoko/encrypted-notes-dapp-vetkd/README.md b/motoko/encrypted-notes-dapp-vetkd/README.md index cbfc0429a..1c2ecec80 100644 --- a/motoko/encrypted-notes-dapp-vetkd/README.md +++ b/motoko/encrypted-notes-dapp-vetkd/README.md @@ -1,11 +1,5 @@ ---- -keywords: [advanced, motoko, encrypted, encrypted notes, notes dapp, vetkeys, vetkd] ---- - # Encrypted notes: vetKD -[View this sample's code on GitHub](https://github.com/dfinity/examples/tree/master/motoko/encrypted-notes-dapp-vetkd) - This is a copy of the `encrypted-notes-dapp` example, adapted to use [the proposed vetKD feature](https://github.com/dfinity/interface-spec/pull/158) and add sharing of notes between users. In particular, instead of creating a principal-specific AES key and syncing it across devices (using device-specific RSA keys), the notes are encrypted with an AES key that is derived (directly in the browser) from a note-ID-specific vetKey obtained from the backend canister (in encrypted form, using an ephemeral transport key), which itself obtains it from the vetKD system API. This way, there is no need for any device management in the dapp, plus sharing of notes becomes possible. @@ -24,9 +18,12 @@ This example uses an **insecure** implementation of [the proposed vetKD system A ### Prerequisites +This example requires an installation of: + +- [x] Install the [IC SDK](https://internetcomputer.org/docs/current/developer-docs/setup/install/index.mdx). - [x] Clone the example dapp project: `git clone https://github.com/dfinity/examples` -### Step 1: Choose which implementation to use by setting a respective environment variable. +## Step 1: Choose which implementation to use by setting a respective environment variable. For **Motoko** deployment use: @@ -34,44 +31,34 @@ For **Motoko** deployment use: export BUILD_ENV=motoko ``` -### Step 2: To generate `$BUILD_ENV`-specific files run: +## Step 2: To generate `$BUILD_ENV`-specific files run: ```sh sh ./pre_deploy.sh ``` -### Step 3: [Install dfx](https://sdk.dfinity.org/docs/quickstart/local-quickstart.html). - -Please keep in mind the `dfx` CLI currently only runs on Linux and macOS. - -### Step 4: Install npm packages from the project root: +## Step 3: Install npm packages from the project root: ```sh npm install ``` _Note_: see [Troubleshooting](#troubleshooting) in case of problems. -### Step 5: In case `dfx` was already started before, run the following: +## Step 4: Run in a separate window: ```sh -dfx stop -rm -rf .dfx +dfx start --clean ``` -### Step 6: Run in a separate window: +> ![TIP] +> If you see an error `Failed to set socket of tcp builder to 0.0.0.0:8000`, make sure that the port `8000` is not occupied, e.g., by the previously run Docker command (you might want to stop the Docker daemon whatsoever for this step). -```sh -dfx start --clean -``` -:::info -If you see an error `Failed to set socket of tcp builder to 0.0.0.0:8000`, make sure that the port `8000` is not occupied, e.g., by the previously run Docker command (you might want to stop the Docker daemon whatsoever for this step). -::: -### Step 7: Install a local [Internet Identity (II)](https://wiki.internetcomputer.org/wiki/What_is_Internet_Identity) canister: +## Step 5: Install a local [Internet Identity (II)](https://wiki.internetcomputer.org/wiki/What_is_Internet_Identity) canister: + +> ![TIP] +> If you have multiple `dfx` identities set up, ensure you are using the identity you intend to use with the `--identity` flag. -:::info -If you have multiple `dfx` identities set up, ensure you are using the identity you intend to use with the `--identity` flag. -::: 1. To install and deploy a canister run: ```sh cd examples/motoko/encrypted-notes-dapp-vetkd @@ -83,7 +70,7 @@ If you have multiple `dfx` identities set up, ensure you are using the identity ``` 3. Visit the URL from above and create at least one local internet identity. -### Step 8: Install the vetKD system API canister: +## Step 6: Install the vetKD system API canister: 1. Ensure the Canister SDK (dfx) uses the canister ID that is hard-coded in the backend canister Rust source code: ```sh dfx canister create vetkd_system_api --specified-id s55qq-oqaaa-aaaaa-aaakq-cai @@ -93,27 +80,30 @@ If you have multiple `dfx` identities set up, ensure you are using the identity dfx deploy vetkd_system_api ``` -### Step 9:. Deploy the encrypted notes backend canister: +## Step 7: Deploy the encrypted notes backend canister: ```sh dfx deploy "encrypted_notes_$BUILD_ENV" ``` -⚠️ Before deploying the Rust canister, you should first run `rustup target add wasm32-unknown-unknown`. -### Step 10: Update the generated canister interface bindings: +> [!WARNING] +> Before deploying the Rust canister, you should first run `rustup target add wasm32-unknown-unknown`. + +## Step 8: Update the generated canister interface bindings: ```sh dfx generate "encrypted_notes_$BUILD_ENV" ``` -### Step 11: Deploy the frontend canister: +## Step 9: Deploy the frontend canister: + ```sh dfx deploy www ``` -You can check its URL with `npm run print-dfx-www`. +You can check its URL with `npm run print-dfx-www`. -### Step 11: Open the frontend: +### Step 10: Open the frontend: 1. Start the local development server, which also supports hot-reloading: ```sh @@ -121,9 +111,9 @@ You can check its URL with `npm run print-dfx-www`. ``` 2. Open the URL that is printed in the console output. Usually, this is [http://localhost:3000/](http://localhost:3000/). -:::info -If you have opened this page previously, please remove all local store data for this page from your web browser, and hard-reload the page. For example in Chrome, go to Inspect → Application → Local Storage → `http://localhost:3000/` → Clear All, and then reload. -::: +> [!TIP] +> If you have opened this page previously, please remove all local store data for this page from your web browser, and hard-reload the page. For example in Chrome, go to Inspect → Application → Local Storage → `http://localhost:3000/` → Clear All, and then reload. + ## Troubleshooting diff --git a/motoko/encrypted-notes-dapp/README.md b/motoko/encrypted-notes-dapp/README.md index b59aee1b8..39340faea 100644 --- a/motoko/encrypted-notes-dapp/README.md +++ b/motoko/encrypted-notes-dapp/README.md @@ -1,11 +1,5 @@ ---- -keywords: [advanced, motoko, encrypted notes, encrypted, notes dapp] ---- - # Encrypted notes -[View this sample's code on GitHub](https://github.com/dfinity/examples/tree/master/motoko/encrypted-notes-dapp) - Encrypted notes is an example dapp for authoring and storing confidential information on the Internet Computer (ICP) in the form of short pieces of text. Users can create and access their notes via any number of automatically synchronized devices authenticated via [Internet Identity (II)](https://wiki.internetcomputer.org/wiki/What_is_Internet_Identity). Notes are stored confidentially thanks to the end-to-end encryption performed by the dapp’s frontend. This project serves as a simple (but not too simple) example of a dapp, which uses Motoko and Rust as backend and Svelte as frontend. @@ -33,8 +27,6 @@ This is an **example dapp** that demonstrates the potential of building **canist ---   -## Overview - You can play around with the [dapp deployed on ICP](https://cvhrw-2yaaa-aaaaj-aaiqa-cai.icp0.io/) and see a quick introduction on [YouTube](https://youtu.be/DZQmtPSxvbs). We wanted to build an example of a simple (but not too simple) dapp running purely on the IC. This example relies upon the **web-serving** and **storage capabilities** of the IC. We focused on the following two key features for our example dapp: @@ -108,12 +100,15 @@ Once authenticated with II: Follow the steps below to deploy this sample project. -## Prerequisites -- [x] Install the [IC SDK](https://internetcomputer.org/docs/current/developer-docs/setup/install/index). +### Prerequisites +This example requires an installation of: + +- [x] Install the [IC SDK](https://internetcomputer.org/docs/current/developer-docs/setup/install/index.mdx). +- [x] Clone the example dapp project: `git clone https://github.com/dfinity/examples` - [x] Download and install [Docker](https://docs.docker.com/get-docker/) if using the Docker option. -- [x] Download the GitHub repo containing this project's files: `git clone https://github.com/dfinity/examples` -### Step 1. Navigate inside of the project's folder: + +## Step 1: Navigate inside of the project's folder ```bash cd examples/motoko/encrypted-notes-dapp @@ -121,7 +116,7 @@ cd examples/motoko/encrypted-notes-dapp This project folder contains the files for both Motoko and Rust development. -### Step 2: Set an environmental variable reflecting which backend canister you'll be using: +## Step 2: Set an environmental variable reflecting which backend canister you'll be using For Motoko deployment run: @@ -132,7 +127,7 @@ export BUILD_ENV=motoko **Building the Rust canister requires either the Rust toolchain installed on your system or Docker-backed deployment (see below).** -### Step 3: Deploy locally. +## Step 3: Deploy locally ### Option 1: Docker deployment **This option does not yet work on Apple M1; the combination of DFX and Docker do not currently support the required architecture.** @@ -188,15 +183,14 @@ dfx start ``` -:::info -If you see an error "Failed to set socket of tcp builder to 0.0.0.0:8000", make sure that the port 8000 is not occupied, e.g., by the previously run Docker command (you might want to stop the Docker daemon whatsoever for this step). -::: +> [!TIP] +> If you see an error "Failed to set socket of tcp builder to 0.0.0.0:8000", make sure that the port 8000 is not occupied, e.g., by the previously run Docker command (you might want to stop the Docker daemon whatsoever for this step). + - #### Step 5: Install a local Internet Identity (II) canister. -:::info -If you have multiple `dfx` identities set up, ensure you are using the identity you intend to use with the `--identity` flag. -::: +> [!TIP] +> If you have multiple `dfx` identities set up, ensure you are using the identity you intend to use with the `--identity` flag. To install and deploy a canister run: @@ -246,12 +240,10 @@ npm run dev ``` -:::caution -If you have opened this page previously, please remove all local store data for this page from your web browser, and hard-reload the page. - -For example in Chrome, go to Inspect → Application → Local Storage → http://localhost:3000/ → Clear All, and then reload. -::: - +> [!WARNING] +> If you have opened this page previously, please remove all local store data for this page from your web browser, and hard-reload the page. +> +> For example in Chrome, go to Inspect → Application → Local Storage → http://localhost:3000/ → Clear All, and then reload. ### Mainnet deployment @@ -341,7 +333,7 @@ Fig. 3. Scenario for a user with multiple registered devices. - #### Step 1: Perform steps 1-3 of Scenario I on Device A. -- #### Step 2:. Perform steps 1-3 of Scenario I on Device B. +- #### Step 2: Perform steps 1-3 of Scenario I on Device B. One subtle difference that you might observe on Device B is that the message "Synchronizing..." (Fig. 3(a)) appears for a short time. As Device A was the first to log in, it was also the first one to generate a shared secret. Device B has to retrieve it. To do that, Device B first uploads its public key (pub B) to the backend canister. Device A retrieves pub B using periodic polling. Device A then re-encrypts the shared secret with pub B and uploads it to the backend. Afterward, Device B can retrieve the encrypted shared secret and decrypt it with its private key. @@ -409,6 +401,7 @@ Observer `All tests passed.` at the end of the output. ## Troubleshooting + ### Building/deployment problems Error `ERR_OSSL_EVP_UNSUPPORTED`. Version 17+ of node.js introduces changes to the way Node handles OpenSSL. diff --git a/motoko/hello_cycles/README.md b/motoko/hello_cycles/README.md index bf3340cfe..430e2fadc 100644 --- a/motoko/hello_cycles/README.md +++ b/motoko/hello_cycles/README.md @@ -1,13 +1,5 @@ ---- -keywords: [beginner, motoko, hello, hello cycles, cycles] ---- - # Hello, cycles! -[View this sample's code on GitHub](https://github.com/dfinity/examples/tree/master/motoko/hello_cycles) - -## Overview - The `hello_cycle`s sample project provides a simple example to illustrate how you might add functions to receive cycles, transfer cycles, and check your cycle balance with a simple Motoko actor (canister). This sample project assumes that you are using the default cycles wallet canister that is created for you. @@ -26,28 +18,31 @@ The wallet's `wallet_receive` return type differs from hello_cycle's `wallet_rec This is a Motoko example that does not currently have a Rust variant. -## Prerequisites +### Prerequisites This example requires an installation of: - [x] Install the [IC SDK](https://internetcomputer.org/docs/current/developer-docs/setup/install/index.mdx). -- [x] Download the following project files from GitHub: `git clone https://github.com/dfinity/examples` +- [x] Clone the example dapp project: `git clone https://github.com/dfinity/examples` Begin by opening a terminal window. -### Step 1: Navigate into the folder containing the project's files and start a local instance of the replica with the command: +## Step 1: Setup the project environment + +Navigate into the folder containing the project's files and start a local instance of the Internet Computer with the commands: + ```bash cd examples/motoko/hello_cycles dfx start --background ``` -### Step 2: Deploy the canister: +## Step 2: Deploy the canister ```bash dfx deploy ``` -### Step 3: Check that the current cycles balance of canister hello_cycles by running the following command: +## Step 3: Check that the current cycles balance of the `hello_cycles` canister ```bash dfx canister call hello_cycles wallet_balance @@ -59,7 +54,7 @@ The output should resemble the following: (3_091_662_816_985 : nat) ``` -You can also see the cycles balance of hello_cycles (or any canister you control) by calling: +You can also see the cycles balance of `hello_cycles` (or any canister you control) by calling: ```bash dfx canister status hello_cycles @@ -79,7 +74,7 @@ Balance: 3_092_278_099_590 Cycles Module hash: 0x09198be65e161bdb5c75c705dfec4b707a8091ac5d1a095dd45c025142a1fc43 ``` -### Step 4: To display the default wallet and hello_cycles canister principals, run the commands: +## Step 4: Display the default wallet and hello_cycles canister principals ```bash dfx identity get-wallet @@ -95,7 +90,7 @@ dzh22-nuaaa-aaaaa-qaaoa-cai Below, we'll frequently use `$(dfx identity get-wallet)` and `$(dfx canister id hello_cycles)` to splice canister principals into longer bash commands. -### Step 5: Attempt to send 2 trillion cycles from the default wallet to the hello_cycles canister by running the following command: +## Step 5: Attempt to send 2 trillion cycles from the default wallet to the hello_cycles canister ```bash dfx canister call $(dfx identity get-wallet) wallet_send "(record { canister = principal \"$(dfx canister id hello_cycles)\"; amount = (2000000000000:nat64); } )" @@ -109,7 +104,7 @@ If successful, the output will look similar to: (variant { 17_724 }) ``` -#### Step 6: Verify that the cycles balance for the hello_cycles canister has increased by 10_000_000 by running the following command: +## Step 6: Verify that the cycles balance for the hello_cycles canister has increased by 10_000_000 ```bash dfx canister call hello_cycles wallet_balance @@ -123,7 +118,7 @@ Output: The amount is only increased by 10_000_000 because the implementation of `wallet_receive` is coded to accept at most 10_000_000 cycles, even when more cycles were transferred with the call. The unaccepted cycles are not lost but implicitly refunded to the caller (in this case, the wallet). -### Step 7: Send some cycles from the hello_cycles canister back to the wallet by running the command: +## Step 7: Send some cycles from the hello_cycles canister back to the wallet ```bash dfx canister call hello_cycles transfer "(func \"$(dfx identity get-wallet)\".\"wallet_receive\", 5000000)" @@ -135,7 +130,7 @@ Output: (record { refunded = 0 : nat }) ``` -### Step 8: Verify that the cycles balance of the `hello_cycles` canister has decreased with: +## Step 8: Verify that the cycles balance of the `hello_cycles` canister has decreased ```bash dfx canister call hello_cycles wallet_balance diff --git a/motoko/ic-pos/README.md b/motoko/ic-pos/README.md index cea9d3ddc..aba1d5dc7 100644 --- a/motoko/ic-pos/README.md +++ b/motoko/ic-pos/README.md @@ -1,7 +1,3 @@ ---- -keywords: [advanced, motoko, bitcoin, pos, point of sale, ckbtc] ---- - # IC-POS ![](./media/header.png) @@ -54,14 +50,14 @@ The frontend interacts with the following IC canisters: - `ckbtc index` - to fetch transaction history. - `internet identity` - to authenticate users. -## Setup, dev environment +### Prerequisites +This example requires an installation of: + +- [x] Install the [IC SDK](https://internetcomputer.org/docs/current/developer-docs/setup/install/index.mdx). +- [x] Clone the example dapp project: `git clone https://github.com/dfinity/examples` -Pre-requisites: +Begin by opening a terminal window. -- [Local Internet Computer dev environment](https://internetcomputer.org/docs/current/developer-docs/backend/rust/dev-env) -- [Node 20+](https://nodejs.org/en/) -- [pnpm](https://pnpm.io/installation) - ## Deploy using script To get started quickly and deploy the IC-POS app locally, you can run a deploy script. This script will start a local replica, deploy the necessary canisters, and build and deploy the frontend. @@ -74,21 +70,17 @@ Once the script has finished, you should proceed to step 10 to create a store an ## Deploy manually -### 1. Clone the examples repository and navigate to the IC-POS project: +### Step 1: Setup the project environment -```bash -git clone https://github.com/dfinity/examples -cd examples/motoko/ic-pos -``` +Navigate into the folder containing the project's files and start a local instance of the Internet Computer with the commands: -### 2. Start a local instance of the replica: - ```bash -dfx start --clean --background +cd examples/motoko/ic-pos +dfx start --background ``` -### 3. Deploy the Internet Identity canister: +### Step 2: Deploy the Internet Identity canister Integration with the [Internet Identity](https://internetcomputer.org/internet-identity/) allows store owners to securely setup and manage their store. The Internet Identity canister is already deployed on the IC mainnet. For local development, you need to deploy it to your local instance of the IC. @@ -96,7 +88,7 @@ Integration with the [Internet Identity](https://internetcomputer.org/internet-i dfx deploy internet_identity ``` -### 4. Save the current principal as a variable: +### Step 3: Save the current principal as a variable The principal will be used when deploying the ledger canister. @@ -104,7 +96,7 @@ The principal will be used when deploying the ledger canister. export OWNER=$(dfx identity get-principal) ``` -### 5. Deploy the ckBTC ledger canister: +### Step 4: Deploy the ckBTC ledger canister The responsibilities of the ledger canister is to keep track of token balances and handle token transfers. @@ -147,7 +139,7 @@ dfx deploy icrc1_ledger --argument ' ' ``` -### 6. Deploy the index canister +### Step 5: Deploy the index canister The index canister syncs the ledger transactions and indexes them by account. @@ -159,7 +151,7 @@ dfx deploy icrc1_index --argument ' ' ``` -### 7. Deploy the icpos canister +### Step 6: Deploy the `icpos` canister The icpos canister manages the store configuration and sends notifications when a payment is received. @@ -169,7 +161,7 @@ The `--argument '(0)'` argument is used to initialize the canister with `startBl dfx deploy icpos --argument '(0)' ``` -### 8. Configure the icpos canister +### Step 7: Configure the `icpos` canister IC-POS uses [Courier](https://courier.com/) to send email and SMS notifications. If you want to enable notifications, you need to sign up for a Courier account and and create and API key. Then issue the following command: @@ -177,7 +169,7 @@ IC-POS uses [Courier](https://courier.com/) to send email and SMS notifications. dfx canister call icpos setCourierApiKey "pk_prod_..." ``` -### 9. Build and run the frontend +### Step 8: Build and run the frontend Run npm to install dependencies and start a development version of the frontend. @@ -188,15 +180,13 @@ pnpm run dev The app should now be accessible at a local url, typically `http://localhost:5173`. -### 10. Make a transfer! - - +## Make a transfer! Now that everything is up and running, you can make a transfer to your newly created store. The easiest way to do this is to create two stores using two different Internet Identity accounts, using two different web browsers. Then, transfer some tokens from one store to the other. -#### 10.1 Create the first store and supply it with some tokens +### Step 10: Create the first store and supply it with some tokens Log in to the frontend using the Internet Identity. Configure the store with a name and then, on the main store page, click on the principal pill to copy the address to your clipboard. Using the `dfx` command, now mint some tokens from your owner principal to the store principal. @@ -211,7 +201,7 @@ dfx canister call icrc1_ledger icrc1_transfer ' ' ``` -#### 10.2 Create the second store +### Step 11: Create the second store Log in to the frontend using **a new Internet Identity using another web browser**. Give this store a name as well and copy the store principal like in the previous step. diff --git a/motoko/icrc2-swap/README.md b/motoko/icrc2-swap/README.md index 45b5cf660..6c4fd1efd 100644 --- a/motoko/icrc2-swap/README.md +++ b/motoko/icrc2-swap/README.md @@ -1,13 +1,5 @@ ---- -keywords: [advanced, motoko, swap, token swap, icrc2] ---- - # ICRC-2 swap -[View this sample's code on GitHub](https://github.com/dfinity/examples/tree/master/motoko/icrc2-swap) - -## Overview - ICRC-2 Swap is a simple canister demonstrating how to safely work with ICRC-2 tokens. It handles depositing, swapping, and withdrawing ICRC-2 tokens. @@ -27,19 +19,24 @@ different from other synchronous blockchains. ## Local deployment -## Prerequisites +### Prerequisites +This example requires an installation of: - [x] Install the [IC SDK](https://internetcomputer.org/docs/current/developer-docs/setup/install/index.mdx). -- [x] Install [Node.js](https://nodejs.org/en/). -- [ ] Clone the example dapp project: `git clone https://github.com/dfinity/examples` +- [x] Clone the example dapp project: `git clone https://github.com/dfinity/examples` + +Begin by opening a terminal window. + +### Step 1: Setup the project environment -### Step 1: Start a local instance of the replica: +Navigate into the folder containing the project's files and start a local instance of the Internet Computer with the commands: ```bash -dfx start --clean --background +cd examples/motoko/icrc2-swap +dfx start --background ``` -### Step 2: Create your user accounts: +### Step 2: Create your user accounts ```bash export OWNER=$(dfx identity get-principal) @@ -51,7 +48,7 @@ dfx identity new bob export BOB=$(dfx identity get-principal --identity bob) ``` -### Step 2: Deploy two tokens: +### Step 3: Deploy two tokens Deploy Token A: @@ -122,7 +119,7 @@ dfx deploy token_b --argument ' ' ``` -### Step 3: Deploy the swap canister: +### Step 4: Deploy the swap canister The swap canister accepts deposits and performs the swap. @@ -140,7 +137,7 @@ dfx deploy swap --argument ' export SWAP=$(dfx canister id swap) ``` -### Step 4: Approve & deposit tokens: +### Step 5: Approve & deposit tokens Before you can swap the tokens, they must be transferred to the swap canister. With ICRC-2, this is a two-step process. First, approve the transfer: @@ -199,7 +196,7 @@ dfx canister call --identity bob swap deposit 'record { }' ``` -### Step 5: Perform a swap: +### Step 6: Perform a swap ```bash dfx canister call swap swap 'record { @@ -217,7 +214,7 @@ dfx canister call swap balances That should show us that now Bob holds Token A, and Alice holds Token B in the swap contract. -### Step 6: Withdraw tokens: +### Step 7: Withdraw tokens After the swap, your balances in the swap canister will have been updated, and you can withdraw your newly received tokens into your wallet. @@ -244,7 +241,7 @@ dfx canister call --identity bob swap withdraw 'record { }' ``` -### Step 7: Check token balances: +### Step 8: Check token balances ```bash # Check Alice's Token A balance. They should now have 998.99980000 A @@ -268,24 +265,31 @@ the token balances. The example comes with a test suite to demonstrate the basic functionality. It shows how to use this repo from a Javascript client. -## Prerequisites +### Prerequisites +This example requires an installation of: - [x] Install the [IC SDK](https://internetcomputer.org/docs/current/developer-docs/setup/install/index.mdx). -- [x] Install [Node.js](https://nodejs.org/en/). +- [x] Clone the example dapp project: `git clone https://github.com/dfinity/examples` + +Begin by opening a terminal window. + +### Step 1: Setup the project environment + +Navigate into the folder containing the project's files and start a local instance of the Internet Computer with the commands: -### Step 1: Start a local instance of the replica: ```bash -dfx start --clean --background +cd examples/motoko/icrc2-swap +dfx start --background ``` -### Step 2: Install npm dependencies: +### Step 2: Install npm dependencies ```bash npm install ``` -### Step 3: Run the test suite: +### Step 3: Run the test suite ```bash make test diff --git a/motoko/internet_identity_integration/README.md b/motoko/internet_identity_integration/README.md index 271d759e9..8626b1754 100644 --- a/motoko/internet_identity_integration/README.md +++ b/motoko/internet_identity_integration/README.md @@ -1,13 +1,5 @@ ---- -keywords: [intermediate, motoko, internet identity, authentication] ---- - # Internet Identity integration -[View this sample's code on GitHub](https://github.com/dfinity/examples/tree/master/motoko/internet_identity_integration) - -## Overview - This tutorial shows how to integrate Internet Identity into a dapp front-end and make use of the user identity in the backend. It builds on the "greet" dapp that is generated by running `dfx new`. If you are unfamiliar with `dfx new` and the generated application, please have a look at [this](https://internetcomputer.org/docs/current/developer-docs/setup/install/index.mdx) guide first. The code contained in this folder shows the finished solution you should arrive at after following the step-by-step instructions. @@ -17,24 +9,28 @@ This tutorial will explain all the steps required to integrate the default start - Offer a login with Internet Identity button. - Greet you with the principal provided by Internet Identity instead of entering a name. -This is a Motoko example that does not currently have a Rust variant. +This is a Motoko example that does not currently have a Rust variant. +### Prerequisites +This example requires an installation of: -## Prerequisites - [x] Install the [IC SDK](https://internetcomputer.org/docs/current/developer-docs/setup/install/index.mdx). -- [x] Install [Node.js](https://nodejs.org/en/download/). +- [x] Clone the example dapp project: `git clone https://github.com/dfinity/examples` - [x] Download and install the `@dfinity/auth-client` package with the command `npm install @dfinity/auth-client`. -- [x] Download the following project files from GitHub: `git clone https://github.com/dfinity/examples` - [x] Chrome or Firefox browser (other browsers also work, but may need a slightly different webpack configuration, see the note on [step 4 below](#step-4-make-the-internet-identity-url-available-in-the-build-process)) -### Step 1: Navigate into the examples folder for this sample and then generate a new project with `dfx new`: +Begin by opening a terminal window. + +## Step 1: Setup the project environment + +Navigate into the folder containing the project's files, start a local instance of the Internet Computer, and create a new project with the commands: ```bash cd examples/motoko/internet_identity_integration +dfx start --background dfx new greet ``` - You should have a starter project generated with the following file structure: ```bash @@ -56,7 +52,8 @@ You should have a starter project generated with the following file structure: └── webpack.config.js ``` -### Step 2: Add Internet Identity to the local project. +## Step 2: Add Internet Identity to the local project + Add this code block to the canister section in the `dfx.json` file: **The following example is a **code snippet** that is part of a larger code file. This snippet may return an error if run on its own. To view the full code file that should be run, please see [final code](#final-code).** @@ -77,7 +74,8 @@ Add this code block to the canister section in the `dfx.json` file: This adds a prebuilt Internet Identity canister to your project. The remote property makes sure, that this canister is only deployed locally (as it already exists on mainnet). The frontend property tells `dfx` that this canister does have a front-end (so it prints the front-end URL after deployment, see the next step). The URLs point to the latest dev build release of Internet Identity. The dev build has some extra features that make Internet Identity easier to use in a development setting (such as a predictable captcha, no requirement for WebAuthn, etc.). -### Step 3: Deploy Internet Identity locally. +## Step 3: Deploy Internet Identity locally + Run `dfx deploy` to deploy all canisters including Internet Identity to the local replica. It should print the Internet Identity URL to the console: ```bash @@ -99,7 +97,8 @@ URLs: Open the `internet_identity` link in the browser. You should be able to create anchors and register devices. -### Step 4: Make the Internet Identity URL available in the build process. +## Step 4: Make the Internet Identity URL available in the build process + We want the sample application to integrate with Internet Identity differently depending on whether we deploy locally or on mainnet: - Locally the application should use the Internet Identity URL `http://.localhost:4943/`. @@ -249,14 +248,14 @@ module.exports = { }; ``` -### Step 5: Add the auth-client library to the frontend. +## Step 5: Add the auth-client library to the frontend The auth-client is a library provided by DFINITY to make integration with Internet Identity easy. Run: ```bash npm install @dfinity/auth-client @dfinity/identity --save-dev ``` -### Step 6: Add a login button to the frontend. +## Step 6: Add a login button to the frontend Open the `index.html` file and replace the content with the following: ```html @@ -288,7 +287,7 @@ Open the `index.html` file and replace the content with the following: ``` -### Step 7: Make the login button interact with II. +## Step 7: Make the login button interact with II In order for the login button to work, we need to give it behavior. Replace the contents of the `src/greet_frontend/src/index.js` file with the following: ```javascript @@ -342,7 +341,7 @@ loginButton.onclick = async (e) => { };% ``` -### Step 8: Modify the backend. +## Step 8: Modify the backend We want our application to greet the caller principal. To do so, the backend Motoko code needs to be changed to: - No longer take a name parameter. @@ -360,7 +359,9 @@ actor { }; ``` -### Step 9: Run `dfx deploy` again. This will also regenerate the bindings in `src/declarations`. +## Step 9: Run `dfx deploy` again + +This will also regenerate the bindings in `src/declarations`. The successful output should resemble the following: @@ -375,7 +376,7 @@ URLs: internet_identity: http://127.0.0.1:4943/?canisterId=gf4a7-g4aaa-aaaaa-qaarq-cai&id=g6z42-4eaaa-aaaaa-qaata-cai ``` -### Step 10: Test the application. +## Step 10: Test the application Open the `greet_frontend` URL in a web browser. diff --git a/motoko/life/README.md b/motoko/life/README.md index 55d2e3f0e..00e9aa435 100644 --- a/motoko/life/README.md +++ b/motoko/life/README.md @@ -1,13 +1,5 @@ ---- -keywords: [beginner, motoko, game of life] ---- - # Game of life -[View this sample's code on GitHub](https://github.com/dfinity/examples/tree/master/motoko/life) - -## Overview - This example contains a series of implementations of Conway's Game of Life. Its main purpose is to demonstrate state-preserving upgrades using Motoko's stable variables. The implementations are meant to be instructive and are not optimized for efficiency or to hide network latency, which a production implementation would need to consider. @@ -22,24 +14,24 @@ To make upgrades apparent, each version uses a different digit to display live c This is a Motoko example that does not currently have a Rust variant. - -## Prerequisites +### Prerequisites This example requires an installation of: - [x] Install the [IC SDK](https://internetcomputer.org/docs/current/developer-docs/setup/install/index.mdx). -- [x] Install [Node.js](https://nodejs.org/en/download/). - [x] Clone the example dapp project: `git clone https://github.com/dfinity/examples` Begin by opening a terminal window. -### Step 1: Navigate into the folder containing the project's files and start a local instance of the Internet Computer with the command: +## Step 1: Setup the project environment + +Navigate into the folder containing the project's files and start a local instance of the Internet Computer with the commands: ```bash cd examples/motoko/life dfx start --background ``` -### Step 2: Deploy the canister: +## Step 2: Deploy the canisters ```bash dfx deploy @@ -53,7 +45,7 @@ Take note of the URL at which the life_assets is accessible using the command: echo "http://127.0.0.1:4943/?canisterId=$(dfx canister id life_assets)" ``` -### Step 3: Open the frontend in your browser by clicking on the link returned in the output of the previous command. +## Step 3: Open the frontend in your browser by clicking on the link returned in the output of the previous command. Click the button **Step**. The grid will advance to the next generation of the Game of Life. @@ -131,7 +123,7 @@ After first upgrading from v0 the state will be random, as on deploying v0. This However, if you re-deploy the v1 project a second time, perhaps after making a minor edit, you'll see the last state of the grid, before deployment, preserved across the deployment, in a state-preserving upgrade. The random initializer for state is skipped and state just assumes the value it had before the upgrade. -### Upgrading to v2: +### Upgrading to v2 To upgrade to the v2 implementation, issue these commands: ```bash diff --git a/motoko/minimal-counter-dapp/README.md b/motoko/minimal-counter-dapp/README.md index fb30764e4..43239413b 100644 --- a/motoko/minimal-counter-dapp/README.md +++ b/motoko/minimal-counter-dapp/README.md @@ -1,15 +1,7 @@ ---- -keywords: [beginner, motoko, counter] ---- - # Minimal counter dapp -[View this sample's code on GitHub](https://github.com/dfinity/examples/tree/master/motoko/minimal-counter-dapp) - ![Counter Frontend](README_images/frontend.png) -## Overview - The example dapp shows how to build a very basic dapp with both backend and frontend, using Motoko for the backend functionality and plain HTML and JavaScript for the frontend. The dapp is a simple counter, which will increment, decrement or reset a counter by clicking a button in the frontend. The purpose of this example dapp is to build a minimalistic dapp, based on the default dapp template, installed by `dfx` when creating a new project. @@ -18,31 +10,29 @@ This example covers: - Create a new canister smart contract using the IC SDK (`dfx`). - Use the default project as a template as the starting point for the new project. -- Add backend functions for a counter (increment, getCount, decreent and reset). +- Add backend functions for a counter (increment, getCount, decrement and reset). - Implement backend functions in the frontend. - Deploy the canister smart contract locally. - Test backend with Candid UI and command line using `dfx`, and test frontend in browser. -## Prerequisites - +### Prerequisites This example requires an installation of: -- [x] Install the [IC SDK](https://internetcomputer.org/docs/current/developer-docs/getting-started/install). -- [x] Install [Node.js](https://nodejs.org/en/download/). -- [x] Download and install [git.](https://git-scm.com/downloads) +- [x] Install the [IC SDK](https://internetcomputer.org/docs/current/developer-docs/setup/install/index.mdx). - [x] Clone the example dapp project: `git clone https://github.com/dfinity/examples` Begin by opening a terminal window. -### Step 1: Navigate into the folder containing the project's files and start a local instance of the replica with the command: +## Step 1: Setup the project environment + +Navigate into the folder containing the project's files and start a local instance of the Internet Computer with the commands: ```bash cd examples/motoko/minimal-counter-dapp -npm install dfx start --background ``` -### Step 2: Build and deploy the canister: +## Step 2: Build and deploy the canister ```bash dfx deploy @@ -61,7 +51,7 @@ URLs: minimal_dapp_backend: http://127.0.0.1:4943/?canisterId=be2us-64aaa-aaaaa-qaabq-cai&id=bkyz2-fmaaa-aaaaa-qaaaq-cai ``` -### Step 3: Open the `minimal_dapp_frontend` URL in a web browser. +## Step 3: Open the `minimal_dapp_frontend` URL in a web browser You will see a GUI interface with following buttons: @@ -76,7 +66,6 @@ The three main parts of the example dapp are the backend, the Candid interface, ### Motoko backend The backend functions are located in the `src/minimal_dapp_backend/main.mo` Motoko file. The backend stores the counter value and has functions to get, increment, decrement and reset the counter value. - #### Counter variable Four functions are created to make the counter work: `increment()`, `decrement()`, `getCount()` and `reset()`. The current counter value is stored as a number in the actor. diff --git a/motoko/parallel_calls/README.md b/motoko/parallel_calls/README.md index e91d06c3b..51e2a5858 100644 --- a/motoko/parallel_calls/README.md +++ b/motoko/parallel_calls/README.md @@ -1,13 +1,5 @@ ---- -keywords: [advanced, motoko, defi] ---- - # Parallel inter-canister calls -[View this sample code on GitHub](https://github.com/dfinity/examples/tree/master/motoko/parallel_calls). - -## Overview - This example demonstrates how to implement inter-canister calls that run in parallel in Motoko, and highlights some differences between parallel and sequential calls. Running independent calls in parallel can lower the latency, especially when messages are sent across subnets. For example, a canister that swaps two tokens might want to launch both token transfer operations in parallel. ## Architecture @@ -18,38 +10,38 @@ The sample code revolves around two simple canisters, `caller` and `callee`. `Ca The callee exposes a simple `ping` endpoint that takes no parameters and returns nothing. -## Prerequisites - -To run this example you should: +### Prerequisites +This example requires an installation of: - [x] Install the [IC SDK](https://internetcomputer.org/docs/current/developer-docs/setup/install/index.mdx). - [x] Clone the example dapp project: `git clone https://github.com/dfinity/examples` -## Running the example - Begin by opening a terminal window. -### Step 1: Navigate into the example folder and start a local Internet Computer replica +## Step 1: Setup the project environment + +Navigate into the folder containing the project's files and start a local instance of the Internet Computer with the commands: ```bash cd examples/motoko/parallel_calls dfx start --background ``` -### Step 2: Deploy the canister +## Step 2: Deploy the canisters ```bash dfx deploy ``` -### Step 3: Set up the caller canister +## Step 3: Set up the caller canister We now provide the ID of the callee to the caller, such that the caller can initiate calls. + ``` dfx canister call caller setup_callee "(principal \"`dfx canister id callee`\")" ``` -### Step 4: Invoke sequential and parallel calls +## Step 4: Invoke sequential and parallel calls Let's first call the different endpoints of the `caller` canister using `dfx` @@ -68,7 +60,7 @@ And the other endpoint: dfx canister call caller parallel_calls 100 ``` -which outputs: +This should output: ```bash (100 : nat64) @@ -102,7 +94,7 @@ All the sequential calls succeed, but most parallel calls fail. The reason is th Lastly, the parallel calls here complete sooner -- because most of them fail! -### Step 5: Multi-subnet setting +## Step 5: Multi-subnet setting Parallel calls are a lot more useful in multi-subnet settings. We can create such a setting locally using Pocket IC. diff --git a/motoko/pub-sub/README.md b/motoko/pub-sub/README.md index 8ce86d03f..683e88581 100644 --- a/motoko/pub-sub/README.md +++ b/motoko/pub-sub/README.md @@ -1,18 +1,10 @@ ---- -keywords: [beginner, motoko, pubsub, publish, subscribe] ---- - # PubSub -[View this sample's code on GitHub](https://github.com/dfinity/examples/tree/master/motoko/pub-sub) - - -## Overview This sample project demonstrates how functions may be passed as arguments of inter-canister calls to be used as callbacks. A common problem in both distributed and decentralized systems is keeping separate services (or canisters) synchronized with one another. While there are many potential solutions to this problem, a popular one is the publisher/subscriber pattern or "PubSub". PubSub is an especially valuable pattern on the Internet Computer as its primary drawback, message delivery failures, does not apply. -## Prerequisites +### Prerequisites This example requires an installation of: - [x] Install the [IC SDK](https://internetcomputer.org/docs/current/developer-docs/setup/install/index.mdx). @@ -20,32 +12,34 @@ This example requires an installation of: Begin by opening a terminal window. -### Step 1: Navigate into the folder containing the project's files and start a local instance of the replica with the command: +## Step 1: Setup the project environment + +Navigate into the folder containing the project's files and start a local instance of the Internet Computer with the commands: ```bash cd examples/motoko/pub-sub dfx start --background ``` -### Step 2: Deploy the canister: +## Step 2: Deploy the canisters: ```bash dfx deploy ``` -### Step 3: Subscribe to the "Apples" topic: +## Step 3: Subscribe to the "Apples" topic ```bash dfx canister call sub init '("Apples")' ``` -### Step 4: Publish to the "Apples" topic: +## Step 4: Publish to the "Apples" topic ```bash dfx canister call pub publish '(record { "topic" = "Apples"; "value" = 2 })' ``` -### Step 5: Receive your subscription: +## Step 5: Receive your subscription ```bash dfx canister call sub getCount diff --git a/motoko/random_maze/README.md b/motoko/random_maze/README.md index ba484e796..65714318b 100644 --- a/motoko/random_maze/README.md +++ b/motoko/random_maze/README.md @@ -1,13 +1,5 @@ ---- -keywords: [beginner, motoko, random, randomness, maze, game] ---- - # Random maze -[View this sample's code on GitHub](https://github.com/dfinity/examples/tree/master/motoko/random_maze) - -## Overview - The example generates a random maze using cryptographic randomness. It illustrates: @@ -26,7 +18,7 @@ The function `generate` calls library function `Random.blob()` asynchronously to This is a Motoko example that does not currently have a Rust variant. -## Prerequisites +### Prerequisites This example requires an installation of: - [x] Install the [IC SDK](https://internetcomputer.org/docs/current/developer-docs/setup/install/index.mdx). @@ -34,26 +26,28 @@ This example requires an installation of: Begin by opening a terminal window. -### Step 1: Navigate into the folder containing the project's files and start a local instance of the replica with the command: +## Step 1: Setup the project environment + +Navigate into the folder containing the project's files and start a local instance of the Internet Computer with the commands: ```bash cd examples/motoko/random_maze dfx start --background ``` -### Step 2: Install front-end dependencies: +## Step 2: Install front-end dependencies ```bash npm install ``` -### Step 3: Deploy the canister: +## Step 3: Deploy the canisters ```bash dfx deploy ``` -### Step 4: Take note of the URL at which the user interface is accessible. +## Step 4: Take note of the URL at which the user interface is accessible ```bash echo "http://127.0.0.1:4943/?canisterId=$(dfx canister id random_maze_assets)" diff --git a/motoko/send_http_get/README.md b/motoko/send_http_get/README.md index 064445c2a..9e6d80a8d 100644 --- a/motoko/send_http_get/README.md +++ b/motoko/send_http_get/README.md @@ -1,11 +1,5 @@ ---- -keywords: [intermediate, motoko, http get, http, get] ---- - # HTTP: GET -[View this sample's code on GitHub](https://github.com/dfinity/examples/tree/master/motoko/send_http_get) - The purpose of this dapp is to give developers a minimal dapp that uses the IC's HTTPS outcalls feature to make a `GET` request. This demo goes in hand with the [developer documentation on HTTPS outcalls](https://internetcomputer.org/docs/current/developer-docs/integrations/https-outcalls/https-outcalls-get). @@ -15,18 +9,6 @@ If you want to start working on your project right away, you might want to try t ```bash git clone https://github.com/dfinity/examples cd examples/motoko/send_http_get -dfx help -dfx canister --help -``` - -## Running the project locally -If you want to test your project locally, you can use the following commands: - -```bash -# Starts the replica, running in the background dfx start --background - -# Deploys your canisters to the replica and generates your candid interface dfx deploy ``` - diff --git a/motoko/send_http_post/README.md b/motoko/send_http_post/README.md index bb2faf180..bfa2b865c 100644 --- a/motoko/send_http_post/README.md +++ b/motoko/send_http_post/README.md @@ -1,11 +1,5 @@ ---- -keywords: [intermediate, motoko, http post, post, http] ---- - # HTTP: POST -[View this sample's code on GitHub](https://github.com/dfinity/examples/tree/master/motoko/send_http_post) - The purpose of this dapp is to give developers a minimal dapp that uses the IC's HTTPS outcalls feature to make a `POST` request. This demo goes in hand with the [developer documentation on HTTPS outcalls](https://internetcomputer.org/docs/current/developer-docs/integrations/https-outcalls/https-outcalls-post). @@ -15,18 +9,6 @@ If you want to start working on your project right away, you might want to try t ```bash git clone https://github.com/dfinity/examples cd examples/motoko/send_http_post_motoko -dfx help -dfx canister --help -``` - -## Running the project locally - -If you want to test your project locally, you can use the following commands: - -```bash -# Starts the replica, running in the background dfx start --background - -# Deploys your canisters to the replica and generates your candid interface dfx deploy ``` diff --git a/motoko/superheroes/README.md b/motoko/superheroes/README.md index b737eb081..3ea4b6122 100644 --- a/motoko/superheroes/README.md +++ b/motoko/superheroes/README.md @@ -1,18 +1,10 @@ ---- -keywords: [advanced, motoko, crud, crud application] ---- - # CRUD example -[View this sample's code on GitHub](https://github.com/dfinity/examples/tree/master/motoko/superheroes) - -## Overview - This example demonstrates how to build a CRUD application on ICP using Motoko and React. This is a Motoko example that does not currently have a Rust variant. -## Prerequisites +### Prerequisites This example requires an installation of: - [x] Install the [IC SDK](https://internetcomputer.org/docs/current/developer-docs/setup/install/index.mdx). @@ -20,32 +12,28 @@ This example requires an installation of: Begin by opening a terminal window. -### Step 1: Navigate into the folder containing the project's files and start a local instance of the replica with the command: +## Step 1: Setup the project environment + +Navigate into the folder containing the project's files and start a local instance of the Internet Computer with the commands: ```bash cd examples/motoko/superheroes dfx start --background ``` -### Step 2: Build the frontend of the application: - -```bash -npm install -``` - -### Step 3: Deploy the canister: +## Step 2: Deploy the canisters ```bash dfx deploy ``` -### Step 4: Take note of the URL at which the canister is accessible. +## Step 3: Take note of the URL at which the canister is accessible ```bash echo "http://127.0.0.1:4943/?canisterId=$(dfx canister id www)" ``` -### Step 5: Open the aforementioned URL in your web browser. +## Step 4: Open the aforementioned URL in your web browser. ## Security considerations and best practices diff --git a/motoko/threshold-ecdsa/README.md b/motoko/threshold-ecdsa/README.md index 13e24ae38..f72dd7aae 100644 --- a/motoko/threshold-ecdsa/README.md +++ b/motoko/threshold-ecdsa/README.md @@ -1,13 +1,5 @@ ---- -keywords: [advanced, motoko, threshold ecdsa, signature, ecdsa] ---- - # Threshold ECDSA sample -[View this sample's code on GitHub](https://github.com/dfinity/examples/tree/master/motoko/threshold-ecdsa) - -## Overview - We present a minimal example canister smart contract for showcasing the [threshold ECDSA](https://internetcomputer.org/docs/current/developer-docs/integrations/t-ecdsa) API. The example canister is a signing oracle that creates ECDSA signatures with keys derived from an input string. @@ -20,32 +12,35 @@ More specifically: This tutorial gives a complete overview of the development, starting with downloading the [IC SDK](https://internetcomputer.org/docs/current/developer-docs/setup/index.md), up to the deployment and trying out the code on the IC mainnet. -:::info -This walkthrough focuses on the version of the sample canister code written in [Motoko](https://internetcomputer.org/docs/current/developer-docs/backend/motoko/index.md) programming language, but no specific knowledge of Motoko is needed to follow along. There is also a [Rust](https://github.com/dfinity/examples/tree/master/rust/threshold-ecdsa) version available in the same repo and follows the same commands for deploying. -::: - -## Prerequisites -- [x] Download and [install the IC SDK](https://internetcomputer.org/docs/current/developer-docs/setup/index.md) if you do not already have it. -- [x] Clone the example dapp project: `git clone https://github.com/dfinity/examples` +> [!TIP] +> This walkthrough focuses on the version of the sample canister code written in [Motoko](https://internetcomputer.org/docs/current/developer-docs/backend/motoko/index.md) programming language, but no specific knowledge of Motoko is needed to follow along. There is also a [Rust](https://github.com/dfinity/examples/tree/master/rust/threshold-ecdsa) version available in the same repo and follows the same commands for deploying. ## Getting started Sample code for `threshold-ecdsa` is provided in the [examples repository](https://github.com/dfinity/examples), under either [`/motoko`](https://github.com/dfinity/examples/tree/master/motoko/threshold-ecdsa) or [`/rust`](https://github.com/dfinity/examples/tree/master/rust/threshold-ecdsa) sub-directories. It requires at least [IC SDK](https://internetcomputer.org/docs/current/developer-docs/setup/index.md) version 0.11.0 for local development. -## Deploy and test the canister locally +### Prerequisites +This example requires an installation of: -This tutorial will use the Motoko version of the canister: +- [x] Install the [IC SDK](https://internetcomputer.org/docs/current/developer-docs/setup/install/index.mdx). +- [x] Clone the example dapp project: `git clone https://github.com/dfinity/examples` + +Begin by opening a terminal window. + +## Step 1: Setup the project environment + +Navigate into the folder containing the project's files and start a local instance of the Internet Computer with the commands: ```bash cd examples/motoko/threshold-ecdsa dfx start --background -npm install -dfx deploy ``` -#### What this does -- `dfx start --background` starts a local instance of the IC via the IC SDK -- `dfx deploy` deploys the code in the user's directory as a canister on the local version of the IC +## Step 2: Deploy the canisters + +```bash +dfx deploy +``` If successful, you should see something like this: @@ -58,19 +53,18 @@ URLs: If you open the URL in a web browser, you will see a web UI that shows the public methods the canister exposes. Since the canister exposes `public_key` and `sign` methods, those are rendered in the web UI. - -### Deploying the canister on the mainnet +## Deploying the canister on the mainnet To deploy this canister to the mainnet, one needs to do two things: - Acquire cycles (the equivalent of "gas" on other blockchains). This is necessary for all canisters. - Update the sample source code to have the right key ID. This is unique to this canister. -#### Acquire cycles to deploy +### Acquire cycles to deploy Deploying to the Internet Computer requires [cycles](https://internetcomputer.org/docs/current/developer-docs/getting-started/tokens-and-cycles) (the equivalent of "gas" on other blockchains). -#### Update source code with the right key ID +### Update source code with the right key ID To deploy the sample code, the canister needs the right key ID for the right environment. Specifically, one needs to replace the value of the `key_id` in the `src/ecdsa_example_motoko/main.mo` file of the sample code. Before deploying to the mainnet, one should modify the code to use the right name of the `key_id`. @@ -102,11 +96,10 @@ let { signature } = await ic.sign_with_ecdsa({ }); ``` -:::caution -To deploy to IC mainnet, one needs to replace the value in `key_id` fields with the values `"dfx_test_key"` to instead have either `"test_key_1"` or `"key_1"` depending on the desired intent. -::: +> [!WARNING] +> To deploy to IC mainnet, one needs to replace the value in `key_id` fields with the values `"dfx_test_key"` to instead have either `"test_key_1"` or `"key_1"` depending on the desired intent. -### Deploy to the mainnet via IC SDK +### Deploying To [deploy via mainnet](https://internetcomputer.org/docs/current/developer-docs/setup/deploy-mainnet.md), run the following commands: @@ -127,7 +120,7 @@ In the example above, `ecdsa_example_motoko` has the URL https://a3gq9-oaaaa-aaa ## Obtaining public keys -### Using the Candid Web UI +### Using the Candid UI If you deployed your canister locally or to the mainnet, you should have a URL to the Candid web UI where you can access the public methods. We can call the `public-key` method. diff --git a/motoko/threshold-schnorr/README.md b/motoko/threshold-schnorr/README.md index 199eb7672..f4ae0c23b 100644 --- a/motoko/threshold-schnorr/README.md +++ b/motoko/threshold-schnorr/README.md @@ -1,13 +1,5 @@ ---- -keywords: [advanced, motoko, threshold schnorr, schnorr, signature] ---- - # Threshold Schnorr -[View this sample's code on GitHub](https://github.com/dfinity/examples/tree/master/motoko/threshold-schnorr) - -## Overview - We present a minimal example canister smart contract for showcasing the [threshold Schnorr](https://internetcomputer.org/docs/current/references/ic-interface-spec/#ic-sign_with_schnorr) @@ -33,23 +25,22 @@ Motoko programming language. There is also a [Rust](https://github.com/dfinity/examples/tree/master/rust/threshold-schnorr) version available in the same repo and follows the same commands for deploying. - -## Prerequisites -- [x] Download and [install the IC - SDK](https://internetcomputer.org/docs/current/developer-docs/setup/index.md) - if you do not already have it. For local testing, `dfx >= 0.22.0-beta.0` is - required. -- [x] Clone the example dapp project: `git clone https://github.com/dfinity/examples` - ## Getting started Sample code for `threshold-schnorr-example` is provided in the [examples repository](https://github.com/dfinity/examples), under either [`/motoko`](https://github.com/dfinity/examples/tree/master/motoko/threshold-schnorr) or [`/rust`](https://github.com/dfinity/examples/tree/master/rust/threshold-schnorr) sub-directories. -### Deploy and test the canister locally +### Prerequisites +This example requires an installation of: -This tutorial will use the Motoko version of the canister. +- [x] Install the [IC SDK](https://internetcomputer.org/docs/current/developer-docs/setup/install/index.mdx). +- [x] Clone the example dapp project: `git clone https://github.com/dfinity/examples` + +Begin by opening a terminal window. + +## Step 1: Setup the project environment + +Navigate into the folder containing the project's files, start a local instance of the Internet Computer and deploy the project with the commands: -To deploy: ```bash cd examples/motoko/threshold-schnorr dfx start --background @@ -83,18 +74,18 @@ If you open the URL in a web browser, you will see a web UI that shows the public methods the canister exposes. Since the canister exposes `public_key` and `sign`, those are rendered in the web UI. -### Deploying the canister on the mainnet +## Deploying the canister on the mainnet To deploy this canister the mainnet, one needs to do two things: - Acquire cycles (equivalent of "gas" in other blockchains). This is necessary for all canisters. - Update the sample source code to have the right key ID. This is unique to this canister. -#### Acquire cycles to deploy +### Acquire cycles to deploy Deploying to the Internet Computer requires [cycles](https://internetcomputer.org/docs/current/developer-docs/getting-started/tokens-and-cycles) (the equivalent of "gas" on other blockchains). -#### Update source code with the right key ID +### Update source code with the right key ID To deploy the sample code, the canister needs the right key ID for the right environment. Specifically, one needs to replace the value of the `key_id` in the `src/schnorr_example_motoko/src/lib.rs` file of the sample code. Before deploying to mainnet, one should modify the code to use the right name of the `key_id`. @@ -115,7 +106,8 @@ IMPORTANT: To deploy to IC mainnet, one needs to replace `"dfx_test_key"` with either "test_key_1"` or `"key_1"` depending on the desired intent. Both uses of key ID in `src/schnorr_example_motoko/src/main.mo` must be consistent. -#### Deploy to the mainnet via IC SDK + +### Deploying To [deploy via the mainnet](https://internetcomputer.org/docs/current/developer-docs/setup/deploy-mainnet.md), run the following commands: @@ -139,7 +131,7 @@ mainnet. ## Obtaining public keys -### Using the Candid Web UI +### Using the Candid UI If you deployed your canister locally or to the mainnet, you should have a URL to the Candid web UI where you can access the public methods. We can call the `public-key` method. diff --git a/motoko/token_transfer/README.md b/motoko/token_transfer/README.md index 5607baba9..95ad249d8 100644 --- a/motoko/token_transfer/README.md +++ b/motoko/token_transfer/README.md @@ -1,9 +1,5 @@ # Token transfer -[View this samples code on GitHub](https://github.com/dfinity/examples/tree/master/motoko/token_transfer). - -## Overview - Token transfer is a canister that can transfer ICRC-1 tokens from its account to other accounts. It is an example of a canister that uses an ICRC-1 ledger canister. Sample code is available in [Motoko](https://github.com/dfinity/examples/tree/master/motoko/token_transfer) and [Rust](https://github.com/dfinity/examples/tree/master/rust/token_transfer). ## Architecture @@ -12,54 +8,44 @@ The sample code revolves around one core transfer function which takes as input This sample will use the Motoko variant. -## Prerequisites - +### Prerequisites This example requires an installation of: -- [x] Install the [IC SDK](https://internetcomputer.org/docs/current/developer-docs/setup/install/index.mdx). -- [x] Download and install [git](https://git-scm.com/downloads). - -## How to get there - -The following steps will guide you through the process of setting up the token transfer canister for your own project. +- [x] Install the [IC SDK](https://internetcomputer.org/docs/current/developer-docs/setup/install/index.mdx). -:::info +Begin by opening a terminal window. -If you just want to interact with this example, follow steps 4-8 and 10-12 below. +## Step 1: Setup the project environment -::: - -### Step 1: Create a new `dfx` project and navigate into the project's directory. +Start a local instance of the Internet Computer and create a new project with the commands: ```bash +dfx start --background dfx new --type=motoko token_transfer --no-frontend cd token_transfer ``` -### Step 2: Determine ICRC-1 ledger file locations - -:::info +## Step 2: Determine ICRC-1 ledger file locations -[Learn more about how to setup the ICRC-1 ledger locally](https://internetcomputer.org/docs/current/developer-docs/defi/icrc-1/icrc1-ledger-setup). +> [!TIP] +> [Learn more about how to setup the ICRC-1 ledger locally](https://internetcomputer.org/docs/current/developer-docs/defi/icrc-1/icrc1-ledger-setup) -::: +Go to the [releases overview](https://dashboard.internetcomputer.org/releases) and copy the latest replica binary revision. -Go to the [releases overview](https://dashboard.internetcomputer.org/releases) and copy the latest replica binary revision. At the time of writing, this is `d87954601e4b22972899e9957e800406a0a6b929`. +The URL for the ledger Wasm module is `https://download.dfinity.systems/ic//canisters/ic-icrc1-ledger.wasm.gz`. -The URL for the ledger Wasm module is `https://download.dfinity.systems/ic//canisters/ic-icrc1-ledger.wasm.gz`, so with the above revision it would be `https://download.dfinity.systems/ic/d87954601e4b22972899e9957e800406a0a6b929/canisters/ic-icrc1-ledger.wasm.gz`. - -The URL for the ledger .did file is `https://raw.githubusercontent.com/dfinity/ic//rs/rosetta-api/icrc1/ledger/ledger.did`, so with the above revision it would be `https://raw.githubusercontent.com/dfinity/ic/d87954601e4b22972899e9957e800406a0a6b929/rs/rosetta-api/icrc1/ledger/ledger.did`. +The URL for the ledger .did file is `https://raw.githubusercontent.com/dfinity/ic//rs/rosetta-api/icrc1/ledger/ledger.did`. **OPTIONAL:** If you want to make sure, you have the latest ICRC-1 ledger files you can run the following script. ```sh -curl -o download_latest_icrc1_ledger.sh "https://raw.githubusercontent.com/dfinity/ic/326df23607fc8280a047daba2d8462f1dfc57466/rs/rosetta-api/scripts/download_latest_icrc1_ledger.sh" +curl -o download_latest_icrc1_ledger.sh "https://raw.githubusercontent.com/dfinity/ic//rs/rosetta-api/scripts/download_latest_icrc1_ledger.sh" chmod +x download_latest_icrc1_ledger.sh ./download_latest_icrc1_ledger.sh ``` -### Step 3: Configure the `dfx.json` file to use the ledger : +## Step 3: Configure the `dfx.json` file to use the ledger Replace its contents with this but adapt the URLs to be the ones you determined in step 2: @@ -73,8 +59,8 @@ Replace its contents with this but adapt the URLs to be the ones you determined }, "icrc1_ledger_canister": { "type": "custom", - "candid": "https://raw.githubusercontent.com/dfinity/ic/d87954601e4b22972899e9957e800406a0a6b929/rs/rosetta-api/icrc1/ledger/ledger.did", - "wasm": "https://download.dfinity.systems/ic/d87954601e4b22972899e9957e800406a0a6b929/canisters/ic-icrc1-ledger.wasm.gz" + "candid": "https://raw.githubusercontent.com/dfinity/ic//rs/rosetta-api/icrc1/ledger/ledger.did", + "wasm": "https://download.dfinity.systems/ic//canisters/ic-icrc1-ledger.wasm.gz" } }, "defaults": { @@ -97,31 +83,23 @@ If you chose to download the ICRC-1 ledger files with the script, you need to re ... ``` -### Step 4: Start a local replica: - -```bash -dfx start --background --clean -``` - -### Step 5: Use the anonymous identity as the minting account: +## Step 4: Use the anonymous identity as the minting account ```bash export MINTER=$(dfx --identity anonymous identity get-principal) ``` -:::info - -Transfers from the minting account will create Mint transactions. Transfers to the minting account will create Burn transactions. +> [!TIP] +> Transfers from the minting account will create Mint transactions. Transfers to the minting account will create Burn transactions. -::: -### Step 6: Record your default identity's principal to mint an initial balance to when deploying the ledger: +## Step 5: Record your default identity's principal to mint an initial balance to when deploying the ledger ```bash export DEFAULT=$(dfx identity get-principal) ``` -### Step 7: Deploy the ICRC-1 ledger locally: +## Step 6: Deploy the ICRC-1 ledger locally Take a moment to read the details of the call made below. Not only are you deploying an ICRC-1 ledger canister, you are also: @@ -157,13 +135,10 @@ URLs: icrc1_ledger_canister: http://127.0.0.1:4943/?canisterId=bnz7o-iuaaa-aaaaa-qaaaa-cai&id=mxzaz-hqaaa-aaaar-qaada-cai ``` -### Step 8: Verify that the ledger canister is healthy and working as expected by using the command: +## Step 7: Verify that the ledger canister is healthy and working as expected by using the command -:::info - -[Learn more about how to interact with the ICRC-1 ledger](https://internetcomputer.org/docs/current/developer-docs/defi/icrc-1/using-icrc1-ledger#icrc-1-and-icrc-1-extension-endpoints). - -::: +> ![TIP] +> [Learn more about how to interact with the ICRC-1 ledger](https://internetcomputer.org/docs/current/developer-docs/defi/icrc-1/using-icrc1-ledger#icrc-1-and-icrc-1-extension-endpoints). ````bash dfx canister call icrc1_ledger_canister icrc1_balance_of "(record { @@ -178,7 +153,7 @@ The output should be: (10_000_000_000 : nat) ```` -### Step 9: Prepare the token transfer canister: +## Step 8: Prepare the token transfer canister Replace the contents of the `src/token_transfer_backend/main.mo` file with the following: @@ -238,19 +213,16 @@ actor { ``` -### Step 10: Deploy the token transfer canister: +## Step 9: Deploy the token transfer canister ```bash dfx deploy token_transfer_backend ``` -### Step 11: Transfer funds to your canister: - -:::info - -Make sure that you are using the default `dfx` account that we minted tokens to in step 7 for the following steps. +## Step 10: Transfer funds to your canister -::: +> [!TIP] +> Make sure that you are using the default `dfx` account that we minted tokens to in step 7 for the following steps. Make the following call to transfer 10 tokens to the canister: @@ -269,7 +241,7 @@ If successful, the output should be: (variant { Ok = 1 : nat }) ``` -### Step 12: Transfer funds from the canister: +## Step 11: Transfer funds from the canister Now that the canister owns tokens on the ledger, you can transfer 1 token from the canister to another account, in this case back to the default account: diff --git a/motoko/token_transfer_from/README.md b/motoko/token_transfer_from/README.md index adde72c79..0bc1270f4 100644 --- a/motoko/token_transfer_from/README.md +++ b/motoko/token_transfer_from/README.md @@ -1,9 +1,5 @@ # Token transfer_from -[View this samples code on GitHub](https://github.com/dfinity/examples/tree/master/motoko/token_transfer_from). - -## Overview - `token_transfer_from_backend` is a canister that can transfer ICRC-1 tokens on behalf of accounts to other accounts. It is an example of a canister that uses an ICRC-1 ledger canister that supports the [ICRC-2](https://github.com/dfinity/ICRC-1/tree/main/standards/ICRC-2) approve and transfer from standard. Sample code is available in [Motoko](https://github.com/dfinity/examples/tree/master/motoko/token_transfer_from) and [Rust](https://github.com/dfinity/examples/tree/master/rust/token_transfer_from). ## Architecture @@ -12,76 +8,59 @@ The sample code revolves around one core transfer function which takes as input This sample will use the Rust variant. -## Prerequisites - +### Prerequisites This example requires an installation of: -- [x] Install the [IC SDK](https://internetcomputer.org/docs/current/developer-docs/setup/install/index.mdx). -- [x] Download and install [git.](https://git-scm.com/downloads) +- [x] Install the [IC SDK](https://internetcomputer.org/docs/current/developer-docs/setup/install/index.mdx). -## How to get there +Begin by opening a terminal window. -The following steps will guide you through the process of setting up the token transfer canister for your own project. - -:::info +## Step 1: Setup the project environment -If you just want to interact with this example, follow steps 4-6 and 8-10 below. - -::: - -### Step 1: Create a new `dfx` project and navigate into the project's directory. +Start a local instance of the Internet Computer and create a new project with the commands: ```bash -dfx new --type=motoko token_transfer_from --no-frontend -cd token_transfer_from +dfx start --background +dfx new --type=motoko token_transfer --no-frontend +cd token_transfer ``` -### Step 2: Determine ICRC-1 ledger file locations +## Step 2: Determine ICRC-1 ledger file locations -:::info +> [!TIP] +> [Learn more about how to setup the ICRC-1 ledger locally](https://internetcomputer.org/docs/current/developer-docs/defi/icrc-1/icrc1-ledger-setup) -You can read more about how to setup the ICRC-1 ledger locally [here](https://internetcomputer.org/docs/current/developer-docs/defi/icrc-1/icrc1-ledger-setup). +Go to the [releases overview](https://dashboard.internetcomputer.org/releases) and copy the latest replica binary revision. -::: - -Go to the [releases overview](https://dashboard.internetcomputer.org/releases) and copy the latest replica binary revision. At the time of writing, this is `d87954601e4b22972899e9957e800406a0a6b929`. +The URL for the ledger Wasm module is `https://download.dfinity.systems/ic//canisters/ic-icrc1-ledger.wasm.gz`. -The URL for the ledger Wasm module is `https://download.dfinity.systems/ic//canisters/ic-icrc1-ledger.wasm.gz`, so with the above revision it would be `https://download.dfinity.systems/ic/d87954601e4b22972899e9957e800406a0a6b929/canisters/ic-icrc1-ledger.wasm.gz`. - -The URL for the ledger .did file is `https://raw.githubusercontent.com/dfinity/ic//rs/rosetta-api/icrc1/ledger/ledger.did`, so with the above revision it would be `https://raw.githubusercontent.com/dfinity/ic/d87954601e4b22972899e9957e800406a0a6b929/rs/rosetta-api/icrc1/ledger/ledger.did`. +The URL for the ledger .did file is `https://raw.githubusercontent.com/dfinity/ic//rs/rosetta-api/icrc1/ledger/ledger.did`. **OPTIONAL:** If you want to make sure, you have the latest ICRC-1 ledger files you can run the following script. ```sh -curl -o download_latest_icrc1_ledger.sh "https://raw.githubusercontent.com/dfinity/ic/326df23607fc8280a047daba2d8462f1dfc57466/rs/rosetta-api/scripts/download_latest_icrc1_ledger.sh" +curl -o download_latest_icrc1_ledger.sh "https://raw.githubusercontent.com/dfinity/ic//rs/rosetta-api/scripts/download_latest_icrc1_ledger.sh" chmod +x download_latest_icrc1_ledger.sh ./download_latest_icrc1_ledger.sh ``` -### Step 3: Configure the `dfx.json` file to use the ledger : - -Replace its contents with this but adapt the URLs to be the ones you determined in step 2. Note that we are deploying the ICRC-1 ledger to the same canister id the ckBTC ledger uses on mainnet. This will make it easier to interact with it later. +## Step 3: Configure the `dfx.json` file to use the ledger -:::info - -Don't forget to add the `icrc1_ledger_canister` as a dependency for `token_transfer_from_backend`, otherwise the build will fail. - -::: +Replace its contents with this but adapt the URLs to be the ones you determined in step 2: ```json { "canisters": { - "token_transfer_from_backend": { - "main": "src/token_transfer_from_backend/main.mo", + "token_transfer_backend": { + "main": "src/token_transfer_backend/main.mo", "type": "motoko", "dependencies": ["icrc1_ledger_canister"] }, "icrc1_ledger_canister": { "type": "custom", - "candid": "https://raw.githubusercontent.com/dfinity/ic/d87954601e4b22972899e9957e800406a0a6b929/rs/rosetta-api/icrc1/ledger/ledger.did", - "wasm": "https://download.dfinity.systems/ic/d87954601e4b22972899e9957e800406a0a6b929/canisters/ic-icrc1-ledger.wasm.gz", - "specified_id": "mxzaz-hqaaa-aaaar-qaada-cai" + "candid": "https://raw.githubusercontent.com/dfinity/ic//rs/rosetta-api/icrc1/ledger/ledger.did", + "wasm": "https://download.dfinity.systems/ic//canisters/ic-icrc1-ledger.wasm.gz" } }, "defaults": { @@ -97,26 +76,31 @@ Don't forget to add the `icrc1_ledger_canister` as a dependency for `token_trans If you chose to download the ICRC-1 ledger files with the script, you need to replace the Candid and Wasm file entries: -``` +```json ... "candid": icrc1_ledger.did, "wasm" : icrc1_ledger.wasm.gz, -... + ... ``` -### Step 4: Start a local replica: +## Step 4: Use the anonymous identity as the minting account ```bash -dfx start --background --clean +export MINTER=$(dfx --identity anonymous identity get-principal) ``` -### Step 5: Deploy the ICRC-1 ledger locally: +> [!TIP] +> Transfers from the minting account will create Mint transactions. Transfers to the minting account will create Burn transactions. -:::info -Transfers from the `minting_account` will create Mint transactions. Transfers to the minting account will create Burn transactions. +## Step 5: Record your default identity's principal to mint an initial balance to when deploying the ledger + +```bash +export DEFAULT=$(dfx identity get-principal) +``` + +## Step 6: Deploy the ICRC-1 ledger locally -::: Take a moment to read the details of the call made below. Not only are you deploying an ICRC-1 ledger canister, you are also: @@ -165,18 +149,16 @@ URLs: icrc1_ledger_canister: http://127.0.0.1:4943/?canisterId=bnz7o-iuaaa-aaaaa-qaaaa-cai&id=mxzaz-hqaaa-aaaar-qaada-cai ``` -### Step 6: Verify that the ledger canister is healthy and working as expected by using the command: - -:::info - -[Learn more about how to interact with the ICRC-1 ledger](https://internetcomputer.org/docs/current/developer-docs/defi/icrc-1/using-icrc1-ledger#icrc-1-and-icrc-1-extension-endpoints). +## Step 7: Verify that the ledger canister is healthy and working as expected by using the command -::: +> ![TIP] +> [Learn more about how to interact with the ICRC-1 ledger](https://internetcomputer.org/docs/current/developer-docs/defi/icrc-1/using-icrc1-ledger#icrc-1-and-icrc-1-extension-endpoints). ````bash dfx canister call icrc1_ledger_canister icrc1_balance_of "(record { - owner = principal \"$(dfx identity --identity default get-principal)\"; -})" + owner = principal \"${DEFAULT}\"; + } +)" ``` The output should be: @@ -185,7 +167,7 @@ The output should be: (10_000_000_000 : nat) ```` -### Step 7: Prepare the token transfer canister: +## Step 8: Prepare the token transfer canister Replace the contents of the `src/token_transfer_from_backend/main.mo` file with the following: @@ -234,7 +216,7 @@ actor { // initiate the transfer let transferFromResult = await Icrc1Ledger.icrc2_transfer_from(transferFromArgs); - // check if the transfer was successfull + // check if the transfer was successful switch (transferFromResult) { case (#Err(transferError)) { return #err("Couldn't transfer funds:\n" # debug_show (transferError)); @@ -250,13 +232,13 @@ actor { ``` -### Step 8: Deploy the token transfer canister: +## Step 9: Deploy the token transfer canister ```bash dfx deploy token_transfer_from_backend ``` -### Step 9: Approve the canister to transfer funds on behalf of the user: +## Step 10: Approve the canister to transfer funds on behalf of the user :::info @@ -283,7 +265,7 @@ If successful, the output should be: (variant { Ok = 1 : nat }) ``` -### Step 10: Let the canister transfer funds on behalf of the user: +## Step 11: Let the canister transfer funds on behalf of the user Now that the canister has an approval for the `default` identities tokens on the ledger, the canister can transfer 1 token on behalf of the `default` identity to another account, in this case to the canisters own account. diff --git a/motoko/vetkd/README.md b/motoko/vetkd/README.md index a5a3de0ee..a7c5a5be1 100644 --- a/motoko/vetkd/README.md +++ b/motoko/vetkd/README.md @@ -1,11 +1,5 @@ ---- -keywords: [advanced, motoko, vetkd, vetkeys] ---- - # vetKD API -[View this sample's code on GitHub](https://github.com/dfinity/examples/tree/master/motoko/vetkd) - This repository provides a canister (`src/system_api`) that offers the vetKD system API proposed in https://github.com/dfinity/interface-spec/pull/158, implemented in an **unsafe** manner **for demonstration purposes**. Additionally, the repository provides: @@ -21,38 +15,33 @@ Additionally, the repository provides: The implementation of [the proposed vetKD system API](https://github.com/dfinity/interface-spec/pull/158) used in this example is **unsafe**, e.g., we hard-code a master secret key, rather than using a master secret key that is distributed among sufficiently many Internet Computer nodes through distributed key generation. **Do not use this in production or for sensitive data**! This example is solely provided **for demonstration purposes** to collect feedback on the mentioned vetKD system API. See also the respective disclaimer [in the system API canister implementation](https://github.com/dfinity/examples/blob/master/rust/vetkd/src/system_api/src/lib.rs#L19-L26). -## Prerequisites -- [x] Install the [IC SDK](https://internetcomputer.org/docs/current/developer-docs/setup/install/). -- [x] Install [Node.js](https://nodejs.org/en/download/). +### Prerequisites +This example requires an installation of: + +- [x] Install the [IC SDK](https://internetcomputer.org/docs/current/developer-docs/setup/install/index.mdx). - [x] Install [Rust](https://www.rust-lang.org/tools/install), and add Wasm as a target (`rustup target add wasm32-unknown-unknown`). Note that Rust is only needed for compiling the (insecure) canister offering the vetKD system API, which later would be directly integrated into ICP. - [x] Clone the example dapp project: `git clone https://github.com/dfinity/examples` -## Running locally +Begin by opening a terminal window. -- #### Step 1: Start a local replica: +## Step 1: Setup the project environment -```sh -dfx start -``` +Navigate into the folder containing the project's files and start a local instance of the Internet Computer with the commands: -- #### Step 2: Open a new terminal window. +```bash +cd examples/motoko/vetkd +dfx start --background +``` -- #### Step 3: Ensure `dfx` uses the canister IDs that are hard-coded in the Rust source code: +## Step 2: Ensure `dfx` uses the canister IDs that are hard-coded in the Rust source code: -```sh -cd examples/motoko/vetkd +```bash dfx canister create system_api --specified-id s55qq-oqaaa-aaaaa-aaakq-cai ``` Without this, `dfx` may use different canister IDs for the `system_api` and `app_backend` canisters in your local environment. -- #### Step 4: Ensure that the required node modules are available in your project directory, if needed, by running the following command: - -```sh -npm install -``` - -- #### Step 5: Register, build, and deploy the project: +## Step 3: Register, build, and deploy the project: ```sh dfx deploy @@ -71,4 +60,4 @@ Backend canister via Candid interface: system_api: http://127.0.0.1:4943/?canisterId=avqkn-guaaa-aaaaa-qaaea-cai&id=s55qq-oqaaa-aaaaa-aaakq-cai ``` -- #### Step 6: Open the printed URL for the `app_frontend_js` in your browser. +## Step 4: Open the printed URL for the `app_frontend_js` in your browser. diff --git a/motoko/whoami/README.md b/motoko/whoami/README.md index 23248ea03..1824097ff 100644 --- a/motoko/whoami/README.md +++ b/motoko/whoami/README.md @@ -1,17 +1,8 @@ ---- -keywords: [beginner, motoko, who am i, whoami] ---- - # Who am I? -[View this sample's code on GitHub](https://github.com/dfinity/examples/tree/master/motoko/whoami) - -## Overview - This example demonstrates how a canister can identify its caller and itself. -## Prerequisites - +### Prerequisites This example requires an installation of: - [x] Install the [IC SDK](https://internetcomputer.org/docs/current/developer-docs/setup/install/index.mdx). @@ -19,14 +10,16 @@ This example requires an installation of: Begin by opening a terminal window. -### Step 1: Navigate into the folder containing the project's files and start a local instance of the replica with the command: +## Step 1: Setup the project environment + +Navigate into the folder containing the project's files and start a local instance of the Internet Computer with the commands: ```bash cd examples/motoko/whoami dfx start --background ``` -### Step 2: Build and deploy the canister: +## Step 2: Build and deploy the canister ```bash dfx canister install whoami --argument='(principal "2mxjj-pyyts-rk2hl-2xyka-avylz-dfama-pqui5-pwrhx-wtq2x-xl5lj-qqe")' @@ -34,21 +27,21 @@ dfx build dfx deploy ``` -### Step 3: Invoke the `whoami` method: +## Step 3: Invoke the `whoami` method ```bash dfx canister call whoami whoami ``` -### Step 4: Observe your principal identifier. +## Step 4: Observe your principal identifier -### Step 5: Invoke the `id` method: +## Step 5: Invoke the `id` method ```bash dfx canister call whoami id ``` -### Step 6: Observe the principal identifier of your canister. +## Step 6: Observe the principal identifier of your canister ## Security considerations and best practices