Cycle ウォレット
トークンと Cycle で説明したように、ICP トークンは Cycle に変換され、Canister の操作に利用されます。Cycle は、Dapp が消費する通信、計算、ストレージの運用コストを示しています。
ICP トークンとは異なり、Cycle は Canister にのみ関連付けられ、ユーザーや開発者の Principal には関連付けられません。 Canister だけが、操作の実行や使用するリソースの支払いに Cycle を必要とし消費するため、ユーザーと開発者は、Cycle ウォレットと呼ばれる特別なタイプの Canister を通じて Cycle の配布と所有権を管理します。Cycle ウォレットは、新しい Canister の作成などの操作に必要な Cycle を保持しているため、ユーザーの Principal の代わりに、Cycle ウォレットの Canister Principal を使用してこれらの操作が実行出来ます。
ローカル Canister 実行環境を使用するために、SDK はすべてのプロジェクトで自動的にデフォルトの Cycle ウォレットを作成します。また Cycle ウォレットを使用して実行される操作のほとんどは見えないところで行われます。例えば、Cycle ウォレットはあなたの（Principal）代わりに、 Canister Principal の登録や、ローカル Canister 実行環境での Canister のデプロイを行います。
しかし、プロダクト環境では Principal を管理して、Cycle を明示的に登録することや、新しい Canister に転送し、カストディアンとして機能できる Principal を指定し、所有権を持たせる必要があります。これらのタスクの一部は、ウェブブラウザで実行されるデフォルトの Cycle ウォレット Dapp を使って実行できます。また、実行したい特定のアクションに応じて、ターミナルで dfx wallet コマンドを実行したり、デフォルトの Cycle ウォレット Canister のメソッドを直接呼び出すことで、これらの Cycle と Canister の管理タスクを実行することができます。
しかし、Cycle ウォレット Canister への呼び出しは、現在選択されているユーザー Identity に関連付けられた Cycle ウォレット Principal を使用して実行されることを覚えておく必要があります。現在選択されている Identity や、それに関連する Principal がウォレットのコントローラーまたはカストディアンとして追加されているかどうかによって、異なる結果が表示されたり、特定のメソッドへのアクセスが拒否されたりする場合があります。
現在使用している Identity を確認するには、以下のコマンドを実行します：
dfx identity whoami
コントローラーとカストディアンの役割
ユーザー Principal または Canister Principal は、コントローラーまたはカストディアンの役割に割り当てることができます。
このドキュメントで説明するコントローラーの役割は、Internet Computer について話すときに通常意味するコントローラーの役割と同じではありません。通常、コントローラーは、 Canister を制御する Principal を意味します。ここでは、コントローラーは、たまたま同じ名前を持つウォレット内部のロールです。より詳細な区別については、このフォーラムの投稿を参照してください。
コントローラーは最も特権的なロールであり、コントローラーロールに割り当てられた Principal は、以下を含む特権的なタスクを実行することができます：
他の Principal をコントローラーとして追加・削除する。
他の Principal をカストディアンとして承認および承認解除する。
Cycle ウォレットのアドレス帳にエントリーを追加する。
Cycle ウォレットの残高と他のすべてのウォレット関連情報にアクセスできる。
他の Canister に Cycle を送信する。
他の Canister から Cycle の受け取りを許可する。
Cycle ウォレットの名前を変更する。
Canister と追加の Cycle ウォレットを作成する。
カストディアンの役割に割り当てられた Principal は、以下を含む Cycle ウォレット管理タスクのサブセットのみを実行することができます：
Cycle ウォレットの残高やその他のウォレット関連情報にアクセスできる。
他の Canister に Cycle を送信する。
他の Canister から Cycle の受け取りを許可する。
Canister を作成する。
Principal にカストディアンとしての権限を与えても、 Principal に自動的に Cycle ウォレットへのアクセス権が与えられるわけではありません。カストディアンロールに割り当てられた Identity は、Cycle ウォレットの Principal も割り当てられなければなりません。例えば、
alice_custodianという Identity をローカルプロジェクトの Cycle ウォレット（rwlgt-iiaaa-aaaaa-cai）のカストディアンとして承認する場合、そのユーザーもdfx identity set-wallet rwlgt-iiaaa-aaaaa-caiコマンドでそのウォレットの使用を割り当てられる必要があります。
Cycle ウォレット作成
ローカルで開発を行っている場合、Cycle ウォレットは dfx canister create を使用して新しい Canister Principal を登録したり、または dfx deploy を使用して Canister を登録、ビルド、デプロイするときに作成されます。
Internet Computer にデプロイする場合、Cycle ウォレットが作成され、通常、ICP トークンを Cycle に変換し、Cycle を新しい Canister Principal に転送し、デフォルトの Cycle ウォレット WebAssembly モジュール（WASM）で Canister を更新することが可能です。ICP トークンを Cycle に変換するでは、この方法を説明しています。
ICP を Cycle に変換し、新しい Cycle ウォレットを作成するための Dapps があります。例えば、NNS Dapp などです。
Cycle 残高の確認
ローカルの Canister 実行環境、または Inernet Computer 上の Cycle ウォレットでは、dfx wallet balance コマンドまたは wallet_balance メソッドを使用して現在の Cycle 残高を確認することができます。
ローカル環境で Cycle 残高を確認する
ローカルで開発を行っている場合、dfx wallet balance コマンドを使用すると、プロジェクトごとに現在の Cycle 残高をチェックすることができます。
ローカルプロジェクトの Cycle 残高を確認するには：
ターミナルを開き、プロジェクトのルートディレクトリに移動します。
以下のコマンドを実行して、ローカルの Canister 実行環境を起動します：
dfx start --background次のコマンドを実行して、現在選択されている Identity に関連付けられた Cycle ウォレットから、Cycle 残高を表示します：
dfx wallet balanceこのコマンドは、次のような出力を表示します：
78.000 TC (trillion cycles).
Internet Computer で Cycle 残高を確認する
Internet Computer に Cycle ウォレットを導入している場合、dfx wallet balance コマンドを使用してネットワーク上の現在の Cycle 残高を確認することができます。
Internet Computer 上の Cycle 残高を確認するには：
ターミナルを開き、設定ファイル
dfx.jsonが格納されているディレクトリに移動します。以下のコマンドを実行して、Internet Computer への接続を確認します：
dfx ping ic次のコマンドを実行して、現在選択されている Identity に関連する Cycle ウォレットから Cycle 残高を表示します：
dfx wallet --network ic balanceこのコマンドは、次のような出力を表示します：
67.992 TC (trillion cycles).
Cycle wallet_balance メソッドを呼び出す
また、Cycle ウォレットの Canister にある wallet_balance メソッドを直接呼び出して、 Cycle の残高を確認することもできます。例えば、あなたの Principal が h5aet-waaaa-aaaab-qaamq-cai で Cycle ウォレットのコントローラーである場合、以下のコマンドを実行して現在の Cycle 残高をチェックすることができます：
dfx canister --network ic call h5aet-waaaa-aaaab-qaamq-cai wallet_balance
このコマンドでは、以下のように金額フィールド（hash 3_573_748_184）と残高 6,895,656,625,450 Cycle を持つレコードとして Candid 形式で残高が返されます：
(record { 3_573_748_184 = 6_895_656_625_450 })
その他 dfx がサポートする Wallet 機能
Cycle ウォレットは、dfx を通じてより多くの機能をサポートしています。サポートされている操作の完全なリストについては、dfx wallet reference を参照してください。
デフォルト Cycle ウォレットの追加メソッド
デフォルトの Cycle ウォレット Canister には、dfx wallet コマンドとして公開されていない追加のメソッドが含まれています。追加のメソッドは、新しい Canister の作成やイベントの管理など、より高度な Cycle 管理タスクをサポートします。
新しい Cycle ウォレットを作成する
wallet_create_wallet メソッドを使用して、初期 Cycle 残高と、オプションで特定の Principal をコントローラーとした新しい Cycle ウォレット Canister を作成します。もし、コントロールする Principal を指定しなければ、新しいウォレットを作成するために使用した Cycle ウォレットが新しいウォレットのコントローラーになります。
例えば、以下のようなコマンドを実行して、新しいウォレットを作成し、 Principal をコントローラーとして割り当てます：
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"})'
このコマンドは、新しいウォレットの Principal を返します：
(record { 1_313_628_723 = principal "dcxxq-jqaaa-aaaab-qaavq-cai" })
Canister Principal を新規登録する
Internet Computer に新しい Canister Principal を登録するには、 wallet_create_canister メソッドを使用します。このメソッドでは、新しい 「空」の Canister プレースホルダーを作成し、初期 Cycle 残高と、オプションでそのコントローラーとして特定の Principal を設定できます。 Canister Principal を登録した後、別の手順で Canister 用のコードをインストールできます。
例えば、以下のようなコマンドを実行して、新しいウォレットを作成し、 Principal をコントローラーとして割り当てることができます：
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"})'
このコマンドは、作成した新しい Canister の Principal を返します：
(record { 1_313_628_723 = principal "dxqg5-iyaaa-aaaab-qaawa-cai" })
Canister から Cycle を受け取る
Cycle を受信するためのエンドポイントとして wallet_receive メソッドを使用します。
ウォレットから呼び出しをする
呼び出し元として Cycle ウォレット Principal を使用して呼び出しを転送するには、 wallet_call メソッドを使用します。
アドレスを管理する
アドレス帳の項目を管理するには、次の方法を使用します：
add_address: (address: AddressEntry) → ();remove_address: (address: principal) → ();
イベントを管理する
イベントやチャートの情報を取得するには、以下のメソッドを使用します。
get_events: (opt record { from: opt nat32; to: opt nat32; }) → (vec Event) query;get_chart: (opt record { count: opt nat32; precision: opt nat64; } ) → (vec record { nat64; nat64; }) query;
例えば、以下のようなコマンドを実行することで、 get_events メソッドを使用して canister_create などのイベントを返すことができます：
dfx canister call <cycles-wallet-principal> get_events '(record {from = null; to = null})'
Cycle ウォレット（gastn-uqaaa-aaaaafq-cai）が Internet Computer のメインネットワークにデプロイされている場合、次のようなコマンドを実行するとイベントを返すことができます：
dfx canister --network ic call gastn-uqaaa-aaaae-aaafq-cai get_events '(record {from = null; to = null})'
コマンドの出力は、以下のような Candid 形式です：
(
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;};},
)
この例では、12個のイベントレコードがあります。Role フィールド（hash 1_269_754_742）は、Principal がコントローラー（hash 4_218_395_836）かカストディアン（hash 2_494_206_670）かを指定するものです。この例のイベントは、10,000,000,000 Cycle の転送を行う金額フィールド（hash 3_573_748_184 で表される）も例示しています。