Basic operation of dfinity (ICP) development-4

Dfinity Basic operation of development

install 、 Upgrade or remove software

Install the latest... Directly from the terminal

From the terminal shell Download and install ：

1. Open the terminal housing on the local computer .

   for example , stay macOS Open up Applications Folder , Then open the Utilities And double-click Terminal.

2. By running the following curl Command download and install SDK package ：

   sh -ci "$(curl -fsSL https://sdk.dfinity.org/install.sh)"
   

Install a specific version from the terminal

If you want to install a specific version , for example , Test against previous versions , You can modify the installation command to include a version .

To download and install a specific version from the terminal housing ：

1. Open the terminal housing on the local computer .

2. take DFX_VERSION The environment variable is set to be curl Command prefix installed DFINITY Canister SDK The version of the package .

   for example , To install 0.7.2 edition , You will run the following command ：

   DFX_VERSION=0.7.2 sh -ci "$(curl -fsSL https://sdk.dfinity.org/install.sh)"
   

Review license agreement

Before installing the command line interface executable and its dependencies on the local computer , The installation script prompts you to read and accept DFINITY Canister SDK license agreement dfx. You must type y And press Enter To continue with the installation .

Upon acceptance of the license agreement , The installation script will display information about the components installed on the local computer .

Installed components

DFINITY Canister SDK The installation script installs multiple components in the default location of the local computer . The following table describes the development environment components installed by the installation script ：

Component	Description	Default location
dfx	DFINITY execution command-line interface (CLI)	/usr/local/bin/dfx
moc	Motoko runtime compiler	~/.cache/dfinity/versions/<VERSION>/moc
replica	Internet Computer local network binary	~/.cache/dfinity/versions/<VERSION>/replica
uninstall.sh	Script to remove the DFINITY Canister SDK and all of its components	~/.cache/dfinity
versions	Cache directory that contains a subdirectory for each version of the DFINITY Canister SDK you install.	~/.cache/dfinity/versions

The core components in the versioning Directory

The ~/.cache/dfinity/versions Directory storage DFINITY Canister SDK One or more versioned subdirectories of . Each versioned subdirectory contains a specific version of DFINITY Canister SDK All directories and files required . for example , If you list the contents of the directory ,~/.cache/dfinity/versions/0.7.2 You will see the following core components ：

total 349192
drwxr-xr-x  17 pubs  staff       544 Mar 15 11:55 .
drwxr-xr-x   4 pubs  staff       128 Mar 25 14:36 ..
drwxr-xr-x  49 pubs  staff      1568 Mar 15 11:55 base
drwxr-xr-x  20 pubs  staff       640 Mar 15 11:55 bootstrap
-r-x------   1 pubs  staff  66253292 Mar 15 11:55 dfx
-r-x------   1 pubs  staff  10496256 Dec 31  1969 ic-ref
-r-x------   1 pubs  staff   5663644 Dec 31  1969 ic-starter
-r-x------   1 pubs  staff      9604 Dec 31  1969 libcharset.1.0.0.dylib
-r-x------   1 pubs  staff     38220 Dec 31  1969 libffi.7.dylib
-r-x------   1 pubs  staff    668300 Dec 31  1969 libgmp.10.dylib
-r-x------   1 pubs  staff    958248 Dec 31  1969 libiconv.2.4.0.dylib
-r-x------   1 pubs  staff      4200 Dec 31  1969 libiconv.dylib
-r-x------   1 pubs  staff     96900 Dec 31  1969 libz.1.2.11.dylib
-r-x------   1 pubs  staff  15417684 Dec 31  1969 mo-doc
-r-x------   1 pubs  staff  14634020 Dec 31  1969 mo-ide
-r-x------   1 pubs  staff  15111508 Dec 31  1969 moc
-r-x------   1 pubs  staff  49404128 Dec 31  1969 replica

Motoko Basic catalog

take base stay DFINITY Containers SDK The version subdirectory directory of contains the meta sub basic library module and the version DFINITY Containers SDK compatible . because Motoko The basic library is developing rapidly , You should only use the... That you installed DFINITY Canister SDK Basic modules packaged with versions .

Boot directory

The bootstrap The directory contains deprecated Web Server code . from 0.7.0 Version start , The proxy can call HTTP Middleware server instead of bootstrap Code . This change enables the container to respond directly HTTP request , And it's more like the traditional one based on Web Applications for .

Upgrade to the latest version

If you have a new version after your initial installation DFINITY Canister SDK Available for download , You should install an updated version as early as possible , To get the latest fixes and enhancements as soon as possible . You can use the dfx upgrade The command compares the currently installed version with the latest version available for download . If there is a newer version dfx You can use , The dfx upgrade The command will automatically download and install the latest version .

Please note that , Before installing the new version , You do not need to uninstall the software . however , If you want to perform a fresh installation instead of an upgrade , You can start by Delete Software The instructions in Uninstall software , Then rerun the download and install commands .

Delete Software

install DFINITY Canister SDK when , The installation script places the required binaries in a local directory and creates a cache . You can run uninstall be located .cache The script in the folder is deleted from the local computer SDK Binaries and caches .

for example ：

~/.cache/dfinity/uninstall.sh Copy 

If you uninstall because you want to reinstall a clean version of dfx, You can run the following command ：

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

Design application

When you come up with an idea for an application , You will make many design decisions about how to build and organize your project . Most of these design decisions are related to whether you are on traditional cloud services or Internet There is nothing to do with deploying applications on the computer . however , If you are going to be in Internet Deploy on the computer , When planning the implementation of the application , You should pay special attention to some design decisions

This section is in progress and incomplete . With the build in Internet Best practices and design patterns for applications running on computers continue to evolve , The information contained herein will also evolve and change accordingly .

Single or multiple container architectures

When designing an application , The first decision you might want to consider is whether it should be encapsulated in a single container or composed of multiple containers .

for example , If you are writing a simple service without a front end , You may want to use a single container to simplify project management and maintenance and focus on adding functionality . If your application has both front-end assets and back-end business logic , Then your project may contain at least two containers , A container for managing user interface components , Another container is used for the back-end services provided by the application .

In planning , You can also consider putting some common reusable services in their own containers , So that they can be imported and invoked from other more specialized containers , Or provide it to other developers . The LinkedUp The example application illustrates this approach by splitting a professional service application into two containers . stay LinkedUp Example , The function of building social connections is connectd Defined in container , And separate from the functions defined in the container for setting professional data linkedup. It's easy to imagine using a third container to extend an application , For example, schedule events based on profile properties or shared connections .

Separate participants from types and utilities

When planning the architecture for your project , A common practice is to put the code of the main role in a file , With separate attached files , It is used to define the types used by your program and the practical functions that do not require roles .

for example , You can set the application's back-end logic to include the following files ：

• Main.mo perhaps main.rs Use functions that require participants to send queries and update calls .
• Util.mo or util.rs With auxiliary functions that can be imported for use by actors .
• Types.mo or types.rs All data type definitions with your application .

Call... Using a query

Queries return results faster than update calls . therefore , Explicitly mark the function as aquery Is an effective strategy to improve application performance . In the planning and design phase , You should consider how best to use query calls instead of functions that can execute queries or updates .

This is a good general rule , It can be widely used in most categories of applications . however , You should also consider the security and performance tradeoffs of queries that do not pass consensus . For some applications , This trade-off may be appropriate . for example , If you are developing a blog platform , Queries that retrieve articles matching tags may not guarantee consensus to ensure that most nodes agree on the results . however , If your application is retrieving sensitive information （ Such as financial data ）, You may need more assurance than the results provided by the basic query .

