Harden payment semantics and add subscription escrow withdrawal (#88)

* protocol: harden payment flows and add escrow withdrawal

* test: cover escrow refund and strict payment invariants

* docs: align pricing semantics and add fast foundry profile

Author: drewstone

docs/PRICING.md

@@ -44,7 +44,7 @@ BlueprintConfig({
 ### Flow
 
 1. Operators publish off-chain `SignedQuote`s (EIP-712) with their `totalCost` for the requested TTL
-2. User calls `createServiceFromQuotes(blueprintId, quotes, config, permittedCallers, ttl)` with `msg.value >= sum(quote.totalCost)`
+2. User calls `createServiceFromQuotes(blueprintId, quotes, config, permittedCallers, ttl)` with `msg.value == sum(quote.totalCost)`
 3. Payment is distributed immediately via `PaymentSplit`
 
 ### What the developer controls
@@ -95,13 +95,15 @@ function getBillableServices(uint64[] calldata serviceIds) external view returns
 
 - Token is set at service creation (native or ERC-20)
 - `getServiceEscrow(serviceId)` returns `{ token, balance, totalDeposited, totalReleased }`
-- No auto-termination on empty escrow — billing simply fails until refunded
+- No auto-termination on empty escrow — billing simply fails until re-funded
+- After service termination, remaining escrow can be withdrawn via `withdrawRemainingEscrow(serviceId)`
 
 ---
 
 ## EventDriven
 
 The most flexible model. Each job submission pays on the spot.
+Optionally, a one-time setup fee can also be charged at service activation.
 
 ### Blueprint config
 
@@ -115,6 +117,12 @@ BlueprintConfig({
 })
 ```
 
+### Settlement asset (current behavior)
+
+- Event-driven payments are currently native-token settled.
+- Request-time `paymentToken` must be `address(0)` for EventDriven services.
+- Job payments from `submitJob()` and `submitJobFromQuote()` are native.
+
 ### Rate resolution
 
 When a job is submitted, the protocol resolves the price in this order:
@@ -124,6 +132,8 @@ per-job override (_jobEventRates[blueprintId][jobIndex])
     └─ if 0 → fallback to BlueprintConfig.eventRate
 ```
 
+If the service request includes a non-zero upfront `paymentAmount`, that setup fee is distributed when the service activates (in addition to per-job billing).
+
 Source: `JobsSubmission.sol:146-162`
 
 ```solidity
@@ -472,7 +482,7 @@ Pricing-related storage in `TangleStorage.sol`:
 
 ### Service consumer
 
-1. For `EventDriven` (fixed rates): call `submitJob()` with `msg.value >= getJobEventRate(blueprintId, jobIndex)`
+1. For `EventDriven` (fixed rates): call `submitJob()` with exact `msg.value == getJobEventRate(blueprintId, jobIndex)` (or configured per-job override)
 2. For `EventDriven` (RFQ): request quotes from operators via their gRPC endpoint, call `submitJobFromQuote()` with signed quotes
 3. For `Subscription`: call `fundService()` to keep escrow funded
 4. For `PayOnce`: pay at service creation via `createServiceFromQuotes()`

foundry.toml

@@ -13,6 +13,16 @@ evm_version = "cancun"
 via_ir = true
 allow_internal_expect_revert = true
 
+[profile.fast]
+# Local iteration profile: much faster compile/test cycles.
+# Use with: `FOUNDRY_PROFILE=fast forge test ...`
+via_ir = true
+optimizer = false
+sparse_mode = true
+gas_reports = []
+fuzz = { runs = 256 }
+invariant = { runs = 64, depth = 64, fail_on_revert = false }
+
 [profile.coverage]
 via_ir = true
 optimizer = true

src/core/Base.sol

@@ -686,6 +686,56 @@ abstract contract Base is
     // can manipulate state during callbacks. Only register audited managers.
     // ═══════════════════════════════════════════════════════════════════════════
 
+    /// @notice Query whether a manager allows a payment asset in a specific context.
+    /// @dev Backwards compatible behavior:
+    ///      - First tries `contextId`
+    ///      - Then falls back to legacy `0` context when `contextId != 0`
+    ///      - If query hooks are missing/unimplemented, defaults to allow
+    function _isPaymentAssetAllowedByManager(
+        address manager,
+        uint64 contextId,
+        address asset
+    )
+        internal
+        view
+        returns (bool)
+    {
+        if (manager == address(0)) return true;
+
+        (bool hasContextResult, bool contextAllowed) = _tryQueryPaymentAssetAllowed(manager, contextId, asset);
+        if (hasContextResult) {
+            if (contextAllowed) return true;
+            if (contextId == 0) return false;
+
+            (bool hasLegacyResult, bool legacyAllowed) = _tryQueryPaymentAssetAllowed(manager, 0, asset);
+            return hasLegacyResult ? legacyAllowed : false;
+        }
+
+        if (contextId != 0) {
+            (bool hasLegacyResult, bool legacyAllowed) = _tryQueryPaymentAssetAllowed(manager, 0, asset);
+            if (hasLegacyResult) return legacyAllowed;
+        }
+
+        // Hook missing/unimplemented: keep backwards compatibility.
+        return true;
+    }
+
+    function _tryQueryPaymentAssetAllowed(
+        address manager,
+        uint64 contextId,
+        address asset
+    )
+        private
+        view
+        returns (bool hasResult, bool allowed)
+    {
+        try IBlueprintServiceManager(manager).queryIsPaymentAssetAllowed(contextId, asset) returns (bool isAllowed) {
+            return (true, isAllowed);
+        } catch {
+            return (false, false);
+        }
+    }
+
     /// @notice Call manager with revert on failure
     function _callManager(address manager, bytes memory data) internal {
         (bool success, bytes memory returnData) = manager.call(data);

src/core/JobsRFQ.sol

@@ -84,6 +84,10 @@ abstract contract JobsRFQ is Base {
         uint64 effectiveMaxQuoteAge = _maxQuoteAge > 0 ? _maxQuoteAge : ProtocolConfig.MAX_QUOTE_AGE;
         uint256 totalPrice = _verifyQuotesAndRecordOperators(serviceId, jobIndex, quotes, effectiveMaxQuoteAge);
 
+        if (totalPrice > 0 && !_isPaymentAssetAllowedByManager(bp.manager, serviceId, address(0))) {
+            revert Errors.TokenNotAllowed(address(0));
+        }
+
         // Collect payment
         PaymentLib.collectPayment(address(0), totalPrice, msg.value);
         _recordPayment(msg.sender, serviceId, address(0), totalPrice);

src/core/JobsSubmission.sol

@@ -156,6 +156,10 @@ abstract contract JobsSubmission is Base {
         if (svc.pricing == Types.PricingModel.EventDriven) {
             uint256 perJob = _jobEventRates[svc.blueprintId][jobIndex];
             payment = perJob > 0 ? perJob : _blueprintConfigs[svc.blueprintId].eventRate;
+            address manager = _blueprints[svc.blueprintId].manager;
+            if (payment > 0 && !_isPaymentAssetAllowedByManager(manager, serviceId, address(0))) {
+                revert Errors.TokenNotAllowed(address(0));
+            }
             PaymentLib.collectPayment(address(0), payment, msgValue);
             _recordPayment(payer, serviceId, address(0), payment);
         }

src/core/Payments.sol

@@ -33,6 +33,7 @@ abstract contract Payments is Base, PaymentsEffectiveExposure {
     // ═══════════════════════════════════════════════════════════════════════════
 
     event EscrowFunded(uint64 indexed serviceId, address indexed token, uint256 amount);
+    event EscrowRefunded(uint64 indexed serviceId, address indexed owner, address indexed token, uint256 amount);
     event SubscriptionBilled(uint64 indexed serviceId, uint256 amount, uint64 period);
     event PaymentDistributed(
         uint64 indexed serviceId,
@@ -46,11 +47,7 @@ abstract contract Payments is Base, PaymentsEffectiveExposure {
         uint256 restakerPoolAmount
     );
     event OperatorRewardAccrued(
-        uint64 indexed serviceId,
-        address indexed operator,
-        address indexed token,
-        uint64 blueprintId,
-        uint256 amount
+        uint64 indexed serviceId, address indexed operator, address indexed token, uint64 blueprintId, uint256 amount
     );
     event RewardsClaimed(address indexed account, address indexed token, uint256 amount);
     event TntPaymentDiscountApplied(
@@ -76,15 +73,29 @@ abstract contract Payments is Base, PaymentsEffectiveExposure {
 
         PaymentLib.depositToEscrow(escrow, token, amount, msg.value);
 
-        // Refund excess ETH for native token payments
-        if (token == address(0) && msg.value > amount) {
-            PaymentLib.transferPayment(msg.sender, address(0), msg.value - amount);
-        }
-
         emit EscrowFunded(serviceId, token, amount);
         _recordPayment(msg.sender, serviceId, token, amount);
     }
 
+    /// @notice Withdraw remaining escrow balance after service termination
+    function withdrawRemainingEscrow(uint64 serviceId) external nonReentrant {
+        Types.Service storage svc = _getService(serviceId);
+        if (svc.status != Types.ServiceStatus.Terminated) {
+            revert Errors.ServiceNotTerminated(serviceId);
+        }
+
+        PaymentLib.ServiceEscrow storage escrow = _serviceEscrows[serviceId];
+        uint256 remaining = escrow.balance;
+        if (remaining == 0) revert Errors.ZeroAmount();
+
+        address token = escrow.token;
+        escrow.balance = 0;
+        escrow.totalReleased += remaining;
+
+        PaymentLib.transferPayment(svc.owner, token, remaining);
+        emit EscrowRefunded(serviceId, svc.owner, token, remaining);
+    }
+
     /// @notice Bill a subscription service
     /// @dev Anyone can call this to trigger billing; no incentive for single billing
     function billSubscription(uint64 serviceId) external nonReentrant {
@@ -429,12 +440,9 @@ abstract contract Payments is Base, PaymentsEffectiveExposure {
         // Protocol payment
         PaymentLib.transferPayment(_treasury, token, amounts.protocolAmount);
 
-        uint256 operatorPoolAmount = operatorsLength == 0
-            ? 0
-            : amounts.operatorAmount + (hasSecurityCommitments ? 0 : amounts.restakerAmount);
-        uint256 restakerPoolAmount = operatorsLength == 0
-            ? 0
-            : (hasSecurityCommitments ? amounts.restakerAmount : 0);
+        uint256 operatorPoolAmount =
+            operatorsLength == 0 ? 0 : amounts.operatorAmount + (hasSecurityCommitments ? 0 : amounts.restakerAmount);
+        uint256 restakerPoolAmount = operatorsLength == 0 ? 0 : (hasSecurityCommitments ? amounts.restakerAmount : 0);
 
         emit PaymentDistributed(
             serviceId,
@@ -470,11 +478,7 @@ abstract contract Payments is Base, PaymentsEffectiveExposure {
                 if (opPayments[i].operatorShare > 0) {
                     _pendingRewardTokens[opPayments[i].operator].add(token);
                     emit OperatorRewardAccrued(
-                        serviceId,
-                        opPayments[i].operator,
-                        token,
-                        blueprintId,
-                        opPayments[i].operatorShare
+                        serviceId, opPayments[i].operator, token, blueprintId, opPayments[i].operatorShare
                     );
                 }
 
@@ -502,13 +506,7 @@ abstract contract Payments is Base, PaymentsEffectiveExposure {
                 PaymentLib.addPendingReward(_pendingRewards, operators[i], token, share);
                 if (share > 0) {
                     _pendingRewardTokens[operators[i]].add(token);
-                    emit OperatorRewardAccrued(
-                        serviceId,
-                        operators[i],
-                        token,
-                        blueprintId,
-                        share
-                    );
+                    emit OperatorRewardAccrued(serviceId, operators[i], token, blueprintId, share);
                 }
                 distributed += share;
                 unchecked {

src/core/QuotesCreate.sol

@@ -6,7 +6,6 @@ import { EnumerableSet } from "@openzeppelin/contracts/utils/structs/EnumerableS
 import { Base } from "./Base.sol";
 import { Types } from "../libraries/Types.sol";
 import { Errors } from "../libraries/Errors.sol";
-import { PaymentLib } from "../libraries/PaymentLib.sol";
 import { SignatureLib } from "../libraries/SignatureLib.sol";
 import { IBlueprintServiceManager } from "../interfaces/IBlueprintServiceManager.sol";
 
@@ -53,7 +52,7 @@ abstract contract QuotesCreate is Base {
 
         uint256 totalCost = _verifyQuotesAndGetCost(quotes, blueprintId, ttl);
 
-        _ensureQuotePaymentAsset(bp.manager, totalCost);
+        _ensureQuotePaymentAsset(bp.manager, _serviceCount, totalCost);
         _collectQuotePayment(totalCost);
         _notifyManagerQuoteRequest(bp.manager, operators, config, ttl, totalCost);
 
@@ -103,11 +102,11 @@ abstract contract QuotesCreate is Base {
         }
     }
 
-    function _ensureQuotePaymentAsset(address manager, uint256 totalCost) private view {
+    function _ensureQuotePaymentAsset(address manager, uint64 quoteContextId, uint256 totalCost) private view {
         if (manager != address(0) && totalCost > 0) {
-            try IBlueprintServiceManager(manager).queryIsPaymentAssetAllowed(0, address(0)) returns (bool allowed) {
-                if (!allowed) revert Errors.TokenNotAllowed(address(0));
-            } catch { }
+            if (!_isPaymentAssetAllowedByManager(manager, quoteContextId, address(0))) {
+                revert Errors.TokenNotAllowed(address(0));
+            }
         }
     }
 
@@ -134,7 +133,7 @@ abstract contract QuotesCreate is Base {
             revert Errors.InsufficientPaymentForQuotes(totalCost, msg.value);
         }
         if (msg.value > totalCost) {
-            PaymentLib.transferPayment(msg.sender, address(0), msg.value - totalCost);
+            revert Errors.InvalidMsgValue(totalCost, msg.value);
         }
     }
 

src/core/QuotesExtend.sol

@@ -6,7 +6,6 @@ import { EnumerableSet } from "@openzeppelin/contracts/utils/structs/EnumerableS
 import { Base } from "./Base.sol";
 import { Types } from "../libraries/Types.sol";
 import { Errors } from "../libraries/Errors.sol";
-import { PaymentLib } from "../libraries/PaymentLib.sol";
 import { SignatureLib } from "../libraries/SignatureLib.sol";
 
 /// @title QuotesExtend
@@ -58,6 +57,10 @@ abstract contract QuotesExtend is Base {
         Types.Blueprint storage bp = _blueprints[svc.blueprintId];
         _requireBlueprintActive(bp, svc.blueprintId);
 
+        if (msg.value > 0) {
+            _requireManagerAllowsNativeExtension(bp.manager, serviceId);
+        }
+
         // Gather operators from quotes and verify they're current service operators
         address[] memory quoteOperators = _gatherQuoteOperators(quotes);
         _verifyQuoteOperatorsInService(serviceId, quoteOperators);
@@ -139,7 +142,14 @@ abstract contract QuotesExtend is Base {
             revert Errors.InsufficientPaymentForQuotes(totalCost, msg.value);
         }
         if (msg.value > totalCost) {
-            PaymentLib.transferPayment(msg.sender, address(0), msg.value - totalCost);
+            revert Errors.InvalidMsgValue(totalCost, msg.value);
+        }
+    }
+
+    function _requireManagerAllowsNativeExtension(address manager, uint64 serviceId) private view {
+        if (manager == address(0)) return;
+        if (!_isPaymentAssetAllowedByManager(manager, serviceId, address(0))) {
+            revert Errors.TokenNotAllowed(address(0));
         }
     }
 

src/core/ServicesRequests.sol

@@ -19,6 +19,7 @@ abstract contract ServicesRequests is Base {
     struct BlueprintRequestData {
         address manager;
         Types.MembershipModel membership;
+        Types.PricingModel pricing;
     }
 
     struct RequestBounds {
@@ -157,8 +158,10 @@ abstract contract ServicesRequests is Base {
         _validateServiceTtl(ttl);
 
         BlueprintRequestData memory blueprintData = _loadBlueprintRequestData(blueprintId);
+        _validatePricingPaymentConsistency(blueprintData.pricing, paymentToken);
 
-        _validateRequestPaymentAsset(blueprintData.manager, paymentToken, paymentAmount);
+        uint64 requestContextId = _serviceRequestCount;
+        _validateRequestPaymentAsset(blueprintData.manager, requestContextId, paymentToken, paymentAmount);
         _validateRequestOperators(blueprintId, operators, exposures);
 
         PaymentLib.collectPayment(paymentToken, paymentAmount, msg.value);
@@ -179,16 +182,27 @@ abstract contract ServicesRequests is Base {
         SchemaLib.validatePayload(_requestSchemas[blueprintId], config, Types.SchemaTarget.Request, blueprintId, 0);
     }
 
-    function _validateRequestPaymentAsset(address manager, address paymentToken, uint256 paymentAmount) private view {
+    function _validateRequestPaymentAsset(
+        address manager,
+        uint64 requestContextId,
+        address paymentToken,
+        uint256 paymentAmount
+    )
+        private
+        view
+    {
         if (manager == address(0) || paymentAmount == 0) {
             return;
         }
-        try IBlueprintServiceManager(manager).queryIsPaymentAssetAllowed(0, paymentToken) returns (bool allowed) {
-            if (!allowed) {
-                revert Errors.TokenNotAllowed(paymentToken);
-            }
-        } catch {
-            // If hook not implemented, allow any token (backwards compatible)
+        if (!_isPaymentAssetAllowedByManager(manager, requestContextId, paymentToken)) {
+            revert Errors.TokenNotAllowed(paymentToken);
+        }
+    }
+
+    function _validatePricingPaymentConsistency(Types.PricingModel pricing, address paymentToken) private pure {
+        // Event-driven services are currently native-settled for both initial and per-job payments.
+        if (pricing == Types.PricingModel.EventDriven && paymentToken != address(0)) {
+            revert Errors.InvalidPaymentToken();
         }
     }
 
@@ -331,6 +345,7 @@ abstract contract ServicesRequests is Base {
         if (!bp.active) revert Errors.BlueprintNotActive(blueprintId);
         data.manager = bp.manager;
         data.membership = bp.membership;
+        data.pricing = bp.pricing;
     }
 
     function _computeRequestBounds(