refactor(motoko/icp_transfer): call the ICP ledger via canister: import + --actor-id-alias (#1455)

Replace the hand-written ICP ledger actor type (and the hardcoded
`actor("ryjl3-…")` reference) with a typed `canister:icp_ledger` import bound
by moc's `--actor-id-alias`. All ledger types now come from the ledger's
official Candid interface — nothing is hand-declared.

Why `--actor-id-alias` (and not `--actor-env-alias` or generated bindings):
the ICP ledger lives at the *same, fixed, well-known* principal
(ryjl3-tyaaa-aaaaa-aaaba-cai) on both mainnet and the local development
network. When the target id is fixed and universal, binding it at compile time
is the simplest correct choice — no per-environment env-var injection needed
(that's what `--actor-env-alias` is for), and no runtime `actor(id)`
construction (that's for targets chosen at runtime).

- candid/icp_ledger.did — the ledger's official interface, from the
  ledger-suite-icp-2025-08-29 release (`ledger.did`).
- mops.toml — `--actor-id-alias icp_ledger ryjl3-tyaaa-aaaaa-aaaba-cai candid/icp_ledger.did`.
- backend/app.mo — `import IcpLedger "canister:icp_ledger"`; types are now
  `IcpLedger.Tokens` / `IcpLedger.TransferArgs` / …; removed the hand-written
  Tokens/SubAccount/BlockIndex/AccountIdentifier/LedgerTransferArgs/TransferError/
  TransferResult and the `actor("ryjl3-…")` line.

Verified end-to-end: `icp deploy && bash test.sh` — all 3 tests pass (real ICP
transfers via the imported ledger, with correct balance deltas).

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

Author: marc0olo

motoko/icp_transfer/README.md

@@ -14,6 +14,14 @@ The example exposes three functions to make this concrete:
 
 > The ICP ledger also supports the [ICRC-1](https://github.com/dfinity/ICRC-1) standard via `icrc1_transfer`. For new token integrations that don't require AccountIdentifier compatibility, ICRC-1 is the recommended interface. A comprehensive ICRC ledger example is planned.
 
+## Calling the ICP ledger
+
+The backend reaches the ledger through the typed import `import IcpLedger "canister:icp_ledger"` — no ledger types are declared in the code. Because the ICP ledger lives at the **same well-known principal** (`ryjl3-tyaaa-aaaaa-aaaba-cai`) on both mainnet and the local development network, the `--actor-id-alias` flag in `mops.toml` binds the import to that fixed id and types it against the ledger's official Candid interface (`candid/icp_ledger.did`). The request/response types (`IcpLedger.Tokens`, `IcpLedger.TransferArgs`, …) come straight from that interface.
+
+> `--actor-id-alias` fits here because the target's id is *fixed and universal*. When a target's id varies per environment, `--actor-env-alias` resolves it from an injected env var instead; when the target is chosen at runtime, generate bindings and construct `actor(principal)` per call.
+
+`candid/icp_ledger.did` is the ledger's own interface, taken from the [ICP ledger suite release](https://github.com/dfinity/ic/releases/tag/ledger-suite-icp-2025-08-29) (`ledger.did`). To refresh it after a new ledger release, download the `ledger.did` asset from that release.
+
 ## Build and deploy from the command line
 
 ### Prerequisites

motoko/icp_transfer/backend/app.mo

@@ -6,48 +6,24 @@ import Result "mo:core/Result";
 import Error "mo:core/Error";
 import Principal "mo:core/Principal";
 
+// The ICP ledger is imported by name via `canister:icp_ledger`. It lives at the
+// same well-known principal (ryjl3-tyaaa-aaaaa-aaaba-cai) on both mainnet and the
+// local development network, so the mops.toml `--actor-id-alias` flag binds this
+// import to that fixed id and types it against the ledger's official Candid
+// interface (candid/icp_ledger.did) — no ledger types are declared here.
+import IcpLedger "canister:icp_ledger";
+
 actor IcpTransfer {
-  // ICP Ledger types (matches the ICP ledger Candid interface)
-  type Tokens = { e8s : Nat64 };
-  type SubAccount = Blob;
-  type BlockIndex = Nat64;
 
+  // Shared transfer logic.
+  //
   // An AccountIdentifier is a 32-byte blob that encodes a principal and an
-  // optional subaccount. It is the native account format used by the ICP ledger.
+  // optional subaccount — the native account format used by the ICP ledger.
   // Centralized exchanges (CEXs) identify accounts by this blob; wallets and
   // newer integrations prefer the ICRC-1 format (principal + subaccount directly).
-  //
   // Use Principal.toLedgerAccount(subaccount) to compute one from a principal.
-  type AccountIdentifier = Blob;
-
-  type TimeStamp = { timestamp_nanos : Nat64 };
-
-  type LedgerTransferArgs = {
-    memo : Nat64;
-    amount : Tokens;
-    fee : Tokens;
-    from_subaccount : ?SubAccount;
-    to : AccountIdentifier;
-    created_at_time : ?TimeStamp;
-  };
-
-  type TransferError = {
-    #BadFee : { expected_fee : Tokens };
-    #InsufficientFunds : { balance : Tokens };
-    #TxTooOld : { allowed_window_nanos : Nat64 };
-    #TxCreatedInFuture;
-    #TxDuplicate : { duplicate_of : BlockIndex };
-  };
-
-  type TransferResult = { #Ok : BlockIndex; #Err : TransferError };
-
-  // The ICP ledger is a system canister available on both mainnet and
-  // the local development network at this well-known principal.
-  let icpLedger : actor { transfer : (LedgerTransferArgs) -> async TransferResult } = actor ("ryjl3-tyaaa-aaaaa-aaaba-cai");
-
-  // Shared transfer logic.
-  func doTransfer(amount : Tokens, to : AccountIdentifier) : async Result.Result<BlockIndex, Text> {
-    let transferArgs : LedgerTransferArgs = {
+  func doTransfer(amount : IcpLedger.Tokens, to : IcpLedger.AccountIdentifier) : async Result.Result<IcpLedger.BlockIndex, Text> {
+    let transferArgs : IcpLedger.TransferArgs = {
       memo = 0;
       amount;
       fee = { e8s = 10_000 };
@@ -59,7 +35,7 @@ actor IcpTransfer {
       created_at_time = null;
     };
     try {
-      switch (await icpLedger.transfer(transferArgs)) {
+      switch (await IcpLedger.transfer(transferArgs)) {
         case (#Err(e)) #err("Transfer failed: " # debug_show e);
         case (#Ok(blockIndex)) #ok blockIndex;
       };
@@ -70,15 +46,15 @@ actor IcpTransfer {
 
   // Convert a principal and optional subaccount to its AccountIdentifier as a
   // lowercase hex string — the format shown in block explorers and CEX deposit screens.
-  public query func toAccountIdHex(p : Principal, subaccount : ?SubAccount) : async Text {
+  public query func toAccountIdHex(p : Principal, subaccount : ?IcpLedger.SubAccount) : async Text {
     let bytes = Array.fromIter(p.toLedgerAccount(subaccount).vals());
     Hex.toText(bytes);
   };
 
   // Transfer ICP to a recipient identified by principal + optional subaccount.
   // Internally calls Principal.toLedgerAccount to derive the AccountIdentifier.
   // This is the most convenient form when you have a principal.
-  public shared func transferToPrincipal(amount : Tokens, toPrincipal : Principal, toSubaccount : ?SubAccount) : async Result.Result<BlockIndex, Text> {
+  public shared func transferToPrincipal(amount : IcpLedger.Tokens, toPrincipal : Principal, toSubaccount : ?IcpLedger.SubAccount) : async Result.Result<IcpLedger.BlockIndex, Text> {
     Debug.print("Transferring " # debug_show amount # " to principal " # debug_show toPrincipal);
     await doTransfer(amount, toPrincipal.toLedgerAccount(toSubaccount));
   };
@@ -91,7 +67,7 @@ actor IcpTransfer {
   // validates it and returns a clear error on mismatch. A fromHex helper with
   // CRC32 validation (equivalent to AccountIdentifier::from_hex in ic-ledger-types)
   // would be a valuable addition to a Motoko ICP library.
-  public shared func transferToAccountId(amount : Tokens, toAccountIdHex : Text) : async Result.Result<BlockIndex, Text> {
+  public shared func transferToAccountId(amount : IcpLedger.Tokens, toAccountIdHex : Text) : async Result.Result<IcpLedger.BlockIndex, Text> {
     switch (Hex.toArray(toAccountIdHex)) {
       case (#err(e)) #err("invalid hex: " # e);
       case (#ok(bytes)) {