Update Motoko project READMEs

dfinity · Dec 18, 2024 · e876b1a · e876b1a
1 parent 786c2e9
commit e876b1a
Show file tree

Hide file tree

Showing 28 changed files with 429 additions and 651 deletions.
diff --git 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
@@ -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
@@ -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
@@ -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
@@ -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
 <!doctype html>
@@ -230,14 +232,14 @@ app.listen(8000, function () {
 </html>
 ```
 
-### 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/