Internet Computer Developer Documentation
This is an experimental approach to developer focused documentation on the Internet Computer.
For official Dfinity Foundation developer documentation visit DFINITY SDK
To get started developing on the Internet Computer, visit the Getting Started guides.
This documentation is designed to be a self-service documentation tool for the Internet Computer developer community. This repository is open sourced and any developer can submit a pull request to have the documentation updated.
This section will serve as a hands-on guide for how to get your development environment ready for deploying to the Internet Computer.
Install the latest version of WSL from Window's official website
Open PowerShell as Administrator and run:
dism.exe /online /enable-feature /featurename:Microsoft-Windows-Subsystem-Linux /all /norestart
Enable Virtual Machine feature by running:
dism.exe /online /enable-feature /featurename:VirtualMachinePlatform /all /norestart
Download the Linux kernel update package from this link
Run the update package downloaded in the previous step.
Open PowerShell and run this command to set WSL 2 as the default version:
wsl --set-default-version 2
Install ubuntu or any other Linux distribution from Window's store
Open terminal and install NodeJS by running
sudo apt install nodejs
Once installed, verify it by checking the installed version by running:
node -v or node –version
and you should see a response similar to
% node --version
v14.17.0
Install NPM by running
sudo apt install npm
npm -v or npm –version
Install the SDK
In your terminal, run:
sh -ci "$(curl -fsSL https://sdk.dfinity.org/install.sh)"
Note if while creating a new project you get a error of missing module run the following commands in the root of the project directory.
npm install @dfinity/candid
npm install @dfinity/agent
npm i @dfinity/principal
Ensure you have Homebrew installed
Note dfx is currently not officially supported on Macs with M1 CPUs. The SDK team is working on a fix.
In your terminal run:
brew --version
and you should see a response similar to
% brew --version
Homebrew 3.2.0
Homebrew/homebrew-core (git revision 9ea42e7407; last commit 2021-06-23)
Homebrew/homebrew-cask (git revision 2696a93ca5; last commit 2021-06-23)
If you see a Homebrew version ; you have Homebrew installed and can proceed to the next section. If not paste the following command in your terminal to install Homebrew:
/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/master/install.sh)"
Ensure you have Node installed
In your terminal run:
node --version
and you should see a response similar to
% node --version
v14.17.0
If you see a Node version ; you have Node installed and can proceed to the next section. If not, use brew to install Node:
brew install node
Install Rust (Optional)
In your terminal, run:
$ curl --proto '=https' --tlsv1.2 https://sh.rustup.rs -sSf | sh
and follow the instructions to install Rust.
Install the SDK
In your terminal, run:
sh -ci "$(curl -fsSL https://sdk.dfinity.org/install.sh)"
Get Cycles (for Network Deployments)
Now that you've successfully installed the SDK follow the steps to get cycles
In order to deploy to the production Internet Computer network, you will need to acquire ICP and then mint cycles for your canisters.
You can purchase ICPs for yourself at any well known exchange. In order to withdraw from the exchange to your personal address, you'll need a ledger account id.
For the purpose of this tutorial, we will use dfx to manage our identities.
Dfx Identities
dfx comes bundled with an identity management toolchain. You can view your current identity by running the command:
dfx identity whoami
The response will most likely be default if you are using a clean installation of dfx.
You can list your identities with:
dfx identity list
Go ahead and create a new identity for this example dfx identity new icptutorial:
% dfx identity new icptutorial
Creating identity: "icptutorial".
Created identity: "icptutorial".
and switch to the identity with dfx identity use icptutorial:
% dfx identity use icptutorial
Using identity: "icptutorial".
Principal Id
As with other blockchain networks, digital signature schemes are used for authenticating messages in various parts of the IC infrastructure. When creating an identity with dfx a .pem file is generated for the identity. These files can be found under the ~/.config/dfx/identity/ directory. Your Internet Computer "Principal" is roughly equivalent to your "public address" in other blockchain systems. You will need this identifier handy in the cycles creation steps. You can get your Principal id with the following command:
% dfx identity get-principal
jvehu-ucxvu-4kulk-noxef-ggd5l-vtx7j-55dob-6546u-eklzd-s4uut-2qe
Ledger Id
Now that you've created a new identity you will need to find the ledger account id for that identity's principal address. Luckily, dfx comes bundled with support for the ICP Ledger canister. You can get the ledger account id with the dfx ledger account-id command:
% dfx ledger account-id
5126d232242e7c54f8da0ab6a5b37e020d06ffc05acacad536290eda22bbf134
Now that you have a ledger account-id; you can withdraw ICPs from your exchange of choice to the account address.
You can always check your ICP balance with dfx and assuming you withdrew ICPs to your account, you should have some balance:
% dfx ledger --network ic balance
1.00000000 ICP
Cycles Wallet
Now that you have ICPs in the ICP Ledger, you can use those ICPs to mint cycles. Minting cycles is a one way process; ICPs can mint cycles and cycles are used to pay for canister computation. Cycles cannot be transformed back into ICPs.
The first step to mint cycles is to to create a wallet canister on the production Internet Computer network computer. You will need the Principal id you used when creating your identity.
The command will look like:
dfx ledger --network ic create-canister <principal-identifier> --amount <icp-tokens>
Lets create an empty canister and preload it with 0.1 ICP as follows:
% dfx ledger --network ic create-canister jvehu-ucxvu-4kulk-noxef-ggd5l-vtx7j-55dob-6546u-eklzd-s4uut-2qe --amount 0.1
Transfer sent at BlockHeight: 239461
Canister created with id: "ad6mp-3aaaa-aaaah-qacya-cai"
Great! Now you have a empty canister living on the Internet Computer. Next we will install the cycles-wallet code into that canister with dfx:
dfx identity --network ic deploy-wallet <canister-identifer>
The previous command gave us our canister id, so lets use that:
% dfx identity --network ic deploy-wallet ad6mp-3aaaa-aaaah-qacya-cai
Creating a wallet canister on the ic network.
The wallet canister on the "ic" network for user "icptutorial" is "ad6mp-3aaaa-aaaah-qacya-cai"
Congrats! You now have a cycles wallet. You can check the balance with dfx using:
% dfx wallet --network ic balance
1923942143701 cycles.
You can also view your wallet canister web UI by putting your canister id in the browser URL box and adding .raw.ic0.app/ to the end. You will need to sign in with Internet Identity and authorize the wallet to your II in order to view the cycles wallet UI.
Topping Up
If you ever run low on cycles you can always top up your cycles balance with dfx:
% dfx ledger --network ic top-up ad6mp-3aaaa-aaaah-qacya-cai
Transfer sent at BlockHeight: 239474
Canister was topped up!
% dfx wallet --network ic balance
1923941192095 cycles.
Be Mindful!
Please be mindful, dfx is a command line tool meant for development and deployment. It is not intended to be a secure, general purpose wallet for storing secure private keys. If you will be using dfx for development purposes it is highly recommended that you only maintain a balance required for developing and deploying your applications while maintaining larger balances in a more conventionally safe storage medium (cold wallets, hardware wallets, online custodial services, etc).
This section will serve as a hands-on guide for how to do specific tasks on the Internet Computer.
Installing an mdbook on the Internet Computer
mdBook is a utility to create modern online books from Markdown files.
This website is a mdBook website! It uses Markdown to generate the content and lives on the Internet Computer.
In this tutorial we will show you how to:
- Install mdBook locally
- Deploy your first mdBook onto a local replica
- Deploy your first mdBook to the production Internet Computer network
Install mdBook Locally
If you have your Rust and Cargo development environment already set up, installing mdBook is as easy as using Cargo:
cargo install mdbook
Deploy your first mdBook onto a local replica
First, create a new dfx project mymdbook
dfx new mymdbook
dfx will then auto-generate the requisite files for your new dfx project:
% dfx new mymdbook
Fetching manifest https://sdk.dfinity.org/manifest.json
Creating new project "mymdbook"...
CREATE mymdbook/src/mymdbook_assets/assets/sample-asset.txt (24B)...
CREATE mymdbook/src/mymdbook/main.mo (107B)...
CREATE mymdbook/dfx.json (478B)...
CREATE mymdbook/.gitignore (165B)...
CREATE mymdbook/README.md (1.16KB)...
CREATE mymdbook/src/mymdbook_assets/src/index.js (521B)...
CREATE mymdbook/src/mymdbook_assets/src/index.html (538B)...
CREATE mymdbook/src/mymdbook_assets/assets/logo.png (24.80KB)...
CREATE mymdbook/src/mymdbook_assets/assets/main.css (484B)...
CREATE mymdbook/package.json (479B)...
CREATE mymdbook/webpack.config.js (2.92KB)...
⠉ Installing node dependencies...
Done.
Creating git repository...
===============================================================================
Welcome to the internet computer developer community!
You're using dfx 0.7.2
▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄ ▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄
▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄ ▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄
▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄ ▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄
▄▄▄▄▄▄▄▄▄▄▀▀▀▀▀▄▄▄▄▄▄▄▄▄▄▄▄ ▄▄▄▄▄▄▄▄▄▄▄▄▀▀▀▀▀▀▄▄▄▄▄▄▄▄▄▄
▄▄▄▄▄▄▄▄▀ ▀▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▀ ▀▄▄▄▄▄▄▄▄▄
▄▄▄▄▄▄▄▄▀ ▀▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▀ ▄▄▄▄▄▄▄▄
▄▄▄▄▄▄▄▄ ▀▄▄▄▄▄▄▄▄▄▄▄▄▀ ▄▄▄▄▄▄▄
▄▄▄▄▄▄▄▄ ▄▄▄▄▄▄▄▄▄▄▄▄ ▄▄▄▄▄▄▄
▄▄▄▄▄▄▄▄ ▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄ ▄▄▄▄▄▄▄▄
▄▄▄▄▄▄▄▄ ▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄ ▄▄▄▄▄▄▄▄▀
▀▄▄▄▄▄▄▄▄▄▄ ▄▄▄▄▄▄▄▄▄▄▄▄▀ ▀▄▄▄▄▄▄▄▄▄▄▄▄ ▄▄▄▄▄▄▄▄▄▄▄
▀▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▀ ▀▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▀
▀▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▀ ▀▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄
▀▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▀▀ ▀▀▄▄▄▄▄▄▄▄▄▄▄▄▄▄▀
▀▀▀▀▀▀▀▀▀▀▀ ▀▀▀▀▀▀▀▀▀▀▀
To learn more before you start coding, see the documentation available online:
- Quick Start: https://sdk.dfinity.org/docs/quickstart/quickstart-intro.html
- SDK Developer Tools: https://sdk.dfinity.org/docs/developers-guide/sdk-guide.html
- Motoko Language Guide: https://sdk.dfinity.org/docs/language-guide/motoko.html
- Motoko Quick Reference: https://sdk.dfinity.org/docs/language-guide/language-manual.html
If you want to work on programs right away, try the following commands to get started:
cd mymdbook
dfx help
dfx new --help
===============================================================================
Change into your mymdbook directory and initialize the mdbook:
% cd mymdbook
% mdbook init
Do you want a .gitignore to be created? (y/n)
n
What title would you like to give the book?
mymdbook
[INFO] (mdbook::book::init): Creating a new book with stub content
All done, no errors...
You will not need the dfx generated Motoko or asset canister code for this tutorial, feel free to delete those
rm -rf src/mymdbook/
Delete all the contents in your dfx.json and create an entry for your mdbook:
{
"canisters": {
"book": {
"type": "assets",
"source": ["book"]
}
}
}
Build your mdbook:
% mdbook build
[INFO] (mdbook::book): Book building has started
[INFO] (mdbook::book): Running the html backend
Ensure that you have a replica running locally:
dfx start --background
Then dfx deploy!:
% dfx deploy
Creating a wallet canister on the local network.
The wallet canister on the "local" network for user "default" is "r7inp-6aaaa-aaaaa-aaabq-cai"
Deploying all canisters.
Creating canisters...
Creating canister "book"...
"book" canister created with canister id: "rkp4c-7iaaa-aaaaa-aaaca-cai"
Building canisters...
Building frontend...
Installing canisters...
Creating UI canister on the local network.
The UI canister on the "local" network is "rno2w-sqaaa-aaaaa-aaacq-cai"
Installing code for canister book, with canister_id rkp4c-7iaaa-aaaaa-aaaca-cai
Authorizing our identity (default) to the asset canister...
Uploading assets to asset canister...
/mark.min.js 1/1 (17320 bytes)
/mark.min.js (gzip) 1/1 (5950 bytes)
/searcher.js 1/1 (18474 bytes)
/searcher.js (gzip) 1/1 (5082 bytes)
/highlight.css 1/1 (1215 bytes)
/highlight.css (gzip) 1/1 (575 bytes)
/index.html 1/1 (8405 bytes)
/index.html (gzip) 1/1 (2125 bytes)
/ayu-highlight.css 1/1 (947 bytes)
/ayu-highlight.css (gzip) 1/1 (440 bytes)
/FontAwesome/css/font-awesome.css 1/1 (31000 bytes)
/FontAwesome/css/font-awesome.css (gzip) 1/1 (6995 bytes)
/FontAwesome/fonts/fontawesome-webfont.svg 1/1 (444379 bytes)
/FontAwesome/fonts/FontAwesome.ttf 1/1 (165548 bytes)
/FontAwesome/fonts/fontawesome-webfont.woff2 1/1 (77160 bytes)
/FontAwesome/fonts/fontawesome-webfont.ttf 1/1 (165548 bytes)
/FontAwesome/fonts/fontawesome-webfont.woff 1/1 (98024 bytes)
/FontAwesome/fonts/fontawesome-webfont.eot 1/1 (165742 bytes)
/css/variables.css 1/1 (5944 bytes)
/css/variables.css (gzip) 1/1 (1156 bytes)
/css/general.css 1/1 (3915 bytes)
/css/general.css (gzip) 1/1 (1522 bytes)
/css/print.css 1/1 (757 bytes)
/css/print.css (gzip) 1/1 (400 bytes)
/css/chrome.css 1/1 (9324 bytes)
/css/chrome.css (gzip) 1/1 (2351 bytes)
/searchindex.js 1/1 (1377 bytes)
/searchindex.js (gzip) 1/1 (444 bytes)
/clipboard.min.js 1/1 (10754 bytes)
/clipboard.min.js (gzip) 1/1 (3353 bytes)
/404.html 1/1 (8538 bytes)
/404.html (gzip) 1/1 (2206 bytes)
/print.html 1/1 (8615 bytes)
/print.html (gzip) 1/1 (2188 bytes)
/favicon.png 1/1 (5679 bytes)
/highlight.js 1/1 (135394 bytes)
/highlight.js (gzip) 1/1 (46066 bytes)
/tomorrow-night.css 1/1 (1741 bytes)
/tomorrow-night.css (gzip) 1/1 (676 bytes)
/chapter_1.html 1/1 (8420 bytes)
/chapter_1.html (gzip) 1/1 (2132 bytes)
/mymdbook/main.mo 1/1 (107 bytes)
/elasticlunr.min.js 1/1 (18051 bytes)
/elasticlunr.min.js (gzip) 1/1 (5510 bytes)
/fonts/SOURCE-CODE-PRO-LICENSE.txt 1/1 (4528 bytes)
/fonts/SOURCE-CODE-PRO-LICENSE.txt (gzip) 1/1 (2009 bytes)
/fonts/open-sans-v17-all-charsets-800italic.woff2 1/1 (40812 bytes)
/fonts/open-sans-v17-all-charsets-800.woff2 1/1 (44536 bytes)
/fonts/OPEN-SANS-LICENSE.txt 1/1 (11358 bytes)
/fonts/OPEN-SANS-LICENSE.txt (gzip) 1/1 (3972 bytes)
/fonts/open-sans-v17-all-charsets-regular.woff2 1/1 (43236 bytes)
/fonts/open-sans-v17-all-charsets-300.woff2 1/1 (44352 bytes)
/fonts/open-sans-v17-all-charsets-600italic.woff2 1/1 (42120 bytes)
/fonts/open-sans-v17-all-charsets-700italic.woff2 1/1 (40800 bytes)
/fonts/open-sans-v17-all-charsets-300italic.woff2 1/1 (40656 bytes)
/fonts/open-sans-v17-all-charsets-700.woff2 1/1 (44988 bytes)
/fonts/open-sans-v17-all-charsets-600.woff2 1/1 (44936 bytes)
/fonts/source-code-pro-v11-all-charsets-500.woff2 1/1 (59140 bytes)
/fonts/open-sans-v17-all-charsets-italic.woff2 1/1 (41076 bytes)
/fonts/fonts.css 1/1 (3620 bytes)
/fonts/fonts.css (gzip) 1/1 (568 bytes)
/book.js 1/1 (24328 bytes)
/book.js (gzip) 1/1 (5572 bytes)
/favicon.svg 1/1 (1835 bytes)
/searchindex.json 1/1 (1346 bytes)
Deployed canisters.
Navigate to http://rkp4c-7iaaa-aaaaa-aaaca-cai.localhost:8000/ (replacing the canister URL with the one that your console reported) and you should be able to see your mdbook! Huzzah!
Deploy your first mdBook to the production Internet Computer network
If you've gone through the steps required to create your cycles wallet and to top it up, deploying will be as easy as:
dfx deploy --network ic