Skip to content

Commit

Permalink
Docs audit #3 (#3809)
Browse files Browse the repository at this point in the history 
* docs audit 3

* Update docs/developer-docs/getting-started/troubleshooting.mdx

Co-authored-by: Marco Walz <[email protected]>

* Update docs/developer-docs/smart-contracts/advanced-features/composite-query.mdx

Co-authored-by: Marco Walz <[email protected]>

---------

Co-authored-by: Marco Walz <[email protected]>
  • Loading branch information
@jessiemongeon1 @marc0olo
jessiemongeon1 and marc0olo authored Dec 3, 2024
1 parent 0b9fc46 commit dcf12f1
Show file tree
Hide file tree
Showing 20 changed files with 401 additions and 3,098 deletions.
2 changes: 2 additions & 0 deletions docs/developer-docs/getting-started/install.mdx
View file
Original file line number Diff line number Diff line change
Expand Up @@ -136,6 +136,8 @@ It also has dependencies of a few additional, important packages:

- [**Candid**](/docs/current/developer-docs/smart-contracts/candid/candid-concepts): An interface description language (IDL) used to interact with a canister's methods. A **method** is a function exposed by the canister that can be called by a user, another canister, or the application's frontend.

For troubleshooting common `dfx` errors, see [IC SDK troubleshooting](troubleshooting.mdx).

## Next step

Next, you must create a developer identity. This identity will be used to control and manage your project's canisters.
Expand Down
113 changes: 113 additions & 0 deletions docs/developer-docs/getting-started/troubleshooting.mdx
View file
Original file line number Diff line number Diff line change
@@ -0,0 +1,113 @@
---
keywords: [intermediate, test, tutorial, troubleshooting, dfx troubleshooting, ic sdk, dfx, ic sdk troubleshooting]
---

import { MarkdownChipRow } from "/src/components/Chip/MarkdownChipRow";

# IC SDK troubleshooting

<MarkdownChipRow labels={["Beginner"]} />

## Overview

This section provides information to help you troubleshoot and resolve or work around common issues that are related to the following tasks:

- Downloading and installing the IC SDK.

- Creating, building, or deploying canisters.

- Using the [IC SDK](/docs/current/developer-docs/getting-started/install).

- Running the local replica.

## Migrating an existing project

Currently, there is no automatic migration or backward compatibility for any projects that you might have created using previous versions of the IC SDK. After upgrading to the latest version, you might see error or failure messages if you attempt to build or install a project created with a previous version of the IC SDK.

In many cases, however, you can continue to work with projects from a previous release by manually changing the `dfx` setting in the `dfx.json` configuration file, then rebuilding the project to be compatible with the version of the IC SDK you have currently installed.

For example, if you have a project that was created with IC SDK version `0.8.0`, open the `dfx.json` file in a text editor and change the `dfx` setting to the latest version or remove the section entirely.

## Restarting the local replica

In some cases, starting the local replica fails due to stale state. If you encounter issues when running `dfx start` to start the local replica:

- #### Step 1: Interrupt the local replica process through Ctrl+C if necessary, then stop the local replica:

```bash
dfx stop
```

- #### Step 2: If not all `dfx` processes can be stopped, forcibly end them:

```
dfx killall
```

- #### Step 3: Restart the local replica in a clean state by running the following command:

```bash
dfx start --clean --background
```

The `--clean` option removes checkpoints and stale state information from your project’s cache so that you can restart the local replica and web server processes in a clean state.

:::danger
Resetting the state information by running `dfx start --clean` removes your existing canisters and new canister IDs may differ from old ones.
:::

- #### Step 4: Recreate your canisters:

```bash
dfx canister create --all
dfx build
dfx canister install --all
```

## Removing the canisters directory

If you run into problems building or deploying canisters after successfully connecting to ICP and registering canister identifiers, you should remove the `canisters` directory before attempting to rebuild or redeploy the canisters.

You can remove the `canisters` directory for a project by running the following command in the project’s root directory:

```bash
rm -rf ./.dfx/* canisters/*
```

## Reinstalling `dfx`

Some bugs can be addressed by uninstalling and reinstalling the IC SDK:

```bash
~/.cache/dfinity/uninstall.sh && sh -ci "$(curl -sSL https://internetcomputer.org/install.sh)"
```

If you have modified the location of the IC SDK binary (the binary is titled `dfx`), you might want run the following command to uninstall the version of the IC SDK that is in your PATH, then reinstall the latest version of the IC SDK:

```bash
rm -rf ~/.cache/dfinity && rm $(which dfx) && sh -ci "$(curl -sSL https://internetcomputer.org/install.sh)"
```

## Xcode prerequisite

