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

[marc0olo]

What

Tier 2 of the canister:<name> import + --actor-env-alias migration (follows #1452). Applies the same pattern to the three Motoko examples whose backend calls an external canister that is already named and env-injected in icp.yaml:

Example	Target	Hand-written code removed
ic-pos	icrc1_ledger	Ledger actor type + Account/Transfer/Transaction/GetTransactions* subtypes
evm_block_explorer	evm_rpc	~140-line type surface in EvmRpcApi.mo (RpcServices/RpcConfig/BlockTag/error types/EvmRpcActor)
llm_chatbot	llm	LlmActor/Request/Response + the Runtime.envVar resolver

Approach

For each backend:

• Import the target by name (import Ledger "canister:icrc1_ledger", etc.) 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 — so it is authoritative and matches the deployed canister.
• Wire the import in mops.toml: --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.

File-placement convention

External-canister interfaces live in a shared project-root candid/ directory, distinct from the project's own generated interface:

• own interface → stays with its code, generated: backend/backend.did ← mops generate candid backend
• external (called) interfaces → vendored into candid/<name>.did, extracted from the pinned Wasm

This separates first-party from third-party interfaces and scales to projects where several canisters share one external interface (a single copy in candid/, referenced by each canister's mops.toml).

Committed .did files are full, not trimmed

The vendored interfaces are the full authoritative services (icrc1_ledger 586 lines, evm_rpc 348, llm 56) — the decided convention is to avoid hand-trimmed subsets. They match the "provide the target canister's .did" principle and stay regenerable by re-extraction (documented in each README).

Frontend safety

llm_chatbot's message types and evm_block_explorer's Block are part of the backend's own public API (the frontends generate bindings from backend.did). For llm_chatbot the public message types are kept (they are structurally identical to the LLM canister's, so values flow straight into LLM.v1_chat); for evm_block_explorer the identical EvmRpc.Block is reused. All three backend.did files are byte-identical after the change (verified with mops generate candid backend), so no frontend is affected.

Testing

All three build with mops build, and every backend.did is unchanged. The backend→external call was verified end-to-end for each (note: the example CI jobs deploy all three but only evm_block_explorer's test.sh asserts the external call — ic-pos's runs in an unasserted timer and llm_chatbot's test.sh is empty — so the other two were verified locally):

• evm_block_explorer — get_evm_block(1) returns Ethereum mainnet block 1 with the correct hash and miner (CI test.sh + local), a real call through canister:evm_rpc + HTTPS outcall.
• ic-pos — after a real transfer, the backend logs Payment of 0.005 LICRC1 received by merchant 'Test Shop', which requires icrc1_symbol + icrc1_decimals + get_transactions to all succeed through canister:icrc1_ledger (incl. decoding the full ICRC transaction response).
• llm_chatbot — prompt(...) returns a model reply, exercising the full backend→llm v1_chat round trip (with tools = null and the structural response decode) against a local Ollama-backed LLM canister.

🤖 Generated with Claude Code

[marc0olo]

Updated per review feedback: the vendored external-canister interfaces now live in a shared project-root candid/ directory instead of backend/, establishing a clear convention:

• a canister's own interface stays with its code and is generated — backend/backend.did ← mops generate candid backend;
• interfaces of external canisters the project calls are vendored into candid/<name>.did, extracted from the pinned Wasm.

This keeps first-party and third-party interfaces separate (a 586-line ledger .did no longer sits next to the 20-line backend.did) and scales to projects where several canisters share one external interface — a single copy in candid/, referenced by each canister's mops.toml. The READMEs now explain this and drop the earlier vague "different kind of file" wording. All three backend.did files remain byte-identical.

[Copilot]

Pull request overview

This PR continues the Motoko canister:<name> + --actor-env-alias migration for examples that call external canisters, replacing hand-written actor/type surfaces with typed canister imports backed by committed external .did files.

Changes:

• Switched llm_chatbot, ic-pos, and evm_block_explorer backends to typed imports (import ... "canister:...") for external canister calls.
• Added vendored external Candid interfaces under each example’s candid/ directory and wired them into mops.toml via --actor-env-alias.
• Updated READMEs to document how to refresh external .did files (from mainnet metadata or pinned Wasm artifacts).

Reviewed changes

Copilot reviewed 12 out of 12 changed files in this pull request and generated no comments.

Show a summary per file

File	Description
motoko/llm_chatbot/backend/app.mo	Replaces env-var + actor(id) plumbing with import LLM "canister:llm" and calls LLM.v1_chat directly.
motoko/llm_chatbot/mops.toml	Adds per-canister args including --actor-env-alias llm ... candid/llm.did.
motoko/llm_chatbot/README.md	Documents the typed import approach and how to refresh candid/llm.did.
motoko/llm_chatbot/candid/llm.did	Adds the full vendored LLM canister interface for typing canister:llm.
motoko/ic-pos/backend/app.mo	Replaces the minimal inline ledger actor/type subset with import Ledger "canister:icrc1_ledger" calls.
motoko/ic-pos/mops.toml	Adds --actor-env-alias icrc1_ledger ... candid/icrc1_ledger.did.
motoko/ic-pos/README.md	Documents the typed import approach and how to refresh candid/icrc1_ledger.did.
motoko/ic-pos/candid/icrc1_ledger.did	Adds the full vendored ICRC-1 ledger interface for typing canister:icrc1_ledger.
motoko/evm_block_explorer/backend/EvmRpcApi.mo	Removes the hand-written EVM RPC type surface in favor of import EvmRpc "canister:evm_rpc" and EvmRpc.* types.
motoko/evm_block_explorer/mops.toml	Adds --actor-env-alias evm_rpc ... candid/evm_rpc.did.
motoko/evm_block_explorer/README.md	Documents the typed import approach and how to refresh candid/evm_rpc.did.
motoko/evm_block_explorer/candid/evm_rpc.did	Adds the full vendored EVM RPC canister interface for typing canister:evm_rpc.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.