diff --git a/README.md b/README.md index 220bf01d62..84b279a1d2 100644 --- a/README.md +++ b/README.md @@ -142,11 +142,6 @@ This audience should be kept in mind when writing docs. For example: ### Documentation types The structure and content of the documentation page will vary based on the document type. Some common types are: -#### Overview -An overview of a documentation section or broad concept of ICP. When creating an overview page that discusses the capabilities of ICP, the benefits and attributes of the possible capabilities should be written about, not only the currently implemented workflows. For example, instead of writing about the currently implemented Bitcoin and Ethereum integrations, the [Chain Fusion overview](/docs/current/developer-docs/multi-chain/overview) page discusses ICP’s cross-chain functionalities and benefits on a much broader scale beyond the two current integrations. - -For overview pages, using bullet point lists to describe specific benefits or features of ICP is recommended. - #### Feature or tool detail page A page that details a specific tool or feature. Feature or tool pages should provide a deeper explanation of a specific feature or tool, why a developer should use it, and how they can use it. It should describe the currently implemented workflows the feature/tool supports, and should not include details of conceptual ideas that are not currently live for developers to use (future roadmap items, possible improvements in the future, etc.) diff --git a/blog/news-and-updates/2024-12-11-update.mdx b/blog/news-and-updates/2024-12-11-update.mdx new file mode 100644 index 0000000000..1f4ba03f13 --- /dev/null +++ b/blog/news-and-updates/2024-12-11-update.mdx @@ -0,0 +1,44 @@ +--- +title: Developer weekly update December 11, 2024 +description: This week, we have an important Motoko security update, an upgrade to the NNS Chain Fusion signer canister, and a new package from Mops- regex. +tags: [Devs] +image: /img/blog/dev-update-blog-dec-11.jpg +--- + +# Developer weekly update December 11, 2024 + +![December 11 2024](../../static/img/blog/dev-update-blog-dec-11.jpg) + +Hello developers, and welcome to this week's developer weekly update! This week, we have an important Motoko security update, an upgrade to the NNS Chain Fusion signer canister, and a new package from Mops: regex. Let's get started! + +## Motoko security fix in dfx v0.24.3 + +A security bug in Motoko was recently discovered that, under certain circumstances, may lead to unwanted memory reads or writes. This bug only affected those using the incremental garbage collector or enhanced orthogonal persistence and was hard to trigger depending on heap constellations, garbage collection scheduling, and specific language features used at a large scale. + +This bug has been fixed in Motoko v0.14.3, which is included in `dfx` v0.24.3 and newer. It is highly recommended to upgrade to the latest `dfx` version if you are using the incremental garbage collector or enhanced orthogonal persistence. + +[Learn more on the dev forum](https://forum.dfinity.org/t/security-fix-in-motoko-dfx-0-24-3/38656/1). + +## Upgrade NNS canister: Chain Fusion signer + +The latest update to the Chain Fusion signer canister can be used to sign transactions from APIs directly from a web browser or off-chain client. + +NNS proposal 134424 introduces Schnorr signatures to be added to the signer canister API, specifically adding the `schnorr_public_key()` and `schnorr_sign()` methods. The Schnorr API can also be used to sign Solana transactions. + +[Read more on the dev forum](https://forum.dfinity.org/t/upgrade-nns-canister-chain-fusion-signer/38623/1). + +## Mops regex package + +A new Mops package has been released: regex. This package allows you to use regex patterns for objects and flags. The team behind this package has published a [tutorial video](https://www.youtube.com/watch?v=O1dOZfK6DQA). + +You can install the Motoko regex package with: + +``` +mops add regex +``` + +[Learn more on the dev forum](https://forum.dfinity.org/t/motoko-regex-is-live-on-mops/37428/1). + +That'll wrap up this week. Tune back in next week for more developer updates! + +-DFINITY \ No newline at end of file diff --git a/docs/developer-docs/ai/ai-on-chain.mdx b/docs/developer-docs/ai/ai-on-chain.mdx index 5595e8760e..7d9298e75d 100644 --- a/docs/developer-docs/ai/ai-on-chain.mdx +++ b/docs/developer-docs/ai/ai-on-chain.mdx @@ -10,7 +10,7 @@ import '/src/components/CenterImages/center.scss'; -## Overview + ICP's unique ability to run compute at scale allows AI and neural networks to run directly onchain within a canister smart contract. diff --git a/docs/developer-docs/ai/inference.mdx b/docs/developer-docs/ai/inference.mdx index c161521e99..33b6c65c9a 100644 --- a/docs/developer-docs/ai/inference.mdx +++ b/docs/developer-docs/ai/inference.mdx @@ -8,7 +8,7 @@ import { MarkdownChipRow } from "/src/components/Chip/MarkdownChipRow"; -## Overview + Inference in the context of decentralized AI refers to using a trained model to draw conclusions about new data. It's possible for canister smart contracts to run inference in a number of ways depending on the decentralization and performance requirements. diff --git a/docs/developer-docs/ai/machine-learning-sample.mdx b/docs/developer-docs/ai/machine-learning-sample.mdx index 3c8db1b341..4982efc2fb 100644 --- a/docs/developer-docs/ai/machine-learning-sample.mdx +++ b/docs/developer-docs/ai/machine-learning-sample.mdx @@ -11,7 +11,7 @@ import '/src/components/CenterImages/center.scss'; -## Overview + Machine learning is a form of artificial intelligence (AI) that observes statistical algorithms and their data to learn patterns and generalizations. By analyzing these data patterns, machine learning algorithms can execute tasks by predicting the correct result with high accuracy. diff --git a/docs/developer-docs/ai/samples.mdx b/docs/developer-docs/ai/samples.mdx index 4d546283a5..65f283425d 100644 --- a/docs/developer-docs/ai/samples.mdx +++ b/docs/developer-docs/ai/samples.mdx @@ -10,7 +10,7 @@ import { MarkdownChipRow } from "/src/components/Chip/MarkdownChipRow"; -## Overview + ICP's unique ability to run compute at scale allows AI and neural networks to run directly onchain within a canister smart contract. Canisters can also interact with LLMs stored off-chain through HTTPS outcalls, or stored locally on a user's device. diff --git a/docs/developer-docs/ai/training-models.mdx b/docs/developer-docs/ai/training-models.mdx index b3ab656bbf..a02d9d137b 100644 --- a/docs/developer-docs/ai/training-models.mdx +++ b/docs/developer-docs/ai/training-models.mdx @@ -8,7 +8,7 @@ import { MarkdownChipRow } from "/src/components/Chip/MarkdownChipRow"; -## Overview + Training AI models on ICP provides developers with a decentralized infrastructure and simplifies the setup process. ICP’s built-in computation and storage capabilities remove the need for external hardware. With GPU support on the roadmap, ICP will soon further enhance its AI capabilities and allow developers to train complex models, including large-scale AI systems. diff --git a/docs/developer-docs/backend/rust/access-control.mdx b/docs/developer-docs/backend/rust/access-control.mdx index 6220ce6be9..fec0a2f74c 100644 --- a/docs/developer-docs/backend/rust/access-control.mdx +++ b/docs/developer-docs/backend/rust/access-control.mdx @@ -9,7 +9,7 @@ import { MarkdownChipRow } from "/src/components/Chip/MarkdownChipRow"; -## Overview + To demonstrate access control using a Rust backend canister, you'll explore access control in the context of NFTs. NFTs (non-fungible tokens) are unique tokens with arbitrary metadata, usually an image of some kind, to form the digital equivalent of trading cards. diff --git a/docs/developer-docs/backend/rust/candid.mdx b/docs/developer-docs/backend/rust/candid.mdx index 38003a57b6..b1ae7edbc4 100644 --- a/docs/developer-docs/backend/rust/candid.mdx +++ b/docs/developer-docs/backend/rust/candid.mdx @@ -8,7 +8,7 @@ import { MarkdownChipRow } from "/src/components/Chip/MarkdownChipRow"; -## Overview + Candid is an **interface description language** with the primary purpose of describing the public interface of a service. A service is usually in the form of a program deployed as a canister. Candid is language-agnostic, meaning that it allows for the inter-operation between services and frontends written in different programming languages, including Rust. diff --git a/docs/developer-docs/backend/rust/counter.mdx b/docs/developer-docs/backend/rust/counter.mdx index bfddc269a1..4bd89cd61c 100644 --- a/docs/developer-docs/backend/rust/counter.mdx +++ b/docs/developer-docs/backend/rust/counter.mdx @@ -8,7 +8,7 @@ import { MarkdownChipRow } from "/src/components/Chip/MarkdownChipRow"; -## Overview + In this guide, you are going to write a dapp that provides a few basic functions to increment a counter value. by calling functions on a deployed canister. By calling the function to increment a value multiple times, you can verify that the variable state, that is, the value of the variable between calls, persists. diff --git a/docs/developer-docs/backend/rust/deploying.mdx b/docs/developer-docs/backend/rust/deploying.mdx index e372e38570..2eac673d90 100644 --- a/docs/developer-docs/backend/rust/deploying.mdx +++ b/docs/developer-docs/backend/rust/deploying.mdx @@ -9,7 +9,7 @@ import { GlossaryTooltip } from "/src/components/Tooltip/GlossaryTooltip"; -## Overview + In this guide, you'll learn the steps required to write, compile, deploy, and interact with a Rust backend canister. diff --git a/docs/developer-docs/backend/rust/generating-candid.mdx b/docs/developer-docs/backend/rust/generating-candid.mdx index 67f1ce1b56..09ea4e6fa0 100644 --- a/docs/developer-docs/backend/rust/generating-candid.mdx +++ b/docs/developer-docs/backend/rust/generating-candid.mdx @@ -8,7 +8,7 @@ import { MarkdownChipRow } from "/src/components/Chip/MarkdownChipRow"; -## Overview + In versions of the Rusk CDK `v0.11.0` and higher, the Candid export workflow has been changed. You can call the `ic_cdk::export_candid!()` macro to enable the Candid export behavior, then use the [candid-extractor](https://github.com/dfinity/cdk-rs/tree/main/src/candid-extractor) to extract the Candid from the canister's Wasm. diff --git a/docs/developer-docs/backend/rust/intercanister.mdx b/docs/developer-docs/backend/rust/intercanister.mdx index 3068125950..7def78c59d 100644 --- a/docs/developer-docs/backend/rust/intercanister.mdx +++ b/docs/developer-docs/backend/rust/intercanister.mdx @@ -8,7 +8,7 @@ import { MarkdownChipRow } from "/src/components/Chip/MarkdownChipRow"; -## Overview + Inter-canister calls can be used to update information between two or more canisters. diff --git a/docs/developer-docs/backend/rust/message-inspect.mdx b/docs/developer-docs/backend/rust/message-inspect.mdx index 43e792978b..86f961305f 100644 --- a/docs/developer-docs/backend/rust/message-inspect.mdx +++ b/docs/developer-docs/backend/rust/message-inspect.mdx @@ -8,7 +8,7 @@ import { MarkdownChipRow } from "/src/components/Chip/MarkdownChipRow"; -## Overview + A canister can inspect an ingress message and either accept or decline the message through the canister's HTTPS interface. If the message is accepted, the canister will execute it. diff --git a/docs/developer-docs/backend/rust/optimizing.mdx b/docs/developer-docs/backend/rust/optimizing.mdx index 717b9090d3..16283ceca6 100644 --- a/docs/developer-docs/backend/rust/optimizing.mdx +++ b/docs/developer-docs/backend/rust/optimizing.mdx @@ -8,7 +8,7 @@ import { MarkdownChipRow } from "/src/components/Chip/MarkdownChipRow"; -## Overview + Compiling Rust to Wasm often increases the file size significantly. `dfx` versions `0.14.0` and newer include the `wasm-opt` package that can be used to optimize cycle consumption and binary size. ## Prerequisites diff --git a/docs/developer-docs/backend/rust/project-organization.mdx b/docs/developer-docs/backend/rust/project-organization.mdx index b9311036bc..b2993f1307 100644 --- a/docs/developer-docs/backend/rust/project-organization.mdx +++ b/docs/developer-docs/backend/rust/project-organization.mdx @@ -8,7 +8,7 @@ import { MarkdownChipRow } from "/src/components/Chip/MarkdownChipRow"; -## Overview + When a new Rust project is created with the command: diff --git a/docs/developer-docs/backend/rust/quickstart.mdx b/docs/developer-docs/backend/rust/quickstart.mdx index 2610ba7e1b..17319784c7 100644 --- a/docs/developer-docs/backend/rust/quickstart.mdx +++ b/docs/developer-docs/backend/rust/quickstart.mdx @@ -9,7 +9,7 @@ import { GlossaryTooltip } from "/src/components/Tooltip/GlossaryTooltip"; -## Overview + Applications for ICP start as **projects**. You can create new projects for ICP using the IC SDK. This guide focuses on how to create, build, and deploy a Rust program by using the `dfx` parent command and its subcommands. diff --git a/docs/developer-docs/backend/rust/rust-considerations.mdx b/docs/developer-docs/backend/rust/rust-considerations.mdx index d14fbbecca..9d7f57b190 100644 --- a/docs/developer-docs/backend/rust/rust-considerations.mdx +++ b/docs/developer-docs/backend/rust/rust-considerations.mdx @@ -8,7 +8,7 @@ import { MarkdownChipRow } from "/src/components/Chip/MarkdownChipRow"; -## Overview + This guide describes information that developers should consider when writing Rust canisters, specifically regarding canister observability and global state. diff --git a/docs/developer-docs/backend/rust/rust-limitations.mdx b/docs/developer-docs/backend/rust/rust-limitations.mdx index b03050052d..3c4ffada37 100644 --- a/docs/developer-docs/backend/rust/rust-limitations.mdx +++ b/docs/developer-docs/backend/rust/rust-limitations.mdx @@ -8,7 +8,7 @@ import { MarkdownChipRow } from "/src/components/Chip/MarkdownChipRow"; -## Overview + WebAssembly (Wasm) is a binary code format and does not provide network access, a filesystem, or other functionalities other than pure computation. Anything function that needs to communicate outside of the Wasm module must use an IC API. This guide details limitations imposed by Wasm on canisters written in Rust. diff --git a/docs/developer-docs/backend/rust/searching-records.mdx b/docs/developer-docs/backend/rust/searching-records.mdx index 445f392afc..524370eb99 100644 --- a/docs/developer-docs/backend/rust/searching-records.mdx +++ b/docs/developer-docs/backend/rust/searching-records.mdx @@ -9,7 +9,7 @@ import { GlossaryTooltip } from "/src/components/Tooltip/GlossaryTooltip"; -## Overview + In this guide, you are going to write a dapp that provides a few basic functions to add and retrieve simple profile records that consist of a name, description, and an array of keywords. This program supports the following functions: diff --git a/docs/developer-docs/backend/rust/stable-structures.mdx b/docs/developer-docs/backend/rust/stable-structures.mdx index 149fd98e65..a4a0ea603a 100644 --- a/docs/developer-docs/backend/rust/stable-structures.mdx +++ b/docs/developer-docs/backend/rust/stable-structures.mdx @@ -8,7 +8,7 @@ import { MarkdownChipRow } from "/src/components/Chip/MarkdownChipRow"; -## Overview + Stable structures are designed to use stable memory as the backing store, allowing them to grow to gigabytes in size without the need for `pre_upgrade`/`post_upgrade` hooks. diff --git a/docs/developer-docs/backend/rust/timers.mdx b/docs/developer-docs/backend/rust/timers.mdx index a43e1f2277..c57bbb7b69 100644 --- a/docs/developer-docs/backend/rust/timers.mdx +++ b/docs/developer-docs/backend/rust/timers.mdx @@ -9,7 +9,7 @@ import { GlossaryTooltip } from "/src/components/Tooltip/GlossaryTooltip"; -## Overview + This guide demonstrates how to create a small dapp with a periodic task. The task is triggered automatically by the ICP network with a specified interval. ## Prerequisites diff --git a/docs/developer-docs/backend/rust/upgrading.mdx b/docs/developer-docs/backend/rust/upgrading.mdx index 62755ff301..0184e2cd6a 100644 --- a/docs/developer-docs/backend/rust/upgrading.mdx +++ b/docs/developer-docs/backend/rust/upgrading.mdx @@ -8,7 +8,7 @@ import { MarkdownChipRow } from "/src/components/Chip/MarkdownChipRow"; -## Overview + Unlike a canister reinstall that preserves the canister identifier but no state, a canister upgrade enables you to preserve the state of a deployed canister and change the code. diff --git a/docs/developer-docs/cost-estimations-and-examples.mdx b/docs/developer-docs/cost-estimations-and-examples.mdx index 07707f94fa..26beaa5418 100644 --- a/docs/developer-docs/cost-estimations-and-examples.mdx +++ b/docs/developer-docs/cost-estimations-and-examples.mdx @@ -8,7 +8,7 @@ import { MarkdownChipRow } from "/src/components/Chip/MarkdownChipRow"; -## Overview + To get a rough estimate of how much your project may cost, below is a pricing calculator that can be used to estimate the cost of a dapp deployed on ICP. Costs are charged to a canister in cycles, which are fixed against the price of [XDR](/docs/current/references/glossary#xdr), where **1 trillion cycles equals 1 XDR**. Cycles costs are calculated based on: diff --git a/docs/developer-docs/daos/nns/concepts/neurons/becoming-a-known-neuron.mdx b/docs/developer-docs/daos/nns/concepts/neurons/becoming-a-known-neuron.mdx index fb909d1a7f..3ce4d7c190 100644 --- a/docs/developer-docs/daos/nns/concepts/neurons/becoming-a-known-neuron.mdx +++ b/docs/developer-docs/daos/nns/concepts/neurons/becoming-a-known-neuron.mdx @@ -9,7 +9,7 @@ import '/src/components/CenterImages/center.scss'; -## Overview + A know neuron has a name and optionally a short description. A known neuron can be registered in the NNS governance via a proposal, officially storing its name and description within the NNS. This information can be used by other neurons to find known neurons and [follow](/docs/current/developer-docs/daos/nns/concepts/neurons/neuron-following) them. diff --git a/docs/developer-docs/daos/nns/concepts/neurons/neuron-following.mdx b/docs/developer-docs/daos/nns/concepts/neurons/neuron-following.mdx index cf0f160a53..7ae27b0f3e 100644 --- a/docs/developer-docs/daos/nns/concepts/neurons/neuron-following.mdx +++ b/docs/developer-docs/daos/nns/concepts/neurons/neuron-following.mdx @@ -9,7 +9,7 @@ import '/src/components/CenterImages/center.scss'; -## Overview + Users may not have the time or knowledge to participate in all voting decisions. Therefore, instead of directly voting on proposals, neuron holders may choose to delegate their vote to other neurons that they trust with certain decisions. This concept, where a neuron follows the decisions of some other neurons, is called **following** in the NNS DAO. diff --git a/docs/developer-docs/daos/nns/concepts/neurons/neuron-management.mdx b/docs/developer-docs/daos/nns/concepts/neurons/neuron-management.mdx index 664b2a51f3..5bbd35586a 100644 --- a/docs/developer-docs/daos/nns/concepts/neurons/neuron-management.mdx +++ b/docs/developer-docs/daos/nns/concepts/neurons/neuron-management.mdx @@ -15,7 +15,7 @@ This page is for you if you want to learn the technical details about neuron ope Tutorials for users who want to interact with the NNS using the [NNS dapp](https://nns.ic0.app) frontend are available in the [NNS dapp quickguide](/docs/current/developer-docs/daos/nns/using-the-nns-dapp/nns-app-quickstart). -## Overview + View the most up-to-date [`candid` definition for the NNS governance canister](https://github.com/dfinity/ic/blob/master/rs/nns/governance/canister/governance.did). This page will explain some of the relevant definitions from this Candid file. To keep up to date with new NNS release proposals from DFINITY, you can subscribe to [this forum thread](https://forum.dfinity.org/t/nns-updates-aggregation-thread/23551). diff --git a/docs/developer-docs/daos/nns/concepts/neurons/staking-voting-rewards.mdx b/docs/developer-docs/daos/nns/concepts/neurons/staking-voting-rewards.mdx index e1c2e28d61..ccdbf3e5d7 100644 --- a/docs/developer-docs/daos/nns/concepts/neurons/staking-voting-rewards.mdx +++ b/docs/developer-docs/daos/nns/concepts/neurons/staking-voting-rewards.mdx @@ -8,7 +8,7 @@ import { MarkdownChipRow } from "/src/components/Chip/MarkdownChipRow"; -## Overview + Stakeholders gain voting power and can earn voting rewards by staking their ICP tokens in neurons and participating in governance. The Internet Computer is a decentralized platform whose evolution is decided by its stakeholders through voting. diff --git a/docs/developer-docs/daos/nns/concepts/proposals/direct-voting.mdx b/docs/developer-docs/daos/nns/concepts/proposals/direct-voting.mdx index f38809424b..d4f228f424 100644 --- a/docs/developer-docs/daos/nns/concepts/proposals/direct-voting.mdx +++ b/docs/developer-docs/daos/nns/concepts/proposals/direct-voting.mdx @@ -9,7 +9,7 @@ import '/src/components/CenterImages/center.scss'; -## Overview + The NNS DAO is an open governance system where anyone can become a participant by [staking some ICP in a neuron](https://internetcomputer.org/docs/current/developer-docs/daos/nns/using-the-nns-dapp/nns-app-quickstart#stake-icp-utility-tokens-in-a-neuron). At least 1 ICP is required to create a neuron. Locking tokens for a period of time is known as the neuron's dissolve delay. If a neuron has more than 6 months dissolve delay, it is eligible to participate in voting. This means that it can both submit and vote on proposals. diff --git a/docs/developer-docs/daos/nns/overview.mdx b/docs/developer-docs/daos/nns/overview.mdx index 977e1af59c..740621c9ae 100644 --- a/docs/developer-docs/daos/nns/overview.mdx +++ b/docs/developer-docs/daos/nns/overview.mdx @@ -8,7 +8,7 @@ import { MarkdownChipRow } from "/src/components/Chip/MarkdownChipRow"; -## Overview +

diff --git a/docs/developer-docs/daos/nns/using-the-nns-dapp/nns-app-quickstart.mdx b/docs/developer-docs/daos/nns/using-the-nns-dapp/nns-app-quickstart.mdx index e031bad71e..3bb6c075e6 100644 --- a/docs/developer-docs/daos/nns/using-the-nns-dapp/nns-app-quickstart.mdx +++ b/docs/developer-docs/daos/nns/using-the-nns-dapp/nns-app-quickstart.mdx @@ -9,7 +9,7 @@ import '/src/components/CenterImages/center.scss'; -## Overview + There are different ways to interact with the NNS DAO to participate in governance. diff --git a/docs/developer-docs/daos/nns/using-the-nns-dapp/nns-dapp-additional-features.mdx b/docs/developer-docs/daos/nns/using-the-nns-dapp/nns-dapp-additional-features.mdx index 5df6b6de9f..39becd9bd2 100644 --- a/docs/developer-docs/daos/nns/using-the-nns-dapp/nns-dapp-additional-features.mdx +++ b/docs/developer-docs/daos/nns/using-the-nns-dapp/nns-dapp-additional-features.mdx @@ -10,7 +10,7 @@ import { GlossaryTooltip } from "/src/components/Tooltip/GlossaryTooltip"; -## Overview + In addition to being the portal for interacting with the NNS DAO, the NNS dapp also provides access to the SNS DAOs, their launches, and allows users to manage canisters that they control. This is a brief guide to some of these additional functionalities. diff --git a/docs/developer-docs/daos/nns/using-the-nns-dapp/nns-dapp-advanced-neuron-operations.mdx b/docs/developer-docs/daos/nns/using-the-nns-dapp/nns-dapp-advanced-neuron-operations.mdx index 4ee772d880..d7d0938828 100644 --- a/docs/developer-docs/daos/nns/using-the-nns-dapp/nns-dapp-advanced-neuron-operations.mdx +++ b/docs/developer-docs/daos/nns/using-the-nns-dapp/nns-dapp-advanced-neuron-operations.mdx @@ -9,7 +9,7 @@ import '/src/components/CenterImages/center.scss'; -## Overview + Once you are a bit more familiar with the NNS, you might want to use the NNS dapp to perform additional neuron operations. For more background on neurons, including the concepts of voting rewards and what the different neuron operations do in details, diff --git a/docs/developer-docs/daos/nns/using-the-nns-dapp/nns-dapp-following-other-neurons.mdx b/docs/developer-docs/daos/nns/using-the-nns-dapp/nns-dapp-following-other-neurons.mdx index 486e3e0225..3ed27fba50 100644 --- a/docs/developer-docs/daos/nns/using-the-nns-dapp/nns-dapp-following-other-neurons.mdx +++ b/docs/developer-docs/daos/nns/using-the-nns-dapp/nns-dapp-following-other-neurons.mdx @@ -15,7 +15,7 @@ import '/src/components/CenterImages/center.scss';
-## Overview + Neuron owners may find it hard to manually vote on every proposal submitted to the NNS. For example, they may not have the time or necessary expertise to evaluate each individual proposal. The NNS uses a form of liquid democracy to address these challenges called **following**. diff --git a/docs/developer-docs/daos/nns/using-the-nns-dapp/nns-dapp-importing-tokens.mdx b/docs/developer-docs/daos/nns/using-the-nns-dapp/nns-dapp-importing-tokens.mdx index 71a535021f..0ad634f781 100644 --- a/docs/developer-docs/daos/nns/using-the-nns-dapp/nns-dapp-importing-tokens.mdx +++ b/docs/developer-docs/daos/nns/using-the-nns-dapp/nns-dapp-importing-tokens.mdx @@ -15,7 +15,7 @@ import '/src/components/CenterImages/center.scss';
-## Overview + The NNS dapp focuses on providing a simple user interface where community members can interact with different on-chain governance systems deployed on the Internet Computer. diff --git a/docs/developer-docs/daos/nns/using-the-nns-dapp/nns-dapp-making-neurons-public.mdx b/docs/developer-docs/daos/nns/using-the-nns-dapp/nns-dapp-making-neurons-public.mdx index 75f66ba2c6..65f7055a47 100644 --- a/docs/developer-docs/daos/nns/using-the-nns-dapp/nns-dapp-making-neurons-public.mdx +++ b/docs/developer-docs/daos/nns/using-the-nns-dapp/nns-dapp-making-neurons-public.mdx @@ -9,7 +9,7 @@ import '/src/components/CenterImages/center.scss'; -## Overview + Neuron visibility settings are available in order to support a [neuron index](https://dashboard.internetcomputer.org/proposal/48491) while respecting neuron holders' privacy. A neuron can be private or public. For public neurons, anyone who knows the neuron's ID can see the full neuron's details, including how they vote on proposals. [Learn more about the differences between private and public neurons](/docs/current/developer-docs/daos/nns/concepts/neurons/neuron-management#neuron-visibility). diff --git a/docs/developer-docs/daos/nns/using-the-nns-dapp/nns-dapp-manage-quill-neurons.mdx b/docs/developer-docs/daos/nns/using-the-nns-dapp/nns-dapp-manage-quill-neurons.mdx index a43ef9c84e..2b2bbad661 100644 --- a/docs/developer-docs/daos/nns/using-the-nns-dapp/nns-dapp-manage-quill-neurons.mdx +++ b/docs/developer-docs/daos/nns/using-the-nns-dapp/nns-dapp-manage-quill-neurons.mdx @@ -15,7 +15,7 @@ import '/src/components/CenterImages/center.scss';
-## Overview + You may have neurons controlled by a principal ID that was created using [quill](../../../../../../docs/current/developer-docs/developer-tools/cli-tools/quill-cli-reference/quill-parent). In this case, it may be inconvenient to manage your neurons through the terminal. If you know the seed phrase of this principal ID, you can use a Ledger hardware wallet to manage your neurons through the [NNS dapp](https://nns.ic0.app/). ## How to access neurons controlled by a principal ID created with quill diff --git a/docs/developer-docs/daos/nns/using-the-nns-dapp/nns-dapp-send-and-receive-tokens.mdx b/docs/developer-docs/daos/nns/using-the-nns-dapp/nns-dapp-send-and-receive-tokens.mdx index 88e6e42f3e..c7b9b2ffdc 100644 --- a/docs/developer-docs/daos/nns/using-the-nns-dapp/nns-dapp-send-and-receive-tokens.mdx +++ b/docs/developer-docs/daos/nns/using-the-nns-dapp/nns-dapp-send-and-receive-tokens.mdx @@ -9,7 +9,7 @@ import '/src/components/CenterImages/center.scss'; -## Overview + When you log into the NNS dapp for the first time you will not yet have any ICP tokens in your wallet. Therefore, you first might want transfer some tokens to the NNS dapp wallet. This also the first step required for staking a neuron with the NNS dapp. diff --git a/docs/developer-docs/daos/sns/index.mdx b/docs/developer-docs/daos/sns/index.mdx index 64f6289449..c35b0243e6 100644 --- a/docs/developer-docs/daos/sns/index.mdx +++ b/docs/developer-docs/daos/sns/index.mdx @@ -8,7 +8,7 @@ import { MarkdownChipRow } from "/src/components/Chip/MarkdownChipRow"; -## Overview + These pages introduce instructions needed when considering handing over control of a dapp to a Service Nervous System (SNS) or integrating with an SNS. If this is the first time you hear about the SNS, it is recommended to take a look at the high level [SNS](/sns) diff --git a/docs/developer-docs/daos/sns/launching/integrating.mdx b/docs/developer-docs/daos/sns/launching/integrating.mdx index 7cad7720ff..74fd75ca09 100644 --- a/docs/developer-docs/daos/sns/launching/integrating.mdx +++ b/docs/developer-docs/daos/sns/launching/integrating.mdx @@ -8,7 +8,7 @@ import { MarkdownChipRow } from "/src/components/Chip/MarkdownChipRow"; -## Overview + When planning an SNS launch, one topic to consider is whether and how the SNS functionality should be integrated in the dapp. For example, one may want to embed a frontend for the SNS swap or for the SNS governance in the dapp's UI. diff --git a/docs/developer-docs/daos/sns/launching/launch-steps-1proposal.mdx b/docs/developer-docs/daos/sns/launching/launch-steps-1proposal.mdx index 0f0adbf923..5a267c9baf 100644 --- a/docs/developer-docs/daos/sns/launching/launch-steps-1proposal.mdx +++ b/docs/developer-docs/daos/sns/launching/launch-steps-1proposal.mdx @@ -8,7 +8,7 @@ import { MarkdownChipRow } from "/src/components/Chip/MarkdownChipRow"; -## Overview + At a high level, the stages for launching an SNS in production are explained [here](../launching/launch-summary-1proposal.mdx). diff --git a/docs/developer-docs/daos/sns/launching/launch-summary-1proposal.mdx b/docs/developer-docs/daos/sns/launching/launch-summary-1proposal.mdx index c4a0b8ee93..4f08219e3b 100644 --- a/docs/developer-docs/daos/sns/launching/launch-summary-1proposal.mdx +++ b/docs/developer-docs/daos/sns/launching/launch-summary-1proposal.mdx @@ -8,7 +8,7 @@ import { MarkdownChipRow } from "/src/components/Chip/MarkdownChipRow"; -## Overview + During an SNS launch, a dapp is handed over to the NNS and the NNS both creates the SNS canisters and starts a decentralization swap to decentralize the SNS and thereby the dapp. diff --git a/docs/developer-docs/daos/sns/managing/cycles-usage.mdx b/docs/developer-docs/daos/sns/managing/cycles-usage.mdx index e690f7ed9e..b8d2f937c5 100644 --- a/docs/developer-docs/daos/sns/managing/cycles-usage.mdx +++ b/docs/developer-docs/daos/sns/managing/cycles-usage.mdx @@ -8,7 +8,7 @@ import { MarkdownChipRow } from "/src/components/Chip/MarkdownChipRow"; -## Overview + :::caution An SNS community must ensure that all SNS and dapp canisters have sufficient cycles by manually sending cycles when necessary to diff --git a/docs/developer-docs/daos/sns/managing/making-proposals.mdx b/docs/developer-docs/daos/sns/managing/making-proposals.mdx index a150aeb5cb..e3d3312474 100644 --- a/docs/developer-docs/daos/sns/managing/making-proposals.mdx +++ b/docs/developer-docs/daos/sns/managing/making-proposals.mdx @@ -8,7 +8,7 @@ import { MarkdownChipRow } from "/src/components/Chip/MarkdownChipRow"; -## Overview + To manage an SNS, the SNS community needs to understand how proposals work, how they can be submitted, voted on, and what effect they have. diff --git a/docs/developer-docs/daos/sns/managing/manage-sns-intro.mdx b/docs/developer-docs/daos/sns/managing/manage-sns-intro.mdx index f8bf013e45..645d0ff379 100644 --- a/docs/developer-docs/daos/sns/managing/manage-sns-intro.mdx +++ b/docs/developer-docs/daos/sns/managing/manage-sns-intro.mdx @@ -8,7 +8,7 @@ import { MarkdownChipRow } from "/src/components/Chip/MarkdownChipRow"; -## Overview + SNSs are protocol-provided DAOs on ICP that are to some extent maintained by the NNS community, who for example approve new upgrades of SNS canister code. This eliminates much of the maintenance burden from the SNS communities. diff --git a/docs/developer-docs/daos/sns/managing/managing-nervous-system-parameters.mdx b/docs/developer-docs/daos/sns/managing/managing-nervous-system-parameters.mdx index af1a2b9f35..609982f2fc 100644 --- a/docs/developer-docs/daos/sns/managing/managing-nervous-system-parameters.mdx +++ b/docs/developer-docs/daos/sns/managing/managing-nervous-system-parameters.mdx @@ -9,7 +9,7 @@ import { MarkdownChipRow } from "/src/components/Chip/MarkdownChipRow"; -## Overview + The nervous system parameters define the settings of a particular SNS. diff --git a/docs/developer-docs/daos/sns/managing/sns-asset-canister.mdx b/docs/developer-docs/daos/sns/managing/sns-asset-canister.mdx index 4cd6eb69ea..3103de6511 100644 --- a/docs/developer-docs/daos/sns/managing/sns-asset-canister.mdx +++ b/docs/developer-docs/daos/sns/managing/sns-asset-canister.mdx @@ -8,7 +8,7 @@ import { MarkdownChipRow } from "/src/components/Chip/MarkdownChipRow"; -## Overview + The [asset canister](https://github.com/dfinity/sdk/tree/master/src/canisters/frontend/ic-frontend-canister) provides users with a way to store and retrieve static assets from a canister deployed on ICP. Generally, asset canisters are used to serve HTML, CSS, or JavaScript assets, which are typically part of a dapp's frontend. For this reason, the asset canister is also referred to as the frontend canister. For purposes of this guide, it will be referred to as the asset canister. diff --git a/docs/developer-docs/daos/sns/overview.mdx b/docs/developer-docs/daos/sns/overview.mdx index a1bd0de82c..fafd0bf34d 100644 --- a/docs/developer-docs/daos/sns/overview.mdx +++ b/docs/developer-docs/daos/sns/overview.mdx @@ -4,7 +4,7 @@ keywords: [advanced, governance, concept, sns, introduction] import { MarkdownChipRow } from "/src/components/Chip/MarkdownChipRow"; -# SNS overview +# What is an SNS? diff --git a/docs/developer-docs/daos/sns/testing/testing-locally.mdx b/docs/developer-docs/daos/sns/testing/testing-locally.mdx index c10f7adfa7..d689e3416a 100644 --- a/docs/developer-docs/daos/sns/testing/testing-locally.mdx +++ b/docs/developer-docs/daos/sns/testing/testing-locally.mdx @@ -8,7 +8,7 @@ import { MarkdownChipRow } from "/src/components/Chip/MarkdownChipRow"; -## Overview + To help developers, DFINITY has created the [sns-testing repo](https://github.com/dfinity/sns-testing) which has scripts that help developers test the SNS process. Developers can run a local version of the ICP execution environment on their local machine, deploy their dapp locally and run through [the stages](../launching/launch-summary-1proposal.mdx) of decentralizing their dapp. diff --git a/docs/developer-docs/daos/sns/testing/testing-on-mainnet.mdx b/docs/developer-docs/daos/sns/testing/testing-on-mainnet.mdx index ebd9160026..856eb3e47c 100644 --- a/docs/developer-docs/daos/sns/testing/testing-on-mainnet.mdx +++ b/docs/developer-docs/daos/sns/testing/testing-on-mainnet.mdx @@ -8,7 +8,7 @@ import { MarkdownChipRow } from "/src/components/Chip/MarkdownChipRow"; -## Overview + Once a developer has tested the process of an SNS, it is highly recommended they do an **"SNS testflight" [on the mainnet](./testing-on-mainnet.mdx)**. An SNS testflight is when a developer deploys their dapp (to the mainnet) and hands control of it to a mock SNS (on the mainnet). diff --git a/docs/developer-docs/daos/sns/tokenomics/index.mdx b/docs/developer-docs/daos/sns/tokenomics/index.mdx index 3893719c98..57c6bb184b 100644 --- a/docs/developer-docs/daos/sns/tokenomics/index.mdx +++ b/docs/developer-docs/daos/sns/tokenomics/index.mdx @@ -8,7 +8,7 @@ import { MarkdownChipRow } from "/src/components/Chip/MarkdownChipRow"; -## Overview + Launching an SNS entails many non-technical and technical preparations steps. [The SNS launch checklist](sns-checklist.mdx) summarizes some of the most important preparation diff --git a/docs/developer-docs/daos/sns/tokenomics/predeployment-considerations.mdx b/docs/developer-docs/daos/sns/tokenomics/predeployment-considerations.mdx index 2b3cee79f4..8cd0402d64 100644 --- a/docs/developer-docs/daos/sns/tokenomics/predeployment-considerations.mdx +++ b/docs/developer-docs/daos/sns/tokenomics/predeployment-considerations.mdx @@ -8,7 +8,7 @@ import { MarkdownChipRow } from "/src/components/Chip/MarkdownChipRow"; -## Overview + Preparing an SNS launch includes many non-technical considerations. For example, to decentralize a dapp, the governance control has to be distributed diff --git a/docs/developer-docs/daos/sns/tokenomics/preparation.mdx b/docs/developer-docs/daos/sns/tokenomics/preparation.mdx index ba7b1ce15d..0c3bb39c46 100644 --- a/docs/developer-docs/daos/sns/tokenomics/preparation.mdx +++ b/docs/developer-docs/daos/sns/tokenomics/preparation.mdx @@ -8,7 +8,7 @@ import { MarkdownChipRow } from "/src/components/Chip/MarkdownChipRow"; -## Overview + Typically, one would first decide on tokenomics and other configurations, for examples using the [SNS tokenomics training & tools](https://wiki.internetcomputer.org/wiki/How-To:_SNS_tokenomics_configuration) diff --git a/docs/developer-docs/daos/sns/tokenomics/rewards.mdx b/docs/developer-docs/daos/sns/tokenomics/rewards.mdx index efb46e8064..13372fe764 100644 --- a/docs/developer-docs/daos/sns/tokenomics/rewards.mdx +++ b/docs/developer-docs/daos/sns/tokenomics/rewards.mdx @@ -12,8 +12,6 @@ Each SNS can be individually configured with parameters that define, among other how an SNS uses rewards to incentivize certain behavior for the governance participants and the dapp users. -## Rewards Overview - The goal of this article is to explain the design of the SNS reward scheme. The full potential of tokenization can be unlocked by a tokenized open governance system, diff --git a/docs/developer-docs/daos/sns/tokenomics/tokenomics-intro.mdx b/docs/developer-docs/daos/sns/tokenomics/tokenomics-intro.mdx index 97e40fad8e..6587d9bc95 100644 --- a/docs/developer-docs/daos/sns/tokenomics/tokenomics-intro.mdx +++ b/docs/developer-docs/daos/sns/tokenomics/tokenomics-intro.mdx @@ -14,8 +14,7 @@ Therefore when launching or maintaining an SNS, it is important to understand to The described concepts are also relevant for [other DAOs](../overview#dao-alternatives). -## Tokenomics overview -### What is tokenomics? +## What is tokenomics? A token is a digital asset on a blockchain. Tokenomics describes the economics of a token system on a blockchain. It is a game changer for decentralized autonomous organization (DAOs) compared to traditional apps running on a Web 2.0 infrastructure, because it enables the introduction of new incentive systems and use cases. Tokenizing a DAO allows, for instance, that anyone in the world can purchase tokens and thereby contribute to initial funding for the DAO. Moreover, tokens can be paid to early adopters and active users, which will help attract users. Tokenomics covers a wide range of topics, such as diff --git a/docs/developer-docs/defi/cycles/converting_icp_tokens_into_cycles.mdx b/docs/developer-docs/defi/cycles/converting_icp_tokens_into_cycles.mdx index 3e297f813d..91877872c3 100644 --- a/docs/developer-docs/defi/cycles/converting_icp_tokens_into_cycles.mdx +++ b/docs/developer-docs/defi/cycles/converting_icp_tokens_into_cycles.mdx @@ -11,7 +11,7 @@ import { GlossaryTooltip } from "/src/components/Tooltip/GlossaryTooltip"; -## Overview + To convert ICP tokens into cycles, you first need to obtain some ICP and transfer to the right account. You can get ICP tokens on exchanges, or ask someone you know to send you some. To figure out which account to transfer the ICP tokens to, run the following: ``` bash diff --git a/docs/developer-docs/defi/cycles/cycles-ledger.mdx b/docs/developer-docs/defi/cycles/cycles-ledger.mdx index e0f999489c..229c885a98 100644 --- a/docs/developer-docs/defi/cycles/cycles-ledger.mdx +++ b/docs/developer-docs/defi/cycles/cycles-ledger.mdx @@ -9,7 +9,7 @@ import { GlossaryTooltip } from "/src/components/Tooltip/GlossaryTooltip"; -## Overview + When developing and deploying canisters on the Internet Computer, developers need to have cycles to pay for the resources used by their canisters. The **cycles ledger** canister has been developed as an alternative to the **cycles wallet** canister for cycles management. diff --git a/docs/developer-docs/defi/cycles/cycles-wallet.mdx b/docs/developer-docs/defi/cycles/cycles-wallet.mdx index 87a85fc74d..b090efca67 100644 --- a/docs/developer-docs/defi/cycles/cycles-wallet.mdx +++ b/docs/developer-docs/defi/cycles/cycles-wallet.mdx @@ -9,7 +9,7 @@ import { GlossaryTooltip } from "/src/components/Tooltip/GlossaryTooltip"; -## Overview + As discussed in [tokens and cycles](/docs/current/developer-docs/getting-started/tokens-and-cycles), ICP tokens can be converted into **cycles** to power canister operations. Cycles reflect the operational cost of communication, computation, and storage that dapps consume. diff --git a/docs/developer-docs/defi/dex/overview.mdx b/docs/developer-docs/defi/dex/overview.mdx index 1e63f6763d..0d18601552 100644 --- a/docs/developer-docs/defi/dex/overview.mdx +++ b/docs/developer-docs/defi/dex/overview.mdx @@ -4,7 +4,7 @@ keywords: [intermediate, defi, overview, dex, decentralized exchange, exchange] import { MarkdownChipRow } from "/src/components/Chip/MarkdownChipRow"; -# Decentralized exchange overview +# Decentralized exchanges diff --git a/docs/developer-docs/defi/exchange-rate-canister.mdx b/docs/developer-docs/defi/exchange-rate-canister.mdx index d927cacba5..f229fe57f4 100644 --- a/docs/developer-docs/defi/exchange-rate-canister.mdx +++ b/docs/developer-docs/defi/exchange-rate-canister.mdx @@ -9,7 +9,7 @@ import { GlossaryTooltip } from "/src/components/Tooltip/GlossaryTooltip"; -## Overview + The exchange rate canister, referred to as the XRC, is a canister that runs on the **uzr34 system subnet**. The XRC uses [HTTPS outcalls](https://internetcomputer.org/https-outcalls/) to fetch data from major cryptocurrency exchanges by using the exchange's public API to retrieve real time or historical cryptocurrency pricing information. The XRC also queries the public APIs for foreign exchange data providers around the world periodically in order to get forex rates. diff --git a/docs/developer-docs/defi/icp-tokens/account-trimming.mdx b/docs/developer-docs/defi/icp-tokens/account-trimming.mdx index 8dbace8a12..e818485f09 100644 --- a/docs/developer-docs/defi/icp-tokens/account-trimming.mdx +++ b/docs/developer-docs/defi/icp-tokens/account-trimming.mdx @@ -10,7 +10,7 @@ import { GlossaryTooltip } from "/src/components/Tooltip/GlossaryTooltip"; -## Overview + Even if the ledger can index a large number of accounts, it has a finite capacity. To avoid saturation and maintain good performance, some accounts are trimmed if the ledger capacity is reaching a threshold. diff --git a/docs/developer-docs/defi/nfts/marketplaces.mdx b/docs/developer-docs/defi/nfts/marketplaces.mdx index 1668efe77f..48dfc204c7 100644 --- a/docs/developer-docs/defi/nfts/marketplaces.mdx +++ b/docs/developer-docs/defi/nfts/marketplaces.mdx @@ -8,7 +8,7 @@ import { MarkdownChipRow } from "/src/components/Chip/MarkdownChipRow"; -## Overview + An NFT marketplace is a dapp used to mint, buy, sell, and trade NFTs. An NFT listed on a marketplace may be part of a large collection, or it may be a one-of-a-kind token. diff --git a/docs/developer-docs/defi/nfts/nft-collections.mdx b/docs/developer-docs/defi/nfts/nft-collections.mdx index 5221c6168c..a7532da87d 100644 --- a/docs/developer-docs/defi/nfts/nft-collections.mdx +++ b/docs/developer-docs/defi/nfts/nft-collections.mdx @@ -9,7 +9,7 @@ import { GlossaryTooltip } from "/src/components/Tooltip/GlossaryTooltip"; -## Overview + An NFT collection is a series of non-fungible tokens that each have a unique identifier value. Each token's metadata may be the same, such as the name, image, and description, or each token's data can be unique and associated with a 'rarity' value, where some metadata values are less common than others. Rarity metadata attributes are common in generative NFT collections, often referring to an NFT collection where the artwork for each image has been randomly generated and some components only appear in a select few of the generated images. diff --git a/docs/developer-docs/defi/nfts/overview.mdx b/docs/developer-docs/defi/nfts/overview.mdx index 3bb2682546..fd23311933 100644 --- a/docs/developer-docs/defi/nfts/overview.mdx +++ b/docs/developer-docs/defi/nfts/overview.mdx @@ -5,7 +5,7 @@ keywords: [intermediate, concept, nfts] import { MarkdownChipRow } from "/src/components/Chip/MarkdownChipRow"; import { GlossaryTooltip } from "/src/components/Tooltip/GlossaryTooltip"; -# NFT overview +# NFTs diff --git a/docs/developer-docs/defi/overview.mdx b/docs/developer-docs/defi/overview.mdx index 2a1948a148..d85612aefa 100644 --- a/docs/developer-docs/defi/overview.mdx +++ b/docs/developer-docs/defi/overview.mdx @@ -5,7 +5,7 @@ keywords: [intermediate, defi, overview, tokens, icrc-1, icrc ledger, icrc index import { MarkdownChipRow } from "/src/components/Chip/MarkdownChipRow"; import { GlossaryTooltip } from "/src/components/Tooltip/GlossaryTooltip"; -# Digital assets overview +# Digital assets diff --git a/docs/developer-docs/defi/rosetta/icp_rosetta/construction_api/index.mdx b/docs/developer-docs/defi/rosetta/icp_rosetta/construction_api/index.mdx index 44e9b6a572..bb0cf4c966 100644 --- a/docs/developer-docs/defi/rosetta/icp_rosetta/construction_api/index.mdx +++ b/docs/developer-docs/defi/rosetta/icp_rosetta/construction_api/index.mdx @@ -8,7 +8,7 @@ import { MarkdownChipRow } from "/src/components/Chip/MarkdownChipRow"; -## Overview + This section will give you an overview of how you can make transactions via Rosetta using the construction API. diff --git a/docs/developer-docs/defi/rosetta/icp_rosetta/construction_api/operations_flow/combine.mdx b/docs/developer-docs/defi/rosetta/icp_rosetta/construction_api/operations_flow/combine.mdx index f187db0660..d243ffc9d7 100644 --- a/docs/developer-docs/defi/rosetta/icp_rosetta/construction_api/operations_flow/combine.mdx +++ b/docs/developer-docs/defi/rosetta/icp_rosetta/construction_api/operations_flow/combine.mdx @@ -8,7 +8,7 @@ import { MarkdownChipRow } from "/src/components/Chip/MarkdownChipRow"; -## Overview + This section details how to call the `construction/combine` endpoint of the Rosetta construction API. The request and response types can be found in the [official documentation](https://docs.cdp.coinbase.com/mesh/reference/constructioncombine). diff --git a/docs/developer-docs/defi/rosetta/icp_rosetta/construction_api/operations_flow/derive.mdx b/docs/developer-docs/defi/rosetta/icp_rosetta/construction_api/operations_flow/derive.mdx index bfce2cbe33..1d5bd72e4a 100644 --- a/docs/developer-docs/defi/rosetta/icp_rosetta/construction_api/operations_flow/derive.mdx +++ b/docs/developer-docs/defi/rosetta/icp_rosetta/construction_api/operations_flow/derive.mdx @@ -8,7 +8,7 @@ import { MarkdownChipRow } from "/src/components/Chip/MarkdownChipRow"; -## Overview + This section details how to derive an ICP adress using the Rosetta construction API. The ICP ledger is using `accountidentifiers` to represent public keys internally. To derive an `accountidentifier` from a public key the Rosetta API offers the `construction/derive` endpoint. diff --git a/docs/developer-docs/defi/rosetta/icp_rosetta/construction_api/operations_flow/index.mdx b/docs/developer-docs/defi/rosetta/icp_rosetta/construction_api/operations_flow/index.mdx index 34588637e8..3403168a8e 100644 --- a/docs/developer-docs/defi/rosetta/icp_rosetta/construction_api/operations_flow/index.mdx +++ b/docs/developer-docs/defi/rosetta/icp_rosetta/construction_api/operations_flow/index.mdx @@ -7,7 +7,7 @@ import { MarkdownChipRow } from "/src/components/Chip/MarkdownChipRow"; # Flow of operations -## Overview + This section will give you an overview of how the flow of operations in the construction API works. It will guide you through each of the necessary endpoints that you will have to call in order to post a valid transaction with your signature to the ICP ledger. As an example of such a transaction this guide will use a simple transfer between accounts. It is recommended to first read through the interactions of each endpoint to acquire an understanding of how the flow of operations works. Although the example of transferring tokens is only one use case of the construction API of Rosetta, it serves as a good example on what to expect from the interaction with the Construction-API. The other functionalities that are supported by ICP Rosetta through the construction API follow a similar flow of operations. diff --git a/docs/developer-docs/defi/rosetta/icp_rosetta/construction_api/operations_flow/metadata.mdx b/docs/developer-docs/defi/rosetta/icp_rosetta/construction_api/operations_flow/metadata.mdx index fd32ac9d2d..e66c154d46 100644 --- a/docs/developer-docs/defi/rosetta/icp_rosetta/construction_api/operations_flow/metadata.mdx +++ b/docs/developer-docs/defi/rosetta/icp_rosetta/construction_api/operations_flow/metadata.mdx @@ -7,7 +7,7 @@ import { MarkdownChipRow } from "/src/components/Chip/MarkdownChipRow"; -## Overview + This section details how to call the `construction/metadata` endpoint of the Rosetta construction API. The request and response types can be found in the [official documentation](https://docs.cdp.coinbase.com/rosetta/reference/constructionmetadata). diff --git a/docs/developer-docs/defi/rosetta/icp_rosetta/construction_api/operations_flow/payloads.mdx b/docs/developer-docs/defi/rosetta/icp_rosetta/construction_api/operations_flow/payloads.mdx index 9cf32167b4..1054fac4ad 100644 --- a/docs/developer-docs/defi/rosetta/icp_rosetta/construction_api/operations_flow/payloads.mdx +++ b/docs/developer-docs/defi/rosetta/icp_rosetta/construction_api/operations_flow/payloads.mdx @@ -8,7 +8,7 @@ import { MarkdownChipRow } from "/src/components/Chip/MarkdownChipRow"; -## Overview + This section details how to call the `construction/payloads` endpoint of the Rosetta construction API. The request and response types can be found in the [official documentation](https://docs.cdp.coinbase.com/mesh/reference/constructionpayloads). diff --git a/docs/developer-docs/defi/rosetta/icp_rosetta/construction_api/operations_flow/preprocess.mdx b/docs/developer-docs/defi/rosetta/icp_rosetta/construction_api/operations_flow/preprocess.mdx index 32edf9451a..a54445bff8 100644 --- a/docs/developer-docs/defi/rosetta/icp_rosetta/construction_api/operations_flow/preprocess.mdx +++ b/docs/developer-docs/defi/rosetta/icp_rosetta/construction_api/operations_flow/preprocess.mdx @@ -7,7 +7,7 @@ import { MarkdownChipRow } from "/src/components/Chip/MarkdownChipRow"; -## Overview + This section details how to call the `construction/preprocess` endpoint of the Rosetta construction API. Preprocess is called prior to `/construction/payloads` to construct a request for any metadata that is needed for transaction construction. The ICP Rosetta implementation will return the required list of public keys that has to be provided by the user and in the metadata it returns the request type that is associated with the given set of operations. The metadata returned from this endpoint will be sent to the `/construction/metadata` endpoint UNMODIFIED by the caller (in an offline execution environment). diff --git a/docs/developer-docs/defi/rosetta/icp_rosetta/construction_api/operations_flow/submit.mdx b/docs/developer-docs/defi/rosetta/icp_rosetta/construction_api/operations_flow/submit.mdx index 8acd3a81b6..b73d28b518 100644 --- a/docs/developer-docs/defi/rosetta/icp_rosetta/construction_api/operations_flow/submit.mdx +++ b/docs/developer-docs/defi/rosetta/icp_rosetta/construction_api/operations_flow/submit.mdx @@ -8,7 +8,7 @@ import { MarkdownChipRow } from "/src/components/Chip/MarkdownChipRow"; -## Overview + This section details how to call the `construction/submit` endpoint of the Rosetta construction API. The request and response types can be found in the [official documentation](https://docs.cdp.coinbase.com/mesh/reference/constructionsubmit). The endpoint sends to transactions to the IC. The first being the `Call Request` which contains the information of what submit, which canister, what function in the canister and with what arguments should be called. diff --git a/docs/developer-docs/defi/rosetta/icp_rosetta/construction_api/staking/change_auto_stake_maturity.mdx b/docs/developer-docs/defi/rosetta/icp_rosetta/construction_api/staking/change_auto_stake_maturity.mdx index 4960214427..2b09e8c055 100644 --- a/docs/developer-docs/defi/rosetta/icp_rosetta/construction_api/staking/change_auto_stake_maturity.mdx +++ b/docs/developer-docs/defi/rosetta/icp_rosetta/construction_api/staking/change_auto_stake_maturity.mdx @@ -8,7 +8,7 @@ import { MarkdownChipRow } from "/src/components/Chip/MarkdownChipRow"; -## Overview + | | | |----------------------|--------| | Since version | 1.7.0 | diff --git a/docs/developer-docs/defi/rosetta/icp_rosetta/construction_api/staking/derive_neuron_id.mdx b/docs/developer-docs/defi/rosetta/icp_rosetta/construction_api/staking/derive_neuron_id.mdx index 5a5d191ed7..7f8658201f 100644 --- a/docs/developer-docs/defi/rosetta/icp_rosetta/construction_api/staking/derive_neuron_id.mdx +++ b/docs/developer-docs/defi/rosetta/icp_rosetta/construction_api/staking/derive_neuron_id.mdx @@ -8,7 +8,7 @@ import { MarkdownChipRow } from "/src/components/Chip/MarkdownChipRow"; -## Overview + | | | |---------------|-------| diff --git a/docs/developer-docs/defi/rosetta/icp_rosetta/construction_api/staking/disburse.mdx b/docs/developer-docs/defi/rosetta/icp_rosetta/construction_api/staking/disburse.mdx index 87fb2d7a2c..e259f5b653 100644 --- a/docs/developer-docs/defi/rosetta/icp_rosetta/construction_api/staking/disburse.mdx +++ b/docs/developer-docs/defi/rosetta/icp_rosetta/construction_api/staking/disburse.mdx @@ -8,7 +8,7 @@ import { MarkdownChipRow } from "/src/components/Chip/MarkdownChipRow"; -## Overview + | | | |----------------------|--------| | Since version | 1.4.0 | diff --git a/docs/developer-docs/defi/rosetta/icp_rosetta/construction_api/staking/dissolve.mdx b/docs/developer-docs/defi/rosetta/icp_rosetta/construction_api/staking/dissolve.mdx index f26bd609c9..08bd401ed7 100644 --- a/docs/developer-docs/defi/rosetta/icp_rosetta/construction_api/staking/dissolve.mdx +++ b/docs/developer-docs/defi/rosetta/icp_rosetta/construction_api/staking/dissolve.mdx @@ -8,7 +8,7 @@ import { MarkdownChipRow } from "/src/components/Chip/MarkdownChipRow"; -## Overview + | | | |----------------------|------------| | Since version | 1.1.0 | diff --git a/docs/developer-docs/defi/rosetta/icp_rosetta/construction_api/staking/hotkeys.mdx b/docs/developer-docs/defi/rosetta/icp_rosetta/construction_api/staking/hotkeys.mdx index f0f8e39375..2afd0c5335 100644 --- a/docs/developer-docs/defi/rosetta/icp_rosetta/construction_api/staking/hotkeys.mdx +++ b/docs/developer-docs/defi/rosetta/icp_rosetta/construction_api/staking/hotkeys.mdx @@ -9,7 +9,7 @@ import { MarkdownChipRow } from "/src/components/Chip/MarkdownChipRow"; -## Overview + This section will explain how to generate a hotkey for neuron management and add or remove hotkeys to your neuron using ICP Rosetta. The recommended way to get hotkeys is to programmatically generate them using the same process used in the public `ic` repository. diff --git a/docs/developer-docs/defi/rosetta/icp_rosetta/construction_api/staking/index.mdx b/docs/developer-docs/defi/rosetta/icp_rosetta/construction_api/staking/index.mdx index f3ad3dbc0a..8f0503ebb1 100644 --- a/docs/developer-docs/defi/rosetta/icp_rosetta/construction_api/staking/index.mdx +++ b/docs/developer-docs/defi/rosetta/icp_rosetta/construction_api/staking/index.mdx @@ -8,7 +8,7 @@ import { MarkdownChipRow } from "/src/components/Chip/MarkdownChipRow"; -## Overview + This section will give you an overview of how how ICP staking on the Internet Computer using Rosetta works. diff --git a/docs/developer-docs/defi/rosetta/icp_rosetta/construction_api/staking/lock_neuron.mdx b/docs/developer-docs/defi/rosetta/icp_rosetta/construction_api/staking/lock_neuron.mdx index 4d6aefb5cd..425cd91928 100644 --- a/docs/developer-docs/defi/rosetta/icp_rosetta/construction_api/staking/lock_neuron.mdx +++ b/docs/developer-docs/defi/rosetta/icp_rosetta/construction_api/staking/lock_neuron.mdx @@ -8,7 +8,7 @@ import { MarkdownChipRow } from "/src/components/Chip/MarkdownChipRow"; -## Overview + | | | |----------------------|------------| | Since version | 1.1.0 | diff --git a/docs/developer-docs/defi/rosetta/icp_rosetta/construction_api/staking/neuron_info.mdx b/docs/developer-docs/defi/rosetta/icp_rosetta/construction_api/staking/neuron_info.mdx index bbd754d1b6..c3de3c3895 100644 --- a/docs/developer-docs/defi/rosetta/icp_rosetta/construction_api/staking/neuron_info.mdx +++ b/docs/developer-docs/defi/rosetta/icp_rosetta/construction_api/staking/neuron_info.mdx @@ -8,7 +8,7 @@ import { MarkdownChipRow } from "/src/components/Chip/MarkdownChipRow"; -## Overview + | | | |----------------------|--------| | Since version | 1.5.0 | diff --git a/docs/developer-docs/defi/rosetta/icp_rosetta/construction_api/staking/spawn.mdx b/docs/developer-docs/defi/rosetta/icp_rosetta/construction_api/staking/spawn.mdx index 8f5a2ab87e..cc9ef429ae 100644 --- a/docs/developer-docs/defi/rosetta/icp_rosetta/construction_api/staking/spawn.mdx +++ b/docs/developer-docs/defi/rosetta/icp_rosetta/construction_api/staking/spawn.mdx @@ -8,7 +8,7 @@ import { MarkdownChipRow } from "/src/components/Chip/MarkdownChipRow"; -## Overview + | | | |----------------------|------------| | Since version | 1.3.0 | diff --git a/docs/developer-docs/defi/rosetta/icp_rosetta/construction_api/staking/stake_icp.mdx b/docs/developer-docs/defi/rosetta/icp_rosetta/construction_api/staking/stake_icp.mdx index 7d0c147bfa..ed4b016813 100644 --- a/docs/developer-docs/defi/rosetta/icp_rosetta/construction_api/staking/stake_icp.mdx +++ b/docs/developer-docs/defi/rosetta/icp_rosetta/construction_api/staking/stake_icp.mdx @@ -8,7 +8,7 @@ import { MarkdownChipRow } from "/src/components/Chip/MarkdownChipRow"; -## Overview + | | | |---------------|-------| | Since version | 1.5.0 | diff --git a/docs/developer-docs/defi/rosetta/icp_rosetta/construction_api/staking/stake_maturity.mdx b/docs/developer-docs/defi/rosetta/icp_rosetta/construction_api/staking/stake_maturity.mdx index 9ce5651750..b78b069d89 100644 --- a/docs/developer-docs/defi/rosetta/icp_rosetta/construction_api/staking/stake_maturity.mdx +++ b/docs/developer-docs/defi/rosetta/icp_rosetta/construction_api/staking/stake_maturity.mdx @@ -8,7 +8,7 @@ import { MarkdownChipRow } from "/src/components/Chip/MarkdownChipRow"; -## Overview + | | | |----------------------|------------| | Since version | 1.4.0 | diff --git a/docs/developer-docs/defi/rosetta/icp_rosetta/construction_api/voting/follow.mdx b/docs/developer-docs/defi/rosetta/icp_rosetta/construction_api/voting/follow.mdx index 2e5272c9ca..9ad9693c68 100644 --- a/docs/developer-docs/defi/rosetta/icp_rosetta/construction_api/voting/follow.mdx +++ b/docs/developer-docs/defi/rosetta/icp_rosetta/construction_api/voting/follow.mdx @@ -8,7 +8,7 @@ import { MarkdownChipRow } from "/src/components/Chip/MarkdownChipRow"; -## Overview + | | | |----------------------|------------| | Since version | 1.5.0 | diff --git a/docs/developer-docs/defi/rosetta/icp_rosetta/construction_api/voting/index.mdx b/docs/developer-docs/defi/rosetta/icp_rosetta/construction_api/voting/index.mdx index 893f8dcf6e..5b73531469 100644 --- a/docs/developer-docs/defi/rosetta/icp_rosetta/construction_api/voting/index.mdx +++ b/docs/developer-docs/defi/rosetta/icp_rosetta/construction_api/voting/index.mdx @@ -8,7 +8,7 @@ import { MarkdownChipRow } from "/src/components/Chip/MarkdownChipRow"; -## Overview + This section will give you an overview of how to vote on NNS proposals using Rosetta. diff --git a/docs/developer-docs/defi/rosetta/icp_rosetta/construction_api/voting/vote.mdx b/docs/developer-docs/defi/rosetta/icp_rosetta/construction_api/voting/vote.mdx index c6a752ace5..9bf836cb6b 100644 --- a/docs/developer-docs/defi/rosetta/icp_rosetta/construction_api/voting/vote.mdx +++ b/docs/developer-docs/defi/rosetta/icp_rosetta/construction_api/voting/vote.mdx @@ -8,7 +8,7 @@ import { MarkdownChipRow } from "/src/components/Chip/MarkdownChipRow"; -## Overview + | | | |----------------------|--------| | Since version | 1.7.0 | diff --git a/docs/developer-docs/defi/rosetta/icp_rosetta/data_api/balances.mdx b/docs/developer-docs/defi/rosetta/icp_rosetta/data_api/balances.mdx index d4e2be420b..a6f4ad0ffa 100644 --- a/docs/developer-docs/defi/rosetta/icp_rosetta/data_api/balances.mdx +++ b/docs/developer-docs/defi/rosetta/icp_rosetta/data_api/balances.mdx @@ -8,7 +8,7 @@ import { MarkdownChipRow } from "/src/components/Chip/MarkdownChipRow"; -## Overview + This endpoint allows you to fetch the balances for a certain account. It is the implementation of the [/account/balance endpoint](https://www.rosetta-api.org/docs/AccountApi.html#accountbalance) of the Rosetta API standard. ### Prerequisites diff --git a/docs/developer-docs/defi/rosetta/icp_rosetta/data_api/blocks.mdx b/docs/developer-docs/defi/rosetta/icp_rosetta/data_api/blocks.mdx index 2e953bc8f3..b6c16891d0 100644 --- a/docs/developer-docs/defi/rosetta/icp_rosetta/data_api/blocks.mdx +++ b/docs/developer-docs/defi/rosetta/icp_rosetta/data_api/blocks.mdx @@ -8,7 +8,7 @@ import { MarkdownChipRow } from "/src/components/Chip/MarkdownChipRow"; -## Overview + This endpoint allows you to fetch blocks at a certain block height. It is the implementation of the [/block endpoint](https://docs.cdp.coinbase.com/mesh/reference/block) of the Rosetta API standard. ### Prerequisites diff --git a/docs/developer-docs/defi/rosetta/icp_rosetta/data_api/get_pending_proposals.mdx b/docs/developer-docs/defi/rosetta/icp_rosetta/data_api/get_pending_proposals.mdx index fe9296ee38..83c4fdee1f 100644 --- a/docs/developer-docs/defi/rosetta/icp_rosetta/data_api/get_pending_proposals.mdx +++ b/docs/developer-docs/defi/rosetta/icp_rosetta/data_api/get_pending_proposals.mdx @@ -8,7 +8,7 @@ import { MarkdownChipRow } from "/src/components/Chip/MarkdownChipRow"; -## Overview + This endpoint allows you to fetch all pending proposals from the NNS. It is the implementation of the [/call endpoint](https://docs.cdp.coinbase.com/mesh/reference/call) of the Rosetta API standard. The call endpoint is very flexible as to what it can be used for. In the case of ICP Rosetta it is used to fetch various custom information that is not covered by the Rosetta API standard. ### Prerequisites diff --git a/docs/developer-docs/defi/rosetta/icp_rosetta/data_api/get_proposal_info.mdx b/docs/developer-docs/defi/rosetta/icp_rosetta/data_api/get_proposal_info.mdx index aaefc01510..f420e7ead1 100644 --- a/docs/developer-docs/defi/rosetta/icp_rosetta/data_api/get_proposal_info.mdx +++ b/docs/developer-docs/defi/rosetta/icp_rosetta/data_api/get_proposal_info.mdx @@ -8,7 +8,7 @@ import { MarkdownChipRow } from "/src/components/Chip/MarkdownChipRow"; -## Overview + This endpoint allows you to fetch more detailed information about a specific proposal from the NNS. It is the implementation of the [/call endpoint](https://docs.cdp.coinbase.com/mesh/reference//call) of the Rosetta API standard. The call endpoint is very flexible as to what it can be used for. In the case of ICP Rosetta it is used to fetch various custom information that is not covered by the Rosetta API standard. diff --git a/docs/developer-docs/defi/rosetta/icp_rosetta/data_api/index.mdx b/docs/developer-docs/defi/rosetta/icp_rosetta/data_api/index.mdx index 296a3d5751..1f9524028a 100644 --- a/docs/developer-docs/defi/rosetta/icp_rosetta/data_api/index.mdx +++ b/docs/developer-docs/defi/rosetta/icp_rosetta/data_api/index.mdx @@ -8,7 +8,7 @@ import { MarkdownChipRow } from "/src/components/Chip/MarkdownChipRow"; -## Overview + This section will give you an overview of what data can be fetched from the data API endpoints for the ICP Rosetta implementation. diff --git a/docs/developer-docs/defi/rosetta/icp_rosetta/data_api/list_known_neurons.mdx b/docs/developer-docs/defi/rosetta/icp_rosetta/data_api/list_known_neurons.mdx index d6589cc17c..3e1e9418cd 100644 --- a/docs/developer-docs/defi/rosetta/icp_rosetta/data_api/list_known_neurons.mdx +++ b/docs/developer-docs/defi/rosetta/icp_rosetta/data_api/list_known_neurons.mdx @@ -8,7 +8,7 @@ import { MarkdownChipRow } from "/src/components/Chip/MarkdownChipRow"; -## Overview + This endpoint allows you to fetch all neurons from the NNS that are publicly known. It is the implementation of the [/call endpoint](https://docs.cdp.coinbase.com/mesh/reference/call) of the Rosetta API standard. The call endpoint is very flexible as to what it can be used for. In the case of ICP Rosetta it is used to fetch various custom information that is not covered by the Rosetta API standard. ### Prerequisites diff --git a/docs/developer-docs/defi/rosetta/icp_rosetta/data_api/network.mdx b/docs/developer-docs/defi/rosetta/icp_rosetta/data_api/network.mdx index 0f3f5879ee..7191446987 100644 --- a/docs/developer-docs/defi/rosetta/icp_rosetta/data_api/network.mdx +++ b/docs/developer-docs/defi/rosetta/icp_rosetta/data_api/network.mdx @@ -8,7 +8,7 @@ import { MarkdownChipRow } from "/src/components/Chip/MarkdownChipRow"; -## Overview + For most endpoints you will require some information about the network represented as a [NetworkIdentifier](https://www.rosetta-api.org/docs/models/NetworkIdentifier.html). diff --git a/docs/developer-docs/defi/rosetta/icp_rosetta/data_api/transactions.mdx b/docs/developer-docs/defi/rosetta/icp_rosetta/data_api/transactions.mdx index acf376c491..dd035ccd8e 100644 --- a/docs/developer-docs/defi/rosetta/icp_rosetta/data_api/transactions.mdx +++ b/docs/developer-docs/defi/rosetta/icp_rosetta/data_api/transactions.mdx @@ -8,7 +8,7 @@ import { MarkdownChipRow } from "/src/components/Chip/MarkdownChipRow"; -## Overview + There exist two different entpoints that allow for querying of transaction. This endpoint allows you to fetch a transaction at a certain block height. It is the implementation of the [/block/transaction endpoint](https://docs.cdp.coinbase.com/mesh/reference/blocktransaction) of the Rosetta API standard. The `search_transactions` endpoint allows you to query for transactions given a set of parameters. It is the implementation of the [/search/transactions endpoint](https://docs.cdp.coinbase.com/mesh/reference/searchtransactions/) diff --git a/docs/developer-docs/defi/rosetta/icp_rosetta/index.mdx b/docs/developer-docs/defi/rosetta/icp_rosetta/index.mdx index 5ad4ea9987..9db2b9456d 100644 --- a/docs/developer-docs/defi/rosetta/icp_rosetta/index.mdx +++ b/docs/developer-docs/defi/rosetta/icp_rosetta/index.mdx @@ -4,7 +4,7 @@ keywords: [intermediate, rosetta, tutorial, approve, icrc, rosetta] import { MarkdownChipRow } from "/src/components/Chip/MarkdownChipRow"; -# Overview +# What is ICP Rosetta? diff --git a/docs/developer-docs/defi/rosetta/icrc_rosetta/construction_api/asset_transfer/approve.mdx b/docs/developer-docs/defi/rosetta/icrc_rosetta/construction_api/asset_transfer/approve.mdx index c9ac7b5f5a..bcfb5143cf 100644 --- a/docs/developer-docs/defi/rosetta/icrc_rosetta/construction_api/asset_transfer/approve.mdx +++ b/docs/developer-docs/defi/rosetta/icrc_rosetta/construction_api/asset_transfer/approve.mdx @@ -8,7 +8,7 @@ import { MarkdownChipRow } from "/src/components/Chip/MarkdownChipRow"; -## Overview + This section will show you how to use the ICRC Rosetta implementation to authorize a spender to spend your ICRC-1 tokens. Make sure you are familiar with the [flow of operations](/docs/developer-docs/defi/rosetta/icp_rosetta/construction_api/operations_flow/index.mdx) for Rosetta. The request types used for making direct transfers are `APPROVE` and `SPENDER`. They consist of two operations, one for the the approve operation and another for the spender operation. diff --git a/docs/developer-docs/defi/rosetta/icrc_rosetta/construction_api/asset_transfer/index.mdx b/docs/developer-docs/defi/rosetta/icrc_rosetta/construction_api/asset_transfer/index.mdx index e33894c31b..55eaee69f2 100644 --- a/docs/developer-docs/defi/rosetta/icrc_rosetta/construction_api/asset_transfer/index.mdx +++ b/docs/developer-docs/defi/rosetta/icrc_rosetta/construction_api/asset_transfer/index.mdx @@ -8,7 +8,7 @@ import { MarkdownChipRow } from "/src/components/Chip/MarkdownChipRow"; -## Overview + This section will give you an overview on what types of asset transfers are supported by ICRC Rosetta and how to use them. It is divided in the following topics: diff --git a/docs/developer-docs/defi/rosetta/icrc_rosetta/construction_api/asset_transfer/transfer.mdx b/docs/developer-docs/defi/rosetta/icrc_rosetta/construction_api/asset_transfer/transfer.mdx index 58557a377f..2b9f07588f 100644 --- a/docs/developer-docs/defi/rosetta/icrc_rosetta/construction_api/asset_transfer/transfer.mdx +++ b/docs/developer-docs/defi/rosetta/icrc_rosetta/construction_api/asset_transfer/transfer.mdx @@ -8,7 +8,7 @@ import { MarkdownChipRow } from "/src/components/Chip/MarkdownChipRow"; -## Overview + The request type that is used for making direct transfers is `TRANSFER`. In the simplest form it consists of two operations, one for the debit operation and one for the credit operation. diff --git a/docs/developer-docs/defi/rosetta/icrc_rosetta/construction_api/index.mdx b/docs/developer-docs/defi/rosetta/icrc_rosetta/construction_api/index.mdx index 0f3a511218..75cad51ffe 100644 --- a/docs/developer-docs/defi/rosetta/icrc_rosetta/construction_api/index.mdx +++ b/docs/developer-docs/defi/rosetta/icrc_rosetta/construction_api/index.mdx @@ -8,7 +8,7 @@ import { MarkdownChipRow } from "/src/components/Chip/MarkdownChipRow"; -## Overview + The construction API allows for offline signing of transactions and then posting them on ICP at a later point in time. It is recommended to first go through [flow of operations](/docs/developer-docs/defi/rosetta/icp_rosetta/construction_api/operations_flow/index.mdx) of the construction API to gain an understanding of how it works, what endpoints to call with what parameters, and where the user has to take action upon receiving certain responses. diff --git a/docs/developer-docs/defi/rosetta/icrc_rosetta/data_api/balances.mdx b/docs/developer-docs/defi/rosetta/icrc_rosetta/data_api/balances.mdx index 27b0f1bd4f..4a6653b8a9 100644 --- a/docs/developer-docs/defi/rosetta/icrc_rosetta/data_api/balances.mdx +++ b/docs/developer-docs/defi/rosetta/icrc_rosetta/data_api/balances.mdx @@ -8,7 +8,7 @@ import { MarkdownChipRow } from "/src/components/Chip/MarkdownChipRow"; -## Overview + The `account_balance` endpoint allows you to fetch the balances for a certain account. It is the implementation of the [/account/balance endpoint](https://www.rosetta-api.org/docs/AccountApi.html#accountbalance) of the Rosetta API standard. diff --git a/docs/developer-docs/defi/rosetta/icrc_rosetta/data_api/blocks.mdx b/docs/developer-docs/defi/rosetta/icrc_rosetta/data_api/blocks.mdx index b1bc114a92..896d891e38 100644 --- a/docs/developer-docs/defi/rosetta/icrc_rosetta/data_api/blocks.mdx +++ b/docs/developer-docs/defi/rosetta/icrc_rosetta/data_api/blocks.mdx @@ -7,7 +7,7 @@ import { MarkdownChipRow } from "/src/components/Chip/MarkdownChipRow"; # Fetch blocks -## Overview + The `block` endpoint allows you to fetch blocks at a certain block height. It is the implementation of the [/block endpoint](https://docs.cdp.coinbase.com/mesh/reference/block) of the Rosetta API standard. ### Prerequisites diff --git a/docs/developer-docs/defi/rosetta/icrc_rosetta/data_api/index.mdx b/docs/developer-docs/defi/rosetta/icrc_rosetta/data_api/index.mdx index 6e6cd474fa..8e60a7853d 100644 --- a/docs/developer-docs/defi/rosetta/icrc_rosetta/data_api/index.mdx +++ b/docs/developer-docs/defi/rosetta/icrc_rosetta/data_api/index.mdx @@ -8,7 +8,7 @@ import { MarkdownChipRow } from "/src/components/Chip/MarkdownChipRow"; -## Overview + The following data can be fetched from the data API endpoints for the ICRC Rosetta implementation: - [Network](/docs/developer-docs/defi/rosetta/icrc_rosetta/data_api/network.mdx): Fetch network specific information, such as the most recent block and what network Rosetta is connected to. diff --git a/docs/developer-docs/defi/rosetta/icrc_rosetta/data_api/network.mdx b/docs/developer-docs/defi/rosetta/icrc_rosetta/data_api/network.mdx index 0090db1f9f..fa3d48d454 100644 --- a/docs/developer-docs/defi/rosetta/icrc_rosetta/data_api/network.mdx +++ b/docs/developer-docs/defi/rosetta/icrc_rosetta/data_api/network.mdx @@ -9,7 +9,7 @@ import { MarkdownChipRow } from "/src/components/Chip/MarkdownChipRow"; -## Overview + Most endpoints require some information about the network represented as a [`NetworkIdentifier`](https://www.rosetta-api.org/docs/models/NetworkIdentifier.html). diff --git a/docs/developer-docs/defi/rosetta/icrc_rosetta/data_api/transactions.mdx b/docs/developer-docs/defi/rosetta/icrc_rosetta/data_api/transactions.mdx index 549611e566..3b788eff95 100644 --- a/docs/developer-docs/defi/rosetta/icrc_rosetta/data_api/transactions.mdx +++ b/docs/developer-docs/defi/rosetta/icrc_rosetta/data_api/transactions.mdx @@ -8,7 +8,7 @@ import { MarkdownChipRow } from "/src/components/Chip/MarkdownChipRow"; -## Overview + There are two endpoints that allow for querying transactions. The `block_transaction` endpoint allows you to fetch a transaction at a certain block height. It is the implementation of the [/block/transaction endpoint](https://docs.cdp.coinbase.com/mesh/reference/blocktransaction) of the Rosetta API standard. The `search_transactions` endpoint allows you to query for transactions given a set of parameters. It is the implementation of the [/search/transactions endpoint](https://docs.cdp.coinbase.com/mesh/reference/searchtransactions/). diff --git a/docs/developer-docs/defi/rosetta/icrc_rosetta/index.mdx b/docs/developer-docs/defi/rosetta/icrc_rosetta/index.mdx index 1928377ed4..b438a7ff3e 100644 --- a/docs/developer-docs/defi/rosetta/icrc_rosetta/index.mdx +++ b/docs/developer-docs/defi/rosetta/icrc_rosetta/index.mdx @@ -4,7 +4,8 @@ keywords: [intermediate, rosetta, tutorial] import { MarkdownChipRow } from "/src/components/Chip/MarkdownChipRow"; -# Overview +# What is ICRC Rosetta? + The ICRC Rosetta implementation allows for communication with the ICRC-1 compatible ledgers through the [Rosetta-API standard](https://docs.cdp.coinbase.com/mesh/docs/welcome). Examples include the [ckBTC ledger](https://dashboard.internetcomputer.org/canister/mxzaz-hqaaa-aaaar-qaada-cai) and the [ckETH ledger](https://dashboard.internetcomputer.org/canister/ss2fx-dyaaa-aaaar-qacoq-cai). diff --git a/docs/developer-docs/defi/rosetta/overview.mdx b/docs/developer-docs/defi/rosetta/overview.mdx index 9ca9b9befe..fbdbe62d57 100644 --- a/docs/developer-docs/defi/rosetta/overview.mdx +++ b/docs/developer-docs/defi/rosetta/overview.mdx @@ -5,7 +5,7 @@ import { MarkdownChipRow } from "/src/components/Chip/MarkdownChipRow"; # Rosetta -## Overview + [Rosetta](https://www.rosetta-api.org/) is an open standard introduced by Coinbase to simplify the integration of blockchain-based tokens in exchanges, block explorers, and wallets. This documentation might help if you want to deploy a token on ICP that aims to be tradable on CeFi exchanges or if you are working on a block explorer or wallet. diff --git a/docs/developer-docs/defi/token_integrations/index.mdx b/docs/developer-docs/defi/token_integrations/index.mdx index 4b5c591811..5710d20302 100644 --- a/docs/developer-docs/defi/token_integrations/index.mdx +++ b/docs/developer-docs/defi/token_integrations/index.mdx @@ -12,8 +12,7 @@ import { GlossaryTooltip } from "/src/components/Tooltip/GlossaryTooltip"; Developers have several options for integrating with the ICP or ICRC-1 ledgers. They can use either the ICRC Rosetta or ICP Rosetta implementations, which is commonly recommended, it might be useful for certain workflows to directly integrate with these ledgers. This section will describe what a direct integration means, how it can be achieved, and how it differs to using Rosetta. -## Token architecture overview - +## Token architecture Tokens on ICP are managed by smart contracts. The ICP ledger canister manages the list of balances for ICP tokens and implements methods for transferring tokens. It builds a chain of blocks consisting of all ICP token transactions since genesis. The chain is authenticated by having the ICP sign the tip of the chain. External parties can retrieve this chain and verify it is genuine by: - Verifying the signature which requires the public key of ICP. diff --git a/docs/developer-docs/defi/tokens/advanced/direct_integration.mdx b/docs/developer-docs/defi/tokens/advanced/direct_integration.mdx index f857511824..0baf17c00d 100644 --- a/docs/developer-docs/defi/tokens/advanced/direct_integration.mdx +++ b/docs/developer-docs/defi/tokens/advanced/direct_integration.mdx @@ -12,8 +12,7 @@ import { GlossaryTooltip } from "/src/components/Tooltip/GlossaryTooltip"; Developers have several options for integrating with the ICP or ICRC-1 ledgers. They can use either the ICP or ICRC Rosetta implementations, which is commonly recommended, although for some workflows, it might be beneficial to directly integrate with these ledgers instead. This section will describe what a direct integration means, how it can be achieved, and how it differs to using Rosetta. -## Token architecture overview - +## Token architecture Tokens on ICP are managed by smart contracts. The ICP ledger canister manages the list of balances for ICP tokens and implements methods for transferring tokens. It builds a chain of blocks consisting of all ICP token transactions since genesis. The chain is authenticated by having the ICP sign the tip of the chain. External parties can retrieve this chain and verify it is genuine by: - Verifying the signature using the public key of ICP. diff --git a/docs/developer-docs/defi/tokens/create.mdx b/docs/developer-docs/defi/tokens/create.mdx index 9c6ee45ca6..5b974722e8 100644 --- a/docs/developer-docs/defi/tokens/create.mdx +++ b/docs/developer-docs/defi/tokens/create.mdx @@ -9,7 +9,7 @@ import { GlossaryTooltip } from "/src/components/Tooltip/GlossaryTooltip"; -## Overview + Custom tokens can be created and deployed on ICP using the [ICRC-1](https://github.com/dfinity/ICRC-1/tree/main/standards/ICRC-1) or [ICRC-2](https://github.com/dfinity/ICRC-1/tree/main/standards/ICRC-2) token standards. diff --git a/docs/developer-docs/defi/tokens/indexes.mdx b/docs/developer-docs/defi/tokens/indexes.mdx index b77d1ed0c3..d66ed98cc2 100644 --- a/docs/developer-docs/defi/tokens/indexes.mdx +++ b/docs/developer-docs/defi/tokens/indexes.mdx @@ -12,7 +12,7 @@ import { GlossaryTooltip } from "/src/components/Tooltip/GlossaryTooltip"; -## Overview + On ICP, an index canister is used in conjunction with a ledger canister to provide the ability for transactions to be queried for a specific account. Without an index canister, a ledger's transaction history cannot easily be parsed and used by applications, as the entire transaction history of a ledger would need to be processed. diff --git a/docs/developer-docs/defi/tokens/ledger/setup/icp_ledger_setup.mdx b/docs/developer-docs/defi/tokens/ledger/setup/icp_ledger_setup.mdx index 21cca18718..6b103f46d9 100644 --- a/docs/developer-docs/defi/tokens/ledger/setup/icp_ledger_setup.mdx +++ b/docs/developer-docs/defi/tokens/ledger/setup/icp_ledger_setup.mdx @@ -3,16 +3,16 @@ keywords: [intermediate, tokens, tutorial, ledger] --- import { MarkdownChipRow } from "/src/components/Chip/MarkdownChipRow"; +import Tabs from "@theme/Tabs"; +import TabItem from "@theme/TabItem"; # ICP ledger local setup -## Overview +The Internet Computer Protocol (ICP) implements management of its utility token (ticker "ICP") using a specialized canister, called the **ICP ledger canister**. It is a single ledger canister that runs alongside other canisters on a special subnet of the Internet Computer—the NNS subnet. The ICP ledger canister is a smart contract that holds **blocks**, each containing a single transaction. -The Internet Computer Protocol (ICP) implements management of its utility token (ticker "ICP") using a specialized canister, called the **ICP ledger canister**. It is a single ledger canister that runs alongside other canisters on a special subnet of the Internet Computer - the NNS subnet. The ICP ledger canister is a smart contract that holds **blocks**, each containing a single transaction. - -These transactions either: +These transactions are either: - **Mint ICP tokens** for accounts. @@ -38,7 +38,7 @@ If you are working in a local development environment, i.e., with a local replic An ICP ledger account (see [ICRC-1 standard](/docs/current/developer-docs/defi/tokens/token-standards#icrc-1)) belongs to and is controlled by the account owner, who must have a valid principal ID. No account can be owned by two or more principals (no "joint accounts"). However, since a principal can refer to an external user as well as to a canister, joint accounts can be implemented as canisters. -An account on the ledger is represented and stored as an `AccountIdentifier`, which is derived from the principal ID and subaccount identifier by computing a hash of the two. The subaccount is an optional bitstring that helps distinguish between the different sub-accounts of the same owner. +An account on the ledger is represented and stored as an `AccountIdentifier`, which is derived from the principal ID and subaccount identifier by computing a hash of the two. The subaccount is an optional bitstring that helps distinguish between the different subaccounts of the same owner. In this context, you can think of principal identifiers as a rough equivalent to the hash of a user’s public key for Bitcoin or Ethereum. You use the corresponding secret key to sign messages and therefore authenticate to the ledger canister and operate on the principal’s account. Canisters can also have accounts in the ledger canister, in which case the address is derived from the canister’s principal. @@ -47,54 +47,56 @@ In this context, you can think of principal identifiers as a rough equivalent to The main reason for introducing accounts was to allow a principal to control multiple accounts. While this could be abstracted away for a user by the wallet software, this is not possible for canisters. ::: - ## Deploying the ledger locally -There are two ways of deploying an ICP ledger locally. -- Use [dfx-nns](/docs/current/developer-docs/developer-tools/cli-tools/cli-reference/dfx-nns) to deploy the entire NNS locally. Since the ICP ledger is part of the NNS, this command will also install an ICP ledger with canister ID `ryjl3-tyaaa-aaaaa-aaaba-cai`. This solution is fast and straightforward, but also more heavyweight. -- Deploy the ICP ledger `wasm` locally. This method is discussed and demonstrated in this guide, as it gives you more control over the deployment and is lightweight. +There are two ways of deploying an ICP ledger locally: -Deploying an ICP ledger locally gives you certain advantages over the default ledger from `dfx` that is installed with `dfx nns install`. For instance, you can define the `minting account`, you have control over the initialization arguments and you have control over which `wasm` version of the ICP ledger you want to interact with. +1. Use [`dfx nns`](/docs/current/developer-docs/developer-tools/cli-tools/cli-reference/dfx-nns) to deploy the entire NNS locally. Since the ICP ledger is part of the NNS, this command will also install an ICP ledger with canister ID `ryjl3-tyaaa-aaaaa-aaaba-cai`. This solution is fast and straightforward, but also more heavyweight. -The ICP ledger only exists on the mainnet and the `wasm` that is running on the mainnet is not meant to be used for other token deployments. It needs to be backward compatible and thus contains a lot of legacy code that should not be used when deploying a new ledger. +2. Deploy the ICP ledger locally using the canister's Wasm file. This method is discussed and demonstrated in this guide, as it gives you more control over the deployment and is lightweight. -If you want to deploy your own token or build an ICRC-1 ledger, have a look at the [guide on setting up an ICRC-1 ledger](/docs/current/developer-docs/defi/tokens/ledger/setup/icrc1_ledger_setup). +Deploying an ICP ledger locally using the Wasm or `.did` files gives you certain advantages over the default ledger from `dfx` that is installed with `dfx nns install`. For instance, you can define the `minting account`, you have control over the initialization arguments, and you have control over which Wasm version of the ICP ledger you want to interact with. -Follow the steps below to deploy your copy of the ledger canister to a local replica. +:::danger +The ICP ledger is not meant to be used for other token deployments because it needs to be backwards compatible and thus contains a lot of legacy code that should not be used when deploying a new ledger. -### Step 1: Make sure you use a recent version of the [IC SDK](/docs/current/developer-docs/getting-started/install). -If you don’t have the IC SDK installed, follow the instructions on the [installing the IC SDK](/docs/current/developer-docs/getting-started/install) section to install it. +If you want to deploy your own token, read the [guide on setting up an ICRC-1 ledger](/docs/current/developer-docs/defi/tokens/ledger/setup/icrc1_ledger_setup). +::: -### Step 2: Create a new dfx project with the command: +## Using `dfx nns install` -``` -dfx new icp_ledger_canister -cd icp_ledger_canister -``` +The [`dfx nns install`](/docs/current/developer-docs/developer-tools/cli-tools/cli-reference/dfx-nns) command can be used to deploy an instance of the entire NNS locally. The NNS includes the ICP ledger canister with canister ID `ryjl3-tyaaa-aaaaa-aaaba-cai`. -:::caution +## Using the most recent ICP ledger Wasm file -If using `dfx` version 0.17.1 or newer, choose 'Motoko' for the backend language, and 'No frontend canister' for the frontend language. + + -::: + Install the IC SDK. + + + -### Step 3: Determine the ledger file locations. +- #### Step 1: Create a new `dfx` project or open an existing project. -Go to the [releases overview](https://dashboard.internetcomputer.org/releases) and copy the latest replica binary revision. At the time of writing, this is `aba60ffbc46acfc8990bf4d5685c1360bd7026b9`. +- #### Step 2: Obtain the latest ledger Wasm and Candid files. -The URL for the ledger Wasm module is `https://download.dfinity.systems/ic//canisters/ledger-canister.wasm.gz`, so with the above revision it would be `https://download.dfinity.systems/ic/aba60ffbc46acfc8990bf4d5685c1360bd7026b9/canisters/ledger-canister.wasm.gz`. +Go to the [releases overview](https://dashboard.internetcomputer.org/releases) and copy the latest replica binary revision. -The URL for the ledger.did file is `https://raw.githubusercontent.com/dfinity/ic//rs/ledger_suite/icp/ledger.did`, so with the above revision it would be `https://raw.githubusercontent.com/dfinity/ic/aba60ffbc46acfc8990bf4d5685c1360bd7026b9/rs/ledger_suite/icp/ledger.did`. +The URL for the ledger Wasm module is `https://download.dfinity.systems/ic//canisters/ledger-canister.wasm.gz`. + +The URL for the ledger's Candid file is `https://raw.githubusercontent.com/dfinity/ic//rs/ledger_suite/icp/ledger.did`. #### Optional -If you want to make sure you have the latest ICP ledger files, you can run the following script. Please ensure that you have [`jq`](https://jqlang.github.io/jq/) installed as the script relies on it. +If you want to make sure you have the latest ICP ledger files, you can run the following script. Please ensure that you have [`jq`](https://jqlang.github.io/jq/) installed, as the script relies on it. + ``` sh curl -o download_latest_icp_ledger.sh "https://raw.githubusercontent.com/dfinity/ic/aba60ffbc46acfc8990bf4d5685c1360bd7026b9/rs/rosetta-api/scripts/download_latest_icp_ledger.sh" chmod +x download_latest_icp_ledger.sh ./download_latest_icp_ledger.sh ``` -### Step 4: Create a new identity that will work as a minting account: +- #### Step 3: Create a new identity that will work as a minting account. ``` sh dfx identity new minter @@ -102,22 +104,20 @@ dfx identity use minter echo $(dfx ledger account-id) ``` -Record the output of these commands as your minting account ID. +Record the output of these commands as your minting account ID. Transfers from the minting account will create `Mint` transactions. Transfers to the minting account will create `Burn` transactions. -Transfers from the minting account will create `Mint` transactions. Transfers to the minting account will create `Burn` transactions. - -### Step 5: Switch back to your default identity and record its ledger account identifier. +- #### Step 4: Switch back to your primary developer identity and record its ledger account identifier. ``` sh -dfx identity use default +dfx identity use MyIdentity echo $(dfx ledger account-id) ``` -Record the output of these commands as your default account ID. +Record the output of these commands as your developer account ID. -### Step 6: Configure the `dfx.json` file. +- #### Step 5: Configure the `dfx.json` file. -Open the `dfx.json` file in your project's directory. Replace the existing content with the following, updating the values of `MINTER_ACCOUNT_ID` and `DEFAULT_ACCOUNT_ID` with the values obtained in the previous steps: +Open the `dfx.json` file in your project's directory. Replace the existing content with the following, updating the values of `MINTER_ACCOUNT_ID` and `DEVELOPER_ACCOUNT_ID` with the values obtained in the previous steps: :::info `dfx.json` does not support referring to values through environment variables. Values must be hardcoded in plain text. @@ -125,67 +125,104 @@ Open the `dfx.json` file in your project's directory. Replace the existing conte ``` json { - "canisters": { - "icp_ledger_canister": { - "type": "custom", - "candid": "https://raw.githubusercontent.com/dfinity/ic/aba60ffbc46acfc8990bf4d5685c1360bd7026b9/rs/ledger_suite/icp/ledger.did", - "wasm": "https://download.dfinity.systems/ic/aba60ffbc46acfc8990bf4d5685c1360bd7026b9/canisters/ledger-canister.wasm.gz", - "remote": { - "id": { - "ic": "ryjl3-tyaaa-aaaaa-aaaba-cai" - } - }, - "init_arg" : "(variant { Init = record { minting_account = \"MINTER_ACCOUNT_ID\"; initial_values = vec { record { \"DEFAULT_ACCOUNT_ID\"; record { e8s = 10_000_000_000 : nat64; }; }; }; send_whitelist = vec {}; transfer_fee = opt record { e8s = 10_000 : nat64; }; token_symbol = opt \"LICP\"; token_name = opt \"Local ICP\"; } })" - } - }, - "defaults": { - "build": { - "args": "", - "packtool": "" - } - }, - "output_env_file": ".env", - "version": 1 +  "canisters": { +    "icp_ledger_canister": { +      "type": "custom", +      "candid": "https://raw.githubusercontent.com/dfinity/ic/aba60ffbc46acfc8990bf4d5685c1360bd7026b9/rs/ledger_suite/icp/ledger.did", +      "wasm": "https://download.dfinity.systems/ic/aba60ffbc46acfc8990bf4d5685c1360bd7026b9/canisters/ledger-canister.wasm.gz", +      "remote": { +        "id": { +          "ic": "ryjl3-tyaaa-aaaaa-aaaba-cai" +        } +      }, +      "init_arg" : "(variant { Init = record { minting_account = \"MINTER_ACCOUNT_ID\"; initial_values = vec { record { \"DEFAULT_ACCOUNT_ID\"; record { e8s = 10_000_000_000 : nat64; }; }; }; send_whitelist = vec {}; transfer_fee = opt record { e8s = 10_000 : nat64; }; token_symbol = opt \"LICP\"; token_name = opt \"Local ICP\"; } })" +    } +  }, +  "defaults": { +    "build": { +      "args": "", +      "packtool": "" +    } +  }, +  "output_env_file": ".env", +  "version": 1 } ``` -If you chose to download the ICP ledger files with the script you need to replace the Candid and Wasm file entries: +:::danger +If you chose to download the ICP ledger files with the script, you need to replace the Candid and Wasm file entries: ```json ... "candid": icp_ledger.did, "wasm" : icp_ledger.wasm.gz, - ... +  ... ``` -This `dfx.json` file also defines the init arguments for the ledger canister: +::: + +This `dfx.json` file defines the init arguments for the ledger canister: - Sets the minting account to the account identifier you saved in a previous step (`MINTER_ACCOUNT_ID`). - Mints 100 ICP tokens to the `DEFAULT_ACCOUNT_ID` (1 ICP is equal to 10^8 e8s). - Sets the transfer fee to 0.0001 ICP. - Names the token `Local ICP / LICP`. -You can also pass these init args to the canister using the command line. [Learn more about init args](/docs/current/developer-docs/developer-tools/cli-tools/advanced-dfx/init-args/). +### Init arguments + +You can also pass these init args to the canister [using the command line](/docs/current/developer-docs/developer-tools/cli-tools/advanced-dfx/init-args/#using-init_arg) or by [storing them in a file](/docs/current/developer-docs/developer-tools/cli-tools/advanced-dfx/init-args/#using-an-init_arg_file), then referencing that file in your `dfx.json` configuration: + +```json +{ +  "canisters": { +    "icp_ledger_canister": { +      "type": "custom", +      "candid": "https://raw.githubusercontent.com/dfinity/ic/aba60ffbc46acfc8990bf4d5685c1360bd7026b9/rs/ledger_suite/icp/ledger.did", +      "wasm": "https://download.dfinity.systems/ic/aba60ffbc46acfc8990bf4d5685c1360bd7026b9/canisters/ledger-canister.wasm.gz", +      "remote": { +        "id": { +          "ic": "ryjl3-tyaaa-aaaaa-aaaba-cai" +        } +      }, +      "init_arg_file" : "init-args.did" +    } +  }, +  "defaults": { +    "build": { +      "args": "", +      "packtool": "" +    } +  }, +  "output_env_file": ".env", +  "version": 1 +} +``` + +[Learn more about init args](/docs/current/developer-docs/developer-tools/cli-tools/advanced-dfx/init-args/). -### Step 7: Start a local replica. +- #### Step 6: Start a local replica. ``` sh dfx start --clean --background ``` -### Step 8: Deploy the ledger canister locally: +- #### Step 7: Deploy the ledger canister locally. :::caution -In this workflow, you cannot deploy this canister to the playground (using flag `dfx deploy --playground`) because it does not accept gzipped Wasm files. +You cannot deploy this canister to the playground (using the flag `dfx deploy --playground`) because it does not accept gzipped Wasm files. ::: ``` dfx deploy --specified-id ryjl3-tyaaa-aaaaa-aaaba-cai icp_ledger_canister ``` -Take a moment to read the details of the call made above. Not only are you deploying the ICP ledger canister, you are also deploying the canister to the same canister ID as the mainnet ledger canister. This is to make it easier to switch between local and mainnet deployments. +:::info +You are deploying the local ICP ledger canister to the same canister ID as the mainnet ledger canister. This is to facilitate switching between local and mainnet deployments. +::: + +Your local ICP ledger canister is up and running. You can now deploy other canisters that need to communicate with the ledger canister. -### Step 9: Interact with the canister. +- #### Step 8: Interact with the canister. You can interact with the canister by running CLI commands, such as: @@ -193,20 +230,8 @@ You can interact with the canister by running CLI commands, such as: dfx canister call icp_ledger_canister name ``` -This command will return the token's name, such as: - -``` -("Local ICP") -``` - Or, you can interact with it using the Candid UI by navigating to the URL provided when the canister was deployed, such as: ``` http://127.0.0.1:4943/?canisterId=bnz7o-iuaaa-aaaaa-qaaaa-cai&id=ryjl3-tyaaa-aaaaa-aaaba-cai ``` - -After navigating to this URL in a web browser, the Candid UI will resemble the following: - -![Candid UI](../../../_attachments/CandidUI.png) - -Your local ICP ledger canister is up and running. You can now deploy other canisters that need to communicate with the ledger canister. diff --git a/docs/developer-docs/defi/tokens/ledger/setup/icrc1_ledger_setup.mdx b/docs/developer-docs/defi/tokens/ledger/setup/icrc1_ledger_setup.mdx index 19b9dfc9a6..a1bbb21a3a 100644 --- a/docs/developer-docs/defi/tokens/ledger/setup/icrc1_ledger_setup.mdx +++ b/docs/developer-docs/defi/tokens/ledger/setup/icrc1_ledger_setup.mdx @@ -3,73 +3,67 @@ keywords: [intermediate, tokens, icrc, tutorial, ledger] --- import { MarkdownChipRow } from "/src/components/Chip/MarkdownChipRow"; +import Tabs from "@theme/Tabs"; +import TabItem from "@theme/TabItem"; # ICRC-1 ledger local setup -## Overview -This guide will show you how to deploy an ICRC-1 ledger locally and on the mainnet. ICRC-1 is a [token standard](https://github.com/dfinity/ICRC-1). Thus, deploying a new token that is ICRC-1-compatible is synonymous with deploying an ICRC-1 ledger. -The ICRC-1 ledger used in this guide is a reference implementation. This guide aims at showing you how to setup an existing ICRC-1 ledger implementation rather than how to build an ICRC-1 ledger yourself. +ICRC-1 is a [token standard](https://github.com/dfinity/ICRC-1) used to create and deploy fungible tokens on the Internet Computer. Each token deployed on the network has its own dedicated ledger. Thus, deploying a new token that is ICRC-1-compatible is synonymous with deploying an ICRC-1 ledger. +The ICRC-1 ledger used in this guide is a reference implementation used to demonstrate how to set up an existing ICRC-1 ledger implementation rather than how to build an ICRC-1 ledger yourself. -## Deploying the ledger locally +## Deploying the ICRC ledger locally -### Step 1: Make sure you use a recent version of the [IC SDK](/docs/current/developer-docs/getting-started/install). -If you don’t have the IC SDK installed, follow instructions on the [installing the IC SDK](/docs/current/developer-docs/getting-started/install) section to install it. + + -### Step 2: Create a new dfx project with the command: + Install the IC SDK. -``` -dfx new icrc1_ledger_canister -cd icrc1_ledger_canister -``` + + -:::caution +- #### Step 1: Create a new `dfx` project or open an existing project. -If using `dfx` version 0.17.1 or newer, choose 'Motoko' for the backend language, and 'No frontend canister' for the frontend language. - -::: +- #### Step 2: Obtain the latest ledger Wasm and Candid files. -### Step 3: Determine ledger file locations. +Search for [ledger-suite-icrc releases](https://github.com/dfinity/ic/releases?q=ledger-suite-icrc&expanded=false) and select the latest ICRC ledger suite release. -Search for [ledger-suite-icrc releases](https://github.com/dfinity/ic/releases?q=ledger-suite-icrc&expanded=false) and select the latest ICRC ledger suite release. At the time of writing, this is [`ledger-suite-icrc-2024-11-28`](https://github.com/dfinity/ic/releases/tag/ledger-suite-icrc-2024-11-28). +The URL for the ledger Wasm module is `https://github.com/dfinity/ic/releases/download//ic-icrc1-ledger.wasm.gz`. -The URL for the ledger Wasm module is `https://github.com/dfinity/ic/releases/download//ic-icrc1-ledger.wasm.gz`, so with the above release it would be `https://github.com/dfinity/ic/releases/download/ledger-suite-icrc-2024-11-28/ic-icrc1-ledger.wasm.gz`. +The URL for the ledger Candid file is `https://github.com/dfinity/ic/releases/download//ledger.did`. -The URL for the ledger .did file is `https://github.com/dfinity/ic/releases/download//ledger.did`, so with the above release it would be `https://github.com/dfinity/ic/releases/download/ledger-suite-icrc-2024-11-28/ledger.did`. +#### Optional +If you want to make sure you have the latest ICRC-1 ledger files, you can run the following script that downloads the files into your local directory: - -#### Optional: -If you want to make sure you have the latest ICRC-1 ledger files you can run the following script that downloads the files into your local directory: ``` sh curl -o download_latest_icrc1_ledger.sh "https://raw.githubusercontent.com/dfinity/ic/aba60ffbc46acfc8990bf4d5685c1360bd7026b9/rs/rosetta-api/scripts/download_latest_icrc1_ledger.sh" chmod +x download_latest_icrc1_ledger.sh ./download_latest_icrc1_ledger.sh ``` -These files will be used by the `dfx.json` file as described in the next step. +- #### Step 4: Configure the `dfx.json` file. -### Step 4: Configure the `dfx.json` file. -Open the `dfx.json` file in your project's directory. Replace the existing content with the following and make sure you replace `` in the `candid` and `wasm` URLs as shown in step 3: +Open the `dfx.json` file in your project's directory. Replace the existing content with the following and make sure you replace `` in the `candid` and `wasm` URLs as shown in the previous step: ``` json { - "canisters": { - "icrc1_ledger_canister": { - "type": "custom", - "candid": "https://github.com/dfinity/ic/releases/download//ledger.did", - "wasm": "https://github.com/dfinity/ic/releases/download//ic-icrc1-ledger.wasm.gz" - } - }, - "defaults": { - "build": { - "args": "", - "packtool": "" - } - }, - "output_env_file": ".env", - "version": 1 +  "canisters": { +    "icrc1_ledger_canister": { +      "type": "custom", +      "candid": "https://github.com/dfinity/ic/releases/download//ledger.did", +      "wasm": "https://github.com/dfinity/ic/releases/download//ic-icrc1-ledger.wasm.gz" +    } +  }, +  "defaults": { +    "build": { +      "args": "", +      "packtool": "" +    } +  }, +  "output_env_file": ".env", +  "version": 1 } ``` @@ -79,15 +73,16 @@ If you chose to download the ICRC-1 ledger files with the script, you need to re ... "candid": "icrc1_ledger.did", "wasm" : "icrc1_ledger.wasm.gz" - ... +  ... ``` +:::info In an existing project you would only need to add the `icrc1_ledger_canister` canister to the `canisters` section instead of replacing the entire content of `dfx.json`. +::: ## Ledger test suite -There is a test suite available to [test ICRC-1 ledgers](https://github.com/dfinity/ICRC-1/tree/main/test). If you are building your own ICRC-1 repository, it might be helpful to run this test suite against your locally deployed ICRC-1 ledger, or import the test suite directly through a Rust crate and add the tests to your repository. You can find a reference implementation of integrating the [test suite to your repo](https://github.com/dfinity/ICRC-1/tree/main/test/ref). - +There is a test suite available for [ICRC-1 ledgers](https://github.com/dfinity/ICRC-1/tree/main/test). If you are building your own ICRC-1 repository, it might be helpful to run this test suite against your locally deployed ICRC-1 ledger, or import the test suite directly through a Rust crate and add the tests to your repository. You can find a reference implementation of integrating the [test suite to your repo](https://github.com/dfinity/ICRC-1/tree/main/test/ref). ## Next steps diff --git a/docs/developer-docs/defi/tokens/ledger/usage/icp_ledger_usage.mdx b/docs/developer-docs/defi/tokens/ledger/usage/icp_ledger_usage.mdx index b79423601f..341206fd15 100644 --- a/docs/developer-docs/defi/tokens/ledger/usage/icp_ledger_usage.mdx +++ b/docs/developer-docs/defi/tokens/ledger/usage/icp_ledger_usage.mdx @@ -8,252 +8,79 @@ import { MarkdownChipRow } from "/src/components/Chip/MarkdownChipRow"; -## Overview -There are multiple ways to interact with the ICP ledger. They depend on whether you want to interact with the ICP ledger on mainnet, the `dfx ledger` default ICP ledger on a local network, or whether you have deployed your own local ledger version. Also, how you interact with the ICP ledger is dependent on whether you want to interact with it from the command line, from your web app, or from another canister. +How you interact with the ICP ledger is dependent on whether you want to interact with it from the command line, from your web app, or from another canister. Available workflows and tools include: -This guide will discuss the different ways to interact with the ICP ledger. In this guide, the following workflows will be covered: -- `dfx ledger`: the built in `dfx` shortcut for interacting with the ICP ledger. -- `dfx canister`: the generic canister call from `dfx`. +- `dfx ledger`: The `dfx` CLI command for interacting with the ICP ledger. +- `dfx canister`: A generic canister call using `dfx`. - [ledger-icp](https://github.com/dfinity/ic-js/tree/main/packages/ledger-icp) JavaScript library. -- `ic-cdk`: inter-canister calls for the ICP ledger. +- `ic-cdk`: Inter-canister calls for the ICP ledger. -## Interacting with ICP ledger via `dfx ledger` +## Interacting with the ICP ledger via `dfx ledger` -`dfx` provides a convenience command to interact with the ICP ledger canister and related functionality. You can find the documentation [here](/docs/current/developer-docs/developer-tools/cli-tools/cli-reference/dfx-ledger) or just enter the following command into your console: +`dfx` provides a convenience command to interact with the ICP ledger canister and related functionality: [`dfx ledger`](/docs/current/developer-docs/developer-tools/cli-tools/cli-reference/dfx-ledger). -``` bash -dfx ledger --help -``` - -It's worth checking out the `--help` flag of the subcommands as well. -`dfx` does not come with an ICP ledger instance installed by default. To be able to use this command you will need to install the ICP ledger locally. You can do that by following this [guide](/docs/developer-docs/defi/tokens/ledger/setup/icp_ledger_setup.mdx) or by installing the NNS locally: -``` bash -dfx extension install nns -dfx nns install -``` -The ICP ledger will then run locally with the canister ID `ryjl3-tyaaa-aaaaa-aaaba-cai`. -Currently, `dfx` exposes only a subset of the ICP ledger functionality, namely `balance` and `transfer`. -Both commands provide a flag to specify a ledger canister id (`--ledger-canister-id`). This simplifies interacting with a local ledger deployment or other tokens that provide the same interface. If you do not specify the canister ID `dfx ledger` will assume you want to interact with a ICP ledger that has a canister ID of `ryjl3-tyaaa-aaaaa-aaaba-cai` or with the ICP ledger on the mainnet. For the latter, you need to specify the mainnet as the network of choice using the flag `--network ic`. +`dfx` does not come with an ICP ledger instance installed by default. To be able to use this command, you will need to install the [ICP ledger locally](/docs/developer-docs/defi/tokens/ledger/setup/icp_ledger_setup.mdx). -:::info -Summary of different `dfx ledger` commands: -- `dfx ledger ...`: interact with the ICP ledger on your local network with canister ID `ryjl3-tyaaa-aaaaa-aaaba-cai`. -- `dfx ledger --network ic ...`: interact with the ICP ledger on the mainnet. -- `dfx ledger --ledger-canister-id ...`: interact with the [locally deployed](/docs/developer-docs/defi/tokens/ledger/setup/icp_ledger_setup.mdx) ICP ledger on your local network. -::: +Currently, `dfx ledger` only exposes a subset of the ICP ledger functionality, namely `balance` and `transfer`. -### Balance +View the [`dfx ledger`](/docs/current/developer-docs/developer-tools/cli-tools/cli-reference/dfx-ledger) documentation for all available `dfx ledger` commands and flags. -Get the ICP balance of a specific account: +## Interacting with the ICP ledger via `dfx canister` -``` bash -dfx ledger --network ic balance -``` +The ICP ledger canister ID is assumed to be `ryjl3-tyaaa-aaaaa-aaaba-cai`. If your locally deployed ICP ledger's canister ID is different, you will need to replace `ryjl3-tyaaa-aaaaa-aaaba-cai` with it. -The `` is encoded as a hex string. You can print the account id of the current `dfx` identity by running: +Use the following command syntax to interact with the ICP ledger via `dfx canister`: -```bash -dfx ledger account-id ``` - -In many cases you want to check the main account balance of a specific principal. You can combine the `balance` command with the `account-id` command, while specifying an `--of-principal` argument to yield this helpful command: - -``` bash -dfx ledger --network ic balance $(dfx ledger account-id --of-principal ) +dfx canister call ``` -### Transfer +For example, to fetch the token symbol of the ICP ledger, call the `symbol` method: -The transfer function can be used to transfer ICP from your account to another. - -``` bash -dfx ledger --network ic transfer --amount --memo -``` - -## Interacting with ICP ledger via `dfx canister` -For this subsection it is assumed that you have deployed an ICP ledger either locally or you want to communicate with the mainnet ICP ledger using `dfx canister`. The ICP ledger canister ID is assumed to be `ryjl3-tyaaa-aaaaa-aaaba-cai`, if your locally deployed ICP ledger's canister ID is different you will need to replace `ryjl3-tyaaa-aaaaa-aaaba-cai` with it. You can find all endpoints that can be called in the `icp_ledger.did` file. How to retrieve it is discussed in the [ICP local deployment guide](/docs/developer-docs/defi/tokens/ledger/setup/icp_ledger_setup.mdx). - -This guide will only go into the ICP ledger specific endpoints. To call the ICRC-1 endpoints you can have a look at [the ICRC-1 setup guide](/docs/current/developer-docs/defi/tokens/indexes). To find a more detailed description of the data types used in these commands you can have a look at [this guide](/docs/current/references/ledger#_getting_ledger_blocks). - -To fetch the symbol of the ICP ledger: ``` dfx canister call ryjl3-tyaaa-aaaaa-aaaba-cai symbol '()' ``` -This command returns the ICP symbol: -``` -(record { symbol = "ICP" }) -``` -To fetch the name of the ICP ledger: -``` -dfx canister call ryjl3-tyaaa-aaaaa-aaaba-cai name '()' -``` -This command returns the ICP name: -``` -(record { name = "Internet Computer" }) -``` +You can find all available methods listed within the ICP ledger canister's Candid file or view the [mainnet ICP ledger canister on the dashboard](https://dashboard.internetcomputer.org/canister/ryjl3-tyaaa-aaaaa-aaaba-cai). -To fetch the decimals of the ICP ledger: -``` -dfx canister call ryjl3-tyaaa-aaaaa-aaaba-cai decimals '()' -``` -This command returns the ICP decimals: -``` -(record { decimals = 8 : nat32 }) -``` -To handle a growing number of transactions within limited canister memory, a new archive canister is created when the history exceeds a threshold, migrating older transactions to it. +[View a more detailed description of the data types used in these commands](/docs/current/references/ledger#_getting_ledger_blocks). -To fetch the archives of the ICP ledger: -``` -dfx canister call ryjl3-tyaaa-aaaaa-aaaba-cai archives '()' -``` -If you are testing locally, no archive canisters should have been created yet: -``` -(record { archives = vec {} }) -``` -However, if you are testing on mainnet, the following archive canisters have been created as of the time of writing this document: -``` -( - record { - archives = vec { - record { canister_id = principal "qjdve-lqaaa-aaaaa-aaaeq-cai" }; - record { canister_id = principal "qsgjb-riaaa-aaaaa-aaaga-cai" }; - record { canister_id = principal "q4eej-kyaaa-aaaaa-aaaha-cai" }; - }; - }, -) -``` +## Interact with ICP ledger from your web application -To send tokens to the `AccountIdentifier` `d52f7f2b7277f025bcaa5c90b10d122274faba289` you can use the following commands. You will need to derive the `AccountIdentifier` by getting the principal first: -``` -dfx ledger account-id --of-principal -``` -You can get the principal of an identity by calling: -``` -dfx identity get-principal --identity -``` -If you have an identity called `default2` and you want to send ICP to this principals default `AccountIdentifier` you would call: - ``` -dfx identity get-principal --identity default2 -``` -This command will return: -``` -sckqo-e2vyl-4rqqu-5g4wf-pqskh-iynjm-46ixm-awluw-ucnqa-4sl6j-mqe -``` -If you plug this response value into the `account-id` command: -``` -dfx ledger account-id --of-principal sckqo-e2vyl-4rqqu-5g4wf-pqskh-iynjm-46ixm-awluw-ucnqa-4sl6j-mqe -``` -The following response will be returned: -``` -d52f7f2b7277f025bcaa5c90b10d122274faba289 -``` -You can bring all of these commands together to form a transfer transaction: -``` -export TO_ACCOUNT = "d52f7f2b7277f025bcaa5c90b10d122274faba2891bea519105309ae1f0af91d" -dfx canister call ryjl3-tyaaa-aaaaa-aaaba-cai transfer '(record { to = $(python3 -c 'print("vec{" + ";".join([str(b) for b in bytes.fromhex("'$TO_ACCOUNT'")]) + "}")'); memo = 1:nat64; amount = record {e8s = 200_000_000 }; fee = record { e8s = 10_000 }; })' -``` +In order to simplify working with the ICP ledger from JavaScript applications, you can use the [ledger-icp](https://github.com/dfinity/ic-js/tree/main/packages/ledger-icp) JavaScript library. -This command returns the block index in which this transaction took place. In this example, it was the first block: -``` -(variant { Ok = 1 : nat64 }) -``` -To get the balance of an `AccountIdentifier` you can call: -``` -dfx canister call ryjl3-tyaaa-aaaaa-aaaba-cai account_balance '(record { account = '$(python3 -c 'print("vec{" + ";".join([str(b) for b in bytes.fromhex("'$TO_ACCOUNT'")]) + "}")')' })' -``` -It returns the the balance in e8s of the `AccountIdentifier` `d52f7f2b7277f025bcaa5c90b10d122274faba2891bea519105309ae1f0af91d`. It should have a balance of 200 million as thats the amount you sent earlier: -``` -(record { e8s = 200_000_000 : nat64 }) -``` +:::info +To interact with the ICRC-1 endpoints of the ICP ledger, learn more about [interacting with an ICRC-1 ledger](/docs/current/developer-docs/defi/tokens/indexes). +::: -To query the created blocks from the ICP ledger you can call: -``` -dfx canister call ryjl3-tyaaa-aaaaa-aaaba-cai query_blocks '(record {start = 1:nat64; length = 1:nat64})' -``` +## Interacting with ICP from a canister (inter-canister calls via `ic-cdk`) -You will have to specify the first block to fetch and the number of blocks to fetch. -This command will return output that resembles the following: +View the [inter-canister call documentation] (/docs/developer-docs/backend/rust/intercanister) to see how you can call one canister from within another. -``` -( - record { - certificate = opt blob "\d9\d9\f7\a2dtree\83\01\83\01\83\01\83\02Hcanister\83\01\83\01\82\04X \05\8f\12\83V\ad(\b6q\e6\0b\60\d2\90\97<\a0\8c~\ea\a9\18\13j\fe<\bbH\1a^n1\83\02J\80\00\00\00\00\10\00\01\01\01\83\01\83\01\83\01\83\02Ncertified_data\82\03X \f5}\c2M\a6\87\fe\03N9H/4?\bd\a8\1c\ad\ba\0b\86,\98\8dx)\11\b9=*\b7\eb\82\04X \83\c5k\f1M\de=(\def\c6\92\b5\fc\9d\97\e9\dd\98[j\d7+\0f\e6\f8N\8a\8d\f3\dc\b2\82\04X l\96\c1\d2D\fe\c00\d5S\f6N\0b4q]\9do\d7\a00\90\a0\8e\c03K\f6\f2hT\fe\82\04X \99i\83\c5\0b\0ec\02\dd\d9{r\a8\cb\7f?\f5\03\04\88\b1QC\d0\15\9eR\87\da(\d6\08\82\04X \97\c3\ef\e5\dc\efyN\1b\cd\d3\a1\c2\bbE\84y@\fc(\ec\87\cb5yk\ef\d74\b5\ef\cf\82\04X S\ebWak\00\b4#\a3\94I+\b0\9a\dc\11\b5\ff\1a\96\b0\a7\cede8\1b\b8\16\1d\14\dd\82\04X \13\c86\94\98\d9\ae)\a7\e4\f3\19\97\08\a2\dc\a5\a5(v\90\f8a\19rL\aa\09\0c\1b\d5\d5\83\01\82\04X \17+O\f52\a3\22\7f\87S\9bop\a6\18\b1\16\e1\1f\19\c2\9e\1f\ea:\df-\e47/\1d\e0\83\02Dtime\82\03I\90\f9\8e\d7\a0\88\b6\c4\17isignatureX0\aa6/\f2b\9a\c1%\98\f6\e32\e0\de\11\0e(\fe\f9=\b09z\be\a3\e7\8aG\d0:\18k\e0o\ed\f3\ba\d2\84\17yAAx\9cm\bf\06"; - blocks = vec { - record { - transaction = record { - memo = 1 : nat64; - icrc1_memo = null; - operation = opt variant { - 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"; - fee = record { e8s = 10_000 : nat64 }; - from = blob "\0amCu\816\9bTj\fd\efa<\a9\c0\81\a2R\ca,F\e7\ec)\e5\10\bc\10\b2\13\fa\27"; - amount = record { e8s = 200_000_000 : nat64 }; - } - }; - created_at_time = record { - timestamp_nanos = 1_695_815_275_230_210_000 : nat64; - }; - }; - timestamp = record { - timestamp_nanos = 1_695_815_275_230_210_000 : nat64; - }; - parent_hash = opt blob "\e6{0\db\a6\a5)1\17@\9d\e7h\ee\85\b0\91h>l\a2\fdxi\d3;x\85\bf\e7\d0a"; - }; - }; - chain_length = 6 : nat64; - first_block_index = 1 : nat64; - archived_blocks = vec {}; - }, -) -``` +Here is an example of how to fetch the token name from the ICP ledger using Rust and the `ic-cdk` [library](https://github.com/dfinity/cdk-rs) from within a canister: -To only query the encoded blocks from the ICP ledger you can call: -``` -dfx canister call ryjl3-tyaaa-aaaaa-aaaba-cai query_encoded_blocks '(record {start = 1:nat64; length = 1:nat64})' ``` -It is a similar format but you will only receive the CBOR encoded block: -``` -( - record { - certificate = opt blob "\d9\d9\f7\a2dtree\83\01\83\01\83\01\83\02Hcanister\83\01\83\01\82\04X \05\8f\12\83V\ad(\b6q\e6\0b\60\d2\90\97<\a0\8c~\ea\a9\18\13j\fe<\bbH\1a^n1\83\02J\80\00\00\00\00\10\00\01\01\01\83\01\83\01\83\01\83\02Ncertified_data\82\03X \f5}\c2M\a6\87\fe\03N9H/4?\bd\a8\1c\ad\ba\0b\86,\98\8dx)\11\b9=*\b7\eb\82\04X \83\c5k\f1M\de=(\def\c6\92\b5\fc\9d\97\e9\dd\98[j\d7+\0f\e6\f8N\8a\8d\f3\dc\b2\82\04X l\96\c1\d2D\fe\c00\d5S\f6N\0b4q]\9do\d7\a00\90\a0\8e\c03K\f6\f2hT\fe\82\04X \99i\83\c5\0b\0ec\02\dd\d9{r\a8\cb\7f?\f5\03\04\88\b1QC\d0\15\9eR\87\da(\d6\08\82\04X \97\c3\ef\e5\dc\efyN\1b\cd\d3\a1\c2\bbE\84y@\fc(\ec\87\cb5yk\ef\d74\b5\ef\cf\82\04X \aao\e5\85L\f7\0b\e3V\07\ed\27\88k\a5z\bd\abQ\aa=\dcc>m\0b\b1\88\ea\c8\f4\b7\82\04X \13\c86\94\98\d9\ae)\a7\e4\f3\19\97\08\a2\dc\a5\a5(v\90\f8a\19rL\aa\09\0c\1b\d5\d5\83\01\82\04X \17+O\f52\a3\22\7f\87S\9bop\a6\18\b1\16\e1\1f\19\c2\9e\1f\ea:\df-\e47/\1d\e0\83\02Dtime\82\03I\b8\c7\d9\f5\9a\8a\b6\c4\17isignatureX0\af\9e\c3\d1\e3\95\c8\1b\0c\b8\5cC\b0\fb\f9E\e0\eeJ\88\1f\e7%G\06\b8\ac\a4\14{\e1k\97\15\8d\8a0\c6\9d\86\a1\03\ef\02\b7\82A\f9"; - blocks = vec { - blob "\0a\22\0a \e6{0\db\a6\a5)1\17@\9d\e7h\ee\85\b0\91h>l\a2\fdxi\d3;x\85\bf\e7\d0a\12\0a\08\d0\cf\9c\e6\a0\e0\af\c4\17\1af\1aT\0a\22\0a \0amCu\816\9bTj\fd\efa<\a9\c0\81\a2R\ca,F\e7\ec)\e5\10\bc\10\b2\13\fa\27\12\22\0a \08.\cf.?dz\c6\00\f4?8\a6\83B\fb\a5\b8\e6\8b\08_\02Y+w\f3\98\08\a8\d2\b5\1a\05\08\80\84\af_\22\03\08\90N\22\02\08\012\0a\08\d0\cf\9c\e6\a0\e0\af\c4\17"; - }; - chain_length = 6 : nat64; - first_block_index = 1 : nat64; - archived_blocks = vec {}; - }, -) -``` - -## Interact with ICP ledger from your web application - -In order to simplify working with ICP ledger from JavaScript applications, you can use the [ledger-icp](https://github.com/dfinity/ic-js/tree/main/packages/ledger-icp) JavaScript library. -. -To interact with the ICRC-1 endpoints of the ICP ledger you can have a look at the guide on [interacting with an ICRC-1 ledger](/docs/current/developer-docs/defi/tokens/indexes). +// You will need the canister ID of the ICP ledger: `ryjl3-tyaaa-aaaaa-aaaba-cai`. -## Interacting with ICP from a canister (inter-canister calls via `ic-cdk`) -You can look at the documentation of [inter-canister calls] (/docs/developer-docs/backend/rust/intercanister) to see how you can interact with the another canister from inside a canister. This guide will give you a couple of examples on how to make such a call in the case of the ICP ledger. - -Here is an example on how fetch the name from the ICP ledger using Rust and the `ic-cdk` [library](https://github.com/dfinity/cdk-rs) from withing a canister: -``` -// You will need the principal of the ICP ledger. The canister id of the ICP ledger on mainnet and the dfx default ICP ledger locally is `ryjl3-tyaaa-aaaaa-aaaba-cai`. let ledger_id = Principal::from_text("ryjl3-tyaaa-aaaaa-aaaba-cai").unwrap(); + // The request object of the `icrc1_name` endpoint is empty. - let req = (); - let (res,): (String,) = - ic_cdk::call(ledger_id, "icrc1_name", (req,)) - .await.unwrap(); + +    let req = (); +    let (res,): (String,) = +        ic_cdk::call(ledger_id, "icrc1_name", (req,)) +            .await.unwrap(); ``` -For all other endpoints you can use the request and response structure from the `ledger.did` Candid file. How to retrieve the Candid file is explained in [the guide on deploying an ICP ledger locally](/docs/developer-docs/defi/tokens/ledger/setup/icp_ledger_setup.mdx). +You can find all available methods listed within the ICP ledger canister's Candid file or view the [mainnet ICP ledger canister on the dashboard](https://dashboard.internetcomputer.org/canister/ryjl3-tyaaa-aaaaa-aaaba-cai). ### `icrc-ledger-types` Rust crate -As explained in the [token standards](/docs/current/developer-docs/defi/tokens/token-standards), the ICP ledger supports all ICRC-1 endpoints. You will need to define the structures used for these endpoints. -To interact with ICRC-1 and ICRC-2 endpoints, the Rust crate [icrc-ledger-types](https://crates.io/crates/icrc-ledger-types) can be used. -This is true for the ICP ledger as well as any other canister that supports ICRC-1 or any of the ICRC-1 extension standards (i.e ICRC-2, ICRC-3,...). + +As explained in [token standards](/docs/current/developer-docs/defi/tokens/token-standards), the ICP ledger supports all ICRC-1 endpoints. You will need to define the structures used for these endpoints. + +To interact with the ICRC-1 and ICRC-2 endpoints, the Rust crate [icrc-ledger-types](https://crates.io/crates/icrc-ledger-types) can be used. +This is true for the ICP ledger as well as any other canister that supports ICRC-1 or any of the ICRC-1 extension standards (i.e., ICRC-2, ICRC-3,...). + The crate can be installed with the command: ``` @@ -268,43 +95,42 @@ icrc-ledger-types = "0.1.1" [View the documentation for this crate](https://docs.rs/icrc-ledger-types/0.1.1/icrc_ledger_types/). - ### Receiving ICP -If you want a canister to receive payment in ICP you need to make sure that the canister knows about the payment, because a transfer only involves the sender and the ledger canister. +If you want a canister to receive payment in ICP, you need to make sure that the canister knows about the payment because a transfer only involves the sender and the ledger canister. -There are currently two main patterns to achieve this. Furthermore, there is a [chartered working group](https://forum.dfinity.org/t/announcing-technical-working-groups/11781) on Ledger & Tokenization which is focused on defining a standard ledger/token interface as well payment flows. +There are currently two main patterns to achieve this. Furthermore, there is a [chartered working group](https://forum.dfinity.org/t/announcing-technical-working-groups/11781) on ledger and tokenization that is focused on defining a standard ledger token interface and payment flows. #### Direct notification by sender -In this pattern the sender notifies the receiver about the payment. However, the receiver needs to verify the payment by using the [`query_blocks` interface](/docs/current/references/ledger#_getting_ledger_blocks) of the ledger. +In this pattern, the sender notifies the receiver about the payment. However, the receiver needs to verify the payment by using the [`query_blocks` interface](/docs/current/references/ledger#_getting_ledger_blocks) of the ledger. + The following diagram shows a simplified illustration of this pattern: ```plantuml - participant Sender - participant "ICP Ledger" - participant Receiver - - Sender -> "ICP Ledger": transfer() - "ICP Ledger" --> Sender: blockNumber - Sender -> Receiver: notify(blockNumber) - Receiver -> "ICP Ledger": query_blocks(blockNumber) - "ICP Ledger" --> Receiver: block - Receiver -> Receiver: verify payment -``` +    participant Sender +    participant "ICP Ledger" +    participant Receiver +    Sender -> "ICP Ledger": transfer() +    "ICP Ledger" --> Sender: blockNumber +    Sender -> Receiver: notify(blockNumber) +    Receiver -> "ICP Ledger": query_blocks(blockNumber) +    "ICP Ledger" --> Receiver: block +    Receiver -> Receiver: verify payment +``` #### Notification by ICP ledger (currently disabled) -In this pattern the ledger itself notifies the receiver. Thereby, the receiver can trust the notification immediately. However, this flow is currently disabled because the call to the receiver is not yet implemented as a one-way call. +In this pattern, the ledger itself notifies the receiver. Thereby, the receiver can trust the notification immediately. However, this flow is currently disabled because the call to the receiver is not yet implemented as a one-way call. ```plantuml - participant Sender - participant "ICP Ledger" - participant Receiver - - Sender -> "ICP Ledger": transfer() - "ICP Ledger" --> Sender: blockNumber - Sender -> "ICP Ledger": notify(blockNumber, receiver) - "ICP Ledger" -> "Receiver": transaction_notification(details) -``` +    participant Sender +    participant "ICP Ledger" +    participant Receiver + +    Sender -> "ICP Ledger": transfer() +    "ICP Ledger" --> Sender: blockNumber +    Sender -> "ICP Ledger": notify(blockNumber, receiver) +    "ICP Ledger" -> "Receiver": transaction_notification(details) +``` \ No newline at end of file diff --git a/docs/developer-docs/defi/tokens/ledger/usage/icrc1_ledger_usage.mdx b/docs/developer-docs/defi/tokens/ledger/usage/icrc1_ledger_usage.mdx index f631ef6c69..3413fb44da 100644 --- a/docs/developer-docs/defi/tokens/ledger/usage/icrc1_ledger_usage.mdx +++ b/docs/developer-docs/defi/tokens/ledger/usage/icrc1_ledger_usage.mdx @@ -1,215 +1,87 @@ --- -keywords: [intermediate, tokens, icrc, tutorial, ledger] +keywords: [intermediate, tokens, icrc, icrc-1, icrc-2, icrc-3, icrc tokens, tutorial, ledger] --- import { MarkdownChipRow } from "/src/components/Chip/MarkdownChipRow"; -# Using the ICRC-1 ledger +# Using an ICRC-1 ledger -## Overview -There are two main ways to interact with an ICRC-1 ledger. -- `dfx canister`: The generic canister call from `dfx`. -- `ic-cdk`: Inter-canister calls for the ICRC-1 ledger. -- [`ledger-icrc-js`](https://github.com/dfinity/ic-js/tree/main/packages/ledger-icrc): A library for interfacing with ICRC-1 ledger on the Internet Computer. - -## ICRC-1 and ICRC-1 extension endpoints - -Whether your ICRC-1 ledger will have all the endpoints discussed in this tutorial will depend on if you chose to support any of the extensions of ICRC-1 (ICRC-2, ICRC-3,...). -This tutorial will go through the endpoints for ICRC-1 and the extension ICRC-2. If you have deployed an ICRC-1 ledger according to the [guide](/docs/developer-docs/defi/tokens/ledger/setup/icrc1_ledger_setup.mdx) you have to make sure that you have enabled the ICRC-2 standard, otherwise, the calls demonstrated in this guide will not work. - -You can always check which standards are supported by a certain ICRC-1 ledger by calling: - -``` -dfx canister call icrc1_ledger_canister icrc1_supported_standards '()' -``` - -The ICRC-1 ledger used in this guide also supports the extension ICRC-2: - -``` - -( - vec { - record { - url = "https://github.com/dfinity/ICRC-1/tree/main/standards/ICRC-1"; - name = "ICRC-1"; - }; - record { - url = "https://github.com/dfinity/ICRC-1/tree/main/standards/ICRC-2"; - name = "ICRC-2"; - }; - }, -) -``` - -The return values as well as the canister name `icrc1_ledger_canister` in this tutorial are specific to the deployed ICRC-1 ledger and thus may differ to your return values, depending on which values you chose during your [ICRC-1 ledger setup](/docs/developer-docs/defi/tokens/ledger/setup/icrc1_ledger_setup.mdx). - -### ICRC-1 endpoints - -To fetch the symbol of the ICRC-1 ledger: - -``` -dfx canister call icrc1_ledger_canister icrc1_symbol '()' -``` +There are three primary methods used to interact with an ICRC-1 ledger: -This command returns: +- `dfx canister`: The generic canister call from `dfx` used to call a canister's methods. -``` -("XMTK") -``` - -To fetch the decimals of the ICRC-1 ledger: - -``` -dfx canister call icrc1_ledger_canister icrc1_decimals '()' -``` - -This command returns: - -``` -(8 : nat8) -``` +- `ic-cdk`: Inter-canister calls for the ICRC-1 ledger. -To fetch the metadata of the ICRC-1 ledger: +- [`ledger-icrc-js`](https://github.com/dfinity/ic-js/tree/main/packages/ledger-icrc): A library for interfacing with an ICRC-1 ledger on the Internet Computer. -``` -dfx canister call icrc1_ledger_canister icrc1_metadata '()' -``` +## Interact with an ICRC-1 canister using `dfx canister call` -This command returns: +### ICRC-1 -``` -( - vec { - record { "icrc1:decimals"; variant { Nat = 8 : nat } }; - record { "icrc1:name"; variant { Text = "My Token" } }; - record { "icrc1:symbol"; variant { Text = "XMTK" } }; - record { "icrc1:fee"; variant { Nat = 10_000 : nat } }; - record { "icrc1:max_memo_length"; variant { Nat = 32 : nat } }; - }, -) -``` - -To fetch the total supply of the ICRC-1 ledger: +Use the following command syntax to interact with an ICRC-1 ledger via `dfx canister`: ``` -dfx canister call icrc1_ledger_canister icrc1_total_supply '()' +dfx canister call ``` -This command returns: +For example, to fetch the token symbol of an ICRC-1 ledger, call the `icrc1_symbol` method: ``` -(10_000_000_000 : nat) +dfx canister call ss2fx-dyaaa-aaaar-qacoq-cai icrc1_symbol '()' ``` -To fetch the fee of the ICRC-1 ledger: - -``` -dfx canister call icrc1_ledger_canister icrc1_fee '()' -``` +Whether your ICRC-1 ledger will have all available methods enabled will depend on if you choose to support any of the extensions of ICRC-1 (ICRC-2, ICRC-3,...). -This command returns: +You can always check which standards are supported by a certain ICRC-1 ledger by calling: ``` -(10_000 : nat) +dfx canister call icrc1_supported_standards '()' ``` -To fetch the minting account of the ICRC-1 ledger: +You can find all available methods for your ICRC-1 ledger within the ICRC-1 ledger canister's Candid file or, if your ICRC-1 ledger has been deployed to the mainnet, view your ICRC-1 ledger canister [on the dashboard](https://dashboard.internetcomputer.org/canisters). An example of an ICRC-1 ledger deployed on the mainnet that you can reference is the [ckETH ledger canister](https://dashboard.internetcomputer.org/canister/ss2fx-dyaaa-aaaar-qacoq-cai). -``` -dfx canister call icrc1_ledger_canister icrc1_minting_account '()' -``` +View the [`dfx canister call` documentation](/docs/current/developer-docs/developer-tools/cli-tools/cli-reference/dfx-canister#dfx-canister-call) for more information on calling canister methods. -This command returns: - -``` -( - opt record { - owner = principal "rrd6e-uoar3-ehz42-jxkun-ymmmv-jw4rn-re7se-5hymk-aoizl-bfb3j-uqe"; - subaccount = null; - }, -) -``` -To fetch the balance of an account (DEFAULT account in this case, with no subaccount set) on the ICRC-1 ledger: +### ICRC-2 -``` -dfx canister call icrc1_ledger_canister icrc1_balance_of "(record {owner = principal \"${DEFAULT}\"; })" -``` +For ledgers that support ICRC-2, you can call ICRC-2 methods. ICRC-2 methods include those for `approve` workflows. For specifics, see the [ICRC-2 standard](https://github.com/dfinity/ICRC-1/tree/main/standards/ICRC-2#icrc2_approve). -This command returns: +View the [`dfx canister call` documentation](/docs/current/developer-docs/developer-tools/cli-tools/cli-reference/dfx-canister#dfx-canister-call) for more information on calling canister methods. -``` -(10_000_000_000 : nat) -``` +## Interacting with an ICRC-1 ledger from your web application (`ledger-icrc-js`) -Transferring of tokens (from `DEFAULT` to the arbitrary principal `sckqo-e2vyl-4rqqu-5g4wf-pqskh-iynjm-46ixm-awluw-ucnqa-4sl6j-mqe`) on the ICRC-1 ledger: +[View specifications and examples on how to use the `ledger-icrc-js` library to interact with ICRC-1 ledgers](https://github.com/dfinity/ic-js/tree/main/packages/ledger-icrc). -``` -dfx canister call icrc1_ledger_canister icrc1_transfer "(record { to = record { owner = principal \"sckqo-e2vyl-4rqqu-5g4wf-pqskh-iynjm-46ixm-awluw-ucnqa-4sl6j-mqe\";}; amount = 10_000;})" -``` +## Interacting with an ICRC-1 ledger from another canister (inter-canister calls via `ic-cdk`) -This command returns: +View the [inter-canister call documentation] (/docs/developer-docs/backend/rust/intercanister) to see how you can call one canister from within another. -``` -(variant { Ok = 1 : nat }) -``` - -### ICRC-2 endpoints +Here is an example of how to fetch the token name from the ICP ledger using Rust and the `ic-cdk` [library](https://github.com/dfinity/cdk-rs) from within a canister: -To approve tokens to a certain spender (this guide uses the principal `sckqo-e2vyl-4rqqu-5g4wf-pqskh-iynjm-46ixm-awluw-ucnqa-4sl6j-mqe`) you can call: -``` -dfx canister call icrc1_ledger_canister icrc2_approve "(record { amount = 100_000; spender = record{owner = principal \"sckqo-e2vyl-4rqqu-5g4wf-pqskh-iynjm-46ixm-awluw-ucnqa-4sl6j-mqe\";} })" ``` +// You will need the canister ID of the ICRC ledger. -This command returns the block index of the transaction. Since this is the second transaction the index will be 2: +let ledger_id = Principal::from_text("ss2fx-dyaaa-aaaar-qacoq-cai").unwrap(); -``` -(variant { Ok = 2 : nat }) -``` +// The request object of the `icrc1_name` endpoint is empty. -To check the allowance of the spender `sckqo-e2vyl-4rqqu-5g4wf-pqskh-iynjm-46ixm-awluw-ucnqa-4sl6j-mqe` from the previous command you can call: -``` -dfx canister call icrc1_ledger_canister icrc2_allowance "(record { account = record{owner = principal "${DEFAULT}";}; spender = record{owner = principal "sckqo-e2vyl-4rqqu-5g4wf-pqskh-iynjm-46ixm-awluw-ucnqa-4sl6j-mqe";} })" +    let req = (); +    let (res,): (String,) = +        ic_cdk::call(ledger_id, "icrc1_name", (req,)) +            .await.unwrap(); ``` -This command will return the allowance of `sckqo-e2vyl-4rqqu-5g4wf-pqskh-iynjm-46ixm-awluw-ucnqa-4sl6j-mqe` for tokens approved by the `DEFAULT` principal. You should expect this to be the `100_000` tokens you approved earlier: -``` -(record { allowance = 100_000 : nat; expires_at = null }) -``` -Alternatively, you can also set the expiration date for approval. For specifics, see the [ICRC-2 standard](https://github.com/dfinity/ICRC-1/tree/main/standards/ICRC-2#icrc2_approve). - -If the spender now wants to transfer tokens that were previously approved for the spender to a certain principal (in this case, use the arbitrary principal `7tmcj-ukheu-y6dvi-fhmxv-7qs5t-lwgh2-qzojr-vzt6m-maqv4-hvzlg-5qe`) you can call: -``` -dfx canister call icrc1_ledger_canister icrc2_transfer_from "(record { amount = 90_000; from = record{owner = principal \"${DEFAULT}\"}; to= record{owner = principal \"${DEFAULT}\"}; })" -``` -Note that you cannot transfer the entire allowance as the fee for making a transfer has to be substracted from the transferred amount. For the reference implementation the fee is `10_000` tokens. Thus, the maximum amount that can be transferred from `DEFAULT` to `7tmcj-ukheu-y6dvi-fhmxv-7qs5t-lwgh2-qzojr-vzt6m-maqv4-hvzlg-5qe` with the spender `sckqo-e2vyl-4rqqu-5g4wf-pqskh-iynjm-46ixm-awluw-ucnqa-4sl6j-mqe` is `90_000`. -The principal making this call has to be the spender, since they are the one that received the approval. -You will receive the block index as a return value: -``` -(variant { Ok = 3 : nat }) -``` +You can find all available methods for your ICRC-1 ledger within the ICRC-1 ledger canister's Candid file or, if your ICRC-1 ledger has been deployed to the mainnet, view your ICRC-1 ledger canister [on the dashboard](https://dashboard.internetcomputer.org/canisters). An example of an ICRC-1 ledger deployed on the mainnet that you can reference is the [ckETH ledger canister](https://dashboard.internetcomputer.org/canister/ss2fx-dyaaa-aaaar-qacoq-cai). -## Interacting with an ICRC-1 ledger from another canister (inter-canister calls via `ic-cdk`) -You can look at the documentation of [inter-canister calls](/docs/current/developer-docs/backend/rust/intercanister) to see how you can interact with another canister from inside a canister. This guide will give you a couple of examples of how to make such a call in the case of the ICRC-1 ledger. -Here is an example of how to fetch the name from the ICRC-1 ledger using Rust and the `ic-cdk` [library](https://github.com/dfinity/cdk-rs) from within a canister: -You will need the principal of the ICRC-1 ledger. For this guide, take the canister ID that was used in the previous guide on [deploying an ICRC-1 ledger](/docs/developer-docs/defi/tokens/ledger/setup/icrc1_ledger_setup.mdx), which was `mxzaz-hqaaa-aaaar-qaada-cai`. -``` -let ledger_id = Principal::from_text("mxzaz-hqaaa-aaaar-qaada-cai").unwrap(); -// The request object of the `icrc1_name` endpoint is empty. - let req = (); - let (res,): (String,) = - ic_cdk::call(ledger_id, "icrc1_name", (req,)) - .await.unwrap(); -``` +### `icrc-ledger-types` Rust crate -For all other endpoints you can use the request and response structure from the `ledger.did` Candid file. How to retrieve the Candid file is explained in [the guide on deploying an ICRC-1 ledger locally](/docs/developer-docs/defi/tokens/ledger/setup/icrc1_ledger_setup.mdx). +To interact with the ICRC-1 and ICRC-2 endpoints, the Rust crate [icrc-ledger-types](https://crates.io/crates/icrc-ledger-types) can be used. +This is true for the ICP ledger as well as any other canister that supports ICRC-1 or any of the ICRC-1 extension standards (i.e., ICRC-2, ICRC-3,...). -### `icrc-ledger-types` Rust crate -To interact with ICRC-1 and ICRC-2 endpoints, the Rust crate [icrc-ledger-types](https://crates.io/crates/icrc-ledger-types) can be used. It provides data types, request types and response types as well as error types needed for interacting with ICRC-1 endpoints. -This is true for any canister that supports ICRC-1 or any of the ICRC-1 extension standards (i.e ICRC-2, ICRC-3,...). The crate can be installed with the command: ``` @@ -222,7 +94,4 @@ Or, it can be added to the `Cargo.toml` file: icrc-ledger-types = "0.1.1" ``` -View the documentation for [this crate](https://docs.rs/icrc-ledger-types/0.1.1/icrc_ledger_types/). - -## Interacting with an ICRC-1 ledger from your web application (`ledger-icrc-js`) -You will find specifications and examples on how to use the library to interact with ICRC-1 ledgers [here](https://github.com/dfinity/ic-js/tree/main/packages/ledger-icrc). +[View the documentation for this crate](https://docs.rs/icrc-ledger-types/0.1.1/icrc_ledger_types/). diff --git a/docs/developer-docs/defi/tokens/token-standards.mdx b/docs/developer-docs/defi/tokens/token-standards.mdx index da584fea88..7dbbe456a2 100644 --- a/docs/developer-docs/defi/tokens/token-standards.mdx +++ b/docs/developer-docs/defi/tokens/token-standards.mdx @@ -10,7 +10,7 @@ import { GlossaryTooltip } from "/src/components/Tooltip/GlossaryTooltip"; -## Overview + Tokens deployed on ICP must adhere to a standard. The network's native token, ICP, adheres to its own standard as it is unique on the network in the sense that it is used for network utility and governance. Tokens created for other purposes on the network typically adhere to one of the ICRC standards. @@ -20,7 +20,7 @@ In the past, the [DIP-721](#dip-721) standard was promoted and used by projects ### How standards are created -- The [ICRC working group](https://github.com/dfinity/ICRC) creates an initial proposal for an ICRC standard. +- The [ICRC working group](https://github.com/dfinity/ICRC) creates an initial proposal for an ICRC standard. - The proposal is agreed upon through a rough consensus of the working group as a starting point for the standard. @@ -28,13 +28,13 @@ In the past, the [DIP-721](#dip-721) standard was promoted and used by projects - Once the proposal is deemed ready for implementation by the working group, it is proposed to the NNS through an NNS proposal. -- The ICRC standard is either adopted or rejected by the NNS. +- The ICRC standard is either adopted or rejected by the NNS. ## ICP tokens The ICP token is the network's native token used for various utility and governance functions, such as: -- Paying for a canister's resources by being converted into cycles. +- Using tokens and cycles by being converted into cycles. - Rewarding node providers for contributing resources to the network. diff --git a/docs/developer-docs/defi/wallets/overview.mdx b/docs/developer-docs/defi/wallets/overview.mdx index d8a8733fa8..9c58a4b5a0 100644 --- a/docs/developer-docs/defi/wallets/overview.mdx +++ b/docs/developer-docs/defi/wallets/overview.mdx @@ -4,7 +4,7 @@ keywords: [beginner, concept, asset custody, self-custody] import { MarkdownChipRow } from "/src/components/Chip/MarkdownChipRow"; -# Wallet overview +# Wallets diff --git a/docs/developer-docs/defi/wallets/self-custody/hardware-wallet-cli.mdx b/docs/developer-docs/defi/wallets/self-custody/hardware-wallet-cli.mdx index 477f38ae37..2527bd07ce 100644 --- a/docs/developer-docs/defi/wallets/self-custody/hardware-wallet-cli.mdx +++ b/docs/developer-docs/defi/wallets/self-custody/hardware-wallet-cli.mdx @@ -8,7 +8,7 @@ import { MarkdownChipRow } from "/src/components/Chip/MarkdownChipRow"; -## Overview + A hardware wallet is a physical ledger device that is used to store assets. Hardware wallets are protected by a seed phase, similar to software wallets, but they can be disconnected from the internet whenever they are ejected from your computer. diff --git a/docs/developer-docs/defi/wallets/self-custody/self-custody-quickstart.mdx b/docs/developer-docs/defi/wallets/self-custody/self-custody-quickstart.mdx index bb9338257a..495ecb403d 100644 --- a/docs/developer-docs/defi/wallets/self-custody/self-custody-quickstart.mdx +++ b/docs/developer-docs/defi/wallets/self-custody/self-custody-quickstart.mdx @@ -8,7 +8,7 @@ import { MarkdownChipRow } from "/src/components/Chip/MarkdownChipRow"; -## Overview + Within the Internet Computer ecosystem, ICP tokens the network's native utility token and are used in both the governance and economics of the network. This self-custody guide scenario assumes: diff --git a/docs/developer-docs/developer-tools/cli-tools/advanced-dfx/check-chunk-store.mdx b/docs/developer-docs/developer-tools/cli-tools/advanced-dfx/check-chunk-store.mdx index bd468fe91f..02d3574220 100644 --- a/docs/developer-docs/developer-tools/cli-tools/advanced-dfx/check-chunk-store.mdx +++ b/docs/developer-docs/developer-tools/cli-tools/advanced-dfx/check-chunk-store.mdx @@ -8,7 +8,7 @@ import { MarkdownChipRow } from "/src/components/Chip/MarkdownChipRow"; -## Overview + A canister's chunk store must be empty before a Wasm module can be installed in the canister. diff --git a/docs/developer-docs/developer-tools/cli-tools/advanced-dfx/dfx-migration.mdx b/docs/developer-docs/developer-tools/cli-tools/advanced-dfx/dfx-migration.mdx index e4e2383429..8c59cf17c5 100644 --- a/docs/developer-docs/developer-tools/cli-tools/advanced-dfx/dfx-migration.mdx +++ b/docs/developer-docs/developer-tools/cli-tools/advanced-dfx/dfx-migration.mdx @@ -8,7 +8,7 @@ import { MarkdownChipRow } from "/src/components/Chip/MarkdownChipRow"; -## Overview + `dfxvm` is a new tool used for installing and managing different versions of `dfx`. In `dfx` versions 0.17.0 and newer, `dfxvm` is used to install and update `dfx`. This means CI jobs that install `dfx` will need to update their workflow. diff --git a/docs/developer-docs/developer-tools/cli-tools/advanced-dfx/init-args.mdx b/docs/developer-docs/developer-tools/cli-tools/advanced-dfx/init-args.mdx index ee7aff1387..303fd7bd2a 100644 --- a/docs/developer-docs/developer-tools/cli-tools/advanced-dfx/init-args.mdx +++ b/docs/developer-docs/developer-tools/cli-tools/advanced-dfx/init-args.mdx @@ -8,7 +8,7 @@ import { MarkdownChipRow } from "/src/components/Chip/MarkdownChipRow"; -## Overview + When installing a canister's code, it may require Candid initialization arguments to be passed with the `dfx canister install` command. Initialization arguments are initial configuration parameters that the canister's installation expects in order to install the code correctly. One example of a canister that requires these Candid initialization arguments is the [ICP ledger canister](/docs/developer-docs/defi/tokens/ledger/setup/icp_ledger_setup.mdx). diff --git a/docs/developer-docs/developer-tools/cli-tools/advanced-dfx/networks-json.mdx b/docs/developer-docs/developer-tools/cli-tools/advanced-dfx/networks-json.mdx index 35ff6589a3..67f97dc149 100644 --- a/docs/developer-docs/developer-tools/cli-tools/advanced-dfx/networks-json.mdx +++ b/docs/developer-docs/developer-tools/cli-tools/advanced-dfx/networks-json.mdx @@ -8,7 +8,7 @@ import { MarkdownChipRow } from "/src/components/Chip/MarkdownChipRow"; -## Overview + When developing multiple projects simultaneously, it can be beneficial to deploy each project to a different local network for simplicity or to support different development workflows. Custom networks can be configured with `dfx` at both the system-wide and project-specific levels. diff --git a/docs/developer-docs/developer-tools/cli-tools/advanced-dfx/specifying-replica-version.mdx b/docs/developer-docs/developer-tools/cli-tools/advanced-dfx/specifying-replica-version.mdx index 6ea2e4911f..a8111425e6 100644 --- a/docs/developer-docs/developer-tools/cli-tools/advanced-dfx/specifying-replica-version.mdx +++ b/docs/developer-docs/developer-tools/cli-tools/advanced-dfx/specifying-replica-version.mdx @@ -8,7 +8,7 @@ import { MarkdownChipRow } from "/src/components/Chip/MarkdownChipRow"; -## Overview + The replica version included in the most recent release of `dfx` may not reflect the most up to date replica release. In some workflows, such as testing new features of the replica, having the most recent version of the replica may be desirable. diff --git a/docs/developer-docs/developer-tools/cli-tools/dfx-json-reference.mdx b/docs/developer-docs/developer-tools/cli-tools/dfx-json-reference.mdx index 261fab6d26..a83420a877 100644 --- a/docs/developer-docs/developer-tools/cli-tools/dfx-json-reference.mdx +++ b/docs/developer-docs/developer-tools/cli-tools/dfx-json-reference.mdx @@ -8,7 +8,7 @@ import { MarkdownChipRow } from "/src/components/Chip/MarkdownChipRow"; -## Overview + This is the schema reference for `dfx.json` in [JSON Schema](https://json-schema.org) format. diff --git a/docs/developer-docs/developer-tools/cli-tools/dfx-json.mdx b/docs/developer-docs/developer-tools/cli-tools/dfx-json.mdx index 1aa03f716a..4cac13434f 100644 --- a/docs/developer-docs/developer-tools/cli-tools/dfx-json.mdx +++ b/docs/developer-docs/developer-tools/cli-tools/dfx-json.mdx @@ -8,7 +8,7 @@ import { MarkdownChipRow } from "/src/components/Chip/MarkdownChipRow"; -## Overview + Every project created and deployed with `dfx` requires a `dfx.json` file to be present in the project's root directory. The `dfx.json` file configures the project's settings such as the canisters in the project, their name, type, and source file, default project build settings, and other configuration parameters such as Wasm optimizations. This page will detail some of the most common configuration options. For a full list of the possible configuration settings in `dfx.json`, view the [`dfx.json` schema](/docs/current/developer-docs/developer-tools/cli-tools/dfx-json-reference). diff --git a/docs/developer-docs/developer-tools/cli-tools/idl2json.mdx b/docs/developer-docs/developer-tools/cli-tools/idl2json.mdx index 1c3510d08a..af541dc789 100644 --- a/docs/developer-docs/developer-tools/cli-tools/idl2json.mdx +++ b/docs/developer-docs/developer-tools/cli-tools/idl2json.mdx @@ -9,7 +9,7 @@ import { MarkdownChipRow } from "/src/components/Chip/MarkdownChipRow"; -## Overview + [`idl2json`](https://github.com/dfinity/idl2json/tree/main) is a command-line tool used to translate [Candid](https://github.com/dfinity/candid) textual values from `stdin` into JSON values outputted in `stdout`. diff --git a/docs/developer-docs/developer-tools/dev-tools-overview.mdx b/docs/developer-docs/developer-tools/dev-tools-overview.mdx index 9f85247401..f7bdecefa8 100644 --- a/docs/developer-docs/developer-tools/dev-tools-overview.mdx +++ b/docs/developer-docs/developer-tools/dev-tools-overview.mdx @@ -4,12 +4,10 @@ keywords: [beginner, developer tools, dev tools, overview] import { MarkdownChipRow } from "/src/components/Chip/MarkdownChipRow"; -# Developer tool overview +# Developer tooling -## Overview - Developer tools are used to create, manage, and interact with canisters. They can come in several formats, such as command line tools, onchain and off-chain libraries, and integrated development environments. For ICP developers, there are tools within each of these categories available for you to utilize when developing your ICP canisters. ## Command line diff --git a/docs/developer-docs/developer-tools/ide/codespaces.mdx b/docs/developer-docs/developer-tools/ide/codespaces.mdx index 512bb6e828..5f8643ae45 100644 --- a/docs/developer-docs/developer-tools/ide/codespaces.mdx +++ b/docs/developer-docs/developer-tools/ide/codespaces.mdx @@ -10,7 +10,7 @@ import '/src/components/CenterImages/center.scss'; -## Overview + GitHub Codespaces is a web-based cloud development environment that provides a platform for developing and deploying code without downloading any necessary tools or packages. GitHub Codespaces can be configured with a local ICP developer environment, including `dfx` and an instance of the ICP replica, to support canister development. diff --git a/docs/developer-docs/developer-tools/ide/dev-containers.mdx b/docs/developer-docs/developer-tools/ide/dev-containers.mdx index df63d12a89..75f7d67252 100644 --- a/docs/developer-docs/developer-tools/ide/dev-containers.mdx +++ b/docs/developer-docs/developer-tools/ide/dev-containers.mdx @@ -9,7 +9,7 @@ import '/src/components/CenterImages/center.scss'; -## Overview + Developer containers are a local development option that uses [Docker](https://www.docker.com/get-started/) and [VS Code](https://code.visualstudio.com/) to run local containerized environments. Containers are isolated from the rest of your local environment, and files within a container cannot be used by applications outside of the container unless explicitly mounted and given access. Developer containers are a good option for developers on Windows systems, since `dfx` is not natively supported for local development on Windows. diff --git a/docs/developer-docs/developer-tools/ide/gitpod.mdx b/docs/developer-docs/developer-tools/ide/gitpod.mdx index 42f512d223..8d50c5c768 100644 --- a/docs/developer-docs/developer-tools/ide/gitpod.mdx +++ b/docs/developer-docs/developer-tools/ide/gitpod.mdx @@ -11,7 +11,7 @@ import '/src/components/CenterImages/center.scss'; -## Overview + Gitpod is a web-based cloud development environment that provides a platform for developing and deploying code without downloading any necessary tools or packages. Gitpod can be configured with a local ICP developer environment, including `dfx` and an instance of the ICP replica, to support canister development. diff --git a/docs/developer-docs/developer-tools/ide/icp-ninja.mdx b/docs/developer-docs/developer-tools/ide/icp-ninja.mdx index 6d4658bfed..5d21ce68d2 100644 --- a/docs/developer-docs/developer-tools/ide/icp-ninja.mdx +++ b/docs/developer-docs/developer-tools/ide/icp-ninja.mdx @@ -9,7 +9,7 @@ import '/src/components/CenterImages/center.scss'; -## Overview + [ICP Ninja](https://icp.ninja/) is a web-based code editor and deployment environment for ICP canister smart contracts. Users can choose from a gallery of example projects, then edit and deploy the project directly to ICP without downloading `dfx` or obtaining cycles. Projects will be live for 20 minutes unless redeployed. The deployment timer resets on each deployment. diff --git a/docs/developer-docs/developer-tools/ide/playground.mdx b/docs/developer-docs/developer-tools/ide/playground.mdx index 22aebd7f8b..deddb9a878 100644 --- a/docs/developer-docs/developer-tools/ide/playground.mdx +++ b/docs/developer-docs/developer-tools/ide/playground.mdx @@ -10,7 +10,7 @@ import '/src/components/CenterImages/center.scss'; -## Overview + Deploying a canister to the playground is ICP's equivalent of deploying to a testnet network. It can be used through `dfx` using the `--network playground` flag, however the playground is also available through a frontend canister, which can be accessed at the following public URL: diff --git a/docs/developer-docs/developer-tools/ide/vs-code.mdx b/docs/developer-docs/developer-tools/ide/vs-code.mdx index 0e8fc10015..b6ca607c1e 100644 --- a/docs/developer-docs/developer-tools/ide/vs-code.mdx +++ b/docs/developer-docs/developer-tools/ide/vs-code.mdx @@ -9,7 +9,7 @@ import { MarkdownChipRow } from "/src/components/Chip/MarkdownChipRow"; -## Overview + Visual Studio (VS) Code is a [widely used](https://survey.stackoverflow.co/2022/#section-worked-with-vs-want-to-work-with-integrated-development-environment) open-source IDE which supports canister development in [Motoko](/docs/current/motoko/main/getting-started/motoko-introduction) and [Rust](https://www.rust-lang.org/). diff --git a/docs/developer-docs/developer-tools/off-chain/agents/javascript-agent.mdx b/docs/developer-docs/developer-tools/off-chain/agents/javascript-agent.mdx index 96a8f6af82..c87bdb925d 100644 --- a/docs/developer-docs/developer-tools/off-chain/agents/javascript-agent.mdx +++ b/docs/developer-docs/developer-tools/off-chain/agents/javascript-agent.mdx @@ -8,7 +8,7 @@ import { MarkdownChipRow } from "/src/components/Chip/MarkdownChipRow"; -## Overview + An agent is an API client used to interact with ICP. The [ICP JavaScript agent](https://www.npmjs.com/package/@dfinity/agent) is used to interact with the public ICP API endpoints and canisters deployed on ICP. ICP JavaScript agent provides `call`, `query`, and `readState` methods, along with other utilities, to an actor. diff --git a/docs/developer-docs/developer-tools/off-chain/agents/nodejs.mdx b/docs/developer-docs/developer-tools/off-chain/agents/nodejs.mdx index ad43265796..0d61cf6484 100644 --- a/docs/developer-docs/developer-tools/off-chain/agents/nodejs.mdx +++ b/docs/developer-docs/developer-tools/off-chain/agents/nodejs.mdx @@ -8,7 +8,7 @@ import { MarkdownChipRow } from "/src/components/Chip/MarkdownChipRow"; -## Overview + [Node.js](https://nodejs.org/en) is a runtime environment for JavaScript. To interact with a canister through Node.js, you can use the [JavaScript agent](https://www.npmjs.com/package/@dfinity/agent). Using Node.js can enable use cases such as running an oracle, connecting an existing Node.js application to ICP, or introducing a websocket layer to your application. diff --git a/docs/developer-docs/developer-tools/off-chain/agents/overview.mdx b/docs/developer-docs/developer-tools/off-chain/agents/overview.mdx index 6dcf58037e..59b34d2d18 100644 --- a/docs/developer-docs/developer-tools/off-chain/agents/overview.mdx +++ b/docs/developer-docs/developer-tools/off-chain/agents/overview.mdx @@ -4,7 +4,7 @@ keywords: [intermediate, agents, overview, javascript, rust, nodejs] import { MarkdownChipRow } from "/src/components/Chip/MarkdownChipRow"; -# Agents overview +# What are the ICP agents? diff --git a/docs/developer-docs/developer-tools/off-chain/agents/rust-agent.mdx b/docs/developer-docs/developer-tools/off-chain/agents/rust-agent.mdx index 7dcd66e3e7..559726cf0c 100644 --- a/docs/developer-docs/developer-tools/off-chain/agents/rust-agent.mdx +++ b/docs/developer-docs/developer-tools/off-chain/agents/rust-agent.mdx @@ -8,7 +8,7 @@ import { MarkdownChipRow } from "/src/components/Chip/MarkdownChipRow"; -## Overview + The [ICP Rust agent](https://docs.rs/ic-agent/latest/ic_agent/) by DFINITY is a simple library that enables you to build applications and interact with ICP, serving as a low-level Rust backend for the IC SDK. diff --git a/docs/developer-docs/developer-tools/off-chain/canbench.mdx b/docs/developer-docs/developer-tools/off-chain/canbench.mdx index b134bf5e52..4779db201d 100644 --- a/docs/developer-docs/developer-tools/off-chain/canbench.mdx +++ b/docs/developer-docs/developer-tools/off-chain/canbench.mdx @@ -8,7 +8,7 @@ import { MarkdownChipRow } from "/src/components/Chip/MarkdownChipRow"; -## Overview + Canisters deployed on ICP use resources such as memory and compute. Resources are finite, and there are limits configured that restrict how many resources a canister may consume. The `canbench` Rust crate provides a way to benchmark a canister's resources so developers can gain an insight into how their canister uses memory, instructions, and other resources. diff --git a/docs/developer-docs/developer-tools/off-chain/canpack.mdx b/docs/developer-docs/developer-tools/off-chain/canpack.mdx index 842e8e025e..4bc198a15f 100644 --- a/docs/developer-docs/developer-tools/off-chain/canpack.mdx +++ b/docs/developer-docs/developer-tools/off-chain/canpack.mdx @@ -8,7 +8,7 @@ import { MarkdownChipRow } from "/src/components/Chip/MarkdownChipRow"; -## Overview + Canpack is a code generation tool designed to simplify communication across canisters written in different languages. It currently supports calling a Rust crate from Motoko code. Canpack generates a separate canister for the host language, then combines the other language's code fragments that are defined across different libraries. diff --git a/docs/developer-docs/developer-tools/on-chain/cdks.mdx b/docs/developer-docs/developer-tools/on-chain/cdks.mdx index 7c635e2f4d..51b2841077 100644 --- a/docs/developer-docs/developer-tools/on-chain/cdks.mdx +++ b/docs/developer-docs/developer-tools/on-chain/cdks.mdx @@ -8,7 +8,7 @@ import { MarkdownChipRow } from "/src/components/Chip/MarkdownChipRow"; -## Overview + Canister development kits (CDKs) are used to interface with the IC SDK and provide different programming languages with the necessary functionalities to develop canisters. These functionalities include the ability to create, deploy, call, and manage canisters, both locally deployed and deployed to the mainnet. diff --git a/docs/developer-docs/developer-tools/on-chain/ic-js.mdx b/docs/developer-docs/developer-tools/on-chain/ic-js.mdx index b7b0eb10b1..f05979a80c 100644 --- a/docs/developer-docs/developer-tools/on-chain/ic-js.mdx +++ b/docs/developer-docs/developer-tools/on-chain/ic-js.mdx @@ -8,7 +8,7 @@ import { MarkdownChipRow } from "/src/components/Chip/MarkdownChipRow"; -## Overview + `ic-js` is a collection of JavaScript libraries that can be used to interface with ICP. Each library can be used independently from one another, or a project can use all of the libraries together. The NNS dapp is an example demonstration of all `ic-js` libraries being used together. diff --git a/docs/developer-docs/gas-cost.mdx b/docs/developer-docs/gas-cost.mdx index 8a35ed2ae8..60ed6eb91f 100644 --- a/docs/developer-docs/gas-cost.mdx +++ b/docs/developer-docs/gas-cost.mdx @@ -8,7 +8,7 @@ import { MarkdownChipRow } from "/src/components/Chip/MarkdownChipRow"; -## Overview + Canister smart contracts pay for consumed resources (storage, messaging, execution, and special features) by burning **cycles**. Developers can obtain cycles by converting ICP tokens into cycles using [`dfx`](/docs/current/developer-docs/defi/cycles/converting_icp_tokens_into_cycles). diff --git a/docs/developer-docs/getting-started/deploy-and-manage.mdx b/docs/developer-docs/getting-started/deploy-and-manage.mdx index e799e4b793..4371776652 100644 --- a/docs/developer-docs/getting-started/deploy-and-manage.mdx +++ b/docs/developer-docs/getting-started/deploy-and-manage.mdx @@ -10,17 +10,15 @@ import { BetaChip } from "/src/components/Chip/BetaChip"; import { MarkdownChipRow } from "/src/components/Chip/MarkdownChipRow"; import { GlossaryTooltip } from "/src/components/Tooltip/GlossaryTooltip"; -# Deploy and manage +# Deploying and managing canisters -## Overview - Once a canister's code has been written, it must be compiled into Wasm, installed into the canister itself, and then deployed to a network. The `dfx deploy` command executes each of these tasks as part of the deployment process; however, `dfx` commands also exist for running each step individually. It is recommended to deploy canisters locally or to the temporary [playground](/docs/current/developer-docs/smart-contracts/deploy/overview#deploying-to-playground) network to test canister functionality and make adjustments before considering the canister production-ready and deploying it to the mainnet. Deploying canisters locally and to the playground is free and does not cost cycles. Once a canister is deployed to the mainnet, it will consistently consume cycles and will need to be topped up periodically. -## Start the local replica +## Starting the local replica To deploy your canister locally, first start the local replica. This simulates the mainnet environment with a single node for local development and testing. @@ -28,8 +26,7 @@ To deploy your canister locally, first start the local replica. This simulates t - `dfx start --background`: Runs the processes in the background and allows you to continue running commands in the current terminal. - -## Deploy locally +## Deploying the project locally Deploy the backend canister that you have written code for: @@ -73,7 +70,7 @@ Your deployed canister will now be executing two timers and printing the output You can interact with the canister's public methods either in your web browser through the [Candid UI](/docs/current/developer-docs/smart-contracts/candid/candid-concepts) URL that was returned in the deployment output or using the command line. Candid is an interface description language used to interact with a canister's public methods. -## Upgrades +## Upgrading canisters Canisters can be upgraded, allowing the same canister ID to be retained for an application. Upgrades preserve the state of a canister while allowing you to change the code. However, canister upgrades clear the canister's Wasm memory. Any data not stored in [stable memory](/docs/current/developer-docs/smart-contracts/maintain/storage) will be removed. @@ -106,7 +103,7 @@ Confirm that the change you made results in the expected functionality or behavi dfx canister stop PROJECT_NAME_backend --network=local ``` -## Deploy to the mainnet +## Deploying your project to the mainnet Now that the canister has been tested, you can deploy it to the mainnet. **Deploying to the mainnet costs [cycles](/docs/current/developer-docs/getting-started/tokens-and-cycles).** @@ -142,7 +139,7 @@ URLs: When a canister is running on the mainnet, you will always need to pass the `--network=ic` flag to interact with it. ::: -## Settings +## Canister settings After a canister is deployed to the mainnet, it will constantly be consuming resources and cycles. To view information about how many resources and cycles currently being used, along with other information, view the canister's settings: @@ -210,7 +207,7 @@ Log visibility: controllers -## Topping up +## Topping up canisters A canister will burn cycles even in an idle state to pay for the network storage it uses. Additional costs will be charged whenever the canister sends and receives messages, uses compute resources, or uses special features like HTTPS outcalls and threshold signatures. @@ -236,7 +233,7 @@ Manually monitoring canisters to determine when they are getting close to the fr - [ICPTopup.com](https://www.icptopup.com/): A simplified version of CycleOps that allows you to top up several canisters (up to 50) at one time. -### Freezing threshold +### Cycles freezing threshold To prevent a canister from running out of cycles and being deleted, you can set what is known as a **freezing threshold**. This threshold is a duration of time set in seconds, indicating the minimum duration that the canister should exist without running out of cycles. Once a canister hits this threshold, it will not execute messages. It will only pay for the network resources it uses, such as compute allocation, memory usage, and storage allocation. @@ -251,7 +248,7 @@ If you set a freezing threshold longer than 1.5 years, you will need to include ::: -## Logging +## Canister logging [Canister logs](/docs/current/developer-docs/smart-contracts/maintain/logs) can be used to gain insight into a canister's behavior and assist with debugging situations such as when a canister traps. @@ -267,7 +264,7 @@ By default, canister logs are only visible to the canister's controllers, but th dfx canister update-settings PROJECT_NAME_backend --network=ic --log-visibility public ``` -## Snapshots +## Canister snapshots Canister snapshots are used as a checkpoint that can be used to roll back your canister to a previous version in the event that the latest upgraded version becomes unresponsive or stops working as expected. @@ -329,16 +326,12 @@ Any cycles remaining in the canister's balance will be returned to your develope dfx canister delete PROJECT_NAME_backend --network=ic ``` -## Stopping `dfx` +## Stopping the local replica -To stop `dfx`, simply use the `dfx stop` command. +To stop the local replica, simply use the `dfx stop` command. For unresponsive `dfx` processes that are not stopped by `dfx stop`, you can use `dfx killall` to forcibly end them. ## Getting help To view help information for `dfx`, you can use the `dfx help` command or view the [`dfx` reference documentation](/docs/current/developer-docs/developer-tools/cli-tools/cli-reference/). - -## Next steps - -- [x] View the [developer next steps](/docs/current/developer-docs/getting-started/next-steps). diff --git a/docs/developer-docs/getting-started/deploy/local.mdx b/docs/developer-docs/getting-started/deploy/local.mdx deleted file mode 100644 index 872a6b84a2..0000000000 --- a/docs/developer-docs/getting-started/deploy/local.mdx +++ /dev/null @@ -1,235 +0,0 @@ ---- -keywords: [beginner, tutorial, local deployment, deploy] ---- - - -import { MarkdownChipRow } from "/src/components/Chip/MarkdownChipRow"; -import { GlossaryTooltip } from "/src/components/Tooltip/GlossaryTooltip"; - - -# Local deployment - - - -## Overview - -When developing canisters and projects, it is recommended to first deploy your project to the local development environment. This is so you can fabricate cycles in your local development environment, which you cannot do on the mainnet. Cycles are charged for the resources used by your canister. [Learn more about cycles](/docs/current/developer-docs/gas-cost). - -Deploying to your local development environment is similar to deploying to a testnet. ICP does not have a testnet available for developers to deploy to. Instead, the IC SDK runs a local version of the ICP node software known as the **replica** and provides a single-node environment on your local machine for you to deploy canisters to. - -## Prerequisites - -Before you create your first canister, verify the following: - --   [x] You have an internet connection and access to a shell terminal on your local computer. - --   [x] You have `Node.js` `16.0.0` or newer installed if you want to include the default template files for frontend development in your project. - --   [x] You have downloaded and installed the IC SDK package as described in the [installing the IC SDK](/docs/current/developer-docs/getting-started/install/) page. - -## Start the local deployment - -Before you can build your first project, you need to connect to the local replica. As a best practice, this step requires you to have **two terminal shells** open, so that you can start and see canister execution operations in one terminal and manage your project in another. - -To prepare the local replica: - -- #### Step 1:  Open a new second terminal window or tab on your local computer. - -- #### Step 2:  Navigate to the root directory for your project, if necessary. - -You should now have **two terminals** open with your **project directory** as your **current working directory** in both terminals. - -- #### Step 3:  Start the local replica on your computer in your second terminal by running the following command: - -``` -dfx start -``` - -Depending on your platform and local security settings, you might see a warning displayed. If you are prompted to allow or deny incoming network connections, click **Allow**. - -- #### Step 4:  Leave the terminal window that displays canister execution operations open and switch your focus to the first terminal window where you created your new project. - -You should perform the remaining steps in the terminal that doesn’t display canister execution operations. - -## Register, build, and deploy the application - -After you connect to the local canister execution environment, you can register, build, and deploy your dapp locally. - -To deploy your first canister locally: - -- #### Step 1:  Check that you are still in the root directory for your project, if needed. - -It is recommended to follow the [creating your first canister](/docs/current/developer-docs/getting-started/default-template) guide to have a simple 'Hello, world!' canister ready to deploy. - -- #### Step 2:  Ensure that `node` modules are available in your project directory, if needed, by running the following command: - -``` -npm install -``` - -For more information about this step, see [ensuring node is available in a project](/docs/current/developer-docs/getting-started/install/#nodejs-is-not-properly-installed). - -- #### Step 3:  Register, build, and deploy your first dapp by running the following command: - -``` -dfx deploy -``` - -The `dfx deploy` command output displays information about the operations it performs. For example, this step registers two identifiers. One is for the `hello_backend` main program, and the other is for the `hello_frontend` frontend user interface and installation information similar to the following: - -``` -Creating a wallet canister on the local network. -The wallet canister on the "local" network for user "mainnet" is "rwlgt-iiaaa-aaaaa-aaaaa-cai" -Deploying all canisters. -Creating canisters... -Creating canister hello_backend... -hello_backend canister created with canister id: rrkah-fqaaa-aaaaa-aaaaq-cai -Creating canister hello_frontend... -hello_frontend canister created with canister id: ryjl3-tyaaa-aaaaa-aaaba-cai -Building canisters... -Building frontend... -Installing canisters... -Creating UI canister on the local network. -The UI canister on the "local" network is "r7inp-6aaaa-aaaaa-aaabq-cai" -Installing code for canister hello_backend, with canister ID rrkah-fqaaa-aaaaa-aaaaq-cai -Installing code for canister hello_frontend, with canister ID ryjl3-tyaaa-aaaaa-aaaba-cai -Uploading assets to asset canister... -Starting batch. -Staging contents of new and changed assets: -  /sample-asset.txt 1/1 (24 bytes) -  /logo2.svg 1/1 (15139 bytes) -  /index.js.map 1/1 (681670 bytes) -  /index.js.map (gzip) 1/1 (156940 bytes) -  /favicon.ico 1/1 (15406 bytes) -  /main.css 1/1 (537 bytes) -  /main.css (gzip) 1/1 (297 bytes) -  /index.html 1/1 (690 bytes) -  /index.html (gzip) 1/1 (386 bytes) -  /index.js (gzip) 1/1 (152884 bytes) -  /index.js 1/1 (637230 bytes) -Committing batch. -Deployed canisters. -URLs: -  Frontend canister via browser -    hello_frontend: http://127.0.0.1:4943/?canisterId=ryjl3-tyaaa-aaaaa-aaaba-cai -  Backend canister via Candid interface: -    hello_backend: http://127.0.0.1:4943/?canisterId=r7inp-6aaaa-aaaaa-aaabq-cai&id=rrkah-fqaaa-aaaaa-aaaaq-cai -``` - -If you create a project with a different name, however, your canister names will match your project name instead of `hello_backend` and `hello_frontend`. - -## Call the canister from the CLI - -Call the `hello_backend` canister and the predefined `greet` function by running the following command: - -``` -dfx canister call hello_backend greet everyone -``` - -Let’s take a closer look at this example command: - --   The `dfx canister call` command requires you to specify a canister name and a method or function to call. - --   `hello_backend` specifies the name of the **canister** you want to call. - --   `greet` specifies the name of the **function** you want to call in the `hello` canister. - --   `everyone` is the text data type argument that you want to pass to the `greet` function. - -Remember, however, that if you create a project with a different name, the canister name will match your project name, and you’ll need to modify the command line to match the name you used instead of `hello_backend`. If you were to choose `test` as the project name, your backend canister would be called `test_backend` and the frontend canister `test_frontend`. - -Verify the command displays the return value of the `greet` function. For example: - -``` -("Hello, everyone!") -``` - -## Call the canister from the browser - -It is possible to access the frontend canister directly from the browser. You will need to navigate to the URL that was printed in the output of the `dfx deploy` command (your URL might differ): - -``` -Frontend canister via browser -    hello_frontend: http://127.0.0.1:4943/?canisterId=bd3sg-teaaa-aaaaa-qaaba-cai -``` - -This will render a webpage with a form that accepts a string and sends it to the backend canister. - -The source code of the webpage is defined in the `src/hello_frontend/src/index.{html,js}` files. - -```html title="src/hello_frontend/src/index.html" - - -  -    -    -    hello -    -    -    -  -  -   
-      DFINITY logo -     
-     
-     
-        -        -        -     
-     
-   
-  - -``` - -```javascript title="src/hello_frontend/src/index.js" -import { hello_backend } from "../../declarations/hello_backend"; - -document.querySelector("form").addEventListener("submit", async (e) => { -  e.preventDefault(); -  const button = e.target.querySelector("button"); - -  const name = document.getElementById("name").value.toString(); - -  button.setAttribute("disabled", true); - -  // Interact with foo actor, calling the greet method -  const greeting = await hello_backend.greet(name); - -  button.removeAttribute("disabled"); - -  document.getElementById("greeting").innerText = greeting; - -  return false; -}); -``` - -The JavaScript code running in the browser uses the [ICP JavaScript agent](/docs/current/developer-docs/developer-tools/off-chain/agents/javascript-agent) library to interact with the backend canister. The library creates a wrapper JavaScript object based on the interface of the canister. That wrapper object provides convenience methods for calling the canister functions as if they were JavaScript functions: - -``` -const greeting = await hello_backend.greet(name); -``` - -## Stop the local canister execution environment - -After testing the application in the browser, you can stop the local canister execution environment so that it doesn’t continue running in the background. - -To stop the local deployment: - -- #### Step 1:  In the terminal that displays the development server, press Control-C to interrupt the development server process. - -- #### Step 2:  In the terminal that displays canister execution operations, press Control-C to interrupt the local network process. - -- #### Step 3:  Stop the local replica running on your local computer by running the following command: - -``` -dfx stop -``` - -## Next steps - -Next, you can deploy your canister on the playground. - -- [Testnet deployment](/docs/current/developer-docs/getting-started/deploy/testnet) \ No newline at end of file diff --git a/docs/developer-docs/getting-started/deploy/mainnet.mdx b/docs/developer-docs/getting-started/deploy/mainnet.mdx deleted file mode 100644 index 00af98dab0..0000000000 --- a/docs/developer-docs/getting-started/deploy/mainnet.mdx +++ /dev/null @@ -1,186 +0,0 @@ ---- -keywords: [beginner, tutorial, mainnet deployment, deploy] ---- - -import { MarkdownChipRow } from "/src/components/Chip/MarkdownChipRow"; -import { GlossaryTooltip } from "/src/components/Tooltip/GlossaryTooltip"; - - -# Mainnet deployment - - - -## Overview - -To make your canister available to others, you must deploy it to the mainnet. - -If you are only deploying projects in a local development environment, see the [local development](/docs/current/developer-docs/getting-started/deploy/local) scenario. - -## Prerequisites - -Before you download and install this release of the IC SDK, verify the following: - -- [x] You have an internet connection and access to a shell terminal on your local computer. - -- [x] You have `Node.js` `16.0.0` or newer installed if you want to access the default frontend for the default project. - -- [x] You have ICP tokens or cycles available for you to use. - -:::info -You must have **cycles** available to complete this guide. To get cycles, you must either convert ICP tokens to cycles or be provided cycles from another source, for example, from a canister controlled by another developer or from a third-party cycles provider. This guide assumes that you have an account with ICP tokens available and illustrates how to convert ICP tokens into cycles. - -For information about how to get ICP tokens, see [how you can get ICP tokens](/docs/current/developer-docs/defi/cycles/converting_icp_tokens_into_cycles). - -For an introduction to using the Network Nervous System application to manage ICP tokens, see [Network Nervous System dapp quickstart](/docs/current/developer-docs/daos/nns/using-the-nns-dapp/nns-app-quickstart). -::: - -## Check the connection to the mainnet - -There is a reserved network alias that you can use to access the mainnet. The network alias is a system setting that’s defined internally, so there’s nothing you need to configure in your projects by default. - -To check your connection to ICP: - -- #### Step 1: Check that you are in the root directory for your project, if needed. - -- #### Step 2: Check the current status of ICP and your ability to connect to it by running the following command for the network alias `ic`: - -``` -dfx ping ic -``` - -- #### Step 3: Verify that the `dfx ping ic` command returns information about ICP. - - For example, you should see output similar to the following: -``` -{ - "ic_api_version": "0.18.0" "impl_hash": "d639545e0f38e075ad240fd4ec45d4eeeb11e1f67a52cdd449cd664d825e7fec" "impl_version": "8dc1a28b4fb9605558c03121811c9af9701a6142" "replica_health_status": "healthy" "root_key": [48, 129, 130, 48, 29, 6, 13, 43, 6, 1, 4, 1, 130, 220, 124, 5, 3, 1, 2, 1, 6, 12, 43, 6, 1, 4, 1, 130, 220, 124, 5, 3, 2, 1, 3, 97, 0, 129, 76, 14, 110, 199, 31, 171, 88, 59, 8, 189, 129, 55, 60, 37, 92, 60, 55, 27, 46, 132, 134, 60, 152, 164, 241, 224, 139, 116, 35, 93, 20, 251, 93, 156, 12, 213, 70, 217, 104, 95, 145, 58, 12, 11, 44, 197, 52, 21, 131, 191, 75, 67, 146, 228, 103, 219, 150, 214, 91, 155, 180, 203, 113, 113, 18, 248, 71, 46, 13, 90, 77, 20, 80, 95, 253, 116, 132, 176, 18, 145, 9, 28, 95, 135, 185, 136, 131, 70, 63, 152, 9, 26, 11, 170, 174] -} -``` - -## Register, build, and deploy the application - -After you have a [cycles balance](/docs/current/developer-docs/getting-started/tokens-and-cycles), you can register, build, and deploy your sample application. - -To deploy your first application on the mainnet: - -- #### Step 1: In your terminal shell, check that you are still in the root directory for your project. - -- #### Step 2: Ensure that `node` modules are available in your project directory, if needed, by running the following command: - -``` -npm install -``` - -For more information about this step, see [ensuring node is available in a project](/docs/current/developer-docs/getting-started/install). - -- #### Step 3: Register, build, and deploy your first application by running the following command: - -``` -dfx deploy --network ic -``` - -The `--network` option specifies the network alias or URL for deploying the dapp. This option is required to deploy your canister on the mainnet. - -The `dfx deploy` command output displays information about the operations it performs. - -For example, this step registers two identifiers—one for the `hello_backend` main program and one for the `hello_frontend` frontend user interface—and installation information similar to the following: - -``` -Deploying all canisters. -Creating canisters... -Creating canister "hello_backend"... -"hello" canister created on network "ic" with canister id: "5o6tz-saaaa-aaaaa-qaacq-cai" -Creating canister "hello_frontend"... -"hello_assets" canister created on network "ic" with canister id: "5h5yf-eiaaa-aaaaa-qaada-cai" -Building canisters... -Building frontend... -Installing canisters... -Installing code for canister hello_backend, with canister_id 5o6tz-saaaa-aaaaa-qaacq-cai -Installing code for canister hello_frontend, with canister_id 5h5yf-eiaaa-aaaaa-qaada-cai -Authorizing our identity (default) to the asset canister... -Uploading assets to asset canister... - /index.html 1/1 (472 bytes) - /index.html (gzip) 1/1 (314 bytes) - /index.js 1/1 (260215 bytes) - /index.js (gzip) 1/1 (87776 bytes) - /main.css 1/1 (484 bytes) - /main.css (gzip) 1/1 (263 bytes) - /sample-asset.txt 1/1 (24 bytes) - /logo.png 1/1 (25397 bytes) - /index.js.map 1/1 (842511 bytes) - /index.js.map (gzip) 1/1 (228404 bytes) - /index.js.LICENSE.txt 1/1 (499 bytes) - /index.js.LICENSE.txt (gzip) 1/1 (285 bytes) -Deployed canisters. -``` - -If you didn’t convert enough ICP tokens to cycles to complete the operation, you can add cycles to your balance by running a command similar to the following: - -``` -dfx cycles convert 1.005 --network ic -``` - -This command converts an additional `1.005` ICP tokens to cycles. The command returns output similar to the following: - -``` -Transfer sent at BlockHeight: 81520 -Canister was topped up! -``` - -- #### Step 4: Call the `hello_backend` canister and the predefined `greet` function by running the following command: - -``` -dfx canister --network ic call hello_backend greet '("everyone": text)' -``` - -Let’s take a closer look at this example: - -- Using the `--network ic` option indicates that the canister you want to call is deployed on the `ic`. The `ic` network alias is an internally-reserved alias for accessing the Internet Computer blockchain mainnet. - -- Note that the `--network ic` option must precede the operation subcommand, which, in this case, is the `dfx canister call` command. - -- The `hello_backend` argument specifies the name of the canister you want to call. - -- The `greet` argument specifies the name of the function you want to call in the `hello` canister. - -- The text string `everyone` is the argument that you want to pass to the `greet` function. - -- #### Step 5: Verify the command displays the return value of the `greet` function. For example: - -``` -("Hello, everyone!") -``` - -- #### Step 6: Rerun the `dfx cycles balance --network ic` command or refresh the browser to see your new cycle balance and recent activity. - -## Test the dapp frontend - -Now that you have verified that your dapp has been deployed and tested its operation using the command line, let’s verify that you can access the frontend using your web browser. - -To access the dapp frontend: - -- #### Step 1: Open a browser. - -- #### Step 2: Navigate to the frontend for the dapp using a URL that consists of the `hello_frontend` identifier and the `boundary.icp0.io` suffix. - -If you didn’t make a note of the canister identifier, you can look it up by running the following command: - -``` -dfx canister --network ic id hello_assets -``` - -For example, the full URL should look similar to the following: - -``` -https://gsueu-yaaaa-aaaae-aaagq-cai.icp0.io -``` - -Navigating to this URL displays the HTML entry page for the template application. For example: - - - -- #### Step 3: Type a greeting, then click **Click Me** to return the greeting. - -## Next steps - -Want to go further? [Start the developer journey series](/docs/current/tutorials/developer-journey/). diff --git a/docs/developer-docs/getting-started/deploy/testnet.mdx b/docs/developer-docs/getting-started/deploy/testnet.mdx deleted file mode 100644 index 7a312f4306..0000000000 --- a/docs/developer-docs/getting-started/deploy/testnet.mdx +++ /dev/null @@ -1,83 +0,0 @@ ---- -keywords: [beginner, tutorial, testnet, testnet deployment, deploy] ---- - -import { MarkdownChipRow } from "/src/components/Chip/MarkdownChipRow"; -import { GlossaryTooltip } from "/src/components/Tooltip/GlossaryTooltip"; - - -# Testnet deployment - - - -## Overview - -In contrast to other blockchain networks, ICP does not have a testnet network where smart contract developers can deploy their projects to test functionality. - -This is because canister smart contracts can be upgraded and changed once they have been deployed on the mainnet, and mainnet deployment is fairly cheap. - -For developers who are looking for a testnet environment, however, ICP offers the [playground](https://m7sm4-2iaaa-aaaab-qabra-cai.ic0.app/) that allows for simple, small-scale, temporary testing for free. It can be used to build and deploy canisters directly in the [web browser](/docs/current/developer-docs/developer-tools/ide/playground), or it can be utilized through the `dfx deploy --playground` command via the CLI. - -Canisters deployed to the playground use resources that are borrowed from a canister pool. Each canister has an initial amount of 0.5T cycles that it receives from the resource pool and can be used for 20 minutes once the canister has been deployed. Note that there are function [limitations and restrictions](/docs/current/developer-docs/smart-contracts/deploy/custom-testnets) imposed on canisters deployed to the playground. - -For advanced developers and use cases, there are [custom testnet options](/docs/current/developer-docs/smart-contracts/deploy/custom-testnets). - -## Deploying to the playground - -Through `dfx`, canisters can be deployed directly from the CLI to the playground using the `--playground` flag. When this flag is used, the specified canister is deployed to the playground canister pool, and a canister URL will be returned to the developer. If no canister is specified, all canisters within the project's `dfx.json` file will be deployed to the playground. - -This workflow enables developers to test canister functionality without needing to obtain cycles or configure other parameters that are required for deployment to the mainnet. - -### Prerequisites - -Before you start, verify the following: - -- [x] You have an internet connection and access to a shell terminal on your local macOS or Linux computer. - -- [x] You have a command line interface (CLI) window open. This window is also referred to as the 'terminal' window. - -- [x] You have downloaded and installed the IC SDK package as described in the [installing the IC SDK](/docs/current/developer-docs/getting-started/install/) page. - -:::info -`dfx deploy --playground` is available in `dfx` versions v0.15.1 and above. -::: - -To deploy a canister to the playground, first create a new `dfx` project with the command: - -``` -dfx new hello_world -``` - -This command will create a new default `dfx` project that contains a simple 'Hello, world!' sample that includes a `hello_world_backend` canister with a predefined `greet` function. - -Then, to deploy this canister to the playground, run the command: - -``` -dfx deploy hello_world_backend --playground -``` - -Once deployed, the canister can be interacted with using a command such as: - -``` -dfx canister call hello_world_backend greet '("everyone")' --network playground -``` - -This command calls the `hello_world_backend` canister that has been deployed to the playground using the `--network` flag since the playground is classified as a deployment network. - -:::info -Any commands that intend to target a canister deployed to the playground must use the `--playground` or `--network playground` flag in order to target the borrowed canister(s). -::: - -Verify the command displays the return value of the `greet` function. - -For example: - -``` -("Hello, everyone!") -``` - -## Next steps - -Next, you can deploy your canister on the mainnet. - -- [Mainnet deployment](/docs/current/developer-docs/getting-started/deploy/mainnet) \ No newline at end of file diff --git a/docs/developer-docs/getting-started/explore-examples.mdx b/docs/developer-docs/getting-started/explore-examples.mdx index 09b7a23b46..7bb6f0b9e8 100644 --- a/docs/developer-docs/getting-started/explore-examples.mdx +++ b/docs/developer-docs/getting-started/explore-examples.mdx @@ -11,8 +11,6 @@ import { GlossaryTooltip } from "/src/components/Tooltip/GlossaryTooltip"; -## Overview - [ICP Ninja](https://icp.ninja) is a web-based integrated development environment (IDE) for creating and deploying decentralized applications (dapps) on the Internet Computer (ICP). ICP Ninja provides a gallery of example projects you can explore to learn about different application types, architectures, and use cases. Example projects can be edited and then deployed to ICP directly from your web browser. Once deployed, you can open the application's frontend in your browser, share the public link to your new onchain dapp, or make calls directly to the backend through the [Candid UI](/docs/current/developer-docs/smart-contracts/candid/candid-concepts). @@ -25,7 +23,6 @@ ICP Ninja serves as an introduction to developing on ICP and learning about: - ICP's unique features, such as [randomness](/docs/current/developer-docs/smart-contracts/advanced-features/randomness), [timers](/docs/current/developer-docs/smart-contracts/advanced-features/periodic-tasks), and [HTTPS outcalls](/docs/current/developer-docs/smart-contracts/advanced-features/https-outcalls/https-outcalls-overview). - :::info Want to skip directly to using CLI tools in a local dev environment? [Get started with the IC SDK](/docs/current/developer-docs/getting-started/install). @@ -91,4 +88,4 @@ Once you are ready to either deploy your ICP Ninja project longer than the tempo - [x] Download the ICP Ninja project files by selecting the dropdown menu next to the "Deploy" button, then select "Download files." **If you want to start a new project instead, you can skip this step.** -- [x] [Install tools.](/docs/current/developer-docs/getting-started/install) +- [x] [Installing developer tools.](/docs/current/developer-docs/getting-started/install) diff --git a/docs/developer-docs/getting-started/identities.mdx b/docs/developer-docs/getting-started/identities.mdx index 725a6ba051..15a9040b3a 100644 --- a/docs/developer-docs/getting-started/identities.mdx +++ b/docs/developer-docs/getting-started/identities.mdx @@ -5,12 +5,10 @@ keywords: [beginner, getting started, tutorial, accounts, developer account] import { MarkdownChipRow } from "/src/components/Chip/MarkdownChipRow"; import { GlossaryTooltip } from "/src/components/Tooltip/GlossaryTooltip"; -# Create a developer identity +# Creating a developer identity -## Overview - On the Internet Computer (ICP), a developer **identity** is essential to developing canisters. Developer identities use a private/public key pair for authentication. The public key can be distributed openly as it will be used to encrypt messages. The private key must be kept secret and stored securely. Developer identities have a **principal**, a generic identifier value used to identify users, canisters, and potentially other entities on the network in the future. Each developer identity's principal value is derived from the identity's public key. @@ -41,8 +39,6 @@ Developer identities are not the only form of identity on ICP. Other ICP identit ::: -## Creating your identity - By default, `dfx` will create and use the `default` identity. ***This identity is not stored securely. It is recommended you create your own personal identity.*** First, use `dfx` to list all current identities. If none exist, it will automatically create the `default` identity. @@ -77,7 +73,7 @@ Identity names must use the characters `ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmn To recover an identity, use `dfx identity import --seed-file seedphrase.txt`, where `seedphrase.txt` contains the seed phrase shown when you created your identity. ::: -### Storing the identity's private key +### Storing the developer identity's private key The private key for an identity is stored in the `~/.config/dfx/identity/IDENTITY_NAME/identity.pem`. ***This file should be backed up to a secure location.*** @@ -85,7 +81,7 @@ The private key for an identity is stored in the `~/.config/dfx/identity/IDENTIT By default, `dfx` will store your identity in the local keyring/keychain. If a keyring/keychain is unavailable, it will prompt you to choose a password, then store your private key locally in a password-protected PEM file at `~/.config/dfx/identity/IDENTITY_NAME/identity.pem.encrypted`. ::: -## Using your identity +## Using your developer identity Once your identity is created, you must tell `dfx` that this is the identity you want to use. If you do not, the `default` identity will be used, and any canister creation and management you execute will not be secure. @@ -125,4 +121,4 @@ aez2y-7yvs5-e6dpq-gwlld-t6ozx-l5hoo-j4vwr-mimoy-me2xq-yrxkx-rae Next, you must obtain cycles. Cycles are required to pay for the resources a canister consumes. -- [x] [Tokens and cycles](/docs/current/developer-docs/getting-started/tokens-and-cycles) +- [x] [Using tokens and cycles](/docs/current/developer-docs/getting-started/tokens-and-cycles) diff --git a/docs/developer-docs/getting-started/install.mdx b/docs/developer-docs/getting-started/install.mdx index ce5bc0a57f..920558e46e 100644 --- a/docs/developer-docs/getting-started/install.mdx +++ b/docs/developer-docs/getting-started/install.mdx @@ -7,12 +7,10 @@ import { AdornedTabs } from "/src/components/Tabs/AdornedTabs"; import { MarkdownChipRow } from "/src/components/Chip/MarkdownChipRow"; import { GlossaryTooltip } from "/src/components/Tooltip/GlossaryTooltip"; -# Install tools +# Installing developer tools -## Overview - The IC SDK is a software development kit used to develop and deploy applications on the Internet Computer (ICP) from a local developer environment. It is comprised of several tools. ## Installing the IC SDK @@ -86,6 +84,8 @@ dfx --version #### Prerequisites +`dfx` is not natively supported on Windows. You will need to install a Linux instance via Windows Subsystem for Linux and run all commands within that Linux instance. + Download and install Windows Subsystem for Linux.
@@ -142,4 +142,4 @@ For troubleshooting common `dfx` errors, see [IC SDK troubleshooting](troublesho Next, you must create a developer identity. This identity will be used to control and manage your project's canisters. -- [x] [Create a developer identity](/docs/current/developer-docs/getting-started/identities). +- [x] [Creating a developer identity](/docs/current/developer-docs/getting-started/identities). diff --git a/docs/developer-docs/getting-started/next-steps.mdx b/docs/developer-docs/getting-started/next-steps.mdx deleted file mode 100644 index fb87240ab7..0000000000 --- a/docs/developer-docs/getting-started/next-steps.mdx +++ /dev/null @@ -1,20 +0,0 @@ ---- -keywords: [beginner, getting started, user journeys, developer paths, features, application types] ---- - -import useBaseUrl from "@docusaurus/useBaseUrl"; -import { MarkdownChipRow } from "/src/components/Chip/MarkdownChipRow"; -import { GlossaryTooltip } from "/src/components/Tooltip/GlossaryTooltip"; -import NextSteps from "@site/src/components/Card/NextSteps"; - -# Next steps - - - -Continue building with these suggested next steps. - - - - - - diff --git a/docs/developer-docs/getting-started/quickstart/first-smart-contract.mdx b/docs/developer-docs/getting-started/quickstart/first-smart-contract.mdx index de2e03f105..1b9c9f8e6f 100644 --- a/docs/developer-docs/getting-started/quickstart/first-smart-contract.mdx +++ b/docs/developer-docs/getting-started/quickstart/first-smart-contract.mdx @@ -7,7 +7,7 @@ import { MarkdownChipRow } from "/src/components/Chip/MarkdownChipRow"; import TabItem from "@theme/TabItem"; import { OsType, useOs } from "/src/hooks/useOs"; -# Quick start +# First smart contract @@ -111,10 +111,21 @@ project. #### Prerequisites +`dfx` is not natively supported on Windows. You will need to install a Linux instance via Windows Subsystem for Linux and run all commands within that Linux instance. + Download and install Windows Subsystem for Linux.
- Download and install Node.js within your WSL environment. + Open a WSL terminal window. +
+
+ Download and install a Linux distribution (i.e., Ubuntu) using Windows Subsystem for Linux: wsl --install -d ubuntu +
+
+ Open the WSL Linux environment. Run all following commands within this environment. +
+
+ Download and install Node.js within your WSL Linux environment. --------- diff --git a/docs/developer-docs/getting-started/quickstart/react-quickstart.mdx b/docs/developer-docs/getting-started/quickstart/react-quickstart.mdx index 9926b2d3a5..69ff57bcd1 100644 --- a/docs/developer-docs/getting-started/quickstart/react-quickstart.mdx +++ b/docs/developer-docs/getting-started/quickstart/react-quickstart.mdx @@ -7,7 +7,7 @@ import { MarkdownChipRow } from "/src/components/Chip/MarkdownChipRow"; import TabItem from "@theme/TabItem"; import { AdornedTabs } from "/src/components/Tabs/AdornedTabs"; -# React quick start +# First web app @@ -66,10 +66,21 @@ dfx --version #### Prerequisites +`dfx` is not natively supported on Windows. You will need to install a Linux instance via Windows Subsystem for Linux and run all commands within that Linux instance. + Download and install Windows Subsystem for Linux.
- Download and install Node.js within your WSL environment. + Open a WSL terminal window. +
+
+ Download and install a Linux distribution (i.e., Ubuntu) using Windows Subsystem for Linux: wsl --install -d ubuntu +
+
+ Open the WSL Linux environment. Run all following commands within this environment. +
+
+ Download and install Node.js within your WSL Linux environment. --------- @@ -118,4 +129,4 @@ dfx deploy --playground Open the `frontend` URL in a web browser. You'll see the template React frontend interface. -*Congratulations, you just created your first internet-native React dapp!* \ No newline at end of file +*Congratulations, you just created your first internet-native React app!* diff --git a/docs/developer-docs/getting-started/tokens-and-cycles.mdx b/docs/developer-docs/getting-started/tokens-and-cycles.mdx index e773172e10..df76bc0aee 100644 --- a/docs/developer-docs/getting-started/tokens-and-cycles.mdx +++ b/docs/developer-docs/getting-started/tokens-and-cycles.mdx @@ -7,12 +7,10 @@ import { GlossaryTooltip } from "/src/components/Tooltip/GlossaryTooltip"; import TabItem from "@theme/TabItem"; import { AdornedTabs } from "/src/components/Tabs/AdornedTabs"; -# Tokens and cycles +# Using tokens and cycles -## Overview - On the Internet Computer, there are three types of token assets: ICP tokens, cycles, and ICRC tokens. ICP and cycles are the most important for every developer to understand and use, as they are necessary for deploying and maintaining a canister. ICP tokens are important because they can be converted into cycles and used to pay for a canister's resource consumption. Cycles reflect the real cost of operations for resources such as physical hardware, rack space, energy, storage devices, and bandwidth. @@ -85,7 +83,7 @@ b0d7beee54be8679a42e999218a16a0d396f223d7e44d259ac089848c1b820bf You can obtain [ICP tokens](https://internetcomputer.org/icp-tokens) from an [exchange](https://coinmarketcap.com/currencies/internet-computer/markets) or through a [developer grant](https://dfinity.org/grants). If you are using an exchange, initiate a withdrawal transaction, then enter the ledger account ID as the "destination" address to send ICP tokens to. -### 3. Check the balance. +### 3. Check the ICP balance. ``` dfx ledger balance --network=ic @@ -135,7 +133,7 @@ The amount of cycles that your canister will use depends on a variety of factors ::: -### 5. Confirm the balance. +### 5. Confirm the cycles balance. ``` dfx cycles balance --network=ic @@ -154,4 +152,4 @@ dfx cycles balance --network=ic Next, it's time to write the code for a smart contract. -- [x] [Write smart contracts](/docs/current/developer-docs/getting-started/write-smart-contracts). +- [x] [Writing smart contracts](/docs/current/developer-docs/getting-started/write-smart-contracts). diff --git a/docs/developer-docs/getting-started/troubleshooting.mdx b/docs/developer-docs/getting-started/troubleshooting.mdx index 06197041f5..773c5d7d9b 100644 --- a/docs/developer-docs/getting-started/troubleshooting.mdx +++ b/docs/developer-docs/getting-started/troubleshooting.mdx @@ -8,8 +8,6 @@ import { MarkdownChipRow } from "/src/components/Chip/MarkdownChipRow"; -## 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. diff --git a/docs/developer-docs/getting-started/write-smart-contracts.mdx b/docs/developer-docs/getting-started/write-smart-contracts.mdx index 2f166120ae..593fa82ddf 100644 --- a/docs/developer-docs/getting-started/write-smart-contracts.mdx +++ b/docs/developer-docs/getting-started/write-smart-contracts.mdx @@ -10,12 +10,10 @@ import { BetaChip } from "/src/components/Chip/BetaChip"; import { MarkdownChipRow } from "/src/components/Chip/MarkdownChipRow"; import { GlossaryTooltip } from "/src/components/Tooltip/GlossaryTooltip"; -# Write smart contracts +# Writing smart contracts -## Overview - Canisters are an enhanced type of smart contract. Before a canister is deployed to ICP, the canister's code is compiled into a WebAssembly (Wasm) program, enabling it to store persistent data, be managed by entities such as DAOs, host entire applications, and more. Each canister has the following components:
@@ -121,7 +119,7 @@ The `frontend` canister stores the app's frontend assets, including files such a   />
-## Writing code +## Writing canister code :::danger @@ -292,14 +290,14 @@ fn get_current_number() -> Nat { }> -Azle code coming soon. + [Learn more about Azle](https://demergent-labs.github.io/azle/). }> -Kybra code coming soon. + [Learn more about Kybra](https://demergent-labs.github.io/kybra/). @@ -413,21 +411,17 @@ fn get_current_number() -> Nat { }> -Azle code coming soon. - [Learn more about Azle](https://demergent-labs.github.io/azle/). }> -Kybra code coming soon. - [Learn more about Kybra](https://demergent-labs.github.io/kybra/). -### 4. Retrieve data. +### 4. Retrieve external data. HTTPS outcalls can obtain data from any external source, including other blockchains, traditional Web2 APIs, and other web services. When HTTPS outcalls are used locally, the returned result is not validated since the local replica is only a single node. HTTPS outcalls used on the mainnet validate the returned result through the subnet's consensus, providing security that the data obtained has not been maliciously tampered with during transport. @@ -676,14 +670,12 @@ fn transform(raw: TransformArgs) -> HttpResponse { }> -Azle code coming soon. - [Learn more about Azle](https://demergent-labs.github.io/azle/). }> -Kybra code coming soon. + [Learn more about Kybra](https://demergent-labs.github.io/kybra/). @@ -898,15 +890,13 @@ fn print_results() { }> -Azle code coming soon. - [Learn more about Azle](https://demergent-labs.github.io/azle/). + }> -Kybra code coming soon. - [Learn more about Kybra](https://demergent-labs.github.io/kybra/). + @@ -914,4 +904,4 @@ Kybra code coming soon. Now that you have written the canister's code, the canister needs to be deployed. -- [x] [Deploy and manage](/docs/current/developer-docs/getting-started/deploy-and-manage). +- [x] [Deploying and managing dapps](/docs/current/developer-docs/getting-started/deploy-and-manage). diff --git a/docs/developer-docs/getting-started/wsl-troubleshoot.mdx b/docs/developer-docs/getting-started/wsl-troubleshoot.mdx index 4786d2f228..484512fef5 100644 --- a/docs/developer-docs/getting-started/wsl-troubleshoot.mdx +++ b/docs/developer-docs/getting-started/wsl-troubleshoot.mdx @@ -8,7 +8,7 @@ import { MarkdownChipRow } from "/src/components/Chip/MarkdownChipRow"; -## Overview + The IC SDK is not natively supported on Windows operating systems. It is recommended for Windows users to install [Windows Subsystem for Linux](https://docs.microsoft.com/en-us/windows/wsl/install). diff --git a/docs/developer-docs/identity/authentication/overview.mdx b/docs/developer-docs/identity/authentication/overview.mdx index 0531a84618..b53a7e3ca9 100644 --- a/docs/developer-docs/identity/authentication/overview.mdx +++ b/docs/developer-docs/identity/authentication/overview.mdx @@ -4,7 +4,7 @@ keywords: [authentication, identity, login, user login, integration] import { MarkdownChipRow } from "/src/components/Chip/MarkdownChipRow"; -# Authentication overview +# Integrating authentication into an application diff --git a/docs/developer-docs/identity/internet-identity/alternative-origins.mdx b/docs/developer-docs/identity/internet-identity/alternative-origins.mdx index b509a15e4e..d65c18179c 100644 --- a/docs/developer-docs/identity/internet-identity/alternative-origins.mdx +++ b/docs/developer-docs/identity/internet-identity/alternative-origins.mdx @@ -9,7 +9,7 @@ import { MarkdownChipRow } from "/src/components/Chip/MarkdownChipRow"; -## Overview + If your application has reached the stage where you want to change domain names, and you have been authenticating with Internet Identity (II), you will want to make sure that your users can seamlessly keep the same principals they have already been using. To support this functionality, you can configure your application for alternative frontend origins using this guide. ![End Result](../_attachments/alternative-origins.png) diff --git a/docs/developer-docs/identity/internet-identity/creating-ii.mdx b/docs/developer-docs/identity/internet-identity/creating-ii.mdx index 51a3b96873..69f45747bc 100644 --- a/docs/developer-docs/identity/internet-identity/creating-ii.mdx +++ b/docs/developer-docs/identity/internet-identity/creating-ii.mdx @@ -8,7 +8,7 @@ import { MarkdownChipRow } from "/src/components/Chip/MarkdownChipRow"; -## Overview + This guide walks through how to create an Internet Identity. Internet Identity is ICP's native form of identity. It is used by many dapps build on ICP for users to authenticate with. diff --git a/docs/developer-docs/identity/internet-identity/integrate-internet-identity.mdx b/docs/developer-docs/identity/internet-identity/integrate-internet-identity.mdx index 7285aa8a50..607c449197 100644 --- a/docs/developer-docs/identity/internet-identity/integrate-internet-identity.mdx +++ b/docs/developer-docs/identity/internet-identity/integrate-internet-identity.mdx @@ -12,7 +12,7 @@ import { BetaChip } from "/src/components/Chip/BetaChip"; -## Overview + This guide shows an example of how to integrate Internet Identity into an application by using a simple 'Who am I?' backend canister and a frontend UI that returns the Internet Identity principal of the user who calls the backend's `whoami` method. This project uses the **pullable** version of the Internet identity canister. A pullable canister is a canister that provides a public service at a static canister ID. To learn more about pullable canisters, please [see the documentation](/docs/current/developer-docs/smart-contracts/maintain/import). diff --git a/docs/developer-docs/identity/internet-identity/overview.mdx b/docs/developer-docs/identity/internet-identity/overview.mdx index 9253d6ede7..f1f89af9ef 100644 --- a/docs/developer-docs/identity/internet-identity/overview.mdx +++ b/docs/developer-docs/identity/internet-identity/overview.mdx @@ -4,7 +4,7 @@ keywords: [intermediate, concept, user sign in, user login, internet identity] import { MarkdownChipRow } from "/src/components/Chip/MarkdownChipRow"; -# Internet Identity overview +# What is Internet Identity? diff --git a/docs/developer-docs/identity/verifiable-credentials/how-it-works.mdx b/docs/developer-docs/identity/verifiable-credentials/how-it-works.mdx index 1f0685e2e4..fb63d4542c 100644 --- a/docs/developer-docs/identity/verifiable-credentials/how-it-works.mdx +++ b/docs/developer-docs/identity/verifiable-credentials/how-it-works.mdx @@ -9,7 +9,7 @@ import useBaseUrl from "@docusaurus/useBaseUrl"; -## Overview + Verifiable credentials (VCs) on ICP rely on Internet Identity (II), which provides distinct identities that preserve unlinkability for each dapp. A dapp utilizing verifiable credentials can’t ask for a user's credentials from the [issuer](/docs/current/developer-docs/identity/verifiable-credentials/overview#terminology) of the verifiable credential directly. When a [relying party](/docs/current/developer-docs/identity/verifiable-credentials/overview#terminology) wants to obtain a credential from an issuer, it must request it through an [identity provider](/docs/current/developer-docs/identity/verifiable-credentials/overview#terminology) such as Internet Identity. diff --git a/docs/developer-docs/identity/verifiable-credentials/issuer.mdx b/docs/developer-docs/identity/verifiable-credentials/issuer.mdx index 6fd309f1e1..b3438db61d 100644 --- a/docs/developer-docs/identity/verifiable-credentials/issuer.mdx +++ b/docs/developer-docs/identity/verifiable-credentials/issuer.mdx @@ -9,7 +9,7 @@ import useBaseUrl from "@docusaurus/useBaseUrl"; -## Overview + An **issuer** is a service or app that can issue a verifiable credential (VC) to a user. On ICP, an issuer is an exposed API that receives calls from an identity provider and does not trigger any workflows itself. To become an issuer, your canister must implement the issuer API as described in the [verifiable credential spec](https://github.com/dfinity/internet-identity/blob/main/docs/vc-spec.md). diff --git a/docs/developer-docs/identity/verifiable-credentials/overview.mdx b/docs/developer-docs/identity/verifiable-credentials/overview.mdx index 5b399baf13..072d6e2155 100644 --- a/docs/developer-docs/identity/verifiable-credentials/overview.mdx +++ b/docs/developer-docs/identity/verifiable-credentials/overview.mdx @@ -4,7 +4,7 @@ keywords: [intermediate, concept, identity, credentials, verifiable credentials] import { MarkdownChipRow } from "/src/components/Chip/MarkdownChipRow"; -# Verifiable credentials overview +# What are verifiable credentials? diff --git a/docs/developer-docs/identity/verifiable-credentials/relying-party.mdx b/docs/developer-docs/identity/verifiable-credentials/relying-party.mdx index e48577c4ef..ccd5dede44 100644 --- a/docs/developer-docs/identity/verifiable-credentials/relying-party.mdx +++ b/docs/developer-docs/identity/verifiable-credentials/relying-party.mdx @@ -9,7 +9,7 @@ import useBaseUrl from "@docusaurus/useBaseUrl"; -## Overview + A **relying party** is a service or app that requests a user's verifiable credentials from an [issuer](issuer.mdx). Relying parties use an **identity provider**, such as Internet Identity, to communicate with the issuer. Identity providers must support the [verifiable credentials specification](https://github.com/dfinity/internet-identity/blob/main/docs/vc-spec.md). Communication with the identity provider uses the [`window.postMessage()`](https://developer.mozilla.org/en-US/docs/Web/API/Window/postMessage) communication channel. diff --git a/docs/developer-docs/multi-chain/bitcoin/overview.mdx b/docs/developer-docs/multi-chain/bitcoin/overview.mdx index 0791743dad..5964cceb27 100644 --- a/docs/developer-docs/multi-chain/bitcoin/overview.mdx +++ b/docs/developer-docs/multi-chain/bitcoin/overview.mdx @@ -5,7 +5,7 @@ keywords: [advanced, bitcoin, btc, overview] import useBaseUrl from "@docusaurus/useBaseUrl"; import { MarkdownChipRow } from "/src/components/Chip/MarkdownChipRow"; -# Bitcoin integration overview +# Bitcoin integration diff --git a/docs/developer-docs/multi-chain/bitcoin/using-btc/btc-comparison.mdx b/docs/developer-docs/multi-chain/bitcoin/using-btc/btc-comparison.mdx index b2df1912b3..9b87508081 100644 --- a/docs/developer-docs/multi-chain/bitcoin/using-btc/btc-comparison.mdx +++ b/docs/developer-docs/multi-chain/bitcoin/using-btc/btc-comparison.mdx @@ -7,7 +7,7 @@ import { MarkdownChipRow } from "/src/components/Chip/MarkdownChipRow"; -## Overview + This guide is designed to help Bitcoin developers understand the core concepts of ICP in order to properly use ICP as a Layer-2 solution for Bitcoin. ## Terminology mapping diff --git a/docs/developer-docs/multi-chain/bitcoin/using-btc/btc-dev-workflow.mdx b/docs/developer-docs/multi-chain/bitcoin/using-btc/btc-dev-workflow.mdx index 25caf4bbf8..ed41c69a9d 100644 --- a/docs/developer-docs/multi-chain/bitcoin/using-btc/btc-dev-workflow.mdx +++ b/docs/developer-docs/multi-chain/bitcoin/using-btc/btc-dev-workflow.mdx @@ -11,7 +11,7 @@ import { MarkdownChipRow } from "/src/components/Chip/MarkdownChipRow"; -## Overview + Developers on ICP can create canisters and dapps that interact directly with the Bitcoin mainnet and testnet networks through ICP's direct integration with Bitcoin. To use this integration, developers must implement a specific workflow to prepare transactions and submit them to the Bitcoin network. Developers can also integrate and interact with chain-key Bitcoin (ckBTC) from within a canister, which uses the ICRC-1 token implementation. diff --git a/docs/developer-docs/multi-chain/bitcoin/using-btc/create-transactions.mdx b/docs/developer-docs/multi-chain/bitcoin/using-btc/create-transactions.mdx index fc178b5b71..0629f95e8a 100644 --- a/docs/developer-docs/multi-chain/bitcoin/using-btc/create-transactions.mdx +++ b/docs/developer-docs/multi-chain/bitcoin/using-btc/create-transactions.mdx @@ -11,7 +11,7 @@ import { MarkdownChipRow } from "/src/components/Chip/MarkdownChipRow"; -## Overview + A Bitcoin transaction spends a number of unspent transaction outputs (UTXOs) and creates new UTXOs. In order to create a Bitcoin transaction, you need to: diff --git a/docs/developer-docs/multi-chain/bitcoin/using-btc/generate-addresses.mdx b/docs/developer-docs/multi-chain/bitcoin/using-btc/generate-addresses.mdx index 485edf60b7..159eef1fe2 100644 --- a/docs/developer-docs/multi-chain/bitcoin/using-btc/generate-addresses.mdx +++ b/docs/developer-docs/multi-chain/bitcoin/using-btc/generate-addresses.mdx @@ -11,7 +11,7 @@ import { MarkdownChipRow } from "/src/components/Chip/MarkdownChipRow"; -## Overview + For a canister to receive Bitcoin payments, it must generate a Bitcoin address. In contrast to most other blockchains, Bitcoin doesn't use accounts. Instead, it diff --git a/docs/developer-docs/multi-chain/bitcoin/using-btc/local-development.mdx b/docs/developer-docs/multi-chain/bitcoin/using-btc/local-development.mdx index 18f940a79c..1bf5d45edf 100644 --- a/docs/developer-docs/multi-chain/bitcoin/using-btc/local-development.mdx +++ b/docs/developer-docs/multi-chain/bitcoin/using-btc/local-development.mdx @@ -10,7 +10,7 @@ import { MarkdownChipRow } from "/src/components/Chip/MarkdownChipRow"; -## Overview + In this guide, you'll explore how you can develop and test a Bitcoin dapp locally. Testing locally allows you to iterate and improve your dapp more quickly. diff --git a/docs/developer-docs/multi-chain/bitcoin/using-btc/ordinals.mdx b/docs/developer-docs/multi-chain/bitcoin/using-btc/ordinals.mdx index cfe71eff34..1e6adf269b 100644 --- a/docs/developer-docs/multi-chain/bitcoin/using-btc/ordinals.mdx +++ b/docs/developer-docs/multi-chain/bitcoin/using-btc/ordinals.mdx @@ -8,7 +8,7 @@ import { MarkdownChipRow } from "/src/components/Chip/MarkdownChipRow"; -## Overview + On Bitcoin, the term 'satoshi' refers to the smallest denomination of BTC, equal to 100 millionth of 1 bitcoin. [Ordinal theory](https://docs.ordinals.com/digital-artifacts.html), or simply 'Ordinals', refers to a numbering scheme used to track and transfer individual satoshis. The term 'Ordinal' comes from the fact that each satoshi is numbered based on the order in which it has been mined and the order in which it is transferred, based on transaction inputs and outputs. diff --git a/docs/developer-docs/multi-chain/bitcoin/using-btc/read-state.mdx b/docs/developer-docs/multi-chain/bitcoin/using-btc/read-state.mdx index d4b51c34f7..f072401a71 100644 --- a/docs/developer-docs/multi-chain/bitcoin/using-btc/read-state.mdx +++ b/docs/developer-docs/multi-chain/bitcoin/using-btc/read-state.mdx @@ -12,7 +12,7 @@ import { MarkdownChipRow } from "/src/components/Chip/MarkdownChipRow"; -## Overview + To read information from the Bitcoin network's state, the Bitcoin integration API exposes the following methods: diff --git a/docs/developer-docs/multi-chain/bitcoin/using-btc/runes.mdx b/docs/developer-docs/multi-chain/bitcoin/using-btc/runes.mdx index 5f50342578..5dc075de01 100644 --- a/docs/developer-docs/multi-chain/bitcoin/using-btc/runes.mdx +++ b/docs/developer-docs/multi-chain/bitcoin/using-btc/runes.mdx @@ -8,7 +8,7 @@ import { MarkdownChipRow } from "/src/components/Chip/MarkdownChipRow"; -## Overview + Bitcoin Runes are a type of fungible asset deployed on the Bitcoin network. Runes are not reliant on the [Ordinals protocol](ordinals.mdx) like other Bitcoin asset standards such as BRC-20 and SRC-20. Runes are designed to be an efficient and simple asset that utilizes Bitcoin's UTXO model and the `OP_RETURN` opcode. Although Runes aren't reliant on Ordinals, the Rune protocol was created and implemented by the same creator, and is part of the same open source project that Ordinals are. diff --git a/docs/developer-docs/multi-chain/bitcoin/using-btc/sign-transactions.mdx b/docs/developer-docs/multi-chain/bitcoin/using-btc/sign-transactions.mdx index 8c46b22e02..9f293bd51d 100644 --- a/docs/developer-docs/multi-chain/bitcoin/using-btc/sign-transactions.mdx +++ b/docs/developer-docs/multi-chain/bitcoin/using-btc/sign-transactions.mdx @@ -10,7 +10,7 @@ import { MarkdownChipRow } from "/src/components/Chip/MarkdownChipRow"; -## Overview + Before a transaction can be sent to the Bitcoin network, each input must be signed. diff --git a/docs/developer-docs/multi-chain/bitcoin/using-btc/submit-transactions.mdx b/docs/developer-docs/multi-chain/bitcoin/using-btc/submit-transactions.mdx index 9d098aa4e3..adb0358a1f 100644 --- a/docs/developer-docs/multi-chain/bitcoin/using-btc/submit-transactions.mdx +++ b/docs/developer-docs/multi-chain/bitcoin/using-btc/submit-transactions.mdx @@ -12,7 +12,7 @@ import { MarkdownChipRow } from "/src/components/Chip/MarkdownChipRow"; -## Overview + To submit transactions to the Bitcoin network, the Bitcoin integration API exposes the `bitcoin_send_transaction` method. diff --git a/docs/developer-docs/multi-chain/chain-key-tokens/ckbtc/making-transactions.mdx b/docs/developer-docs/multi-chain/chain-key-tokens/ckbtc/making-transactions.mdx index e302cc4ee8..e44e1222dd 100644 --- a/docs/developer-docs/multi-chain/chain-key-tokens/ckbtc/making-transactions.mdx +++ b/docs/developer-docs/multi-chain/chain-key-tokens/ckbtc/making-transactions.mdx @@ -11,7 +11,7 @@ import { MarkdownChipRow } from "/src/components/Chip/MarkdownChipRow"; -## Overview + There are several different ways to interact with ckBTC: diff --git a/docs/developer-docs/multi-chain/chain-key-tokens/ckbtc/overview.mdx b/docs/developer-docs/multi-chain/chain-key-tokens/ckbtc/overview.mdx index ad967947c1..550ef60bf1 100644 --- a/docs/developer-docs/multi-chain/chain-key-tokens/ckbtc/overview.mdx +++ b/docs/developer-docs/multi-chain/chain-key-tokens/ckbtc/overview.mdx @@ -4,7 +4,7 @@ keywords: [advanced, bitcoin, btc, ckbtc, chain-key bitcoin] import { MarkdownChipRow } from "/src/components/Chip/MarkdownChipRow"; -# ckBTC overview +# ckBTC diff --git a/docs/developer-docs/multi-chain/chain-key-tokens/ckbtc/using-ckbtc-in-dapps.mdx b/docs/developer-docs/multi-chain/chain-key-tokens/ckbtc/using-ckbtc-in-dapps.mdx index db48fd9e34..905d8d5110 100644 --- a/docs/developer-docs/multi-chain/chain-key-tokens/ckbtc/using-ckbtc-in-dapps.mdx +++ b/docs/developer-docs/multi-chain/chain-key-tokens/ckbtc/using-ckbtc-in-dapps.mdx @@ -10,7 +10,7 @@ import { MarkdownChipRow } from "/src/components/Chip/MarkdownChipRow"; -## Overview + ckBTC is an ICRC-2 compliant token, meaning it supports the [ICRC-1](https://github.com/dfinity/ICRC-1/tree/main/standards/ICRC-1) and [ICRC-2](https://github.com/dfinity/ICRC-1/blob/main/standards/ICRC-2/README.md) token standards. diff --git a/docs/developer-docs/multi-chain/chain-key-tokens/ckerc20/making-transactions.mdx b/docs/developer-docs/multi-chain/chain-key-tokens/ckerc20/making-transactions.mdx index 3c70227949..de5975040c 100644 --- a/docs/developer-docs/multi-chain/chain-key-tokens/ckerc20/making-transactions.mdx +++ b/docs/developer-docs/multi-chain/chain-key-tokens/ckerc20/making-transactions.mdx @@ -11,7 +11,7 @@ import { MarkdownChipRow } from "/src/components/Chip/MarkdownChipRow"; -## Overview + There are several different ways to interact with ckERC20 tokens: diff --git a/docs/developer-docs/multi-chain/chain-key-tokens/ckerc20/overview.mdx b/docs/developer-docs/multi-chain/chain-key-tokens/ckerc20/overview.mdx index 0751371522..39ce7592d2 100644 --- a/docs/developer-docs/multi-chain/chain-key-tokens/ckerc20/overview.mdx +++ b/docs/developer-docs/multi-chain/chain-key-tokens/ckerc20/overview.mdx @@ -5,7 +5,7 @@ keywords: [advanced, ethereum, cketh, erc20, ckerc20, ckusdc, cklink, ckoct, ckp import useBaseUrl from "@docusaurus/useBaseUrl"; import { MarkdownChipRow } from "/src/components/Chip/MarkdownChipRow"; -# ckERC20 overview +# ckERC20 diff --git a/docs/developer-docs/multi-chain/chain-key-tokens/ckerc20/using-ckerc20-in-dapps.mdx b/docs/developer-docs/multi-chain/chain-key-tokens/ckerc20/using-ckerc20-in-dapps.mdx index daa9c575bf..85605a1615 100644 --- a/docs/developer-docs/multi-chain/chain-key-tokens/ckerc20/using-ckerc20-in-dapps.mdx +++ b/docs/developer-docs/multi-chain/chain-key-tokens/ckerc20/using-ckerc20-in-dapps.mdx @@ -10,7 +10,7 @@ import { MarkdownChipRow } from "/src/components/Chip/MarkdownChipRow"; -## Overview + All ckERC20 tokens are ICRC-2 compliant tokens, which means that they support the [ICRC-1](https://github.com/dfinity/ICRC-1/blob/main/standards/ICRC-1/README.md) and [ICRC-2](https://github.com/dfinity/ICRC-1/blob/main/standards/ICRC-2/README.md) token standards. diff --git a/docs/developer-docs/multi-chain/chain-key-tokens/cketh/making-transactions.mdx b/docs/developer-docs/multi-chain/chain-key-tokens/cketh/making-transactions.mdx index 270fc064f2..0d55fce044 100644 --- a/docs/developer-docs/multi-chain/chain-key-tokens/cketh/making-transactions.mdx +++ b/docs/developer-docs/multi-chain/chain-key-tokens/cketh/making-transactions.mdx @@ -11,7 +11,7 @@ import { MarkdownChipRow } from "/src/components/Chip/MarkdownChipRow"; -## Overview + There are several different ways to interact with ckETH: diff --git a/docs/developer-docs/multi-chain/chain-key-tokens/cketh/overview.mdx b/docs/developer-docs/multi-chain/chain-key-tokens/cketh/overview.mdx index ad4312c6e9..8522d950fb 100644 --- a/docs/developer-docs/multi-chain/chain-key-tokens/cketh/overview.mdx +++ b/docs/developer-docs/multi-chain/chain-key-tokens/cketh/overview.mdx @@ -5,7 +5,7 @@ keywords: [advanced, ethereum, cketh, chain-key ethereum, overview] import useBaseUrl from "@docusaurus/useBaseUrl"; import { MarkdownChipRow } from "/src/components/Chip/MarkdownChipRow"; -# ckETH overview +# ckETH diff --git a/docs/developer-docs/multi-chain/chain-key-tokens/cketh/using-cketh-in-dapps.mdx b/docs/developer-docs/multi-chain/chain-key-tokens/cketh/using-cketh-in-dapps.mdx index 823e732745..eecc24aa1a 100644 --- a/docs/developer-docs/multi-chain/chain-key-tokens/cketh/using-cketh-in-dapps.mdx +++ b/docs/developer-docs/multi-chain/chain-key-tokens/cketh/using-cketh-in-dapps.mdx @@ -10,7 +10,7 @@ import { MarkdownChipRow } from "/src/components/Chip/MarkdownChipRow"; -## Overview + ckETH is an ICRC-2 compliant token, meaning it supports the [ICRC-1](https://github.com/dfinity/ICRC-1/blob/main/standards/ICRC-1/README.md) and [ICRC-2](https://github.com/dfinity/ICRC-1/blob/main/standards/ICRC-2/README.md) token standards. diff --git a/docs/developer-docs/multi-chain/chain-key-tokens/overview.mdx b/docs/developer-docs/multi-chain/chain-key-tokens/overview.mdx index 1b04ffbf64..c0581b6752 100644 --- a/docs/developer-docs/multi-chain/chain-key-tokens/overview.mdx +++ b/docs/developer-docs/multi-chain/chain-key-tokens/overview.mdx @@ -5,7 +5,7 @@ keywords: [advanced, Chain Fusion, overview, chain-key tokens, cktokens, ck toke import useBaseUrl from "@docusaurus/useBaseUrl"; import { MarkdownChipRow } from "/src/components/Chip/MarkdownChipRow"; -# Chain-key token overview +# Chain-key tokens @@ -34,6 +34,12 @@ In addition to the requirement that a chain-key token must adhere to an [ICRC](/ - Builds must be reproducible. - The canisters must be immutable or controlled by a DAO, for example, an [SNS](https://internetcomputer.org/docs/current/developer-docs/daos/sns) or a [threshold canister](https://github.com/dfinity/threshold) with a large number of verified voters. +## Know-your-transaction (KYT) checks + +The ckBTC minter interacts with a dedicated KYT canister that executes KYT checks. Checks are applied to both incoming and outgoing transactions. + +The ckETH and ckERC20 minters implement a local OFAC checklist for both incoming and outgoing transactions. + ## Available chain-key tokens The current chain-key tokens are supported: diff --git a/docs/developer-docs/multi-chain/ethereum/evm-rpc/costs.mdx b/docs/developer-docs/multi-chain/ethereum/evm-rpc/costs.mdx index 87e58c7917..a3635724ca 100644 --- a/docs/developer-docs/multi-chain/ethereum/evm-rpc/costs.mdx +++ b/docs/developer-docs/multi-chain/ethereum/evm-rpc/costs.mdx @@ -11,7 +11,7 @@ import { AdornedTab } from "/src/components/Tabs/AdornedTab"; -## Overview + Each call made to the EVM RPC canister costs [cycles](/docs/current/developer-docs/getting-started/tokens-and-cycles). diff --git a/docs/developer-docs/multi-chain/ethereum/evm-rpc/evm-rpc-canister.mdx b/docs/developer-docs/multi-chain/ethereum/evm-rpc/evm-rpc-canister.mdx index e4cf1d7bf9..525f078483 100644 --- a/docs/developer-docs/multi-chain/ethereum/evm-rpc/evm-rpc-canister.mdx +++ b/docs/developer-docs/multi-chain/ethereum/evm-rpc/evm-rpc-canister.mdx @@ -417,7 +417,65 @@ dfx canister call evm_rpc eth_getTransactionReceipt "(variant {$RPC_SOURCE}, $RP -Calling an Ethereum smart contract from Motoko is possible but not yet officially supported. +```motoko no-repl +import EvmRpc "canister:evm_rpc"; + +import Cycles "mo:base/ExperimentalCycles"; +import Debug "mo:base/Debug"; + +actor { + public func call() : async ?Text { + + // Configure RPC request + let services = #EthMainnet(null); + let config = null; + + // Add cycles to next call + Cycles.add(2000000000); + + // Call an Ethereum smart contract. The smart contract's information in this example is hard coded. + let result = await EvmRpc.eth_call(services, config, { + block = null; + transaction = { + to = ?"0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48"; + input = ?"0x70a08231000000000000000000000000b25eA1D493B49a1DeD42aC5B1208cC618f9A9B80"; // ABI-encoded + accessList = null; + blobVersionedHashes = null; + blobs = null; + chainId = null; + from = null; + gas = null; + gasPrice = null; + maxFeePerBlobGas = null; + maxFeePerGas = null; + maxPriorityFeePerGas = null; + nonce = null; + type_ = null; + value = null + }; + }); + + // Process results + switch result { + // Prints the response if each RPC provider returns a consistent, successful result + case (#Consistent(#Ok response)) { + Debug.print("Success: " # debug_show response); + ?response // ABI-encoded + }; + // Trap is an RPC provider returns an error message consistent with the response of the other providers + case (#Consistent(#Err error)) { + Debug.trap("Error: " # debug_show error); + null + }; + // Trap if an RPC provider returns a response inconsistent with the other providers + case (#Inconsistent(_results)) { + Debug.trap("Inconsistent results"); + null + }; + }; + }; +}; +``` diff --git a/docs/developer-docs/multi-chain/ethereum/evm-rpc/how-it-works.mdx b/docs/developer-docs/multi-chain/ethereum/evm-rpc/how-it-works.mdx index de1383d145..b03b39ccf2 100644 --- a/docs/developer-docs/multi-chain/ethereum/evm-rpc/how-it-works.mdx +++ b/docs/developer-docs/multi-chain/ethereum/evm-rpc/how-it-works.mdx @@ -8,7 +8,7 @@ import { MarkdownChipRow } from "/src/components/Chip/MarkdownChipRow"; -## Overview + The [Ethereum Virtual Machine](https://ethereum.org/en/developers/docs/evm/) (EVM) [Remote Procedure Call](https://ethereum.org/en/developers/docs/apis/json-rpc/) (RPC) canister enables communication between ICP canisters and RPC services. These services, such as Cloudflare and Alchemy, provide public APIs for interacting with blockchain networks. The EVM RPC canister acts as a gateway for a dapp's canisters to communicate with and query information from EVM-compatible chains. It provides endpoints that ICP developers can use to interact with Ethereum smart contracts and ensures that the responses received from the Ethereum network are secure and immediately useful within a canister. diff --git a/docs/developer-docs/multi-chain/ethereum/evm-rpc/overview.mdx b/docs/developer-docs/multi-chain/ethereum/evm-rpc/overview.mdx index e098135fc1..eb0a6ddc6c 100644 --- a/docs/developer-docs/multi-chain/ethereum/evm-rpc/overview.mdx +++ b/docs/developer-docs/multi-chain/ethereum/evm-rpc/overview.mdx @@ -4,11 +4,11 @@ keywords: [advanced, ethereum, evm rpc, evm, tutorial] import { MarkdownChipRow } from "/src/components/Chip/MarkdownChipRow"; -# EVM RPC canister overview +# EVM RPC canister -**EVM RPC** is an ICP canister smart contract for communicating with [Ethereum](https://ethereum.org/en/) and other [EVM blockchains](https://chainlist.org/?testnets=true) using an onchain API. Communication with EVM-compatible chains includes obtaining and sending information such as: +The **EVM RPC** canister is used for communicating with [Ethereum](https://ethereum.org/en/) and other [EVM blockchains](https://chainlist.org/?testnets=true) using an onchain API. Communication with EVM-compatible chains includes obtaining and sending information such as: - The logs of a specific block or transaction. diff --git a/docs/developer-docs/multi-chain/ethereum/overview.mdx b/docs/developer-docs/multi-chain/ethereum/overview.mdx index 8dc24bf43e..279eb0e043 100644 --- a/docs/developer-docs/multi-chain/ethereum/overview.mdx +++ b/docs/developer-docs/multi-chain/ethereum/overview.mdx @@ -4,7 +4,7 @@ keywords: [advanced, ethereum, overview] import { MarkdownChipRow } from "/src/components/Chip/MarkdownChipRow"; -# Ethereum integration overview +# Ethereum & EVM integration diff --git a/docs/developer-docs/multi-chain/ethereum/using-eth/eth-comparison.mdx b/docs/developer-docs/multi-chain/ethereum/using-eth/eth-comparison.mdx index f9aacedd4e..ceaa429997 100644 --- a/docs/developer-docs/multi-chain/ethereum/using-eth/eth-comparison.mdx +++ b/docs/developer-docs/multi-chain/ethereum/using-eth/eth-comparison.mdx @@ -7,7 +7,7 @@ import { MarkdownChipRow } from "/src/components/Chip/MarkdownChipRow"; -## Overview + This guide is designed to help Ethereum developers understand the core concepts of ICP, focusing on the terminology and functionalities that differ between the two protocols. While the underlying concepts might be similar, ICP utilizes different terms to describe them. For a feature comparison between the two protocols, refer to the [quick comparison between ICP and Ethereum](/docs/current/developer-docs/getting-started/network-overview#quick-comparison-with-ethereum). diff --git a/docs/developer-docs/multi-chain/ethereum/using-eth/eth-dev-workflow.mdx b/docs/developer-docs/multi-chain/ethereum/using-eth/eth-dev-workflow.mdx index e1bd07ef5c..c3996d489c 100644 --- a/docs/developer-docs/multi-chain/ethereum/using-eth/eth-dev-workflow.mdx +++ b/docs/developer-docs/multi-chain/ethereum/using-eth/eth-dev-workflow.mdx @@ -9,7 +9,7 @@ import { MarkdownChipRow } from "/src/components/Chip/MarkdownChipRow"; -## Overview + Developers on ICP can create canisters and dapps that interact with the Ethereum mainnet, Sepolia testnet, and other EVM-compatible networks through ICP's Ethereum integration. To use this integration, developers must implement a specific workflow that makes JSON-RPC calls to the EVM RPC canister in order to query network information and submit transactions to an EVM-compatible network. Developers can also integrate and interact with chain-key Ethereum (ckETH) from within a canister, which uses the ICRC-1 token implementation. diff --git a/docs/developer-docs/multi-chain/ethereum/using-eth/generating-addresses.mdx b/docs/developer-docs/multi-chain/ethereum/using-eth/generating-addresses.mdx index 363003dde6..ab5b838d57 100644 --- a/docs/developer-docs/multi-chain/ethereum/using-eth/generating-addresses.mdx +++ b/docs/developer-docs/multi-chain/ethereum/using-eth/generating-addresses.mdx @@ -12,7 +12,7 @@ import { MarkdownChipRow } from "/src/components/Chip/MarkdownChipRow"; -## Overview + On Ethereum, there are two types of addresses: wallet addresses for holding assets and contract addresses. Wallet addresses are public accounts that can send and receive ETH tokens. Contract addresses refer to a smart contract that has been executed on Ethereum and the transactions associated with that contract. diff --git a/docs/developer-docs/multi-chain/ethereum/using-eth/signing-transactions.mdx b/docs/developer-docs/multi-chain/ethereum/using-eth/signing-transactions.mdx index 19410fe153..d380705ca7 100644 --- a/docs/developer-docs/multi-chain/ethereum/using-eth/signing-transactions.mdx +++ b/docs/developer-docs/multi-chain/ethereum/using-eth/signing-transactions.mdx @@ -10,7 +10,7 @@ import { MarkdownChipRow } from "/src/components/Chip/MarkdownChipRow"; -## Overview + Before a transaction can be sent to the Ethereum network, it must be signed and formatted into a raw ETH transaction. Transactions are signed with [threshold ECDSA](/docs/current/developer-docs/smart-contracts/signatures/t-ecdsa). For this example, the transaction standard EIP1559 will be used. diff --git a/docs/developer-docs/multi-chain/ethereum/using-eth/submit-transactions.mdx b/docs/developer-docs/multi-chain/ethereum/using-eth/submit-transactions.mdx index df9c900d0c..0df229cfc9 100644 --- a/docs/developer-docs/multi-chain/ethereum/using-eth/submit-transactions.mdx +++ b/docs/developer-docs/multi-chain/ethereum/using-eth/submit-transactions.mdx @@ -12,7 +12,7 @@ import { MarkdownChipRow } from "/src/components/Chip/MarkdownChipRow"; -## Overview + To submit transactions to the Ethereum network, first the transaction must be signed and formatted as an ETH transaction. [Learn more about signing transactions](signing-transactions.mdx). diff --git a/docs/developer-docs/multi-chain/examples.mdx b/docs/developer-docs/multi-chain/examples.mdx index 63627a8cdf..4265719bfe 100644 --- a/docs/developer-docs/multi-chain/examples.mdx +++ b/docs/developer-docs/multi-chain/examples.mdx @@ -8,7 +8,7 @@ import { MarkdownChipRow } from "/src/components/Chip/MarkdownChipRow"; -## Overview + ICP's Chain Fusion technology allows developers to build dapps that can interact seamlessly with other blockchain networks without using an intermediary, such as an oracle or a bridge. diff --git a/docs/developer-docs/multi-chain/overview.mdx b/docs/developer-docs/multi-chain/overview.mdx index 13de2a38d2..1056c4a6e3 100644 --- a/docs/developer-docs/multi-chain/overview.mdx +++ b/docs/developer-docs/multi-chain/overview.mdx @@ -8,7 +8,7 @@ import TabItem from "@theme/TabItem"; import { AdornedTabs } from "/src/components/Tabs/AdornedTabs"; import { AdornedTab } from "/src/components/Tabs/AdornedTab"; -# Chain Fusion overview +# What is Chain Fusion? @@ -434,7 +434,7 @@ There are several building blocks available to augment non-ICP smart contracts w - **[Threshold signatures](/docs/current/references/t-ecdsa-how-it-works)**: An ICP service implementing the threshold ECDSA and threshold Schnorr protocols. -- **[HTTPS outcalls](/docs/current/developer-docs/security/security-best-practices/https-outcalls)**: Replicated calls into external web services. +- **[HTTPS outcalls](/docs/current/developer-docs/smart-contracts/advanced-features/https-outcalls/https-outcalls-overview)**: Replicated calls into external web services. - **[Bitcoin API](/docs/current/references/bitcoin-how-it-works)**: A protocol API that allows canisters to interact with the Bitcoin blockchain directly. @@ -442,4 +442,4 @@ There are several building blocks available to augment non-ICP smart contracts w - [ICP Chain Fusion Educate - Bitcoin Edition: Introduction to ICP and Chain Fusion](https://www.youtube.com/watch?v=A0K9GXsfw74&list=PLfEHHr3qexv_L0t6KrCyJ-l2ZaHaO-m85). -- [ICP Chain Fusion Educate Powered by Encode Club](https://www.youtube.com/playlist?list=PLfEHHr3qexv9bjbFNp3ItK7yBZ5IQVXjf). \ No newline at end of file +- [ICP Chain Fusion Educate Powered by Encode Club](https://www.youtube.com/playlist?list=PLfEHHr3qexv9bjbFNp3ItK7yBZ5IQVXjf). diff --git a/docs/developer-docs/multi-chain/supported-chains.mdx b/docs/developer-docs/multi-chain/supported-chains.mdx index 06efed3971..4b0cfdb6ba 100644 --- a/docs/developer-docs/multi-chain/supported-chains.mdx +++ b/docs/developer-docs/multi-chain/supported-chains.mdx @@ -41,7 +41,7 @@ import { BetaChip } from "/src/components/Chip/BetaChip"; -## Overview + Other blockchain networks can be integrated with ICP if they leverage an authentication method that is supported by the threshold signing protocols of diff --git a/docs/developer-docs/security/security-best-practices/overview.mdx b/docs/developer-docs/security/security-best-practices/overview.mdx index 6d403f6e0e..b905431e1a 100644 --- a/docs/developer-docs/security/security-best-practices/overview.mdx +++ b/docs/developer-docs/security/security-best-practices/overview.mdx @@ -4,7 +4,7 @@ keywords: [security, concept] import { MarkdownChipRow } from "/src/components/Chip/MarkdownChipRow"; -# Overview +# What are security best practices? diff --git a/docs/developer-docs/security/security-best-practices/resources.mdx b/docs/developer-docs/security/security-best-practices/resources.mdx index 1cc7e29e6e..1de4ce1a02 100644 --- a/docs/developer-docs/security/security-best-practices/resources.mdx +++ b/docs/developer-docs/security/security-best-practices/resources.mdx @@ -10,7 +10,7 @@ import { MarkdownChipRow } from "/src/components/Chip/MarkdownChipRow"; -## Overview + Below are resources which cover security best practices for technologies you are likely using in your dapp. These best practices are equally important as our Internet Computer specific guidelines and should be studied carefully. They can be useful to reference when developing secure dapps or executing security reviews. ## General diff --git a/docs/developer-docs/smart-contracts/advanced-features/async-code.mdx b/docs/developer-docs/smart-contracts/advanced-features/async-code.mdx index 4ab1db4151..9a9089d24e 100644 --- a/docs/developer-docs/smart-contracts/advanced-features/async-code.mdx +++ b/docs/developer-docs/smart-contracts/advanced-features/async-code.mdx @@ -8,7 +8,7 @@ import { MarkdownChipRow } from "/src/components/Chip/MarkdownChipRow"; -## Overview + In programming, the [async/await pattern](https://en.wikipedia.org/wiki/Async/await) is a syntactic feature of many programming languages that allows an asynchronous, non-blocking function to be structured in a similar way to an ordinary synchronous function. @@ -20,7 +20,7 @@ The `async/await` pattern makes this look straightforward, as the developer can the callee is handled “synchronously”. However, given ICP's message passing model, one has to be careful in case there are [concurrent calls that message executions can interleave](/docs/current/references/message-execution-properties) as these can lead to inconsistencies if they are not anticipated. -## Overview of language runtime for asynchronous code + ## Language runtime for asynchronous code Most languages implement asynchronous code through constructs that they typically call [futures](https://docs.rs/futures/latest/futures/) ([promises](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise) in Javascript). A future is a representation diff --git a/docs/developer-docs/smart-contracts/advanced-features/composite-query.mdx b/docs/developer-docs/smart-contracts/advanced-features/composite-query.mdx index 7c2663b012..5f4db06c79 100644 --- a/docs/developer-docs/smart-contracts/advanced-features/composite-query.mdx +++ b/docs/developer-docs/smart-contracts/advanced-features/composite-query.mdx @@ -12,7 +12,7 @@ import { GlossaryTooltip } from "/src/components/Tooltip/GlossaryTooltip"; -## 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, especially those that shard data across multiple canisters. diff --git a/docs/developer-docs/smart-contracts/advanced-features/handling-get-post-requests.mdx b/docs/developer-docs/smart-contracts/advanced-features/handling-get-post-requests.mdx index 1d1f801617..a739b45263 100644 --- a/docs/developer-docs/smart-contracts/advanced-features/handling-get-post-requests.mdx +++ b/docs/developer-docs/smart-contracts/advanced-features/handling-get-post-requests.mdx @@ -12,7 +12,7 @@ import { MarkdownChipRow } from "/src/components/Chip/MarkdownChipRow"; -## Overview + Canisters running on ICP can use HTTP requests in two ways: incoming and outgoing. Incoming HTTP requests refer to HTTP requests that are sent to a canister and can be used to retrieve data from a canister or send new data to the canister. Outgoing HTTP requests refer to HTTP requests that the canister sends to other canisters or external services to retrieve data or send new data. @@ -110,13 +110,9 @@ For outgoing HTTP requests, the [HTTPS outcalls](./https-outcalls/https-outcalls ## Incoming HTTP requests -To handle incoming HTTP requests, canisters must define methods for `http_requests` and `http_requests_update` for `GET` and `POST` requests respectively. +Every HTTP request first goes to `http_request`, and only if you return `upgrade: true` will it be upgraded and re-called as `http_request_update`. The HTTP method (`GET`, `POST`) does not matter. -All HTTP requests are handled by the ICP HTTP Gateway, therefore you cannot make direct `POST` calls to a canister's `http_request_update` method with HTTP clients such as curl. Instead, you can make a `POST` call to a canister's HTTP endpoint, then configure the canister's `http_request` method to [upgrade the call to `http_request_update` if necessary](/docs/current/references/http-gateway-protocol-spec#upgrade-to-update-calls). Below is an example `POST` call to a canister's endpoint: - -``` -curl -X POST -H "Content-Type: application/json" -d '{"key":"value"}' https://.raw.ic0.app/ -``` +View the [HTTP Candid interface reference](/docs/current/references/http-gateway-protocol-spec#canister-http-interface) for more information. ## `GET` requests @@ -152,7 +148,9 @@ Check out the [Rust documentation](https://docs.rs/ic-cdk/latest/ic_cdk/attr.que ## `POST` requests -HTTP `POST` requests are used to send data to an endpoint with the intention of retaining that data. To handle incoming `POST` requests, the `http_request_update` method can be used. This method uses an `update` call, which can be used to change a canister's state. The following examples display how to configure `http_request_update` method within your canister. +HTTP `POST` requests are used to send data to an endpoint with the intention of retaining that data. You cannot make direct `POST` calls to a canister's `http_request_update` method with HTTP clients such as curl. Instead, you can make a `POST` call to a canister's HTTP endpoint, then configure the canister's `http_request` method to [upgrade the call to `http_request_update`](/docs/current/references/http-gateway-protocol-spec#upgrade-to-update-calls). + +The following examples display how to configure `http_request_update` method within your canister. diff --git a/docs/developer-docs/smart-contracts/advanced-features/https-outcalls/https-outcalls-get.mdx b/docs/developer-docs/smart-contracts/advanced-features/https-outcalls/https-outcalls-get.mdx index 2dfc04365c..7782198d78 100644 --- a/docs/developer-docs/smart-contracts/advanced-features/https-outcalls/https-outcalls-get.mdx +++ b/docs/developer-docs/smart-contracts/advanced-features/https-outcalls/https-outcalls-get.mdx @@ -13,7 +13,7 @@ import { MarkdownChipRow } from "/src/components/Chip/MarkdownChipRow"; -## Overview + A minimal example to make a `GET` HTTP request. The purpose of this dapp is only to show how to make HTTP requests from a canister. It sends a `GET` request to the Coinbase API and retrieves some historical data about the ICP token. diff --git a/docs/developer-docs/smart-contracts/advanced-features/https-outcalls/https-outcalls-overview.mdx b/docs/developer-docs/smart-contracts/advanced-features/https-outcalls/https-outcalls-overview.mdx index 0f0ecd89fc..1dcbcfd875 100644 --- a/docs/developer-docs/smart-contracts/advanced-features/https-outcalls/https-outcalls-overview.mdx +++ b/docs/developer-docs/smart-contracts/advanced-features/https-outcalls/https-outcalls-overview.mdx @@ -4,11 +4,11 @@ keywords: [https outcalls, advanced, concept] import { MarkdownChipRow } from "/src/components/Chip/MarkdownChipRow"; -# HTTPS outcalls overview +# What are HTTPS outcalls? -Canister smart contracts can make a request to a URL using [HTTPS outcalls](https://internetcomputer.org/https-outcalls). HTTPS outcalls can be used to directly obtain off-chain data or interact with off-chain systems, such as Web 2.0 services or enterprise IT infrastructure. +Canisterscan make a request to a URL using [HTTPS outcalls](https://internetcomputer.org/https-outcalls). HTTPS outcalls can be used to directly obtain off-chain data or interact with off-chain systems, such as Web 2.0 services or enterprise IT infrastructure. HTTPS outcalls enable a wide range of applications. For example, oracle services can directly integrate with ICP in a trustless manner, and dapps can provide user notifications or anything else that requires communication with servers on the Internet. diff --git a/docs/developer-docs/smart-contracts/advanced-features/https-outcalls/https-outcalls-post.mdx b/docs/developer-docs/smart-contracts/advanced-features/https-outcalls/https-outcalls-post.mdx index 59371eb8f4..d2d7b77b5b 100644 --- a/docs/developer-docs/smart-contracts/advanced-features/https-outcalls/https-outcalls-post.mdx +++ b/docs/developer-docs/smart-contracts/advanced-features/https-outcalls/https-outcalls-post.mdx @@ -12,7 +12,7 @@ import { MarkdownChipRow } from "/src/components/Chip/MarkdownChipRow"; -## Overview + A minimal example of how to make a `POST` HTTP request. The purpose of this dapp is only to show how to make HTTP requests from a canister. It sends a `POST` request with some JSON to a free API where you can verify the headers and body were sent correctly. diff --git a/docs/developer-docs/smart-contracts/advanced-features/management-canister.mdx b/docs/developer-docs/smart-contracts/advanced-features/management-canister.mdx index 28d74eeee9..ccd76a472b 100644 --- a/docs/developer-docs/smart-contracts/advanced-features/management-canister.mdx +++ b/docs/developer-docs/smart-contracts/advanced-features/management-canister.mdx @@ -12,7 +12,7 @@ import { MarkdownChipRow } from "/src/components/Chip/MarkdownChipRow"; -## Overview + The ICP management canister is used to provide access to system features, such as managing canisters, integrating with Bitcoin, making HTTPS outcalls, signing with threshold signatures, and securely retrieving randomness. diff --git a/docs/developer-docs/smart-contracts/advanced-features/periodic-tasks.mdx b/docs/developer-docs/smart-contracts/advanced-features/periodic-tasks.mdx index b8aed0f245..1f79c87176 100644 --- a/docs/developer-docs/smart-contracts/advanced-features/periodic-tasks.mdx +++ b/docs/developer-docs/smart-contracts/advanced-features/periodic-tasks.mdx @@ -14,7 +14,7 @@ import { MarkdownChipRow } from "/src/components/Chip/MarkdownChipRow"; -## Overview + Unlike other blockchains, ICP canisters can automatically execute tasks after a specified delay or interval. There are two ways to schedule an automatic canister execution on ICP: diff --git a/docs/developer-docs/smart-contracts/advanced-features/query-stats.mdx b/docs/developer-docs/smart-contracts/advanced-features/query-stats.mdx index f5a7380992..d71d644ce1 100644 --- a/docs/developer-docs/smart-contracts/advanced-features/query-stats.mdx +++ b/docs/developer-docs/smart-contracts/advanced-features/query-stats.mdx @@ -1,6 +1,6 @@ # Query stats -## Overview + When users interact with a dapp, query calls may be used. Query calls cannot modify a canister's state, making it impossible to track them from the canister's code. diff --git a/docs/developer-docs/smart-contracts/advanced-features/randomness.mdx b/docs/developer-docs/smart-contracts/advanced-features/randomness.mdx index 307b1c4993..bea955a696 100644 --- a/docs/developer-docs/smart-contracts/advanced-features/randomness.mdx +++ b/docs/developer-docs/smart-contracts/advanced-features/randomness.mdx @@ -13,7 +13,7 @@ import { BetaChip } from "/src/components/Chip/BetaChip"; -## Overview + The Internet Computer provides a secure and verifiable way to generate random numbers directly within canisters. This functionality is exposed through the [raw_rand](../../../references/ic-interface-spec.md) method offered by the [management canister](../advanced-features/management-canister.mdx) and the [Motoko Random module](/docs/current/motoko/main/base/Random). diff --git a/docs/developer-docs/smart-contracts/advanced-features/simd.mdx b/docs/developer-docs/smart-contracts/advanced-features/simd.mdx index aa7e0e87fd..82086b42c9 100644 --- a/docs/developer-docs/smart-contracts/advanced-features/simd.mdx +++ b/docs/developer-docs/smart-contracts/advanced-features/simd.mdx @@ -13,7 +13,7 @@ import { MarkdownChipRow } from "/src/components/Chip/MarkdownChipRow"; -## Overview + ICP supports deterministic WebAssembly SIMD support. This is a significant milestone for smart contracts demanding top onchain performance, such as artificial intelligence (AI), image processing (NFTs), games, scientific decentralized applications (dapps), and more. diff --git a/docs/developer-docs/smart-contracts/advanced-features/system-canisters.mdx b/docs/developer-docs/smart-contracts/advanced-features/system-canisters.mdx index 57d8564a23..e29c2574e4 100644 --- a/docs/developer-docs/smart-contracts/advanced-features/system-canisters.mdx +++ b/docs/developer-docs/smart-contracts/advanced-features/system-canisters.mdx @@ -8,7 +8,7 @@ import { MarkdownChipRow } from "/src/components/Chip/MarkdownChipRow"; -## Overview + System canisters are canisters that provide a necessary function to the ICP network. They are controlled by the NNS and upgraded via NNS proposals. These canisters have static canister IDs that projects can make calls to. One common example of a system canister that is used by projects is the Internet Identity canister. diff --git a/docs/developer-docs/smart-contracts/advanced-features/time-and-timestamps.mdx b/docs/developer-docs/smart-contracts/advanced-features/time-and-timestamps.mdx index e3a2d19857..01f84871a7 100644 --- a/docs/developer-docs/smart-contracts/advanced-features/time-and-timestamps.mdx +++ b/docs/developer-docs/smart-contracts/advanced-features/time-and-timestamps.mdx @@ -13,7 +13,7 @@ import { GlossaryTooltip } from "/src/components/Tooltip/GlossaryTooltip"; -## Overview + System time is a publicly exposed and verified part of the [IC state tree](/docs/current/references/ic-interface-spec#state-tree). System time is expressed in nanoseconds since `1970-01-01` and indicates the time at which the state is current. It is exposed at `/time`, and all partial state trees include a timestamp. diff --git a/docs/developer-docs/smart-contracts/best-practices/general.mdx b/docs/developer-docs/smart-contracts/best-practices/general.mdx index 0ad4374f35..2f96d49b1a 100644 --- a/docs/developer-docs/smart-contracts/best-practices/general.mdx +++ b/docs/developer-docs/smart-contracts/best-practices/general.mdx @@ -8,7 +8,7 @@ import { MarkdownChipRow } from "/src/components/Chip/MarkdownChipRow"; -## Overview + This guide outlines essential development best practices for building on the Internet Computer Protocol (ICP). diff --git a/docs/developer-docs/smart-contracts/best-practices/idempotency.mdx b/docs/developer-docs/smart-contracts/best-practices/idempotency.mdx index 66b2231a81..b20f6db610 100644 --- a/docs/developer-docs/smart-contracts/best-practices/idempotency.mdx +++ b/docs/developer-docs/smart-contracts/best-practices/idempotency.mdx @@ -9,7 +9,7 @@ import { MarkdownChipRow } from "/src/components/Chip/MarkdownChipRow"; -## Overview + In the case of network issues or other unexpected behavior, ICP clients (such as agents) that issue ingress update calls may be unable to determine whether their ingress diff --git a/docs/developer-docs/smart-contracts/best-practices/reproducible-builds.mdx b/docs/developer-docs/smart-contracts/best-practices/reproducible-builds.mdx index bce4af1759..e115bc91e7 100644 --- a/docs/developer-docs/smart-contracts/best-practices/reproducible-builds.mdx +++ b/docs/developer-docs/smart-contracts/best-practices/reproducible-builds.mdx @@ -10,7 +10,7 @@ import { GlossaryTooltip } from "/src/components/Tooltip/GlossaryTooltip"; -## Overview + If you are using a canister that you did not develop yourself, you may want to verify that the canister is running the code that you expect it to be before giving it control to make important decisions for you, such as accepting ICP for a payment. Verifying a canister's code requires confirming that the Wasm module is the correct result of compiling the canister source code and that the canister is in fact running that Wasm module and not another Wasm module. diff --git a/docs/developer-docs/smart-contracts/best-practices/storage.mdx b/docs/developer-docs/smart-contracts/best-practices/storage.mdx index 3d09844bd0..c7bb0f33c7 100644 --- a/docs/developer-docs/smart-contracts/best-practices/storage.mdx +++ b/docs/developer-docs/smart-contracts/best-practices/storage.mdx @@ -8,7 +8,7 @@ import { MarkdownChipRow } from "/src/components/Chip/MarkdownChipRow"; -## Overview + There are two forms of storage available to ICP canisters: **heap memory** and **stable memory**. diff --git a/docs/developer-docs/smart-contracts/best-practices/troubleshooting.mdx b/docs/developer-docs/smart-contracts/best-practices/troubleshooting.mdx index 123fa74c0d..356e84d7f9 100644 --- a/docs/developer-docs/smart-contracts/best-practices/troubleshooting.mdx +++ b/docs/developer-docs/smart-contracts/best-practices/troubleshooting.mdx @@ -8,7 +8,7 @@ import { MarkdownChipRow } from "/src/components/Chip/MarkdownChipRow"; -## Overview + When a dapp or canister is running with a high amount of latency, there are some steps that developers can take to troubleshoot or optimize the performance of their canisters. diff --git a/docs/developer-docs/smart-contracts/call/overview.mdx b/docs/developer-docs/smart-contracts/call/overview.mdx index 5ef5910778..20bfde5816 100644 --- a/docs/developer-docs/smart-contracts/call/overview.mdx +++ b/docs/developer-docs/smart-contracts/call/overview.mdx @@ -9,7 +9,7 @@ import { BetaChip } from "/src/components/Chip/BetaChip"; import { MarkdownChipRow } from "/src/components/Chip/MarkdownChipRow"; import { GlossaryTooltip } from "/src/components/Tooltip/GlossaryTooltip"; -# Call overview +# Calling canisters diff --git a/docs/developer-docs/smart-contracts/candid/candid-concepts.mdx b/docs/developer-docs/smart-contracts/candid/candid-concepts.mdx index 724bea1ddf..0cb85a3dac 100644 --- a/docs/developer-docs/smart-contracts/candid/candid-concepts.mdx +++ b/docs/developer-docs/smart-contracts/candid/candid-concepts.mdx @@ -10,7 +10,7 @@ import { GlossaryTooltip } from "/src/components/Tooltip/GlossaryTooltip"; -## Overview + Candid is an **interface description language**. Its primary purpose is to describe the public interface of a **service**, usually in the form of a program deployed as a canister that runs on the Internet Computer. One of the key benefits of Candid is that it is language-agnostic, and allows inter-operation between services and frontends written in different programming languages, including Motoko, Rust, and JavaScript. diff --git a/docs/developer-docs/smart-contracts/candid/candid-howto.mdx b/docs/developer-docs/smart-contracts/candid/candid-howto.mdx index 3ee957c4db..11006e0e76 100644 --- a/docs/developer-docs/smart-contracts/candid/candid-howto.mdx +++ b/docs/developer-docs/smart-contracts/candid/candid-howto.mdx @@ -9,7 +9,7 @@ import { GlossaryTooltip } from "/src/components/Tooltip/GlossaryTooltip"; -## Overview + Candid provides a language-agnostic way to interact with canisters. diff --git a/docs/developer-docs/smart-contracts/candid/candid-tools.mdx b/docs/developer-docs/smart-contracts/candid/candid-tools.mdx index cbfb0a6d05..bfe794f1cf 100644 --- a/docs/developer-docs/smart-contracts/candid/candid-tools.mdx +++ b/docs/developer-docs/smart-contracts/candid/candid-tools.mdx @@ -8,7 +8,7 @@ import { MarkdownChipRow } from "/src/components/Chip/MarkdownChipRow"; -## Overview + Candid is an **interface description language** that can be used by ICP canisters to define the public interface of a service. Candid is language-agnostic and allows for the inter-operation of services and frontends written in different programming languages, including Motoko, Rust, and JavaScript. diff --git a/docs/developer-docs/smart-contracts/compile.mdx b/docs/developer-docs/smart-contracts/compile.mdx index 86c542753f..edbfa3f8ab 100644 --- a/docs/developer-docs/smart-contracts/compile.mdx +++ b/docs/developer-docs/smart-contracts/compile.mdx @@ -14,7 +14,7 @@ import { MarkdownChipRow } from "/src/components/Chip/MarkdownChipRow"; -## Overview + After you have [written the code](/docs/current/developer-docs/smart-contracts/write/overview) for your project's canisters and [created them](/docs/current/developer-docs/smart-contracts/create), you need to compile the code into a WebAssembly module before it can be deployed on ICP. diff --git a/docs/developer-docs/smart-contracts/create.mdx b/docs/developer-docs/smart-contracts/create.mdx index 75abc51005..131e109c99 100644 --- a/docs/developer-docs/smart-contracts/create.mdx +++ b/docs/developer-docs/smart-contracts/create.mdx @@ -14,7 +14,7 @@ import { GlossaryTooltip } from "/src/components/Tooltip/GlossaryTooltip"; -## Overview + Canisters contain both code and state. Once you have written the code for a canister, the canister doesn't exist until it is registered with ICP, either locally, on the playground, or on the mainnet. diff --git a/docs/developer-docs/smart-contracts/deploy/custom-testnets.mdx b/docs/developer-docs/smart-contracts/deploy/custom-testnets.mdx index 1675bc55a9..cbc1937c5a 100644 --- a/docs/developer-docs/smart-contracts/deploy/custom-testnets.mdx +++ b/docs/developer-docs/smart-contracts/deploy/custom-testnets.mdx @@ -5,7 +5,7 @@ import { GlossaryTooltip } from "/src/components/Tooltip/GlossaryTooltip"; -## Overview + ICP does not have a public testnet network that developers can use to deploy and test canisters because canisters deployed to the mainnet can be upgraded and changed. Plus, deployment costs are fairly low compared to other chains. diff --git a/docs/developer-docs/smart-contracts/deploy/overview.mdx b/docs/developer-docs/smart-contracts/deploy/overview.mdx index 0185a6c09a..8753c55cdd 100644 --- a/docs/developer-docs/smart-contracts/deploy/overview.mdx +++ b/docs/developer-docs/smart-contracts/deploy/overview.mdx @@ -10,7 +10,7 @@ import { BetaChip } from "/src/components/Chip/BetaChip"; import { MarkdownChipRow } from "/src/components/Chip/MarkdownChipRow"; import { GlossaryTooltip } from "/src/components/Tooltip/GlossaryTooltip"; -# Deploy overview +# Deploying canisters diff --git a/docs/developer-docs/smart-contracts/encryption/using-vetkeys.mdx b/docs/developer-docs/smart-contracts/encryption/using-vetkeys.mdx index 1c147ab3dc..7c5d27189b 100644 --- a/docs/developer-docs/smart-contracts/encryption/using-vetkeys.mdx +++ b/docs/developer-docs/smart-contracts/encryption/using-vetkeys.mdx @@ -12,7 +12,7 @@ import { MarkdownChipRow } from "/src/components/Chip/MarkdownChipRow"; -## Overview + This demo provides a canister (`src/system_api`) that offers the [proposed vetKD system API](https://github.com/dfinity/interface-spec/pull/158), implemented demonstration, testing, and initial development purposes. We stress that it does not offer security yet as no threshold cryptography is used yet to secure the key. diff --git a/docs/developer-docs/smart-contracts/encryption/vetkeys.mdx b/docs/developer-docs/smart-contracts/encryption/vetkeys.mdx index 180abbdb57..74bd09fd28 100644 --- a/docs/developer-docs/smart-contracts/encryption/vetkeys.mdx +++ b/docs/developer-docs/smart-contracts/encryption/vetkeys.mdx @@ -4,7 +4,7 @@ keywords: [advanced, concept, vetkd, vetkeys] import { MarkdownChipRow } from "/src/components/Chip/MarkdownChipRow"; -# Overview +# What are vetKeys? diff --git a/docs/developer-docs/smart-contracts/install.mdx b/docs/developer-docs/smart-contracts/install.mdx index 4e768572e8..ea21efd9b6 100644 --- a/docs/developer-docs/smart-contracts/install.mdx +++ b/docs/developer-docs/smart-contracts/install.mdx @@ -14,7 +14,7 @@ import { GlossaryTooltip } from "/src/components/Tooltip/GlossaryTooltip"; -## Overview + When a canister has been initially created, it is empty and does not contain code or state. It only contains information such as the settings, canister ID, cycles balance, and controllers. [Learn more about creating a canister](/docs/current/developer-docs/smart-contracts/create). diff --git a/docs/developer-docs/smart-contracts/maintain/control.mdx b/docs/developer-docs/smart-contracts/maintain/control.mdx index 49c8878b1c..14965d0a05 100644 --- a/docs/developer-docs/smart-contracts/maintain/control.mdx +++ b/docs/developer-docs/smart-contracts/maintain/control.mdx @@ -11,7 +11,7 @@ import { GlossaryTooltip } from "/src/components/Tooltip/GlossaryTooltip"; -## Overview + A canister is managed by a list of controllers. A controller is specified by a principal, which can be self-authenticating, e.g. a `dfx` developer identity, or another canister. Canisters can have multiple controllers where each has the same administrative rights, or it can have no controller, in which case the canister becomes immutable (blackholed) and cannot be upgraded or deleted. diff --git a/docs/developer-docs/smart-contracts/maintain/delete.mdx b/docs/developer-docs/smart-contracts/maintain/delete.mdx index 72bb900183..69bb27b500 100644 --- a/docs/developer-docs/smart-contracts/maintain/delete.mdx +++ b/docs/developer-docs/smart-contracts/maintain/delete.mdx @@ -9,7 +9,7 @@ import { GlossaryTooltip } from "/src/components/Tooltip/GlossaryTooltip"; -## Overview + If you want to permanently delete a specific canister or all canisters for a project, you can use the [`dfx canister delete `](/docs/current/developer-docs/developer-tools/cli-tools/cli-reference/dfx-canister#dfx-canister-delete) command. diff --git a/docs/developer-docs/smart-contracts/maintain/history.mdx b/docs/developer-docs/smart-contracts/maintain/history.mdx index 4d4aa075e7..cc57348522 100644 --- a/docs/developer-docs/smart-contracts/maintain/history.mdx +++ b/docs/developer-docs/smart-contracts/maintain/history.mdx @@ -14,7 +14,7 @@ import { GlossaryTooltip } from "/src/components/Tooltip/GlossaryTooltip"; -## Overview + The Internet Computer tracks the history of a deployed canister through the canister's Wasm module hashes and controller changes. This tracking provides insight into the canister's history, such as what code has been used to run the canister and which controller deployed that code. diff --git a/docs/developer-docs/smart-contracts/maintain/import.mdx b/docs/developer-docs/smart-contracts/maintain/import.mdx index 4aac16cab1..c080e0526e 100644 --- a/docs/developer-docs/smart-contracts/maintain/import.mdx +++ b/docs/developer-docs/smart-contracts/maintain/import.mdx @@ -5,46 +5,89 @@ keywords: [beginner, tutorial, maintain canisters, import, pullable canisters] import { MarkdownChipRow } from "/src/components/Chip/MarkdownChipRow"; import { GlossaryTooltip } from "/src/components/Tooltip/GlossaryTooltip"; -# Import +# Using third-party canisters -## Overview +Third-party canisters are canisters created by DFINITY or ICP community members that provide an important functionality that other developers may want to integrate within their own projects. It is important to test integrations with these canisters locally to: -The interoperability of canisters is a vital feature for many developers. `dfx` provides a consistent developer workflow for creating, integrating and testing third-party canisters with local developer environments. +- Validate the accuracy of the integration and other canister code. +- Test without paying cycles. +- Use non-production data and environments. +- Execute operations faster when run locally. -Third-party canisters include canisters created by DFINITY or by developers in ICP community. Developers depend on third-party canisters to integrate with. They typically need a way to develop and test the integrations locally for: -- Validating the accuracy of the integration and other canister code. -- Testing without paying cycles. -- Using non-production data and environments. -- Faster completion time when run locally. +To integrate with third-party canisters and test them within your project, you can either: -To pull these canisters from the mainnet to be tested locally, the [`dfx deps`](/docs/current/developer-docs/developer-tools/cli-tools/cli-reference/dfx-deps) command and workflow can be used. +- If the canister's Candid and Wasm files are publicly available, the URLs of the files can be referenced directly in the project's `dfx.json` file. -In this workflow, a **service provider** configures a canister to be `pullable`, then deploys the canister to the mainnet. A service provider can be any community developer creating a public, third-party canister. +- If the canister is configured as `pullable`, it can be pulled into a project with `dfx deps`. -Then a **service consumer** can pull the canister as a dependency directly from the mainnet and then deploy the dependency locally. +## Using a canister's Candid and Wasm files directly -## Determining if a canister should be `pullable` +If a canister's Candid and Wasm files are publicly available, you can reference them directly in a project's `dfx.json` file. -First the canister must be configured to be `pullable`. Developers must ask question whether the canister *should* be `pullable`? +If the canister is deployed to the mainnet, you can also specify the `remote` canister ID. When your project is deployed to the mainnet, it will use the mainnet canister with that ID. When your project is deployed locally, `dfx` will download the specified Candid and Wasm files and create a new local canister using them. -#### `Pullable` examples: +```json +{ + "canisters": { + "icp_ledger_canister": { + "type": "custom", + "candid": "https://raw.githubusercontent.com/dfinity/ic/aba60ffbc46acfc8990bf4d5685c1360bd7026b9/rs/ledger_suite/icp/ledger.did", + "wasm": "https://download.dfinity.systems/ic/aba60ffbc46acfc8990bf4d5685c1360bd7026b9/canisters/ledger-canister.wasm.gz", + "remote": { + "id": { + "ic": "ryjl3-tyaaa-aaaaa-aaaba-cai" + } + }, +... +``` -If a canister is providing a public service at a static canister ID, then it makes sense for the canister to be `pullable`. +Alternatively, you can reference Candid and Wasm files stored in your local environment: -If a service canister depends on other canisters, those dependencies should also be `pullable`. +```json +{ + "canisters": { + "icp_ledger_canister": { + "type": "custom", + "candid": "ledger.did", + "wasm": "ledger-canister.wasm.gz", + "remote": { + "id": { + "ic": "ryjl3-tyaaa-aaaaa-aaaba-cai" + } + }, +... +``` -#### Non-`pullable` examples: +An example of using this method is the [XRC demo project.](https://github.com/THLO/xrc_demo/blob/main/dfx.json#L15) -If the canister is meant for personal use and not intended for others, the canister should not be `pullable`. +## Using `dfx deps` to pull third-party canisters + +The command and workflow can be used to pull third-party canisters into a project that is deployed locally or on the mainnet. + +In this workflow, a **service provider** configures a canister to be `pullable`, then deploys the canister to the mainnet. A service provider can be anyone, such as a community developer creating a public, third-party canister. + +Then a **service consumer** can pull the canister as a dependency directly from the mainnet using [`dfx deps`](/docs/current/developer-docs/developer-tools/cli-tools/cli-reference/dfx-deps) and deploy the dependency locally. + +### Determining if a canister should be `pullable` + +First the canister must be configured to be `pullable`. Developers must ask question whether the canister *should* be `pullable`? Canisters should be `pullable` if it provides a public service at a static canister ID. If it depends on other canisters, those dependencies should also be `pullable`. + +### Configuring a canister to be `pullable` + +A service provider must configure a canister to be `pullable` by setting the following configuration details in the project's `dfx.json` file: + +- `wasm_url`: A URL used to download the canister Wasm module which will be deployed locally. +- `wasm_hash`: A SHA256 hash of the Wasm module located at `wasm_url`. This field is optional. In most cases, the Wasm module at `wasm_url` will be the same as the onchain Wasm module. This means that `dfx` can read the state tree to obtain and verify the module hash. In some cases, the Wasm module at `wasm_url` is not the same as the onchain Wasm module. For example, the Internet Identity canister provides a `development` variant to be integrated locally. In these cases, `wasm_hash` provides the expected hash, and `dfx` verifies the downloaded Wasm against this. -If a canister's Wasm is published for other developers to use, then the canister should not be `pullable` since the canister ID of the instance is not static. Users can test integrations locally and deploy them using the Wasm file directly. +:::caution +If the `wasm_hash` of the Wasm module at `wasm_url` does not match, `dfx` will abort with an error message indicating that there is a hash mismatch. In this scenario, the service consumer should contact the service provider. It is the responsibility of the service provider to assure that the correct Wasm module can be downloaded from the `wasm_url`. +::: -## Service provider workflow -First, a service provider must configure a canister to be `pullable` by setting it as such in the `dfx.json` file. +- `dependencies`: An array of canister IDs (`Principal`) of direct dependencies. +- `init_guide`: A message to guide consumers how to initialize the canister. -An example of a provider `dfx.json` which has a `pullable` "service" canister can be found below: ```json { @@ -66,55 +109,35 @@ An example of a provider `dfx.json` which has a `pullable` "service" canister ca ``` :::danger -The Wasm module of a `pullable` canister must be hosted via a public URL where service consumers can download it. - -GitHub Releases are a good, free option if the project is open source on GitHub. The GitHub URL schema is: - -`https://github.com///releases/latest/download/` - +The Wasm module of a `pullable` canister must be hosted via a public URL where service consumers can download it, such as GitHub. ::: The `pullable` object will be serialized as a part of the `dfx` metadata and attached to the Wasm. -To better understand the `pullable` object, let's look at each property in depth: - -- `wasm_url`: A URL used to download the canister Wasm module which will be deployed locally. -- `wasm_hash`: A SHA256 hash of the Wasm module located at `wasm_url`. This field is optional. In most cases, the Wasm module at `wasm_url` will be the same as the onchain Wasm module. This means that `dfx` can read the state tree to obtain and verify the module hash. In some cases, the Wasm module at `wasm_url` is not the same as the onchain Wasm module. For example, the Internet Identity canister provides a `development` variant to be integrated locally. In these cases, `wasm_hash` provides the expected hash, and `dfx` verifies the downloaded Wasm against this. - -:::caution -If the `wasm_hash` of the Wasm module at `wasm_url` does not match, `dfx` will abort with an error message indicating that there is a hash mismatch. In this scenario, the service consumer should contact the service provider. It is the responsibility of the service provider to assure that the correct Wasm module can be downloaded from the `wasm_url`. -::: - -- `dependencies`: An array of canister IDs (`Principal`) of direct dependencies. -- `init_guide`: A message to guide consumers how to initialize the canister. - ### Canister metadata requirements -A service provider canister used in production or in a production environment running on the mainnet should have public `dfx` metadata and public or private `candid:service` and `candid:args` metadata. - -All metadata sections are handled by `dfx` when the canister is built. +A third-party canister used in production should have public `dfx` metadata and public or private `candid:service` and `candid:args` metadata. All metadata sections are handled by `dfx` when the canister is built. ### Deployment process -Service providers should use the following deployment process to deploy their `pullable` canister. -- #### Step 1: From within your project's repo, deploy the canister to the mainnet with the command: +Service providers should use the following deployment process to deploy their `pullable` canister and make it available to others: + +- #### Step 1: Deploy the canister to the mainnet. ``` dfx deploy --network ic ``` -- #### Step 2: If you're using GitHub, `git tag` and `GitHub release` with the commands: +- #### Step 2: If you're using GitHub, [`git tag` and `GitHub release`](https://docs.github.com/en/repositories/releasing-projects-on-github/managing-releases-in-a-repository#creating-a-release) with the commands: ``` git tag 0.1.0 git push --tags ``` -You can follow [this guide](https://docs.github.com/en/repositories/releasing-projects-on-github/managing-releases-in-a-repository#creating-a-release) to create a release. - - #### Step 3: Attach the Wasm to the release assets. -Edit the release and attach the deployed Wasm as a release asset. The deployed Wasm file will be located at: +Edit the GitHub release and attach the deployed Wasm as a release asset. The deployed Wasm file will be located at: ``` .dfx/ic/canisters//.wasm @@ -130,14 +153,12 @@ The workflow with CI will follow these steps: 2. Download the canister Wasm from the release assets (`wget https://github.com/lwshang/pullable/releases/latest/download/service.wasm`). 3. Install (upgrade) the canister using the downloaded Wasm (`dfx canister --network ic install service --wasm service.wasm --argument '(1 : nat)' --mode upgrade`). -## Consumer workflow +### Pulling a third-party canister into your project -The following workflow can be used for consumers to pull a `pullable` canister as a dependency. +The following workflow can be used for consumers to import a `pullable` canister as a dependency. - #### Step 1: Declare "pull" dependencies in `dfx.json`. -First, the `dfx.json` file must include the `dependencies` configuration for the canister. - An example `dfx.json` in which the consumer is developing a canister named "dapp" that has two pull dependencies can be found below: - "dep_b" has canister ID of `yhgn4-myaaa-aaaaa-aabta-cai` on the mainnet. @@ -171,67 +192,13 @@ An example `dfx.json` in which the consumer is developing a canister named "dapp `dfx deps pull` connects to the mainnet by default (`--network ic`). You can choose other network as usual, e.g. `--network local`. ::: -Running this command will do the following: - -1. First, it will resolve the dependency graph by fetching the `dependencies` field in the `dfx` metadata recursively. -2. Then, it will download the Wasm of all direct and indirect dependencies from `wasm_url` into the shared cache. -3. Next, the hash of the downloaded Wasm will be verified against `wasm_hash` metadata or the hash of the canister deployed on mainnet. -4. Then, `candid:args`, `candid:service`, `dfx` metadata will be extracted from the downloaded Wasm. -5. The `deps/` folder is created in the project root. -6. The `candid:service` of direct dependencies is saved as `deps/candid/.did`. -7. The `deps/pulled.json` which contains major info of all direct and indirect dependencies is saved. - -For the example project, you will find the following files in `deps/`: - -- `yhgn4-myaaa-aaaaa-aabta-cai.did` and `yahli-baaaa-aaaaa-aabtq-cai.did`: Candid files that can be imported by "dapp". -- `pulled.json`: A json file with the following content: - -```json -{ - "canisters": { - "yofga-2qaaa-aaaaa-aabsq-cai": { - "dependencies": [], - "wasm_hash": "e9b8ba2ad28fa1403cf6e776db531cdd6009a8e5cac2b1097d09bfc65163d56f", - "init_guide": "A natural number, e.g. 10.", - "candid_args": "(nat)" - }, - "yhgn4-myaaa-aaaaa-aabta-cai": { - "name": "dep_b", - "dependencies": [ - "yofga-2qaaa-aaaaa-aabsq-cai" - ], - "wasm_hash": "f607c30727b0ee81317fc4547a8da3cda9bb9621f5d0740806ef973af5b479a2", - "init_guide": "No init arguments required", - "candid_args": "()" - }, - "yahli-baaaa-aaaaa-aabtq-cai": { - "name": "dep_c", - "dependencies": [ - "yofga-2qaaa-aaaaa-aabsq-cai" - ], - "wasm_hash": "016df9800dc5760785646373bcb6e6bb530fc17f844600991a098ef4d486cf0b", - "init_guide": "A natural number, e.g. 20.", - "candid_args": "(nat)" - } - } -} -``` - -In this file, you can see there are three dependencies: - -- `yhgn4-myaaa-aaaaa-aabta-cai`: "dep_b" in `dfx.json`. -- `yahli-baaaa-aaaaa-aabtq-cai`: "dep_c" in `dfx.json`. -- `yofga-2qaaa-aaaaa-aabsq-cai`: An indirect dependency that both "dep_b" and "dep_c" depend on. - -- #### Step 3: Set init arguments using `dfx deps init` +- #### Step 3: Set init arguments using `dfx deps init`. Running the command `dfx deps init` will iterate over all dependencies in the `pulled.json` file and set an empty argument for any that do not need an `init` argument. Then, it will print the list of dependencies that do require an `init` argument. Running the command `dfx deps init --argument ` will set the `init` argument for an individual dependency. The init arguments will be recorded in `deps/init.json`. -Using the example above, you can run the following commands: - -- To set the init arguments: +To set the init arguments: ``` dfx deps init @@ -248,7 +215,7 @@ yahli-baaaa-aaaaa-aabtq-cai (dep_c) -- If you try to set an `init` argument for an individual dependency without an argument, it will result in the following error: +If you try to set an `init` argument for an individual dependency without an argument, it will result in the following error: ``` Error: Canister yofga-2qaaa-aaaaa-aabsq-cai requires an init argument. The following info might be helpful: @@ -256,10 +223,10 @@ init_guide => A natural number, e.g. 10. candid:args => (nat) ``` -- To set an init argument with an argument using the `--argument` flag, the following commands can be used: +To set an init argument with an argument using the `--argument` flag: ``` -dfx deps init yofga-2qaaa-aaaaa-aabsq-cai --argument 10 +dfx deps init --argument 10 dfx deps init deps_c --argument 20 ``` @@ -284,36 +251,24 @@ The resulting generated file `init.json` will have the following content: } ``` -- #### Step 4: Deploy the pulled dependencies on a local replica using the `dfx deps deploy` command. +- #### Step 4: Deploy the pulled dependencies in your local environment using the `dfx deps deploy` command. + +``` +dfx deps deploy +``` Running the `dfx deps deploy` command will: -1. First, create the dependencies on the local replica with the same mainnet canister ID. +1. Create the dependencies in your local environment with the same mainnet canister ID. 2. Then, it will install the downloaded Wasm with the init arguments in the `init.json` file. You can also specify the canister name or principal to deploy one particular dependency. -Using the example above, you can run the following command to deploy all dependencies: - -``` -dfx deps deploy -``` - -
-Output -Creating canister: yofga-2qaaa-aaaaa-aabsq-cai -Installing canister: yofga-2qaaa-aaaaa-aabsq-cai -Creating canister: yhgn4-myaaa-aaaaa-aabta-cai (dep_b) -Installing canister: yhgn4-myaaa-aaaaa-aabta-cai (dep_b) -Creating canister: yahli-baaaa-aaaaa-aabtq-cai (dep_c) -Installing canister: yahli-baaaa-aaaaa-aabtq-cai (dep_c) -
- :::info `dfx deps deploy` always creates the canister with the anonymous identity so that dependencies and application canisters will have different controllers. It will also always install the canister in "reinstall" mode so that the canister status will be discarded. ::: -## Frequently asked questions +### Frequently asked questions - #### Why download the Wasm into shared cache instead of a project subfolder? diff --git a/docs/developer-docs/smart-contracts/maintain/logs.mdx b/docs/developer-docs/smart-contracts/maintain/logs.mdx index 6ed299224c..d49ae1444b 100644 --- a/docs/developer-docs/smart-contracts/maintain/logs.mdx +++ b/docs/developer-docs/smart-contracts/maintain/logs.mdx @@ -9,7 +9,7 @@ import { GlossaryTooltip } from "/src/components/Tooltip/GlossaryTooltip"; -## Overview + The canister logging feature is designed to provide developers with insight into their canister's behavior and assist with scenarios where their canister traps. This feature supports log messages for: diff --git a/docs/developer-docs/smart-contracts/maintain/recovery.mdx b/docs/developer-docs/smart-contracts/maintain/recovery.mdx index 4b0a1f3730..d1a2a9cdb1 100644 --- a/docs/developer-docs/smart-contracts/maintain/recovery.mdx +++ b/docs/developer-docs/smart-contracts/maintain/recovery.mdx @@ -9,7 +9,7 @@ import { GlossaryTooltip } from "/src/components/Tooltip/GlossaryTooltip"; -## Overview + A canister is managed and maintained by **controllers**. A controller can be a single developer identity, a list of developer identities, or another canister. If a canister does not have a controller, it cannot be upgraded, deleted, or otherwise maintained. This also applies if access to all canister's controllers identities are lost. If a canister's code traps with an unrecoverable error and cannot be upgraded, the canister can potentially be recovered using canister snapshots or an NNS proposal. diff --git a/docs/developer-docs/smart-contracts/maintain/resource-limits.mdx b/docs/developer-docs/smart-contracts/maintain/resource-limits.mdx index 1f1d6b151b..062fec3f77 100644 --- a/docs/developer-docs/smart-contracts/maintain/resource-limits.mdx +++ b/docs/developer-docs/smart-contracts/maintain/resource-limits.mdx @@ -10,7 +10,7 @@ import { Tooltip } from "/src/components/Tooltip/Tooltip"; -## Overview + The Internet Computer uses WebAssembly as the platform for executing messages of smart contracts. Since WebAssembly is [Turing-complete](https://en.wikipedia.org/wiki/Turing_completeness), it can express different kinds of computations including non-terminating computations. diff --git a/docs/developer-docs/smart-contracts/maintain/settings.mdx b/docs/developer-docs/smart-contracts/maintain/settings.mdx index 9e0efe905f..60e8a55dc4 100644 --- a/docs/developer-docs/smart-contracts/maintain/settings.mdx +++ b/docs/developer-docs/smart-contracts/maintain/settings.mdx @@ -11,7 +11,7 @@ import { GlossaryTooltip } from "/src/components/Tooltip/GlossaryTooltip"; -## Overview + Each canister has a group of possible settings that control its behavior. diff --git a/docs/developer-docs/smart-contracts/maintain/snapshots.mdx b/docs/developer-docs/smart-contracts/maintain/snapshots.mdx index bd4ba13384..599e6d2d8b 100644 --- a/docs/developer-docs/smart-contracts/maintain/snapshots.mdx +++ b/docs/developer-docs/smart-contracts/maintain/snapshots.mdx @@ -9,7 +9,7 @@ import { GlossaryTooltip } from "/src/components/Tooltip/GlossaryTooltip"; -## Overview + A canister contains compiled Wasm code and data, such as the canister ID, settings, and Wasm memory. If a canister stops working as expected, traps, or simply needs to be rolled back to a previous version, the developer can use canister snapshots. Developers can take a snapshot of a stopped canister to save the canister's current stable memory, heap memory, data, and Wasm module. This snapshot can be loaded at a later date, rolling the canister back to the code and data saved within that snapshot. diff --git a/docs/developer-docs/smart-contracts/maintain/state.mdx b/docs/developer-docs/smart-contracts/maintain/state.mdx index 36f1ab4edd..534e648e28 100644 --- a/docs/developer-docs/smart-contracts/maintain/state.mdx +++ b/docs/developer-docs/smart-contracts/maintain/state.mdx @@ -9,7 +9,7 @@ import { GlossaryTooltip } from "/src/components/Tooltip/GlossaryTooltip"; -## Overview + After you deploy a canister, it can begin receiving and processing requests from users and from other canisters. Canisters that are available to send requests and receive replies are considered in be in a **Running** state. diff --git a/docs/developer-docs/smart-contracts/maintain/storage.mdx b/docs/developer-docs/smart-contracts/maintain/storage.mdx index 19847ca6c6..be53920b36 100644 --- a/docs/developer-docs/smart-contracts/maintain/storage.mdx +++ b/docs/developer-docs/smart-contracts/maintain/storage.mdx @@ -9,7 +9,7 @@ import { GlossaryTooltip } from "/src/components/Tooltip/GlossaryTooltip"; -## Overview + When developing projects on ICP, there are two primary forms of data storage that your canisters can utilize. The first type of storage is the canister's **heap memory**, sometimes referred to as the canister's *main memory*. Heap memory is **temporary**, and any data stored in a canister's heap memory is cleared whenever the canister is reinstalled or upgraded. diff --git a/docs/developer-docs/smart-contracts/maintain/trapping.mdx b/docs/developer-docs/smart-contracts/maintain/trapping.mdx index 4f77674b52..474cbc5979 100644 --- a/docs/developer-docs/smart-contracts/maintain/trapping.mdx +++ b/docs/developer-docs/smart-contracts/maintain/trapping.mdx @@ -9,7 +9,7 @@ import { GlossaryTooltip } from "/src/components/Tooltip/GlossaryTooltip"; -## Overview + Trapping, in the context of WebAssembly code, refers to an interruption of code execution that returns an error. Trapping is defined by [the WebAssembly documentation](https://webassembly.github.io/spec/core/intro/overview.html) as: diff --git a/docs/developer-docs/smart-contracts/maintain/upgrade.mdx b/docs/developer-docs/smart-contracts/maintain/upgrade.mdx index 86b6d53bec..aed683d785 100644 --- a/docs/developer-docs/smart-contracts/maintain/upgrade.mdx +++ b/docs/developer-docs/smart-contracts/maintain/upgrade.mdx @@ -9,7 +9,7 @@ import { GlossaryTooltip } from "/src/components/Tooltip/GlossaryTooltip"; -## Overview + Unlike a canister reinstall that preserves the canister identifier but no state, a canister upgrade enables you to preserve the state of a deployed canister and change the code. diff --git a/docs/developer-docs/smart-contracts/overview/introduction.mdx b/docs/developer-docs/smart-contracts/overview/introduction.mdx index 724264107c..09f42fdae2 100644 --- a/docs/developer-docs/smart-contracts/overview/introduction.mdx +++ b/docs/developer-docs/smart-contracts/overview/introduction.mdx @@ -6,7 +6,7 @@ import { MarkdownChipRow } from "/src/components/Chip/MarkdownChipRow"; import { GlossaryTooltip } from "/src/components/Tooltip/GlossaryTooltip"; -# Introduction +# What are canisters? diff --git a/docs/developer-docs/smart-contracts/overview/trust-in-canisters.mdx b/docs/developer-docs/smart-contracts/overview/trust-in-canisters.mdx index 3c65c7ee6a..6035c6219f 100644 --- a/docs/developer-docs/smart-contracts/overview/trust-in-canisters.mdx +++ b/docs/developer-docs/smart-contracts/overview/trust-in-canisters.mdx @@ -8,7 +8,7 @@ import { MarkdownChipRow } from "/src/components/Chip/MarkdownChipRow"; -## Overview + Applications that provide DeFi or other valuable transactions, such as the ability to transfer assets, require that users trust the application to act honestly and reliably. How can one ensure that it is safe to entrust assets to a canister? diff --git a/docs/developer-docs/smart-contracts/signatures/signing-messages-t-ecdsa.mdx b/docs/developer-docs/smart-contracts/signatures/signing-messages-t-ecdsa.mdx index 562ee12ae6..240f9ec7e2 100644 --- a/docs/developer-docs/smart-contracts/signatures/signing-messages-t-ecdsa.mdx +++ b/docs/developer-docs/smart-contracts/signatures/signing-messages-t-ecdsa.mdx @@ -13,7 +13,7 @@ import { MarkdownChipRow } from "/src/components/Chip/MarkdownChipRow"; -## Overview + The threshold ECDSA API allows canisters to securely sign messages and transactions without the corresponding private keys ever existing. Each canister can control an unlimited number of keys by specifying different key `derivation_path`s. The API provides two methods: diff --git a/docs/developer-docs/smart-contracts/signatures/signing-messages-t-schnorr.mdx b/docs/developer-docs/smart-contracts/signatures/signing-messages-t-schnorr.mdx index cf0145cc47..dc1caa918c 100644 --- a/docs/developer-docs/smart-contracts/signatures/signing-messages-t-schnorr.mdx +++ b/docs/developer-docs/smart-contracts/signatures/signing-messages-t-schnorr.mdx @@ -12,7 +12,7 @@ import { MarkdownChipRow } from "/src/components/Chip/MarkdownChipRow"; -## Overview + The threshold Schnorr API allows canisters to securely sign messages and transactions without the corresponding private keys ever existing. Each canister can control an unlimited number of keys by specifying different key `derivation_path`s and `key_id`s. diff --git a/docs/developer-docs/smart-contracts/signatures/t-ecdsa.mdx b/docs/developer-docs/smart-contracts/signatures/t-ecdsa.mdx index 4bca0319e1..ec6e029d66 100644 --- a/docs/developer-docs/smart-contracts/signatures/t-ecdsa.mdx +++ b/docs/developer-docs/smart-contracts/signatures/t-ecdsa.mdx @@ -8,7 +8,7 @@ import { MarkdownChipRow } from "/src/components/Chip/MarkdownChipRow"; -## Overview + The Internet Computer implements a novel threshold ECDSA protocol as part of its chain-key signatures suite. In this protocol, the private ECDSA key exists only as secret shares held by nodes. Secret shares are shards of the ECDSA private key. Signatures are computed using those secret shares without the private key ever being reconstructed. Each replica of such subnet holds a key share that provides no information on its own. More than one third of the nodes are required to generate a threshold signature using their respective key shares. Besides the actual threshold signing protocol, chain-key ECDSA is comprised of protocols for secure, distributed key generation and periodic key resharing. Distributed key generation enables the nodes on a subnet to collaboratively generate keys, while periodic key resharing allows for ECDSA keys to be re-shared within the subnet. This makes chain-key ECDSA signatures much more powerful than any off-the-shelf threshold ECDSA protocol. diff --git a/docs/developer-docs/smart-contracts/signatures/t-schnorr.mdx b/docs/developer-docs/smart-contracts/signatures/t-schnorr.mdx index d936176e99..9516dca689 100644 --- a/docs/developer-docs/smart-contracts/signatures/t-schnorr.mdx +++ b/docs/developer-docs/smart-contracts/signatures/t-schnorr.mdx @@ -8,7 +8,7 @@ import { MarkdownChipRow } from "/src/components/Chip/MarkdownChipRow"; -## Overview + Schnorr signatures are a type of digital signature scheme popularly used amongst blockchain networks because they are efficient, simple, and allow for multi-signatures, threshold signatures, and aggregated signatures to be used on the network. On ICP, threshold Schnorr signatures enable canisters to hold a wider range of digital assets and allow for direct integrations with other chains like Solana. diff --git a/docs/developer-docs/smart-contracts/test/overview.mdx b/docs/developer-docs/smart-contracts/test/overview.mdx index 65f8e6da18..f9967c2725 100644 --- a/docs/developer-docs/smart-contracts/test/overview.mdx +++ b/docs/developer-docs/smart-contracts/test/overview.mdx @@ -6,9 +6,9 @@ keywords: [intermediate, test, tutorial, test code, test canister, pocket ic, po import { MarkdownChipRow } from "/src/components/Chip/MarkdownChipRow"; import { GlossaryTooltip } from "/src/components/Tooltip/GlossaryTooltip"; -# Testing canisters overview +# Testing canisters - + Testing your canister's code during the development process is an important step to verify that the code operates as expected and does not produce bugs, errors, or result in the canister trapping. Before deploying and using the code in a production environment, it should undergo testing. diff --git a/docs/developer-docs/smart-contracts/test/pocket-ic.mdx b/docs/developer-docs/smart-contracts/test/pocket-ic.mdx index 9f0a76e226..eed7a4ecdd 100644 --- a/docs/developer-docs/smart-contracts/test/pocket-ic.mdx +++ b/docs/developer-docs/smart-contracts/test/pocket-ic.mdx @@ -10,7 +10,7 @@ import { GlossaryTooltip } from "/src/components/Tooltip/GlossaryTooltip"; -## Overview + PocketIC is a lightweight, deterministic testing solution for programmatic testing of canisters. It seamlessly integrates with existing testing infrastructure, such as `cargo test`, and runs as a standalone binary that doesn't require additional containers or virtual machines. diff --git a/docs/developer-docs/smart-contracts/topping-up/cycles_management_services.mdx b/docs/developer-docs/smart-contracts/topping-up/cycles_management_services.mdx index 378ac9766b..609c412605 100644 --- a/docs/developer-docs/smart-contracts/topping-up/cycles_management_services.mdx +++ b/docs/developer-docs/smart-contracts/topping-up/cycles_management_services.mdx @@ -5,7 +5,7 @@ import { GlossaryTooltip } from "/src/components/Tooltip/GlossaryTooltip"; -## Overview + Once a canister is deployed to the Internet Computer, the compute and storage it utilizes must be pre-paid. The process of burning ICP to obtain cycles and transferring them to a canister is referred to as "topping up" a canister. diff --git a/docs/developer-docs/smart-contracts/topping-up/topping-up-canister.mdx b/docs/developer-docs/smart-contracts/topping-up/topping-up-canister.mdx index 7cc81e5220..8d997a3609 100644 --- a/docs/developer-docs/smart-contracts/topping-up/topping-up-canister.mdx +++ b/docs/developer-docs/smart-contracts/topping-up/topping-up-canister.mdx @@ -9,7 +9,7 @@ import { AdornedTab } from "/src/components/Tabs/AdornedTab"; -## Overview + A canister needs to have cycles deposited continuously into it to pay for the resources it uses. This process is known as 'topping up' the canister. Topping up canisters is routine maintenance. diff --git a/docs/developer-docs/web-apps/application-frontends/add-stylesheet.mdx b/docs/developer-docs/web-apps/application-frontends/add-stylesheet.mdx deleted file mode 100644 index 253f721793..0000000000 --- a/docs/developer-docs/web-apps/application-frontends/add-stylesheet.mdx +++ /dev/null @@ -1,145 +0,0 @@ ---- -keywords: [beginner, tutorial, frontend, stylesheet, assets, asset canister, style, css] ---- - -import { MarkdownChipRow } from "/src/components/Chip/MarkdownChipRow"; -import { GlossaryTooltip } from "/src/components/Tooltip/GlossaryTooltip"; - -# Using CSS to style frontends - - - -## Overview - -[Cascading stylesheets (CSS)](https://www.w3schools.com/css/default.asp) are an important part of any frontend user interface. The default project template is configured to include a basic stylesheet that you can edit, but you may prefer to import your own custom stylesheet or use an alternate format. This guide illustrates how to style the [default frontend canister](default-frontend.mdx) using SCSS, the default format used by `dfx new` when creating React frontend canisters. - -### Prerequisites - -Before you start, verify that you have: - --  [x] `Node.js` `16.0.0` or newer installed for frontend development and can install packages using `npm install` in your project. For information about installing Node for your local operating system and package manager, see the [Node](https://nodejs.org/en/) website. - -- [x] Downloaded and installed [`dfx`](https://github.com/dfinity/sdk/releases/latest) version `0.17.0` or newer. - -## Create a new project - -You can either create a new project using [`dfx new`](/docs/current/developer-docs/developer-tools/cli-tools/cli-reference/dfx-new/), or you can follow the [default frontend canister](default-frontend.mdx) tutorial to setup a project that includes a React default frontend canister. - -If you’ve never used React before, you might want to explore the [intro to React](https://reactjs.org/tutorial/tutorial.html) tutorial or the [React website](https://reactjs.org/) before editing the frontend code. - -## Viewing the default stylesheet - -In the project `custom_greeting`, the default stylesheet for the frontend is stored in the file `src/custom_greeting_frontend/src/index.scss`. This file is imported to the `src/custom_greeting_frontend/src/main.jsx` file through the line: - -``` -import './index.scss'; -``` - -Recall that in this default template, the `main.jsx` file is used to render the `App` content exported from `App.jsx`, and is then imported into the frontend's entrypoint `index.html` file. - -By default, this file contains the following code: - -```css -body { -  font-family: sans-serif; -  font-size: 1.5rem; -} - -img { -  max-width: 50vw; -  max-height: 25vw; -  display: block; -  margin: auto; -} - -form { -  display: flex; -  justify-content: center; -  gap: 0.5em; -  flex-flow: row wrap; -  max-width: 40vw; -  margin: auto; -  align-items: baseline; -} - -button[type="submit"] { -  padding: 5px 20px; -  margin: 10px auto; -  float: right; -} - -#greeting { -  margin: 10px auto; -  padding: 10px 60px; -  border: 1px solid #222; -} - -#greeting:empty { -  display: none; -} -``` - -With this styling, the default frontend looks like this: - -![Sample frontend](_attachments/react-greeting.png) - -You can edit this style sheet to change the existing defined style, such as altering the font size, margin, border, and padding values, or you can add new style components, such as a background color. Here's a revised example: - -```css -body { -  font-family: serif; -  font-size: 2.6rem; -  color: purple; -  background-color: lightblue; - -} - -img { -  max-width: 100vw; -  max-height: 100vw; -  display: block; -  margin: auto; -} - -form { -  display: flex; -  justify-content: center; -  gap: 0.5em; -  flex-flow: row wrap; -  max-width: 40vw; -  margin: auto; -  align-items: baseline; -} - -button[type="submit"] { -  padding: 5px 20px; -  margin: 10px auto; -  float: right; -  color: pink; -  font: serif; -} - -#greeting { -  margin: 10px auto; -  padding: 10px 60px; -  border: 10px solid #222; -} - -#greeting:empty { -  display: none; -} -``` - -![Revised frontend](_attachments/revised-css.png) - -## Using multiple stylesheets - -Your application can use different stylesheets for different pages or sections of your app. Simply change the import statement to point to another stylesheet that should be used, such as: - -``` -import './another-stylesheet.scss'; -``` - -## Next steps - -[Learn how to use an existing frontend application](existing-frontend.mdx). \ No newline at end of file diff --git a/docs/developer-docs/web-apps/application-frontends/asset-security.mdx b/docs/developer-docs/web-apps/application-frontends/asset-security.mdx index 58f20eb929..7c26f1180f 100644 --- a/docs/developer-docs/web-apps/application-frontends/asset-security.mdx +++ b/docs/developer-docs/web-apps/application-frontends/asset-security.mdx @@ -9,7 +9,7 @@ import { GlossaryTooltip } from "/src/components/Tooltip/GlossaryTooltip"; -## Overview + You can configure how a frontend canister responds to requests for specific assets by defining your desired configuration in a file named `.ic-assets.json` Each entry in `.ic-assets.json` allows for specifying a [glob](https://code.visualstudio.com/docs/editor/glob-patterns) pattern along with the headers to be returned in the response for any file that matches the pattern. You may also dictate whether redirects are performed from the non-certified endpoint to a certified endpoint for any given filename pattern. @@ -49,8 +49,3 @@ If you are using an older version of `dfx`, we recommend updating your security ## Resources - [Asset canister architecture reference](/docs/current/references/asset-canister). - -## Next steps - -[Learn more about webpack](webpack.mdx). - diff --git a/docs/developer-docs/web-apps/application-frontends/default-frontend.mdx b/docs/developer-docs/web-apps/application-frontends/default-frontend.mdx index 92c7acb6e3..811319ce9f 100644 --- a/docs/developer-docs/web-apps/application-frontends/default-frontend.mdx +++ b/docs/developer-docs/web-apps/application-frontends/default-frontend.mdx @@ -5,37 +5,25 @@ keywords: [beginner, tutorial, frontend, frontend canister, asset canister, asse import { MarkdownChipRow } from "/src/components/Chip/MarkdownChipRow"; import { GlossaryTooltip } from "/src/components/Tooltip/GlossaryTooltip"; -# Using the default frontend canister +# Hosting application frontends using an asset canister -## Overview +When a dapp is deployed to ICP, it has the ability to host web assets natively. An ICP project's frontend is commonly referred to as the **frontend canister**, as it is a canister that hosts the frontend of the application. -Dapps may have complex frontends that serve dynamic, interactive interfaces, or they can serve simple, static webpages such as HTML and CSS pages. +Dapps may have complex frontends that serve dynamic, interactive interfaces, or they can be simple, static webpages using HTML and CSS. Web assets can come in many forms, such as CSS, JavaScript, React, HTML, images, videos, or streaming content. Most web apps contain a combination of several assets and frameworks together. -Assets can come in many forms, such as: +## What is an asset canister? -- CSS. +When a project has a frontend canister configured in its `dfx.json` file, `dfx` will compile the project's web assets into an **asset canister**. An asset canister is a special type of custom canister that uses Rust to compile the project's asset files into a Wasm module that can be installed and deployed to ICP. This is because canisters deployed on ICP must have a Wasm module. -- JavaScript. +## Application URLs -- React. +Frontend canisters serve the application's web assets via a URL that contains the canister's ID. Local deployments use local URLs such as `http://127.0.0.1:4943/?canisterId=`, while applications deployed to the mainnet use public URLs containing the canister's ID followed by `.ic0.app`, `.icp0.io` or `raw.icp0.io`. -- HTML. +### Raw HTTP interfaces -- Images, videos, or streaming content. - -- User interfaces that combine CSS, HTML, React, or other frameworks together. - -- Dynamic assets, such as dashboards that frequently update with real-time data. - -- Point of sale interfaces. - -When a dapp is deployed to ICP and has a frontend configured, the frontend assets will be displayed via a URL that contains the canister's ID. For local deployments, canisters are accessible through local URLs such as `http://127.0.0.1:4943/?canisterId=`. The port `4943` is the default local deployment port, though this can be changed via the `dfx` configuration or using a `dfx` flag. [Learn more about custom local networks](/docs/current/developer-docs/developer-tools/cli-tools/advanced-dfx/networks-json). - -For canisters deployed to the mainnet, the canister can be accessed in a web browser using the canister's ID followed by `.ic0.app`, `.icp0.io` or `raw.icp0.io`. For example, the [playground](https://m7sm4-2iaaa-aaaab-qabra-cai.ic0.app/) is an application with a frontend user interface that can be used to deploy canisters in a temporary, sandbox environment. This dapp can be accessed via the URL `https://m7sm4-2iaaa-aaaab-qabra-cai.ic0.app/`. - -The `raw.icp0.io` domain is used for canisters deployed to the mainnet, and provides a way to access the raw HTTP interface of that canister. For local deployments that want to simulate the behavior of the `raw.icp0.io` domain, you must implement a method in your canister that consumes an HTTP request and outputs an HTTP response. Here is an example written in Motoko: +The `raw.icp0.io` domain provides a way to access the raw HTTP interface of that canister. For local deployments that want to simulate the behavior of the `raw.icp0.io` domain, you must implement a method in your canister that consumes an HTTP request and outputs an HTTP response. Here is an example written in Motoko: ```motoko no-repl public shared(msg) func http_request(req: HttpRequest) : async HttpResponse { @@ -47,123 +35,28 @@ public shared(msg) func http_request(req: HttpRequest) : async HttpResponse { }; ``` -By default, projects created with `dfx new` have the option to include a frontend canister that uses a template for one of several frontend frameworks. This guide illustrates using the default React template generated by `dfx new` and guides you through some basic modifications to customize the interface displayed. - - -### dfx v0.17.0 and newer - -Projects created with `dfx` v0.17.0 and newer include the option to decide between: - -- SvelteKit -- React -- Vue -- Vanilla JS -- No JS template -- No frontend canister - -### dfx v0.16.1 and older - -`dfx` versions v0.16.1 and older include a JavaScript template `index.js` and `webpack.config.js` file. - -By default, the `index.js` file imports an agent that is located in the `src/declarations/project_frontend/` folder, where `project` is your project's name. This directory will be generated by `dfx` when you run `dfx deploy`, either locally or when deploying to the mainnet. - -### Prerequisites - -Before you start, verify that you have: - -- [x] Node.js `16.0.0` or newer installed for frontend development and can install packages using `npm install` in your project. For information about installing Node for your local operating system and package manager, see the [Node](https://nodejs.org/en/) website. - -- [x] Downloaded and installed [`dfx`](https://github.com/dfinity/sdk/releases/latest) version `0.17.0` or newer. - -## Create a new project - -To create a new project directory for your custom frontend dapp: - -- #### Step 1: Open a terminal shell on your local computer. - -- #### Step 2: Navigate to the directory you are using for your ICP projects, if you are using one. Otherwise, it is recommended to create a new working directory. - -- #### Step 3: Check that you have `Node.js` installed locally by running the following commands: - -```bash -which node -which npm -``` - -- #### Step 4:  Create a new project by running the following command: +## Default `dfx` project configuration -``` -dfx start --clean --background -dfx new custom_greeting -``` +By default, each project created with `dfx new` will include a frontend canister unless the `--no-frontend` flag is used. `dfx` supports default templates for the SvelteKit, React, Vue, and Vanilla JS frameworks, or you can select "No JS template" if you'd like no frontend template to be used. -You will be prompted to select the language that your backend canister will use: - -``` -? Select a backend language: › -❯ Motoko -  Rust -  TypeScript (Azle) -  Python (Kybra) -``` - -:::info -`dfx` versions `v0.17.0` and newer support this `dfx new` interactive prompt. [Learn more about `dfx v0.17.0`](/blog/2024/02/14/news-and-updates/update#dfx-v0170). -::: - -Then, select a frontend framework for your frontend canister. Select 'React': - -``` -  ? Select a frontend framework: › -  SvelteKit -❯ React -  Vue -  Vanilla JS -  No JS template -  No frontend canister -``` - -Lastly, you can include extra features to be added to your project: - -``` -  ? Add extra features (space to select, enter to confirm) › -⬚ Internet Identity -⬚ Bitcoin (Regtest) -⬚ Frontend tests -``` - -- #### Step 5:  Navigate into your project directory by running the following command: - -``` -cd custom_greeting -``` - -If you’ve never used React before, you might want to explore the [intro to React](https://reactjs.org/tutorial/tutorial.html) tutorial or the [React website](https://reactjs.org/) before editing the frontend code. - -## Review the default configuration - -Before you make any changes, let’s review the default frontend settings in the `dfx.json` configuration file for your project: - -- #### Step 1: Open the `dfx.json` configuration file in a code editor. - -- #### Step 2: Notice that the `canisters` key includes settings for a `custom_greeting_frontend` canister. +Frontend canisters will be defined in your project's `dfx.json` file as `PROJECT_NAME_frontend`. ```json {   "canisters": { -    "custom_greeting_backend": { -      "main": "src/custom_greeting_backend/main.mo", +    "PROJECT_NAME_backend": { +      "main": "src/PROJECT_NAME_backend/main.mo",       "type": "motoko"     }, -    "custom_greeting_frontend": { +    "PROJECT_NAME_frontend": {       "dependencies": [ -        "custom_greeting_backend" +        "PROJECT_NAME_backend"       ],       "source": [ -        "src/custom_greeting_frontend/dist" +        "src/PROJECT_NAME_frontend/dist"       ],       "type": "assets", -      "workspace": "custom_greeting_frontend" +      "workspace": "PROJECT_NAME_frontend"     }   },   "defaults": { @@ -177,206 +70,28 @@ Before you make any changes, let’s review the default frontend settings in the } ``` -Let’s take a look at the settings in this section. - -- Frontend assets for your project are compiled into their own canister. In this case, a canister named `custom_greeting_frontend`. - -- The `custom_greeting_frontend` canister has a default dependency on the `custom_greeting_backend` canister for the project. - -- The `source` settings specify the paths to the `src` directory that is used for the static assets that will be included in your `custom_greeting_frontend` canister when you build your project. If you have CSS or JavaScript files, you would include them in this directory. After building the project, the assets are served from the `dist` directory. - -- The `type` setting specifies that the `custom_greeting_frontend` should be deployed using the [asset canister](https://github.com/dfinity/sdk/tree/master/src/canisters/frontend/ic-frontend-canister), which comes with everything you need to host static assets on ICP. - -## Review the default frontend files - -For this guide, you are going to make calls to the default backend canister through a custom frontend. Before you make any changes, let’s take a look at the default frontend canister files. - -- #### Step 1: View the contents of `src/custom_greeting_frontend/src/index.html`. - -This template file is the default frontend entrypoint for the dapp. It contains standard HTML that imports the `/src/main.jsx` script that is used to serve the React application: - -```html - - - - - - - IC Hello Starter - - - - - -
- - - - -``` - -- #### Step 2:  View the contents of `src/custom_greeting_frontend/src/main.jsx`. - -```js -import React from 'react'; -import ReactDOM from 'react-dom/client'; -import App from './App'; -import './index.scss'; - -ReactDOM.createRoot(document.getElementById('root')).render( - - - , -); -``` - -This file is imported into the `index.html` file and is used to render the App that is exported from the `App.jsx` file. - -- #### Step 3:  View the contents of `src/custom_greeting_frontend/src/App.jsx`. - -This file will contain the following piece of code: - -```js -import { useState } from 'react'; -import { custom_greeting_backend } from 'declarations/custom_greeting_backend'; - -function App() { - const [greeting, setGreeting] = useState(''); - - function handleSubmit(event) { - event.preventDefault(); - const name = event.target.elements.name.value; - custom_greeting_backend.greet(name).then((greeting) => { - setGreeting(greeting); - }); - return false; - } - - return ( -
- DFINITY logo -
-
-
- - - -
-
{greeting}
-
- ); -} - -export default App; -``` - -This code has the following components: +Frontend canisters have the following default configuration settings: -- An `import` statement points to an actor that will allow us to make calls to our `custom_greeting_backend` canister from `"../declarations"`. +- Frontend assets for your project are compiled into their own canister. In this case, a canister named `PROJECT_NAME_frontend`. -- A function that handles the logic for calling the backend canister's `greeting` method when the button is pressed. +- The `PROJECT_NAME_frontend` canister has a default dependency on the `PROJECT_NAME_backend` canister for the project. -- Creates the components for the image file, input form, and clickable button. - -- Returns the result of the `greeting` method along with the input from the submitted form. - -## Deploy the dapp - -- #### Step 1:  Check that you are still in the root directory for your project, if needed. - -- #### Step 2:  Build and deploy your dapp by running the following command: - -``` -dfx deploy // Deploy locally -dfx deploy --network ic // Deploy to the mainnet -``` +- The `source` setting specifies the paths to the `src` directory that are used for the web assets that will be compiled into your `PROJECT_NAME_frontend` canister when you build the project. -:::info -Deploying to the mainnet will cost [cycles](/docs/current/developer-docs/getting-started/tokens-and-cycles). -::: +- The `type` setting specifies that the `PROJECT_NAME_frontend` should be deployed using the [asset canister](https://github.com/dfinity/sdk/tree/master/src/canisters/frontend/ic-frontend-canister), which compiles the web assets listed in `source` into a Wasm module. -## View the frontend - -You can now access the frontend for the default dapp by navigating to the frontend canister's generated URL. - -- #### Step 1: To view the frontend locally, open a new tab or window of your terminal and run: - -``` -npm start -``` - -Then, open a browser and navigate to `http://localhost:4943`. - -To view the frontend on the mainnet, navigate to the frontend canister URL returned when you ran `dfx deploy`, such as: - -``` -https://.icp0.io/ -``` - -- #### Step 2: Verify that you are prompted to type a name. - -For example: - -![Sample frontend](_attachments/react-greeting.png) - -- #### Step 3: Enter a name in the input field with the text you want to display, then click **Click Me!** to see the result. - -For example: - -![Greeting result](_attachments/greeting-response.png) - -## Revise the frontend and test your changes - -After viewing the frontend, you might want to make some changes. To modify the frontend code: - -- #### Step 1:  Open the `src/custom_greeting_frontend/src/App.jsx` file in a code editor to modify the application's style settings. - -For example, you might want to add a placeholder for the input field or change the button text and styling by making changes such as: - -```js -import { useState } from 'react'; -import { custom_greeting_backend } from 'declarations/custom_greeting_backend'; - -function App() { - const [greeting, setGreeting] = useState(''); - - function handleSubmit(event) { - event.preventDefault(); - const name = event.target.elements.name.value; - custom_greeting_backend.greet(name).then((greeting) => { - setGreeting(greeting); - }); - return false; - } - - return ( -
- DFINITY logo -
-
-
- - - -
-
{greeting}
-
- ); -} - -export default App; -``` +### Default frontend canister files -- #### Step 2:  Save the file and view the updated page in your browser. +The default files included in the frontend canister will depend on the framework you chose when you created your project, or you can use an [existing application frontend](existing-frontend.mdx). -If viewing the changes locally, refresh the page, and the updates should be reflected in the browser. +## Example frontend canisters -If you deployed to the mainnet, you will need to run `dfx deploy` again to upgrade the canister and apply the changes. +A few example frontend canisters you can reference include: -For example: +- [ICP Ninja sample projects](https://icp.ninja). -![Modified styles on your entry page](_attachments/revised-greeting.png) +- [Minimal counter dapp](https://github.com/dfinity/examples/tree/master/motoko/minimal-counter-dapp/src/minimal_dapp_frontend). -## Next steps +- [Random maze](https://github.com/dfinity/examples/tree/master/motoko/random_maze/src/random_maze_assets). -You can change things such as font family, background color, button styling, and more through CSS stylesheets. [Learn how to customize the frontend with CSS](add-stylesheet.mdx). \ No newline at end of file +- [IC Point of sale](https://github.com/dfinity/examples/tree/master/motoko/ic-pos/src/icpos_frontend).q diff --git a/docs/developer-docs/web-apps/application-frontends/existing-frontend.mdx b/docs/developer-docs/web-apps/application-frontends/existing-frontend.mdx index af258f87a7..71d1154de4 100644 --- a/docs/developer-docs/web-apps/application-frontends/existing-frontend.mdx +++ b/docs/developer-docs/web-apps/application-frontends/existing-frontend.mdx @@ -4,79 +4,67 @@ keywords: [intermediate, tutorial, frontend, assets, asset canister] import { MarkdownChipRow } from "/src/components/Chip/MarkdownChipRow"; import { GlossaryTooltip } from "/src/components/Tooltip/GlossaryTooltip"; +import TabItem from "@theme/TabItem"; +import Tabs from "@theme/Tabs"; + # Using an existing frontend application -## Overview - While numerous starter projects and examples exist for those who prefer to start from scratch, deploying an existing frontend application as a frontend canister is also a viable option for building an application on ICP. -This guide provides an overview of how to deploy an existing Next.js application as a frontend canister. - :::caution Server methods such as `getServerSideProps` are not supported, since it will be deployed as a client-only application. ::: -## Next.js +## Using a Next.js frontend [Next.js](https://nextjs.org/) is an open-source web development framework providing React-based web applications with server-side rendering and static website generation. [View the GitHub repo for this example](https://github.com/jennifertrin/nextjsicp). -### Prerequisites - -Before you start, verify that you have: + + -- [x] Downloaded and installed [`dfx`](https://github.com/dfinity/sdk/releases/latest). + Install the IC SDK. -- [x] An existing Next.js application. This guide will use the [Next.js ICP example](https://github.com/jennifertrin/nextjsicp). + + -### Step 1: Build your Next.js application +- #### Step 1: Build your Next.js application. To start, you must generate static files and build your Next.js application. To generate the static files, add this line to your `next.config.js` file: -```js -output: 'export' -``` - -Your `next.config.js` file should resemble the following: - ```js const nextConfig = {   output: 'export', }; ``` -Please note that you may have existing settings that you should avoid overriding. +:::danger +Please note that you may have existing settings that you should avoid overwriting. +::: -Then, build your Next.js application by running the appropriate build command. For example, if you are using npx: +Then, build your Next.js application by running the appropriate build command. You should reference your `package.json`'s `scripts` section to determine the correct build command. + For example, if you are using npx: ```bash npx run build ``` -You should reference your `package.json` `scripts` section to determine the correct build command. - This should generate an `out` folder, which consists of the static assets that make up the frontend. -:::info -When deploying on ICP, these static files are not public to anyone, including the nodes. Only the Wasm file, which is a binary instruction file that does not leak any of your code, is public. -::: - -### Step 2: Create a `dfx.json` file +- #### Step 2: Create a `dfx.json` file In the top-level directory of your repository, add a `dfx.json` file containing the following content: ```json {     "canisters": { -      "app": { -        "frontend": { +      "frontend": {           "entrypoint": "out/index.html" -        },         "source": ["out"],         "type": "assets"       } @@ -85,13 +73,13 @@ In the top-level directory of your repository, add a `dfx.json` file containing } ``` -`dfx.json` is the configuration file for deploying your to ICP as a canister. In this example, this file is configuring a canister called 'app'. Note that you can adjust `app` to refer to the name of your canister. Also, make sure that these point to the correct files: +`dfx.json` is the configuration file used for configuring and deploying your app to ICP as a canister. In this example, this file is configuring a canister called 'app'. Note that you can adjust `app` to refer to the name of your canister. Also, make sure that these point to the correct files: -- `"entrypoint": "out/index.html"` +- `"entrypoint": "out/index.html"`: The index or entrance point for the application's files. -- `"source": ["out"]` +- `"source": ["out"]`: The directory hosting the application's web assets. -### Step 3: Generate Candid definitions +- #### Step 3: Generate Candid definitions. Run the following command to generate the correct [Candid](/docs/current/developer-docs/smart-contracts/candid/candid-concepts) type definitions: @@ -99,7 +87,7 @@ Run the following command to generate the correct [Candid](/docs/current/develop dfx generate ``` -### Step 4: Deploy the project +- #### Step 4: Deploy the project. Then, you can deploy the Next.js application locally for testing: @@ -119,10 +107,7 @@ Deploying to the mainnet will cost [cycles](/docs/current/developer-docs/getting After running either command, you will see a generated link that is now hosting your Next.js application. The local url will be in the format `http://127.0.0.1:4943/?canisterId=`, while the mainnet URL will be in the format `https://.icp0.io/`. -### Step 5: Navigate to the frontend canister to view the application +- #### Step 5: Open the application. Navigate to the frontend canister using the URL you received in the last step. -## Next steps - -[Learn about asset security policies](asset-security.mdx). diff --git a/docs/developer-docs/web-apps/application-frontends/overview.mdx b/docs/developer-docs/web-apps/application-frontends/overview.mdx index 3c88956dad..c64548f258 100644 --- a/docs/developer-docs/web-apps/application-frontends/overview.mdx +++ b/docs/developer-docs/web-apps/application-frontends/overview.mdx @@ -5,7 +5,7 @@ keywords: [beginner, concept, frontend, asset canister, assets] import { MarkdownChipRow } from "/src/components/Chip/MarkdownChipRow"; import { GlossaryTooltip } from "/src/components/Tooltip/GlossaryTooltip"; -# Asset canister overview +# What is an asset canister? @@ -133,8 +133,6 @@ let path = HttpCertificationPath::wildcard("/js"); - Using [raw HTML and JavaScript](/docs/current/motoko/main/getting-started/motoko-introduction) to display a simple HTML entry page. -- Using [React and TypeScript](./add-stylesheet.mdx) to import CSS properties from an external file. - - [Vite + React + Motoko](https://github.com/rvanasa/vite-react-motoko) template example. - [Vite + SvelteKit + Motoko](https://github.com/letmejustputthishere/vite-sveltekit-motoko-ii/tree/main) template example. diff --git a/docs/developer-docs/web-apps/application-frontends/webpack.mdx b/docs/developer-docs/web-apps/application-frontends/webpack.mdx index 06227f9a54..5f1de6fd65 100644 --- a/docs/developer-docs/web-apps/application-frontends/webpack.mdx +++ b/docs/developer-docs/web-apps/application-frontends/webpack.mdx @@ -8,7 +8,7 @@ import { MarkdownChipRow } from "/src/components/Chip/MarkdownChipRow"; -## Overview + Webpack is a popular and highly configurable module bundler for JavaScript-based applications. New projects created with `dfx new` that choose to create a default JavaScript frontend include a default `webpack.config.js` file that makes it easy to add specific modules such as `react` and `markdown`. @@ -18,8 +18,7 @@ In many cases, you can use the default `webpack.config.js` file as is, without a plugins, modules, and other custom configurations to suit your needs. The specific changes you make to the `webpack.config.js` configuration largely depends on the other tools and frameworks you want to use. -For example, if you have experimented with the [using the default frontend canister](default-frontend.mdx) -or [using CSS to style frontends](add-stylesheet.mdx) tutorials, you might have modified the following section to work with React +For example, if you have experimented with the default frontend canister, you might have modified the following section to work with React JavaScript: ```js diff --git a/docs/developer-docs/web-apps/browser-js/js-frameworks.mdx b/docs/developer-docs/web-apps/browser-js/js-frameworks.mdx index e5714945df..f7a3923b3a 100644 --- a/docs/developer-docs/web-apps/browser-js/js-frameworks.mdx +++ b/docs/developer-docs/web-apps/browser-js/js-frameworks.mdx @@ -8,7 +8,7 @@ import { MarkdownChipRow } from "/src/components/Chip/MarkdownChipRow"; -## Overview + To build user interfaces that utilize in-browser JavaScript, several frameworks can be used. diff --git a/docs/developer-docs/web-apps/custom-domains/dns-setup.mdx b/docs/developer-docs/web-apps/custom-domains/dns-setup.mdx index d5ab678687..20fee2a1bd 100644 --- a/docs/developer-docs/web-apps/custom-domains/dns-setup.mdx +++ b/docs/developer-docs/web-apps/custom-domains/dns-setup.mdx @@ -8,7 +8,7 @@ import { MarkdownChipRow } from "/src/components/Chip/MarkdownChipRow"; -## Overview + This guide explains how to configure the DNS records of your domain for three popular registrars: [Namecheap](#namecheap), [GoDaddy](#godaddy), and [Amazon Route 53](#amazonroute53). diff --git a/docs/developer-docs/web-apps/custom-domains/using-custom-domains.mdx b/docs/developer-docs/web-apps/custom-domains/using-custom-domains.mdx index 0935e24fa8..ec7800d8fe 100644 --- a/docs/developer-docs/web-apps/custom-domains/using-custom-domains.mdx +++ b/docs/developer-docs/web-apps/custom-domains/using-custom-domains.mdx @@ -8,7 +8,7 @@ import { MarkdownChipRow } from "/src/components/Chip/MarkdownChipRow"; -## Overview + By default, all canisters on the Internet Computer are accessible through the domain `icp0.io` and their canister ID. In addition to that default domain, one diff --git a/docs/developer-docs/web-apps/frameworks/juno.mdx b/docs/developer-docs/web-apps/frameworks/juno.mdx index 9e59d5d148..8c1213adff 100644 --- a/docs/developer-docs/web-apps/frameworks/juno.mdx +++ b/docs/developer-docs/web-apps/frameworks/juno.mdx @@ -8,7 +8,7 @@ import { MarkdownChipRow } from "/src/components/Chip/MarkdownChipRow"; -## Overview + Juno is a cutting-edge blockchain-as-a-service platform designed to enable developers to create decentralized applications at lightning speed. It can be thought of as an innovative, open-source alternative to Google Firebase, but with the added benefits of the Internet Computer technology. diff --git a/docs/developer-docs/web-apps/independently-verifying-ic-signatures.mdx b/docs/developer-docs/web-apps/independently-verifying-ic-signatures.mdx index 4136775964..5720384933 100644 --- a/docs/developer-docs/web-apps/independently-verifying-ic-signatures.mdx +++ b/docs/developer-docs/web-apps/independently-verifying-ic-signatures.mdx @@ -8,7 +8,7 @@ import { MarkdownChipRow } from "/src/components/Chip/MarkdownChipRow"; -## Overview + Calls made on ICP require a cryptographic `signature` and `principal` to be included within the call. This is typically attached in the form of an identity. This identity can either be authenticated or anonymous. Canisters use this identity to respond to the call and process authentication-based workflows. diff --git a/docs/references/asset-canister.mdx b/docs/references/asset-canister.mdx index 2f47381dbe..bfed083dc9 100644 --- a/docs/references/asset-canister.mdx +++ b/docs/references/asset-canister.mdx @@ -4,8 +4,6 @@ import { MarkdownChipRow } from "/src/components/Chip/MarkdownChipRow"; -## Overview - An [asset canister](https://github.com/dfinity/sdk/tree/master/src/canisters/frontend/ic-frontend-canister), also referred to as a 'frontend canister' is a type of canister deployed on ICP that can be used to store and retrieve an application's frontend, typically used to serve static HTML, JS, and CSS assets. ## Architecture reference diff --git a/docs/references/bitcoin-how-it-works.mdx b/docs/references/bitcoin-how-it-works.mdx index 0dc2d99b1d..42120ca9c8 100644 --- a/docs/references/bitcoin-how-it-works.mdx +++ b/docs/references/bitcoin-how-it-works.mdx @@ -4,8 +4,6 @@ import { MarkdownChipRow } from "/src/components/Chip/MarkdownChipRow"; -## Overview - The Bitcoin integration on the Internet Computer allows for direct and trustless interaction with the Bitcoin network, enabling canister smart contracts to create Bitcoin addresses and send and receive bitcoin directly. This opens up new possibilities for decentralized applications and services, such as DeFi, that can leverage the liquidity and security of Bitcoin without relying on centralized bridges, thereby enhancing security and efficiency. Two advanced engineering challenges needed to be solved to enable Bitcoin smart contracts on ICP: diff --git a/docs/references/candid-ref.mdx b/docs/references/candid-ref.mdx index adf1a55591..eaa14b0b62 100644 --- a/docs/references/candid-ref.mdx +++ b/docs/references/candid-ref.mdx @@ -4,8 +4,6 @@ import { MarkdownChipRow } from "/src/components/Chip/MarkdownChipRow"; -## Overview - This document provides detailed reference information about Candid supported types and links to the Candid specification and documentation for the Candid Rust crate. - [Supported types](#supported-types). @@ -175,6 +173,12 @@ We can use type annotation to distinguish different integer types. (42 : nat64) ``` +Canister init arguments passed to `dfx` must be explicit with data types, such as: + +``` +field = 5 : nat64 +``` + #### Corresponding Motoko type `natN` translates by default to `NatN`, but can also correspond to `WordN` when required. diff --git a/docs/references/dashboard/dashboard-apis.mdx b/docs/references/dashboard/dashboard-apis.mdx index 56e70d76f7..96c689c165 100644 --- a/docs/references/dashboard/dashboard-apis.mdx +++ b/docs/references/dashboard/dashboard-apis.mdx @@ -9,7 +9,7 @@ import { GlossaryTooltip } from "/src/components/Tooltip/GlossaryTooltip"; -## Overview + ## IC API diff --git a/docs/references/dashboard/overview.mdx b/docs/references/dashboard/overview.mdx index 3c1f313ac7..e7231ce76b 100644 --- a/docs/references/dashboard/overview.mdx +++ b/docs/references/dashboard/overview.mdx @@ -5,7 +5,7 @@ keywords: [ICP dashboard, dashboard, icp dashboard] import { MarkdownChipRow } from "/src/components/Chip/MarkdownChipRow"; import { GlossaryTooltip } from "/src/components/Tooltip/GlossaryTooltip"; -# ICP dashboard overview +# Using the ICP dashboard diff --git a/docs/references/dashboard/using-the-dashboard.mdx b/docs/references/dashboard/using-the-dashboard.mdx index 306b4ec3a5..ec84e027f2 100644 --- a/docs/references/dashboard/using-the-dashboard.mdx +++ b/docs/references/dashboard/using-the-dashboard.mdx @@ -9,7 +9,7 @@ import { GlossaryTooltip } from "/src/components/Tooltip/GlossaryTooltip"; -## Overview + The ICP dashboard is a graphical user interface that can be used to obtain detailed data about the ICP network architecture, canisters deployed on the network, tokenomics and token transactions, and information about each active SNS. Data displayed by the dashboard can also be obtained through one of several [data APIs](dashboard-apis.mdx). This page will detail using the graphic user interface to obtain different data. diff --git a/docs/references/execution-errors.mdx b/docs/references/execution-errors.mdx index 49c4e00533..c1a001ffe0 100644 --- a/docs/references/execution-errors.mdx +++ b/docs/references/execution-errors.mdx @@ -8,7 +8,6 @@ import { MarkdownChipRow } from "/src/components/Chip/MarkdownChipRow"; -## Overview A list of possible errors returned when executing canisters. ## Errors diff --git a/docs/references/https-outcalls-how-it-works.mdx b/docs/references/https-outcalls-how-it-works.mdx index 5d751072b3..51e44539eb 100644 --- a/docs/references/https-outcalls-how-it-works.mdx +++ b/docs/references/https-outcalls-how-it-works.mdx @@ -4,8 +4,6 @@ import { MarkdownChipRow } from "/src/components/Chip/MarkdownChipRow"; -## Overview - This page provides details on how canister HTTPS outcalls, or canister HTTP requests, work and important aspects to consider when using the API. You also want to note that there are some limitations and differences compared to regular (Web 2.0) computer programs making HTTP calls and considerations for programmers for successfully using this feature. Engineers who intend to use this feature are advised to read through this page to get up to speed quickly w.r.t. the feature. The impatient reader who wants to dive into coding right away can skip the conceptual part and jump right away to the [coding section](#coding-https-outcalls) to get started. ## Architecture diff --git a/docs/references/ingress-messages.mdx b/docs/references/ingress-messages.mdx index 525f9c9417..9bcd5c91ce 100644 --- a/docs/references/ingress-messages.mdx +++ b/docs/references/ingress-messages.mdx @@ -8,9 +8,9 @@ import { MarkdownChipRow } from "/src/components/Chip/MarkdownChipRow"; -## Overview -Ingress messages are requests to ICP canisters that are sent by external entities, such as users, usually through an [agent](/docs/current/developer-docs/developer-tools/dev-tools-overview/#agents) like [agent-js](https://github.com/dfinity/agent-js/tree/main) that runs within a web application, or [agent-rs](https://github.com/dfinity/agent-rs/tree/main) in a Rust application. See also the introductory [call overview](/docs/current/developer-docs/smart-contracts/call/overview). + +Ingress messages are requests to ICP canisters that are sent by external entities, such as users, usually through an [agent](/docs/current/developer-docs/developer-tools/dev-tools-overview/#agents) like [agent-js](https://github.com/dfinity/agent-js/tree/main) that runs within a web application, or [agent-rs](https://github.com/dfinity/agent-rs/tree/main) in a Rust application. See also the introductory [call overview](/docs/current/developer-docs/smart-contracts/call/overview). For example, you can browse what ingress messages can be sent to the ckBTC ledger by browsing through its [API using the dashboard](https://dashboard.internetcomputer.org/canister/mxzaz-hqaaa-aaaar-qaada-cai). The tool also allows you to send messages, using agent-js behind the scenes. @@ -18,27 +18,27 @@ This page discusses ICP's ingress message APIs. While these APIs are defined in ## Types of ingress messages -ICP supports several types of calls, as defined in the [HTTPS interface specification](/docs/current/references/ic-interface-spec#http-interface). These include query and update calls. +ICP supports several types of calls, as defined in the [HTTPS interface specification](/docs/current/references/ic-interface-spec#http-interface). These include query and update calls. ## Query calls -Queries don't modify a canister's state and are answered and signed by a single replica. Responses can be obtained within milliseconds, but they are typically not signed by the subnet, meaning a malicious replica or boundary node could arbitrarily modify the response. +Queries don't modify a canister's state and are answered and signed by a single replica. Responses can be obtained within milliseconds, but they are typically not signed by the subnet, meaning a malicious replica or boundary node could arbitrarily modify the response. -Some applications may have higher authenticity requirements for query responses. For example, if a dapp queries a proposal description that the user then votes on, it may not be acceptable that the result could be tampered with, as it could trick users to vote in the attacker's favor. As an alternative, you can issue query calls as update calls instead. While that's easy to implement, it makes the calls significantly slower. +Some applications may have higher authenticity requirements for query responses. For example, if a dapp queries a proposal description that the user then votes on, it may not be acceptable that the result could be tampered with, as it could trick users to vote in the attacker's favor. As an alternative, you can issue query calls as update calls instead. While that's easy to implement, it makes the calls significantly slower. Another alternative approach is to sign the data beforehand and provide *certified variables* (see [tutorial](/docs/current/tutorials/developer-journey/level-3/3.3-certified-data/), [security best practices](/docs/current/developer-docs/security/security-best-practices/data-integrity-and-authenticity#certified-variables)) in query responses. While this approach has better performance than sending query calls as update calls, it can be complex to implement depending on the specific use case. An example where certified variables are used is within the [HTTP asset certification](/docs/current/developer-docs/security/security-best-practices/data-integrity-and-authenticity#use-http-asset-certification-and-avoid-serving-your-dapp-through-rawicp0io). -Error handling for queries is typically simple: on error, one can simply retry until a successful response is received. +Error handling for queries is typically simple: on error, one can simply retry until a successful response is received. ## Update calls Updates can modify a canister's state and thus must go through consensus, typically taking 1-3 seconds. They return certified responses (signed by the subnet), providing authenticity within the subnet's corruption bounds. -Update calls can be [synchronous](/docs/current/references/ic-interface-spec#http-sync-call-overview) or [asynchronous](/docs/current/references/ic-interface-spec#http-async-call-overview). +Update calls can be [synchronous](/docs/current/references/ic-interface-spec#http-sync-call-overview) or [asynchronous](/docs/current/references/ic-interface-spec#http-async-call-overview). -A [synchronous `call`](https://internetcomputer.org/docs/current/references/ic-interface-spec#http-call) follows the "call and await" pattern. In the success case, it maintains the HTTPS connection until a certified response is produced, as illustrated below. +A [synchronous `call`](https://internetcomputer.org/docs/current/references/ic-interface-spec#http-call) follows the "call and await" pattern. In the success case, it maintains the HTTPS connection until a certified response is produced, as illustrated below. ![Dev containers 1](./_attachments/ingress_sync_call.png) -Compared to the [asynchronous `call`](/docs/current/references/ic-interface-spec#http-async-call) endpoint, where the [`read_state`](/docs/current/references/ic-interface-spec#http-read-state) endpoint is used to poll for the request status and obtain the reply, the synchronous endpoint removes the need to poll for the response in the success case. +Compared to the [asynchronous `call`](/docs/current/references/ic-interface-spec#http-async-call) endpoint, where the [`read_state`](/docs/current/references/ic-interface-spec#http-read-state) endpoint is used to poll for the request status and obtain the reply, the synchronous endpoint removes the need to poll for the response in the success case. However, a response may not be produced until some implementation-specific timeout is reached. In that case, the synchronous endpoint behaves like the asynchronous one: it returns a `202` response, and the client must poll [`read_state`](/docs/current/references/ic-interface-spec#http-read-state) to get the request status and eventually obtain the reply, as illustrated below. @@ -65,7 +65,7 @@ In general, there are cases where it is impossible to determine if a call was su * The client loses its connection until the request status has been removed from the state tree. (Recall that ICP will remove the request from the system state tree some time after ingress expiry.) * There is no application specific way to tell if the call successfully executed. For example, the canister does not provide a way to find out if the call happened. -In this situation, it is indistinguishable if the call was successful, but all information has already been removed from the system state tree, or the call never made it into the state tree in the first place and hasn't been executed. +In this situation, it is indistinguishable if the call was successful, but all information has already been removed from the system state tree, or the call never made it into the state tree in the first place and hasn't been executed. ### Recommendations and best practices for secure update call handling @@ -81,13 +81,13 @@ In summary, there are two options for a client: * _No retries, only poll `read_state`:_ Submit the `call` once, and poll `read_state` until at least one of the following conditions is met: * A certified response was produced. That is, the call status is `replied`, `rejected`, or `done`. * The subnet time exceeds`ingress_expiry`, and the call status is not `processing`. - - Evaluating the second condition may be hard if the subnet time and local time of the user differ. -* _Retry the call while polling `read_state`_ Do the same as above, but resubmit the initial `call` (same `request_id`) periodically (e.g. every `30s`) until at least one of the following conditions is met: + + Evaluating the second condition may be hard if the subnet time and local time of the user differ. +* _Retry the call while polling `read_state`_ Do the same as above, but resubmit the initial `call` (same `request_id`) periodically (e.g. every `30s`) until at least one of the following conditions is met: * The call is known to the system. That is, the call status is `received`, `processing`, `replied`, `rejected`, or `done`. * `ingress_expiry` is reached. - This can be beneficial because a call that didn’t make it is retried. For example, if the first call was dropped due to a network issue or by a malicious replica, a subsequent call could make it through e.g. if it is successfully routed to an honest replica. + This can be beneficial because a call that didn’t make it is retried. For example, if the first call was dropped due to a network issue or by a malicious replica, a subsequent call could make it through e.g. if it is successfully routed to an honest replica. At the time of writing, both agent-js (v2.1.3) and agent-rs (v0.39.1) don't retry `call`, so they follow the first option above. By default, both agent-rs and agent-js use `ingress_expiry` of four minutes and poll for five minutes. Additionally, agent-rs resets the timer to allow for an additional five minutes of polling whenever it observes a `received` or `processing` status. diff --git a/docs/references/ledger.mdx b/docs/references/ledger.mdx index 84e3e5c4d4..745e1a153e 100644 --- a/docs/references/ledger.mdx +++ b/docs/references/ledger.mdx @@ -4,7 +4,7 @@ import { MarkdownChipRow } from "/src/components/Chip/MarkdownChipRow"; -## Overview + This document is a specification of the public interface of the ledger canister. It provides an overview of the functionality, details some internal aspects, and documents publicly available methods. It also provides an abstract mathematical model precisely describing the expected behavior of the methods implemented by the canister, albeit at a somewhat high level of abstraction. :::info diff --git a/docs/references/node-providers/node-metrics.mdx b/docs/references/node-providers/node-metrics.mdx index 25938d2e03..5508acbfe6 100644 --- a/docs/references/node-providers/node-metrics.mdx +++ b/docs/references/node-providers/node-metrics.mdx @@ -9,7 +9,7 @@ import '/src/components/CenterImages/center.scss'; -## Overview + ICP publishes node metrics publicly and provides an observability stack to collect, inspect, and analyze these metrics. By publishing these metrics worldwide, anyone can monitor the health of ICP nodes, therefore decentralizing the monitoring process, ensuring that more nodes stay healthy, and decreasing the amount of time it takes to resolve any issues. This feature provides increased overall transparency and a more stable network. diff --git a/docs/references/node-providers/overview.mdx b/docs/references/node-providers/overview.mdx index 672402929b..1d2620a557 100644 --- a/docs/references/node-providers/overview.mdx +++ b/docs/references/node-providers/overview.mdx @@ -4,7 +4,7 @@ keywords: [references, node providers, nodes ] import { MarkdownChipRow } from "/src/components/Chip/MarkdownChipRow"; -# Node provider overview +# Node provider resources diff --git a/docs/references/subnets/overview.mdx b/docs/references/subnets/overview.mdx index 095ac85589..8197d5833b 100644 --- a/docs/references/subnets/overview.mdx +++ b/docs/references/subnets/overview.mdx @@ -9,7 +9,7 @@ import { GlossaryTooltip } from "/src/components/Tooltip/GlossaryTooltip"; -## Overview + Internet Computer **subnet blockchains** are formed by a number of independently owned and controlled high-performance hardware devices called **node machines**, that run the Internet Computer Protocol (ICP). diff --git a/docs/references/subnets/subnet-types.mdx b/docs/references/subnets/subnet-types.mdx index a72f319c06..b59dc9c315 100644 --- a/docs/references/subnets/subnet-types.mdx +++ b/docs/references/subnets/subnet-types.mdx @@ -8,7 +8,7 @@ import { MarkdownChipRow } from "/src/components/Chip/MarkdownChipRow"; -## Overview + A subnet on ICP is a collection of interacting replicas that run their own, separate instance of the ICP consensus mechanism, effectively creating their own blockchain on which a set of canisters can run. Each subnet can communicate with other subnets and is controlled by a root subnet. The root subnet uses chain-key cryptography to delegate its authority to the various subnets. diff --git a/docs/references/t-sigs-how-it-works.mdx b/docs/references/t-sigs-how-it-works.mdx index 8c0b0ddbd3..81ee3874cc 100644 --- a/docs/references/t-sigs-how-it-works.mdx +++ b/docs/references/t-sigs-how-it-works.mdx @@ -4,7 +4,7 @@ import { MarkdownChipRow } from "/src/components/Chip/MarkdownChipRow"; -## Overview + This page gives a high-level outline of threshold signatures on ICP. Some of the information in this section is not required to use threshold signing features, but may be of interest to the technically inclined reader for obtaining background information on the technology. ICP currently supports **threshold Schnorr** signing and **threshold ECDSA** signing. diff --git a/docs/references/vetkeys-overview.mdx b/docs/references/vetkeys-overview.mdx index ef6186dc09..1bdeb1f0b5 100644 --- a/docs/references/vetkeys-overview.mdx +++ b/docs/references/vetkeys-overview.mdx @@ -4,7 +4,7 @@ import { MarkdownChipRow } from "/src/components/Chip/MarkdownChipRow"; -## Overview + vetKeys on the Internet Computer allow developers to more easily perform encryption, threshold decryption, and signing when building dapps on ICP. It is powered by a protocol called **vetKD (Verifiably Encrypted Threshold Key Derivation)** that allows to derive decryption keys on demand. ## Key derivation on demand diff --git a/docs/tutorials/developer-journey/index.mdx b/docs/tutorials/developer-journey/index.mdx index 5dcaa7c73b..10230161b3 100644 --- a/docs/tutorials/developer-journey/index.mdx +++ b/docs/tutorials/developer-journey/index.mdx @@ -8,7 +8,7 @@ import { MarkdownChipRow } from "/src/components/Chip/MarkdownChipRow"; -## Overview + Are you ready to get started developing on the Internet Computer, but not sure where to begin? diff --git a/docs/tutorials/developer-journey/level-0/01-ic-overview.mdx b/docs/tutorials/developer-journey/level-0/01-ic-overview.mdx index cbfb3be778..5070d018d8 100644 --- a/docs/tutorials/developer-journey/level-0/01-ic-overview.mdx +++ b/docs/tutorials/developer-journey/level-0/01-ic-overview.mdx @@ -7,7 +7,7 @@ import { MarkdownChipRow } from "/src/components/Chip/MarkdownChipRow"; import { GlossaryTooltip } from "/src/components/Tooltip/GlossaryTooltip"; -# 0.1 Overview of the Internet Computer +# 0.1 What is the Internet Computer? @@ -17,8 +17,6 @@ import { GlossaryTooltip } from "/src/components/Tooltip/GlossaryTooltip";
-## Overview - The **Internet Computer Protocol (ICP)** is a secure and transparent blockchain-based network that can be used to host data and programs. Programs and their data hosted on ICP are referred to as **decentralized applications**, often abbreviated to **dapps**. Dapps are created by the development and deployment of **smart contracts**, which are known as **canisters** on ICP. Each canister is hosted on an independent blockchain network running on **nodes** called a **subnet**. diff --git a/docs/tutorials/developer-journey/level-0/02-ic-terms.mdx b/docs/tutorials/developer-journey/level-0/02-ic-terms.mdx index dcfd9fffdd..f62b320a0a 100644 --- a/docs/tutorials/developer-journey/level-0/02-ic-terms.mdx +++ b/docs/tutorials/developer-journey/level-0/02-ic-terms.mdx @@ -15,8 +15,6 @@ import { GlossaryTooltip } from "/src/components/Tooltip/GlossaryTooltip";
-## Overview - This page introduces some of the most commonly used terminology that developers should be aware of when building on the Internet Computer. This page covers many terms, but does not include every single term that is related to the Internet Computer. [View the full glossary of terms](/docs/current/references/glossary). ## Concepts diff --git a/docs/tutorials/developer-journey/level-0/03-dev-env.mdx b/docs/tutorials/developer-journey/level-0/03-dev-env.mdx index 9c0d9e6fca..7ec875c733 100644 --- a/docs/tutorials/developer-journey/level-0/03-dev-env.mdx +++ b/docs/tutorials/developer-journey/level-0/03-dev-env.mdx @@ -15,8 +15,6 @@ import { GlossaryTooltip } from "/src/components/Tooltip/GlossaryTooltip";
-## Overview - Before you can begin the developer ladder, you need to set up a developer environment. A developer environment consists of tools and packages that are required to develop code projects. Usually, developer environments are stored and hosted on your local computer, but there are some situations where a virtual, web-based development environment exists. An example of this is the [playground](https://m7sm4-2iaaa-aaaab-qabra-cai.ic0.app/), which is a web-based, virtual developer environment that can be used by developers without having to set up a local environment. Deploying to the playground is ICP's equivalent of deploying to a testnet network. diff --git a/docs/tutorials/developer-journey/level-0/04-intro-canisters.mdx b/docs/tutorials/developer-journey/level-0/04-intro-canisters.mdx index ef433d13b7..07694e200a 100644 --- a/docs/tutorials/developer-journey/level-0/04-intro-canisters.mdx +++ b/docs/tutorials/developer-journey/level-0/04-intro-canisters.mdx @@ -15,8 +15,6 @@ import { GlossaryTooltip } from "/src/components/Tooltip/GlossaryTooltip";
-## Overview - Smart contracts on the Internet Computer are known as **canisters**. A canister contains both the source code and software state. A canister's source code is compiled into a WebAssembly module and is associated with a module of stable memory. When a dapp is written to be deployed on ICP, the source code is compiled into a WebAssembly module. Then, that WebAssembly module is deployed and executed inside of the canister. Once a canister is deployed, end-users can interact with the canister through the CLI or through a frontend client such as a web browser. diff --git a/docs/tutorials/developer-journey/level-0/05-intro-languages.mdx b/docs/tutorials/developer-journey/level-0/05-intro-languages.mdx index 64942b9790..9806368a46 100644 --- a/docs/tutorials/developer-journey/level-0/05-intro-languages.mdx +++ b/docs/tutorials/developer-journey/level-0/05-intro-languages.mdx @@ -15,8 +15,6 @@ import { GlossaryTooltip } from "/src/components/Tooltip/GlossaryTooltip";
-## Overview - When developing canisters, the most common development workflow is to use a software development kit (SDK). The Internet Computer SDK is the most commonly used, which natively supports Motoko and Rust out of the box. Since ICP supports dapps that have been compiled into WebAssembly modules, many different programming languages can be used for canister development. However, a canister development kit (CDK) needs to be used. A CDK is an adapter used by the IC SDK that provides a programming language with the necessary features and tools required to create and manage canisters. The IC SDK comes bundled with CDKs for Motoko and Rust. Additionally, there are several community created CDKs for additional languages, such as Python and TypeScript, that can be installed separately. diff --git a/docs/tutorials/developer-journey/level-0/06-intro-dfx.mdx b/docs/tutorials/developer-journey/level-0/06-intro-dfx.mdx index 9363851f66..2435c63310 100644 --- a/docs/tutorials/developer-journey/level-0/06-intro-dfx.mdx +++ b/docs/tutorials/developer-journey/level-0/06-intro-dfx.mdx @@ -15,8 +15,6 @@ import { GlossaryTooltip } from "/src/components/Tooltip/GlossaryTooltip";
-## Overview - `dfx` is a command line utility that is used to interact with the IC SDK. It is the primary tool that is used for creating, managing, and deploying dapps onto the Internet Computer. The `dfx` parent command has several flags and subcommands that can be used to perform a wide array of operations. First, you'll take a look at basic usage of the command, then you'll get started creating your first project using dfx. diff --git a/docs/tutorials/developer-journey/level-0/index.mdx b/docs/tutorials/developer-journey/level-0/index.mdx index 5558da83f2..ed54033e84 100644 --- a/docs/tutorials/developer-journey/level-0/index.mdx +++ b/docs/tutorials/developer-journey/level-0/index.mdx @@ -8,23 +8,23 @@ import { MarkdownChipRow } from "/src/components/Chip/MarkdownChipRow"; -- [0.1 Overview of the Internet Computer](/docs/current/tutorials/developer-journey/level-0/ic-overview): In order to understand how to develop dapps on ICP, the first step in the developer ladder is to take a look at the architecture of ICP and how it functions. This module covers: - - Overview of The Internet Computer Protocol: +- [0.1 What is the Internet Computer?](/docs/current/tutorials/developer-journey/level-0/ic-overview): In order to understand how to develop dapps on ICP, the first step in the developer ladder is to take a look at the architecture of ICP and how it functions. This module covers: + - What is the Internet Computer?: - Protocol stack: - Peer-to peer layer. - Consensus layer. - Message routing layer. - Execution layer. - - Overview of chain-key cryptography: + - Chain-key cryptography: - Threshold signature schemes. - - Overview of canisters and smart contracts. - - Overview of tokens: + - Canister smart contracts. + - Tokens: - ICP. - Cycles. - - Overview of governance: + - Governance: - Network Nervous System. - Service Nervous System. - - Overview of Internet Identity. + - Internet Identity. - [0.2 Internet Computer terminology](/docs/current/tutorials/developer-journey/level-0/ic-terms): This page introduces some of the most commonly used terminology that developers should be aware of when building on the Internet Computer. This module covers the following terms: - Concepts: diff --git a/docs/tutorials/developer-journey/level-1/1.1-live-demo.mdx b/docs/tutorials/developer-journey/level-1/1.1-live-demo.mdx index 45048c1422..017705d09a 100644 --- a/docs/tutorials/developer-journey/level-1/1.1-live-demo.mdx +++ b/docs/tutorials/developer-journey/level-1/1.1-live-demo.mdx @@ -18,7 +18,7 @@ import '/src/components/CenterImages/center.scss';
-## Overview + In the previous segment of our developer ladder, introduction to `dfx`, you created a new `dfx` project using the default 'Hello, world' template and looked into the project's structure and code. However, you didn't build or deploy the canister. diff --git a/docs/tutorials/developer-journey/level-1/1.2-motoko-lvl1.mdx b/docs/tutorials/developer-journey/level-1/1.2-motoko-lvl1.mdx index 1bd3fa8fe4..6b7b929bd4 100644 --- a/docs/tutorials/developer-journey/level-1/1.2-motoko-lvl1.mdx +++ b/docs/tutorials/developer-journey/level-1/1.2-motoko-lvl1.mdx @@ -15,7 +15,7 @@ import { GlossaryTooltip } from "/src/components/Tooltip/GlossaryTooltip";
-## Overview + Motoko is a programming language that has been developed and optimized for creating programs built on the Internet Computer. In this module, you'll cover the fundamental basics of Motoko that you'll use when you build your [first dapp](/docs/current/tutorials/developer-journey/level-1/1.3-first-dapp). diff --git a/docs/tutorials/developer-journey/level-1/1.3-first-dapp.mdx b/docs/tutorials/developer-journey/level-1/1.3-first-dapp.mdx index 6c600cf950..447f680c6a 100644 --- a/docs/tutorials/developer-journey/level-1/1.3-first-dapp.mdx +++ b/docs/tutorials/developer-journey/level-1/1.3-first-dapp.mdx @@ -21,7 +21,7 @@ import { GlossaryTooltip } from "/src/components/Tooltip/GlossaryTooltip"; The video corresponding to this tutorial is outdated and follows a different project structure than what is written on this page. ::: -## Overview + At this point in your developer ladder, you've covered the fundamentals of canister development and deployed the default 'Hello, world' project template on the playground. It's time to get into writing code and developing your first dapp! @@ -623,7 +623,7 @@ Start by creating the file `src/poll_frontend/src/index.html` that contains the **What does this code do?** The HTML code above is a simple form that provides the end user with options to select using radio buttons. There is nothing 'Web3' or specific to ICP about this code. -Then, the `` tag is used to include some basic CSS for the page's styling. To learn more about adding a stylesheet, see: [add a stylesheet](/docs/current/developer-docs/web-apps/application-frontends/add-stylesheet). +Then, the `` tag is used to include some basic CSS for the page's styling. To learn more about adding a stylesheet, see: [add a stylesheet](/docs/current/developer-docs/web-apps/application-frontends/default-frontend). ::: Next, you will need a `webpack.config.js` file that defines several parameters to facilitate your local development web server. diff --git a/docs/tutorials/developer-journey/level-1/1.4-using-cycles.mdx b/docs/tutorials/developer-journey/level-1/1.4-using-cycles.mdx index 3e860517f8..a861fcc315 100644 --- a/docs/tutorials/developer-journey/level-1/1.4-using-cycles.mdx +++ b/docs/tutorials/developer-journey/level-1/1.4-using-cycles.mdx @@ -17,8 +17,6 @@ import { GlossaryTooltip } from "/src/components/Tooltip/GlossaryTooltip";
-## Overview - If you recall from the previous module, [Internet Computer terminology](/docs/current/tutorials/developer-journey/level-0/ic-terms), cycles are used to measure the resources, such as memory, storage, and compute power, that are used by a canister. When a canister is deployed on the mainnet, cycles are 'charged' for every action that a canister performs. To obtain cycles, the Internet Computer Protocol's utility token, ICP, can be converted into cycles and transferred into a canister to be used to pay for that canister's consumed resources. Cycles have a fixed price in [XDR](https://internetcomputer.org/docs/current/references/glossary#xdr) in order to make canister costs predictable and independent of the price of ICP. One trillion cycles always correspond to one XDR. @@ -91,8 +89,13 @@ The principal will resemble the following format: tsqwz-udeik-5migd-ehrev-pvoqv-szx2g-akh5s-fkyqc-zy6q7-snav6-uqe ``` +## Acquiring cycles + +:::danger +Cycles are required to deploy to the mainnet. If you only plan to deploy to your local environment for testing, cycles are not required. The following tutorials will focus on local deployment to assure anyone can complete this tutorial series. -## Acquiring cycles using a cycles coupon +You may skip this tutorial if you do not plan to deploy to the mainnet. +::: Cycles can be obtained by converting ICP tokens into cycles. There are a few ways to obtain ICP tokens, such as: @@ -101,129 +104,56 @@ Cycles can be obtained by converting ICP tokens into cycles. There are a few way - Receiving a grant of ICP tokens through the DFINITY Foundation. - Receiving ICP tokens in return for providing resources as a node provider. -For new developers, a free cycles coupon can be obtained and redeemed for 10T free cycles that can be used to get started with dapp deployment. For this tutorial, you'll be obtaining and using that free cycles coupon. - -This coupon is good for new developers since it doesn't require that you transfer ICP tokens into cycles, and doesn't require a purchase of tokens to get started. - -First, navigate to the website [https://faucet.dfinity.org](https://faucet.dfinity.org). - -To obtain a coupon code to use the cycles faucet, you need to put in a written request for the coupon via the [Discord](https://discord.internetcomputer.org) server. - -Click on the **REQUEST CYCLES** button on the faucet web page to join the Discord server. - -![Getting Coupon](../_attachments/faucet_step_1.png) - -Once inside the Discord server, navigate into the `#cycles-faucet` channel. - -![Cycles-faucet](../_attachments/cycles-faucet.png) - -In this channel, execute the following slash command: - -``` -/request -``` - -This command will make a call to the IC Cycles Faucet Bot. This bot will prompt you to fill out a survey in the channel. - -Once the survey has been completed, our team will review your submission. If accepted, the faucet bot will send you a private message with a coupon code. - -:::info -Please ensure that your Discord settings are set to allow direct messages from other users. If you do not have this setting enabled, you will not receive a direct message from the faucet bot. -::: - -Head back to the [https://faucet.dfinity.org](https://faucet.dfinity.org) webpage. - -Now, click **NEXT STEP** to continue. +You need to obtain [ICP tokens](https://internetcomputer.org/icp-tokens), then convert them into cycles using `dfx`. However, when participating at DFINITY events like [hackathons](https://dfinity.org/hackathons) or working on a [developer grant](https://dfinity.org/grants), you will receive a coupon which you can redeem to claim free cycles from the [cycles faucet](https://anv4y-qiaaa-aaaal-qaqxq-cai.ic0.app/). -Now that you have a coupon code, enter your coupon code within the faucet UI. - -![Enter Coupon](../_attachments/faucet_step_3.png) - -Click **NEXT STEP** to continue. - -Return to your terminal window. If you closed the window in the process, run the following commands to start `dfx` and use your previously created identity: - -```bash -dfx start --clean --background -dfx identity use DevJourney -``` +:::tip +Each developer identity has both a **principal** and a **ledger account identifier**. -This workflow utilizes the **cycles ledger** feature. If you'd like to use the **cycles wallet** instead, [view the cycles wallet documentation](/docs/current/developer-docs/defi/cycles/cycles-wallet). +A principal has the format `itk7v-ihlxk-ktdrh-fcnst-vkoou-orj77-52ogl-jqwj5-zpfdv-az3lr-xqe` and is used for canister ownership, management, and holding cycles. -:::caution -The cycles ledger is supported by default in [`dfx` version 0.22.0 and newer](/docs/current/developer-docs/getting-started/install). +A ledger account identifier has the format `e213184a548871a47fb526f3cba24e2ee2fbbc8129c4ab497ef2ce535130a0a4` and is used to send and receive tokens like ICP. ::: -Then, redeem your coupon with the command: +First, get your account's ledger account ID: -```bash -dfx cycles --network ic redeem-faucet-coupon COUPON_CODE ``` - -Replace **COUPON_CODE** with the cycles coupon code sent to you by the DFINITY faucet bot. - -Verify your cycles balance with the command: - -```bash -dfx cycles --network ic balance +dfx ledger account-id ``` -This should return an output showing 10T cycles associated with your identity. - -## Converting ICP tokens to cycles - -If you've already redeemed a cycles coupon in the past, or if you've already used the cycles from your coupon, you can convert ICP tokens into cycles. - -Before you can convert ICP tokens into cycles, first you need to obtain ICP tokens. ICP tokens can be purchased through a crypto exchange, or they can be received through other activities such as participating in the NNS governance and receiving grants from the DFINITY foundation. +Then, send ICP tokens to this ledger account ID. You can obtain [ICP tokens](https://internetcomputer.org/icp-tokens) from an [exchange](https://coinmarketcap.com/currencies/internet-computer/markets) or through a [developer grant](https://dfinity.org/grants). If you are using an exchange, initiate a withdrawal transaction, then enter the ledger account ID as the "destination" address to send ICP tokens to. -To get your account ID so you know where to send your ICP tokens, run the command: +After you have sent ICP tokens to your ledger account, check the ICP balance. -```bash -dfx ledger account-id ``` - -This will display your account number on the ICP ledger, which will resemble the following: - -```bash -e213184a548871a47fb526f3cba24e2ee2fbbc8129c4ab497ef2ce535130a0a4 +dfx ledger balance --network=ic ``` -Once you have sent some ICP to this account ID, you can verify that they were received by checking the balance with the command: +Converting ICP to cycles is done through the **cycles ledger**, a ledger canister that enables developer identities to convert, hold, send, and receive cycles. -```bash -dfx ledger --network ic balance -``` +The price of cycles is fixed against the price of [XDR](/docs/current/references/glossary#xdr), where 1 trillion cycles equals 1 XDR. -This will output something like this: +Cycles are measured in very large numbers, such as billions and trillions. When you talk about cycle transfers and replenishment, you will usually operate with trillions of cycles. -```bash -12.49840000 ICP -``` +:::danger +These commands must be run with the `--network=ic` flag. The cycles ledger is not necessary for local development and therefore not part of the local replica. +::: -Once you have your ICP tokens ready, you will need to convert them into cycles. To convert ICP into cycles using the cycles ledger, use the command: +Next, convert ICP into cycles. Replace `AMOUNT` with the number of ICP tokens you want to convert into cycles. ``` -dfx cycles convert --amount AMOUNT --network ic +dfx cycles convert --amount AMOUNT --network=ic ``` -:::info -This workflow utilizes the **cycles ledger** feature. If you'd like to use the **cycles wallet** instead, [view the cycles wallet documentation](/docs/current/developer-docs/defi/cycles/cycles-wallet). +:::info Calculating how many cycles you need -Please note that the cycles wallet will be removed from dfx in a future release. -::: +The amount of cycles that your canister will use depends on a variety of factors. Cycles are charged for storage, compute, update messages, special features, and more. To get an approximation, you can view the [detailed cycles cost table](/docs/current/developer-docs/gas-cost) or use the [cycles pricing calculator](/docs/current/developer-docs/cost-estimations-and-examples). -Replace the **AMOUNT** with the number of ICP to convert into cycles. +::: -To verify that your ICP was converted into cycles properly, query the balance of the wallet with the command: +Lastly, confirm that the ICP was properly converted into cycles by checking the cycles balance. -```bash -dfx cycles balance --network ic ``` - -This should return your balance in cycles: - -```bash -6.951 TC (trillion cycles). +dfx cycles balance --network=ic ``` ## Resources diff --git a/docs/tutorials/developer-journey/level-1/1.5-deploying-canisters.mdx b/docs/tutorials/developer-journey/level-1/1.5-deploying-canisters.mdx index a7908ef799..0effe5384f 100644 --- a/docs/tutorials/developer-journey/level-1/1.5-deploying-canisters.mdx +++ b/docs/tutorials/developer-journey/level-1/1.5-deploying-canisters.mdx @@ -15,7 +15,9 @@ import { GlossaryTooltip } from "/src/components/Tooltip/GlossaryTooltip";
-## Overview +:::danger +If you did not obtain cycles in the previous tutorial, [1.4 Acquiring and using cycles](/docs/current/tutorials/developer-journey/level-1/1.4-using-cycles), then you can skip this module and continue with the rest of the tutorial series. +::: Now that you have some cycles to pay for your canister's resources, you can deploy your dapp on the mainnet. When a canister is deployed to the mainnet, it's code will be hosted on the nodes that make up one of the mainnet's subnets. The canister will be hosted on these nodes until it is manually uninstalled by the developer, or until it runs out of cycles and is uninstalled automatically. @@ -29,6 +31,10 @@ You will be building off of the previous two modules, [1.3 Developing your first ## Deploying to the mainnet +:::danger +If you did not obtain cycles in the previous tutorial, [1.4 Acquiring and using cycles](/docs/current/tutorials/developer-journey/level-1/1.4-using-cycles), then you can skip this module and continue with the rest of the tutorial series. +::: + To deploy your dapp to the mainnet, first assure that your terminal window is open and you've navigated into the directory of your `poll` dapp that you created in module [1.3 Developing your first dapp](/docs/current/tutorials/developer-journey/level-1/1.3-first-dapp). Then, assure that all necessary packages are installed for the project's frontend with the command: @@ -101,7 +107,7 @@ Uploading assets to asset canister... Deployed canisters. ``` -If you manually converted ICP tokens into cycles, and your cycles balance doesn't contain enough cycles to complete this deployment, you can convert more ICP into cycles with the command: +If your cycles balance doesn't contain enough cycles to complete this deployment, you can convert more ICP into cycles with the command: ```bash @@ -110,8 +116,6 @@ dfx cycles convert 1.005 --network ic This command converts an additional 1.005 ICP tokens to cycles. -If you used the free cycles coupon, this step is not applicable. - Now, let's use your dapp! To access the dapp's frontend, first you need to get the canister's URL. To get this, run the command: ```bash diff --git a/docs/tutorials/developer-journey/level-1/1.6-managing-canisters.mdx b/docs/tutorials/developer-journey/level-1/1.6-managing-canisters.mdx index ed868ae122..3729182df7 100644 --- a/docs/tutorials/developer-journey/level-1/1.6-managing-canisters.mdx +++ b/docs/tutorials/developer-journey/level-1/1.6-managing-canisters.mdx @@ -16,9 +16,8 @@ import { GlossaryTooltip } from "/src/components/Tooltip/GlossaryTooltip";
-## Overview -Now that you have canisters deployed on the mainnet, the next step is to learn how to manage those canisters. Managing a canister includes workflows such as obtaining information, setting an identity as the canister's owner, and deleting a canister. You'll dive into these different workflows and more in this guide to assure that you have the core fundamentals of how to maintain canisters. +Now that you have canisters deployed, the next step is to learn how to manage those canisters. Managing a canister includes workflows such as obtaining information, setting an identity as the canister's owner, and deleting a canister. You'll dive into these different workflows and more in this guide to assure that you have the core fundamentals of how to maintain canisters. ## The ICP management canister @@ -54,6 +53,12 @@ If you want to get the canister ID for a locally deployed canister, simply omit dfx canister id poll_backend ``` +:::danger + +This tutorial will reference locally deployed canisters from this point forward. + +::: + ## Obtaining canister information Next, to obtain some information about your canister, such as the canister's controller(s) and the Wasm module hash, use the command: @@ -151,13 +156,13 @@ Canisters are placed in the **Running** state by default, but there may be situa To check the current state of all canisters, you can use the command: ```bash -dfx canister status --network ic --all +dfx canister status --all ``` Or, you can check the status of a single canister by specifying it's name, such as: ```bash -dfx canister status poll_backend --network ic +dfx canister status poll_backend ``` The output of the command will resemble the following: @@ -179,13 +184,13 @@ Module hash: 0xf8680eb74022a1079012b7e9c644d1156580002a6126305791811533d3fd6f17 Stopping a canister works in a similar fashion. For example, to stop a single canister, run the command: ```bash -dfx canister stop poll_backend --network ic +dfx canister stop poll_backend ``` Or, to stop all canisters, use the command: ```bash -dfx canister stop --network ic --all +dfx canister stop --all ``` This command displays output similar to the following: @@ -198,7 +203,7 @@ Stopping code for canister poll_frontend, with canister_id 5h5yf-eiaaa-aaaaa-qaa Then you can verify that the canisters have been stopped by rerunning the `dfx canister status` command: ```bash -dfx canister status --network ic poll_backend +dfx canister status poll_backend ``` Which should return: @@ -220,7 +225,7 @@ Module hash: 0xf8680eb74022a1079012b7e9c644d1156580002a6126305791811533d3fd6f17 Then to start the canister again, run the command: ```bash -dfx canister start --network ic --all +dfx canister start --all ``` This will return a confirmation such as: @@ -235,7 +240,7 @@ Starting code for canister poll_frontend, with canister_id 5h5yf-eiaaa-aaaaa-qaa To check a canister's cycles balance, you must be the controller of the canister. The cycles balance can be seen in the output of the `dfx canister status` command, such as: ```bash -dfx canister status 5o6tz-saaaa-aaaaa-qaacq-cai --network ic +dfx canister status poll_backend ``` The output will resemble the following, where the value `Balance` refers to the main cycles balance and `Reserved` refers to the reserved cycles balance: @@ -267,97 +272,7 @@ There are a few ways to top up a canister: - Using the NNS dapp web UI. - Using a third-party service such as [CycleOps](/docs/current/developer-docs/smart-contracts/topping-up/cycles_management_services). -This tutorial will cover the first two workflows. [Learn more about using a third-party service for cycles management](/docs/current/developer-docs/smart-contracts/topping-up/cycles_management_services). - - -## Setting the reserved cycles limit - -When a canister allocates storage bytes, the system may reserve some amount of cycles by moving them from the main cycles balance of the canister to the reserved cycles balance. -These reserved cycles are used for [future storage payments](/docs/current/developer-docs/gas-cost). - -You can control the maximum amount of reserved cycles by setting the reserved cycles limit: - -```bash -dfx canister update-settings 5o6tz-saaaa-aaaaa-qaacq-cai --reserved-cycles-limit 42 --network ic -dfx canister status 5o6tz-saaaa-aaaaa-qaacq-cai --network ic -``` - -The first command sets the reserved cycles limit to `42` and the second command queries the canister status and shows the following output: - -``` -Canister status call result for 5o6tz-saaaa-aaaaa-qaacq-cai. -... -Reserved: 0 Cycles -Reserved Cycles Limit: 42 Cycles -... - -``` - -Once the reserved cycles balances reaches the reserved cycles limit, the system is going to fail all operations that require cycle reservation. -The error message might look like this: - -``` -Canister cannot grow memory by 65536 bytes due to its reserved cycles limit. The current limit (42) would be exceeded by 1000. -``` - -Such errors can be fixed by increasing the reserved cycles limit. - - -### Using ICP - -If you currently have a balance of ICP tokens within your dfx ledger account ID, you can use the `dfx ledger top-up` command to automatically convert that ICP into cycles and deposit it into the specified canister, for example: - -```bash -dfx ledger top-up 5o6tz-saaaa-aaaaa-qaacq-cai --amount 2.7 --network ic -``` - -### Using the cycles ledger - -You can top up a canister using the cycles balance associated with your identity and the cycles ledger with the command: - -```bash -dfx cycles top-up `AMOUNT` `CANISTER_ID` --network ic -``` - -## Getting cycles back from a canister - -To withdraw cycles from a canister, the canister must be deleted. The cycles will be returned to the identity associated with the canister's controller principal. - -First, check the cycles balance of your identity: - -``` -dfx cycles balance -``` - -This will return your cycles balance, such as: - -``` -90.700 TC (trillion cycles). -``` - -Then, you can stop and delete the canister with the commands: - -```bash -dfx canister stop jqylk-byaaa-aaaal-qbymq-cai --network ic -dfx canister delete jqylk-byaaa-aaaal-qbymq-cai --network ic -``` - -The output of the `dfx canister delete` command will return information regarding the cycles withdraw: - -``` -Beginning withdrawal of cycles to canister jqylk-byaaa-aaaal-qbymq-cai; on failure try --no-wallet --no-withdrawal. -Setting the controller to identity principal. -Installing temporary wallet in canister poll_backend to enable transfer of cycles. -Attempting to transfer 3089393970000 cycles to canister jqylk-byaaa-aaaal-qbymq-cai. -Successfully withdrew 3089393970000 cycles. -Deleting canister poll_backend, with canister_id jqylk-byaaa-aaaal-qbymq-cai -``` - -To confirm that the cycles were withdrawn properly, check your cycles balance again with `dfx cycles balance`. The balance should be increased, such as: - -``` -93.789 TC (trillion cycles). -``` +Local development fabricates cycles as needed for canister deployment. To learn about topping up canisters on the mainnet, [read more about how to use ICP or cycles](/docs/current/developer-docs/getting-started/deploy-and-manage#topping-up-canisters) ## Setting the canister's freezing threshold @@ -371,7 +286,7 @@ For example, to set a freezing threshold for your `poll_backend` canister, use t dfx canister update-settings poll_backend --freezing-threshold 3472000 ``` -Then, you can confirm that this threshold has been set by running the `dfx canister status poll_backend --network ic ` command again: +Then, you can confirm that this threshold has been set by running the `dfx canister status poll_backend ` command again: ``` Canister status call result for poll_backend. @@ -388,23 +303,25 @@ Module hash: 0xf8680eb74022a1079012b7e9c644d1156580002a6126305791811533d3fd6f17 ## Deleting a canister -The last portion of canister management that will be covered in this guide is deleting canisters. To delete a single canister, first you need to stop the canister with the command: +The last portion of canister management that will be covered in this guide is deleting canisters. Deleting a canister will withdraw any cycles from that canister and return them to the identity associated with the canister's controller principal. + +To delete a single canister, first you need to stop the canister with the command: ```bash -dfx canister stop poll_frontend --network ic +dfx canister stop poll_backend ``` Then you can run the command: ```bash -dfx canister delete poll_frontend --network ic +dfx canister delete poll_backend ``` When a canister is deleted, the canister's code, state, and canister ID are removed. Canisters must be stopped before they can be deleted. Alternatively, all canisters for a project can be deleted with the commands: ```bash -dfx canister stop --network ic --all -dfx canister delete --network ic --all +dfx canister stop --all +dfx canister delete --all ``` ## Need help? diff --git a/docs/tutorials/developer-journey/level-2/2.1-storage-persistence.mdx b/docs/tutorials/developer-journey/level-2/2.1-storage-persistence.mdx index 1fdb682f73..c2e42f03e2 100644 --- a/docs/tutorials/developer-journey/level-2/2.1-storage-persistence.mdx +++ b/docs/tutorials/developer-journey/level-2/2.1-storage-persistence.mdx @@ -18,7 +18,7 @@ import { GlossaryTooltip } from "/src/components/Tooltip/GlossaryTooltip";
-## Overview + The Internet Computer handles persistent data storage using a feature known as **stable memory**. **Stable memory** is a unique feature of the Internet Computer that defines a data store separate from the canister's regular Wasm memory data store, which is known as **heap memory**. A canister's heap memory is not persistent storage and does not persist across canister upgrades; canister data and state stored in heap memory is removed when a canister is upgraded or reinstalled. For immutable canisters that use less than the heap memory limit of 4GiB, heap memory can be used. For larger canisters, and especially those that intend to be upgraded and changed over time, stable memory is important since it persists across canister upgrades, has a much larger storage capacity than heap memory, and is very beneficial for vertically scaling a dapp. diff --git a/docs/tutorials/developer-journey/level-2/2.2-advanced-canister-calls.mdx b/docs/tutorials/developer-journey/level-2/2.2-advanced-canister-calls.mdx index a33395e8bb..bda989a24a 100644 --- a/docs/tutorials/developer-journey/level-2/2.2-advanced-canister-calls.mdx +++ b/docs/tutorials/developer-journey/level-2/2.2-advanced-canister-calls.mdx @@ -15,7 +15,7 @@ import { GlossaryTooltip } from "/src/components/Tooltip/GlossaryTooltip";
-## Overview + In the previous tutorial where you [created your first dapp](/docs/current/tutorials/developer-journey/level-1/1.3-first-dapp), the developer ladder briefly discussed query and update canister calls. In this tutorial, you'll dive deeper into these types of canister calls, but also take a look at advanced canister calls such as composite queries, certified variables, and inter-canister calls. diff --git a/docs/tutorials/developer-journey/level-2/2.3-third-party-canisters.mdx b/docs/tutorials/developer-journey/level-2/2.3-third-party-canisters.mdx index 08f6bb4838..16861819eb 100644 --- a/docs/tutorials/developer-journey/level-2/2.3-third-party-canisters.mdx +++ b/docs/tutorials/developer-journey/level-2/2.3-third-party-canisters.mdx @@ -15,7 +15,7 @@ import { GlossaryTooltip } from "/src/components/Tooltip/GlossaryTooltip";
-## Overview + Third-party canisters are canisters that provide a public service at a static canister ID. Some examples are the DFINITY NNS and Internet Identity canisters, but third-party canisters can also be made by community developers. Using third-party canisters can be a good way to add additional functionalities to your dapp. For example, by integrating the Internet Identity canister into your dapp, you can enable identity and authentication for the users of your application. diff --git a/docs/tutorials/developer-journey/level-2/2.4-intro-candid.mdx b/docs/tutorials/developer-journey/level-2/2.4-intro-candid.mdx index aff7247042..1c8e6f9821 100644 --- a/docs/tutorials/developer-journey/level-2/2.4-intro-candid.mdx +++ b/docs/tutorials/developer-journey/level-2/2.4-intro-candid.mdx @@ -16,7 +16,7 @@ import { GlossaryTooltip } from "/src/components/Tooltip/GlossaryTooltip";
-## Overview + Candid is an interface description language that is used to describe the public interface of a service. A **service** is usually in the form of an application deployed as a canister on ICP. Public interfaces of canisters are used to interact with the canister. Candid supports interactions through the IC SDK via the terminal, through a web browser, or through the use of agents. It also provides a way to specify input argument values and display return values from different canister **methods**, regardless of the manner used to interact with the canister. Recall that a method is a piece of code specifying a task which declares a sequence of arguments and their associated result types. diff --git a/docs/tutorials/developer-journey/level-2/2.5-unit-testing.mdx b/docs/tutorials/developer-journey/level-2/2.5-unit-testing.mdx index 2f17abc20b..f1dbe306d5 100644 --- a/docs/tutorials/developer-journey/level-2/2.5-unit-testing.mdx +++ b/docs/tutorials/developer-journey/level-2/2.5-unit-testing.mdx @@ -15,7 +15,7 @@ import { GlossaryTooltip } from "/src/components/Tooltip/GlossaryTooltip";
-## Overview + Testing code is an important stage of any development workflow. Without proper testing before the code is put into production, bugs and errors that may have been caught during testing can be detrimental to production environments. At this point of the developer ladder, it's time to explore tools that can be used to test our code. @@ -220,7 +220,6 @@ Then, open your `package.json` file and insert `"test": "vitest"` in the `script "prebuild": "dfx generate", "start": "webpack serve --mode development --env development", "deploy:local": "dfx deploy --network=local", - "deploy:ic": "dfx deploy --network ic", "generate": "dfx generate e2e_tests_backend", "test": "vitest" }, diff --git a/docs/tutorials/developer-journey/level-2/2.6-motoko-lvl2.mdx b/docs/tutorials/developer-journey/level-2/2.6-motoko-lvl2.mdx index fd256620d3..8e47fd8fe9 100644 --- a/docs/tutorials/developer-journey/level-2/2.6-motoko-lvl2.mdx +++ b/docs/tutorials/developer-journey/level-2/2.6-motoko-lvl2.mdx @@ -15,7 +15,7 @@ import { GlossaryTooltip } from "/src/components/Tooltip/GlossaryTooltip";
-## Overview + As you've seen so far, **actors** are at the core functionality of canisters written in Motoko. In this tutorial, you'll explore actors further by taking a look at actor type definitions, how actors interact with async data, actor classes, and using multiple actors. diff --git a/docs/tutorials/developer-journey/level-3/3.1-package-managers.mdx b/docs/tutorials/developer-journey/level-3/3.1-package-managers.mdx index 62aa662f97..6dbfb4e5b1 100644 --- a/docs/tutorials/developer-journey/level-3/3.1-package-managers.mdx +++ b/docs/tutorials/developer-journey/level-3/3.1-package-managers.mdx @@ -14,7 +14,7 @@ import { MarkdownChipRow } from "/src/components/Chip/MarkdownChipRow";
-## Overview + [Mops](https://mops.one) and [Vessel](https://github.com/dfinity/vessel) are package managers for Motoko. In this guide, you'll explore how to download and install Mops and Vessel, then how to import and use different libraries that have been downloaded through a package manager. diff --git a/docs/tutorials/developer-journey/level-3/3.2-https-outcalls.mdx b/docs/tutorials/developer-journey/level-3/3.2-https-outcalls.mdx index 2252d3bf31..e6d789527e 100644 --- a/docs/tutorials/developer-journey/level-3/3.2-https-outcalls.mdx +++ b/docs/tutorials/developer-journey/level-3/3.2-https-outcalls.mdx @@ -15,7 +15,7 @@ import '/src/components/CenterImages/center.scss';
-## Overview + In the past, blockchain networks were only able to communicate with external servers through blockchain oracles, or third-party entities that relayed calls from the blockchain to an external server, then routed the response back to the blockchain. This is because blockchains are a form of replicated state machine, where each replica must perform the same computations within the same state to make the same transitions each round. Since doing computations with results from an external source may lead to a state divergence, tools like oracles have been used in the past. However, on the Internet Computer, canisters can communicate directly with external servers or other blockchains through **HTTPS outcalls**. diff --git a/docs/tutorials/developer-journey/level-3/3.3-certified-data.mdx b/docs/tutorials/developer-journey/level-3/3.3-certified-data.mdx index 54cf4234af..eb4ae0ea39 100644 --- a/docs/tutorials/developer-journey/level-3/3.3-certified-data.mdx +++ b/docs/tutorials/developer-journey/level-3/3.3-certified-data.mdx @@ -14,7 +14,7 @@ import { MarkdownChipRow } from "/src/components/Chip/MarkdownChipRow";
-## Overview + In a previous module, [2.2: Advanced canister calls](/docs/current/tutorials/developer-journey/level-2/2.2-advanced-canister-calls), you briefly touched on certified variables. In this guide, you'll dive deeper into certified data and take a look at an example that displays how to use certified data. diff --git a/docs/tutorials/developer-journey/level-3/3.4-intro-to-agents.mdx b/docs/tutorials/developer-journey/level-3/3.4-intro-to-agents.mdx index f69860c7a2..aab45fa174 100644 --- a/docs/tutorials/developer-journey/level-3/3.4-intro-to-agents.mdx +++ b/docs/tutorials/developer-journey/level-3/3.4-intro-to-agents.mdx @@ -16,7 +16,7 @@ import '/src/components/CenterImages/center.scss';
-## Overview + When you have a canister running, either locally or on the mainnet, you have two primary ways for interacting with the canister: using the API through an agent, or using the canister's HTTP interface. On the Internet Computer, an **agent** is a library used to make calls to ICP's public interface. diff --git a/docs/tutorials/developer-journey/level-3/3.5-identities-and-auth.mdx b/docs/tutorials/developer-journey/level-3/3.5-identities-and-auth.mdx index 74e931c1e3..6fd7e2758b 100644 --- a/docs/tutorials/developer-journey/level-3/3.5-identities-and-auth.mdx +++ b/docs/tutorials/developer-journey/level-3/3.5-identities-and-auth.mdx @@ -16,7 +16,7 @@ import '/src/components/CenterImages/center.scss';
-## Overview + When developing on the Internet Computer, there are several types of identities and methods of authentication that you'll encounter. In the previous module where you obtained a cycles coupon, [1.4: acquiring and using cycles](/docs/current/tutorials/developer-journey/level-1/1.4-using-cycles), you created a **developer identity** that has a **cycles balance**. You also looked at how to convert ICP tokens stored in a **ledger account** into cycles. diff --git a/docs/tutorials/developer-journey/level-3/3.6-motoko-lvl3.mdx b/docs/tutorials/developer-journey/level-3/3.6-motoko-lvl3.mdx index 1381c7e081..f9f08b5d75 100644 --- a/docs/tutorials/developer-journey/level-3/3.6-motoko-lvl3.mdx +++ b/docs/tutorials/developer-journey/level-3/3.6-motoko-lvl3.mdx @@ -14,7 +14,7 @@ import { MarkdownChipRow } from "/src/components/Chip/MarkdownChipRow";
-## Overview + In the previous module, [3.5: Identities and authentication](/docs/current/tutorials/developer-journey/level-3/3.5-identities-and-auth) you covered different forms of identities and authentication on ICP. In this Motoko level, you'll look into caller identification, adding access control with identities, plus other non-identity related functionalities such as pattern matching and periodic tasks. diff --git a/docs/tutorials/developer-journey/level-4/4.1-icp-ledger.mdx b/docs/tutorials/developer-journey/level-4/4.1-icp-ledger.mdx index 1de4aa6288..a00733fa49 100644 --- a/docs/tutorials/developer-journey/level-4/4.1-icp-ledger.mdx +++ b/docs/tutorials/developer-journey/level-4/4.1-icp-ledger.mdx @@ -17,7 +17,7 @@ import '/src/components/CenterImages/center.scss';
-## Overview + Recall from previous modules that ICP is the native token of the Internet Computer. ICP tokens have three key functionalities on the Internet Computer: @@ -245,7 +245,7 @@ dfx ledger account-id Then, to check the balance of that account, use the command: ```bash -dfx ledger --network ic balance ACCOUNT_ID +dfx ledger balance ACCOUNT_ID ``` Replace `ACCOUNT_ID` with the output from the `dfx ledger account-id` command. diff --git a/docs/tutorials/developer-journey/level-4/4.2-icrc-tokens.mdx b/docs/tutorials/developer-journey/level-4/4.2-icrc-tokens.mdx index a23fdeb212..bfaafa4075 100644 --- a/docs/tutorials/developer-journey/level-4/4.2-icrc-tokens.mdx +++ b/docs/tutorials/developer-journey/level-4/4.2-icrc-tokens.mdx @@ -16,7 +16,7 @@ import '/src/components/CenterImages/center.scss';
-## Overview + For developers to create their own fungible tokens on the Internet Computer, the ICRC-1 token standard can be used. The acronym "ICRC" stands for "Internet Computer Request for Comments", as the standard was created by the Internet Computer working group. [Learn more about the working group](https://github.com/dfinity/ICRC). diff --git a/docs/tutorials/developer-journey/level-4/4.3-ckbtc-and-bitcoin.mdx b/docs/tutorials/developer-journey/level-4/4.3-ckbtc-and-bitcoin.mdx index 38d44f0ecb..ca751d9313 100644 --- a/docs/tutorials/developer-journey/level-4/4.3-ckbtc-and-bitcoin.mdx +++ b/docs/tutorials/developer-journey/level-4/4.3-ckbtc-and-bitcoin.mdx @@ -14,7 +14,7 @@ import { MarkdownChipRow } from "/src/components/Chip/MarkdownChipRow";
-## Overview + One of the key features of the Internet Computer is known as **chain-key cryptography**. Chain-key cryptography is a feature that encompasses several cryptographic mechanisms that enable novel workflows and functionalities such as chain-key tokens. Chain-key tokens are not wrapped tokens; they are twin tokens that are backed 1:1 with the original token (BTC, ETH) that use chain-key cryptography to transfer and use the original tokens with less fees and higher transfer speeds than using the token's native blockchain network. diff --git a/docs/tutorials/developer-journey/level-4/4.4-nns-governance.mdx b/docs/tutorials/developer-journey/level-4/4.4-nns-governance.mdx index c50a3b4068..3dde42c03c 100644 --- a/docs/tutorials/developer-journey/level-4/4.4-nns-governance.mdx +++ b/docs/tutorials/developer-journey/level-4/4.4-nns-governance.mdx @@ -14,7 +14,7 @@ import { MarkdownChipRow } from "/src/components/Chip/MarkdownChipRow";
-## Overview + When blockchain networks need to be upgraded, traditionally they use a method known as a 'hard fork', which involves substantial work and manual coordination. In comparison, the Internet Computer upgrades itself weekly, which can be seen on the [ICP dashboard](https://dashboard.internetcomputer.org/releases). diff --git a/docs/tutorials/developer-journey/level-4/4.5-using-quill.mdx b/docs/tutorials/developer-journey/level-4/4.5-using-quill.mdx index 35f5ba8437..b643d26f23 100644 --- a/docs/tutorials/developer-journey/level-4/4.5-using-quill.mdx +++ b/docs/tutorials/developer-journey/level-4/4.5-using-quill.mdx @@ -14,7 +14,7 @@ import { MarkdownChipRow } from "/src/components/Chip/MarkdownChipRow";
-## Overview + Now that you've covered both the ICP ledger and the NNS, it's time to take a look at a CLI tool that can be used to interact with both. Quill is a ledger and governance toolkit that provides support for self-custody of ICP or ckBTC tokens and functionality to interact with the NNS, SNSs, and ICP ledger from a **cold wallet**. diff --git a/docs/tutorials/developer-journey/level-4/4.6-motoko-lvl4.mdx b/docs/tutorials/developer-journey/level-4/4.6-motoko-lvl4.mdx index 6a306ce0eb..9bfa1fb679 100644 --- a/docs/tutorials/developer-journey/level-4/4.6-motoko-lvl4.mdx +++ b/docs/tutorials/developer-journey/level-4/4.6-motoko-lvl4.mdx @@ -14,7 +14,7 @@ import { MarkdownChipRow } from "/src/components/Chip/MarkdownChipRow";
-## Overview + In this final Motoko module of the developer ladder series, you'll cover the following Motoko concepts and components: diff --git a/docs/tutorials/developer-journey/level-5/5.1-vetKeys-tutorial.mdx b/docs/tutorials/developer-journey/level-5/5.1-vetKeys-tutorial.mdx index 15aa03d90e..d6bd8394d3 100644 --- a/docs/tutorials/developer-journey/level-5/5.1-vetKeys-tutorial.mdx +++ b/docs/tutorials/developer-journey/level-5/5.1-vetKeys-tutorial.mdx @@ -16,7 +16,7 @@ import '/src/components/CenterImages/center.scss';
-## Overview + Many types of applications rely on secure ways to store user data and keep certain aspects of the dapp private. On a blockchain, transactions are traditionally public and dapps might rely on the storage within a web browser to store user-side secrets, which can lead to potential security risks. diff --git a/docs/tutorials/developer-journey/level-5/5.2-ICP-ETH-tutorial.mdx b/docs/tutorials/developer-journey/level-5/5.2-ICP-ETH-tutorial.mdx index 16c6e83584..01fda73be0 100644 --- a/docs/tutorials/developer-journey/level-5/5.2-ICP-ETH-tutorial.mdx +++ b/docs/tutorials/developer-journey/level-5/5.2-ICP-ETH-tutorial.mdx @@ -17,7 +17,7 @@ import useBaseUrl from "@docusaurus/useBaseUrl";
-## Overview + As you explored in a previous tutorial, the Internet Computer is integrated with the Bitcoin network, allowing for smart contracts to seamlessly communicate from ICP to Bitcoin for multi-chain functionality. ICP also has an integration with Ethereum and EVM networks, but in a different manner than the Bitcoin integration. diff --git a/docs/tutorials/developer-journey/level-5/5.3-token-swap-tutorial.mdx b/docs/tutorials/developer-journey/level-5/5.3-token-swap-tutorial.mdx index 3cb68ccaf7..e15f34f64b 100644 --- a/docs/tutorials/developer-journey/level-5/5.3-token-swap-tutorial.mdx +++ b/docs/tutorials/developer-journey/level-5/5.3-token-swap-tutorial.mdx @@ -17,7 +17,7 @@ import '/src/components/CenterImages/center.scss'; -## Overview + The Internet Computer enables decentralized finance (DeFi) applications through its design that includes complex, onchain computation. One primary example of a DeFi application is a decentralized exchange (DEX). A DEX is an exchange that can be used to buy, sell, trade, and withdraw cryptocurrencies and other digital assets without a centralized authority that authorizes the trades, such as bank. Decentralized exchanges are extremely useful, as they allow users to buy and hold cryptocurrencies, trade it directly for another token or coin, then withdraw the tokens to be used elsewhere. diff --git a/docs/tutorials/developer-journey/level-5/5.4-NFT-tutorial.mdx b/docs/tutorials/developer-journey/level-5/5.4-NFT-tutorial.mdx index 3b994efeae..27de1e93bd 100644 --- a/docs/tutorials/developer-journey/level-5/5.4-NFT-tutorial.mdx +++ b/docs/tutorials/developer-journey/level-5/5.4-NFT-tutorial.mdx @@ -17,7 +17,7 @@ import '/src/components/CenterImages/center.scss'; -## Overview + A **non-fungible token**, commonly referred to as an NFT, is a type of tokenized asset that is assigned a unique identifier that is used to distinguish one NFT from another. An NFT cannot be replicated or reproduced since it is cryptographically unique. A non-fungible token is a type of token that cannot be exchanged 1:1 with another token of the same type, as the value of the NFT token can vary. In comparison, a **fungible** token can always be transferred 1:1 for another token of the same type. diff --git a/docs/tutorials/developer-journey/level-5/5.5-auction-tutorial.mdx b/docs/tutorials/developer-journey/level-5/5.5-auction-tutorial.mdx index 4de9493fde..94bf2fa02e 100644 --- a/docs/tutorials/developer-journey/level-5/5.5-auction-tutorial.mdx +++ b/docs/tutorials/developer-journey/level-5/5.5-auction-tutorial.mdx @@ -10,7 +10,7 @@ import '/src/components/CenterImages/center.scss'; -## Overview + Until this point in the developer ladder series, each tutorial has focused on a specific use case or feature of ICP. To wrap up the series, this tutorial will showcase how to create a general purpose dapp that provides a real-world use case. In this tutorial, you'll create the foundation for a simple auction dapp. diff --git a/docs/tutorials/developer-journey/level-5/5.6-next-steps.mdx b/docs/tutorials/developer-journey/level-5/5.6-next-steps.mdx index 7f54573111..851341cfa6 100644 --- a/docs/tutorials/developer-journey/level-5/5.6-next-steps.mdx +++ b/docs/tutorials/developer-journey/level-5/5.6-next-steps.mdx @@ -8,7 +8,7 @@ import { MarkdownChipRow } from "/src/components/Chip/MarkdownChipRow"; -## Overview + Congratulations! You've completed the ICP developer ladder series, and are now an ICP astronaut! diff --git a/docs/tutorials/hackathon-prep-course/1-what-is-icp.mdx b/docs/tutorials/hackathon-prep-course/1-what-is-icp.mdx index 9414129a0d..3b7683e0e4 100644 --- a/docs/tutorials/hackathon-prep-course/1-what-is-icp.mdx +++ b/docs/tutorials/hackathon-prep-course/1-what-is-icp.mdx @@ -11,7 +11,7 @@ import '/src/components/CenterImages/center.scss'; -## Overview + The Internet Computer (ICP) is a transparent and secure blockchain network that enables developers to create and deploy fully decentralized applications. Decentralized applications are created through deploying smart contracts, which are known as **canisters** on ICP. Canisters are highly scalable to directly serve user experiences. Each canister on the Internet Computer is hosted on an independent version of the blockchain network called a **subnet**. **Subnets** can seamlessly communicate with each other. diff --git a/docs/tutorials/hackathon-prep-course/2-deploying-first-fullstack-dapp.mdx b/docs/tutorials/hackathon-prep-course/2-deploying-first-fullstack-dapp.mdx index 4fa745910c..1278f842b1 100644 --- a/docs/tutorials/hackathon-prep-course/2-deploying-first-fullstack-dapp.mdx +++ b/docs/tutorials/hackathon-prep-course/2-deploying-first-fullstack-dapp.mdx @@ -10,7 +10,7 @@ import '/src/components/CenterImages/center.scss'; -## Overview + To get started developing on ICP, there are several sample projects, boilerplate templates, and other resources to help you get started. In this tutorial, you'll learn how to deploy your first full-stack dapp using a boilerplate sample. This sample dapp uses Motoko for the backend canister and the frameworks Vite and React to create a frontend user interface (UI) that makes calls to a simple counter method in the backend canister. When the button in the UI is clicked, the counter function increases the value of the count by an increment of 1. The updated count value is then reflected in the UI. diff --git a/docs/tutorials/hackathon-prep-course/3-exploring-the-backend.mdx b/docs/tutorials/hackathon-prep-course/3-exploring-the-backend.mdx index db07240115..a3db8e4d6f 100644 --- a/docs/tutorials/hackathon-prep-course/3-exploring-the-backend.mdx +++ b/docs/tutorials/hackathon-prep-course/3-exploring-the-backend.mdx @@ -10,7 +10,7 @@ import '/src/components/CenterImages/center.scss'; -## Overview + In the previous tutorial, you deployed a sample full-stack dapp using the `vite-react-motoko` example boilerplate. This tutorial builds off of that previous tutorial, so if you haven't followed [2: Deploying your first fullstack dapp](/docs/current/tutorials/hackathon-prep-course/deploying-first-fullstack-dapp), it is recommended that you complete it prior to starting this tutorial. diff --git a/docs/tutorials/hackathon-prep-course/4-exploring-the-frontend.mdx b/docs/tutorials/hackathon-prep-course/4-exploring-the-frontend.mdx index ee79c07349..810e950c97 100644 --- a/docs/tutorials/hackathon-prep-course/4-exploring-the-frontend.mdx +++ b/docs/tutorials/hackathon-prep-course/4-exploring-the-frontend.mdx @@ -10,7 +10,7 @@ import '/src/components/CenterImages/center.scss'; -## Overview + Recall that a frontend canister is used to contain an application's user interface assets. In this tutorial, you will explore the frontend canister code to learn more. diff --git a/docs/tutorials/hackathon-prep-course/5-integrating-with-tokens.mdx b/docs/tutorials/hackathon-prep-course/5-integrating-with-tokens.mdx index 42cf363818..766bfb62d4 100644 --- a/docs/tutorials/hackathon-prep-course/5-integrating-with-tokens.mdx +++ b/docs/tutorials/hackathon-prep-course/5-integrating-with-tokens.mdx @@ -10,7 +10,7 @@ import '/src/components/CenterImages/center.scss'; -## Overview + When building dapps on the Internet Computer, integrating tokens into your dapp may be necessary for enabling DeFi, governance, marketplace, or other tokenomic functions. There are several types of tokens in the Internet Computer ecosystem, such as the protocol's native token ICP, fungible tokens that use the ICRC-1 or ICRC-2 standards, and soon non-fungible tokens that will use the upcoming ICRC-7 standard. diff --git a/docs/tutorials/hackathon-prep-course/6-authentication.mdx b/docs/tutorials/hackathon-prep-course/6-authentication.mdx index 97018a6c74..0d66d44f30 100644 --- a/docs/tutorials/hackathon-prep-course/6-authentication.mdx +++ b/docs/tutorials/hackathon-prep-course/6-authentication.mdx @@ -10,7 +10,7 @@ import '/src/components/CenterImages/center.scss'; -## Overview + For end-users to interact with the frontend of applications on ICP, Internet Identity can be used. Internet Identity is ICP's native form of digital identity that can be used to authenticate with apps, such as the NNS dashboard, without having to manage a username or password. Instead, Internet Identity uses a cryptographic key pair that's stored in your local device's hardware. diff --git a/docs/tutorials/hackathon-prep-course/7-obtaining-cycles.mdx b/docs/tutorials/hackathon-prep-course/7-obtaining-cycles.mdx index e21cbc9fae..b0350eb8f9 100644 --- a/docs/tutorials/hackathon-prep-course/7-obtaining-cycles.mdx +++ b/docs/tutorials/hackathon-prep-course/7-obtaining-cycles.mdx @@ -11,7 +11,7 @@ import '/src/components/CenterImages/center.scss'; -## Overview + Cycles are used to measure the resources, such as memory, storage, and compute power, that are used by a canister. When a canister is deployed on the mainnet, cycles are 'charged' for every action that a canister performs. diff --git a/docs/tutorials/hackathon-prep-course/8-managing-canisters.mdx b/docs/tutorials/hackathon-prep-course/8-managing-canisters.mdx index 2aff9956de..423e42763f 100644 --- a/docs/tutorials/hackathon-prep-course/8-managing-canisters.mdx +++ b/docs/tutorials/hackathon-prep-course/8-managing-canisters.mdx @@ -10,7 +10,7 @@ import '/src/components/CenterImages/center.scss'; -## Overview + Now that you have canisters deployed on the mainnet, it's important to learn how to manage and maintain those canisters. Basic canister management includes obtaining information about a canister, adding an identity as a controller of a canister, topping up a canister, starting and stopping a canister, and deleting a canister. diff --git a/how-it-works/0_general/01_overview-of-the-internet-computer.subpage.md b/how-it-works/0_general/01_overview-of-the-internet-computer.subpage.md index a6a0529ed1..2e7a630861 100644 --- a/how-it-works/0_general/01_overview-of-the-internet-computer.subpage.md +++ b/how-it-works/0_general/01_overview-of-the-internet-computer.subpage.md @@ -75,12 +75,12 @@ dapps on the IC can be governed by an out-of-the-box deployable governance syste If you want to learn in more detail how the IC works and realizes the vision of a World Computer, read through the sections of the page and the referenced Medium articles, or watch the YouTube videos. If you prefer to have a single source of information, the [White Paper](https://dfinity.org/whitepaper.pdf) is highly recommended. However, note that it is a little technical at times. -[Internet Computer for Geeks – White Paper](https://dfinity.org/whitepaper.pdf) -[Internet Computer Dashboard](https://dashboard.internetcomputer.org/) -[Internet Computer Source Code](https://github.com/dfinity/ic) -[Public Repositories for the Internet Computer](https://github.com/dfinity?q=&type=public&language=&sort=) -[Internet Computer Interface Specification Docs](https://internetcomputer.org/docs/current/references/ic-interface-spec) -[Internet Computer Primer - Deck](https://dfinity.org/deck/) -[Internet Computer SDK](https://github.com/dfinity/sdk) +- [Internet Computer for Geeks – White Paper](https://internetcomputer.org/whitepapers/The%20Internet%20Computer%20for%20Geeks.pdf) +- [Internet Computer Dashboard](https://dashboard.internetcomputer.org/) +- [Internet Computer Source Code](https://github.com/dfinity/ic) +- [Public Repositories for the Internet Computer](https://github.com/dfinity?q=&type=public&language=&sort=) +- [Internet Computer Interface Specification Docs](https://internetcomputer.org/docs/current/references/ic-interface-spec) +- [Internet Computer Primer - Deck](https://dfinity.org/deck/) +- [Internet Computer SDK](https://github.com/dfinity/sdk) [![Watch youtube video](https://i.ytimg.com/vi/YWHTNr8RZHg/maxresdefault.jpg)](https://www.youtube.com/watch?v=YWHTNr8RZHg) diff --git a/plugins/utils/redirects.js b/plugins/utils/redirects.js index 3217b7a205..99851dfc7d 100644 --- a/plugins/utils/redirects.js +++ b/plugins/utils/redirects.js @@ -54,7 +54,7 @@ const redirects = ` /docs/rust-guide/rust-intro /docs/current/developer-docs/backend/rust/ /docs/languages/languages-overview /docs/current/developer-docs/smart-contracts/write/overview /docs/current/developer-docs/smart-contracts/write/choosing-language /docs/current/developer-docs/smart-contracts/write/overview - /docs/current/developer-docs/frontend/my-contacts /docs/current/developer-docs/web-apps/application-frontends/add-stylesheet + /docs/current/developer-docs/frontend/my-contacts /docs/current/developer-docs/web-apps/application-frontends/default-frontend /docs/ic-interface-spec /docs/current/references/ic-interface-spec /docs/interface-spec /docs/current/references/ic-interface-spec /docs/current/developer-docs/updates/computation-and-storage-costs /docs/current/developer-docs/gas-cost @@ -110,7 +110,7 @@ const redirects = ` /docs/developers-guide/troubleshooting /docs/current/developer-docs/getting-started/troubleshooting /docs/developers-guide/tutorials-intro /docs/current/motoko/main/getting-started/motoko-introduction /docs/developers-guide/tutorials/default-frontend /docs/current/developer-docs/web-apps/application-frontends/default-frontend - /docs/developers-guide/tutorials/my-contacts /docs/current/developer-docs/web-apps/application-frontends/add-stylesheet + /docs/developers-guide/tutorials/my-contacts /docs/current/developer-docs/web-apps/application-frontends/default-frontend /docs/developers-guide/webpack-config /docs/current/developer-docs/web-apps/application-frontends/overview /docs/developers-guide/work-with-languages /docs/current/developer-docs/smart-contracts/write/overview /docs/developers-guide/working-with-canisters /docs/current/developer-docs/smart-contracts/maintain/settings @@ -340,7 +340,7 @@ const redirects = ` /docs/current/developer-docs/setup/best-practices/troubleshooting /docs/current/developer-docs/smart-contracts/best-practices/troubleshooting /docs/current/developer-docs/frontend/ /docs/current/developer-docs/web-apps/application-frontends/overview /docs/current/developer-docs/frontend/default-frontend /docs/current/developer-docs/web-apps/application-frontends/default-frontend - /docs/current/developer-docs/frontend/add-stylesheet /docs/current/developer-docs/web-apps/application-frontends/add-stylesheet + /docs/current/developer-docs/frontend/add-stylesheet /docs/current/developer-docs/web-apps/application-frontends/default-frontend /docs/current/developer-docs/frontend/boilerplate-frontend /docs/current/developer-docs/web-apps/application-frontends/overview /docs/current/developer-docs/frontend/existing-frontend /docs/current/developer-docs/web-apps/application-frontends/existing-frontend /docs/current/developer-docs/production/custom-domain/ /docs/current/developer-docs/web-apps/custom-domains/using-custom-domains @@ -657,6 +657,8 @@ const redirects = ` /docs/current/developer-docs/defi/tokens/ledger/usage/overview /docs/current/developer-docs/defi/overview /docs/current/developer-docs/web-apps/obtain-verify-ic-pubkey /docs/current/developer-docs/developer-tools/cli-tools/cli-reference/dfx-ping /docs/current/developer-docs/web-apps/design-dapps /docs/current/developer-docs/smart-contracts/overview/introduction + /docs/current/developer-docs/web-apps/application-frontends/add-stylesheet /docs/current/developer-docs/web-apps/application-frontends/default-frontend + ` .split(/[\r\n]+/) .map((line) => line.trim().replace(/^#.*$/, "").trim()) diff --git a/showcase.json b/showcase.json index e3f835c8a8..9c477d3b25 100644 --- a/showcase.json +++ b/showcase.json @@ -1,4 +1,24 @@ [ + { + "id": "decideai", + "name": "DecideAI", + "display": "Large", + "oneLiner": "A fullstack decentralized AI platform", + "website": "https://decideai.xyz", + "twitter": "https://twitter.com/DecideAI_", + "tags": [ + "AI", + "Tools / Infrastructure" + ], + "stats": "50,000+ inference requests", + "description": "DecideAI is an ecosystem that consists of three products, Decide Protocol, Decide ID, and Decide Cortex, designed to meet the needs of the high-end, specialized LLM market.", + "usesInternetIdentity": true, + "logo": "/img/showcase/decideai_logo.png", + "screenshots": [ + "/img/showcase/decideai_screenshot_0.png" + ], + "github": "https://github.com/modclub-app" + }, { "id": "bitfinity-evm", "name": "Bitfinity EVM", @@ -13,7 +33,7 @@ "description": "Bitfinity is the EVM compatibility layer for the IC. Using Bitfinity, you can deploy your Solidity smart contracts to the Internet Computer, taking advantage of its many advantageous DeFi capabilities: HTTPS Outcalls, the BTC integration, and more.", "usesInternetIdentity": true, "stats": "1,000+ TPS", - "display": "Large", + "display": "Normal", "logo": "/img/showcase/bitfinity_evm.svg", "screenshots": [ "/img/showcase/bitfinity_showcase.webp" @@ -334,13 +354,13 @@ { "id": "catalyze", "name": "Catalyze", - "website": "https://aqs24-xaaaa-aaaal-qbbea-cai.ic0.app/", + "website": "https://catalyze.one/", "tags": [ "SocialFi", "DAO" ], + "description": "Catalyze is building the new Web3 social learning hub: Communities, Events & Seamless Token Transfer, all in one place.", "twitter": "https://x.com/catalyze_one", - "description": "Catalyze is building the new Web3 social learning hub: Communities, Events & Seamless Token Transfer. Now onboarding KOLs.", "usesInternetIdentity": true, "oneLiner": "Manage your Web3 communities and events", "display": "Large", @@ -624,26 +644,6 @@ "/img/showcase/plethora_screenshot.webp" ] }, - { - "id": "decideai", - "name": "DecideAI", - "display": "Large", - "oneLiner": "A fullstack decentralized AI platform", - "website": "https://decideai.xyz", - "twitter": "https://twitter.com/DecideAI_", - "tags": [ - "AI", - "Tools / Infrastructure" - ], - "stats": "50,000+ inference requests", - "description": "DecideAI is an ecosystem that consists of three products, Decide Protocol, Decide ID, and Decide Cortex, designed to meet the needs of the high-end, specialized LLM market.", - "usesInternetIdentity": true, - "logo": "/img/showcase/decideai_logo.png", - "screenshots": [ - "/img/showcase/decideai_screenshot_0.png" - ], - "github": "https://github.com/modclub-app" - }, { "id": "querio", "name": "Querio", diff --git a/sidebars.js b/sidebars.js index bbff85da62..a5904dbf74 100644 --- a/sidebars.js +++ b/sidebars.js @@ -14,7 +14,7 @@ const sidebars = { }, { type: "doc", - label: "React", + label: "First web app", id: "developer-docs/getting-started/quickstart/react-quickstart", }, ], @@ -35,34 +35,29 @@ const sidebars = { }, { type: "doc", - label: "Install tools", + label: "Installing developer tools", id: "developer-docs/getting-started/install", }, { type: "doc", - label: "Create an identity", + label: "Creating a developer identity", id: "developer-docs/getting-started/identities", }, { type: "doc", - label: "Tokens and cycles", + label: "Using tokens and cycles", id: "developer-docs/getting-started/tokens-and-cycles", }, { type: "doc", - label: "Write smart contracts", + label: "Writing smart contracts", id: "developer-docs/getting-started/write-smart-contracts", }, { type: "doc", - label: "Deploy and manage", + label: "Deploying and managing dapps", id: "developer-docs/getting-started/deploy-and-manage", }, - { - type: "doc", - label: "Next steps", - id: "developer-docs/getting-started/next-steps", - }, ], }, { @@ -71,9 +66,12 @@ const sidebars = { items: [ { type: "category", - label: "Overview", + label: "What are canisters?", + link: { + type: "doc", + id: "developer-docs/smart-contracts/overview/introduction", + }, items: [ - "developer-docs/smart-contracts/overview/introduction", "developer-docs/smart-contracts/overview/inside-canisters", "developer-docs/smart-contracts/development-workflow", "developer-docs/smart-contracts/overview/trust-in-canisters", @@ -109,24 +107,22 @@ const sidebars = { { type: "category", label: "Deploy", + link: { + type: "doc", + id: "developer-docs/smart-contracts/deploy/overview", + }, items: [ - { - label: "Overview", - type: "doc", - id: "developer-docs/smart-contracts/deploy/overview", - }, "developer-docs/smart-contracts/deploy/custom-testnets", ], }, { type: "category", label: "Call", + link: { + type: "doc", + id: "developer-docs/smart-contracts/call/overview", + }, items: [ - { - type: "doc", - label: "Overview", - id: "developer-docs/smart-contracts/call/overview", - }, { type: "doc", label: "Async code & inter-canister calls", @@ -187,12 +183,11 @@ const sidebars = { { type: "category", label: "Test", + link: { + type: "doc", + id: "developer-docs/smart-contracts/test/overview", + }, items: [ - { - label: "Overview", - type: "doc", - id: "developer-docs/smart-contracts/test/overview", - }, "developer-docs/smart-contracts/test/pocket-ic", ], }, @@ -215,12 +210,11 @@ const sidebars = { { type: "category", label: "HTTPS outcalls", + link: { + type: "doc", + id: "developer-docs/smart-contracts/advanced-features/https-outcalls/https-outcalls-overview", + }, items: [ - { - label: "Overview", - type: "doc", - id: "developer-docs/smart-contracts/advanced-features/https-outcalls/https-outcalls-overview", - }, "developer-docs/smart-contracts/advanced-features/https-outcalls/https-outcalls-how-to-use", "developer-docs/smart-contracts/advanced-features/https-outcalls/https-outcalls-get", "developer-docs/smart-contracts/advanced-features/https-outcalls/https-outcalls-post", @@ -323,12 +317,11 @@ const sidebars = { { type: "category", label: "Developer tools", + link: { + type: "doc", + id: "developer-docs/developer-tools/dev-tools-overview", + }, items: [ - { - type: "doc", - label: "Overview", - id: "developer-docs/developer-tools/dev-tools-overview", - }, { type: "category", label: "Command line", @@ -481,12 +474,11 @@ const sidebars = { { type: "category", label: "Agents", + link: { + type: "doc", + id: "developer-docs/developer-tools/off-chain/agents/overview", + }, items: [ - { - label: "Overview", - type: "doc", - id: "developer-docs/developer-tools/off-chain/agents/overview", - }, "developer-docs/developer-tools/off-chain/agents/javascript-agent", "developer-docs/developer-tools/off-chain/agents/nodejs", "developer-docs/developer-tools/off-chain/agents/rust-agent", @@ -525,14 +517,12 @@ const sidebars = { { type: "category", label: "Application frontends", + link: { + type: "doc", + id: "developer-docs/web-apps/application-frontends/overview", + }, items: [ - { - label: "Overview", - type: "doc", - id: "developer-docs/web-apps/application-frontends/overview", - }, "developer-docs/web-apps/application-frontends/default-frontend", - "developer-docs/web-apps/application-frontends/add-stylesheet", "developer-docs/web-apps/application-frontends/existing-frontend", "developer-docs/web-apps/application-frontends/asset-security", "developer-docs/web-apps/application-frontends/webpack", @@ -561,12 +551,11 @@ const sidebars = { { type: "category", label: "Security best practices", + link: { + type: "doc", + id: "developer-docs/security/security-best-practices/overview", + }, items: [ - { - type: "doc", - label: "Overview", - id: "developer-docs/security/security-best-practices/overview", - }, { type: "doc", label: "Inter-canister calls", @@ -634,22 +623,20 @@ const sidebars = { { type: "category", label: "Chain Fusion", + link: { + type: "doc", + id: "developer-docs/multi-chain/overview", + }, items: [ - { - label: "Overview", - type: "doc", - id: "developer-docs/multi-chain/overview", - }, "developer-docs/multi-chain/supported-chains", { type: "category", label: "Bitcoin", + link: { + type: "doc", + id: "developer-docs/multi-chain/bitcoin/overview", + }, items: [ - { - label: "Overview", - type: "doc", - id: "developer-docs/multi-chain/bitcoin/overview", - }, "developer-docs/multi-chain/bitcoin/using-btc/btc-comparison", "developer-docs/multi-chain/bitcoin/using-btc/btc-dev-workflow", { @@ -671,12 +658,11 @@ const sidebars = { { type: "category", label: "Ethereum", + link: { + type: "doc", + id: "developer-docs/multi-chain/ethereum/overview", + }, items: [ - { - label: "Overview", - type: "doc", - id: "developer-docs/multi-chain/ethereum/overview", - }, "developer-docs/multi-chain/ethereum/using-eth/eth-comparison", "developer-docs/multi-chain/ethereum/using-eth/eth-dev-workflow", { @@ -691,12 +677,11 @@ const sidebars = { { type: "category", label: "EVM RPC canister", + link: { + type: "doc", + id: "developer-docs/multi-chain/ethereum/evm-rpc/overview", + }, items: [ - { - label: "Overview", - type: "doc", - id: "developer-docs/multi-chain/ethereum/evm-rpc/overview", - }, "developer-docs/multi-chain/ethereum/evm-rpc/how-it-works", "developer-docs/multi-chain/ethereum/evm-rpc/evm-rpc-canister", "developer-docs/multi-chain/ethereum/evm-rpc/costs", @@ -709,17 +694,19 @@ const sidebars = { { type: "category", label: "Chain-key tokens", + link: { + type: "doc", + id: "developer-docs/multi-chain/chain-key-tokens/overview", + }, items: [ - "developer-docs/multi-chain/chain-key-tokens/overview", { type: "category", label: "ckBTC", + link: { + type: "doc", + id: "developer-docs/multi-chain/chain-key-tokens/ckbtc/overview", + }, items: [ - { - label: "Overview", - type: "doc", - id: "developer-docs/multi-chain/chain-key-tokens/ckbtc/overview", - }, "developer-docs/multi-chain/chain-key-tokens/ckbtc/making-transactions", "developer-docs/multi-chain/chain-key-tokens/ckbtc/using-ckbtc-in-dapps", ], @@ -727,12 +714,11 @@ const sidebars = { { type: "category", label: "ckETH", + link: { + type: "doc", + id: "developer-docs/multi-chain/chain-key-tokens/cketh/overview", + }, items: [ - { - label: "Overview", - type: "doc", - id: "developer-docs/multi-chain/chain-key-tokens/cketh/overview", - }, "developer-docs/multi-chain/chain-key-tokens/cketh/making-transactions", "developer-docs/multi-chain/chain-key-tokens/cketh/using-cketh-in-dapps", ], @@ -740,12 +726,11 @@ const sidebars = { { type: "category", label: "ckERC20", + link: { + type: "doc", + id: "developer-docs/multi-chain/chain-key-tokens/ckerc20/overview", + }, items: [ - { - label: "Overview", - type: "doc", - id: "developer-docs/multi-chain/chain-key-tokens/ckerc20/overview", - }, "developer-docs/multi-chain/chain-key-tokens/ckerc20/making-transactions", "developer-docs/multi-chain/chain-key-tokens/ckerc20/using-ckerc20-in-dapps", "developer-docs/multi-chain/chain-key-tokens/ckerc20/creating-new-ckerc20", @@ -758,21 +743,19 @@ const sidebars = { { type: "category", label: "Authentication", + link: { + type: "doc", + id: "developer-docs/identity/authentication/overview", + }, items: [ - { - label: "Overview", - type: "doc", - id: "developer-docs/identity/authentication/overview", - }, { type: "category", label: "Internet Identity (II)", + link: { + type: "doc", + id: "developer-docs/identity/internet-identity/overview", + }, items: [ - { - label: "Overview", - type: "doc", - id: "developer-docs/identity/internet-identity/overview", - }, "developer-docs/identity/internet-identity/creating-ii", "developer-docs/identity/internet-identity/integrate-internet-identity", "developer-docs/identity/internet-identity/alternative-origins", @@ -781,12 +764,11 @@ const sidebars = { { type: "category", label: "Verifiable credentials", + link: { + type: "doc", + id: "developer-docs/identity/verifiable-credentials/overview", + }, items: [ - { - label: "Overview", - type: "doc", - id: "developer-docs/identity/verifiable-credentials/overview", - }, "developer-docs/identity/verifiable-credentials/how-it-works", "developer-docs/identity/verifiable-credentials/issuer", "developer-docs/identity/verifiable-credentials/relying-party", @@ -797,12 +779,11 @@ const sidebars = { { type: "category", label: "Digital assets", + link: { + type: "doc", + id: "developer-docs/defi/overview", + }, items: [ - { - type: "doc", - label: "Overview", - id: "developer-docs/defi/overview", - }, { type: "category", label: "Tokens", @@ -990,12 +971,11 @@ const sidebars = { { type: "category", label: "NFTs", + link: { + type: "doc", + id: "developer-docs/defi/nfts/overview", + }, items: [ - { - type: "doc", - label: "Overview", - id: "developer-docs/defi/nfts/overview", - }, "developer-docs/defi/nfts/nft-collections", "developer-docs/defi/nfts/marketplaces" ], @@ -1003,23 +983,21 @@ const sidebars = { { type: "category", label: "Decentralized exchanges", + link: { + type: "doc", + id: "developer-docs/defi/dex/overview", + }, items: [ - { - type: "doc", - label: "Overview", - id: "developer-docs/defi/dex/overview", - } ], }, { type: "category", label: "Wallets", + link: { + type: "doc", + id: "developer-docs/defi/wallets/overview", + }, items: [ - { - type: "doc", - label: "Overview", - id: "developer-docs/defi/wallets/overview", - }, "developer-docs/defi/wallets/self-custody/self-custody-quickstart", "developer-docs/defi/wallets/self-custody/hardware-wallet-cli", ], @@ -1029,21 +1007,19 @@ const sidebars = { { type: "category", label: "Decentralized AI", + link: { + type: "doc", + id: "developer-docs/ai/overview", + }, items: [ - { - type: "doc", - label: "Overview", - id: "developer-docs/ai/overview", - }, { type: "category", label: "Inference", + link: { + type: "doc", + id: "developer-docs/ai/inference", + }, items: [ - { - type: "doc", - label: "Overview", - id: "developer-docs/ai/inference", - }, "developer-docs/ai/samples", ], }, @@ -1057,12 +1033,11 @@ const sidebars = { { type: "category", label: "Network Nervous System (NNS)", + link: { + type: "doc", + id: "developer-docs/daos/nns/overview", + }, items: [ - { - type: "doc", - label: "Overview", - id: "developer-docs/daos/nns/overview", - }, { type: "category", label: "Using the NNS dapp", @@ -1119,7 +1094,7 @@ const sidebars = { }, items: [ { - label: "Overview", + label: "What is an SNS?", type: "doc", id: "developer-docs/daos/sns/overview", }, @@ -1262,12 +1237,11 @@ const sidebars = { { type: "category", label: "ICP dashboard", + link: { + type: "doc", + id: "references/dashboard/overview", + }, items: [ - { - type: "doc", - label: "Overview", - id: "references/dashboard/overview", - }, "references/dashboard/using-the-dashboard", "references/dashboard/dashboard-apis", ], @@ -1286,24 +1260,22 @@ const sidebars = { { type: "category", label: "Node providers", + link: { + type: "doc", + id: "references/node-providers/overview", + }, items: [ - { - type: "doc", - label: "Overview", - id: "references/node-providers/overview", - }, "references/node-providers/node-metrics", ], }, { type: "category", label: "Subnets", + link: { + type: "doc", + id: "references/subnets/overview", + }, items: [ - { - type: "doc", - label: "Overview", - id: "references/subnets/overview", - }, "references/subnets/subnet-types", ], }, diff --git a/src/components/Common/toolingItems.ts b/src/components/Common/toolingItems.ts index f9d13c6ce4..69b97bcff4 100644 --- a/src/components/Common/toolingItems.ts +++ b/src/components/Common/toolingItems.ts @@ -21,6 +21,12 @@ export const dfinityToolingItems = [ description: "A configurable Prettier plugin for Motoko.", links: { github: "https://github.com/dfinity/prettier-plugin-motoko" }, }, + { + title: "ICP Ninja", + tags: ["IDE", "website", "development"], + description: "A web-based IDE for developing and deploying ICP smart contracts.", + links: { external: "https://icp.ninja" }, + }, { title: "Motoko Playground", tags: ["website"], diff --git a/static/img/blog/dev-update-blog-dec-11.jpg b/static/img/blog/dev-update-blog-dec-11.jpg new file mode 100644 index 0000000000..a219d0ce29 Binary files /dev/null and b/static/img/blog/dev-update-blog-dec-11.jpg differ diff --git a/style-guide.md b/style-guide.md index 282f0d67ff..9a1ad8051b 100644 --- a/style-guide.md +++ b/style-guide.md @@ -1,6 +1,6 @@ -# Dev Docs Style Guide +# ICP Developer Documentation style guide -## Overview +## Purpose of this guide This guide outlines the format, language, and style that should be used when contributing pages to the Internet Computer developer documentation. This is designed to assist with standardizing the documentation to create a cohesive, uniform look and feel across all pages of documentation that have been contributed by multiple individuals and teams. @@ -21,7 +21,7 @@ This guide will outline the following: ## Page structure -The developers docs contain a wide variety of different document types, such as overview pages, concept pages, feature pages, tutorials, and reference pages. For this reason, the page structure will vary based on what type of document the page is. +The developers docs contain a wide variety of different document types, such as introduction pages, concept pages, feature pages, tutorials, and reference pages. For this reason, the page structure will vary based on what type of document the page is. The following example template can be used: @@ -36,8 +36,6 @@ import { MarkdownChipRow } from "/src/components/Chip/MarkdownChipRow"; -## Overview - Introduce the feature or tool. What is it? Give a brief overview of how it works, but keep it very high level. Link to additional documents that explain the in-depth concepts behind it (if they exist). ## Prerequisites @@ -45,9 +43,15 @@ Introduce the feature or tool. What is it? Give a brief overview of how it works Optional; only necessary for documents that require prerequisite conditions or parameters be met. List all dependencies that the developer will need to download or setup in order to use the feature. The most common prerequisite is downloading dfx. Please link to the dfx installation page. -- [x] Prerequisite 1. -- [x] Prerequisite 2. -- [x] Prerequisite 3. + + + + +Before you start, verify that you have: + Install the IC SDK. + + + ## Topic 1 @@ -90,7 +94,7 @@ There are 4 types of headings used throughout the ICP developer docs: | Heading size | Usage | |--------------|-------| | Heading 1 | Page title only; not used within the page's content.| -| Heading 2 | Used for primary topics amongst the page; used for consistent page headings such as 'Overview', 'Prerequisites', 'Conclusion' and 'References'.| +| Heading 2 | Used for primary topics amongst the page; used for consistent page headings such as 'Prerequisites', 'Conclusion' and 'References'.| | Heading 3 | Used for subtopics under primary topics amongst the page or user steps within a tutorial. Note; there are some instances where using Heading 2 for a tutorial step is more fitting, such as when a step contains several different concepts or subtopics. Please refer to the writing a tutorial section below for further information.| | Heading 4 | Used for listing steps a user should take within a guide document, where the guide document includes several different, separate walkthroughs for the user to follow; in this scenario, this heading should be used in conjunction with a bullet point. Heading 4 is also used for listing terms within the `glossary` document page and for subtopics under an already existing Heading 3 subtopic heading. | @@ -101,8 +105,6 @@ The following is a sample guide document that showcases how the 4 types of headi ``` # File management -## Overview - This document describes basic file management workflows. ### Workflows covered @@ -156,7 +158,6 @@ Capitalization within the developer documentation should follow these outlined s - Example: Using Internet Identity with a dapp - Example: Motoko reference guide - Only the first word of a page heading should be capitalized unless the title includes a proper noun. - - Example: Overview - Example: Register, build, and deploy the dapp - Example: Using Motoko canisters - Titles of links to other documentation pages or external articles, such as blog posts, should not be capitalized except for the proper nouns within the title. diff --git a/submodules/dfxvm b/submodules/dfxvm index f3a159e194..5e887d483b 160000 --- a/submodules/dfxvm +++ b/submodules/dfxvm @@ -1 +1 @@ -Subproject commit f3a159e194e5b386509795c5c2088f4b0d9c08ab +Subproject commit 5e887d483bf99b7cbe8ef88edc06b0bc15cd7dee diff --git a/submodules/internetidentity b/submodules/internetidentity index 766795bf2f..411ed8a69c 160000 --- a/submodules/internetidentity +++ b/submodules/internetidentity @@ -1 +1 @@ -Subproject commit 766795bf2f289685c1b66b9078b2aa54c5b6eb08 +Subproject commit 411ed8a69ce74fd5617e292f86773ce5555aba8f diff --git a/submodules/motoko b/submodules/motoko index 6603c0ac25..e88efd9f9b 160000 --- a/submodules/motoko +++ b/submodules/motoko @@ -1 +1 @@ -Subproject commit 6603c0ac25df0ae7527b8abd3b563b0714c9b027 +Subproject commit e88efd9f9b7a7631586ea4ea06432426a1dcb986 diff --git a/submodules/quill b/submodules/quill index 5a5a9ad4a7..077696fd4e 160000 --- a/submodules/quill +++ b/submodules/quill @@ -1 +1 @@ -Subproject commit 5a5a9ad4a72ea9fa9f0adad5c3b11b00ced78db9 +Subproject commit 077696fd4e433cd6f590bc9cec1674c8275faed9 diff --git a/submodules/response-verfication b/submodules/response-verfication index 7e3f70d69f..b8aa830680 160000 --- a/submodules/response-verfication +++ b/submodules/response-verfication @@ -1 +1 @@ -Subproject commit 7e3f70d69fa5e238d1be81af58f89cb2a012abe7 +Subproject commit b8aa830680fbd95bb3105ca7402002a2b5d98cd6 diff --git a/submodules/samples b/submodules/samples index daf9a06654..786c2e9c3d 160000 --- a/submodules/samples +++ b/submodules/samples @@ -1 +1 @@ -Subproject commit daf9a06654785c59ec273df1df459bb1b03b85cf +Subproject commit 786c2e9c3d6b6b5e13351f536f1e5f14f6d43ede diff --git a/submodules/sdk b/submodules/sdk index 3405dc6933..26a976dac6 160000 --- a/submodules/sdk +++ b/submodules/sdk @@ -1 +1 @@ -Subproject commit 3405dc693391c144c97ab77d8a67cf70a3606343 +Subproject commit 26a976dac61991eaaf426c0fd9d31eaafecc7c42