As an alternative to the basic query , Internet computers also support Authentication query . An authenticated query enables you to receive Authenticated A trusted Respond to . Using certified queries is an advanced technology , Not covered in tutorials or other developer centric documentation , But you can see how Authentication works and configure the program to return authenticated data in response to The interface specification .

Data storage and retrieval

For many applications , The database is mainly used to provide long-term storage of records that can be effectively retrieved using one or more key fields . stay Internet On computer , This use case is usually solved through data structures such as hash tables .Internet Computers are not traditional databases , Instead, it enables you to use Stable memory To handle long-term data storage （ It is often called orthogonal persistence ） And use Query call To retrieve data . Although this approach is applicable to most applications and simple key value database requests , But it doesn't fully simulate a relational database .

Management project

You can modify the for each project dfx.json Configuration file to modify some key settings of a single project . You can use the dfx config The command changes these settings programmatically , It's fine too dfx.json Edit the file directly and manually .

How to change the source directory

When using the dfx build Command before compiling source code for the project , You may want to check the default location for storing program source code . By default , The name you use to create a new project is a data intelligence contract container （canister_name） And an asset container （canister_name_assets） The name of , And the program source code should be in this src/canister_name Directory . Again , The default location of the front-end source code is src/canister_name_assets/src Directory , Front end output is located at dist/canister_name_assets Directory .

however , Depending on the complexity and architecture of the application , You may want to modify the program source code 、 The default location for front-end source code or front-end output .

for example , For a simple program , You might want to eliminate a directory level and put the source code in that src Directory ：

 "main": "src/main.mo",

For more complex applications , You may want to use a multi tiered directory structure ：

"canisters": {
  "profiles": {
    "main": "src/profiles/utils/main.mo"
  },
  "events": {
    "main": "src/events/calendar/main.mo"
  },
  "media": {
    "main": "src/events/reports/main.mo"
  }
}

How to modify the default settings of the source code directory , Please make sure dfx.json The settings in the configuration file match the directory location on the file system

How to modify the main program file name

When using the dfx build Command before compiling source code for the project , You should verify the location and file name used for the program source code .

for example , If you want to build a smart contract container for your program and factorial The source code of the program is located in in src/math/factorial.mo, Then make sure that... In the configuration file section main The setting specifies the correct path canisters.

for example ：

"main": "src/math/factorial.mo",

please remember , Changing the configuration settings of the program file name will only affect dfx build Command to find the location of the source code to compile . Making changes in the configuration file does not rename any files or directories on the file system . If you change the path of the main program file or the name of the file itself , Be sure to change the name and location in the project directory .

How to modify the position of the front section of a service application

You can modify dfx.json Local network settings in the configuration file to change the default host name and port number serving the application front end .

for example , You can modify bind Set to change the local network IP Address ：

"networks": {
  "local": {
    "bind": "192.168.47.1:8000",
    "type": "ephemeral"
  }
}

Develop in different languages

Most of the examples in this guide use Motoko—— A device specially designed for Internet The programming language of a computer . however , You may be able to program in any language , Compiled into WebAssembly To deploy in Internet Applications running on computers . This section provides some information on how to write programs in different languages and how to Internet Advanced instructions for deploying them on your computer .

Rust

You can use the Cargo And compile your program to use WebAssembly Create as target output Rust The project is based on Internet Run on computer .

This section provides an overview of the Rust Key steps involved in deploying the program as a smart contract container on Internet computers . however , You should pay attention to , The steps described here illustrate only one approach . Other implementations are also possible .

Please note that ,Rust Container development kit (Rust CDK) Provides some shortcuts , It's easier to write query and update calling functions , And contains several Example To help you get started building on Rust Project , But you can also do it for Internet Developing applications does not use Rust CDK The computer .

Create project

Because most Rust Programmers use Cargo To handle build and package management tasks —— Such as downloading and compiling the libraries your program depends on —— Your first step is to use Cargo The command line interface creates a new Rust project .

perhaps , You can use DFINITY Canister Software development kit (SDK) instead of Cargo Create a new project , But use Cargo Creating a project represents creating Rust Typical workflow of the project .

Create a new Rust project ：

1. If you haven't opened , Please open a terminal shell on the local computer .

2. Verify that you have installed... By running the following command Cargo：

   cargo --version
   

3. Change to for Internet Computers or Rust Folder for the sample project .

4. Create a new project by running a command similar to the following ：

   cargo new my_rust_program
   

   This command creates a my_rust_program With default Cargo.toml The new directory of the file and a with the default file src Catalog main.rs.

5. Switch to your project directory by running the following command ：

   cd my_rust_program
   

   If you list the contents of this directory , You will see that it contains only Cargo.toml Document and src Catalog . To compile this project in Internet Run on computer , You need some additional files .

modify Cargo The configuration file

The Cargo.toml File for each Rust The package provides a detailed list . The listing contains the section that specifies the configuration details of the package . In preparation for Rust The project in Internet Run on computer , We will copy the default Cargo.toml file , Then modify some configuration details of the project .

To be modified Cargo.toml file ：

1. pwd If necessary, , Please check whether you are in the root directory of the project by running the command .

2. By running the following command, the default Cargo.toml File copy to src Catalog ：

   cp Cargo.toml src/Cargo.toml
   

   stay Internet Projects running on a computer usually use a project level Cargo.toml File to set the workspace for the container members of the project , And use Cargo.toml A second file in the source directory to configure the settings for each container .

3. Cargo.toml Open the file that is the root of the project in a text editor .

   By default , The file contains [package] and [dependencies] part .

4. Will be [package] Part replaced with [workspace] Parts similar to the following ：

   [workspace]
   members = [
       "src/my_rust_program",
   ]
   

   of [workspace] Part and [workspace] Key information , see also work area . You can find information about Cargo.toml Information about other parts and keys configured in the file , see also List format .

5. Delete the [dependencies] part .

6. Save your changes and close the file to continue .

7. src/Cargo.toml Open the file in a text editor .

8. Add one [lib] The part containing the main source code path , Similar to ：

   [lib]
   path = "main.rs"
   

9. [dependencies] Update this section with any package dependencies .

10. Save your changes and close the file to continue .

Add container profile

When you use DFINITY Canister SDK When creating a new project , The dfx new The command will automatically default to dfx.json Add the configuration file to the project directory . Because we use Cargo Created Rust project , So you need to manually create this file in your project directory .

add to dfx.json The configuration file ：

1. pwd If necessary, , Please check whether you are still in the project directory by running the command .

2. dfx.json Create a new configuration file in the root directory of your project .

3. open in text editor dfx.json file .

4. Will have settings similar to version and canisters Key added to dfx.json In file ：

   {
         
     "version": 1,
     "canisters": {
         
       "my_rust_program": {
         
         "type": "custom",
         "candid": "src/my_rust_program.did",
         "wasm": "target/wasm32-unknown-unknown/debug/my_rust_program.wasm",
         "build": "cargo build --target wasm32-unknown-unknown --package my_rust_program"
       }
     }
   }
   

   Let's take a closer look at these settings .

   • The version Settings are used to identify the software version used to create the project .
   • The canisters Section specifies the name of the project container . under these circumstances , There is only one container , be known as my_rust_program.
   • The type The key is set to custom, Because this container is not currently recognized （ One motoko or assets） Container type .
   • The candid The key specifies the name and location of the straightforward interface description file for this project .
   • The wasm Key , Produced by WebAssembly file cargo build command .
   • The build Key assignment cargo Command is used to compile the output .

   These are the minimum settings required . When you build more complex programs , You may need to be in Cargo.toml file 、dfx.json File or both files contain additional configuration details .

