fix(factory): require evm confirmation depth

Author: domwoe

IMPLEMENTATION_LEARNINGS.md

@@ -48,3 +48,14 @@
 - Process improvement: lease/version ownership is part of every nested async function contract. Recheck it immediately after each await and in the same atomic mutation as every result write, including errors. Tests must force takeover inside nested send and receipt awaits and return both stale success and stale error. Recovery must reconstruct all signing inputs from the persisted draft or reject configuration drift.
 - Final cycle-4 review: accepted and fixed guard propagation through persisted transaction resume, send, and receipt awaits; guarded CAS evidence/error/finalization writes; stale-owner-safe cleanup; and complete draft authority including the optional ECDSA key name. Factory 110/110, artifact/Candid parity, shared 25/25, indexer 96/96, web 95/95, and all lints passed. No P0/P1 or implementation-caused/plan-required P2 findings remain.
 - Follow-up risk for Plan 004: use the factory's persisted transaction draft and generation-CAS discipline for confirmation depth; an observed receipt must never finalize after a lease/version loss or configuration drift.
+
+## Plan 004 — Factory EVM confirmation depth (2026-07-16)
+
+- Repository convention: release, refund, and reproduction flows share typed receipt evidence and must use the same canonical block and confirmation-count helper; persisted transaction hashes are authoritative and must never fall through to a second broadcast.
+- Constraint: every caller of a confirmation helper must branch on its returned `confirmed` flag. Persisting receipt evidence is not equivalent to finality, and `debug_assert!` cannot enforce a financial invariant in release builds.
+- ICP/Candid/stable storage: the implementation uses additive serde-defaulted receipt and per-block payment-evidence fields plus an optional stable confirmation-depth field, preserving old snapshot decoding while regenerating the factory Candid interface.
+- Effective gates: 19 confirmation tests, 6 escrow tests, 146 full factory tests, fmt, clippy with warnings denied, warning-free release Wasm, generated Candid, and artifact parity all passed. Parent diff inspection still caught no-rebroadcast and bytes32 fixture regressions; final review caught host refund finalization below depth, demonstrating that green gates did not cover every caller contract.
+- Review findings accepted and fixed before the final review: canonicality-before-depth, per-block deposit evidence, guard propagation across async RPC stages, pending receipt representation, overflow-safe arithmetic, local-chain defaults, spawn no-rebroadcast behavior, pending-state preservation, and exact bytes32 fixtures.
+- Authorized final-cycle finding accepted and fixed: `claim_escrow_refund_inner` in the non-Wasm path had finalized both resumed and newly broadcast refunds without rejecting `receipt.confirmed == false`; one branch relied only on `debug_assert!`. Both branches now persist evidence, return a pending error below depth, and finalize only after runtime-confirmed depth. Three host tests cover fresh pending, resumed pending, and exact-depth idempotent finalization.
+- Process improvement: map every boolean/enum result from a shared financial helper to every call site and add a caller-contract test matrix, including host-only adapters. Keep Spark executor/reviewer prompts bounded, use high reasoning, require runtime model provenance, and stop broad diagnostic loops that can overflow context or generate unbounded logs.
+- Final review: the same Spark/high reviewer approved the extra authorized cycle with no unresolved P0/P1 or implementation-caused P2 findings. Final independent gates passed with 3 focused refund tests, 20 confirmation tests, 9 escrow tests, 149 full factory tests, clean fmt/clippy, warning-free release Wasm, regenerated Candid, and artifact parity.

backend/factory/factory.did

