chore: migrate motoko/ic-pos to icp-cli (#1442)

Author: marc0olo

.github/workflows/ic_pos.yml

@@ -0,0 +1,28 @@
+name: ic_pos
+
+on:
+  push:
+    branches: [master]
+  pull_request:
+    paths:
+      - motoko/ic-pos/**
+      - .github/workflows/ic_pos.yml
+
+concurrency:
+  group: ${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: true
+
+jobs:
+  motoko-ic_pos:
+    runs-on: ubuntu-24.04
+    container: ghcr.io/dfinity/icp-dev-env-motoko:1.0.1
+    env:
+      ICP_CLI_GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+    steps:
+      - uses: actions/checkout@34e114876b0b11c390a56381ad16ebd13914f8d5 # v4.3.1
+      - name: Deploy and test
+        working-directory: motoko/ic-pos
+        run: |
+          icp network start -d
+          bash deploy.sh
+          bash test.sh

motoko/ic-pos/.gitignore

@@ -17,6 +17,12 @@ target/
 node_modules/
 dist/
 
+# generated canister bindings (icp-bindgen)
+frontend/src/bindings/
+
+# TypeScript incremental build info
+*.tsbuildinfo
+
 # environment variables
 .env
 

motoko/ic-pos/CHANGELOG.md

@@ -0,0 +1,160 @@
+import Debug "mo:core/Debug";
+import Map "mo:core/Map";
+import Nat "mo:core/Nat";
+import Nat8 "mo:core/Nat8";
+import Nat64 "mo:core/Nat64";
+import Principal "mo:core/Principal";
+import Runtime "mo:core/Runtime";
+import Text "mo:core/Text";
+import Time "mo:core/Time";
+
+import Types "app.types";
+
+// This actor:
+//  - stores merchant information,
+//  - monitors the ICRC-1 ledger for incoming transfers, and
+//  - logs where a merchant notification would be sent.
+//
+// The ledger canister is resolved at runtime from the injected
+// `PUBLIC_CANISTER_ID:icrc1_ledger` environment variable:
+//   local: the pre-built ICRC-1 ledger deployed by deploy.sh
+//   ic:    the TICRC1 test ledger (see icp.yaml)
+//
+// `_startBlock` is the ledger block index to start monitoring from.
+//
+// NOTE: notifications are illustrative. The original example sent email/SMS via
+// an HTTPS outcall to a third party; this version only logs that a notification
+// could be sent. To implement real notifications, use HTTPS outcalls — see
+// https://docs.internetcomputer.org/guides/backends/https-outcalls
+//
+// NOTE: scanning the ledger's global transaction log sequentially does not scale
+// to a busy shared ledger (such as TICRC1); it is illustrative only. A
+// production app would query the index canister per merchant account instead
+// (as this example's frontend already does).
+actor class Main(_startBlock : Nat) {
+
+  // Minimal subset of the ICRC-1 ledger interface this actor uses. Candid
+  // ignores wire fields not declared here, so only the read fields are listed.
+  type Account = { owner : Principal };
+  type Transfer = { to : Account; from : Account; amount : Nat };
+  type Transaction = { kind : Text; transfer : ?Transfer };
+  type GetTransactionsRequest = { start : Nat; length : Nat };
+  type GetTransactionsResponse = { transactions : [Transaction] };
+  type Ledger = actor {
+    get_transactions : GetTransactionsRequest -> async GetTransactionsResponse;
+    icrc1_symbol : () -> async Text;
+    icrc1_decimals : () -> async Nat8;
+  };
+
+  let merchantStore = Map.empty<Text, Types.Merchant>();
+  // Next ledger block index to scan for incoming transfers.
+  var nextBlock : Nat = _startBlock;
+  // Token metadata, cached lazily from the ledger to format logged amounts.
+  // Transient: re-fetched on demand after an upgrade.
+  transient var tokenSymbol : Text = "tokens";
+  transient var tokenDecimals : Nat = 8;
+  transient var metadataLoaded : Bool = false;
+
+  // How many ledger blocks to scan per timer tick. Draining a batch (rather than
+  // one block per tick) means a payment is logged within a single tick even when
+  // the monitor is catching up on a backlog (e.g. the initial mint).
+  let scanBatchSize : Nat = 100;
+
+  // Get the caller's merchant information.
+  public query (context) func getMerchant() : async Types.Response<Types.Merchant> {
+    switch (merchantStore.get(context.caller.toText())) {
+      case (?merchant) {
+        { status = 200; status_text = "OK"; data = ?merchant; error_text = null };
+      };
+      case null {
+        {
+          status = 404;
+          status_text = "Not Found";
+          data = null;
+          error_text = ?("Merchant with principal ID: " # context.caller.toText() # " not found.");
+        };
+      };
+    };
+  };
+
+  // Create or update the caller's merchant information.
+  public shared (context) func updateMerchant(merchant : Types.Merchant) : async Types.Response<Types.Merchant> {
+    merchantStore.add(context.caller.toText(), merchant);
+    { status = 200; status_text = "OK"; data = ?merchant; error_text = null };
+  };
+
+  // Resolve the ledger canister, injected as PUBLIC_CANISTER_ID:icrc1_ledger.
+  func ledger<system>() : Ledger {
+    switch (Runtime.envVar<system>("PUBLIC_CANISTER_ID:icrc1_ledger")) {
+      case (?id) actor (id) : Ledger;
+      case null Runtime.trap("PUBLIC_CANISTER_ID:icrc1_ledger not set — run icp deploy");
+    };
+  };
+
+  // Fetch the token's symbol and decimals from the ledger once, then cache them.
+  func loadMetadataOnce<system>() : async () {
+    if (metadataLoaded) return;
+    let l = ledger<system>();
+    tokenSymbol := await l.icrc1_symbol();
+    tokenDecimals := Nat8.toNat(await l.icrc1_decimals());
+    metadataLoaded := true;
+  };
+
+  // Render a base-unit amount using the cached decimals and symbol, e.g. with
+  // 8 decimals: 100_000_000 -> "1 LICRC1", 50_000 -> "0.0005 LICRC1".
+  func formatAmount(amount : Nat) : Text {
+    let base = 10 ** tokenDecimals;
+    let whole = (amount / base).toText();
+    let frac = amount % base;
+    if (frac == 0) return whole # " " # tokenSymbol;
+    // Left-pad the fractional digits to `tokenDecimals`, then drop trailing zeros.
+    var fracText = frac.toText();
+    while (fracText.size() < tokenDecimals) { fracText := "0" # fracText };
+    whole # "." # Text.trimEnd(fracText, #char '0') # " " # tokenSymbol;
+  };
+
+  // Scan for new transactions and log a would-be notification for each payment
+  // to a merchant that has notifications enabled. Called by the global timer.
+  system func timer(setGlobalTimer : Nat64 -> ()) : async () {
+    let next = Nat64.fromIntWrap(Time.now()) + 20_000_000_000; // 20 seconds
+    setGlobalTimer(next);
+    await notify<system>();
+  };
+
+  func notify<system>() : async () {
+    let response = await ledger<system>().get_transactions({ start = nextBlock; length = scanBatchSize });
+    let txs = response.transactions;
+    if (txs.size() == 0) return; // caught up; check again next tick
+    nextBlock += txs.size();
+
+    var i = 0;
+    label scan while (i < txs.size()) {
+      let t = txs[i];
+      i += 1;
+      if (t.kind != "transfer") continue scan;
+      switch (t.transfer) {
+        case (?transfer) {
+          switch (merchantStore.get(transfer.to.owner.toText())) {
+            case (?merchant) {
+              // A payment for a merchant with notifications enabled: emit a
+              // canister log (observable via `icp canister logs backend`) marking
+              // where a real notification would be sent. To actually send one,
+              // use HTTPS outcalls —
+              // https://docs.internetcomputer.org/guides/backends/https-outcalls
+              if (merchant.email_notifications or merchant.phone_notifications) {
+                if (not metadataLoaded) await loadMetadataOnce<system>();
+                Debug.print(
+                  "Payment of " # formatAmount(transfer.amount) # " received by merchant '" # merchant.name #
+                  "' from " # transfer.from.owner.toText() #
+                  ". A notification could be sent here via HTTPS outcalls."
+                );
+              };
+            };
+            case null {};
+          };
+        };
+        case null {};
+      };
+    };
+  };
+};

motoko/ic-pos/README.md

@@ -0,0 +1,21 @@
+type Response = 
+ record {
+   data: opt Merchant;
+   error_text: opt text;
+   status: nat16;
+   status_text: text;
+ };
+type Merchant = 
+ record {
+   email_address: text;
+   email_notifications: bool;
+   name: text;
+   phone_notifications: bool;
+   phone_number: text;
+ };
+type Main = 
+ service {
+   getMerchant: () -> (Response) query;
+   updateMerchant: (merchant: Merchant) -> (Response);
+ };
+service : (_startBlock: nat) -> Main

motoko/ic-pos/backend/app.mo

@@ -0,0 +1,66 @@
+#!/usr/bin/env bash
+set -e
+
+# Local deploy for ic-pos. Use `bash deploy.sh` (not `icp deploy`): the ICRC-1
+# ledger and index require init args (minting account, initial balances, ledger
+# id) that are only known after identities exist.
+#
+# For mainnet, deploy with `icp deploy -e ic` instead — the ledger, index, and
+# Internet Identity are not deployed there (the app uses the shared TICRC1 test
+# token and the production II; see icp.yaml and the README).
+#
+# Prerequisite: a running local network (`icp network start -d`).
+
+# Two dedicated identities:
+#  - ic-pos-minter: the ledger's minting account (mints the initial supply).
+#  - ic-pos-dev:    a normal, pre-funded holder you pay merchants from.
+# These must be DIFFERENT identities — and independent of your current default —
+# so that transfers from ic-pos-dev are real "transfer"s (debited, with a fee)
+# that the backend monitor picks up. If the minter and the holder were the same
+# identity, its "transfers" would be mints: no debit, no fee, and the monitor
+# (which only reacts to transfers) would ignore them.
+icp identity new ic-pos-minter --storage plaintext 2>/dev/null || true
+icp identity new ic-pos-dev --storage plaintext 2>/dev/null || true
+MINTER=$(icp identity principal --identity ic-pos-minter)
+DEV=$(icp identity principal --identity ic-pos-dev)
+
+# 1. ICRC-1 ledger — minting account = ic-pos-minter; ic-pos-dev pre-funded.
+# Named distinctly from the shared mainnet TICRC1 token to make clear this is a
+# throwaway local ledger, not the real thing.
+icp deploy icrc1_ledger --mode reinstall -y --args "(variant { Init = record { \
+  token_name = \"Local ICRC-1\"; \
+  token_symbol = \"LICRC1\"; \
+  minting_account = record { owner = principal \"$MINTER\" }; \
+  initial_balances = vec { record { record { owner = principal \"$DEV\" }; 1_000_000_000_000 : nat } }; \
+  metadata = vec {}; \
+  transfer_fee = 10_000 : nat; \
+  archive_options = record { \
+    trigger_threshold = 2000 : nat64; \
+    num_blocks_to_archive = 1000 : nat64; \
+    controller_id = principal \"$MINTER\" }; \
+  feature_flags = opt record { icrc2 = true } } })"
+
+# 2. ICRC-1 index — points at the ledger we just deployed.
+LEDGER_ID=$(icp canister status icrc1_ledger -i)
+icp deploy icrc1_index --mode reinstall -y --args "(opt variant { Init = record { \
+  ledger_id = principal \"$LEDGER_ID\"; \
+  retrieve_blocks_from_ledger_interval_seconds = opt (1 : nat64) } })"
+
+# 3. Backend and frontend (init args come from icp.yaml). Internet Identity is
+# provided by the local network (ii: true in icp.yaml), not deployed here.
+icp deploy backend
+icp deploy frontend
+
+echo
+echo "Deployed. The test tokens are held by the 'ic-pos-dev' identity"
+echo "(your default identity has none). Pass --identity ic-pos-dev to spend"
+echo "them — no need to change your selected identity:"
+echo
+echo "  # check the balance"
+echo "  icp token \$(icp canister status icrc1_ledger -i) balance --identity ic-pos-dev"
+echo
+echo "  # pay a merchant 1 LICRC1 (amounts are in base units; 8 decimals),"
+echo "  # a real transfer the backend monitor picks up"
+echo "  icp canister call icrc1_ledger icrc1_transfer \\"
+echo "    '(record { to = record { owner = principal \"<MERCHANT_PRINCIPAL>\" }; amount = 100_000_000 : nat })' \\"
+echo "    --identity ic-pos-dev"