5. Save your changes and close the file to continue .

establish Candid Interface description file

except dfx.json Outside the configuration file , You also need to have a Candid Interface description file —— for example ,my_rust_program.did—— Map the input parameters and return value formats of the program to their Candid A language independent representation in .

add to Candid Interface description file ：

1. pwd If necessary, , Please check whether you are still in the project directory by running the command .

2. Create a new candid interface description file , for example my_rust_program.did, - stay src Your project directory .

3. open in text editor Candid Interface description file , And add a description for each function defined by the program .

   for example , If my_rust_program It's a simple procedure , The increment counter uses increment,read and write function , The my_rust_program.did The file might look like this ：

   service : {
     "increment": () -> ();
     "read": () -> (nat) query;
     "write": (nat) -> ();
   }
   

4. Save your changes and close the file to continue .

Modify the default program

When creating a new project , project src The directory contains a template main.rs file , It includes “Hello, World!” Program .

Modify the template source code ：

1. src/main.rs Open the template file in a text editor and delete the existing content .

2. Write in Internet Programs deployed on the computer .

   When writing a program , Remember that there are two types of calls —— Update call and query call —— And the update function uses asynchronous messaging .

3. Save your changes and close main.rs file .

Connect to the network and deploy

Before deploying and testing the program , You need to do the following ：

• Connect to Internet computer network , Can run locally in your development environment , You can also run it remotely on a subnet that you can access .
• Register a network specific identifier for the application
• Use WebAssembly Target output compiler for .

Because of you dfx.json Use cargo build Compiled into WebAssembly The custom file is configured with the command of , So you can use dfx Command line interface and standard workflow to perform all remaining steps .

Build and deploy programs locally ：

1. pwd If necessary, , Please check whether you are still in the project directory by running the command .

2. Open a new terminal window or tab on the local computer , Then navigate to your project directory .

   for example , If in macOS Run the terminal on , You can do any of the following ：

   • single click Shell, And then choose New Tab Open a new terminal in the current working directory .
   • single click Shell And select New Window,cd ~/ic-projects/location_hello If your location_hello The project in ic-projects In the working folder , Run in the new terminal .

   You should now open both terminals , And make your project directory your current working directory **.

3. Start on the local computer by running the following command Internet computer network ：

   dfx start
   

   Depending on your platform and local security settings , You may see a warning displayed . If you are prompted to allow or deny incoming network connections , Please click on the allow .

4. Keep the terminal displaying network operation open , And switch the focus to the original terminal where you created the project .

5. Register a unique container identifier for the application by running the following command ：

   dfx canister create --all
   

6. Build the program by running the following command ：

   dfx build
   

7. Deploy the program on the local network by running the following command ：

   dfx canister install --all
   

8. Test the functions in the program from the command line or browser .

C

because Internet Computer Support compiling to standard WebAssembly Module application , So you can use standard compilers and toolchains to C、C++、Objective-C and Objective-C++ Programming languages and Clang Compiler and other languages to build applications .

To illustrate how to use C The program written is migrated to Internet Run on computer , Let's take a look Example Simple in the repository reverse.c Program . The program contains a function named , Used to invert strings in place .reverse.c``go

Set up the development environment

To put reverse.c The program is compiled into WebAssembly, You need to clang Install compilers and standard libraries . You can clang Check that you have installed... On your local computer by running the following command ：

clang --version

If clang already installed , This command displays information similar to the following ：

 Jingle version  10.0.0
 The goal is ：x86_64-apple-darwin19.5.0
 Threading model ：posix
 The installation directory ：/usr/local/opt/llvm/bin

If the command does not return version information , please clang Install... Before continuing . Installation steps clang It varies depending on the operating system you use . for example , stay Debian Linux On , Run the following command ：

sudo apt-get install clang lld gcc-multilib

stay macOS On , You can clang Through installation Developer Command-Line Tools Or use Homebrew install LLVM Installation . for example , If clang Not installed , Then run the following command ：

brew install llvm

Compile the program into WebAssembly

You can compile C Program as WebAssembly Module operation , The method is to compile using clang, And then use link wasm-ld. according to clang The operating system and version you are using , You may use different versions of WebAssembly The linker , for example wasm-ld stay macOS or wasm-ld-8Debian On .

stay macOS Compiled as WebAssembly：

1. By running the following clang Command to compile the program ：

   clang --target=wasm32 -c -O3 reverse.c
   

2. By running the following wasm-ld Command to run the linker to create WebAssembly modular ：

   wasm-ld --no-entry --export-dynamic --allow-undefined reverse.o -o reverse.wasm
   

Create minimum profile

Next , You need to prepare a simple configuration file , The document will reverse The program binary is identified as a file that can be installed in Internet The bag on the computer and a build Catalog , So that you can use dfx The command line interface installs and runs packages as containers .

Prepare configuration files and build directories ：

1. dfx.json Create a file with canisters Key file ：

   echo '{"canisters":{"reverse":{"main":"reverse"}}}' > dfx.json
   

2. build Create a directory for the program by running the following command ：

   mkdir build
   

3. reverse Create a directory for the program by running the following command ：

   mkdir build/reverse
   

4. build/reverse By running the following command WebAssembly Copy the module to the new directory ：

   cp reverse.wasm build/reverse/
   

Create a minimal interface description file

In the standard development workflow , Run the dfx build The order will be in canisters Create multiple files in the output directory , Include one or more Candid Interface description ( .did) file , These file handlers match the types of data types associated with program functions .

More about the syntax for different data types , see also Candid guide and Candid standard .

To create... For this program Candid Interface description file ：

1. stay build You are reverse.c Open a terminal in the directory created by the program source

2. Create a file called reverse.did.

3. add to go Description of function .

   for example ：

   service : {
     "go": (text) -> (text);
   }
   

4. Save your changes and close the file to continue .

Deploy and test the program

Before deploying and testing the program , You need to do the following ：

• Connect to Internet computer network , Can run locally in your development environment , You can also run it remotely on a subnet that you can access .
• Register a network specific identifier for the application .

Deploy and test applications locally ：

1. Open a new terminal window or tab on the local computer .

   for example , If in macOS Run the terminal on , Please click on the Shell, And then choose New tab Open a new terminal in the current working directory .

2. By running the following command , Start on the local computer in the second terminal Internet computer network ：

   dfx start
   

3. reverse Register a unique container identifier for the application by running the following command ：

   dfx canister create --all
   

4. Deploy the default program on the local network by running the following command ：

   dfx canister install --all
   

5. go Call the function in the program by running the following command ：

   dfx canister call reverse go reward
   ("drawer")
   

You can go to Example Find... In the repository C Other aspects of the program Example .

Build the front end

These tutorials show you some basic ways to build a front-end user interface for your project . for example , The tutorial demonstrates ：

• Use Candid As a basic interface to expose and test functions in the container .
• Use original HTML and JavaScript To show a simple HTML Entry page .
• Use React And compiled JavaScript take HTML Attributes and elements are embedded directly in the page .
• Use React and TypeScript Import from an external file CSS attribute .

This section details the default front-end template 、 Front end configuration options and building the user interface for your project using other frameworks .

How to use the default template

As you may have noticed in the tutorial , The project includes templates index.js and webpack.config.js file .

By default , The index.js File explicit instantiation HTTP Instance of agent . The agent is a user oriented front end and Internet The interaction between computers provides an interface . After creating the agent , The index.js The file will be project dfx.json The container defined in the file constructs a participant .

If you look at index.js Code in file , You will see that it performs these steps using the following code block ：

