diff --git a/hosting/godot-html5-template/README.md b/hosting/godot-html5-template/README.md
index 5fd9ac537..7efa95296 100644
--- a/hosting/godot-html5-template/README.md
+++ b/hosting/godot-html5-template/README.md
@@ -1,41 +1,41 @@
-# Godot HTML5 Sample
+# Godot HTML5 sample
+## Overview
The example shows how to deploy a Godot HTML5 build on the IC in an asset canister. The Godot HTML5 build is deployed as frontend, no backend is needed in this sample.
-
-## Installation
This example project can be cloned, installed and deployed locally, for learning and testing purposes. The instructions are based on running the example on either macOS or Linux, but when using WSL2 on Windows, the instructions will be the same.
-### Prerequisites
-The example project requires the following installed:
+## Prerequisites
+
+This example requires an installation of:
+
+- [x] Install the [IC SDK](https://internetcomputer.org/docs/current/developer-docs/setup/install/).
-- git
-- dfx
+- [x] Download and install [git](https://git-scm.com/downloads).
-git can be installed from various package managers. DFX can be installed following the instructions [here](https://internetcomputer.org/docs/current/developer-docs/build/install-upgrade-remove).
+## Install
-### Download the code
Clone the example dapp project:
```bash
-$ git clone https://github.com/dfinity/examples
-$ cd examples/hosting/godot-html5-template
+git clone https://github.com/dfinity/examples
+cd examples/hosting/godot-html5-template
```
## Deployment
-The local network is started by running this command:
+The local replica is started by running this command:
```bash
-$ dfx start --background
+dfx start --background
```
-When the local network is up and running, run this command to deploy the canisters:
+When the local replica is up and running, run this command to deploy the canisters:
```bash
-$ dfx deploy
+dfx deploy
```
If you get error code 500 after deploying to the IC mainnet, try to use `raw` keyword in the URL like this: `https://\.raw.ic0.app`.
## License
-This project is licensed under the Apache 2.0 license, see LICENSE.md for details. See CONTRIBUTE.md for details about how to contribute to this project.
+This project is licensed under the Apache 2.0 license, see `LICENSE.md` for details. See `CONTRIBUTE.md` for details about how to contribute to this project.
diff --git a/hosting/photo-storage/README.md b/hosting/photo-storage/README.md
index ba0885483..28a7b045a 100644
--- a/hosting/photo-storage/README.md
+++ b/hosting/photo-storage/README.md
@@ -3,35 +3,31 @@
The example shows how to store photos on the IC in an asset canister with the `@dfinity/assets` package. The photo
storage app is deployed as a frontend in an asset canister which is also used for photo upload.
-## Installation
-
This example project can be cloned, installed and deployed locally, for learning and testing purposes. The instructions
are based on running the example on either macOS or Linux, but when using WSL2 on Windows, the instructions will be the
same.
-### Prerequisites
+## Prerequisites
-The example project requires the following installed:
+This example requires an installation of:
-- git
-- dfx
-- npm
+- [x] Install the [IC SDK](https://internetcomputer.org/docs/current/developer-docs/setup/install/).
-git and npm can be installed from various package managers. DFX can be installed following the
-instructions [here](https://internetcomputer.org/docs/current/developer-docs/build/install-upgrade-remove).
+- [x] Download and install [git](https://git-scm.com/downloads).
-### Download the code
+- [x] Download and install [Node.js](https://nodejs.org/en).
+## Install
Clone the example dapp project:
```bash
-$ git clone https://github.com/dfinity/examples
-$ cd examples/hosting/photo-storage
+git clone https://github.com/dfinity/examples
+cd examples/hosting/photo-storage
```
## React build
-The React frontend is build by running this command:
+The React frontend is built by running:
```bash
npm install
@@ -40,34 +36,34 @@ npm run build
## Deployment
-The local network is started by running this command:
+The local replica is started by running:
```bash
-$ dfx start --clean --background
+dfx start --clean --background
```
-When the local network is up and running, run this command to deploy the canisters:
+When the local replica is up and running, run this command to deploy the canisters:
```bash
-$ dfx deploy
+dfx deploy
```
## Authorization
-To authorize the identity from this example project on a local network to upload files, it must be authorized first:
+To authorize an identity to upload files, it must be authorized first:
```bash
dfx canister call photo-storage authorize '(principal "535yc-uxytb-gfk7h-tny7p-vjkoe-i4krp-3qmcl-uqfgr-cpgej-yqtjq-rqe")'
```
-Before deployment on the IC, the hardcoded identity (defined in `src/App.js`) should be replaced by an authentication
-method e.g. Internet Identity.
+Before deployment on ICP, the hardcoded identity (defined in `src/App.js`) should be replaced by an authentication
+method such as Internet Identity.
-## Cats
+## Example photos
The example cat stock photos are from [Pexels](https://www.pexels.com/license/).
## License
-This project is licensed under the Apache 2.0 license, see LICENSE.md for details. See CONTRIBUTE.md for details about
+This project is licensed under the Apache 2.0 license, see `LICENSE.md` for details. See `CONTRIBUTE.md` for details about
how to contribute to this project.
diff --git a/hosting/static-website/README.md b/hosting/static-website/README.md
index 4d694f9c4..91f93233f 100644
--- a/hosting/static-website/README.md
+++ b/hosting/static-website/README.md
@@ -1,9 +1,10 @@
# Static website
+
+## Overview
The example shows how to deploy a simple, static website on the IC in an asset canister. The website is very simple, it just shows the DFINITY logo and has a basic styling of the logo.
-## Introduction
The purpose of this example is to show how to deploy a static website in an asset canister. While the website in this example is very simple, the method would be the same for a more advanced static website, e.g. based on popular static site generators.
This example covers:
@@ -13,30 +14,27 @@ This example covers:
- Deploy the canister smart contract locally
- Test the frontend in browser
-## Installation
-This example project can be cloned, installed and deployed locally, for learning and testing purposes. The instructions are based on running the example on either macOS or Linux, but when using WSL2 on Windows, the instructions will be the same.
+## Prerequisites
-### Prerequisites
-The example project requires the following installed:
+This example requires an installation of:
-- git
-- dfx
+- [x] Install the [IC SDK](https://internetcomputer.org/docs/current/developer-docs/setup/install/).
-git can be installed from various package managers. DFX can be installed following the instructions [here](https://internetcomputer.org/docs/current/developer-docs/setup/deploy-locally).
+- [x] Download and install [git](https://git-scm.com/downloads).
### Install
Install the example dapp project:
```bash
-$ git clone https://github.com/dfinity/examples
-$ cd examples/hosting/static-website
+git clone https://github.com/dfinity/examples
+cd examples/hosting/static-website
```
## Documentation
There are two parts in this dapp. One is the website and the other is `dfx.json`. Since there's no backend, there is not any benefit of using the `dfx new project_name` command to set up a template. The `dfx.json` file is all that is needed.
### Website
-The website is really simple. It consists of an HTML file, a CSS file and a PNG file. The content of the HTML file looks like this:
+The website is simple. It consists of an HTML file, a CSS file and a PNG file. The content of the HTML file looks like this:
```html
@@ -105,16 +103,16 @@ The `dfx.json` file is a configuration file which specifies the canister used fo
This is all needed for creating a canister smart contract for hosting a static website on the IC.
## Deployment
-The local network is started by running this command:
+The local replica is started by running:
```bash
-$ dfx start --background
+dfx start --background
```
-When the local network is up and running, run this command to deploy the canisters:
+When the local replica is up and running, run this command to deploy the canisters:
```bash
-$ dfx deploy
+dfx deploy
```
@@ -126,4 +124,4 @@ The URL for the frontend depends on the canister ID. Local canister IDs can be
## License
-This project is licensed under the Apache 2.0 license, see LICENSE.md for details. See CONTRIBUTE.md for details about how to contribute to this project.
+This project is licensed under the Apache 2.0 license, see `LICENSE.md` for details. See `CONTRIBUTE.md` for details about how to contribute to this project.
diff --git a/hosting/unity-webgl-template/README.md b/hosting/unity-webgl-template/README.md
index ec247003c..e4a43d250 100644
--- a/hosting/unity-webgl-template/README.md
+++ b/hosting/unity-webgl-template/README.md
@@ -1,43 +1,39 @@
-# Unity WebGL Sample
+# Unity WebGL sample
The example shows how to deploy a simple Unity WebGL build on the IC in an asset canister. It just shows a Unity WebGL build with the URP template installed.
The Unity WebGL build is deployed as frontend, no backend is needed in this sample.
+## Prerequisites
-## Installation
-This example project can be cloned, installed and deployed locally, for learning and testing purposes. The instructions are based on running the example on either macOS or Linux, but when using WSL2 on Windows, the instructions will be the same.
+This example requires an installation of:
-### Prerequisites
-The example project requires the following installed:
+- [x] Install the [IC SDK](https://internetcomputer.org/docs/current/developer-docs/setup/install/).
-- git
-- dfx
+- [x] Download and install [git](https://git-scm.com/downloads).
-git can be installed from various package managers. DFX can be installed following the instructions [here](https://internetcomputer.org/docs/current/developer-docs/setup/deploy-locally).
-
-### Install
+## Install
Install the example dapp project:
```bash
-$ git clone https://github.com/dfinity/examples
-$ cd examples/hosting/unity-webgl-template
+git clone https://github.com/dfinity/examples
+cd examples/hosting/unity-webgl-template
```
## Deployment
-The local network is started by running this command:
+The local replica is started by running this command:
```bash
-$ dfx start --background
+dfx start --background
```
-When the local network is up and running, run this command to deploy the canisters:
+When the local replica is up and running, run this command to deploy the canisters:
```bash
-$ dfx deploy
+dfx deploy
```
If you get error code 500 after deploying to the IC mainnet, try to use `raw` keyword in the URL like this: `https://\.raw.ic0.app`.
## License
-This project is licensed under the Apache 2.0 license, see LICENSE.md for details. See CONTRIBUTE.md for details about how to contribute to this project.
+This project is licensed under the Apache 2.0 license, see `LICENSE.md` for details. See `CONTRIBUTE.md` for details about how to contribute to this project.
diff --git a/motoko/actor_reference/README.md b/motoko/actor_reference/README.md
index d79451415..e1e38721c 100644
--- a/motoko/actor_reference/README.md
+++ b/motoko/actor_reference/README.md
@@ -1,8 +1,3 @@
-# Actor references
-
-
-[](https://github.com/dfinity/examples/actions?query=workflow%3Amotoko-actor_reference-example)
-
# Actor reference
## Overview
@@ -33,28 +28,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 Internet Computer 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:
-```
+```bash
cd examples/motoko/actor-reference
dfx start --background
```
### Step 2: Deploy the canister:
-```
+```bash
dfx deploy
```
### Step 3: Invoke the `burn` method of canister `actor_reference`:
-```
+```bash
dfx canister call actor_reference burn '()'
```
The output will resemble the following:
-```
+```bash
[Canister by6od-j4aaa-aaaaa-qaadq-cai] balance before: 3091661916488
[Canister by6od-j4aaa-aaaaa-qaadq-cai] cycles: 1538138650552
[Canister by6od-j4aaa-aaaaa-qaadq-cai] balance after: 1545830657728
@@ -65,6 +60,6 @@ The output will resemble the following:
- [Actors and sync data](https://internetcomputer.org/docs/current/motoko/main/actors-async).
- [Basic Motoko concepts and terms](https://internetcomputer.org/docs/current/motoko/main/basic-concepts).
-# Security Considerations and Security Best Practices
+# Security considerations best practices
-If you base your application on this example, we recommend you familiarize yourself with and adhere to the [Security Best Practices](https://internetcomputer.org/docs/current/references/security/) for developing on the Internet Computer. This example may not implement all the best practices.
+If you base your application on this example, we recommend you familiarize yourself with and adhere to the [Security Best Practices](https://internetcomputer.org/docs/current/references/security/) for developing on ICP. This example may not implement all the best practices.
diff --git a/motoko/auth_client_demo/README.md b/motoko/auth_client_demo/README.md
index b997a6df4..c7b972d20 100644
--- a/motoko/auth_client_demo/README.md
+++ b/motoko/auth_client_demo/README.md
@@ -1,4 +1,4 @@
-# Auth-Client Demo
+# Auth-client
This is an example project, intended to demonstrate how an app developer might integrate with an [Internet Identity](https://identity.ic0.app).
@@ -23,7 +23,7 @@ Once deployed, start the development server with `npm start`.
You can now access the app at `http://127.0.0.1:5173/`.
-## Multiple Versions
+## Multiple versions
This demo has multiple versions, each of which demonstrates a different feature of the auth-client. `npm start` will run the vanilla JS version, but you can run the others by running `npm run start:version` where `version` is one of the following:
@@ -36,7 +36,7 @@ This demo has multiple versions, each of which demonstrates a different feature
To pull Internet Identity into your own project, you'll need to do the following:
-1. Add Internet Identity to your `dfx.json` file:
+- #### Step 1: Add Internet Identity to your `dfx.json` file:
```json
"internet-identity" : {
@@ -45,7 +45,7 @@ To pull Internet Identity into your own project, you'll need to do the following
}
```
-2. Run the following commands to install the dependencies:
+- #### Step 2: Run the following commands to install the dependencies:
```bash
dfx deps pull
diff --git a/motoko/basic_bitcoin/README.md b/motoko/basic_bitcoin/README.md
index ef408d3ad..91de7e26b 100644
--- a/motoko/basic_bitcoin/README.md
+++ b/motoko/basic_bitcoin/README.md
@@ -1,4 +1,4 @@
-# Basic Bitcoin example
+# Basic Bitcoin
## Deploying your first Bitcoin dapp
@@ -20,10 +20,6 @@ For deeper understanding of the ICP < > BTC integration, see the IC wiki article
### Clone the smart contract
-This tutorial has the **same smart contract** written in different programming languages: in [Motoko](https://internetcomputer.org/docs/current/developer-docs/backend/motoko/index.md) and [Rust](https://internetcomputer.org/docs/current/developer-docs/backend/rust/index.md).
-
-You can clone and deploy either one, as they both function in the same way.
-
To clone and build the smart contract in **Motoko**:
```bash
@@ -32,7 +28,6 @@ cd examples/motoko/basic_bitcoin
git submodule update --init --recursive
```
-
### Acquire cycles to deploy
Deploying to the Internet Computer requires [cycles](https://internetcomputer.org/docs/current/developer-docs/setup/cycles) (the equivalent of "gas" in other blockchains). You can get free cycles from the [cycles faucet](https://internetcomputer.org/docs/current/developer-docs/setup/cycles/cycles-faucet.md).
@@ -81,7 +76,9 @@ generate a P2PKH Bitcoin address.
Or, if you prefer the command line:
- dfx canister --network=ic call basic_bitcoin get_p2pkh_address
+```bash
+dfx canister --network=ic call basic_bitcoin get_p2pkh_address
+```
* The Bitcoin address you see will be different from the one above, because the
ECDSA public key your canister retrieves is unique.
@@ -90,19 +87,19 @@ Or, if you prefer the command line:
used for sending/receiving Bitcoin on the Bitcoin testnet.
-## Step 3: Receiving Bitcoin
+## Step 3: Receiving bitcoin
Now that the canister is deployed and you have a Bitcoin address, it's time to receive
-some testnet Bitcoin. You can use one of the Bitcoin faucets, such as [coinfaucet.eu](https://coinfaucet.eu),
+some testnet bitcoin. You can use one of the Bitcoin faucets, such as [coinfaucet.eu](https://coinfaucet.eu),
to receive some bitcoin.
-Enter your address and click on "Send testnet Bitcoins". In the example below we will use bitcoin address `n31eU1K11m1r58aJMgTyxGonu7wSMoUYe7`, but you would use your own address. The canister will be receiving 0.011 test BTC on the Bitcoin Testnet.
+Enter your address and click on "Send testnet bitcoins". In the example below we will use Bitcoin address `n31eU1K11m1r58aJMgTyxGonu7wSMoUYe7`, but you would use your own address. The canister will be receiving 0.011 test BTC on the Bitcoin Testnet.
Once the transaction has at least one confirmation, which can take a few minutes,
you'll be able to see it in your canister's balance.
-## Step 4: Checking your Bitcoin balance
+## Step 4: Checking your bitcoin balance
You can check a Bitcoin address's balance by using the `get_balance` endpoint on your canister.
@@ -110,22 +107,26 @@ In the Candid UI, paste in your canister's address, and click on "Call".
Alternatively, make the call using the command line. Be sure to replace `mheyfRsAQ1XrjtzjfU1cCH2B6G1KmNarNL` with your own generated P2PKH address:
- dfx canister --network=ic call basic_bitcoin get_balance '("mheyfRsAQ1XrjtzjfU1cCH2B6G1KmNarNL")'
+```bash
+dfx canister --network=ic call basic_bitcoin get_balance '("mheyfRsAQ1XrjtzjfU1cCH2B6G1KmNarNL")'
+```
Checking the balance of a Bitcoin address relies on the [bitcoin_get_balance](https://internetcomputer.org/docs/current/references/ic-interface-spec/#ic-bitcoin_get_balance) API.
-## Step 5: Sending Bitcoin
+## Step 5: Sending bitcoin
-You can send Bitcoin using the `send` endpoint on your canister.
+You can send bitcoin using the `send` endpoint on your canister.
In the Candid UI, add a destination address and an amount to send. In the example
below, we're sending 4'321 Satoshi (0.00004321 BTC) back to the testnet faucet.
Via command line, the same call would look like this:
- dfx canister --network=ic call basic_bitcoin send '(record { destination_address = "tb1ql7w62elx9ucw4pj5lgw4l028hmuw80sndtntxt"; amount_in_satoshi = 4321; })'
+```bash
+dfx canister --network=ic call basic_bitcoin send '(record { destination_address = "tb1ql7w62elx9ucw4pj5lgw4l028hmuw80sndtntxt"; amount_in_satoshi = 4321; })'
+```
-The `send` endpoint is able to send Bitcoin by:
+The `send` endpoint is able to send bitcoin by:
1. Getting the percentiles of the most recent fees on the Bitcoin network using the [bitcoin_get_current_fee_percentiles API](https://internetcomputer.org/docs/current/references/ic-interface-spec/#ic-bitcoin_get_current_fee_percentiles).
2. Fetching your unspent transaction outputs (UTXOs), using the [bitcoin_get_utxos API](https://internetcomputer.org/docs/current/references/ic-interface-spec/#ic-bitcoin_get_utxos).
@@ -155,7 +156,7 @@ This example is extensively documented in the following tutorials:
* [Deploying your first Bitcoin dapp](https://internetcomputer.org/docs/current/samples/deploying-your-first-bitcoin-dapp).
* [Developing Bitcoin dapps locally](https://internetcomputer.org/docs/current/developer-docs/integrations/bitcoin/local-development).
-## Security considerations and security best practices
+## Security considerations and best practices
If you base your application on this example, we recommend you familiarize yourself with and adhere to the [security best practices](https://internetcomputer.org/docs/current/references/security/) for developing on the Internet Computer. This example may not implement all the best practices.
diff --git a/motoko/basic_dao/README.md b/motoko/basic_dao/README.md
index 2c244c0ca..b1e76e6e8 100644
--- a/motoko/basic_dao/README.md
+++ b/motoko/basic_dao/README.md
@@ -1,4 +1,4 @@
-# Basic decentralized autonomous organization (DAO)
+# 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).
@@ -12,14 +12,6 @@ Certain system parameters, like the number of `Yes` votes needed to pass a propo
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.
-## Security considerations and security best practices
-
-If you base your application on this example, we recommend you familiarize yourself with and adhere to the [security best practices](https://internetcomputer.org/docs/current/references/security/) for developing on the Internet Computer. This example may not implement all the best practices.
-
-For example, the following aspects are particularly relevant for this app:
-* [Use a decentralized governance system like SNS to make a canister have a decentralized controller](https://internetcomputer.org/docs/current/references/security/rust-canister-development-security-best-practices#use-a-decentralized-governance-system-like-sns-to-make-a-canister-have-a-decentralized-controller), since this is a DAO's use case.
-* [Certify query responses if they are relevant for security](https://internetcomputer.org/docs/current/references/security/general-security-best-practices#certify-query-responses-if-they-are-relevant-for-security), since e.g. account_balance and list_accounts are query calls that a client may want to issue as update call.
-
### Prerequisites
This example requires an installation of:
@@ -30,19 +22,21 @@ 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:
-`cd basic_dao`
-`dfx start --background`
+```bash
+cd basic_dao
+dfx start --background
+```
### Step 2: 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.
-```
+```bash
dfx deploy --argument "(record {
accounts = vec { record { owner = principal \"$ALICE\"; tokens = record { amount_e8s = 100_000_000 }; };
record { owner = principal \"$BOB\"; tokens = record { amount_e8s = 100_000_000 };}; };
@@ -57,8 +51,15 @@ dfx deploy --argument "(record {
### Step 4: Run the ic-repl test scripts:
-```
+```bash
ic-repl tests/account.test.sh
ic-repl tests/proposal.test.sh
```
+## Security considerations and best practices
+
+If you base your application on this example, we recommend you familiarize yourself with and adhere to the [security best practices](https://internetcomputer.org/docs/current/references/security/) for developing on the Internet Computer. This example may not implement all the best practices.
+
+For example, the following aspects are particularly relevant for this app:
+* [Use a decentralized governance system like SNS to make a canister have a decentralized controller](https://internetcomputer.org/docs/current/references/security/rust-canister-development-security-best-practices#use-a-decentralized-governance-system-like-sns-to-make-a-canister-have-a-decentralized-controller), since this is a DAO's use case.
+* [Certify query responses if they are relevant for security](https://internetcomputer.org/docs/current/references/security/general-security-best-practices#certify-query-responses-if-they-are-relevant-for-security), since e.g. account_balance and list_accounts are query calls that a client may want to issue as update call.
diff --git a/motoko/calc/README.md b/motoko/calc/README.md
index 471303ff3..8fbe34946 100644
--- a/motoko/calc/README.md
+++ b/motoko/calc/README.md
@@ -25,35 +25,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: Navigate into the folder containing the project's files and start a local instance of the replica with the command:
-```
+```bash
cd examples/motoko/calc
dfx start --background
```
### Step 2: Deploy the canister with the command:
-```
+```bash
dfx deploy
```
### Step 3: Run a calculator function. For example, to multiple 2 by 3:
-```
+```bash
dfx canister call calc add '(2)'
dfx canister call calc mul '(3)'
```
Output:
-```
+```bash
(2 : int)
(6 : int)
```
-## Security considerations and security best practices
+## Security considerations and best practices
If you base your application on this example, we recommend you familiarize yourself with and adhere to the [security best practices](https://internetcomputer.org/docs/current/references/security/) for developing on the Internet Computer. This example may not implement all the best practices.
diff --git a/motoko/cert-var/README.md b/motoko/cert-var/README.md
index 3410d49f4..b8cfb405e 100644
--- a/motoko/cert-var/README.md
+++ b/motoko/cert-var/README.md
@@ -1,8 +1,5 @@
# Certified variables
-
-[](https://github.com/dfinity/examples/actions?query=workflow%3Amotoko-cert-var-example)
-
## Overview
This example demonstrates the use of a single cryptographically certified variable, as supported by the Internet Computer.
@@ -43,7 +40,6 @@ Notably, in an example with more data in the canister than a single number, or a
This is a Motoko example that does not currently have a Rust variant.
-
## Prerequisites
This example requires an installation of:
@@ -54,26 +50,26 @@ 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:
-```
+```bash
cd examples/motoko/cert-var
dfx start --background
```
### Step 2: Install the front-end dependencies:
-```
+```bash
npm install
```
### Step 3: Deploy the canister:
-```
+```bash
dfx deploy
```
### Step 4: Next, open the `webpack.config.js` file and replace the contents with the following:
-```
+```javascript
const path = require("path");
const webpack = require("webpack");
const HtmlWebpackPlugin = require("html-webpack-plugin");
@@ -187,7 +183,7 @@ module.exports = {
### Step 5: Create a new file called `server.js` with the following content:
-```
+```javascript
var express = require('express');
var app = express();
@@ -202,7 +198,7 @@ app.listen(8000, function () {
### Step 6: Replace the content of the `src/cert_var_assets/src/index.html` with the following content:
-```
+```html
@@ -227,16 +223,16 @@ app.listen(8000, function () {
```
-### Step 7: Start a local web server that hosts the front-end.
+### 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:
-```
+```bash
http://localhost:8080/
```
@@ -247,7 +243,7 @@ Enter a number and click the button.
The canister updates its certificate, and the frontend checks it. The developer console contains some additional comments about each step.
-## Security considerations and security best practices
+## Security considerations and best practices
If you base your application on this example, we recommend you familiarize yourself with and adhere to the [security best practices](https://internetcomputer.org/docs/current/references/security/) for developing on the Internet Computer. This example may not implement all the best practices.
diff --git a/motoko/classes/README.md b/motoko/classes/README.md
index a092ed47f..e856a782d 100644
--- a/motoko/classes/README.md
+++ b/motoko/classes/README.md
@@ -1,4 +1,4 @@
-# Actor Classes
+# Classes
[](https://github.com/dfinity/examples/actions?query=workflow%3Amotoko-classes-example)
@@ -33,26 +33,26 @@ 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:
-```
+```bash
cd examples/motoko/classes
dfx start --background
```
### Step 2: Deploy the canisters `Map` and `Test`:
-```
+```bash
dfx deploy
```
### Step 3: Invoke the run method of canister Test:
-```
+```bash
dfx canister call Test run '()'
```
The output should resemble the following:
-```
+```bash
debug.print: putting: (0, "0")
debug.print: putting: (1, "1")
debug.print: putting: (2, "2")
@@ -80,6 +80,6 @@ debug.print: putting: (23, "23")
()
```
-## Security considerations and security best practices
+## Security considerations and best practices
If you base your application on this example, we recommend you familiarize yourself with and adhere to the [security best practices](https://internetcomputer.org/docs/current/references/security/) for developing on the Internet Computer. This example may not implement all the best practices.
diff --git a/motoko/composite_query/README.md b/motoko/composite_query/README.md
index a875f3055..9d9b1d4de 100644
--- a/motoko/composite_query/README.md
+++ b/motoko/composite_query/README.md
@@ -1,7 +1,6 @@
-# Composite Queries
+# Composite queries
-
-[](https://github.com/dfinity/examples/actions?query=workflow%3Amotoko-classes-example)
+## Overview
This example modifies the simple actor class example to demonstrate the implementation of composite queries.
@@ -30,11 +29,6 @@ Each new `Bucket` must be provisioned with enough cycles to pay for its installa
`Map`'s `test` method simply `put`s 16 consecutive entries into `Map`. These entries are distributed evenly amongst the buckets making up the key-value store. Adding the first entry to a bucket takes longer than adding a subsequent one, since the bucket needs to be installed on first use.
-
-## Security Considerations and Security Best Practices
-
-If you base your application on this example, we recommend you familiarize yourself with and adhere to the [Security Best Practices](https://internetcomputer.org/docs/current/references/security/) for developing on the Internet Computer. This example may not implement all the best practices.
-
## Prerequisites
Verify the following before running this demo:
@@ -45,75 +39,68 @@ Verify the following before running this demo:
* You have stopped any Internet Computer or other network process that would
create a port conflict on 8000.
-## Demo
-
-1. Start a local internet computer.
+## Install
- ```text
- dfx start
- ```
+### Step 1: Start a local internet computer.
- (Alternatively, the example will run faster if you use the emulator, not a full replica:
- ```
- dfx start --emulator
- ```
- )
+```bash
+dfx start
+```
-2. Open a new terminal window.
+### Step 2: Open a new terminal window.
-3. Deploy the `Map` canister:
+### Step 3: Deploy the `Map` canister:
- ```text
- dfx deploy
- ```
+```bash
+dfx deploy
+```
-4. Invoke the `test` method of canister `Map` to add some entries
+### Step 4: Invoke the `test` method of canister `Map` to add some entries:
- ```text
- dfx canister call Map test '()'
- ```
+```bash
+dfx canister call Map test '()'
+```
-5. Observe the following result.
+### Step 5: Observe the following result.
- ```text
- debug.print: putting: (0, "0")
- debug.print: putting: (1, "1")
- debug.print: putting: (2, "2")
- debug.print: putting: (3, "3")
- debug.print: putting: (4, "4")
- debug.print: putting: (5, "5")
- debug.print: putting: (6, "6")
- debug.print: putting: (7, "7")
- debug.print: putting: (8, "8")
- debug.print: putting: (9, "9")
- debug.print: putting: (10, "10")
- debug.print: putting: (11, "11")
- debug.print: putting: (12, "12")
- debug.print: putting: (13, "13")
- debug.print: putting: (14, "14")
- debug.print: putting: (15, "15")
- ()
- ```
+```bash
+debug.print: putting: (0, "0")
+debug.print: putting: (1, "1")
+debug.print: putting: (2, "2")
+debug.print: putting: (3, "3")
+debug.print: putting: (4, "4")
+debug.print: putting: (5, "5")
+debug.print: putting: (6, "6")
+debug.print: putting: (7, "7")
+debug.print: putting: (8, "8")
+debug.print: putting: (9, "9")
+debug.print: putting: (10, "10")
+debug.print: putting: (11, "11")
+debug.print: putting: (12, "12")
+debug.print: putting: (13, "13")
+debug.print: putting: (14, "14")
+debug.print: putting: (15, "15")
+()
+```
-6. Invoke the `get` composite query method of canister `Main`
+### Step 6: Invoke the `get` composite query method of canister `Main`:
- ```text
- dfx canister call --query Map get '(15)'
- ```
+```bash
+dfx canister call --query Map get '(15)'
+```
-7. Observe the following result.
+### Step 7: Observe the following result:
- ```
- (opt "15")
- ```
+```bash
+(opt "15")
+```
-
-
-# Links
-
-Specific links:
+## Resources
- [Actor classes](https://internetcomputer.org/docs/current/motoko/main/actor-classes)
-- [Managing Cycles](https://internetcomputer.org/docs/current/motoko/main/cycles)
-- [Composite Queries](https://internetcomputer.org/docs/current/motoko/main/actors-async#composite-query-functions)
+- [Managing cycles](https://internetcomputer.org/docs/current/motoko/main/cycles)
+- [Composite queries](https://internetcomputer.org/docs/current/motoko/main/actors-async#composite-query-functions)
+
+## Security considerations and best practices
+If you base your application on this example, we recommend you familiarize yourself with and adhere to the [security best practices](https://internetcomputer.org/docs/current/references/security/) for developing on ICP. This example may not implement all the best practices.
\ No newline at end of file
diff --git a/motoko/counter/README.md b/motoko/counter/README.md
index b677e8563..495c4e733 100644
--- a/motoko/counter/README.md
+++ b/motoko/counter/README.md
@@ -1,8 +1,5 @@
# Counter
-
-[](https://github.com/dfinity/examples/actions?query=workflow%3Amotoko-counter-example)
-
## 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.
@@ -24,38 +21,38 @@ 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:
-```
+```bash
cd examples/motoko/counter
dfx start --background
```
### Step 2: Deploy the canister:
-```
+```bash
dfx deploy
```
### Step 3: Set the value of the counter:
-```
+```bash
dfx canister call counter set '(7)'
```
### Step 4: Increment the value of the counter:
-```
+```bash
dfx canister call counter inc
```
### Step 5: Get the value of the counter:
-```
+```bash
dfx canister call counter get
```
The following output should be returned:
-```
+```bash
(8 : nat)
```
@@ -66,6 +63,6 @@ To learn more about these features of Motoko, see:
- [Declaring stable values](https://internetcomputer.org/docs/current/motoko/main/upgrades#declaring-stable-variables).
-## Security considerations and security best practices
+## Security considerations and best practices
If you base your application on this example, we recommend you familiarize yourself with and adhere to the [security best practices](https://internetcomputer.org/docs/current/references/security/) for developing on the Internet Computer. This example may not implement all the best practices.
diff --git a/motoko/defi/README.md b/motoko/defi/README.md
index 8ce5cb6cb..ea4ed345e 100644
--- a/motoko/defi/README.md
+++ b/motoko/defi/README.md
@@ -1,4 +1,4 @@
-# Decentralized exchange (DEX) sample
+# Decentralized exchange sample
## Overview
@@ -88,7 +88,7 @@ Compared to depositing funds, withdrawing funds is simpler. Since the exchange h
### Step 1: Download the project's GitHub repo and install the dependencies:
-```
+```bash
git clone --recurse-submodules --shallow-submodules https://github.com/dfinity/examples.git
# for the rust implementation examples/rust/defi
cd examples/motoko/defi
@@ -97,7 +97,7 @@ make install
The install scripts output the URL to visit the exchange frontend:
-```
+```bash
===== VISIT DEFI FRONTEND =====
http://127.0.0.1:4943?canisterId=by6od-j4aaa-aaaaa-qaadq-cai
===== VISIT DEFI FRONTEND =====
@@ -138,7 +138,7 @@ To trade tokens with yourself, you can open a second incognito browser window.
- No panics after await: when a panic happens, the state gets rolled back. This can cause issues with the correctness of the exchange.
-## Security considerations and security best practices
+## Security considerations and best practices
If you base your application on this example, we recommend you familiarize yourself with and adhere to the [security best practices](https://internetcomputer.org/docs/current/references/security/) for developing on the Internet Computer. This example may not implement all the best practices.
diff --git a/motoko/dip721-nft-container/README.md b/motoko/dip721-nft-container/README.md
index 85e834919..d6d146c26 100644
--- a/motoko/dip721-nft-container/README.md
+++ b/motoko/dip721-nft-container/README.md
@@ -1,4 +1,4 @@
-# DIP721 NFT container
+# DIP721 NFTs
This example demonstrates implementing an NFT canister. NFTs (non-fungible tokens) are unique tokens with arbitrary
metadata, usually an image of some kind, to form the digital equivalent of trading cards. There are a few different
@@ -89,32 +89,33 @@ Using this management canister address, we can construct its principal and set t
### Step 1: Clone the examples repo:
-```
+```bash
git clone git@github.com:dfinity/examples.git
```
### Step 2: Navigate to DIP721 project root:
-```
+```bash
cd examples/motoko/dip-721-nft-container
```
### Step 3: Run a local instance of the Internet Computer:
-```
+```bash
dfx start --background
```
**If this is not a new installation, you may need to run `start` with the `--clean` flag.**
-```
+```bash
dfx start --clean --background
```
- ### Step 4: Deploy a DIP721 NFT canister to your local IC.
+ ### Step 4: Deploy a DIP721 NFT canister to your local replica:
+
This command deploys the DIP721 NFT canister with the following initialization arguments:
-```
+```bash
dfx deploy --argument "(
principal\"$(dfx identity get-principal)\",
record {
@@ -143,18 +144,18 @@ dfx deploy --argument "(
You will receive output that resembles the following:
-```
+```bash
Deployed canisters.
URLs:
Backend canister via Candid interface:
dip721_nft_container: http://127.0.0.1:4943/?canisterId=br5f7-7uaaa-aaaaa-qaaca-cai&id=be2us-64aaa-aaaaa-qaabq-cai
```
- ### Step 5: Mint an NFT.
+ ### Step 5: Mint an NFT:
Use the following command to mint an NFT:
-```
+```bash
dfx canister call dip721_nft_container mintDip721 \
"(
principal\"$(dfx identity get-principal)\",
@@ -175,27 +176,29 @@ dfx canister call dip721_nft_container mintDip721 \
If this succeeds, you should see the following message:
-```
+```bash
(variant { Ok = record { id = 1 : nat; token_id = 0 : nat64 } })
```
- ### Step 6: Transferring an NFT.
+ ### Step 6: Transferring an NFT:
The DIP721 interface supports transferring an NFT to some other `principal` values via the `transferFromDip721` or `safeTransferFromDip721` methods.
First, create a different identity using DFX. This will become the principal that you receives the NFT
-```
+```bash
dfx identity new --disable-encryption alice
ALICE=$(dfx --identity alice identity get-principal)
```
Verify the identity for `ALICE` was created and set as an environment variable:
-```
+
+```bash
echo $ALICE
```
-You should see a principal get printed
-```
+You should see a principal returned:
+
+```bash
o4f3h-cbpnm-4hnl7-pejut-c4vii-a5u5u-bk2va-e72lb-edvgw-z4wuq-5qe
```
@@ -206,56 +209,56 @@ Here the arguments are:
`to`: principal to transfer the NFT to
`token_id`: the id of the token to transfer
-```
+```bash
dfx canister call dip721_nft_container transferFromDip721 "(principal\"$(dfx identity get-principal)\", principal\"$ALICE\", 0)"
```
Transfer the NFT from from `ALICE` back to the default user.
-```
+```bash
dfx canister call dip721_nft_container safeTransferFromDip721 "(principal\"$ALICE\", principal\"$(dfx identity get-principal)\", 0)"
```
Note the second transfer works because the caller is in the list of custodians, i.e. the default user has admin rights to modify the NFT collection.
-### Other methods
+## Other methods
- ### balanceOfDip721
+### `balanceOfDip721`
-```
+```bash
dfx canister call dip721_nft_container balanceOfDip721 "(principal\"$(dfx identity get-principal)\")"
```
Output:
-```
+```bash
(1 : nat64)
```
- ### getMaxLimitDip721
+### `getMaxLimitDip721`
-```
+```bash
dfx canister call dip721_nft_container getMaxLimitDip721
```
Output:
-```
+```bash
(10 : nat16)
```
- ### getMetadataDip721
+### `getMetadataDip721`
Provide a token ID.
The token ID was provided to you when you ran `mintDip721`, e.g. `(variant { Ok = record { id = 1 : nat; token_id = 0 : nat64 } })` So, the token ID is 0 in this case.
-```
+```bash
dfx canister call dip721_nft_container getMetadataDip721 "0"
```
Output:
-```
+```bash
(
variant {
Ok = vec {
@@ -286,15 +289,15 @@ Output:
```
- ### getMetadataForUserDip721
+### `getMetadataForUserDip721`
-```
+```bash
dfx canister call dip721_nft_container getMetadataForUserDip721 "(principal\"$(dfx identity get-principal)\")"
```
Output:
-```
+```bash
(
variant {
Ok = record {
@@ -327,88 +330,90 @@ Output:
)
```
- ### getTokenIdsForUserDip721
+### `getTokenIdsForUserDip721`
-```
+```bash
dfx canister call dip721_nft_container getTokenIdsForUserDip721 "(principal\"$(dfx identity get-principal)\")"
```
Output:
-```
+```bash
(vec { 0 : nat64 })
```
- ### logoDip721
+### `logoDip721`
-```
+```bash
dfx canister call dip721_nft_container logoDip721
```
Output:
-```
+```bash
(record { data = ""; logo_type = "image/png" })
```
- ### nameDip721
+### `nameDip721`
-```
+```bash
dfx canister call dip721_nft_container nameDip721
```
Output:
-```
+```bash
("My DIP721")
```
- ### supportedInterfacesDip721
+### `supportedInterfacesDip721`
-```
+```bash
dfx canister call dip721_nft_container supportedInterfacesDip721
```
Output:
-```
+```bash
(vec { variant { TransferNotification }; variant { Burn }; variant { Mint } })
```
- ### symbolDip721
+### `symbolDip721`
-```
+```bash
dfx canister call dip721_nft_container symbolDip721
```
Output:
-```
+
+```bash
("DFXB")
```
- ### totalSupplyDip721
+### `totalSupplyDip721`
-```
+```bash
dfx canister call dip721_nft_container totalSupplyDip721
```
Output:
-```
+```bash
(1 : nat64)
```
- ### ownerOfDip721
+### `ownerOfDip721`
+
Provide a token ID.
The token ID was provided to you when you ran `mintDip721`, e.g. `(variant { Ok = record { id = 1 : nat; token_id = 0 : nat64 } })` So, the token ID is 0 in this case.
-```
+```bash
dfx canister call dip721_nft_container ownerOfDip721 "0"
```
Output:
-```
+```bash
(
variant {
Ok = principal "5wuse-ejxao-gkqq6-4dhl5-hn5ps-2mgop-2se4s-w4zle-agr6j-svlhq-3qe"
@@ -418,11 +423,11 @@ Output:
Verify that this is the same principal that you ran `mintDip721` with:
-```
+```bash
dfx identity get-principal
```
-## Security considerations and security best practices
+## Security considerations and best practices
If you base your application on this example, we recommend you familiarize yourself with and adhere to the [security best practices](https://internetcomputer.org/docs/current/references/security/) for developing on the Internet Computer. This example may not implement all the best practices.
diff --git a/motoko/echo/README.md b/motoko/echo/README.md
index cf491e7e9..8ded6bb66 100644
--- a/motoko/echo/README.md
+++ b/motoko/echo/README.md
@@ -1,8 +1,5 @@
# Echo
-
-[](https://github.com/dfinity/examples/actions?query=workflow%3Amotoko-echo-example)
-
## Overview
This example demonstrates a simple echo effect, where an application sends back the data it receives.
@@ -17,28 +14,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 Internet Computer 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:
-```
+```bash
cd examples/motoko/echo
dfx start --background
```
### Step 2: Deploy the canisters `Map` and `Test`:
-```
+```bash
dfx deploy
```
### Step 3: Invoke the say method:
-```
+```bash
dfx canister call echo say '("This is a test.")'
```
The following output will be returned:
-```
+```bash
("This is a test.")
```
diff --git a/motoko/encrypted-notes-dapp-vetkd/README.md b/motoko/encrypted-notes-dapp-vetkd/README.md
index 6f98d64bf..fcefde46a 100644
--- a/motoko/encrypted-notes-dapp-vetkd/README.md
+++ b/motoko/encrypted-notes-dapp-vetkd/README.md
@@ -1,4 +1,4 @@
-# Encrypted notes adapted for using vetKD
+# Encrypted notes: vetKD
This is a copy of the encrypted-notes-dapp example, adapted to (1) use [the proposed vetKD feature](https://github.com/dfinity/interface-spec/pull/158) and (2) add sharing of notes between users.
@@ -15,37 +15,45 @@ Please also see the [README of the original encrypted-notes-dapp](../encrypted-n
This example uses an **insecure** implementation of [the proposed vetKD system API](https://github.com/dfinity/interface-spec/pull/158) in a pre-compiled form via the [vetkd_system_api.wasm](./vetkd_system_api.wasm). **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.
## Manual local deployment
-1. Choose which implementation to use by setting a respective environment variable. You can choose Motoko or Rust.
+### Step 1: Choose which implementation to use by setting a respective environment variable.
- For **Motoko** deployment use
- ```sh
- export BUILD_ENV=motoko
- ```
- For **Rust** deployment use
- ```sh
- export BUILD_ENV=rust
- ```
-2. To generate `$BUILD_ENV`-specific files (i.e., Motoko or Rust) run:
- ```sh
- sh ./pre_deploy.sh
- ```
-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.
-4. Install npm packages from the project root:
- ```sh
- npm install
- ```
- _Note_: see [Troubleshooting](#troubleshooting) in case of problems
-5. In case DFX was already started before, run the following:
- ```sh
- dfx stop
- rm -rf .dfx
- ```
-6. Run in a separate shell (it blocks the shell):
- ```sh
- dfx start --clean
- ```
- ⚠️ 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 deamon whatsoever for this step).
-7. Install a local [Internet Identity (II)](https://wiki.internetcomputer.org/wiki/What_is_Internet_Identity) canister:
+For **Motoko** deployment use
+```sh
+export BUILD_ENV=motoko
+```
+
+### 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:
+
+```sh
+npm install
+```
+_Note_: see [Troubleshooting](#troubleshooting) in case of problems.
+
+### Step 5: In case dfx was already started before, run the following:
+
+```sh
+dfx stop
+rm -rf .dfx
+```
+
+### Step 6: Run in a separate window:
+
+```sh
+dfx start --clean
+```
+⚠️ 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:
_Note_: 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
@@ -56,7 +64,8 @@ This example uses an **insecure** implementation of [the proposed vetKD system A
npm run print-dfx-ii
```
3. Visit the URL from above and create at least one local internet identity.
-7. Install the vetKD system API canister:
+
+### Step 8: 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
@@ -65,28 +74,36 @@ This example uses an **insecure** implementation of [the proposed vetKD system A
```sh
dfx deploy vetkd_system_api
```
-8. 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`.
-9. Update the generated canister interface bindings:
- ```sh
- dfx generate "encrypted_notes_$BUILD_ENV"
- ```
-10. Deploy the frontend canister:
- ```sh
- dfx deploy www
- ```
- You can check its URL with `npm run print-dfx-www`.
-11. Open the frontend:
- 1. Start the local development server, which also supports hot-reloading:
- ```sh
- npm run dev
- ```
- 2. Open the URL that is printed in the console output. Usually, this is [http://localhost:3000/](http://localhost:3000/).
-
- ⚠️ 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.
+
+### Step 9:. 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:
+
+```sh
+dfx generate "encrypted_notes_$BUILD_ENV"
+```
+
+### Step 11: Deploy the frontend canister:
+```sh
+dfx deploy www
+```
+You can check its URL with `npm run print-dfx-www`.
+
+
+### Step 11: Open the frontend:
+
+ 1. Start the local development server, which also supports hot-reloading:
+ ```sh
+ npm run dev
+ ```
+ 2. Open the URL that is printed in the console output. Usually, this is [http://localhost:3000/](http://localhost:3000/).
+
+ ⚠️ 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 9d6fac99e..7b50a8b7a 100644
--- a/motoko/encrypted-notes-dapp/README.md
+++ b/motoko/encrypted-notes-dapp/README.md
@@ -109,24 +109,20 @@ Follow the steps below to deploy this sample project.
### Step 1. Navigate inside of the project's folder:
-```
+```bash
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:
+
For Motoko deployment run:
-```
+```bash
export BUILD_ENV=motoko
```
-For Rust deployment run:
-
-```
-export BUILD_ENV=rust
-```
**Building the Rust canister requires either the Rust toolchain installed on your system or Docker-backed deployment (see below).**
@@ -138,7 +134,7 @@ export BUILD_ENV=rust
- #### Step 1: Install and start Docker by following the instructions.
- #### Step 2: For Motoko build/deployment set environmental variable:
-```
+```bash
export BUILD_ENV=motoko
```
@@ -146,7 +142,7 @@ export BUILD_ENV=motoko
Execution can take a few minutes:
-```
+```bash
sh ./deploy_locally.sh
```
@@ -163,25 +159,25 @@ sh ./deploy_locally.sh
### Option 2: Manual deployment
- #### Step 1: For Motoko deployment set environmental variable:
-```
+```bash
export BUILD_ENV=motoko
```
- #### Step 2: To generate $BUILD_ENV-specific files (i.e., Motoko or Rust) run:
-```
+```bash
sh ./pre_deploy.sh
```
- #### Step 3: Install `npm` packages from the project root:
-```
+```bash
npm install
```
- #### Step 4: Start `dfx`:
-```
+```bash
dfx start
```
@@ -194,13 +190,13 @@ dfx start
To install and deploy a canister run:
-```
+```bash
dfx deploy internet_identity --argument '(null)'
```
- #### Step 6: To print the Internet Identity URL, run:
-```
+```bash
npm run print-dfx-ii
```
@@ -208,7 +204,7 @@ Visit the URL from above and create at least one local Internet Identity.
- #### Step 7: Deploy the encrypted notes backend canister:
-```
+```bash
dfx deploy "encrypted_notes_$BUILD_ENV"
```
@@ -216,26 +212,26 @@ dfx deploy "encrypted_notes_$BUILD_ENV"
- #### Step 8: Update the generated canister interface bindings:
-```
+```bash
dfx generate "encrypted_notes_$BUILD_ENV"
```
- #### Step 9: Deploy the frontend canister.
To install and deploy the canister run:
-```
+```bash
dfx deploy www
```
- #### Step 10: To print the frontend canister's URL, run:
-```
+```bash
npm run print-dfx-www
```
Visit the URL from above in a web browser. To run the frontend with hot-reloading on `http://localhost:3000/`, run:
-```
+```bash
npm run dev
```
@@ -249,7 +245,7 @@ npm run dev
- #### Step 1: Create the canisters:
-```
+```bash
dfx canister --network ic create "encrypted_notes_${BUILD_ENV}"
dfx canister --network ic create www
```
@@ -259,7 +255,7 @@ dfx canister --network ic create www
- #### Step 2: Build the canisters:
-```
+```bash
dfx build "encrypted_notes_${BUILD_ENV}" --network ic
dfx build www --network ic
```
@@ -269,12 +265,12 @@ dfx build www --network ic
**In the commands below, --mode could also be reinstall to reset the stable memory.**
-```
+```bash
dfx canister --network ic install "encrypted_notes_${BUILD_ENV}" --mode=upgrade
dfx canister --network ic install www --mode=upgrade
```
-## Security considerations and security best practices
+## Security considerations and best practices
If you base your application on this example, we recommend you familiarize yourself with and adhere to the [security best practices](https://internetcomputer.org/docs/current/references/security/) for developing on the Internet Computer. This example may not implement all the best practices, see also the [disclaimer](#disclaimer-please-read-carefully) above.
@@ -283,139 +279,6 @@ For example, the following aspects are particularly relevant for this app:
* [Protect key material against XSS using Web Crypto API](https://internetcomputer.org/docs/current/references/security/web-app-development-security-best-practices#crypto-protect-key-material-against-xss-using-web-crypto-api), since this app stores private keys in the browser.
* [Use secure cryptographic schemes](https://internetcomputer.org/docs/current/references/security/general-security-best-practices#use-secure-cryptographic-schemes), since notes are being encrypted.
-## Deployment
-### Selecting backend canister deployment option
-* For **Motoko** deployment run:
-
-```sh
-export BUILD_ENV=motoko
-```
-
-* For **Rust** deployment run:
-
-```sh
-export BUILD_ENV=rust
-```
-
-**Note:** Building the Rust canister requires either the Rust toolchain installed on your system or Docker-backed deployment (see below).
-
----
-
-
-### Local deployment
-#### Option 1: Docker deployment
-
-**Note:** this option does not yet work on Apple M1; the combination of [DFX](https://internetcomputer.org/docs/current/references/cli-reference/dfx-parent) and Docker do not currently support the required architecture.
-
-1. Install and start Docker by following the [instructions](https://docs.docker.com/get-docker/).
-2. For **Motoko** build/deployment set environmental variable:
- ```sh
- export BUILD_ENV=motoko
- ```
-3. Run the following Bash script that builds a Docker image, compiles the canister, and deploys this dapp (all inside the Docker instance). Execution can take some minutes:
- ```sh
- sh ./deploy_locally.sh
- ```
- ⚠️ If this fails with `No such container`, please ensure that the Docker daemon is running on your system.
-
-4. To open the frontend, go to http://localhost:3000/
-
-5. To stop the docker instance:
-
- 5.1. Hit `Ctrl+C` on your keyboard to abort the running process.
-
- 5.2. Run `docker ps` and find the _``_ of `encrypted_notes`.
-
- 5.3. Run `docker rm -f `_``_.
-
-#### Option 2: Manual deployment
-1. For **Motoko** deployment set environmental variable:
- ```sh
- export BUILD_ENV=motoko
- ```
-2. To generate `$BUILD_ENV`-specific files (i.e., Motoko or Rust) run:
- ```sh
- sh ./pre_deploy.sh
- ```
-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.
-4. Install npm packages from the project root:
- ```sh
- npm install
- ```
- _Note_: see [Troubleshooting](#troubleshooting) in case of problems
-5. In case DFX was already started before, run the following:
- ```sh
- dfx stop
- rm -rf .dfx
- ```
-6. Run in a separate shell (it blocks the shell):
- ```sh
- dfx start --clean
- ```
- ⚠️ 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 deamon whatsoever for this step).
-7. Install a local [Internet Identity (II)](https://wiki.internetcomputer.org/wiki/What_is_Internet_Identity) canister:
- _Note_: 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
- dfx deploy internet_identity --argument '(null)'
- ```
- 2. To print the Internet Identity URL, run:
- ```sh
- npm run print-dfx-ii
- ```
- 3. Visit the URL from above and create at least one local internet identity.
-8. 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`.
-9. Update the generated canister interface bindings:
- ```sh
- dfx generate "encrypted_notes_$BUILD_ENV"
- ```
-10. Deploy the frontend canister:
- 1. To install and deploy the canister run:
- ```sh
- dfx deploy www
- ```
- 2. To print the frontend canister's URL, run:
- ```sh
- npm run print-dfx-www
- ```
- 3. Visit the URL from above
-11. To get the frontend with hot-reloading on [http://localhost:3000/](http://localhost:3000/), run:
- ```sh
- npm run dev
- ```
- ⚠️ 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
-**Note:** Prior to starting the mainnet deployment process, ensure you have your identities and wallets set up for controlling the canisters correctly. This guide assumes that this work has been done in advance. [More info here](https://internetcomputer.org/docs/current/references/cli-reference/dfx-identity).
-
-1. Create the canisters:
- ```sh
- dfx canister --network ic create "encrypted_notes_${BUILD_ENV}"
- dfx canister --network ic create www
- ```
- _Note_: `encrypted_notes_rust` will only work if you have the Rust toolchain installed.
-2. Build the canisters:
- ```sh
- dfx build "encrypted_notes_${BUILD_ENV}" --network ic
- dfx build www --network ic
- ```
-
-3. Deploy to mainnet:
- _Note_: In the commands below, `--mode` could also be `reinstall` to reset the [stable memory](https://internetcomputer.org/docs/current/motoko/main/upgrades/).
-
- ```sh
- dfx canister --network ic install "encrypted_notes_${BUILD_ENV}" --mode=upgrade
- dfx canister --network ic install www --mode=upgrade
- ```
-
----
-
## User interaction with "Encrypted Notes" dapp
### Scenario I: basic single-device usage
@@ -427,7 +290,7 @@ export BUILD_ENV=rust
Fig. 2. Basic single-device scenario for a user.
-1. Open the main page of the `Encrypted Notes` dapp. You will see a _login_ button.
+- #### Step 1: Open the main page of the `Encrypted Notes` dapp. You will see a _login_ button.
1. If deployed locally, visit the following link: http://localhost:8000?canisterId=rkp4c-7iaaa-aaaaa-aaaca-cai
2. If deployed to the mainnet IC, visit the corresponding canister URL.
@@ -436,13 +299,14 @@ Fig. 2. Basic single-device scenario for a user.
**Note:** see [Troubleshooting](#troubleshooting) in case of problems.
-2. Click the "Login" button. You will be redirected to the _Internet Identity_ canister (see Fig. 2(b)).
+- #### Step 2: Click the "Login" button. You will be redirected to the _Internet Identity_ canister (see Fig. 2(b)).
1. If you already have an `anchor`, you may continue with it. Click "Authenticate", then verify your identity and finally click "Proceed", see Fig. 2(c).
2. If you do not have an anchor yet, you should [create one](https://internetcomputer.org/how-it-works/web-authentication-identity/). Once an `anchor` is created, please follow 2.1.
-3. Once logged in for the first time, your notes list should be empty. At this moment, your _Local Storage_ should be populated with additional variables (see Fig. 2(d)): **ic-identity**, **ic-delegation**. These variables are used for storing/retrieving notes from the backend canister. In addition, another two variables are generated in the _IndexedDB_: **PrivateKey**, **PublicKey**. These two variable are used for encrypting/decrypting the shared secret key.
-4. Create/edit/delete notes and observe changes in the resulting notes list (see Fig. 2(e)).
+- #### Step 3: Once logged in for the first time, your notes list should be empty. At this moment, your _Local Storage_ should be populated with additional variables (see Fig. 2(d)): **ic-identity**, **ic-delegation**. These variables are used for storing/retrieving notes from the backend canister. In addition, another two variables are generated in the _IndexedDB_: **PrivateKey**, **PublicKey**. These two variable are used for encrypting/decrypting the shared secret key.
+
+- #### Step 4: Create/edit/delete notes and observe changes in the resulting notes list (see Fig. 2(e)).
### Scenario II: user is accessing notes from multiple devices
@@ -455,12 +319,19 @@ In this scenario, a user accesses the dapp using the same _Internet Identity_ an
Fig. 3. Scenario for a user with multiple registered devices.
-1. Perform steps 1-3 of Scenario I on Device A.
-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 period of time. As Device A was the first to login, it was also the first one to generate a shared secret. Device B has to retrieve it. In order to do that, Device B first uploads its public key (pub B) to the backend canister. Device A retrieves pub B by means of periodic polling. Device A then re-encrypts the shared secret with pub B and uploads it to the backend. Afterwards, Device B can retrieve the encrypted shared secret and decrypt it with its private key.
-3. Observe that the list of notes is now empty for both devices.
-4. Create a Note, e.g. "Note from Device A" on Device A, and observe it on Device B.
-5. Analogously, create a different note, e.g. "Note from Device B" on Device B.
-6. Confirm that the notes are synchronized between the two 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.
+
+One subtle difference that you might observe on Device B is that the message "Synchronizing..." (Fig. 3(a)) appears for a short period of time. As Device A was the first to login, it was also the first one to generate a shared secret. Device B has to retrieve it. In order to do that, Device B first uploads its public key (pub B) to the backend canister. Device A retrieves pub B by means of periodic polling. Device A then re-encrypts the shared secret with pub B and uploads it to the backend. Afterwards, Device B can retrieve the encrypted shared secret and decrypt it with its private key.
+
+- #### Step 3: Observe that the list of notes is now empty for both devices.
+
+- #### Step 4: Create a Note, e.g. "Note from Device A" on Device A, and observe it on Device B.
+
+- #### Step 5: Analogously, create a different note, e.g. "Note from Device B" on Device B.
+
+- #### Step 6: Confirm that the notes are synchronized between the two devices.
### Scenario III: device management
@@ -471,31 +342,36 @@ Fig. 3. Scenario for a user with multiple registered devices.
Fig. 4. Scenario for a user adding/removing devices.
-1. Login into the dapp with the same anchor on two or more devices.
-2. On each device, navigate to "Devices" item in the menu.
-3. Observe that the list of registered devices contains as many entries as the number of logged in devices.
-4. Assuming we are using Device A, click "remove" for some other device, say, Device B.
-5. While still on Device A, observe that Device B is deleted from the list of devices. _Note_: a device cannot remove itself. That is why you do not see a "remove" button for your current device.
-6. Switch to Device B and observe that it has been logged out.
-7. Login with Device B again and observe in "Device" tab both devices again.
+- #### Step 1: Login into the dapp with the same anchor on two or more devices.
----
-
+- #### Step 2: On each device, navigate to "Devices" item in the menu.
-## Unit testing
+- #### Step 3: Observe that the list of registered devices contains as many entries as the number of logged in devices.
+
+- #### Step 4: Assuming we are using Device A, click "remove" for some other device, say, Device B.
+
+- #### Step 5: While still on Device A, observe that Device B is deleted from the list of devices.
-This project also demonstrates how one can write unit tests for Motoko and Rust canisters.
+ _Note_: a device cannot remove itself. That is why you do not see a "remove" button for your current device.
-### Motoko Unit Tests
+- #### Step 6: Switch to Device B and observe that it has been logged out.
+
+- #### Step 7: Login with Device B again and observe in "Device" tab both devices again.
+
+## Unit testing
The unit tests are implemented in `src/encrypted_notes_motoko/test/test.mo` using the [Motoko Matchers](https://kritzcreek.github.io/motoko-matchers/) library.
The easiest way to run all tests involves the following steps:
-1. Follow the [above instructions](#option-1-docker-deployment) for Deployment via Docker with `BUILD_ENV=motoko`.
-2. Open a new console, type `docker ps`, and copy the _``_ of the `encrypted_notes` image.
-3. Run: `docker exec `_``_` sh src/encrypted_notes_motoko/test/run_tests.sh`
-4. Observer `All tests passed.` at the end of the output.
+- #### Step 1: Follow the [above instructions](#option-1-docker-deployment) for Deployment via Docker with `BUILD_ENV=motoko`.
+
+- #### Step 2:. Open a new console, type `docker ps`, and copy the _``_ of the `encrypted_notes` image.
+
+- #### Step 3: Run: `docker exec `_``_` sh src/encrypted_notes_motoko/test/run_tests.sh`
+
+- #### Step 4: Observer `All tests passed.` at the end of the output.
+
Alternatively, one can also run unit tests after a local deployment via:
```sh
@@ -511,24 +387,6 @@ src/encrypted_notes_motoko/test/run_tests.sh
Observer `All tests passed.` at the end of the output.
-### Rust Unit Tests
-
-The unit tests are implemented in `src/encrypted_notes_rust/src/lib.rs` at the bottom.
-
-The easiest way to run all tests involves the following steps:
-
-1. Follow the [above instructions](#option-1-docker-deployment) for Deployment via Docker with `BUILD_ENV=rust`.
-2. Open a new console, type `docker ps`, and copy the _``_ of the `encrypted_notes` image.
-3. Run: `docker exec `_``_` cargo test`
-4. Observer `test result: ok.` at the end of the output.
-
-Alternatively, one can also run unit tests after a local deployment via:
-```sh
-cargo test
-```
-
----
-
## Troubleshooting
### Building/deployment problems
diff --git a/motoko/factorial/README.md b/motoko/factorial/README.md
index aeec1e27f..9b3632fa7 100644
--- a/motoko/factorial/README.md
+++ b/motoko/factorial/README.md
@@ -1,15 +1,11 @@
# Factorial
-
-[](https://github.com/dfinity/examples/actions?query=workflow%3Amotoko-factorial-example)
-
## Overview
This example demonstrates a recursive mathematical function that calculates the product of all positive integers less than or equal to its input.
This is a Motoko example that does not currently have a Rust variant.
-
## Prerequisites
This example requires an installation of:
@@ -17,31 +13,31 @@ 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 replica with the command:
-```
+```bash
cd examples/motoko/factorial
dfx start --background
```
### Step 2: Deploy the canister:
-```
+```bash
dfx deploy
```
### Step 3: Calculate the factorial of 20:
-```
+```bash
dfx canister call factorial fac '(20)'
```
The following output will be returned:
-```
+```bash
(2_432_902_008_176_640_000 : nat)
```
-## Security considerations and security best practices
+## Security considerations and best practices
If you base your application on this example, we recommend you familiarize yourself with and adhere to the [security best practices](https://internetcomputer.org/docs/current/references/security/) for developing on the Internet Computer. This example may not implement all the best practices.
diff --git a/motoko/hello_cycles/README.md b/motoko/hello_cycles/README.md
index 971343169..0d1e91993 100644
--- a/motoko/hello_cycles/README.md
+++ b/motoko/hello_cycles/README.md
@@ -1,4 +1,4 @@
-# Hello cycles
+# Hello, cycles!
## Overview
@@ -29,40 +29,40 @@ 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 replica with the command:
-```
+```bash
cd examples/motoko/hello_cycles
dfx start --background
```
### 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:
-```
+```bash
dfx canister call hello_cycles wallet_balance
```
The output should resemble the following:
-```
+```bash
(3_091_662_816_985 : nat)
```
You can also see the cycles balance of hello_cycles (or any canister you control) by calling:
-```
+```bash
dfx canister status hello_cycles
```
The output of this command will be similar to:
-```
+```bash
Canister status call result for hello_cycles.
Status: Running
Controllers: 2vxsx-fae b77ix-eeaaa-aaaaa-qaada-cai
@@ -76,14 +76,14 @@ Module hash: 0x09198be65e161bdb5c75c705dfec4b707a8091ac5d1a095dd45c025142a1fc43
### Step 4: To display the default wallet and hello_cycles canister principals, run the commands:
-```
+```bash
dfx identity get-wallet
dfx canister id hello_cycles
```
The output should resemble the following:
-```
+```bash
b77ix-eeaaa-aaaaa-qaada-cai
dzh22-nuaaa-aaaaa-qaaoa-cai
```
@@ -92,7 +92,7 @@ Below, we'll frequently use `$(dfx identity get-wallet)` and `$(dfx canister id
### Step 5: Attempt to send 2 trillion cycles from the default wallet to the hello_cycles canister by running the following command:
-```
+```bash
dfx canister call $(dfx identity get-wallet) wallet_send "(record { canister = principal \"$(dfx canister id hello_cycles)\"; amount = (2000000000000:nat64); } )"
```
@@ -100,19 +100,19 @@ The wallet's `wallet_send` function transfers the amount to the argument caniste
If successful, the output will look similar to:
-```
+```bash
(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:
-```
+```bash
dfx canister call hello_cycles wallet_balance
```
Output:
-```
+```bash
(5_091_662_569_379 : nat)
```
@@ -120,25 +120,25 @@ The amount is only increased by 10_000_000 because the implementation of `wallet
### Step 7: Send some cycles from the hello_cycles canister back to the wallet by running the command:
-```
+```bash
dfx canister call hello_cycles transfer "(func \"$(dfx identity get-wallet)\".\"wallet_receive\", 5000000)"
```
Output:
-```
+```bash
(record { refunded = 0 : nat })
```
### Step 8: Verify that the cycles balance of hello_cycles canister has decreased with:
-```
+```bash
dfx canister call hello_cycles wallet_balance
```
Output:
-```
+```bash
(5_091_657_208_987 : nat)
```
@@ -147,7 +147,7 @@ In this step, we are passing our own wallet's `wallet_receive` function as the f
Without some additional access control checks (omitted here), a malicious client could abuse our naive transfer function to drain the canister of all of its cycles.
-## Security considerations and security best practices
+## Security considerations and best practices
If you base your application on this example, we recommend you familiarize yourself with and adhere to the [security best practices](https://internetcomputer.org/docs/current/references/security/) for developing on the Internet Computer. This example may not implement all the best practices.
diff --git a/motoko/http_counter/README.md b/motoko/http_counter/README.md
index 8adaae746..5c4b1dc0b 100644
--- a/motoko/http_counter/README.md
+++ b/motoko/http_counter/README.md
@@ -28,14 +28,14 @@ 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:
-```
+```bash
cd examples/motoko/http_counter
dfx start --background
```
### Step 2: Deploy the canister:
-```
+```bash
dfx deploy
```
@@ -68,7 +68,7 @@ curl --compressed -X POST "$CANISTER_ID.localhost:4943/" --resolve "$CANISTER_ID
```
-## Security considerations and security best practices
+## Security considerations and best practices
If you base your application on this example, we recommend you familiarize yourself with and adhere to the [security best practices](https://internetcomputer.org/docs/current/references/security/) for developing on the Internet Computer. This example may not implement all the best practices.
diff --git a/motoko/ic-pos/README.md b/motoko/ic-pos/README.md
index 4e276ec47..f6a7de22c 100644
--- a/motoko/ic-pos/README.md
+++ b/motoko/ic-pos/README.md
@@ -56,13 +56,13 @@ The frontend interacts with the following IC canisters:
- [x] Install the [IC SDK](https://internetcomputer.org/docs/current/developer-docs/setup/install/index.mdx).
- [x] Install [Node.js](https://nodejs.org/en/).
-### Step 1: Start a local instance of the Internet Computer
+### Step 1: Start a local instance of the replica:
```bash
dfx start --clean --background
```
-### Step 2: 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.
@@ -70,7 +70,7 @@ Integration with the [Internet Identity](https://internetcomputer.org/internet-i
dfx deploy --network local internet_identity
```
-### Step 3: Save current principal as a variable
+### Step 3: Save current principal as a variable:
The principal will be used when deploying the ledger canister.
@@ -78,7 +78,7 @@ The principal will be used when deploying the ledger canister.
export OWNER=$(dfx identity get-principal)
```
-### Step 3: Deploy the ckBTC ledger canister
+### Step 3: Deploy the ckBTC ledger canister:
The responsibilities of the ledger canister is to keep track of token balances and handle token transfers.
@@ -121,7 +121,7 @@ dfx deploy --network local --specified-id mxzaz-hqaaa-aaaar-qaada-cai icrc1_ledg
'
```
-### Step 4: Deploy the index canister
+### Step 4: Deploy the index canister:
The index canister syncs the ledger transactions and indexes them by account.
@@ -133,7 +133,7 @@ dfx deploy --network local icrc1_index --argument '
'
```
-### Step 5: Deploy the icpos canister
+### Step 5: Deploy the icpos canister:
The icpos canister manages the store configuration and sends notifications when a payment is received.
@@ -143,7 +143,7 @@ The `--argument '(0)'` argument is used to initialize the canister with `startBl
dfx deploy --network local icpos --argument '(0)'
```
-### Step 6: Configure the icpos canister
+### Step 6: 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:
@@ -151,7 +151,7 @@ ic-pos uses [Courier](https://courier.com/) to send email and SMS notifications.
dfx canister --network local call icpos setCourierApiKey "pk_prod_..."
```
-### Step 7: Build and run the frontend
+### Step 7: Build and run the frontend:
Run npm to install dependencies and start the frontend. The frontend will be available at http://localhost:5173.
@@ -170,7 +170,7 @@ Transfers made from the owner principal will not trigger notifications in the UI
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.
-#### 8.1: Create the first store and supply it with some tokens
+#### 8.1: Create the first store and supply it with some tokens:
Log in to the frontend using the Internet Identity. Configure the store and navigate to the `Receive` page. Click on the principal pill to copy the address to your clipboard. Then, using the `dfx` command, mint some tokens from your owner principal to the store principal.
@@ -185,7 +185,7 @@ dfx canister --network local call icrc1_ledger icrc1_transfer '
'
```
-#### 8.2: Create the second store
+#### 8.2: Create the second store:
Log in to the frontend using **a new Internet Identity on another web browser**. Configure the store and navigate to the `Receive` page. Click on the principal pill to copy the address to your clipboard.
@@ -195,7 +195,7 @@ If everything is working, you should see a notification in the second store.
🎉
-## Possible Improvements
+## Possible improvements
- Login state is not persisted. Reloading the app will log the user out. This should be done using `localStorage` or `sessionStorage`.
- Show more information about transactions. A transaction detail page.
diff --git a/motoko/icrc2-swap/README.md b/motoko/icrc2-swap/README.md
index 57b1d7932..83bf24ece 100644
--- a/motoko/icrc2-swap/README.md
+++ b/motoko/icrc2-swap/README.md
@@ -1,4 +1,6 @@
-# ICRC-2 Swap
+# ICRC-2 swap
+
+## Overview
ICRC-2 Swap is simple canister demonstrating how to safely work with ICRC-2
tokens. It handles depositing, swapping, and withdrawing ICRC-2 tokens.
@@ -17,20 +19,20 @@ different from other synchronous blockchains.
- **Withdraw Tokens**: Users can withdraw the resulting tokens after
swapping.
-# Local deployment
+## Local deployment
## 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/).
-## Step 1: Start a local instance of the Internet Computer
+### Step 1: Start a local instance of the replica:
```bash
dfx start --clean --background
```
-## Step 2: Create our user accounts
+### Step 2: Create your user accounts:
```bash
export OWNER=$(dfx identity get-principal)
@@ -42,7 +44,7 @@ dfx identity new bob
export BOB=$(dfx identity get-principal --identity bob)
```
-## Step 2: Deploy two tokens
+### Step 2: Deploy two tokens:
Deploy Token A:
@@ -112,7 +114,7 @@ dfx deploy token_b --argument '
'
```
-## Step 3: Deploy the swap canister
+### Step 3: Deploy the swap canister:
The swap canister accepts deposits, and performs the swap.
@@ -130,7 +132,7 @@ dfx deploy swap --argument '
export SWAP=$(dfx canister id swap)
```
-## Step 4: Approve & deposit tokens
+### Step 4: Approve & deposit tokens:
Before we can swap the tokens, they must be transferred to the swap canister.
With ICRC-2, this is a two-step process. First we approve the transfer:
@@ -187,7 +189,7 @@ dfx canister call --identity bob swap deposit 'record {
}'
```
-## Step 5: Perform a swap
+### Step 5: Perform a swap:
```bash
dfx canister call swap swap 'record {
@@ -205,9 +207,9 @@ 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 6: Withdraw tokens:
-After the swap, our balandes in the swap canister will have been updated, and we
+After the swap, our balances in the swap canister will have been updated, and we
can withdraw our newly received tokens into our wallet.
```bash
@@ -232,7 +234,7 @@ dfx canister call --identity bob swap withdraw 'record {
}'
```
-## Step 7: Check token balances
+### Step 7: Check token balances:
```bash
# Check Alice's Token A balance. They should now have 998.99980000 A
@@ -251,7 +253,7 @@ the token balances.
🎉
-# Running the test suite
+## Running the test suite
The example comes with a test suite to demonstrate the basic functionality. It
shows how to use this repo from a Javascript client.
@@ -261,30 +263,30 @@ shows how to use this repo from a Javascript client.
- [x] Install the [IC SDK](https://internetcomputer.org/docs/current/developer-docs/setup/install/index.mdx).
- [x] Install [Node.js](https://nodejs.org/en/).
-## Step 1: Start a local instance of the Internet Computer
+### Step 1: Start a local instance of the replica:
```bash
dfx start --clean --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
```
-# Possible Improvements
+## Possible improvements
- Keep a history of deposits/withdrawaps/swaps.
- Add a frontend.
-# Known issues
+## Known issues
- Any DeFi on the Internet Computer is experimental. It is a constantly evolving
space, with unknown attacks, and should be treated as such.
diff --git a/motoko/internet_identity_integration/README.md b/motoko/internet_identity_integration/README.md
index e186e8cd4..8088e0c0a 100644
--- a/motoko/internet_identity_integration/README.md
+++ b/motoko/internet_identity_integration/README.md
@@ -1,4 +1,4 @@
-# Internet Identity integration sample
+# Internet Identity integration
## Overview
@@ -15,15 +15,15 @@ This is a Motoko example that does not currently have a Rust variant.
## Prerequisites
-- [ ] Install the [IC SDK](https://internetcomputer.org/docs/current/developer-docs/setup/install/index.mdx).
-- [ ] Install [Node.js](https://nodejs.org/en/download/).
-- [ ] Download and install the `@dfinity/auth-client` package with the command `npm install @dfinity/auth-client`.
-- [ ] Download the following project files from GitHub: https://github.com/dfinity/examples/
-- [ ] 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))
+- [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] Download and install the `@dfinity/auth-client` package with the command `npm install @dfinity/auth-client`.
+- [x] Download the following project files from GitHub: 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`:
-```
+```bash
cd examples/motoko/internet_identity_integration
dfx new greet
```
@@ -31,7 +31,7 @@ dfx new greet
You should have a starter project generated with the following file structure:
-```
+```bash
├── README.md
├── dfx.json
├── package.json
@@ -55,7 +55,7 @@ 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).**
-```
+```json
"internet_identity": {
"type": "custom",
"candid": "https://github.com/dfinity/internet-identity/releases/latest/download/internet_identity.did",
@@ -74,13 +74,13 @@ This adds a prebuilt Internet Identity canister to your project. The remote prop
### 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
dfx deploy
```
If successful, your output will resemble the following:
-```
+```bash
...
Deployed canisters.
URLs:
@@ -114,7 +114,7 @@ To do so, we can make an environment variable II_URL available using webpack.
Open the `webpack.config.js` file and replace the contents with the following:
-```
+```javascript
const path = require("path");
const webpack = require("webpack");
const HtmlWebpackPlugin = require("html-webpack-plugin");
@@ -243,17 +243,17 @@ module.exports = {
};
```
-### Step 5: Add the auth-client library to the front-end.
+### 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 front-end.
+### Step 6: Add a login button to the frontend.
Open the `index.html` file and replace the content with the following:
-```
+```html
@@ -285,7 +285,7 @@ Open the `index.html` file and replace the content with the following:
### 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
import {createActor, greet_backend} from "../../declarations/greet_backend";
import {AuthClient} from "@dfinity/auth-client"
import {HttpAgent} from "@dfinity/agent";
@@ -336,15 +336,15 @@ loginButton.onclick = async (e) => {
};%
```
-### Step 8: Modify the back-end.
-We want our application to greet the caller principal. In order to do so, the back-end Motoko code needs to be changed to:
+### Step 8: Modify the backend.
+We want our application to greet the caller principal. In order to do so, the backend Motoko code needs to be changed to:
- No longer take a name parameter.
- Use the `message.caller` for the greeting.
Replace the content of `src/greet_backend/main.mo` with the following:
-```
+```motoko
import Principal "mo:base/Principal";
actor {
@@ -358,7 +358,7 @@ actor {
The successful output should resemble the following:
-```
+```bash
Deployed canisters.
URLs:
Frontend canister via browser
diff --git a/motoko/invoice-canister/README.md b/motoko/invoice-canister/README.md
index 04db644c6..3f4be204f 100644
--- a/motoko/invoice-canister/README.md
+++ b/motoko/invoice-canister/README.md
@@ -53,8 +53,10 @@ Begin by opening a terminal window.
### Step 1: Navigate into the folder containing the project's files install the required packages:
-`cd examples/motoko/invoice-canister`
-`npm install`
+```bash
+cd examples/motoko/invoice-canister
+npm install
+```
At this point the project is ready to be deployed to a local replica. As support for four tokens requires four token-ledger canisters, three of these are installed by the downloaded Wasm and did files provided by the [DFINITY Rosetta-API repository](https://github.com/dfinity/ic/tree/master/rs/rosetta-api). These files can be found in the `src/token-ledger-canisters` directory with an accompanying shell script for downloading them independently of this project. The ICRC1 token-ledger canister Wasm and did is deployed twice, once for each of the two ICRC1 tokens integrated. The ICP ledger wasm and did is only deployed once as the other ICP based token has its ledger canister deployed by running the `dfx nns install` command. This to demonstrate the multiple ways of integrating token-ledger canisters into your own projects.
@@ -80,8 +82,10 @@ Once the system-wide `networks.json` is set as above, this project's startup scr
### Step 3: For convenience, two npm scripts have been added to initiate this script:
-`npm run deployAll`
-`npm run deployForTesting`
+```bash
+npm run deployAll
+npm run deployForTesting
+```
If deployed for testing, the Secp256k1 identity the `dfx nns install` command uses as one of its two initial deposit identities is added and switched to as the current user. Whether testing or not, the current identity is used as the minting account for all four token-ledger canisters. See the `clean-startup.mjs` for more details. To see an example of the console output of running this script for testing, the `./docs/clean-startup-console-output` file that can be reviewed in the docs folder.
diff --git a/motoko/ios-notifications/README.md b/motoko/ios-notifications/README.md
index 9adabe799..df17c88c9 100644
--- a/motoko/ios-notifications/README.md
+++ b/motoko/ios-notifications/README.md
@@ -1,9 +1,9 @@
-# IOS integration
+# iOS integration
## Overview
-[IOS integration](https://github.com/dfinity/examples/tree/master/motoko/ios-notifications) is an experimental dapp with a native app integration that showcases a possible solution for integrating a dapp hosted in the Internet Computer with multiple platforms. For this example we've created an iOS app.
+[iOS integration](https://github.com/dfinity/examples/tree/master/motoko/ios-notifications) is an experimental dapp with a native app integration that showcases a possible solution for integrating a dapp hosted in the Internet Computer with multiple platforms. For this example we've created an iOS app.
-We aimed to create an example of a simple integration of a dapp running purely on the IC and is using [Internet Identity](https://internetcomputer.org/docs/current/docs/current/references/ii-spec) with a native iOS application that can let the user have a native feel such as authenticating and receive push notifications.
+We aimed to create an example of a simple integration of a dapp running purely on ICP and is using [Internet Identity](https://internetcomputer.org/docs/current/docs/current/references/ii-spec) with a native iOS application that can let the user have a native feel such as authenticating and receive push notifications.
## Architecture
@@ -33,19 +33,19 @@ dfx start --background --clean
### Step 2: Install the dependency packages:
-```
+```bash
npm install
```
### Step 3: Deploy your canisters:
-```
+```bash
dfx deploy
```
-### Step 4: Start the front-end:
+### Step 4: Start the frontend:
-```
+```bash
npm start
```
@@ -57,7 +57,7 @@ You can now access the dapp at `http://localhost:4943/?canisterId={YOUR_LOCAL_CA
The integration of this dapp with the [Internet Identity](https://internetcomputer.org/docs/current/developer-docs/integrations/internet-identity/integrate-identity) enables authentication. To support the IOS integration, it uses the `delegation` and `key` made available in the browser IndexedDB.
-The steps for IOS authentication are:
+The steps for iOS authentication are:
1. User clicks to authenticate (this triggers the `window.open` to be called).
2. The dapp intercepts the request and opens a new [ASWebAuthenticationSession](https://developer.apple.com/documentation/authenticationservices/aswebauthenticationsession).
@@ -66,7 +66,7 @@ The steps for IOS authentication are:
4. The dapp receives this callback and injects the `delegation` and `key` into the local [WKWebView](https://developer.apple.com/documentation/webkit/wkwebview).
5. The webview reloads and the user is now authenticated, since authentication uses IndexedDB, it continues to work after the user closes the dapp (expiration time of the session is kept, max is 30 days).
-#### An example of how this can be handled:
+#### Example of how this can be handled:
```ts
async handleMultiPlatformLogin(): Promise {
@@ -109,7 +109,7 @@ These are the steps to show an IOS notification:
## Security considerations
- When integrating with Internet Identity make sure to setup and use universal links, other forms of passing the delegation such as a custom app scheme is known to have security risks such as allowing others to impersonate your dapp.
-- For this example we are generating the keypair in the native app but the private key is still available there since the signing of the request happens on the dapp, in your production application make sure this is generated by your native app and stored in a [secure enclave](https://developer.apple.com/documentation/security/certificate_key_and_trust_services/keys/protecting_keys_with_the_secure_enclave), and expose a `sign` method to the dapp through webkit, this will ensure that your dapp does not have access to your private key.
+- For this example we are generating the key pair in the native app but the private key is still available there since the signing of the request happens on the dapp, in your production application make sure this is generated by your native app and stored in a [secure enclave](https://developer.apple.com/documentation/security/certificate_key_and_trust_services/keys/protecting_keys_with_the_secure_enclave), and expose a `sign` method to the dapp through webkit, this will ensure that your dapp does not have access to your private key.
## References
@@ -123,4 +123,4 @@ This is an example dapp that demonstrates the potential of integrating a dapp wi
Please be mindful when considering this code for production and be mindful of:
1. The integration with II in this example is using a universal links which is known to be safer than custom app schemes that are not bound to the appID. To enable this in your production code you should look at setting up [universal links](https://developer.apple.com/documentation/xcode/supporting-universal-links-in-your-app).
-1. APN Certificate Key provided by apple needs to be safely stored to avoid a malicious actor from being able to send notifications to your app users.
+2. APN Certificate Key provided by apple needs to be safely stored to avoid a malicious actor from being able to send notifications to your app users.
diff --git a/motoko/ledger-transfer/README.md b/motoko/ledger-transfer/README.md
index 85853eff7..019595825 100644
--- a/motoko/ledger-transfer/README.md
+++ b/motoko/ledger-transfer/README.md
@@ -19,7 +19,7 @@ This example requires an installation of:
### Step 1: Create a new `dfx` project and navigate into the project's directory.
-```
+```bash
dfx new ledger_transfer
cd ledger_transfer
```
@@ -32,11 +32,11 @@ The URL for the ledger WASM module is `https://download.dfinity.systems/ic//rs/rosetta-api/icrc1/ledger/ledger.did`, so with the above revision it would be `https://raw.githubusercontent.com/dfinity/ic/a17247bd86c7aa4e87742bf74d108614580f216d/rs/rosetta-api/icrc1/ledger/ledger.did`.
-### 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:
+Replace its contents with this, but adapt the URLs to be the ones you determined in step 2:
-```
+```json
{
"canisters": {
"ledger": {
@@ -83,13 +83,13 @@ Replace its contents with this (but adapt the URLs to be the ones you determined
### Step 5: Start a local replica:
-```
+```bash
dfx start --background
```
### Step 6: Create a new identity that will work as a minting account:
-```
+```bash
dfx identity new minter
dfx identity use minter
export MINT_ACC=$(dfx ledger account-id)
@@ -99,35 +99,36 @@ Transfers from the minting account will create Mint transactions. Transfers to t
### Step 7: Switch back to your default identity and record its ledger account identifier:
-```
+```bash
dfx identity use default
export LEDGER_ACC=$(dfx ledger account-id)
```
-
### Step 8: Deploy the ledger canister to your network:
-`dfx canister install ledger --argument "(variant {Init = record { token_name = \"NAME\"; token_symbol = \"SYMB\"; transfer_fee = 1000000; metadata = vec {}; minting_account = record {owner = principal \"$(dfx --identity minter identity get-principal)\";}; initial_balances = vec {}; archive_options = record {num_blocks_to_archive = 1000000; trigger_threshold = 1000000; controller_id = principal \"$(dfx identity get-principal)\"}; }})"`
+```bash
+dfx canister install ledger --argument "(variant {Init = record { token_name = \"NAME\"; token_symbol = \"SYMB\"; transfer_fee = 1000000; metadata = vec {}; minting_account = record {owner = principal \"$(dfx --identity minter identity get-principal)\";}; initial_balances = vec {}; archive_options = record {num_blocks_to_archive = 1000000; trigger_threshold = 1000000; controller_id = principal \"$(dfx identity get-principal)\"}; }})"
+```
If you want to setup the ledger in a way that matches the production deployment, you should deploy it with archiving enabled. In this setup, the ledger canister dynamically creates new canisters to store old blocks. We recommend using this setup if you are planning to exercise the interface for fetching blocks.
### Step 9: Obtain the principal of the identity you use for development.
This principal will be the controller of archive canisters.
-```
+```bash
dfx identity use default
export ARCHIVE_CONTROLLER=$(dfx identity get-principal)
```
### Step 10: Deploy the ledger canister with archiving options:
-```
+```bash
dfx deploy ledger --argument '(record {minting_account = "'${MINT_ACC}'"; initial_values = vec { record { "'${LEDGER_ACC}'"; record { e8s=100_000_000_000 } }; }; send_whitelist = vec {}; archive_options = opt record { trigger_threshold = 2000; num_blocks_to_archive = 1000; controller_id = principal "'${ARCHIVE_CONTROLLER}'" }})'
```
If successful, the output should be:
-```
+```bash
Deployed canisters.
URLs:
Frontend canister via browser
@@ -139,31 +140,31 @@ URLs:
### Step 11: Verify that the ledger canister is healthy and working as expected by using the command:
-```
+```bash
dfx canister call ledger account_balance '(record { account = '$(python3 -c 'print("vec{" + ";".join([str(b) for b in bytes.fromhex("'$LEDGER_ACC'")]) + "}")')' })'
```
The output should be:
-```
+```bash
(record { e8s = 100_000_000_000 : nat64 })
```
### Step 10: In a separate working directory, clone the Github repo containing the `ledger_transfer` project's files:
-```
+```bash
git clone https://github.com/dfinity/examples.git
```
### Step 11: Copy the files for the `ledger-transfer` canister into your `ledger_transfer` workspace:
-```
+```bash
cp -r ./examples/motoko/ledger-transfer/src/* ./ledger_transfer/src
```
### Step 12: Edit your `dfx.json` file to include the following information within the 'canisters' section:
-```
+```json
...
"canisters": {
"ledger_transfer": {
@@ -185,13 +186,13 @@ cp -r ./examples/motoko/ledger-transfer/src/* ./ledger_transfer/src
### Step 13: Deploy this new canister:
-```
+```bash
dfx deploy
```
Your output should resemble the following:
-```
+```bash
Deployed canisters.
URLs:
Frontend canister via browser
@@ -204,13 +205,13 @@ URLs:
### Step 14: Determine out the address of your canister:
-```
+```bash
dfx canister call ledger_transfer canisterAccount '()'
```
Your output should resemble the following:
-```
+```bash
(
blob "\94\b9\bc]\ab(\ad\b93\8dE\19#\914\b6\a0\0e\dfam5\e4\e5\80\b5\01\9a~\e1_{",
)
@@ -218,19 +219,19 @@ Your output should resemble the following:
### Step 15: Transfer funds to your canister:
-```
+```bash
dfx canister call ledger transfer '(record { to = blob "\08.\cf.?dz\c6\00\f4?8\a6\83B\fb\a5\b8\e6\8b\08_\02Y+w\f3\98\08\a8\d2\b5"; memo = 1; amount = record { e8s = 2_00_000_000 }; fee = record { e8s = 10_000 }; })'
```
If successful, the output should be:
-```
+```bash
(variant { Ok = 1 : nat64 })
```
### Step 16: Post a message as a new user:
-```
+```bash
dfx identity new --disable-encryption ALICE
dfx identity use ALICE
dfx canister call ledger_transfer post "(\"Test message\")"
@@ -238,12 +239,12 @@ dfx canister call ledger_transfer post "(\"Test message\")"
### Step 17: Distribute rewards to users:
-```
+```bash
dfx identity use default
dfx canister call ledger_transfer distributeRewards '()'
```
-## Security considerations and security best practices
+## Security considerations and best practices
If you base your application on this example, we recommend you familiarize yourself with and adhere to the [security best practices](https://internetcomputer.org/docs/current/references/security/) for developing on the Internet Computer. This example may not implement all the best practices.
diff --git a/motoko/life/README.md b/motoko/life/README.md
index 14446152a..ce81e8360 100644
--- a/motoko/life/README.md
+++ b/motoko/life/README.md
@@ -1,4 +1,4 @@
-# Game of Life
+# Game of life
## Overview
@@ -27,14 +27,14 @@ 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:
-```
+```bash
cd examples/motoko/life
dfx start --background
```
### Step 2: Deploy the canister:
-```
+```bash
dfx deploy
```
@@ -42,7 +42,7 @@ The deployment step should report a canister id for the life_assets canister.
Take note of the URL at which the life_assets is accessible using the command:
-```
+```bash
echo "http://127.0.0.1:4943/?canisterId=$(dfx canister id life_assets)"
```
@@ -60,7 +60,7 @@ Because the v0 implementation makes no provision for upgrades, every time you re
The state of the grid is represented naively as a nested, mutable array of Boolean values, as described in the `src/State.mo` file:
-```
+```motoko
module {
public type Cell = Bool;
@@ -73,7 +73,7 @@ A `src/life/grid` is represented as a simple class constructed from, and maintai
The main actor in `src/life/main` creates a random state and maintains two grid objects, the current and next grid (`cur` and `nxt`). Life's `next()` method advances the Game of Life to the next generation by updating `nxt` from `cur`, using Grid method call `cur.next(nxt)`. The roles of `cur` and `nxt` are then swapped to re-use `cur`'s space for the next generation (a simple application of double-buffering). This logic is described in the `src/life/main.mo` file:
-```
+```motoko
import Random = "Random";
import State = "State";
import Grid = "Grid";
@@ -110,7 +110,7 @@ Note that none of the variables in this actor are declared stable so their value
### Upgrading to v1
To upgrade to the v1 implementation, issue these commands:
-```
+```bash
mv src versions/v0
mv versions/v1 src
dfx deploy
@@ -127,7 +127,7 @@ However, if you re-deploy the v1 project a second time, perhaps after making a m
### Upgrading to v2:
To upgrade to the v2 implementation, issue these commands:
-```
+```bash
mv src versions/v1
mv versions/v2 src
dfx deploy
@@ -137,7 +137,7 @@ Return to the same browser tab. Refresh the tab. Note the current grid state is
Click button **Run**, then click button **Pause** when bored. Open **Details** and click **View State**. Admire the #v2 state on display.
-## Security considerations and security best practices
+## Security considerations and best practices
If you base your application on this example, we recommend you familiarize yourself with and adhere to the [security best practices](https://internetcomputer.org/docs/current/references/security/) for developing on the Internet Computer. This example may not implement all the best practices.
diff --git a/motoko/minimal-counter-dapp/README.md b/motoko/minimal-counter-dapp/README.md
index 9f9feb521..8b7a05a58 100644
--- a/motoko/minimal-counter-dapp/README.md
+++ b/motoko/minimal-counter-dapp/README.md
@@ -6,16 +6,16 @@
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 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. The dapp is a simple website with a counter. Every time a button is pressed, a counter is incremented.
+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. The dapp is a simple website with a counter. Every time a button is pressed, a counter is incremented.
This example covers:
-- Create new canister smart contract using the IC SDK (DFX).
+- Create 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 (count, get count and reset count).
- 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.
+- Test backend with Candid UI and command line using dfx, and test frontend in browser.
## Prerequisites
@@ -27,9 +27,9 @@ 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 replica with the command:
-```
+```bash
cd examples/motoko/minimal-counter-dapp
npm install
dfx start --background
@@ -37,13 +37,13 @@ dfx start --background
### Step 2: Build and deploy the canister:
-```
+```bash
dfx deploy
```
The output will resemble the following:
-```
+```bash
Deployed canisters.
URLs:
Frontend canister via browser
@@ -152,7 +152,7 @@ document.getElementById("clickMeBtn").addEventListener("click", async () => {
```
#### dfx
-DFX has a subset of commands for canister operations, and one of them enables calling the public functions added to the `main.mo` file in the previous step. In the following examples the initial value is 0. `count` will increment value and return 1, `getCount` will return the current value and `reset` will set the value to 0.
+dfx has a subset of commands for canister operations, and one of them enables calling the public functions added to the `main.mo` file in the previous step. In the following examples the initial value is 0. `count` will increment value and return 1, `getCount` will return the current value and `reset` will set the value to 0.
Command usage: `dfx canister call `
@@ -188,7 +188,7 @@ rrkah-fqaaa-aaaaa-aaaaq-cai
## License
This project is licensed under the Apache 2.0 license, see LICENSE.md for details. See CONTRIBUTE.md for details about how to contribute to this project.
-## Security considerations and security best practices
+## Security considerations and best practices
If you base your application on this example, we recommend you familiarize yourself with and adhere to the [security best practices](https://internetcomputer.org/docs/current/references/security/) for developing on the Internet Computer. This example may not implement all the best practices.
diff --git a/motoko/persistent-storage/README.md b/motoko/persistent-storage/README.md
index 78e75203e..bc945ece6 100644
--- a/motoko/persistent-storage/README.md
+++ b/motoko/persistent-storage/README.md
@@ -28,46 +28,46 @@ 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:
-```
+```bash
cd examples/motoko/persistent-storage
dfx start --background
```
### Step 2: Build and deploy the canister:
-```
+```bash
dfx deploy
```
### Step 3: Command usage: `dfx canister call `
-```
+```bash
dfx canister call persistent_storage increment
```
Output:
-```
+```bash
(1 : Nat)
```
-```
+```bash
dfx canister call persistent_storage get
```
Output:
-```
+```bash
(1 : Nat)
```
-```
+```bash
dfx canister call persistent_storage reset
```
Output:
-```
+```bash
(0 : Nat)
```
@@ -144,7 +144,7 @@ rrkah-fqaaa-aaaaa-aaaaq-cai
This project is licensed under the Apache 2.0 license, see LICENSE.md for details. See CONTRIBUTE.md for details about how to contribute to this project.
-## Security Considerations and Security Best Practices
+## Security considerations and best practices
If you base your application on this example, we recommend you familiarize yourself with and adhere to the [Security Best Practices](https://internetcomputer.org/docs/current/references/security/) for developing on the Internet Computer. This example may not implement all the best practices.
diff --git a/motoko/phone-book/README.md b/motoko/phone-book/README.md
index 4037bc9aa..45bcbeff4 100644
--- a/motoko/phone-book/README.md
+++ b/motoko/phone-book/README.md
@@ -22,28 +22,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 Internet Computer 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:
-```
+```bash
cd examples/motoko/phone-book
dfx start --background
```
### Step 2: Install front-end dependencies:
-```
+```bash
npm install
```
### Step 3: Deploy the canister:
-```
+```bash
dfx deploy
```
### Step 4: Take note of the URL at which the phone book is accessible.
-```
+```bash
echo "http://127.0.0.1:4943/?canisterId=$(dfx canister id www)"
```
diff --git a/motoko/pub-sub/README.md b/motoko/pub-sub/README.md
index 3fbd28a95..a394b2327 100644
--- a/motoko/pub-sub/README.md
+++ b/motoko/pub-sub/README.md
@@ -1,12 +1,9 @@
-# Design Pattern: Pub/Sub
-
-
-[](https://github.com/dfinity/examples/actions?query=workflow%3Amotoko-pub-sub-example)
+# PubSub
## 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.
+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
This example requires an installation of:
@@ -15,44 +12,44 @@ 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 replica with the command:
-```
+```bash
cd examples/motoko/pub-sub
dfx start --background
```
### Step 2: Deploy the canister:
-```
+```bash
dfx deploy
```
### Step 3: Subscribe to the "Apples" topic:
-```
+```bash
dfx canister call sub init '("Apples")'
```
### Step 4: Publish to the "Apples" topic:
-```
+```bash
dfx canister call pub publish '(record { "topic" = "Apples"; "value" = 2 })'
```
### Step 5: Receive your subscription:
-```
+```bash
dfx canister call sub getCount
```
The output should resemble the following:
-```
+```bash
(2 : nat)
```
-## Security considerations and security best practices
+## Security considerations and best practices
If you base your application on this example, we recommend you familiarize yourself with and adhere to the [security best practices](https://internetcomputer.org/docs/current/references/security/) for developing on the Internet Computer. This example may not implement all the best practices.
diff --git a/motoko/quicksort/README.md b/motoko/quicksort/README.md
index a3627c0e1..691f087c9 100644
--- a/motoko/quicksort/README.md
+++ b/motoko/quicksort/README.md
@@ -15,28 +15,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 Internet Computer 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:
-```
+```bash
cd examples/motoko/quicksort
dfx start --background
```
### Step 2: Deploy the canister:
-```
+```bash
dfx deploy
```
### Step 3: Sort an array of integers.
-```
+```bash
dfx canister call quicksort sort '(vec { 5; 3; 0; 9; 8; 2; 1; 4; 7; 6 })'
```
The output will resemble the following:
-```
+```bash
(
vec {
0 : int;
@@ -53,7 +53,7 @@ The output will resemble the following:
)
```
-## Security considerations and security best practices
+## Security considerations and best practices
If you base your application on this example, we recommend you familiarize yourself with and adhere to the [security best practices](https://internetcomputer.org/docs/current/references/security/) for developing on the Internet Computer. This example may not implement all the best practices.
diff --git a/motoko/random_maze/README.md b/motoko/random_maze/README.md
index 497333f3b..492c24c87 100644
--- a/motoko/random_maze/README.md
+++ b/motoko/random_maze/README.md
@@ -1,8 +1,4 @@
-# Random Maze
-
-
-[](https://github.com/dfinity/examples/actions?query=workflow%3Amotoko-random_maze-example)
-
+# Random maze
## Overview
The example generates a random maze using cryptographic randomness.
@@ -17,7 +13,7 @@ The application is built from the following Motoko source code file:
- `main.mo`: contains the actor definition and methods exposed by this canister.
-This actor use Motoko's Random library to generate a cryptographically random maze of user-specified size.
+This actor use Motoko's random library to generate a cryptographically random maze of user-specified size.
Function generate, calls library function `Random.blob()` asynchronously to obtain 256-bits of raw entropy (256 random bits as 32 bytes) from the Internet Computer. It makes these calls on demand as it is constructing a maze. The bits of these blobs are consumed to generate samples from a variety of discrete distributions using some of the other classes and functions of library Random.mo.
@@ -30,34 +26,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 Internet Computer 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:
-```
+```bash
cd examples/motoko/random_maze
dfx start --background
```
### Step 2: Install front-end dependencies:
-```
+```bash
npm install
```
### Step 3: Deploy the canister:
-```
+```bash
dfx deploy
```
### 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)"
```
Enter a size for the maze, then select **Generate!**. The maze will be displayed.
-## Security considerations and security best practices
+## Security considerations and best practices
If you base your application on this example, we recommend you familiarize yourself with and adhere to the [security best practices](https://internetcomputer.org/docs/current/references/security/) for developing on the Internet Computer. This example may not implement all the best practices.
diff --git a/motoko/send_http_get/README.md b/motoko/send_http_get/README.md
index 0eb9a3742..3ae19461e 100644
--- a/motoko/send_http_get/README.md
+++ b/motoko/send_http_get/README.md
@@ -1,4 +1,4 @@
-# send_http_get
+# 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.
diff --git a/motoko/send_http_post/README.md b/motoko/send_http_post/README.md
index 371fbcd68..5ab1a95b3 100644
--- a/motoko/send_http_post/README.md
+++ b/motoko/send_http_post/README.md
@@ -1,4 +1,4 @@
-# send_http_post
+# 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.
diff --git a/motoko/simple-to-do/README.md b/motoko/simple-to-do/README.md
index 6e42cb02e..b97900a65 100644
--- a/motoko/simple-to-do/README.md
+++ b/motoko/simple-to-do/README.md
@@ -1,8 +1,3 @@
-# Simple To-Do
-
-
-[](https://github.com/dfinity/examples/actions?query=workflow%3Amotoko-simple-to-do-example)
-
# Simple to-do
## Overview
@@ -23,22 +18,22 @@ 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 replica with the command:
-```
+```bash
cd examples/motoko/simple-to-do
dfx start --background
```
### Step 2: Deploy the canister:
-```
+```bash
dfx deploy
```
### Step 3: Create a to-do checklist by invoking the addTodo method:
-```
+```bash
dfx canister call simple_to_do addTodo '("Create a project")'
dfx canister call simple_to_do addTodo '("Build the project")'
dfx canister call simple_to_do addTodo '("Deploy the project")'
@@ -46,13 +41,13 @@ dfx canister call simple_to_do addTodo '("Deploy the project")'
### Step 4: Display the to-do checklist by invoking the showTodos method:
-```
+```bash
dfx canister call simple_to_do showTodos
```
### Step 5: Verify the output returns the values you inputted:
-```
+```bash
("
___TO-DOs___
(1) Create a project
@@ -62,26 +57,26 @@ ___TO-DOs___
### Step 6: Complete a to-do checklist item by invoking the completeTodo method:
-```
+```bash
dfx canister call simple_to_do completeTodo '(1)'
```
### Step 7: Display the to-do checklist by invoking the showTodos method.
-```
+```bash
dfx canister call simple_to_do showTodos
```
### Step 8: Verify the return value matches what you would expect.
-```
+```bash
("
___TO-DOs___
(1) Create a project ✔
(2) Build the project
(3) Deploy the project")
```
-## Security considerations and security best practices
+## Security considerations and best practices
If you base your application on this example, we recommend you familiarize yourself with and adhere to the [security best practices](https://internetcomputer.org/docs/current/references/security/) for developing on the Internet Computer. This example may not implement all the best practices.
diff --git a/motoko/superheroes/README.md b/motoko/superheroes/README.md
index d163eefbd..afd217a52 100644
--- a/motoko/superheroes/README.md
+++ b/motoko/superheroes/README.md
@@ -1,11 +1,8 @@
## Superheroes
-
-[](https://github.com/dfinity/examples/actions?query=workflow%3Amotoko-superheroes-example)
-
## Overview
-This example demonstrates how to build a CRUD application on the Internet Computer using Motoko and React.
+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.
@@ -16,35 +13,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 Internet Computer 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:
-```
+```bash
cd examples/motoko/superheros
dfx start --background
```
### Step 2: Build the front-end of the application:
-```
+```bash
npm install
```
### Step 3: Deploy the canister:
-```
+```bash
dfx deploy
```
### Step 4: 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.
-You will see the following interface that you can interact with.
-## Security considerations and security best practices
+## Security considerations and best practices
If you base your application on this example, we recommend you familiarize yourself with and adhere to the [security best practices](https://internetcomputer.org/docs/current/references/security/) for developing on the Internet Computer. This example may not implement all the best practices.
diff --git a/motoko/threshold-ecdsa/README.md b/motoko/threshold-ecdsa/README.md
index 30d800462..93166bbb6 100644
--- a/motoko/threshold-ecdsa/README.md
+++ b/motoko/threshold-ecdsa/README.md
@@ -1,4 +1,4 @@
-# Threshold ECDSA signing code walkthrough
+# Threshold ECDSA sample
## Overview
@@ -21,11 +21,11 @@ This walkthrough focuses on the version of the sample canister code written in [
## 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.
-## Step 1: Getting started
+## 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
+## Deploy and test the canister locally
This tutorial will use the Motoko version of the canister:
@@ -52,18 +52,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.
-## Step 2: Deploying the canister on IC mainnet
+### Deploying the canister on the mainnet
-To deploy this canister the IC mainnet, one needs to do two things:
+To deploy this canister to 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/setup/cycles). You can get free cycles from the [cycles faucet](https://internetcomputer.org/docs/current/developer-docs/setup/cycles/cycles-faucet.md).
-### 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 mainnet, one should modify the code to use the right name of the `key_id`.
@@ -99,7 +99,7 @@ let { signature } = await ic.sign_with_ecdsa({
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 mainnet via IC SDK
+### Deploy to the mainnet via IC SDK
To [deploy via mainnet](https://internetcomputer.org/docs/current/developer-docs/setup/deploy-mainnet.md), run the following commands:
@@ -118,7 +118,7 @@ URLs:
In example above, `ecdsa_example_motoko` has the URL https://a3gq9-oaaaa-aaaab-qaa4q-cai.raw.icp0.io/?id=736w4-cyaaa-aaaal-qb3wq-cai and serves up the Candid web UI for this particular canister deployed on mainnet.
-## Step 3: Obtaining public keys
+## Obtaining public keys
### Using the Candid web UI
@@ -183,7 +183,7 @@ For obtaining the canister's root public key, the derivation path in the API can
- For obtaining a canister's public key below its root key in the BIP-32 key derivation hierarchy, a derivation path needs to be specified. As explained in the general documentation, each element in the array of the derivation path is either a 32-bit integer encoded as 4 bytes in big endian or a byte array of arbitrary length. The element is used to derive the key in the corresponding level at the derivation hierarchy.
- In the example code above, we use the bytes extracted from the `msg.caller` principal in the `derivation_path`, so that different callers of `public_key()` method of our canister will be able to get their own public keys.
-## Step 4: Signing
+## Signing
Computing threshold ECDSA signatures is the core functionality of this feature. **Canisters do not hold ECDSA keys themselves**, but keys are derived from a master key held by dedicated subnets. A canister can request the computation of a signature through the management canister API. The request is then routed to a subnet holding the specified key and the subnet computes the requested signature using threshold cryptography. Thereby, it derives the canister root key or a key obtained through further derivation, as part of the signature protocol, from a shared secret and the requesting canister's principal identifier. Thus, a canister can only request signatures to be created for their canister root key or a key derived from it. This means, canisters "control" their private ECDSA keys in that they decide when signatures are to be created with them, but don't hold a private key themselves.
@@ -205,7 +205,7 @@ Computing threshold ECDSA signatures is the core functionality of this feature.
};
```
-## Step 5: Signature verification
+## Signature verification
For completeness of the example, we show that the created signatures can be verified with the public key corresponding to the same canister and derivation path.
diff --git a/motoko/vetkd/README.md b/motoko/vetkd/README.md
index 272d54eb0..5943ea877 100644
--- a/motoko/vetkd/README.md
+++ b/motoko/vetkd/README.md
@@ -1,4 +1,4 @@
-# vetKD System API Preview
+# vetKD API
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**.
@@ -16,51 +16,51 @@ 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 by means of 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
-- [ ] Install the [IC SDK](https://internetcomputer.org/docs/current/developer-docs/setup/install/).
-- [ ] Install [Node.js](https://nodejs.org/en/download/).
-- [ ] 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 the Internet Computer.
+- [x] Install the [IC SDK](https://internetcomputer.org/docs/current/developer-docs/setup/install/).
+- [x] Install [Node.js](https://nodejs.org/en/download/).
+- [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.
-## Running Locally
+## Running locally
-1. Start a local internet computer.
+- #### Step 1: Start a local replica:
- ```sh
- dfx start
- ```
+```sh
+dfx start
+```
-1. Open a new terminal window.
+- #### Step 2: Open a new terminal window.
-1. Ensure the Canister SDK (dfx) uses the canister IDs that are hard-coded in the Rust source code:
+- #### Step 3: Ensure the IC SDK (dfx) uses the canister IDs that are hard-coded in the Rust source code:
- ```sh
- dfx canister create system_api --specified-id s55qq-oqaaa-aaaaa-aaakq-cai
- ```
+```sh
+dfx canister create system_api --specified-id s55qq-oqaaa-aaaaa-aaakq-cai
+```
- Without this, the Canister SDK (dfx) may use different canister IDs for the `system_api` and `app_backend` canisters in your local environment.
+Without this, the IC SDK (dfx) may use different canister IDs for the `system_api` and `app_backend` canisters in your local environment.
-1. Ensure that the required node modules are available in your project directory, if needed, by running the following command:
+- #### Step 4: Ensure that the required node modules are available in your project directory, if needed, by running the following command:
- ```sh
- npm install
- ```
+```sh
+npm install
+```
-1. Register, build and deploy the project:
+- #### Step 5: Register, build and deploy the project:
- ```sh
- dfx deploy
- ```
+```sh
+dfx deploy
+```
- This command should finish successfully with output similar to the following one:
+This command should finish successfully with output similar to the following one:
- ```sh
- Deployed canisters.
- URLs:
- Frontend canister via browser
- app_frontend_js: http://127.0.0.1:4943/?canisterId=by6od-j4aaa-aaaaa-qaadq-cai
- Backend canister via Candid interface:
- app_backend: http://127.0.0.1:4943/?canisterId=avqkn-guaaa-aaaaa-qaaea-cai&id=tcvdh-niaaa-aaaaa-aaaoa-cai
- app_frontend: http://127.0.0.1:4943/?canisterId=avqkn-guaaa-aaaaa-qaaea-cai&id=b77ix-eeaaa-aaaaa-qaada-cai
- system_api: http://127.0.0.1:4943/?canisterId=avqkn-guaaa-aaaaa-qaaea-cai&id=s55qq-oqaaa-aaaaa-aaakq-cai
- ```
+```sh
+Deployed canisters.
+URLs:
+Frontend canister via browser
+ app_frontend_js: http://127.0.0.1:4943/?canisterId=by6od-j4aaa-aaaaa-qaadq-cai
+Backend canister via Candid interface:
+ app_backend: http://127.0.0.1:4943/?canisterId=avqkn-guaaa-aaaaa-qaaea-cai&id=tcvdh-niaaa-aaaaa-aaaoa-cai
+ app_frontend: http://127.0.0.1:4943/?canisterId=avqkn-guaaa-aaaaa-qaaea-cai&id=b77ix-eeaaa-aaaaa-qaada-cai
+ system_api: http://127.0.0.1:4943/?canisterId=avqkn-guaaa-aaaaa-qaaea-cai&id=s55qq-oqaaa-aaaaa-aaakq-cai
+```
-1. Open the printed URL for the `app_frontend_js` in your browser.
+- #### Step 6: 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 05798a97c..cd0c7e64e 100644
--- a/motoko/whoami/README.md
+++ b/motoko/whoami/README.md
@@ -15,16 +15,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 Internet Computer 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:
-```
+```bash
cd examples/motoko/whoami
dfx start --background
```
### 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")'
dfx build
dfx deploy
@@ -32,7 +32,7 @@ dfx deploy
### Step 3: Invoke the `whoami` method:
-```
+```bash
dfx canister call whoami whoami
```
@@ -40,14 +40,14 @@ dfx canister call whoami whoami
### Step 5: Invoke the `id` method:
-```
+```bash
dfx canister call whoami id
```
### Step 6: Observe the principal identifier of your canister.
-## Security considerations and security best practices
+## Security considerations and best practices
If you base your application on this example, we recommend you familiarize yourself with and adhere to the [security best practices](https://internetcomputer.org/docs/current/references/security/) for developing on the Internet Computer. This example may not implement all the best practices.
diff --git a/rust/basic_bitcoin/README.md b/rust/basic_bitcoin/README.md
index 28092a336..7ed26a3d5 100644
--- a/rust/basic_bitcoin/README.md
+++ b/rust/basic_bitcoin/README.md
@@ -1,6 +1,4 @@
-# Basic Bitcoin example
-
-## Deploying your first Bitcoin dapp
+# 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.
@@ -91,18 +89,18 @@ Or, if you prefer the command line:
used for sending/receiving Bitcoin on the Bitcoin testnet.
-## Step 3: Receiving Bitcoin
+## Step 3: Receiving bitcoin
Now that the canister is deployed and you have a Bitcoin address, it's time to receive
-some testnet Bitcoin. You can use one of the Bitcoin faucets, such as [coinfaucet.eu](https://coinfaucet.eu),
+some testnet bitcoin. You can use one of the Bitcoin faucets, such as [coinfaucet.eu](https://coinfaucet.eu),
to receive some bitcoin.
-Enter your address and click on "Send testnet Bitcoins". In the example below we will use bitcoin address `n31eU1K11m1r58aJMgTyxGonu7wSMoUYe7`, but you would use your own address. The canister will be receiving 0.011 test BTC on the Bitcoin Testnet.
+Enter your address and click on "Send testnet bitcoins". In the example below we will use Bitcoin address `n31eU1K11m1r58aJMgTyxGonu7wSMoUYe7`, but you would use your own address. The canister will be receiving 0.011 test BTC on the Bitcoin Testnet.
Once the transaction has at least one confirmation, which can take a few minutes,
you'll be able to see it in your canister's balance.
-## Step 4: Checking your Bitcoin balance
+## Step 4: Checking your bitcoin balance
You can check a Bitcoin address's balance by using the `get_balance` endpoint on your canister.
@@ -110,22 +108,26 @@ In the Candid UI, paste in your canister's address, and click on "Call":
Alternatively, make the call using the command line. Be sure to replace `mheyfRsAQ1XrjtzjfU1cCH2B6G1KmNarNL` with your own generated P2PKH address:
- dfx canister --network=ic call basic_bitcoin get_balance '("mheyfRsAQ1XrjtzjfU1cCH2B6G1KmNarNL")'
+```bash
+dfx canister --network=ic call basic_bitcoin get_balance '("mheyfRsAQ1XrjtzjfU1cCH2B6G1KmNarNL")'
+```
Checking the balance of a Bitcoin address relies on the [bitcoin_get_balance](https://internetcomputer.org/docs/current/references/ic-interface-spec/#ic-bitcoin_get_balance) API.
-## Step 5: Sending Bitcoin
+## Step 5: Sending bitcoin
-You can send Bitcoin using the `send` endpoint on your canister.
+You can send bitcoin using the `send` endpoint on your canister.
In the Candid UI, add a destination address and an amount to send. In the example
below, we're sending 4'321 Satoshi (0.00004321 BTC) back to the testnet faucet.
Via command line, the same call would look like this:
- dfx canister --network=ic call basic_bitcoin send '(record { destination_address = "tb1ql7w62elx9ucw4pj5lgw4l028hmuw80sndtntxt"; amount_in_satoshi = 4321; })'
+```bash
+dfx canister --network=ic call basic_bitcoin send '(record { destination_address = "tb1ql7w62elx9ucw4pj5lgw4l028hmuw80sndtntxt"; amount_in_satoshi = 4321; })'
+```
-The `send` endpoint is able to send Bitcoin by:
+The `send` endpoint is able to send bitcoin by:
1. Getting the percentiles of the most recent fees on the Bitcoin network using the [bitcoin_get_current_fee_percentiles API](https://internetcomputer.org/docs/current/references/ic-interface-spec/#ic-bitcoin_get_current_fee_percentiles).
2. Fetching your unspent transaction outputs (UTXOs), using the [bitcoin_get_utxos API](https://internetcomputer.org/docs/current/references/ic-interface-spec/#ic-bitcoin_get_utxos).
@@ -143,7 +145,7 @@ reflected in your current balance.
In this tutorial, you were able to:
-* Deploy a canister smart contract on the ICP blockchain that can receive & send Bitcoin.
+* Deploy a canister smart contract on the ICP blockchain that can receive & send bitcoin.
* Use a cycles faucet to deploy the canister to ICP blockchain on mainnet for free.
* Connect the canister to the Bitcoin testnet.
* Send the canister some testnet BTC.
@@ -155,7 +157,7 @@ This example is extensively documented in the following tutorials:
* [Deploying your first Bitcoin dapp](https://internetcomputer.org/docs/current/samples/deploying-your-first-bitcoin-dapp).
* [Developing Bitcoin dapps locally](https://internetcomputer.org/docs/current/developer-docs/integrations/bitcoin/local-development).
-## Security considerations and security best practices
+## Security considerations and best practices
If you base your application on this example, we recommend you familiarize yourself with and adhere to the [security best practices](https://internetcomputer.org/docs/current/references/security/) for developing on the Internet Computer. This example may not implement all the best practices.
diff --git a/rust/basic_dao/README.md b/rust/basic_dao/README.md
index 679787d44..816daf465 100644
--- a/rust/basic_dao/README.md
+++ b/rust/basic_dao/README.md
@@ -1,4 +1,4 @@
-# Basic decentralized autonomous organization (DAO)
+# 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).
@@ -12,15 +12,7 @@ Certain system parameters, like the number of `Yes` votes needed to pass a propo
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.
-## Security considerations and security best practices
-
-If you base your application on this example, we recommend you familiarize yourself with and adhere to the [security best practices](https://internetcomputer.org/docs/current/references/security/) for developing on the Internet Computer. This example may not implement all the best practices.
-
-For example, the following aspects are particularly relevant for this app:
-* [Use a decentralized governance system like SNS to make a canister have a decentralized controller](https://internetcomputer.org/docs/current/references/security/rust-canister-development-security-best-practices#use-a-decentralized-governance-system-like-sns-to-make-a-canister-have-a-decentralized-controller), since this is a DAO's use case.
-* [Certify query responses if they are relevant for security](https://internetcomputer.org/docs/current/references/security/general-security-best-practices#certify-query-responses-if-they-are-relevant-for-security), since e.g. account_balance and list_accounts are query calls that a client may want to issue as update call.
-
-### Prerequisites
+## Prerequisites
This example requires an installation of:
- [x] The Rust toolchain (e.g. cargo).
@@ -30,29 +22,29 @@ This example requires an installation of:
Begin by opening a terminal window.
-* #### Step 1: Build the `basic_dao` canister:
+### Step 1: Build the `basic_dao` canister:
-```
+```bash
make clean; make
```
- ### Step 2: Navigate into the folder containing the project's files and start a local instance of the Internet Computer with the command:
+### Step 2: Navigate into the folder containing the project's files and start a local instance of the Internet Computer with the command:
-```
+```bash
cd basic_dao
dfx start --background
```
- ### Step 3: Create test identities with the commands:
+### Step 3: Create test identities with the commands:
-```
+```bash
dfx identity new --disable-encryption Alice; dfx identity use Alice; export ALICE=$(dfx identity get-principal);
dfx identity new --disable-encryption Bob; dfx identity use Bob; export BOB=$(dfx identity get-principal);
```
- ### Step 4: Deploy basic_dao with the initial test accounts:
+### Step 4: Deploy basic_dao with the initial test accounts:
-```
+```bash
dfx deploy --argument "(record {
accounts = vec { record { owner = principal \"$ALICE\"; tokens = record { amount_e8s = 100_000_000:nat64 }; };
record { owner = principal \"$BOB\"; tokens = record { amount_e8s = 100_000_000:nat64 };}; };
@@ -65,15 +57,15 @@ dfx deploy --argument "(record {
})"
```
- ### Step 5: List accounts and confirm you see the two test accounts:
+### Step 5: List accounts and confirm you see the two test accounts:
-```
+```bash
dfx canister call basic_dao list_accounts '()'
```
Output:
-```
+```bash
(
vec {
record {
@@ -88,37 +80,39 @@ Output:
)
```
- ### Step 6: Call `account_balance` as Bob:
+### Step 6: Call `account_balance` as Bob:
-```
+```bash
dfx canister call basic_dao account_balance '()'
```
You should see the output:
-```
+```bash
(record { amount_e8s = 100_000_000 : nat64 })
```
- ### Step 7: Transfer tokens to Alice:
+### Step 7: Transfer tokens to Alice:
-```
+```bash
dfx canister call basic_dao transfer "(record { to = principal \"$ALICE\"; amount = record { amount_e8s = 90_000_000:nat;};})";
```
Output:
-`(variant { Ok })`
+```bash
+(variant { Ok })
+```
- ### Step 8: List accounts and see that the transfer was made:
+### Step 8: List accounts and see that the transfer was made:
-```
+```bash
dfx canister call basic_dao list_accounts '()'
```
Output:
-```
+```bash
(
vec {
record {
@@ -137,15 +131,15 @@ Output:
Note that the transfer fee was deducted from Bob's account.
:::
- ### Step 9: Let's make a proposal to change the transfer fee. We can call `get_system_params` to learn the current transfer fee:
+### Step 9: Let's make a proposal to change the transfer fee. You can call `get_system_params` to learn the current transfer fee:
-```
+```bash
dfx canister call basic_dao get_system_params '()';
```
Output:
-```
+```bash
(
record {
transfer_fee = record { amount_e8s = 10_000 : nat64 };
@@ -155,9 +149,9 @@ Output:
)
```
-To change `transfer_fee`, we need to submit a proposal by calling `submit_proposal`, which takes a `ProposalPayload` as an arg:
+To change `transfer_fee`, you need to submit a proposal by calling `submit_proposal`, which takes a `ProposalPayload` as an arg:
-```
+```bash
type ProposalPayload = record {
canister_id: principal;
method: text;
@@ -165,17 +159,21 @@ type ProposalPayload = record {
};
```
-We can change `transfer_fee` by calling `basic_dao`'s `update_system_params` method. This method takes a `UpdateSystemParamsPayload` as an arg, which we need to encode into a blob to use in `ProposalPayload`. Use didc to encode a `UpdateSystemParamsPayload`:
+You can change `transfer_fee` by calling `basic_dao`'s `update_system_params` method. This method takes a `UpdateSystemParamsPayload` as an arg, which we need to encode into a blob to use in `ProposalPayload`. Use didc to encode a `UpdateSystemParamsPayload`:
-`didc encode '(record { transfer_fee = opt record { amount_e8s = 20_000:nat64; }; })' -f blob`
+```bash
+didc encode '(record { transfer_fee = opt record { amount_e8s = 20_000:nat64; }; })' -f blob
+```
Output:
-`blob "DIDL\03l\01\f2\c7\94\ae\03\01n\02l\01\b9\ef\93\80\08x\01\00\01 N\00\00\00\00\00\00"`
+```bash
+blob "DIDL\03l\01\f2\c7\94\ae\03\01n\02l\01\b9\ef\93\80\08x\01\00\01 N\00\00\00\00\00\00"
+```
- ### Step 10: We can then submit the proposal:
+### Step 10: We can then submit the proposal:
-```
+```bash
dfx canister call basic_dao submit_proposal '(record { canister_id = principal "rrkah-fqaaa-aaaaa-aaaaq-cai";
method = "update_system_params":text;
message = blob "DIDL\03l\01\f2\c7\94\ae\03\01n\02l\01\b9\ef\93\80\08x\01\00\01 N\00\00\00\00\00\00"; })'
@@ -183,63 +181,63 @@ message = blob "DIDL\03l\01\f2\c7\94\ae\03\01n\02l\01\b9\ef\93\80\08x\01\00\01 N
Note the output proposal ID:
-```
+```bash
(variant { Ok = 0 : nat64 })
```
- ### Step 11: Confirm the proposal was created:
+### Step 11: Confirm the proposal was created:
-```
+```bash
dfx canister call basic_dao get_proposal '(0:nat64)'
```
You should see `state = variant { Open };` in the output.
- ### Step 12: Vote on the proposal:
+### Step 12: Vote on the proposal:
-```
+```bash
dfx canister call basic_dao vote '(record { proposal_id = 0:nat64; vote = variant { Yes };})'
```
You should see the following output:
-```
+```bash
(variant { Ok = variant { Open } })
```
Because we voted as Bob, and Bob does not have enough voting power to pass proposals, the proposal remains Open. To get the proposal accepted, we can vote with Alice:
-```
+```bash
dfx identity use Alice; dfx canister call basic_dao vote '(record { proposal_id = 0:nat64; vote = variant { Yes };})';
```
You should see the following output:
-```
+```bash
(variant { Ok = variant { Accepted } })
```
Query the proposal again:
-```
+```bash
dfx canister call basic_dao get_proposal '(0:nat64)'
```
And see that the state is `Succeeded`:
-```
+```bash
state = variant { Succeeded };
```
Query the system params again and see that transfer_fee has been updated:
-```
+```bash
dfx canister call basic_dao get_system_params '()'
```
Output:
-```
+```bash
(
record {
transfer_fee = record { amount_e8s = 20_000 : nat64 };
@@ -253,3 +251,11 @@ Output:
- [ic-cdk](https://docs.rs/ic-cdk/latest/ic_cdk/)
- [ic-cdk-macros](https://docs.rs/ic-cdk-macros)
- [JavaScript API reference](https://erxue-5aaaa-aaaab-qaagq-cai.ic0.app/)
+
+## Security considerations and best practices
+
+If you base your application on this example, we recommend you familiarize yourself with and adhere to the [security best practices](https://internetcomputer.org/docs/current/references/security/) for developing on the Internet Computer. This example may not implement all the best practices.
+
+For example, the following aspects are particularly relevant for this app:
+* [Use a decentralized governance system like SNS to make a canister have a decentralized controller](https://internetcomputer.org/docs/current/references/security/rust-canister-development-security-best-practices#use-a-decentralized-governance-system-like-sns-to-make-a-canister-have-a-decentralized-controller), since this is a DAO's use case.
+* [Certify query responses if they are relevant for security](https://internetcomputer.org/docs/current/references/security/general-security-best-practices#certify-query-responses-if-they-are-relevant-for-security), since e.g. account_balance and list_accounts are query calls that a client may want to issue as update call.
diff --git a/rust/canister-info/README.md b/rust/canister-info/README.md
index 6448376ec..183429b8c 100644
--- a/rust/canister-info/README.md
+++ b/rust/canister-info/README.md
@@ -1,4 +1,4 @@
-# canister_info
+# Canister info
The purpose of this dapp is to give developers a small (backend) dapp that uses the IC's `canister_info` management call to retrieve information about canisters including canister history.
@@ -6,7 +6,7 @@ You can find a detailed description of its methods in the form of doc comments i
Please also refer to the [Interface Specification](https://internetcomputer.org/docs/current/references/ic-interface-spec#ic-canister-info) for details about the `canister_info` management call.
-## Security considerations and security best practices
+## Security considerations and best practices
If you base your application on this example, we recommend you familiarize yourself with and adhere to the [security best practices](https://internetcomputer.org/docs/current/developer-docs/security/) for developing on the Internet Computer. This example may not implement all the best practices.
diff --git a/rust/composite_query/README.md b/rust/composite_query/README.md
index 02bc004fa..b1c5faa76 100644
--- a/rust/composite_query/README.md
+++ b/rust/composite_query/README.md
@@ -1,8 +1,10 @@
-# Installing
+# Composite queries
+
+## Building the example
We first need to build the data partition backend canister.
-```
+```bash
cd rust/composite_query/src
dfx start
dfx canister create kv_frontend
@@ -10,37 +12,39 @@ dfx canister create kv_frontend
During compilation of the fronted canister, the canister's wasm code will be inlined in the frontend canister's wasm code.
-```
+```bash
dfx build kv_frontend
dfx canister install kv_frontend
```
-# Using the canister
+## Using the canister
Now we add some key value pairs to via the frontend canister.
-```
-$ dfx canister call kv_frontend put '(1:nat, 1337:nat)'
+```bash
+dfx canister call kv_frontend put '(1:nat, 1337:nat)'
(null)
-$ dfx canister call kv_frontend put '(1:nat, 42:nat)'
+dfx canister call kv_frontend put '(1:nat, 42:nat)'
(opt (1_337 : nat))
```
Note that the first call to `put` is slow, since the data partitions have to be created first.
-```
-$ dfx canister call kv_frontend get '(1:nat)'
+```bash
+dfx canister call kv_frontend get '(1:nat)'
(opt (42 : nat))
```
-We can also query it via a (duplicate) method doing update calls
-```
-$ dfx canister call kv_frontend get_update '(1:nat)'
+We can also query it via a (duplicate) method doing update calls:
+
+```bash
+dfx canister call kv_frontend get_update '(1:nat)'
(opt (1_337 : nat))
```
It's also possible to do *two* query calls, first into the frontend and then into the data partition:
-```
+
+```bash
$ dfx canister call kv_frontend lookup '(1: nat)'
(1 : nat, "dmalx-m4aaa-aaaaa-qaanq-cai")
$ dfx canister call dmalx-m4aaa-aaaaa-qaanq-cai get '(1: nat)' --query
diff --git a/rust/counter/README.md b/rust/counter/README.md
index 86c4e3969..0d79e220b 100644
--- a/rust/counter/README.md
+++ b/rust/counter/README.md
@@ -1,8 +1,6 @@
# Counter
-## Rust variant
-
-### Prerequisites
+## Prerequisites
This example requires an installation of:
- [x] Install the [IC SDK](https://internetcomputer.org/docs/current/developer-docs/setup/install/).
@@ -10,51 +8,51 @@ 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 replica with the command:
-```
+```bash
cd examples/rust/counter
dfx start --background
```
- ### Step 2: Test the canister:
+### Step 2: Test the canister:
-```
+```bash
cargo test
```
- ### Step 3: Deploy the canister:
+### Step 3: Deploy the canister:
-```
+```bash
dfx deploy
```
- ### Step 4: Set the value of the counter:
+### Step 4: Set the value of the counter:
-```
+```bash
dfx canister call counter set '(7)'
```
- ### Step 5: Increment the value of the counter:
+### Step 5: Increment the value of the counter:
-```
+```bash
dfx canister call counter inc
```
- ### Step 6: Get the value of the counter:
+### Step 6: Get the value of the counter:
-```
+```bash
dfx canister call counter get
```
The following output should be returned:
-```
+```bash
(8 : nat)
```
-## Security considerations and security best practices
+## Security considerations and best practices
If you base your application on this example, we recommend you familiarize yourself with and adhere to the [security best practices](https://internetcomputer.org/docs/current/references/security/) for developing on the Internet Computer. This example may not implement all the best practices.
diff --git a/rust/dip721-nft-container/README.md b/rust/dip721-nft-container/README.md
index 6ebc03822..3dad7662e 100644
--- a/rust/dip721-nft-container/README.md
+++ b/rust/dip721-nft-container/README.md
@@ -1,4 +1,4 @@
-# DIP721 NFT container
+# DIP721 NFT
This example demonstrates implementing an NFT canister. NFTs (non-fungible tokens) are unique tokens with arbitrary
metadata, usually an image of some kind, to form the digital equivalent of trading cards. There are a few different
@@ -165,7 +165,7 @@ Minting is restricted to anyone authorized with the `custodians` parameter or th
This Rust example comes with a demo script, `demo.sh`, which runs through an example workflow with minting and trading an NFT between a few users. This is primarily designed to be read rather than run so that you can use it to see how basic NFT operations are done. For a more in-depth explanation, read the [standard][DIP721].
-## Security considerations and security best practices
+## Security considerations and best practices
If you base your application on this example, we recommend you familiarize yourself with and adhere to the [security best practices](https://internetcomputer.org/docs/current/references/security/) for developing on the Internet Computer. This example may not implement all the best practices.
@@ -175,6 +175,6 @@ For example, the following aspects are particularly relevant for this app:
* [Use a decentralized governance system like SNS to make a canister have a decentralized controller](https://internetcomputer.org/docs/current/references/security/rust-canister-development-security-best-practices#use-a-decentralized-governance-system-like-sns-to-make-a-canister-have-a-decentralized-controller), since decentralizing control is a fundamental aspect when dealing with NFTs.
## Resources
-[Rust]: https://rustup.rs
-[DIP721]: https://github.com/Psychedelic/DIP721
-[mint]: https://github.com/dfinity/experimental-minting-tool
\ No newline at end of file
+- [Rust](https://rustup.rs).
+- [DIP721](https://github.com/Psychedelic/DIP721).
+- [mint](https://github.com/dfinity/experimental-minting-tool).
\ No newline at end of file
diff --git a/rust/encrypted-notes-dapp-vetkd/README.md b/rust/encrypted-notes-dapp-vetkd/README.md
index 33ee599a7..bf41f3b5d 100644
--- a/rust/encrypted-notes-dapp-vetkd/README.md
+++ b/rust/encrypted-notes-dapp-vetkd/README.md
@@ -1,3 +1,3 @@
-# Encrypted notes adapted for using vetKD
+# Encrypted notes: vetKD
See the respective [motoko/encrypted-notes-dapp-vetkd](../../motoko/encrypted-notes-dapp-vetkd/) example, which supports both Rust and Motoko via environment variables.
\ No newline at end of file
diff --git a/rust/encrypted-notes-dapp/README.md b/rust/encrypted-notes-dapp/README.md
index 11ba45014..0fd854fd9 100644
--- a/rust/encrypted-notes-dapp/README.md
+++ b/rust/encrypted-notes-dapp/README.md
@@ -113,26 +113,13 @@ Follow the steps below to deploy this sample project.
### Step 1. Navigate inside of the project's folder:
-```
-cd examples/motoko/encrypted-notes-dapp
-```
-
-or
-
-```
+```bash
cd examples/rust/encrypted-notes-dapp
```
### Step 2: Set an environmental variable reflecting which backend canister you'll be using:
-For Motoko deployment run:
-```
-export BUILD_ENV=motoko
-```
-
-For Rust deployment run:
-
-```
+```bash
export BUILD_ENV=rust
```
@@ -141,20 +128,20 @@ export BUILD_ENV=rust
### 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.**
+**This option does not yet work on Apple M1; the combination of dfx and Docker do not currently support the required architecture.**
- #### Step 1: Install and start Docker by following the instructions.
-- #### Step 2: For Motoko build/deployment set environmental variable:
+- #### Step 2: For Rust build/deployment set environmental variable:
-```
-export BUILD_ENV=motoko
+```bash
+export BUILD_ENV=rust
```
- #### Step 3: Run the following Bash script that builds a Docker image, compiles the canister, and deploys this dapp (all inside the Docker instance).
Execution can take a few minutes:
-```
+```bash
sh ./deploy_locally.sh
```
@@ -169,27 +156,27 @@ sh ./deploy_locally.sh
- Run `docker rm -f `.
### Option 2: Manual deployment
-- #### Step 1: For Motoko deployment set environmental variable:
+- #### Step 1: For Rust deployment set environmental variable:
-```
-export BUILD_ENV=motoko
+```bash
+export BUILD_ENV=rust
```
-- #### Step 2: To generate $BUILD_ENV-specific files (i.e., Motoko or Rust) run:
+- #### Step 2: To generate $BUILD_ENV-specific files:
-```
+```bash
sh ./pre_deploy.sh
```
- #### Step 3: Install `npm` packages from the project root:
-```
+```bash
npm install
```
- #### Step 4: Start `dfx`:
-```
+```bash
dfx start
```
@@ -249,7 +236,7 @@ Visit the URL from above in a web browser. To run the frontend with hot-reloadin
- #### Step 1: Create the canisters:
-```
+```bash
dfx canister --network ic create "encrypted_notes_${BUILD_ENV}"
dfx canister --network ic create www
```
@@ -259,7 +246,7 @@ dfx canister --network ic create www
- #### Step 2: Build the canisters:
-```
+```bash
dfx build "encrypted_notes_${BUILD_ENV}" --network ic
dfx build www --network ic
```
@@ -269,12 +256,12 @@ dfx build www --network ic
**In the commands below, --mode could also be reinstall to reset the stable memory.**
-```
+```bash
dfx canister --network ic install "encrypted_notes_${BUILD_ENV}" --mode=upgrade
dfx canister --network ic install www --mode=upgrade
```
-## Security considerations and security best practices
+## Security considerations and best practices
If you base your application on this example, we recommend you familiarize yourself with and adhere to the [security best practices](https://internetcomputer.org/docs/current/references/security/) for developing on the Internet Computer. This example may not implement all the best practices, see also the [disclaimer](#disclaimer-please-read-carefully) above.
@@ -295,7 +282,7 @@ For example, the following aspects are particularly relevant for this app:
Fig. 2. Basic single-device scenario for a user.
-1. Open the main page of the `Encrypted Notes` dapp. You will see a _login_ button.
+- #### Step 1: Open the main page of the `Encrypted Notes` dapp. You will see a _login_ button.
1. If deployed locally, visit the following link: http://localhost:8000?canisterId=rkp4c-7iaaa-aaaaa-aaaca-cai
2. If deployed to the mainnet IC, visit the corresponding canister URL.
@@ -304,13 +291,16 @@ Fig. 2. Basic single-device scenario for a user.
_Note_: see [Troubleshooting](#troubleshooting) in case of problems.
-2. Click the "Login" button. You will be redirected to the _Internet Identity_ canister (see Fig. 2(b)).
+- #### Step 2: Click the "Login" button. You will be redirected to the _Internet Identity_ canister (see Fig. 2(b)).
1. If you already have an `anchor`, you may continue with it. Click "Authenticate", then verify your identity and finally click "Proceed", see Fig. 2(c).
2. If you do not have an anchor yet, you should [create one](https://internetcomputer.org/how-it-works/web-authentication-identity/). Once an `anchor` is created, please follow 2.1.
-3. Once logged in for the first time, your notes list should be empty. At this moment, your _Local Storage_ should be populated with additional variables (see Fig. 2(d)): **ic-identity**, **ic-delegation**. These variables are used for storing/retrieving notes from the backend canister. In addition, another two variables are generated in the _IndexedDB_: **PrivateKey**, **PublicKey**. These two variable are used for encrypting/decrypting the shared secret key.
-4. Create/edit/delete notes and observe changes in the resulting notes list (see Fig. 2(e)).
+- #### Step 3: Once logged in for the first time, your notes list should be empty.
+
+At this moment, your _Local Storage_ should be populated with additional variables (see Fig. 2(d)): **ic-identity**, **ic-delegation**. These variables are used for storing/retrieving notes from the backend canister. In addition, another two variables are generated in the _IndexedDB_: **PrivateKey**, **PublicKey**. These two variable are used for encrypting/decrypting the shared secret key.
+
+- #### Step 4: Create/edit/delete notes and observe changes in the resulting notes list (see Fig. 2(e)).
### Scenario II: user is accessing notes from multiple devices
@@ -352,35 +342,6 @@ Fig. 4. Scenario for a user adding/removing devices.
## Unit testing
-This project also demonstrates how one can write unit tests for Motoko and Rust canisters.
-
-### Motoko Unit Tests
-
-The unit tests are implemented in `src/encrypted_notes_motoko/test/test.mo` using the [Motoko Matchers](https://kritzcreek.github.io/motoko-matchers/) library.
-
-The easiest way to run all tests involves the following steps:
-
-1. Follow the above instructions for Deployment via Docker with `BUILD_ENV=motoko`.
-2. Open a new console, type `docker ps`, and copy the _``_ of the `encrypted_notes` image.
-3. Run: `docker exec `_``_` sh src/encrypted_notes_motoko/test/run_tests.sh`
-4. Observer `All tests passed.` at the end of the output.
-
-Alternatively, one can also run unit tests after a local deployment via:
-```sh
-src/encrypted_notes_motoko/test/run_tests.sh
-```
-However, this requires installing [`wasmtime`](https://wasmtime.dev/) and [`motoko-matchers`](https://github.com/kritzcreek/motoko-matchers):
-
-```sh
-git clone https://github.com/kritzcreek/motoko-matchers $(dfx cache show)/motoko-matchers
-chmod +x src/encrypted_notes_motoko/test/run_tests.sh
-src/encrypted_notes_motoko/test/run_tests.sh
-```
-
-Observer `All tests passed.` at the end of the output.
-
-### Rust Unit Tests
-
The unit tests are implemented in `src/encrypted_notes_rust/src/lib.rs` at the bottom.
The easiest way to run all tests involves the following steps:
diff --git a/rust/performance_counters/README.md b/rust/performance_counters/README.md
index 9266b2013..cbac54cc8 100644
--- a/rust/performance_counters/README.md
+++ b/rust/performance_counters/README.md
@@ -6,7 +6,7 @@ The canister can query one of the "performance counters", which is a determinist
```Candid
ic0.performance_counter : (counter_type : i32) -> i64
-````
+```
The argument `type` decides which performance counter to return:
@@ -29,9 +29,7 @@ The argument `type` decides which performance counter to return:
(ignoring WebAssembly instructions executed within any further downstream calls
of `composite_query_helper`).
-In the future, the IC might expose more performance counters.
-
-## Tutorial
+In the future, ICP might expose more performance counters.
## Prerequisites
@@ -149,7 +147,7 @@ Note the same performance counters behavior for composite queries.
1. Have a look at the locally running dashboard. The URL is at the end of the `dfx start` command: `Dashboard: http://localhost/...`
2. Check out the Candid user interface for `performance_counters` canister. The URL is at the end of the `dfx deploy` command: `performance_counters: http://127.0.0.1/...`
-### Canister Interface
+### Canister interface
The `performance_counters` canisters provide the following interface:
@@ -160,6 +158,6 @@ The `performance_counters` canisters provide the following interface:
Performance counters is a great tool to optimize canister performance, both for update calls and queries.
-## Security considerations and security best practices
+## Security considerations and best practices
If you base your application on this example, we recommend you familiarize yourself with and adhere to the [security best practices](https://internetcomputer.org/docs/current/references/security/) for developing on the Internet Computer. This example may not implement all the best practices.
diff --git a/rust/periodic_tasks/README.md b/rust/periodic_tasks/README.md
index 34710ab81..c38d88566 100644
--- a/rust/periodic_tasks/README.md
+++ b/rust/periodic_tasks/README.md
@@ -13,8 +13,6 @@ This example demonstrates different ways of scheduling periodic tasks on the Int
The example consist of two canisters named `heartbeat` and `timer`, both implementing the same functionality: schedule a periodic task to increase a counter.
-## Tutorial
-
## Prerequisites
This example requires an installation of:
@@ -237,7 +235,7 @@ For such an isolation of execution and scheduling contexts, timers library uses
2. Check out `heartbeat` and `timer` canisters Candid user interface. The URLs are et the end of the `dfx deploy` command: `heartbeat: http://127.0.0.1/...`
3. Find which interval makes even the costs of running periodic tasks in the `timer` and `heartbeat` canisters: `dfx deploy heartbeat --argument 5 && dfx deploy timer --argument 5`
-### Canister Interface
+### Canister interface
The `heartbeat` and `timer` canisters provide the following interface:
@@ -260,6 +258,6 @@ For the code composability, execution context isolation and cost efficiency, can
As shown in `Example 2`, there might be still very specific use cases for the heartbeats. Those should be considered case by case, with composability and isolation issues in mind.
-## Security considerations and security best practices
+## Security considerations and best practices
If you base your application on this example, we recommend you familiarize yourself with and adhere to the [security best practices](https://internetcomputer.org/docs/current/references/security/) for developing on the Internet Computer. This example may not implement all the best practices.
diff --git a/rust/pub-sub/README.md b/rust/pub-sub/README.md
index ae2cc293f..c65dda2e8 100644
--- a/rust/pub-sub/README.md
+++ b/rust/pub-sub/README.md
@@ -1,7 +1,4 @@
-# Design Pattern: Pub/Sub
-
-
-[](https://github.com/dfinity/examples/actions?query=workflow%3Amotoko-pub-sub-example)
+# PubSub
## Overview
This sample project demonstrates how functions may be passed as arguments of inter-canister calls to be used as callbacks.
@@ -17,48 +14,48 @@ 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:
-```
+```bash
cd examples/rust/pub-sub
dfx start --background
```
### Step 2: Deploy the canister:
-```
+```bash
dfx deploy
```
### Step 3: Get the publisher ID
-```
+```bash
dfx canister id publisher
```
### Step 4: Subscribe to the "Apples" topic:
-```
+```bash
dfx canister call subscriber setup_subscribe '(principal "", "Apples")'
```
### Step 5: Publish to the "Apples" topic:
-```
+```bash
dfx canister call publisher publish '(record { "topic" = "Apples"; "value" = 2 })'
```
### Step 6: Receive your subscription:
-```
+```bash
dfx canister call subscriber get_count
```
The output should resemble the following:
-```
+```bash
(2 : nat64)
```
-## Security considerations and security best practices
+## Security considerations and best practices
If you base your application on this example, we recommend you familiarize yourself with and adhere to the [security best practices](https://internetcomputer.org/docs/current/references/security/) for developing on the Internet Computer. This example may not implement all the best practices.
diff --git a/rust/qrcode/README.md b/rust/qrcode/README.md
index d3a9a5bec..4cf2924af 100644
--- a/rust/qrcode/README.md
+++ b/rust/qrcode/README.md
@@ -1,4 +1,4 @@
-# QR code generator on the Internet Computer
+# QR code generator
## Overview
@@ -6,7 +6,7 @@ This example shows that an Internet Computer dapp can perform a long-running com
This is possible due to a unique feature called Deterministic Time Slicing (DTS), which automatically divides long computations into smaller slices executed across multiple blocks.
Developers can write long-running code as usual and don't require anything special to take advantage of DTS, as demonstrated in this example.
-You try the live version of the dapp running on the Internet Computer mainnet here: [https://khpe2-4qaaa-aaaao-a2fnq-cai.icp0.io/](https://khpe2-4qaaa-aaaao-a2fnq-cai.icp0.io/).
+You try the live version of the dapp running on the mainnet here: [https://khpe2-4qaaa-aaaao-a2fnq-cai.icp0.io/](https://khpe2-4qaaa-aaaao-a2fnq-cai.icp0.io/).
## Prerequisites
This example requires an installation of:
@@ -22,21 +22,22 @@ This example requires an installation of:
Start a local replica of the Internet Computer by running:
-```
+```bash
dfx start --background
```
You can omit the `--background` argument if you want to see log messages of the dapp.
-Now you can build and deploy the dapp with a single command
-```
+Now you can build and deploy the dapp with a single command:
+
+```bash
dfx deploy
```
If you see any error, it might be worthwhile to consult the [developer forum](https://forum.dfinity.org/).
In case of successful deployment, you will see an output with local URLs:
-```
+```bash
Deployed canisters.
URLs:
Frontend canister via browser
diff --git a/rust/send_http_get/README.md b/rust/send_http_get/README.md
index 2c16f1c73..e3f6a1a8b 100644
--- a/rust/send_http_get/README.md
+++ b/rust/send_http_get/README.md
@@ -1,4 +1,4 @@
-# send_http_get
+# 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.
diff --git a/rust/send_http_post/README.md b/rust/send_http_post/README.md
index e475f9a81..4396d1c2b 100644
--- a/rust/send_http_post/README.md
+++ b/rust/send_http_post/README.md
@@ -1,4 +1,4 @@
-# send_http_post
+# 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.
diff --git a/rust/threshold-ecdsa/README.md b/rust/threshold-ecdsa/README.md
index df192fa98..2472c10ea 100644
--- a/rust/threshold-ecdsa/README.md
+++ b/rust/threshold-ecdsa/README.md
@@ -1,4 +1,4 @@
-# Threshold ECDSA signing code walkthrough
+# Threshold ECDSA
## Overview
@@ -20,7 +20,7 @@ This walkthrough focuses on the version of the sample canister code written in [
## 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.
-## Step 1: Getting started
+## 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.
@@ -50,18 +50,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.
-## Step 2: Deploying the canister on IC mainnet
+### Deploying the canister on the mainnet
-To deploy this canister the IC mainnet, one needs to do two things:
+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/setup/cycles). You can get free cycles from the [cycles faucet](https://internetcomputer.org/docs/current/developer-docs/setup/cycles/cycles-faucet.md).
-### 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_rust/main.mo` file of the sample code. Before deploying to mainnet, one should modify the code to use the right name of the `key_id`.
@@ -97,9 +97,9 @@ let { signature } = await ic.sign_with_ecdsa({
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 mainnet via IC SDK
+#### Deploy to the mainnet via IC SDK
-To [deploy via mainnet](https://internetcomputer.org/docs/current/developer-docs/setup/deploy-mainnet.md), run the following commands:
+To [deploy via the mainnet](https://internetcomputer.org/docs/current/developer-docs/setup/deploy-mainnet.md), run the following commands:
```bash
npm install
@@ -116,7 +116,7 @@ URLs:
In example above, `ecdsa_example_motoko` has the URL https://a3gq9-oaaaa-aaaab-qaa4q-cai.raw.icp0.io/?id=736w4-cyaaa-aaaal-qb3wq-cai and serves up the Candid web UI for this particular canister deployed on mainnet.
-## Step 3: Obtaining public keys
+## Obtaining public keys
### Using the Candid web UI
@@ -181,7 +181,7 @@ For obtaining the canister's root public key, the derivation path in the API can
- For obtaining a canister's public key below its root key in the BIP-32 key derivation hierarchy, a derivation path needs to be specified. As explained in the general documentation, each element in the array of the derivation path is either a 32-bit integer encoded as 4 bytes in big endian or a byte array of arbitrary length. The element is used to derive the key in the corresponding level at the derivation hierarchy.
- In the example code above, we use the bytes extracted from the `msg.caller` principal in the `derivation_path`, so that different callers of `public_key()` method of our canister will be able to get their own public keys.
-## Step 4: Signing
+## Signing
Computing threshold ECDSA signatures is the core functionality of this feature. **Canisters do not hold ECDSA keys themselves**, but keys are derived from a master key held by dedicated subnets. A canister can request the computation of a signature through the management canister API. The request is then routed to a subnet holding the specified key and the subnet computes the requested signature using threshold cryptography. Thereby, it derives the canister root key or a key obtained through further derivation, as part of the signature protocol, from a shared secret and the requesting canister's principal identifier. Thus, a canister can only request signatures to be created for their canister root key or a key derived from it. This means, canisters "control" their private ECDSA keys in that they decide when signatures are to be created with them, but don't hold a private key themselves.
@@ -203,7 +203,7 @@ Computing threshold ECDSA signatures is the core functionality of this feature.
};
```
-## Step 5: Signature verification
+## Signature verification
For completeness of the example, we show that the created signatures can be verified with the public key corresponding to the same canister and derivation path.
diff --git a/rust/tokens_transfer/README.md b/rust/tokens_transfer/README.md
index aaae17b65..8b90ad2ec 100644
--- a/rust/tokens_transfer/README.md
+++ b/rust/tokens_transfer/README.md
@@ -1,4 +1,4 @@
-# Ledger transfer
+# Token transfer
## Overview
ICP transfer is a canister that can transfer ICP from its account to other accounts. It is an example of a canister that uses the ledger canister. Sample code is available in [Motoko](https://github.com/dfinity/examples/tree/master/ rust/ledger-transfer) and [Rust](https://github.com/dfinity/examples/tree/master/rust/tokens_transfer).
@@ -16,7 +16,7 @@ This example requires an installation of:
### Step 1: Create a new `dfx` project and navigate into the project's directory.
-```
+```bash
dfx new --type=rust ledger_transfer
cd ledger_transfer
```
@@ -31,9 +31,9 @@ The URL for the ledger .did file is `https://raw.githubusercontent.com/dfinity/i
### 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:
+Replace its contents with this but adapt the URLs to be the ones you determined in step 2:
-```
+```json
{
"canisters": {
"ledger": {
@@ -78,15 +78,15 @@ Replace its contents with this (but adapt the URLs to be the ones you determined
}
```
-### Step 5: Start a local replica:
+### Step 4: Start a local replica:
-```
+```bash
dfx start --background
```
-### Step 6: Create a new identity that will work as a minting account:
+### Step 5: Create a new identity that will work as a minting account:
-```
+```bash
dfx identity new minter
dfx identity use minter
export MINT_ACC=$(dfx ledger account-id)
@@ -94,39 +94,39 @@ export MINT_ACC=$(dfx ledger account-id)
Transfers from the minting account will create Mint transactions. Transfers to the minting account will create Burn transactions.
-### Step 7: Switch back to your default identity and record its ledger account identifier:
+### Step 6: Switch back to your default identity and record its ledger account identifier:
-```
+```bash
dfx identity use default
export LEDGER_ACC=$(dfx ledger account-id)
```
-### Step 8: Deploy the ledger canister to your network:
+### Step 7: Deploy the ledger canister to your network:
-```
+```bash
dfx deploy ledger --argument "(variant {Init = record { token_name = \"NAME\"; token_symbol = \"SYMB\"; transfer_fee = 1000000; metadata = vec {}; minting_account = record {owner = principal \"$(dfx --identity minter identity get-principal)\";}; initial_balances = vec {}; archive_options = record {num_blocks_to_archive = 1000000; trigger_threshold = 1000000; controller_id = principal \"$(dfx identity get-principal)\"}; }})"
```
If you want to setup the ledger in a way that matches the production deployment, you should deploy it with archiving enabled. In this setup, the ledger canister dynamically creates new canisters to store old blocks. We recommend using this setup if you are planning to exercise the interface for fetching blocks.
-### Step 9: Obtain the principal of the identity you use for development.
+### Step 8: Obtain the principal of the identity you use for development.
This principal will be the controller of archive canisters.
-```
+```bash
dfx identity use default
export ARCHIVE_CONTROLLER=$(dfx identity get-principal)
```
-### Step 10: Deploy the ledger canister with archiving options:
+### Step 9: Deploy the ledger canister with archiving options:
-```
+```bash
dfx deploy ledger --argument '(record {minting_account = "'${MINT_ACC}'"; initial_values = vec { record { "'${LEDGER_ACC}'"; record { e8s=100_000_000_000 } }; }; send_whitelist = vec {}; archive_options = opt record { trigger_threshold = 2000; num_blocks_to_archive = 1000; controller_id = principal "'${ARCHIVE_CONTROLLER}'" }})'
```
If successful, the output should be:
-```
+```bash
Deployed canisters.
URLs:
Frontend canister via browser
@@ -136,33 +136,33 @@ URLs:
ledger_transfer_backend: http://127.0.0.1:4943/?canisterId=bd3sg-teaaa-aaaaa-qaaba-cai&id=be2us-64aaa-aaaaa-qaabq-cai
```
-### Step 11: Verify that the ledger canister is healthy and working as expected by using the command:
+### Step 10: Verify that the ledger canister is healthy and working as expected by using the command:
-```
+```bash
dfx canister call ledger account_balance '(record { account = '$(python3 -c 'print("vec{" + ";".join([str(b) for b in bytes.fromhex("'$LEDGER_ACC'")]) + "}")')' })'
```
The output should be:
-```
+```bash
(record { e8s = 100_000_000_000 : nat64 })
```
-### Step 10: In a separate working directory, clone the Github repo containing the `ledger_transfer` project's files:
+### Step 11: In a separate working directory, clone the Github repo containing the `ledger_transfer` project's files:
-```
+```bash
git clone https://github.com/dfinity/examples.git
```
-### Step 11: Copy the files for the `ledger-transfer` canister into your `ledger_transfer` workspace:
+### Step 12: Copy the files for the `ledger-transfer` canister into your `ledger_transfer` workspace:
-```
+```bash
cp -r ./examples/rust/ledger-transfer/src/* ./ledger_transfer/src
```
-### Step 12: Edit your `dfx.json` file to include the following information within the 'canisters' section:
+### Step 13: Edit your `dfx.json` file to include the following information within the 'canisters' section:
-```
+```json
...
"canisters": {
"ledger_transfer": {
@@ -182,15 +182,15 @@ cp -r ./examples/rust/ledger-transfer/src/* ./ledger_transfer/src
```
-### Step 13: Deploy this new canister:
+### Step 14: Deploy this new canister:
-```
+```bash
dfx deploy
```
Your output should resemble the following:
-```
+```bash
Deployed canisters.
URLs:
Frontend canister via browser
@@ -201,48 +201,48 @@ URLs:
ledger_transfer_backend: http://127.0.0.1:4943/?canisterId=bd3sg-teaaa-aaaaa-qaaba-cai&id=be2us-64aaa-aaaaa-qaabq-cai
```
-### Step 14: Determine out the address of your canister:
+### Step 15: Determine out the address of your canister:
-```
+```bash
dfx canister call ledger_transfer canisterAccount '()'
```
Your output should resemble the following:
-```
+```bash
(
blob "\94\b9\bc]\ab(\ad\b93\8dE\19#\914\b6\a0\0e\dfam5\e4\e5\80\b5\01\9a~\e1_{",
)
```
-### Step 15: Transfer funds to your canister:
+### Step 16: Transfer funds to your canister:
-```
+```bash
dfx canister call ledger transfer '(record { to = blob "\08.\cf.?dz\c6\00\f4?8\a6\83B\fb\a5\b8\e6\8b\08_\02Y+w\f3\98\08\a8\d2\b5"; memo = 1; amount = record { e8s = 2_00_000_000 }; fee = record { e8s = 10_000 }; })'
```
If successful, the output should be:
-```
+```bash
(variant { Ok = 1 : nat64 })
```
-### Step 16: Post a message as a new user:
+### Step 17: Post a message as a new user:
-```
+```bash
dfx identity new --disable-encryption ALICE
dfx identity use ALICE
dfx canister call ledger_transfer post "(\"Test message\")"
```
-### Step 17: Distribute rewards to users:
+### Step 18: Distribute rewards to users:
-```
+```bash
dfx identity use default
dfx canister call ledger_transfer distributeRewards '()'
```
-## Security considerations and security best practices
+## Security considerations and best practices
If you base your application on this example, we recommend you familiarize yourself with and adhere to the [security best practices](https://internetcomputer.org/docs/current/references/security/) for developing on the Internet Computer. This example may not implement all the best practices.
diff --git a/rust/vetkd/README.md b/rust/vetkd/README.md
index 9d7ff562e..9c8043dba 100644
--- a/rust/vetkd/README.md
+++ b/rust/vetkd/README.md
@@ -1,4 +1,4 @@
-# vetKD System API Preview
+# vetKD API
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**.
@@ -16,51 +16,51 @@ 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 by means of 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
-- [ ] Install the [IC SDK](https://internetcomputer.org/docs/current/developer-docs/setup/install/).
-- [ ] Install [Node.js](https://nodejs.org/en/download/).
-- [ ] Install [Rust](https://www.rust-lang.org/tools/install), and add Wasm as a target (`rustup target add wasm32-unknown-unknown`).
+- [x] Install the [IC SDK](https://internetcomputer.org/docs/current/developer-docs/setup/install/).
+- [x] Install [Node.js](https://nodejs.org/en/download/).
+- [x] Install [Rust](https://www.rust-lang.org/tools/install), and add Wasm as a target (`rustup target add wasm32-unknown-unknown`).
## Running Locally
-1. Start a local internet computer.
+- #### Step 1: Start a local internet computer.
- ```sh
- dfx start
- ```
+```sh
+dfx start
+```
-1. Open a new terminal window.
+- #### Step 2: Open a new terminal window.
-1. Ensure the Canister SDK (dfx) uses the canister IDs that are hard-coded in the Rust source code:
+- #### Step 3: Ensure the IC SDK (dfx) uses the canister IDs that are hard-coded in the Rust source code:
- ```sh
- dfx canister create system_api --specified-id s55qq-oqaaa-aaaaa-aaakq-cai
- ```
+```sh
+dfx canister create system_api --specified-id s55qq-oqaaa-aaaaa-aaakq-cai
+```
- Without this, the Canister SDK (dfx) may use different canister IDs for the `system_api` and `app_backend` canisters in your local environment.
+Without this, the IC SDK (dfx) may use different canister IDs for the `system_api` and `app_backend` canisters in your local environment.
-1. Ensure that the required node modules are available in your project directory, if needed, by running the following command:
+- #### Step 4: Ensure that the required node modules are available in your project directory, if needed, by running the following command:
- ```sh
- npm install
- ```
+```sh
+npm install
+```
-1. Register, build and deploy the project:
+- #### Step 5:. Register, build and deploy the project:
- ```sh
- dfx deploy
- ```
+```sh
+dfx deploy
+```
- This command should finish successfully with output similar to the following one:
+This command should finish successfully with output similar to the following one:
- ```sh
- Deployed canisters.
- URLs:
- Frontend canister via browser
- app_frontend_js: http://127.0.0.1:4943/?canisterId=by6od-j4aaa-aaaaa-qaadq-cai
- Backend canister via Candid interface:
- app_backend: http://127.0.0.1:4943/?canisterId=avqkn-guaaa-aaaaa-qaaea-cai&id=tcvdh-niaaa-aaaaa-aaaoa-cai
- app_frontend: http://127.0.0.1:4943/?canisterId=avqkn-guaaa-aaaaa-qaaea-cai&id=b77ix-eeaaa-aaaaa-qaada-cai
- system_api: http://127.0.0.1:4943/?canisterId=avqkn-guaaa-aaaaa-qaaea-cai&id=s55qq-oqaaa-aaaaa-aaakq-cai
- ```
+```sh
+Deployed canisters.
+URLs:
+Frontend canister via browser
+ app_frontend_js: http://127.0.0.1:4943/?canisterId=by6od-j4aaa-aaaaa-qaadq-cai
+Backend canister via Candid interface:
+ app_backend: http://127.0.0.1:4943/?canisterId=avqkn-guaaa-aaaaa-qaaea-cai&id=tcvdh-niaaa-aaaaa-aaaoa-cai
+ app_frontend: http://127.0.0.1:4943/?canisterId=avqkn-guaaa-aaaaa-qaaea-cai&id=b77ix-eeaaa-aaaaa-qaada-cai
+ system_api: http://127.0.0.1:4943/?canisterId=avqkn-guaaa-aaaaa-qaaea-cai&id=s55qq-oqaaa-aaaaa-aaakq-cai
+```
-1. Open the printed URL for the `app_frontend_js` in your browser.
+- #### Step 6: Open the printed URL for the `app_frontend_js` in your browser.