For macOS environments, you should have **Developer Command Line Tools** installed if you want to create a Git repository for your project.

You can check whether you have the developer tools installed by running `xcode-select -p`. You can install the developer tools by running `xcode-select --install`.

## Memory leak

Fixing memory leaks is an ongoing process. If you encounter any error messages related to memory leaks, you should do the following:

- #### Step 1: Run `dfx stop` to stop currently running processes.

- #### Step 2: Uninstall the IC SDK to prevent further degradation.

- #### Step 3: Re-install the IC SDK

- #### Step 4: Run `dfx start` to restart replica processes.

Alternatively, you can remove the `.cache/dfinity` directory and re-install the latest IC SDK `dfx` binary:

```bash
rm -rf ~/.cache/dfinity && sh -ci "$(curl -sSL https://internetcomputer.org/install.sh)"
```
10 changes: 10 additions & 0 deletions docs/developer-docs/smart-contracts/advanced-features/async-code.mdx
View file
Original file line number Diff line number Diff line change
@@ -1,3 +1,13 @@
---
keywords: [advanced, concept, async code, inter-canister calls, async inter-canister, async]
---

import { MarkdownChipRow } from "/src/components/Chip/MarkdownChipRow";

# Composite queries

<MarkdownChipRow labels={["Advanced", "Concept"]} />

# Async code and inter-canister calls

## Overview
Expand Down
120 changes: 27 additions & 93 deletions docs/developer-docs/smart-contracts/advanced-features/composite-query.mdx
View file
Original file line number Diff line number Diff line change
Expand Up @@ -2,8 +2,11 @@
keywords: [advanced, tutorial, composite queries, queries]
---


import TabItem from "@theme/TabItem";
import { AdornedTabs } from "/src/components/Tabs/AdornedTabs";
import { AdornedTab } from "/src/components/Tabs/AdornedTab";
import { MarkdownChipRow } from "/src/components/Chip/MarkdownChipRow";
import { GlossaryTooltip } from "/src/components/Tooltip/GlossaryTooltip";

# Composite queries

Expand All @@ -12,31 +15,31 @@ import { MarkdownChipRow } from "/src/components/Chip/MarkdownChipRow";
## Overview
The Internet Computer Protocol supports two types of messages: updates and queries. An update message is executed on all nodes and persists canister state changes. A query message discards state changes and typically executes on a single node. It is possible to execute a query message as an update. In such a case, the query still discards the state changes, but the execution happens on all nodes and the result of execution goes through consensus. This “query-as-update” execution mode is also known as replicated query.

An update can call other updates and queries. However a query cannot make any calls, which can hinder development of scalable decentralized applications (dapps), especially those that shard data across multiple canisters.
An update can call other updates and queries. However a query cannot make any calls, which can hinder development of scalable decentralized applications, especially those that shard data across multiple canisters.

Composite queries solve this problem. A composite query is a new type of query that you can add to your canister using the following annotations:
Composite queries solve this problem. You can add composite queries to your canister using the following annotations:

* Candid: `composite_query`
* Azle: `$query`; in combination with `async`
* Motoko: `composite query`
* Rust: `#[query(composite = true)]`

Users and the client-side JavaScript code can invoke a composite query endpoint of a canister using the same query URL as for existing regular queries. In contrast to regular queries, a composite query can call other composite and regular queries. Due to limitations of the current implementation, composite queries have two restrictions:
Users and the client-side JavaScript code can invoke a composite query endpoint of a canister using the same query URL for existing regular queries. In contrast to regular queries, a composite query can call other composite and regular queries. Due to limitations of the current implementation, composite queries have two restrictions:

* A composite query cannot call canisters on another subnet.
* A composite query cannot be executed as an update. As a result, updates cannot call composite queries.
| Query | Update | Composite query |
|--------|--------|----------------|
| Cannot call other queries or composite queries| Can call other updates and queries ; Cannot call composite queries| Can call other queries and composite queries |
| Can be called as an update | Cannot be called as a query | Cannot be called as an update |
| Can call canisters on another subnet | Can call canisters on another subnet | Cannot call canisters on another subnet |

These restrictions will be hopefully lifted in future implementations.

Composite queries are enabled in the following releases:
Composite queries were enabled in the following releases:

