Merge pull request #2361 from dfinity/jmongeon-revisions

Dev Docs Accelerator: Revisions Part 1

docs/developer-docs/agents/ic-agent-dfinity.md

@@ -1,17 +1,73 @@
----
-sidebar_position: 4
-sidebar_label: "From a Rust agent"
----
 # Making a call from a Rust agent
 
 ## Overview
-The Rust agent by DFINTY is a simple-to-use library that enables you to build applications and interact with the Internet Computer. It serves as a Rust-based low-level backend for the IC SDK.
 
-The ic-agent is a Rust crate that can connect directly to the Internet Computer through the Internet Computer..
+The Rust agent by DFINTY is a simple library that enables you to build applications and interact with ICP. It serves as a Rust-based low-level backend for the IC SDK.
 
-The agent is designed to be compatible with multiple versions of the replica API, and to expose both low-level APIs for communicating with Internet Computer components like the replica and to provide higher-level APIs for communicating with software applications deployed as canisters.
+The agent is designed to be compatible with multiple versions of the replica API. It exposes both low-level APIs for communicating with ICP components like the replica and provides higher-level APIs for communicating with software applications deployed as canisters.
 
-One example of a project that uses the `ic-agent` is dfx, which you can find [here](https://github.com/dfinity/sdk).
+One example of a project that uses the `ic-agent` is [dfx](https://github.com/dfinity/sdk).
 
-- Rust agent documentation [here](https://docs.rs/ic-agent/latest/ic_agent).
-- Rust agent source code [here](https://github.com/dfinity/agent-rs).
+## Adding the agent as a dependency
+
+To add the `ic-agent` crate as a dependency in your project, use the command:
+
+```
+cargo add ic-agent
+```
+
+## Example
+
+The following is an example of how to use the agent interface to make a call to a canister deployed on the mainnet. The canister being called is the management canister (`aaaaa-aa`), which then creates a placeholder value for a new canister and returns that value. 
+
+```rust
+use ic_agent::{Agent, export::Principal};
+use candid::{Encode, Decode, CandidType, Nat};
+use serde::Deserialize;
+
+#[derive(CandidType)]
+struct Argument {
+  amount: Option<Nat>,
+}
+
+#[derive(CandidType, Deserialize)]
+struct CreateCanisterResult {
+  canister_id: Principal,
+}
+
+async fn create_a_canister() -> Result<Principal, Box<dyn std::error::Error>> {
+  let agent = Agent::builder()
+    .with_url(URL)
+    .with_identity(create_identity())
+    .build()?;
+  // Only do the following call when not contacting the IC main net (e.g. a local emulator).
+  // This is important as the main net public key is static and a rogue network could return
+  // a different key.
+  // If you know the root key ahead of time, you can use `agent.set_root_key(root_key);`.
+  agent.fetch_root_key().await?;
+  let management_canister_id = Principal::from_text("aaaaa-aa")?;
+
+  // Create a call to the management canister to create a new canister ID,
+  // and wait for a result.
+  // The effective canister id must belong to the canister ranges of the subnet at which the canister is created.
+  let effective_canister_id = Principal::from_text("rwlgt-iiaaa-aaaaa-aaaaa-cai").unwrap();
+  let response = agent.update(&management_canister_id, "provisional_create_canister_with_cycles")
+    .with_effective_canister_id(effective_canister_id)
+    .with_arg(Encode!(&Argument { amount: None})?)
+    .call_and_wait()
+    .await?;
+
+  let result = Decode!(response.as_slice(), CreateCanisterResult)?;
+  let canister_id: Principal = result.canister_id;
+  Ok(canister_id)
+}
+
+let canister_id = create_a_canister().await.unwrap();
+eprintln!("{}", canister_id);
+```
+
+## Further reading
+
+- [ic-agent documentation](https://docs.rs/ic-agent/latest/ic_agent).
+- [Rust agent documentation](https://docs.rs/ic-agent/latest/ic_agent/struct.Agent.html).
+- [Rust agent source code](https://github.com/dfinity/agent-rs).

docs/developer-docs/agents/javascript-intro.md

@@ -1,7 +1,4 @@
----
-sidebar_position: 1
-sidebar_label: From a JavaScript agent
----
+
 # Making a call from a JavaScript agent
 
 ## Overview

docs/developer-docs/agents/nodejs.md

@@ -1,7 +1,3 @@
----
-sidebar_position: 2
-sidebar_label: "From Node.js"
----
 
 # Making a call from Node.js
 

docs/developer-docs/backend/candid/candid-howto.md

@@ -6,7 +6,7 @@ As discussed in the [Candid concepts](./candid-concepts.md) page, Candid provide
 
 As a concrete example, let’s assume there is a `counter` canister already deployed on the network with the following Candid interface:
 
-``` candid
+```candid
 service Counter : {
   inc : (step: nat) -> (nat);
 }

docs/developer-docs/backend/motoko/access-control.md

@@ -48,44 +48,54 @@ Open the `src/access_hello_backend/main.mo` file in a text editor and delete the
 
 Copy and paste this code into the file:
 
-```
+```motoko
 // Import base modules
 import AssocList "mo:base/AssocList";
 import Error "mo:base/Error";
 import List "mo:base/List";
 
 shared({ caller = initializer }) actor class() {
 
-    // Establish role-based greetings to display
+    // Establish the role-based greetings to display
     public shared({ caller }) func greet(name : Text) : async Text {
+
+        // If an identity with admin rights calls the method, display this greeting:
         if (has_permission(caller, #assign_role)) {
             return "Hello, " # name # ". You have a role with administrative privileges."
+
+        // If an identity with the authorized user rights calls the method, display this greeting:
         } else if (has_permission(caller, #lowest)) {
             return "Welcome, " # name # ". You have an authorized account. Would you like to play a game?";
+
+        // If the identity is not an admin or authorized user, display this greeting:
         } else {
             return "Greetings, " # name # ". Nice to meet you!";
         }
     };
 
-    // Define custom types
+    // Define the custom types used for each user type
     public type Role = {
         #owner;
         #admin;
         #authorized;
     };
 
+    // Define the custom types for assigning the permissions 
     public type Permission = {
         #assign_role;
         #lowest;
     };
 
+    // Create two stable variables to store the roles associated with each principal
     private stable var roles: AssocList.AssocList<Principal, Role> = List.nil();
     private stable var role_requests: AssocList.AssocList<Principal, Role> = List.nil();
 
+    // Return the caller's principal
     func principal_eq(a: Principal, b: Principal): Bool {
         return a == b;
     };
 
+    // Get the principal's current role
     func get_role(pal: Principal) : ?Role {
         if (pal == initializer) {
             ?#owner;
@@ -163,7 +173,7 @@ Let's take a look at a few key elements of this dapp:
 
 - You might notice that the `greet` function is a variation on the `greet` function you have seen in previous guides. In this dapp, however, the `greet` function uses a message caller to determine the permissions that should be applied and, based on the permissions associated with the caller, which greeting to display.
 
-- The dapp defines two custom types—one for `Roles` and one for `Permissions`.
+- The dapp defines two custom types, one for `Roles` and one for `Permissions`.
 
 - The `assign_roles` function enables the message caller to assign a role to the principal associated with an identity.
 

docs/developer-docs/backend/motoko/at-a-glance.md

@@ -1,10 +1,8 @@
-# 4: Motoko quick start
+# 4: Motoko quickstart
 
 ## Overview
 
-The [1.3: Deploying your first dapp](/docs/tutorials/developer-journey/level-1/1.3-first-dapp.md) developer journey tutorial provides a fast path to deploying a simple default application without stopping to admire the scenery along the way. Individual tutorials in this section walk through specific scenarios, pointing out details about what you’re doing in each step.
-
-If the quick start and tutorials are not quite your style, this at-a-glance cheat sheet summarizes the steps to follow for quick reference.
+This at-a-glance cheat sheet summarizes the steps to follow for quick reference.
 
 ## Prerequisites
 
@@ -34,7 +32,13 @@ Start the Internet Computer for local development or check your connection to th
 
 ## Register, build, and deploy locally or on the mainnet 
 
-For the mainnet, use: `--network ic`.
+To deploy locally, use the command:
+
+```
+dfx deploy
+```
+
+For deploying to the mainnet, use: `--network ic`.
 
 ```
 dfx deploy --network <network>

docs/developer-docs/backend/motoko/calculator.md

@@ -73,7 +73,7 @@ Then, open the `src/calc_backend/calc_main.mo` file in a text editor and delete
 
 Copy and paste this code into the `calc_main.mo` file:
 
-```
+```motoko
 // This single-cell calculator defines one calculator instruction per
 // public entry point (add, sub, mul, div).
 

docs/developer-docs/backend/motoko/candid-ui.md

@@ -11,70 +11,15 @@ Based on the type signature of the actor, Candid also provides a web interface t
 
 ## Using Candid UI
 
-After you have deployed your project in the local canister execution environment using the `dfx deploy` or `dfx canister install` command, you can access the Candid web interface endpoint in a browser. 
+To learn how to use Candid, check out the documentation here:
 
-This web interface, the Candid UI, exposes the service description in a form, enabling you to quickly view and test functions and experiment with entering different data types without writing any front-end code.
+- [Candid UI](../candid/index.md).
 
-To use the Candid web interface to test canister functions, first find the Candid UI canister identifier associated with the current project by running the command:
+- [What is Candid?](../candid/candid-concepts.md).
 
-```
-dfx canister id __Candid_UI
-```
+- [Using Candid](../candid/candid-howto.md).
 
-This command displays the canister identifier for the Candid UI with output similar to the following:
-
-```
-r7inp-6aaaa-aaaaa-aaabq-cai
-```
-
-Copy the Candid UI canister identifier so that it is available in the clipboard. 
-
-If you've stopped the local canister execution environment, restart it locally by running the following command:
-
-```
-dfx start --background
-```
-
-Open a browser and navigate to the address and port number specified in the `dfx.json` configuration file. 
-
-By default, the local canister execution environment binds to the `127.0.0.1:4943` address and port number.
-
-Add the required `canisterId` parameter and the Candid UI canister identifier returned by the `dfx canister id __Candid_UI` command to the URL. 
-
-For example, the full URL should look similar to the following but with the `CANDID-UI-CANISTER-IDENTIFIER` that was returned by the `dfx canister id __Candid_UI` command:
-
-```
-http://127.0.0.1:4943/?canisterId=<CANDID-UI-CANISTER-IDENTIFIER>
-```
-
-For instance, with the example canister identifier for the Candid UI as shown above, this could look as follows:
-
-```
-http://127.0.0.1:4943/?canisterId=r7inp-6aaaa-aaaaa-aaabq-cai
-```
-
-The browser then displays a form for you to specify a canister identifier or choose a Candid description (`.did`) file. 
-Note that this field refers to the canister identifier of the canister you would like to interact with (as opposed to the canister identifier for the Candid UI that you used in the last step).
-
-Specify the canister identifier of the canister you would like to test in the **Provide a canister ID** field, then click **Go** to display the service description.
-
-If you aren’t sure which canister identifier to use, you can run the `dfx canister id` command to look up the identifier for a specific canister name. For instance, to get the canister identifier for a canister named `my_counter`, you would use:
-
-```
-dfx canister id my_counter
-```
-
-Review the list of function calls and types defined in the dapp.
-
-Type a value of the appropriate type for a function or click **Random** to generate a value, then click **Call** or **Query** to see the result.
-
-:::info
-Note that depending on the data type, the Candid interface might display additional configuration settings for testing functions.
-:::
-
-For example, if a function takes an array, you might need to specify the number of items in the array before entering values.
-
-![Calculator functions](_attachments/candid-calc.png)
+- [Candid specification](https://github.com/dfinity/candid/blob/master/spec/Candid.md).
 
 ## Next steps
 

docs/developer-docs/backend/motoko/counter-tutorial.md

@@ -70,7 +70,7 @@ To modify the default template source code, open the `src/my_counter_backend/inc
 
 Copy and paste this code into the `increment_counter.mo` file:
 
-```
+```motoko
 // Create a simple Counter actor.
 actor Counter {
 stable var currentValue : Nat = 0;

docs/developer-docs/backend/motoko/define-an-actor.md

@@ -43,7 +43,7 @@ The sample canister for this guide doesn’t use any frontend assets, so you can
 For example, if you remove the `actor_hello_assets` section, the configuration file looks like this:
 
 
-```
+```json
     {
     "canisters": {
         "actor_hello": {
@@ -78,7 +78,7 @@ The next step is to write a canister that prints a statement like the traditiona
 
 Copy and paste this code into the `main.mo` file:
 
-```
+```motoko
 import Debug "mo:base/Debug";
 actor HelloActor {
    public query func hello() : async () {
@@ -205,7 +205,7 @@ The `dfx canister create` command also stores the connection-specific canister i
 
 For example:
 
-```
+```json
 {
 "actor_hello_backend": {
     "local": "dzh22-nuaaa-aaaaa-qaaoa-cai"

docs/developer-docs/backend/motoko/deploying.md

@@ -32,7 +32,7 @@ Open the `dfx.json` configuration file in a text editor to review the default se
 
 It may look like this:
 
-```
+```json
 {
 "canisters": {
     "explore_hello_backend": {
@@ -90,7 +90,7 @@ Let’s take a look at the sample program in the default `main.mo` template file
 
 Open the `src/explore_hello_backend/main.mo` file in a text editor and review the code in the template:
 
-```
+```motoko
 actor {
     public func greet(name : Text) : async Text {
         return "Hello, " # name # "!";
@@ -141,8 +141,6 @@ Leave the terminal that displays network operations open and switch your focus t
 
 After you connect to the local canister execution environment, you can register with the network to generate unique, network-specific **canister identifiers** for your project.
 
-In the [1.3: Deploying your first dapp](/docs/tutorials/developer-journey/level-1/1.3-first-dapp.md) developer journey tutorial, this step was performed as part of the `dfx deploy` command work flow. This guide demonstrates how to perform each of the operations independently.
-
 To register canister identifiers for the local network, register unique canister identifiers for the canisters in the project by running the following command:
 
 ```
@@ -162,7 +160,7 @@ Because you are connected to the local canister execution environment, these can
 
 For example:
 
-```
+```json
 {
 "explore_hello_backend": {
     "local": "br5f7-7uaaa-aaaaa-qaaca-cai"
@@ -289,7 +287,7 @@ Open a terminal window on your local computer, if you don’t already have one o
 
 Open the `src/explore_hello_frontend/src/index.js` file in a text editor and review the code in the template script:
 
-```
+```javascript
 import { explore_hello } from "../../declarations/explore_hello_backend";
 
 document.getElementById("clickMeBtn").addEventListener("click", async () => {

docs/developer-docs/backend/motoko/explore-templates.md

@@ -1,7 +1,6 @@
 # 2: Project organization
 
 ## Overview
-If you started your tour of the IC SDK with the [0.6: Introduction to dfx](/docs/tutorials/developer-journey/level-0/06-intro-dfx.md) developer journey tutorial, you have already seen the basic work flow for creating dapps that run on the Internet Computer. Now, let’s take a closer look at that work flow by exploring the default files and folders that are added to your workspace when you create a new project.
 
 As a preview, the following diagram illustrates the development work flow when running the Internet Computer locally on you computer.
 
@@ -68,7 +67,7 @@ To review the default configuration file for your project, open the `dfx.json` c
 
 The contents of the file should resemble the following:
 
-```
+```json
 {
   "canisters": {
     "explore_hello_backend": {
@@ -119,7 +118,7 @@ Let’s take a look at the sample program in the default `main.mo` template file
 
 To review the default sample program for your project, open the `src/explore_hello_backend/main.mo` file in a text editor and review the code in the template:
 
-```
+```motoko
 actor {
   public query func greet(name : Text) : async Text {
     return "Hello, " # name # "!";