import {
     Actor, HttpAgent } from '@dfinity/agent';
import {
     idlFactory as hello_idl, canisterId as hello_id } from 'dfx-generated/hello';

const agent = new HttpAgent();
const hello = Actor.createActor(hello_idl, {
     agent, canisterId: hello_id });

After creating agents and participants for the project , The index.js The file is the document object model for the application (DOM) and HTML The interaction of JavaScript A placeholder is provided .

modify webpack To configure

because webpack Is a popular one 、 Highly configurable module packer , Used based on JavaScript Applications for , The new project creates a default webpack.config.js file , You can easily add specific modules —— for example react and markdown—— You want to use .

If you view the template webpack.config.js Code in file , You will see it for the project dfx.json Container construction alias defined in the file . then , When the current end is imported as a module , Aliases can be used to reference containers .

You can see these steps in the following code block ：

// List of all aliases for canisters. This creates the module alias for
// the `import ... from "dfx-generated/canisters/xyz"` where xyz is the name of a
// canister.
const aliases = Object.entries(dfxJson.canisters).reduce(
  (acc, [name, _value]) => {
    
    // Get the network name, or `local` by default.
    const networkName = process.env["DFX_NETWORK"] || "local";
    const outputRoot = path.join(
      __dirname,
      ".dfx",
      networkName,
      "canisters",
      name
    );

    return {
    
      ...acc,
      ["dfx-generated/" + name]: path.join(outputRoot, name + ".js"),
    };
  },
  {
    }
);

I / O configuration

After creating the container alias , Templates webpack.config.js The file will generate a for the front end webpack To configure , And add the generated files to the output directory of the project directory .

In many cases , You can webpack.config.js Use the default file as is , No changes needed , You can also add plug-ins 、 Modules and other custom configurations to meet your needs . You are right. webpack.config.js The specific changes you make to the configuration depend largely on the other tools and frameworks you use .

for example , If you have tried Custom front end or Add style sheets Front end tutorial , You may have modified the following sections to use React

JavaScript：

    module: {
    
      rules: [
        {
     test: /\.(ts|tsx|jsx)$/, loader: "ts-loader" },
        {
     test: /\.css$/, use: ['style-loader','css-loader'] }
      ]
    },
    plugins: [
      new HtmlWebpackPlugin({
    
        template: path.join(__dirname, info.frontend.entrypoint),
        filename: 'index.html',
        chunks: ['index'],
      })
    ],
  };
}

Ensure that nodes are available in the project

Because the project depends on webpack Provides a framework for the default front end , So you must have node.js It is installed in your development environment and can be accessed in the project directory .

• If you want to use the default webpack Develop your project with configuration and container aliases , You can assets from dfx.json Delete the container from the file or build your project with a specific container name . for example , You can choose to build only by running the following command hello Program , Without front-end assets ：

  dfx  Build Hello 
  

• If you use the default webpack Configure and run dfx build Failure , You should try npm install Run in the project directory and rerun dfx build.

• If npm install Running in the project directory does not solve the problem , You should check webpack.config.js Whether there is syntax error in the configuration of the file .

stay React Other modules are used in the framework

Example Several tutorials and sample projects in the repository illustrate how to use this npm install Command addition React modular . You can use these modules to build user interface components to be used in your project . for example , You can run the following command to install react-router modular ：

npm install --save react react-router-dom

then , You can use this module to build navigation components similar to the following ：

import React from 'react';
import {
     NavLink } from 'react-router-dom';

const Navigation = () => {
    
  return (
    <nav className="main-nav">
      <ul>
        <li><NavLink to="/myphotos">Remember</NavLink></li>
        <li><NavLink to="/myvids">Watch</NavLink></li>
        <li><NavLink to="/audio">Listen</NavLink></li>
        <li><NavLink to="/articles">Read</NavLink></li>
        <li><NavLink to="/contribute">Write</NavLink></li>
      </ul>
    </nav>
  );
}

export default Navigation;

Use webpack-dev-server Iterate faster

You can use some simple shortcuts to speed up iterations in the development environment . for example , You can choose to build and deploy only specific containers , Instead of all the containers in the project .

If most of your changes are at the front of the application , One of the most effective ways to iterate faster is to install and configure webpack Development server .webpack Development server webpack-dev-server—— Provide right webpack Memory access to assets , Enables you to make changes and immediately see their reflection in the browser using live reload .

install and configure webpack-dev-server：

1. Create a new project and switch to your project directory .

2. webpack-dev-server By running the following command Install in the project directory ：

   npm install webpack-dev-server
   

3. webpack.config.js Open the project file in a text editor .

4. output stay webpack.config.js Add your network host name and port information after the file section .

   for example , If you use default host and port information for local development , The following should be added to webpack.config.js In file ：

   devServer: {
         
    proxy: {
         
      "/api": "http://localhost:8000",
    },
   },
   

5. Save your changes and close webpack.config.js File to continue .

6. package.json Open the project file in a text editor .

7. "build": "webpack" In the scripts Add a comma after the section .

8. "start": "webpack serve" In the scripts Add a new line to the section .

   for example ：

   "start": "webpack serve"
   

9. Save your changes and close package.json File to continue .

10. If necessary, , Start locally Internet Computer , Then deploy as usual , for example , By running dfx deploy command .

11. Start... By running the following command webpack Development server ：

    npm start
    

12. open Web Browser and use port 8080 Navigate to your application's asset container .

    for example ：

    http://localhost:8080/?canisterId=ryjl3-tyaaa-aaaaa-aaaba-cai
    

13. Open a new terminal window or tab and navigate to your project directory .

14. index.js Open the project file in a text editor and change the contents .

    for example , You can use JavaScript Add an element to the page ：

    document.body.onload = addElement;

    document.body.onload = addElement;
    
    function addElement () {
          
      // create a new div element
      const newDiv = document.createElement("div");
    
      // and give it some content
      const newContent = document.createTextNode("Test live page reloading!");
    
      // add the text node to the newly created div
      newDiv.appendChild(newContent);
    
      // add the newly created element and its content into the DOM
      const currentDiv = document.getElementById("div1");
      document.body.insertBefore(newDiv, currentDiv);
    }
    

15. Save pairs index.js Changes to documents , But keep the editor open to continue making changes .

16. Refresh the browser or wait for it to refresh itself to see your changes .

    When you finish the front end of the project , You can press Control-C stop it webpack Development server .

Manage containers

If you have followed course In section course Or through Example Clone the sample in the repository to try DFINITY Container software development kit (SDK) , So you are already familiar with how to build and deploy your program as Containers . This section provides additional information about the container lifecycle and how to manage containers .

Register container identifier

According to your preferred development workflow , You can register a unique container identifier before or after you are ready to compile the program . for example , If you want to keep a unique identifier for your program on the subnet before writing any code , You can run this dfx canister create Command to implement . This command actually creates an empty container placeholder , You can install the code into it later .

To register a unique identifier for a container ：

1. Open a new terminal window or tab on the local computer .

2. By running a command similar to the following , Create a new project for the container you plan to create ：

   dfx new YOUR-PROJECT-NAME
   

   Please note that , By default , The name you use for the project is also used as the container name .

3. Switch to your new project directory .

4. open dfx.json Configuration file and for the Internet The computer network provider sets the host and port .

   If you use the local host as Internet Computer network providers , You can skip this step .

   If you want to create identifiers for any other containers you think you need before compiling the code , You can also choose to change the name of the container or add container settings to the configuration file .

5. If necessary, , Start... By running the following command Internet computer network ：

   dfx start --background
   

   in the majority of cases , Only if you are running locally Internet This step is required only when the computer is connected to the network .

   If you are registering a container to run on a remote network , You will include --network Command line options to perform tasks on this network .