@@ -111,9 +111,13 @@ type EscrowClaim = record {
   created_at : nat64;
   payment_status : PaymentStatus;
   refundable : bool;
+  payment_evidence : vec PaymentEvidenceBlock;
+  payment_evidence_block_hash : opt text;
   refunded_at : opt nat64;
   refund_broadcast : opt ReleaseBroadcastRecord;
   payment_address : text;
+  payment_evidence_increment : opt text;
+  payment_evidence_block_number : opt nat64;
   last_scanned_block : opt nat64;
 };
 type FactoryArtifactSnapshot = record {
@@ -123,6 +127,7 @@ type FactoryArtifactSnapshot = record {
   version_commit : opt text;
 };
 type FactoryConfigSnapshot = record {
+  evm_confirmation_depth : nat64;
   base_rpc_fallback_endpoint : opt text;
   escrow_contract_address : text;
   session_ttl_ms : nat64;
@@ -171,6 +176,7 @@ type FactoryError = variant {
   ManagementCallFailed : record { method : text; message : text };
   InvalidChildRuntimeConfig : record { field : text; message : text };
   InvalidDeathReport : record { reason : text };
+  InvalidOperationalConfig : record { field : text; message : text };
   SessionNotFound : record { session_id : text };
   InvalidStewardProof : record { reason : text };
   RepositoryStrategyAlreadyExists : record { strategy_id : text };
@@ -251,6 +257,7 @@ type FactoryInitArgs = record {
   admin_principals : vec principal;
 };
 type FactoryOperationalConfig = record {
+  evm_confirmation_depth : nat64;
   cycles_per_spawn : nat64;
   estimated_outcall_cycles_per_interval : nat64;
   min_pool_balance : nat64;
@@ -333,6 +340,11 @@ type ListRepositoryStrategiesResponse = record {
 };
 type MemoryDowryFact = record { key : text; value : text };
 type OpenRouterReasoningLevel = variant { Low; High; Medium; Default };
+type PaymentEvidenceBlock = record {
+  block_hash : text;
+  block_number : nat64;
+  amount : text;
+};
 type PaymentStatus = variant { Refunded; Paid; Unpaid; Partial };
 type PostRoomMessageRequest = record {
   body : text;
@@ -372,6 +384,7 @@ type ReleaseBroadcastFailure = record {
   rpc_category : opt RpcFailureCategory;
 };
 type ReleaseBroadcastRecord = record {
+  receipt_status : opt bool;
   last_error : opt ReleaseBroadcastFailure;
   signature : opt ReleaseSignatureRecord;
   rpc_tx_hash : opt text;
@@ -388,6 +401,8 @@ type ReleaseBroadcastRecord = record {
   signing_payload_hash : opt text;
   gas_limit : nat64;
   raw_transaction_hash : opt text;
+  receipt_block_number : opt nat64;
+  receipt_block_hash : opt text;
   calldata_hex : text;
 };
 type ReleaseBroadcastStage = variant {

backend/factory/src/api/admin.rs

@@ -85,11 +85,28 @@ pub fn set_operational_config(
     caller: &str,
     config: FactoryOperationalConfig,
 ) -> Result<FactoryOperationalConfig, FactoryError> {
+    if config.evm_confirmation_depth == 0 {
+        return Err(FactoryError::InvalidOperationalConfig {
+            field: "evm_confirmation_depth".to_string(),
+            message: "must be greater than zero".to_string(),
+        });
+    }
+    if config.evm_confirmation_depth > crate::types::MAX_EVM_CONFIRMATION_DEPTH {
+        return Err(FactoryError::InvalidOperationalConfig {
+            field: "evm_confirmation_depth".to_string(),
+            message: format!(
+                "exceeds maximum supported confirmation depth {}",
+                crate::types::MAX_EVM_CONFIRMATION_DEPTH
+            ),
+        });
+    }
+
     write_state(|state| -> Result<(), FactoryError> {
         ensure_admin_in_state(state, caller)?;
         state.cycles_per_spawn = config.cycles_per_spawn;
         state.min_pool_balance = config.min_pool_balance;
         state.estimated_outcall_cycles_per_interval = config.estimated_outcall_cycles_per_interval;
+        state.evm_confirmation_depth = config.evm_confirmation_depth;
         Ok(())
     })?;
 
@@ -177,6 +194,7 @@ pub fn get_factory_config(caller: &str) -> Result<FactoryConfigSnapshot, Factory
             cycles_per_spawn: state.cycles_per_spawn,
             min_pool_balance: state.min_pool_balance,
             estimated_outcall_cycles_per_interval: state.estimated_outcall_cycles_per_interval,
+            evm_confirmation_depth: state.evm_confirmation_depth,
             session_ttl_ms: state.session_ttl_ms,
             version_commit: state.version_commit.clone(),
             wasm_sha256: state.wasm_sha256.clone(),