refactor(motoko): canister: import + --actor-env-alias for external-canister calls (ic-pos, evm_block_explorer, llm_chatbot) (#1453)

* refactor(motoko): use canister: import + --actor-env-alias for external-canister calls

Apply the Tier 1 pattern (canister:<name> import backed by moc's
--actor-env-alias) to the three Motoko examples that call an external
canister already named + env-injected in icp.yaml:

- ic-pos            → icrc1_ledger  (drops the hand-written Ledger actor
                       type and the Account/Transfer/Transaction subtypes)
- evm_block_explorer → evm_rpc      (drops the ~140-line EvmRpcApi type
                       surface: RpcServices/RpcConfig/BlockTag/errors/actor)
- llm_chatbot        → llm          (drops the LlmActor/Request/Response
                       boilerplate; keeps the public message types, which
                       are the backend's own API and are structurally
                       identical to the LLM canister's)

For each backend:
- import the target by name and drop the actor type + Runtime.envVar +
  actor(id) plumbing (and the now-unneeded <system> params);
- commit the target's Candid interface, extracted from the exact pre-built
  Wasm pinned in icp.yaml via `ic-wasm <wasm> metadata candid:service`
  (icrc1_ledger.did, evm_rpc.did, llm.did);
- wire the import in mops.toml with
  `--actor-env-alias <alias> PUBLIC_CANISTER_ID:<name> <did-path>`
  (per-canister args replace the global [moc].args, so the global flags
  are repeated).

The principal is still resolved from PUBLIC_CANISTER_ID:<name>, now at
canister install/upgrade rather than per call. Each backend's public
backend.did is byte-identical after the change (verified with
`mops generate candid backend`), so the frontends are unaffected.

READMEs document the typed import and, for these external targets, that
the committed .did is refreshed by re-extracting it from the pinned Wasm
(not `mops generate candid`).

Verified: all three build with `mops build`; evm_block_explorer deployed
locally and `get_evm_block(1)` returns Ethereum mainnet block 1 with the
correct hash and miner.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

* refactor(motoko): move external-canister interfaces into a project-level candid/ dir

Address review feedback on the Tier 2 examples: keep a project's own
interface with its code (backend/backend.did, generated by
`mops generate candid`), and move the interfaces of *external* canisters
the project calls into a shared, project-root `candid/` directory:

- ic-pos:            backend/icrc1_ledger.did -> candid/icrc1_ledger.did
- evm_block_explorer: backend/evm_rpc.did     -> candid/evm_rpc.did
- llm_chatbot:        backend/llm.did          -> candid/llm.did

This separates first-party from vendored interfaces (a 586-line ledger
.did no longer sits next to the 20-line backend.did) and scales to
projects with several canisters that share an external interface — one
copy in candid/, referenced by each canister's mops.toml, rather than a
per-backend folder that would duplicate it.

Updates the `--actor-env-alias` did-paths in mops.toml, the in-code
comments, and the READMEs (which now explain the candid/ convention and
drop the vague "different kind of file" wording). Rebuilt all three;
each backend.did is unchanged.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

* docs(motoko): explain both ways to refresh an external canister's .did

The refresh instructions previously said "re-extract it from that Wasm"
but never said where the Wasm comes from — it is only pinned by URL in
icp.yaml, not present in the project. Rewrite the note in all three Tier 2
examples to give two clear, self-contained options:

- from mainnet, by the canister's principal:
  `icp canister metadata <principal> candid:service -e ic`
- from the pinned Wasm: download the exact pre-built artifact pinned in
  icp.yaml (build.steps[].url), unpack it, then `ic-wasm ... candid:service`

Both were verified to reproduce the committed candid/*.did byte-for-byte.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

---------

Co-authored-by: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

Author: marc0olo

motoko/evm_block_explorer/README.md

@@ -6,6 +6,8 @@
 
 The EVM Block Explorer example demonstrates how an ICP canister can fetch block data directly from Ethereum and other EVM-compatible chains. Using HTTPS outcalls via the [EVM RPC canister](https://github.com/dfinity/evm-rpc-canister), canisters on ICP can read on-chain data without a bridge or oracle. The same pattern applies to any EVM-compatible chain supported by the EVM RPC canister.
 
+The backend reaches the EVM RPC canister through the typed import `import EvmRpc "canister:evm_rpc"` in `backend/EvmRpcApi.mo` — no RPC actor type is hand-written. The import is typed against the EVM RPC canister's committed Candid interface (`candid/evm_rpc.did`), and the `--actor-env-alias` flag in `mops.toml` binds it to the `PUBLIC_CANISTER_ID:evm_rpc` environment variable that icp-cli injects (the local `evm_rpc` canister when developing, the shared `7hfb6-caaaa-aaaar-qadga-cai` on mainnet). The principal is resolved at canister install/upgrade; no principal is compiled into the Wasm, so the same artifact runs in every environment.
+
 <!--
 ## Deploying from ICP Ninja
 
@@ -66,6 +68,23 @@ If you modify the backend's public API, regenerate the `.did` file:
 mops generate candid backend
 ```
 
+`candid/evm_rpc.did` is the **EVM RPC canister's own interface**, not the backend's — the `canister:evm_rpc` import is typed against it. The `candid/` directory holds the interfaces of external canisters this project calls (as opposed to `backend/backend.did`, which is this project's own interface). These are not produced by `mops generate candid` — each is the Candid interface of an external canister. To refresh one (e.g. after bumping the EVM RPC release), get it straight from the canister with either of:
+
+**From mainnet** — the live shared EVM RPC canister. One command, no files to handle:
+
+```bash
+icp canister metadata 7hfb6-caaaa-aaaar-qadga-cai candid:service -e ic > candid/evm_rpc.did
+```
+
+**From the pinned Wasm** — matches exactly what deploys locally. The Wasm is the pre-built artifact pinned in this project's `icp.yaml` (the `evm_rpc` canister's `build.steps[].url`); download and unpack it, then extract its interface:
+
+```bash
+curl -sSL https://github.com/dfinity/evm-rpc-canister/releases/download/evm_rpc-v2.8.0/evm_rpc.wasm.gz | gunzip > evm_rpc.wasm
+ic-wasm evm_rpc.wasm metadata candid:service > candid/evm_rpc.did
+```
+
+Both give the same interface as long as `icp.yaml` pins the release that is live on mainnet.
+
 ## RPC providers and API keys
 
 The example uses [PublicNode](https://ethereum-rpc.publicnode.com) by default — a free, no-registration provider that works out of the box locally and on mainnet. This is sufficient for getting started and automated testing.

motoko/evm_block_explorer/backend/EvmRpcApi.mo

@@ -1,179 +1,31 @@
-import Runtime "mo:core/Runtime";
+import EvmRpc "canister:evm_rpc";
 
 module {
-  // Inline actor type for the EVM RPC canister, exposing only eth_getBlockByNumber.
-  // Full Candid interface: https://github.com/dfinity/evm-rpc-canister/blob/main/candid/evm_rpc.did
+  // The EVM RPC canister is imported by name via `canister:evm_rpc`, typed
+  // against candid/evm_rpc.did — so the request/response types below are the
+  // canister's own (e.g. EvmRpc.Block, EvmRpc.RpcServices), not hand-written.
+  // icp-cli injects its principal as PUBLIC_CANISTER_ID:evm_rpc at deploy time;
+  // the mops.toml `--actor-env-alias` flag binds the import to that variable.
 
-  public type Block = {
-    miner : Text;
-    totalDifficulty : ?Nat;
-    receiptsRoot : Text;
-    stateRoot : Text;
-    hash : Text;
-    difficulty : ?Nat;
-    size : Nat;
-    uncles : [Text];
-    baseFeePerGas : ?Nat;
-    extraData : Text;
-    transactionsRoot : ?Text;
-    sha3Uncles : Text;
-    nonce : Nat;
-    number : Nat;
-    timestamp : Nat;
-    transactions : [Text];
-    gasLimit : Nat;
-    logsBloom : Text;
-    parentHash : Text;
-    gasUsed : Nat;
-    mixHash : Text;
-  };
-
-  type BlockTag = {
-    #Earliest;
-    #Safe;
-    #Finalized;
-    #Latest;
-    #Number : Nat;
-    #Pending;
-  };
-
-  type HttpHeader = { value : Text; name : Text };
-  type RpcApi = { url : Text; headers : ?[HttpHeader] };
-
-  type EthMainnetService = {
-    #Alchemy;
-    #Ankr;
-    #BlockPi;
-    #Cloudflare;
-    #PublicNode;
-    #Llama;
-  };
-
-  type EthSepoliaService = {
-    #Alchemy;
-    #Ankr;
-    #BlockPi;
-    #PublicNode;
-    #Sepolia;
-  };
-
-  type L2MainnetService = {
-    #Alchemy;
-    #Ankr;
-    #BlockPi;
-    #PublicNode;
-    #Llama;
-  };
-
-  type RpcServices = {
-    #Custom : { chainId : Nat64; services : [RpcApi] };
-    #EthSepolia : ?[EthSepoliaService];
-    #EthMainnet : ?[EthMainnetService];
-    #ArbitrumOne : ?[L2MainnetService];
-    #BaseMainnet : ?[L2MainnetService];
-    #OptimismMainnet : ?[L2MainnetService];
-  };
-
-  type RpcService = {
-    #Provider : Nat64;
-    #Custom : RpcApi;
-    #EthSepolia : EthSepoliaService;
-    #EthMainnet : EthMainnetService;
-    #ArbitrumOne : L2MainnetService;
-    #BaseMainnet : L2MainnetService;
-    #OptimismMainnet : L2MainnetService;
-  };
-
-  type RejectionCode = {
-    #NoError;
-    #CanisterError;
-    #SysTransient;
-    #DestinationInvalid;
-    #Unknown;
-    #SysFatal;
-    #CanisterReject;
-  };
-
-  type JsonRpcError = { code : Int64; message : Text };
-
-  type ProviderError = {
-    #TooFewCycles : { expected : Nat; received : Nat };
-    #MissingRequiredProvider;
-    #ProviderNotFound;
-    #NoPermission;
-    #InvalidRpcConfig : Text;
-  };
-
-  type HttpOutcallError = {
-    #IcError : { code : RejectionCode; message : Text };
-    #InvalidHttpJsonRpcResponse : { status : Nat16; body : Text; parsingError : ?Text };
-  };
-
-  type ValidationError = {
-    #Custom : Text;
-    #InvalidHex : Text;
-  };
-
-  type RpcError = {
-    #JsonRpcError : JsonRpcError;
-    #ProviderError : ProviderError;
-    #ValidationError : ValidationError;
-    #HttpOutcallError : HttpOutcallError;
-  };
-
-  type GetBlockByNumberResult = { #Ok : Block; #Err : RpcError };
-
-  type MultiGetBlockByNumberResult = {
-    #Consistent : GetBlockByNumberResult;
-    #Inconsistent : [(RpcService, GetBlockByNumberResult)];
-  };
-
-  // Controls how the EVM RPC canister aggregates responses from multiple providers.
-  // - responseSizeEstimate: hint for the expected response size in bytes (affects cycles cost).
-  //   Leave null to use the canister's built-in default.
-  // - responseConsensus: how providers must agree before a result is accepted.
-  //   #Equality requires all providers to return identical responses (default).
-  //   #Threshold { total; min } requires at least `min` out of `total` providers to agree.
-  //   Leave null to use #Equality.
-  // Pass null for the entire RpcConfig to use all defaults — this is the right choice for most callers.
-  type ConsensusStrategy = {
-    #Equality;
-    #Threshold : { total : ?Nat; min : Nat };
-  };
-  type RpcConfig = { responseSizeEstimate : ?Nat64; responseConsensus : ?ConsensusStrategy };
-
-  type EvmRpcActor = actor {
-    eth_getBlockByNumber : (RpcServices, ?RpcConfig, BlockTag) -> async MultiGetBlockByNumberResult;
-  };
-
-  // The result type exposed to the main actor — matches the Rust variant names for cross-language consistency.
-  public type EvmBlockResult = { #Ok : Block; #Err : Text };
-
-  // Returns the EVM RPC canister actor, resolved at runtime from the PUBLIC_CANISTER_ID:evm_rpc
-  // environment variable. icp-cli sets this automatically at deploy time:
-  //   - locally: the principal of the locally deployed evm_rpc canister
-  //   - on ICP mainnet (ic environment): 7hfb6-caaaa-aaaar-qadga-cai
-  func evmRpc<system>() : EvmRpcActor {
-    let ?id = Runtime.envVar<system>("PUBLIC_CANISTER_ID:evm_rpc") else
-      Runtime.trap("PUBLIC_CANISTER_ID:evm_rpc not set — run icp deploy");
-    actor(id) : EvmRpcActor;
-  };
+  // The result type exposed to the main actor — matches the Rust variant names
+  // for cross-language consistency, and carries the RPC canister's Block type.
+  public type EvmBlockResult = { #Ok : EvmRpc.Block; #Err : Text };
 
   // Fetches the Ethereum mainnet block at the given height.
   // Uses PublicNode by default — no API key required, works locally and on mainnet.
   // For production deployments requiring premium providers (Alchemy, Ankr, BlockPi),
   // configure API keys via the EVM RPC canister, then pass null to use all configured
   // providers for better consensus: #EthMainnet(null)
-  public func getBlock<system>(height : Nat) : async EvmBlockResult {
-    let services : RpcServices = #EthMainnet(?[#PublicNode]);
+  public func getBlock(height : Nat) : async EvmBlockResult {
+    let services : EvmRpc.RpcServices = #EthMainnet(?[#PublicNode]);
 
     // To query a different chain, use #Custom instead:
-    // let services : RpcServices = #Custom {
+    // let services : EvmRpc.RpcServices = #Custom {
     //   chainId = 8453; // Base Mainnet — see https://chainlist.org/ for chain IDs
     //   services = [{ url = "https://base-rpc.publicnode.com"; headers = null }];
     // };
 
-    let result = await (with cycles = 10_000_000_000) evmRpc<system>().eth_getBlockByNumber(services, null, #Number height);
+    let result = await (with cycles = 10_000_000_000) EvmRpc.eth_getBlockByNumber(services, null, #Number height);
 
     switch result {
       case (#Consistent(#Ok block)) { #Ok block };