6. dfx.json By running the following command , by Container registration unique identifier defined in ：

   dfx canister create --all
   

   This command creates .dfx/local Directory and canister_ids.json Add the file to this directory of the project .

Building containers using local identifiers

After writing the source code for the project , You need to compile it as WebAssembly modular , And then deploy it to the network as a container .

If you compile your project just for local debugging , You can generate a locally defined identifier for your project .

Generate locally defined identifiers ：

1. Create a project using configuration settings and program logic to meet your needs .

2. If necessary, , start-up Internet computer network .

   in the majority of cases , Only if you are running locally Internet This step is required only when the computer is connected to the network .

   If you are compiling containers to run on a remote network , You will include --network Command line options to perform tasks on this network .

3. dfx.json By running the following command , by The container defined in generates hard coded local identifiers ：

   dfx build --check
   

   Please note that , You must first register a unique container identifier to replace the locally defined identifier , Then we can go to Internet Deploy the project on the computer network .

stay Internet Deploy containers on the computer network

After compiling the program , You can install the compiled code to run locally in your development Internet On a computer network or remote network provider .

Container identifiers created in advance or during build determine where your code is installed during deployment .

First deployed in Internet On the computer network ：

1. Open a new terminal and navigate to your project directory .

2. If necessary, , start-up Internet computer network .

   in the majority of cases , Only if you are running locally Internet This step is required only when the computer is connected to the network .

   If you are installing containers on a remote network , You will include --network Command line options to perform tasks on this network .

3. Verify that you have container identifiers for all containers you want to deploy .

4. Deploy all containers by running the following command ：

   dfx canister install --all
   

Find container identifier

All containers have unique 、 Network specific identifiers . You often need to use these identifiers to interact with containers . for example , If you want to access the application's front-end container or use Candid Web Interface and service interaction , You must specify the appropriate container identifier .

Because identifiers are network specific , The files used to store information are located in different directories . for example , The identifier of the locally deployed container is located in the project .dfx/local/canister_ids.json In file .

You can run this dfx canister id Command to find the container identifier for any particular container . for example , To find out lookup Container identifier of the container deployed on the local network , You can run the following command ：

dfx canister id lookup

To find in ic The container identifier of the same container deployed on the network specified by the alias , You will run the following command ：

dfx canister --network=ic id lookup

For the existing canister Add wallet

When doing local development , A new project will automatically create a default wallet for you and the containers in that project (canister) Use it together . If you want to add a wallet for the container sub item you created earlier , You can force dfx Generate one through several manual steps .

Add a wallet to use with an existing container ：

1. Open the terminal and navigate to your project directory .

2. If necessary, , Stop the local... By running the following command Internet computer network ：

   dfx stop
   

3. Delete .dfx Catalog .

4. From... By running the following command Internet The computer network starts ：

   dfx start --clean
   

Reinstall a canister

In the development cycle , You may want to install , Then replace it when debugging and improving the program .

under these circumstances , You may want to keep the registered container identifier , But no container code or state is preserved . for example , Your container may only have test data that you do not want to keep , Or you may have decided to change the program completely but want to reinstall it under the container identifier used to install the previous program .

To be in Internet Reinstall on the computer network ：

1. Open a new terminal and navigate to your project directory .

2. If necessary, , start-up Internet computer network .

   in the majority of cases , Only if you are running locally Internet This step is required only when the computer is connected to the network .

   If you reinstall the container on a remote network , You will include --network Command line options to perform tasks on this network .

3. Verify that you have container identifiers for all containers you want to redeploy .

4. Redeploy all containers by running the following command ：

   dfx canister install --all --mode reinstall
   

Please note that , You can use the reinstall Pattern replaces any container , Regardless of whether the container has a code or state associated with it .

Set up identity to own canister

in the majority of cases ,default The system will run this for the first time dfx canister create Command automatically creates a user identity for you . This default identity consists of a public and private key pair generated for your local user account . Usually , this default Identity is also the default owner of all projects you create and all containers you deploy . however , You can proactively create and use your choice of default Identity to avoid using user identity .

for example , The following scenario illustrates creating a registered_owner identity , Then use that identity to register 、 structure 、 Deploy and invoke pubs project .

To set the identity for the project ：

1. Create a new project by running the following command ：

   dfx new pubs
   

2. Switch to the project directory by running the following command ：

   cd pubs
   

3. Start locally in the background by running the following command Internet computer network ：

   dfx start --background
   

4. registered_owner Create a new identity by running the following command ：

   dfx identity new registered_owner
   

5. registered_owner Set the active user context to use this identity by running the following command ：

   dfx identity use registered_owner
   

6. Register the project by running the following command 、 Build and deploy containers ：

   dfx canister create --all
   dfx build --all
   dfx canister install --all
   

   These commands use registered_owner Identity running , Make the user the owner of the deployed container .

7. greet Call this function by running the following command to verify that the deployment was successful ：

   dfx canister call pubs greet '("Sam")'
   

Manage the running state of the container

stay Internet After the container is deployed on the computer , It can start receiving and processing requests from users and other containers . Containers that can be used to send requests and receive replies are considered to be in function state .

Although containers are usually running by default , But in some cases , You may want to temporarily or permanently stop the container . for example , You may want to stop the container before upgrading it . Stopping the container helps ensure that any messages that are in progress and need to be completed or rolled back are processed correctly . As a prerequisite for deleting containers , You may also want to stop the container to clean up its message queue .

You can run dfx canister status Command to check the current state of all containers or specified containers . for example , To view local Internet Status of all containers running on the computer network , You can run the following command ：

dfx canister status --all

If the container is currently running , This command will return output similar to the following ：

Canister status_check's status is Running.
Canister status_check_assets's status is Running.

You can run dfx canister stop Command to stop the currently running container .

dfx canister stop --all

This command displays output similar to ：

Stopping code for canister status_check, with canister_id 75hes-oqbaa-aaaaa-aaaaa-aaaaa-aaaaa-aaaaa-q
Stopping code for canister status_check_assets, with canister_id cxeji-wacaa-aaaaa-aaaaa-aaaaa-aaaaa-aaaaa-q

If you want to rerun this dfx canister status command , You may see Stopped Indicates the status or... Of no pending messages to process Stopping Indicates the status of a message being transmitted that needs to be processed .

To restart the container （ for example , After the container is upgraded successfully ）, You can run this dfx canister start command . for example , To restart locally Internet All containers running on the computer network , You will run the following command ：

dfx canister start --all

This command displays output similar to ：

Starting code for canister status_check, with canister_id 75hes-oqbaa-aaaaa-aaaaa-aaaaa-aaaaa-aaaaa-q
Starting code for canister status_check_assets, with canister_id cxeji-wacaa-aaaaa-aaaaa-aaaaa-aaaaa-aaaaa-q

Upgrade one canister

Unlike container substitution that preserves container identifiers but does not preserve state , Container upgrade enables you to preserve the state of deployed containers and change code .

for example , Suppose you have an application that manages professional data and social relationships . If you want to add new features to your application , You need to be able to update the container code without losing any previously stored data . Container upgrade enables you to update existing container identifiers with program changes , Without losing program status .

To upgrade Internet Containers on computer networks ：

1. Open a new terminal and navigate to your project directory .

2. If necessary, , start-up Internet computer network .

   in the majority of cases , Only if you are running locally Internet This step is required only when the computer is connected to the network .

   If you upgrade the container on a remote network , You will include --network Command line options to perform tasks on this network .

