feat: ckEth orchestrator (#632)

# Motivation Add the ckEth orchestrator ([source](https://github.com/dfinity/ic/tree/master/rs/ethereum/ledger-suite-orchestrator)) to `@dfinity/ledger-cketh` and expose function `get_orchestrator_info`. This additional canister is responsible for spinning up Ledger and Index canisters for ckERC20 tokens when (and if) the respective proposals are approved and executed (for example, proposal [129750](https://nns.ic0.app/proposal/?u=qoctq-giaaa-aaaaa-aaaea-cai&proposal=129750)). One might want to use this canister to fetch at runtime the list of ledgers and indexes or the list of supported ckERC20 tokens, but most probably, as in Oisy, one might use this feature to set up a job that periodically checks automatically if new tokens were approved and deployed. # Changes - set-up did and idl generation for `orchestrator.did` - init and expose `CkETHOrchestratorCanister` (no particular options) - implement `get_orchestrator_info` (nothing particular, readonly function) - add canister to `docs.js` to generate its documentation
dfinity · May 21, 2024 · cec0dc3 · cec0dc3
1 parent 7eae0e4
commit cec0dc3
Show file tree

Hide file tree

Showing 13 changed files with 788 additions and 0 deletions.
diff --git a/packages/cketh/README.md b/packages/cketh/README.md
@@ -171,6 +171,46 @@ Parameters:
 
 [:link: Source](https://github.com/dfinity/ic-js/tree/main/packages/cketh/src/minter.canister.ts#L157)
 
+### :factory: CkETHOrchestratorCanister
+
+Class representing the CkETH Orchestrator Canister, which manages the Ledger and Index canisters of ckERC20 tokens.
+
+[:link: Source](https://github.com/dfinity/ic-js/tree/main/packages/cketh/src/orchestrator.canister.ts#L15)
+
+#### Methods
+
+- [create](#gear-create)
+- [getOrchestratorInfo](#gear-getorchestratorinfo)
+
+##### :gear: create
+
+Creates an instance of CkETHOrchestratorCanister.
+
+| Method   | Type                                                                                 |
+| -------- | ------------------------------------------------------------------------------------ |
+| `create` | `(options: CkETHOrchestratorCanisterOptions<_SERVICE>) => CkETHOrchestratorCanister` |
+
+Parameters:
+
+- `options`: - Options for creating the canister.
+
+[:link: Source](https://github.com/dfinity/ic-js/tree/main/packages/cketh/src/orchestrator.canister.ts#L21)
+
+##### :gear: getOrchestratorInfo
+
+Retrieves orchestrator information, which contains the list of existing ckERC20 Ledger and Index canisters.
+
+| Method                | Type                                                          |
+| --------------------- | ------------------------------------------------------------- |
+| `getOrchestratorInfo` | `({ certified, }?: QueryParams) => Promise<OrchestratorInfo>` |
+
+Parameters:
+
+- `params`: - The query parameters.
+- `params.certified`: - Whether to execute a certified (update) call.
+
+[:link: Source](https://github.com/dfinity/ic-js/tree/main/packages/cketh/src/orchestrator.canister.ts#L40)
+
 <!-- TSDOC_END -->
 
 ## Resources

diff --git a/packages/cketh/candid/orchestrator.certified.idl.d.ts b/packages/cketh/candid/orchestrator.certified.idl.d.ts
@@ -0,0 +1,2 @@
+import type { IDL } from "@dfinity/candid";
+export const idlFactory: IDL.InterfaceFactory;
diff --git a/packages/cketh/candid/orchestrator.certified.idl.js b/packages/cketh/candid/orchestrator.certified.idl.js
@@ -0,0 +1,159 @@
+/* Do not edit.  Compiled with ./scripts/compile-idl-js from packages/cketh/candid/orchestrator.did */
+export const idlFactory = ({ IDL }) => {
+  const UpdateCyclesManagement = IDL.Record({
+    'cycles_top_up_increment' : IDL.Opt(IDL.Nat),
+    'cycles_for_ledger_creation' : IDL.Opt(IDL.Nat),
+    'cycles_for_archive_creation' : IDL.Opt(IDL.Nat),
+    'cycles_for_index_creation' : IDL.Opt(IDL.Nat),
+  });
+  const UpgradeArg = IDL.Record({
+    'cycles_management' : IDL.Opt(UpdateCyclesManagement),
+    'archive_compressed_wasm_hash' : IDL.Opt(IDL.Text),
+    'git_commit_hash' : IDL.Opt(IDL.Text),
+    'ledger_compressed_wasm_hash' : IDL.Opt(IDL.Text),
+    'index_compressed_wasm_hash' : IDL.Opt(IDL.Text),
+  });
+  const CyclesManagement = IDL.Record({
+    'cycles_top_up_increment' : IDL.Nat,
+    'cycles_for_ledger_creation' : IDL.Nat,
+    'cycles_for_archive_creation' : IDL.Nat,
+    'cycles_for_index_creation' : IDL.Nat,
+  });
+  const InitArg = IDL.Record({
+    'cycles_management' : IDL.Opt(CyclesManagement),
+    'more_controller_ids' : IDL.Vec(IDL.Principal),
+    'minter_id' : IDL.Opt(IDL.Principal),
+  });
+  const Erc20Contract = IDL.Record({
+    'chain_id' : IDL.Nat,
+    'address' : IDL.Text,
+  });
+  const LedgerSubaccount = IDL.Vec(IDL.Nat8);
+  const LedgerAccount = IDL.Record({
+    'owner' : IDL.Principal,
+    'subaccount' : IDL.Opt(LedgerSubaccount),
+  });
+  const LedgerFeatureFlags = IDL.Record({ 'icrc2' : IDL.Bool });
+  const LedgerInitArg = IDL.Record({
+    'decimals' : IDL.Opt(IDL.Nat8),
+    'token_symbol' : IDL.Text,
+    'transfer_fee' : IDL.Nat,
+    'minting_account' : LedgerAccount,
+    'initial_balances' : IDL.Vec(IDL.Tuple(LedgerAccount, IDL.Nat)),
+    'maximum_number_of_accounts' : IDL.Opt(IDL.Nat64),
+    'accounts_overflow_trim_quantity' : IDL.Opt(IDL.Nat64),
+    'fee_collector_account' : IDL.Opt(LedgerAccount),
+    'max_memo_length' : IDL.Opt(IDL.Nat16),
+    'token_logo' : IDL.Text,
+    'token_name' : IDL.Text,
+    'feature_flags' : IDL.Opt(LedgerFeatureFlags),
+  });
+  const AddErc20Arg = IDL.Record({
+    'contract' : Erc20Contract,
+    'ledger_init_arg' : LedgerInitArg,
+    'git_commit_hash' : IDL.Text,
+    'ledger_compressed_wasm_hash' : IDL.Text,
+    'index_compressed_wasm_hash' : IDL.Text,
+  });
+  const OrchestratorArg = IDL.Variant({
+    'UpgradeArg' : UpgradeArg,
+    'InitArg' : InitArg,
+    'AddErc20Arg' : AddErc20Arg,
+  });
+  const ManagedCanisterIds = IDL.Record({
+    'ledger' : IDL.Opt(IDL.Principal),
+    'index' : IDL.Opt(IDL.Principal),
+    'archives' : IDL.Vec(IDL.Principal),
+  });
+  const ManagedCanisterStatus = IDL.Variant({
+    'Created' : IDL.Record({ 'canister_id' : IDL.Principal }),
+    'Installed' : IDL.Record({
+      'canister_id' : IDL.Principal,
+      'installed_wasm_hash' : IDL.Text,
+    }),
+  });
+  const ManagedCanisters = IDL.Record({
+    'erc20_contract' : Erc20Contract,
+    'ledger' : IDL.Opt(ManagedCanisterStatus),
+    'index' : IDL.Opt(ManagedCanisterStatus),
+    'archives' : IDL.Vec(IDL.Principal),
+    'ckerc20_token_symbol' : IDL.Text,
+  });
+  const OrchestratorInfo = IDL.Record({
+    'cycles_management' : CyclesManagement,
+    'managed_canisters' : IDL.Vec(ManagedCanisters),
+    'more_controller_ids' : IDL.Vec(IDL.Principal),
+    'minter_id' : IDL.Opt(IDL.Principal),
+  });
+  return IDL.Service({
+    'canister_ids' : IDL.Func(
+        [Erc20Contract],
+        [IDL.Opt(ManagedCanisterIds)],
+        [],
+      ),
+    'get_orchestrator_info' : IDL.Func([], [OrchestratorInfo], []),
+  });
+};
+export const init = ({ IDL }) => {
+  const UpdateCyclesManagement = IDL.Record({
+    'cycles_top_up_increment' : IDL.Opt(IDL.Nat),
+    'cycles_for_ledger_creation' : IDL.Opt(IDL.Nat),
+    'cycles_for_archive_creation' : IDL.Opt(IDL.Nat),
+    'cycles_for_index_creation' : IDL.Opt(IDL.Nat),
+  });
+  const UpgradeArg = IDL.Record({
+    'cycles_management' : IDL.Opt(UpdateCyclesManagement),
+    'archive_compressed_wasm_hash' : IDL.Opt(IDL.Text),
+    'git_commit_hash' : IDL.Opt(IDL.Text),
+    'ledger_compressed_wasm_hash' : IDL.Opt(IDL.Text),
+    'index_compressed_wasm_hash' : IDL.Opt(IDL.Text),
+  });
+  const CyclesManagement = IDL.Record({
+    'cycles_top_up_increment' : IDL.Nat,
+    'cycles_for_ledger_creation' : IDL.Nat,
+    'cycles_for_archive_creation' : IDL.Nat,
+    'cycles_for_index_creation' : IDL.Nat,
+  });
+  const InitArg = IDL.Record({
+    'cycles_management' : IDL.Opt(CyclesManagement),
+    'more_controller_ids' : IDL.Vec(IDL.Principal),
+    'minter_id' : IDL.Opt(IDL.Principal),
+  });
+  const Erc20Contract = IDL.Record({
+    'chain_id' : IDL.Nat,
+    'address' : IDL.Text,
+  });
+  const LedgerSubaccount = IDL.Vec(IDL.Nat8);
+  const LedgerAccount = IDL.Record({
+    'owner' : IDL.Principal,
+    'subaccount' : IDL.Opt(LedgerSubaccount),
+  });
+  const LedgerFeatureFlags = IDL.Record({ 'icrc2' : IDL.Bool });
+  const LedgerInitArg = IDL.Record({
+    'decimals' : IDL.Opt(IDL.Nat8),
+    'token_symbol' : IDL.Text,
+    'transfer_fee' : IDL.Nat,
+    'minting_account' : LedgerAccount,
+    'initial_balances' : IDL.Vec(IDL.Tuple(LedgerAccount, IDL.Nat)),
+    'maximum_number_of_accounts' : IDL.Opt(IDL.Nat64),
+    'accounts_overflow_trim_quantity' : IDL.Opt(IDL.Nat64),
+    'fee_collector_account' : IDL.Opt(LedgerAccount),
+    'max_memo_length' : IDL.Opt(IDL.Nat16),
+    'token_logo' : IDL.Text,
+    'token_name' : IDL.Text,
+    'feature_flags' : IDL.Opt(LedgerFeatureFlags),
+  });
+  const AddErc20Arg = IDL.Record({
+    'contract' : Erc20Contract,
+    'ledger_init_arg' : LedgerInitArg,
+    'git_commit_hash' : IDL.Text,
+    'ledger_compressed_wasm_hash' : IDL.Text,
+    'index_compressed_wasm_hash' : IDL.Text,
+  });
+  const OrchestratorArg = IDL.Variant({
+    'UpgradeArg' : UpgradeArg,
+    'InitArg' : InitArg,
+    'AddErc20Arg' : AddErc20Arg,
+  });
+  return [OrchestratorArg];
+};
diff --git a/packages/cketh/candid/orchestrator.d.ts b/packages/cketh/candid/orchestrator.d.ts
@@ -0,0 +1,96 @@
+import type { ActorMethod } from "@dfinity/agent";
+import type { IDL } from "@dfinity/candid";
+import type { Principal } from "@dfinity/principal";
+
+export interface AddErc20Arg {
+  contract: Erc20Contract;
+  ledger_init_arg: LedgerInitArg;
+  git_commit_hash: string;
+  ledger_compressed_wasm_hash: string;
+  index_compressed_wasm_hash: string;
+}
+export interface CyclesManagement {
+  cycles_top_up_increment: bigint;
+  cycles_for_ledger_creation: bigint;
+  cycles_for_archive_creation: bigint;
+  cycles_for_index_creation: bigint;
+}
+export interface Erc20Contract {
+  chain_id: bigint;
+  address: string;
+}
+export interface InitArg {
+  cycles_management: [] | [CyclesManagement];
+  more_controller_ids: Array<Principal>;
+  minter_id: [] | [Principal];
+}
+export interface LedgerAccount {
+  owner: Principal;
+  subaccount: [] | [LedgerSubaccount];
+}
+export interface LedgerFeatureFlags {
+  icrc2: boolean;
+}
+export interface LedgerInitArg {
+  decimals: [] | [number];
+  token_symbol: string;
+  transfer_fee: bigint;
+  minting_account: LedgerAccount;
+  initial_balances: Array<[LedgerAccount, bigint]>;
+  maximum_number_of_accounts: [] | [bigint];
+  accounts_overflow_trim_quantity: [] | [bigint];
+  fee_collector_account: [] | [LedgerAccount];
+  max_memo_length: [] | [number];
+  token_logo: string;
+  token_name: string;
+  feature_flags: [] | [LedgerFeatureFlags];
+}
+export type LedgerSubaccount = Uint8Array | number[];
+export interface ManagedCanisterIds {
+  ledger: [] | [Principal];
+  index: [] | [Principal];
+  archives: Array<Principal>;
+}
+export type ManagedCanisterStatus =
+  | {
+      Created: { canister_id: Principal };
+    }
+  | {
+      Installed: { canister_id: Principal; installed_wasm_hash: string };
+    };
+export interface ManagedCanisters {
+  erc20_contract: Erc20Contract;
+  ledger: [] | [ManagedCanisterStatus];
+  index: [] | [ManagedCanisterStatus];
+  archives: Array<Principal>;
+  ckerc20_token_symbol: string;
+}
+export type OrchestratorArg =
+  | { UpgradeArg: UpgradeArg }
+  | { InitArg: InitArg }
+  | { AddErc20Arg: AddErc20Arg };
+export interface OrchestratorInfo {
+  cycles_management: CyclesManagement;
+  managed_canisters: Array<ManagedCanisters>;
+  more_controller_ids: Array<Principal>;
+  minter_id: [] | [Principal];
+}
+export interface UpdateCyclesManagement {
+  cycles_top_up_increment: [] | [bigint];
+  cycles_for_ledger_creation: [] | [bigint];
+  cycles_for_archive_creation: [] | [bigint];
+  cycles_for_index_creation: [] | [bigint];
+}
+export interface UpgradeArg {
+  cycles_management: [] | [UpdateCyclesManagement];
+  archive_compressed_wasm_hash: [] | [string];
+  git_commit_hash: [] | [string];
+  ledger_compressed_wasm_hash: [] | [string];
+  index_compressed_wasm_hash: [] | [string];
+}
+export interface _SERVICE {
+  canister_ids: ActorMethod<[Erc20Contract], [] | [ManagedCanisterIds]>;
+  get_orchestrator_info: ActorMethod<[], OrchestratorInfo>;
+}
+export declare const idlFactory: IDL.InterfaceFactory;
+export declare const init: (args: { IDL: typeof IDL }) => IDL.Type[];
Original file line number	Diff line number	Diff line change
		@@ -0,0 +1,2 @@
		import type { IDL } from "@dfinity/candid";
		export const idlFactory: IDL.InterfaceFactory;