| Platform / Language | Version |
| -------------------------- | ------- |
| Internet computer mainnet | Release [7742d96ddd30aa6b607c9d2d4093a7b714f5b25b](https://nns.ic0.app/proposal/?u=qoctq-giaaa-aaaaa-aaaea-cai&proposal=123311) |
| Candid | [2023-06-30 (Rust 0.9.0)](https://github.com/dfinity/candid/blob/master/Changelog.md#2023-06-30-rust-090) |
| Motoko | [0.9.4](https://github.com/dfinity/motoko/releases/tag/0.9.4), revision: [2d9902f](https://github.com/dfinity/motoko/commit/2d9902fb75bb04e377c28913c311aa2be373e159) |
| Rust | [0.6.8](https://github.com/dfinity/cdk-rs/blob/219ae179b9c5ef0ebfff20b926a90f6624ebe704/src/ic-cdk/CHANGELOG.md#068---2022-11-28) |
| Azle | [0.11.0](https://github.com/demergent-labs/azle/releases/tag/0.11.0) |


## Sample code
Expand All @@ -45,104 +48,35 @@ As an example, consider a partitioned key-value store, where a single frontend d
- First, determines the ID of the data partition canister that holds the value with the given key.
- Then, makes a call into the `get` or `put` function of that canister and parses the result.

Below is a simplified example of the frontend code. Take note of the line `#[query(composite = true)]` which is used to leverage the new composite query feature:

```rust
#[query(composite = true)]
async fn frontend_get(key: u128) -> Option<u128> {
let canister_id = get_partition_for_key(key);
match call(canister_id, "get", (key, ), ).await {
Ok(r) => {
let (res,): (Option<u128>,) = r;
res
},
Err(_) => None,
}
}
```

The backend simply stores the key value pairs in a `BTreeMap` in stable memory:
<AdornedTabs groupId="language">
<TabItem value="motoko" label="Motoko" default>

```rust
#[query]
fn get(key: u128) -> Option<u128> {
STORE.with(|store| store.borrow().get(&key))
}
```motoko no-repl file=../../../references/samples/motoko/composite_query/src/map/Map.mo
```

## Using composite queries
### Prerequisites
- [x] [Download and install the IC SDK.](/docs/current/developer-docs/getting-started/install)
- [x] [Download and install git.](https://git-scm.com/downloads)
</TabItem>
<TabItem value="rust" label="Rust">

### Setting up the example
- #### Step 1: Open a terminal window and clone the DFINITY examples repo with the command:

```bash
git clone https://github.com/dfinity/examples.git
```rust file=../../../references/samples/rust/composite_query/src/kv_frontend/lib.rs
```
</TabItem>

- #### Step 2: Navigate into the `rust/composite_query/src` directory, start a local replica, and build the frontend canister with the commands:

```bash
cd rust/composite_query/src
dfx start
dfx canister create kv_frontend
dfx build kv_frontend
During compilation of the fronted canister, the backend canister's wasm code will be compiled and inlined in the frontend canister's wasm code.
```
<AdornedTab value={"typescript"} label="TypeScript" endAdornment={<BetaChip />}>

- #### Step 3: Then, install the frontend canister with the command:
[Learn more about Azle](https://demergent-labs.github.io/azle/the_azle_book.html).

```
dfx canister install kv_frontend
```

### Interacting with the canisters
- #### Step 1: To add a key-value pair via the frontend canister, run the following command:

```bash
dfx canister call kv_frontend put '(1, 1337)'
```

:::note
The first call to put might be slow to respond because the data partition canisters have to be created first.
:::

The output should resemble the following indicating that no value has previously been registered for this key:
```(null)```

- #### Step 2: Retrieve the value associated with a key using composite queries with the command:

```bash
dfx canister call kv_frontend get '(1)'
```

The output should resemble the following:
```(opt (1337 : nat))```

This workflow displays the ability to fetch the value using composite queries with very low latency.

## Comparing composite queries to calls from update functions
Let’s now compare the performance of composite query calls with those of an equivalent implementation that leverages calls from update functions. To do this, you will use the `get_update` method, which contains the exact same logic, but is implemented based on update calls. Run the following command in your terminal window:

```bash
dfx canister call kv_frontend get_update '(1)'
```
</AdornedTab>

The output will resemble the following:
```(opt (1_337 : nat))```
<AdornedTab value={"python"} label="Python" endAdornment={<BetaChip />}>

You can observe that with update calls you receive the very same result, but the call is at least one order of magnitude slower compared to composite query calls.
[Learn more about Kybra](https://demergent-labs.github.io/kybra/).

:::note
The examples repository also contains an equivalent [Motoko example](https://github.com/dfinity/examples/tree/master/motoko/composite_query).
:::
</AdornedTab>
</AdornedTabs>

## Resources
The following example canisters demonstrate how to use composite queries:

* [Azle example](https://github.com/demergent-labs/azle/tree/main/examples/composite_queries)
* [Motoko example](https://github.com/dfinity/examples/tree/master/motoko/composite_query)
* [Rust example](https://github.com/dfinity/examples/tree/master/rust/composite_query)

Expand Down
Loading

0 comments on commit dcf12f1

Please sign in to comment.