3. Verify that you have container identifiers for all containers you want to upgrade .

   Please note that , Your program must pass stable Use keywords in variable declarations to identify the variables for which you want to keep state .

   For more information about declaring stable variables , see also Motoko Programming language guide .

4. Upgrade all containers by running the following command ：

   dfx canister install --all --mode upgrade
   

Delete container

If you want to permanently delete a given Internet A specific container or all containers for a specific item on a computer network , You can run this dfx canister delete Command to implement .

Deleting a container will delete the container from Internet Remove container identifier from computer network 、 Code and status . however , Before deleting the container , You must first stop the container to clear any pending message requests or replies .

To delete locally Internet All containers for projects running on the computer network ：

1. Open a new terminal and navigate to your project directory .

2. If necessary, , start-up Internet computer network .

   in the majority of cases , Only if you are running locally Internet This step is required only when the computer is connected to the network .

   If you want to delete a container on a remote network , You will include --network Command line options to perform tasks on this network .

3. Check the local by running the following command Internet Status of the project container running on the computer network ：

   dfx canister status --all
   

4. Stop all project containers by running the following command ：

   dfx canister stop --all
   

5. Delete all project containers by running the following command ：

   dfx canister delete --all
   

Use default cycles wallet

just as Token and cycle in question ,ICP Tokens can be converted to cycle To power the vessel operation . Cycle provides a basically stable value proposition , Represents the communication consumed by the application 、 Calculate and store operating costs . for example , The cycle is reflected in Internet The physical hardware required for applications running on the computer 、 Rack space 、 energy 、 The actual cost of storage and network bandwidth .

And ICP Tokens are different , The period is only associated with the container , Not associated with the user or developer principal . Because only containers need and consume cycles —— Perform actions and pay for the resources they use —— Users and developers use a method called Cycle wallet A special type of container to manage the allocation and ownership of cycles . As a result of the circulation wallet saves the execution operation （ For example, create a new container ） Required period , Therefore, by default, the container identifier of the circular wallet is used instead of your user principal to perform these operations .

For local development purposes ,DFINITY Canister SDK A default circular wallet will be automatically created for you in each project , And most of the operations performed with the circular wallet are done behind the scenes . for example ,cycles The wallet registers the container identifier on your behalf and deploys the container on your local network .

however , In the production environment , You usually need to specify the registration cycle and move it to a new container , Appoint a settlor who can act as custodian , And manage the trustor with the ownership . You can use it in Web The default circular wallet application running in the browser performs some of these tasks . Depending on what you want to do , You can also go through dfx wallet Run commands in the terminal or directly call methods in the default cycle wallet container to perform these cycle and container management tasks .

however , You should remember , Yes cycles wallet canister Is associated with the currently selected user identity cycles wallet Identifier . According to the identity you currently select and whether the trustee associated with the identity has been added as the controller or custodian of the wallet , You may see different results or be denied access to certain methods .

To check your current identity , Please run the following command ：

dfx identity whoami

The role of controller and custodian

You can assign a user principal or container identifier to controller or Custodian role .

nail controller The role assigned to the controller can perform privileged tasks , Including the following most superior functions and a main body ：

• Add and remove other principals as controllers .
• Authorize and cancel the authorization of other principals as custodians .
• Add entries to the cycle wallet address book .
• Access cycle wallet balances and all other wallet related information .
• Send cycles to other containers .
• Receive cycles from other containers .
• Act as... When calling other containers “ Message caller ” The main body .
• Create containers and extra cycle wallets .
• Rename cycle wallet .

Assigned to Custodian Role delegates can only perform a subset of periodic wallet management tasks , Including the following ：

• Access cycle wallet balances and all other wallet related information .
• Send cycles to other containers .
• Receive cycles from other containers .
• Act as... When calling other containers “ Message caller ” The main body .
• Create a container .

Check cycle balance

If you are doing local development , When you use the register a new container ID to create your cycle wallet dfx canister create Or when you register , Build and deploy a container dfx deploy.

If you are in Internet Deploy on the computer , You usually do this by putting ICP Token conversion to cycle 、 Transfer cycle to new container identifier and use default cycle Wallet WebAssembly modular (WASM) Update container to create cycle wallet .

There is one on the local or remote network cycles Behind the wallet , You can use dfx wallet balance Order or wallet_balance Method to view the current cycle balance .

Check your cycle balance during local development

If you are developing locally , You can use the dfx wallet balance The command checks the current cycle balance item by item .

To check the cycle balance in the local project ：

1. Open the terminal and navigate to the root directory of the project .

2. Start locally by running the following command Internet Computer ：

   dfx start --background
   

3. By running the following command , Displays the cycle balance in the cycle wallet associated with the currently selected identity ：

   dfx wallet balance
   

   This command displays output similar to the following ：

   78000000000000 cycles.
   

Check the cycle balance on the Internet computer

If you deploy on the main Internet computer network cycles wallet , You can use the dfx wallet balance Command to view the current network cycles balance .

To be in Internet Check the cycle balance on the computer ：

1. Open the terminal and navigate to include dfx.json Directory of configuration files .

2. Check and by running the following command Internet Connection to the computer ：

   dfx ping ic
   

3. By running the following command , Displays the recurring balance in the recurring wallet associated with the currently selected identity ：

   dfx wallet --network ic balance
   

   This command displays output similar to the following ：

   67991783875995 cycles.
   

Call cycle wallet_balance Method

You can also. wallet_balance Call directly cycles wallet canister To view cycles balance . for example , If your client is h5aet-waaaa-aaaab-qaamq-cai Controller of cycle wallet , You can check the current period balance by running the following command ：

dfx canister --network ic call h5aet-waaaa-aaaab-qaamq-cai wallet_balance

The command uses Candid The format returns the balance as a field with an amount （ By hash 3_573_748_184 Express ） and 6,895,656,625,450 A record of the balance of periods , As shown below ：

(record { 3_573_748_184 = 6_895_656_625_450 })

Add controller

If you are the controller of the circular wallet , You can add other principal or container identifiers to the controller role . Adding a delegate to the controller role will also automatically add the delegate to the custodian role .

To add a controller to a circular wallet in a local project ：

1. Open the terminal and navigate to the root directory of the project .

2. Start locally by running the following command Internet Computer ：

   dfx start --backgrounddfx start --background
   

3. By running a command similar to the following , Displays the cycle balance in the cycle wallet associated with the currently selected identity ：

   dfx wallet add-controller <controller-principal-identifier>
   

   for example , You will run the following command to change the principal identifier b5quc-npdph-l6qp4-kur4u-oxljq-7uddl-vfdo6-x2uo5-6y4a6-4pt6v-7qe Indicates that the user is added as the controller of the local loop wallet ：

   dfx wallet add-controller b5quc-npdph-l6qp4-kur4u-oxljq-7uddl-vfdo6-x2uo5-6y4a6-4pt6v-7qe
   

   This command displays output similar to the following ：

   Added b5quc-npdph-l6qp4-kur4u-oxljq-7uddl-vfdo6-x2uo5-6y4a6-4pt6v-7qe as a controller.
   

List the current controller

You can use dfx wallet controllers Order or get_controllers Method lists the principals who have full control of the wallet container for the specified period .

To list the controllers of the circular wallet in the local project ：

1. Open the terminal and navigate to the root directory of the project .

2. Start locally by running the following command Internet Computer ：

   dfx start --background
   

3. By running the following command , List the principal identifiers that have full control over the circular wallet in the current project ：

   dfx wallet controllers
   

   This command displays the text representation of the body that controls the loop wallet , The output is similar to the following ：

   tsqwz-udeik-5migd-ehrev-pvoqv-szx2g-akh5s-fkyqc-zy6q7-snav6-uqe 
   b5quc-npdph-l6qp4-kur4u-oxljq-7uddl-vfdo6-x2uo5-4q6y4a6
   

