Simplified ICP Top-Up — Proposed Protocol-Canister Changes

From → To

Add the notify input (block id only). No other type changes — the existing RedeemedForOptions.#MainerTopUp is reused.

// Notify input: the mAIner is derived from the block's memo, not passed in.
public type NotifyTopUpInput = { paymentTransactionBlockId : Nat64 };

TopUpResult / TopUpRecord already exist and are reused for notifyTopUp.

New private helper. Iterates mainerAgentCanistersStorage (the authoritative HashMap<Text, OfficialMainerAgentCanister>) and returns the unique mAIner whose textual canister id starts with the supplied prefix. Ambiguous or empty → null → notify rejects with #InvalidId.

// Decode the icrc1_memo to the mAIner id-prefix (ASCII, dashes included,
// e.g. "2r3eo-5q"). Matched verbatim against the canister id — no normalisation.
private func memoToPrefix(tx : TokenLedger.CandidTransaction) : ?Text {
    switch (tx.icrc1_memo) {
        case (?b) { Text.decodeUtf8(b) };            // ASCII id-prefix, '-' required
        case (null) { null };
    };
};

// Unique, unambiguous prefix match across all registered mAIners.
private func resolveMainerByPrefix(prefix : Text) : ?Types.OfficialMainerAgentCanister {
    if (Text.size(prefix) < MIN_MEMO_PREFIX_LEN) { return null };
    var hit : ?Types.OfficialMainerAgentCanister = null;
    for (m in mainerAgentCanistersStorage.vals()) {
        if (Text.startsWith(m.address, #text prefix)) {  // literal match, '-' included
            switch (hit) {
                case (null) { hit := ?m };
                case (?_)  { return null };           // ambiguous → #InvalidId
            };
        };
    };
    hit;
};

Permissionless notify: takes only a block id, resolves the mAIner from the block's memo, then delegates to the existing shared helper.

public shared (msg) func notifyTopUp(input : Types.NotifyTopUpInput) : async Types.TopUpResult {
    if (Principal.isAnonymous(msg.caller)) { return #Err(#Unauthorized); };
    if (PAUSE_PROTOCOL and not Principal.isController(msg.caller)) {
        return #Err(#Other("Protocol is currently paused"));
    };
    // Cheap double-spend guard — runs before any ledger call
    if (checkExistingTransactionBlock(input.paymentTransactionBlockId)) {
        return #Err(#Other("Already redeemd this transaction block"));
    };
    // Fetch the block ONCE (archive-aware); reused by the verify step (no second query_blocks)
    let tx = switch (await fetchLedgerTransaction(input.paymentTransactionBlockId)) {
        case (?t) { t };
        case (null) { return #Err(#InvalidId); };
    };
    let mainerEntry = switch (Option.chain(memoToPrefix tx, resolveMainerByPrefix)) {
        case (?m) { m };
        case (null) { return #Err(#InvalidId); };    // memo didn't resolve to a mAIner
    };
    switch (await processTopUpCyclesForMainer({
        caller = msg.caller;
        paymentTransactionBlockId = input.paymentTransactionBlockId;
        mainerEntry;
        ledgerTx = tx;                                // reuse the already-fetched block — no re-query
    })) {
        case (#Ok(r)) { #Ok({ cyclesAdded = r.cyclesAdded; mainerAgentAddress = r.mainerEntry.address }); };
        case (#Err(e)) { #Err(e); };
    };
};

Anonymous is still rejected (consistent with existing endpoints). "Any caller" is safe because the memo names the target mAIner — a caller can only trigger the top-up the sender already intended.

Bug. verifyIncomingPayment fetches the block with ICP_LEDGER_ACTOR.query_blocks and returns #Err(#InvalidId) when its blocks array is empty (Main.mo:5172). Once a block leaves the ledger's live window it is moved to an archive canister — query_blocks then returns empty blocks plus an archived_blocks range — so verification wrongly fails for every archived block.

Impact. This breaks every payment-verifying path: the new notifyTopUp / processTopUpCyclesForMainer and the admin recovery completeTopUpCyclesForMainerAgentAdmin. A Jupiter Faucet disbursal notified after its block is archived would fail with #InvalidId.

Fix. Extract an archive-aware fetchLedgerTransaction(blockId) helper; when the live window misses, follow the matching archived_blocks range's callback (get_blocks on the archive canister). Callers fetch the block once with it and pass the result down — verifyIncomingPayment no longer queries the ledger itself (also removes the duplicate query_blocks, see Cycle drain in §Security).

private func fetchLedgerTransaction(blockId : Nat64) : async ?TokenLedger.CandidTransaction {
    let args : TokenLedger.GetBlocksArgs = { start = blockId; length = 1 };
    let resp = await ICP_LEDGER_ACTOR.query_blocks(args);
    if (resp.blocks.size() >= 1) { return ?resp.blocks[0].transaction };   // still in the live window
    // archived: find the range holding this block and query its archive canister
    for (range in resp.archived_blocks.vals()) {
        if (blockId >= range.start and blockId < range.start + range.length) {
            switch (await range.callback(args)) {
                case (#Ok(r)) { if (r.blocks.size() >= 1) { return ?r.blocks[0].transaction } };
                case (#Err(_)) {};
            };
        };
    };
    null;
};

// ProcessTopUpInput carries the already-fetched block: add  ledgerTx : TokenLedger.CandidTransaction
// verifyIncomingPayment takes it instead of calling query_blocks itself — drop the fetch +
// empty check (Main.mo:5164-5176) and read the operation/amount straight off input.ledgerTx.
// Each caller (notifyTopUp, the gated endpoint, the admin recovery) does the single fetch:
let tx = switch (await fetchLedgerTransaction(blockId)) {
    case (?t) { t };
    case (null) { return #Err(#InvalidId); };        // also covers archived blocks now
};

Closes the double-redemption TOCTOU (see §Security). The block id is claimed in the same synchronous slice as the double-spend check — before any await — so a concurrent call sees the claim and bails. Motoko runs a message atomically between awaits, which is what makes this correct. The claim is released on every failure path so a failed attempt can be retried.

// transient: in-flight claims; entries are short-lived and need not survive upgrades
transient var inFlightBlocks = TrieSet.empty<Nat64>();

// in notifyTopUp — same slice as the check, no await in between:
if (checkExistingTransactionBlock(blockId) or TrieSet.mem(inFlightBlocks, blockId, hashN64 blockId, Nat64.equal)) {
    return #Err(#Other("Already redeemd this transaction block"));
};
inFlightBlocks := TrieSet.put(inFlightBlocks, blockId, hashN64 blockId, Nat64.equal);   // claim

let result = try {
    // ... fetch once, resolve, processTopUpCyclesForMainer (records via putRedeemedTransactionBlock on success) ...
} catch (e) { #Err(#Other(Error.message(e))) };

inFlightBlocks := TrieSet.delete(inFlightBlocks, blockId, hashN64 blockId, Nat64.equal);  // release (success or fail)
result;

A trap (not a catchable reject) rolls state back to the last await commit, so structure the credit + record so a trap can't leave a delivered top-up without its redeemed-block record.