Remove controller

You can use dfx wallet remove-controller Order or remove_controller Method to delete the principal as a controller .

To delete the controller of the circular wallet in the local project ：

1. Open the terminal and navigate to the root directory of the project .

2. Start locally by running the following command Internet Computer ：

   dfx start --background
   

3. By running a command similar to the following , Specify the principal identifier to remove from the controller role in the current project ：

   dfx wallet remove-controller b5quc-npdph-l6qp4-kur4u-oxljq-7uddl-vfdo6-x2uo5-6y4a6-4pt6v-7qe
   

   The command output is similar to the following ：

   Removed b5quc-npdph-l6qp4-kur4u-oxljq-7uddl-vfdo6-x2uo5-6y4a6-4pt6v-7qe as a controller.
   

List current custodians

You can use dfx wallet custodians Order or get_custodians Method returns the list of principals currently defined as the cycle wallet custodian .

List the custodians of the recurring wallets in the local project ：

1. Open the terminal and navigate to the root directory of the project .

2. Start locally by running the following command Internet Computer ：

   dfx start --background
   

3. By running the following command , List the principal identifiers in the current project that have the custodian role for the circular wallet ：

   dfx wallet custodians
   

   This command displays output similar to the following ：

   tsqwz-udeik-5migd-ehrev-pvoqv-szx2g-akh5s-fkyqc-zy6q7-snav6-uqe 
   b5quc-npdph-l6qp4-kur4u-oxljq-7uddl-vfdo6-x2uo5-4q6y4a6
   

Delete the authorization to the custodian

You can use dfx wallet deauthorize Order or deauthorize Method to delete the principal as the custodian of the cycle wallet . Delegating a principal that was previously added as a controller also automatically removes the principal from the controller role .

To delete the custodian of the circular wallet in the local project ：

1. Open the terminal and navigate to the root directory of the project .

2. Start locally by running the following command Internet Computer ：

   dfx start --background
   

3. By running a command similar to the following , Specify the principal identifier to remove from the custodian role in the current project ：

   dfx wallet deauthorize b5quc-npdph-l6qp4-kur4u-oxljq-7uddl-vfdo6-x2uo5-6y4a6-4pt6v-7qe
   

   The command output is similar to the following ：

   Deauthorized b5quc-npdph-l6qp4-kur4u-oxljq-7uddl-vfdo6-x2uo5-6y4a6-4pt6v-7qe as a custodian.
   

Send cycle to container

You can use dfx wallet send The wallet_send Method sends a specific number of loops to a specific container . please remember , The container you specify must be a cycle wallet or have wallet_receive Method of accepting cycle .

If you are already in Internet Computer A circular wallet is deployed on the main network , You can use this dfx wallet send Command sends a loop between containers running on the network .

To send a loop to at Internet Another container running on the computer ：

1. Open the terminal and navigate to include dfx.json Directory of configuration files .

2. Check and by running the following command Internet Connection to the computer ：

   dfx ping ic
   

3. Get the container identifier of the container to receive the cycle .

   for example , Run the following command to display and Internet Circular wallet identifier associated with the current user identity on the computer ：

   dfx identity --network ic get-wallet
   

   This command displays the circular wallet container identifier , The output is similar to the following ：

   gastn-uqaaa-aaaae-aaafq-cai
   

4. Send the loop to the container identifier by running a command similar to the following ：

   dfx wallet --network ic send <destination> <amount>
   

   for example ：

   dfx wallet --network ic send gastn-uqaaa-aaaae-aaafq-cai 10000000000
   

   If the transmission is successful , This command does not display any output .

5. Check the cycle wallet balance by running the following command to see the updated number of available cycles ：

   dfx wallet --network ic balance
   

   for example ：

   67991699387090 cycles.
   

List address book entries

You can use dfx wallet addresses Order or list_addresses Method lists the principal identifiers and roles that have been configured for the cycle wallet .

To view in Internet Address book entries for the circular wallet running on the computer ：

1. Open the terminal and navigate to include dfx.json Directory of configuration files .

2. Check and by running the following command Internet Connection to the computer ：

   dfx ping ic
   

3. Get the address book entry of the cycle wallet by running the following command ：

   dfx wallet --network ic addresses
   

   This command displays the controller and custodian of the circulating wallet , The output is similar to the following ：

   Id：tsqwz-udeik-5migd-ehrev-pvoqv-szx2g-akh5s-fkyqc-zy6q7-snav6-uqe, species ： Unknown , role ： controller , name ： Name not set .
   Id：ejta3-neil3-qek6c-i7rdw-sxreh-lypfe-v6hjg-6so7x-5ugze-3iohr-2qe, species ： Unknown , role ： Custodian , name ： Name not set .
   Id：b5quc-npdph-l6qp4-kur4u-oxljq-7uddl-vfdo6-x2uo5-6y4a6-4pt6v-7qe, species ： Unknown 
   

Other methods in the default wallet

The default circular wallet container includes not as dfx wallet Command exposes additional methods . Other methods support more advanced cycle management tasks , For example, creating new containers and managing events .

Create a new circular wallet

Use this wallet_create_wallet Method to create a new cycle wallet container with an initial cycle balance , And you can choose to have a specific principal as its controller . If you do not specify a control principal , The circular wallet used to create the new wallet will be the controller of the new wallet .

for example , You can run commands like the following to create a new wallet and specify a principal as the controller ：

dfx canister --network  call f3yw6-7qaaa-aaaab-qaabq-cai wallet_create_wallet '(record { cycles = 5000000000000 : nat64; controller = principal "vpqee-nujda-46rtu-4noo7-qnxmb-zqs7g-5gvqf-4gy7t-vuprx-u2urx-gqe"})'

This command returns the client of the new wallet ：

(record { 1_313_628_723 = principal "dcxxq-jqaaa-aaaab-qaavq-cai" })

Register a new container identifier

Use this wallet_create_canister Method in Internet Register a new container identifier on the computer . This method creates a new “ empty ” Container placeholder , This includes the initial period balance , And you can choose to use a specific subject as its controller . After registering the container identifier , You can install code for your application as a separate step .

for example , You can run commands like the following to create a new wallet and specify a principal as the controller ：

dfx canister --network  call f3yw6-7qaaa-aaaab-qaabq-cai wallet_create_canister '(record { cycles = 5000000000000 : nat64; controller = principal "vpqee-nujda-46rtu-4noo7-qnxmb-zqs7g-5gvqf-4gy7t-vuprx-u2urx-gqe"})'

This command returns the body of the new container you created ：

(record { 1_313_628_723 = principal "dxqg5-iyaaa-aaaab-qaawa-cai" })

Receive cycle from container

Use this wallet_receive Method as the endpoint to receive the cycle .

Transfer calls from your wallet

Use this wallet_call Method uses a circular wallet identifier to forward the call .

Management address

Use the following methods to manage address book entries ：

• add_address：（ Address ：AddressEntry）→（）;
• remove_address：（ Address ： client ）→（）;

Management activities

Use the following methods to retrieve event and chart information .

• get_events:(opt record { from: opt nat32; to: opt nat32; }) → (vec Event) Inquire about ;
• get_chart: (opt record { count: opt nat32; precision: opt nat64; } ) → (vec record { nat64; nat64; }) query;

for example , You can use this... By running a command similar to the following get_events Method returns canister_create And other events ：

dfx canister call <cycles-wallet-identifier> get_events '(record {from = null; to = null})'

If cycles wallet ( gastn-uqaaa-aaaae-aaafq-cai) Deployed in Internet Computer On the primary network , You can run the following command to return the event ：

dfx canister --network ic call gastn-uqaaa-aaaae-aaafq-cai get_events '(record {from = null; to = null})'

The output of this command takes a form similar to Candid Format ：

(
  vec { record { 23_515 = 0; 1_191_829_844 = variant { 4_271_600_268 = record { 23_515 = principal "tsqwz-udeik-5migd-ehrev-pvoqv-szx2g-akh5s-fkyqc-zy6q7-snav6-uqe"; 1_224_700_491 = null; 1_269_754_742 = variant { 4_218_395_836 };} }; 2_781_795_542 = 1_621_456_688_636_513_683;}; record { 23_515 = 1; 1_191_829_844 = variant { 4_271_600_268 = record { 23_515 = principal "ejta3-neil3-qek6c-i7rdw-sxreh-lypfe-v6hjg-6so7x-5ugze-3iohr-2qe"; 1_224_700_491 = null; 1_269_754_742 = variant { 2_494_206_670 };} }; 2_781_795_542 = 1_621_461_468_638_569_551;}; record { 23_515 = 2; 1_191_829_844 = variant { 1_205_528_161 = record { 2_190_693_645 = 11_000_000_000_000; 2_631_180_839 = principal "gvvca-vyaaa-aaaae-aaaga-cai";} }; 2_781_795_542 = 1_621_462_573_993_647_258;}; record { 23_515 = 3; 1_191_829_844 = variant { 1_205_528_161 = record { 2_190_693_645 = 11_000_000_000_000; 2_631_180_839 = principal "gsueu-yaaaa-aaaae-aaagq-cai";} }; 2_781_795_542 = 1_621_462_579_193_578_440;}; record { 23_515 = 4; 1_191_829_844 = variant { 1_955_698_212 = record { 2_190_693_645 = 0; 2_374_371_241 = "install_code"; 2_631_180_839 = principal "aaaaa-aa";} }; 2_781_795_542 = 1_621_462_593_047_590_026;}; record { 23_515 = 5; 1_191_829_844 = variant { 1_955_698_212 = record { 2_190_693_645 = 0; 2_374_371_241 = "install_code"; 2_631_180_839 = principal "aaaaa-aa";} }; 2_781_795_542 = 1_621_462_605_779_157_885;}; record { 23_515 = 6; 1_191_829_844 = variant { 1_955_698_212 = record { 2_190_693_645 = 0; 2_374_371_241 = "authorize"; 2_631_180_839 = principal "gsueu-yaaaa-aaaae-aaagq-cai";} }; 2_781_795_542 = 1_621_462_609_036_146_536;}; record { 23_515 = 7; 1_191_829_844 = variant { 1_955_698_212 = record { 2_190_693_645 = 0; 2_374_371_241 = "greet"; 2_631_180_839 = principal "gvvca-vyaaa-aaaae-aaaga-cai";} }; 2_781_795_542 = 1_621_463_144_066_333_270;}; record { 23_515 = 8; 1_191_829_844 = variant { 4_271_600_268 = record { 23_515 = principal "ejta3-neil3-qek6c-i7rdw-sxreh-lypfe-v6hjg-6so7x-5ugze-3iohr-2qe"; 1_224_700_491 = null; 1_269_754_742 = variant { 2_494_206_670 };} }; 2_781_795_542 = 1_621_463_212_828_477_570;}; record { 23_515 = 9; 1_191_829_844 = variant { 1_955_698_212 = record { 2_190_693_645 = 0; 2_374_371_241 = "wallet_balance"; 2_631_180_839 = principal "gastn-uqaaa-aaaae-aaafq-cai";} }; 2_781_795_542 = 1_621_878_637_071_884_946;}; record { 23_515 = 10; 1_191_829_844 = variant { 4_271_600_268 = record { 23_515 = principal "b5quc-npdph-l6qp4-kur4u-oxljq-7uddl-vfdo6-x2uo5-6y4a6-4pt6v-7qe"; 1_224_700_491 = null; 1_269_754_742 = variant { 4_218_395_836 };} }; 2_781_795_542 = 1_621_879_473_916_547_313;}; record { 23_515 = 11; 1_191_829_844 = variant { 313_999_214 = record { 1_136_829_802 = principal "gastn-uqaaa-aaaae-aaafq-cai"; 3_573_748_184 = 10_000_000_000;} }; 2_781_795_542 = 1_621_977_470_023_492_664;}; record { 23_515 = 12; 1_191_829_844 = variant { 2_171_739_429 = record { 25_979 = principal "gastn-uqaaa-aaaae-aaafq-cai"; 3_573_748_184 = 10_000_000_000; 4_293_698_680 = 0;} }; 2_781_795_542 = 1_621_977_470_858_839_320;};},
)

In this example , There are twelve events recorded .Role Field （ from hash Express 1_269_754_742） Specifies that the principal is the controller （ from hash Express 4_218_395_836） Or custodian （ from hash Express 2_494_206_670）. The event in this example also illustrates an amount field （ from hash Express 3_573_748_184）, Which transmits 10,000,000,000 A cycle .

190_693_645 = 0; 2_374_371_241 = “greet”; 2_631_180_839 = principal “gvvca-vyaaa-aaaae-aaaga-cai”;} }; 2_781_795_542 = 1_621_463_144_066_333_270;}; record { 23_515 = 8; 1_191_829_844 = variant { 4_271_600_268 = record { 23_515 = principal “ejta3-neil3-qek6c-i7rdw-sxreh-lypfe-v6hjg-6so7x-5ugze-3iohr-2qe”; 1_224_700_491 = null; 1_269_754_742 = variant { 2_494_206_670 };} }; 2_781_795_542 = 1_621_463_212_828_477_570;}; record { 23_515 = 9; 1_191_829_844 = variant { 1_955_698_212 = record { 2_190_693_645 = 0; 2_374_371_241 = “wallet_balance”; 2_631_180_839 = principal “gastn-uqaaa-aaaae-aaafq-cai”;} }; 2_781_795_542 = 1_621_878_637_071_884_946;}; record { 23_515 = 10; 1_191_829_844 = variant { 4_271_600_268 = record { 23_515 = principal “b5quc-npdph-l6qp4-kur4u-oxljq-7uddl-vfdo6-x2uo5-6y4a6-4pt6v-7qe”; 1_224_700_491 = null; 1_269_754_742 = variant { 4_218_395_836 };} }; 2_781_795_542 = 1_621_879_473_916_547_313;}; record { 23_515 = 11; 1_191_829_844 = variant { 313_999_214 = record { 1_136_829_802 = principal “gastn-uqaaa-aaaae-aaafq-cai”; 3_573_748_184 = 10_000_000_000;} }; 2_781_795_542 = 1_621_977_470_023_492_664;}; record { 23_515 = 12; 1_191_829_844 = variant { 2_171_739_429 = record { 25_979 = principal “gastn-uqaaa-aaaae-aaafq-cai”; 3_573_748_184 = 10_000_000_000; 4_293_698_680 = 0;} }; 2_781_795_542 = 1_621_977_470_858_839_320;};},
)

 In this example , There are twelve events recorded .Role  Field （ from  hash  Express `1_269_754_742`） Specifies that the principal is the controller （ from  hash  Express `4_218_395_836`） Or custodian （ from  hash  Express `2_494_206_670`）. The event in this example also illustrates an amount field （ from  hash  Express `3_573_748_184`）, Which transmits  10,000,000,000  A cycle .