feat(dips): admit non-manager proposal senders backed by escrow

Senders that hold no on-chain agreement-manager role were rejected outright. This admits
one when its recovered signer resolves to escrow at or above a configurable minimum
(default 1 GRT); an empty snapshot is transient so a funded sender isn't branded unfunded.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

Author: MoonBoi9001

crates/config/src/config.rs

@@ -694,6 +694,10 @@ pub struct DipsConfig {
     /// Max seconds the role subgraph head may lag wall-clock before its data is
     /// treated as unreliable. 0 disables the check.
     pub role_subgraph_max_lag_secs: u64,
+    /// Minimum escrow balance an untrusted sender's recovered signer must hold to
+    /// pass the escrow fallback. TODO: derive from the configured price minimum
+    /// plus a buffer for unknown entity counts instead of using a flat floor.
+    pub min_escrow_grt: GRT,
 }
 
 impl Default for DipsConfig {
@@ -709,6 +713,7 @@ impl Default for DipsConfig {
             role_refresh_interval_secs: 86_400,
             role_failopen_grace_secs: 3_600,
             role_subgraph_max_lag_secs: 1_800,
+            min_escrow_grt: GRT::ONE,
         }
     }
 }

crates/config/src/grt.rs

@@ -12,6 +12,8 @@ pub struct GRT(u128);
 
 impl GRT {
     pub const ZERO: GRT = GRT(0);
+    /// One GRT in wei (10^18).
+    pub const ONE: GRT = GRT(1_000_000_000_000_000_000);
 
     /// Convert GRT string to wei for test construction.
     /// Panics on invalid input - only use in tests.

crates/dips/src/escrow.rs

@@ -0,0 +1,87 @@
+// Copyright 2023-, Edge & Node, GraphOps, and Semiotic Labs.
+// SPDX-License-Identifier: Apache-2.0
+
+//! Escrow fallback for agreement-proposal senders that are not on-chain agreement
+//! managers: the role gate would reject them, but this lets one through when its
+//! recovered signer resolves to a payer with enough escrow (a limited permissionless path).
+
+use thegraph_core::alloy::primitives::{Address, U256};
+
+/// Outcome of looking a signer up in the escrow snapshot.
+#[derive(Debug, Clone, Copy, PartialEq, Eq)]
+pub enum EscrowLookup {
+    /// The snapshot has no signers at all (cold start or total outage), so the
+    /// answer is "can't tell" rather than "unfunded".
+    Unavailable,
+    /// The signer resolved to a funded payer holding this balance (wei).
+    Balance(U256),
+    /// The snapshot is populated but the signer is not a funded payer.
+    NotFound,
+}
+
+/// Read-side view of the escrow snapshot, keyed on the cryptographically
+/// recovered signer (never a caller-written proposal field).
+pub trait EscrowSource: std::fmt::Debug + Send + Sync {
+    fn lookup(&self, signer: Address) -> EscrowLookup;
+}
+
+/// A fixed escrow snapshot. Used in tests and as a simple in-memory source;
+/// production uses the shared TAP escrow watcher.
+#[derive(Debug, Clone, Default)]
+pub struct StaticEscrow(pub std::collections::HashMap<Address, U256>);
+
+impl EscrowSource for StaticEscrow {
+    fn lookup(&self, signer: Address) -> EscrowLookup {
+        if self.0.is_empty() {
+            return EscrowLookup::Unavailable;
+        }
+        match self.0.get(&signer) {
+            Some(balance) => EscrowLookup::Balance(*balance),
+            None => EscrowLookup::NotFound,
+        }
+    }
+}
+
+#[cfg(feature = "db")]
+impl EscrowSource for indexer_monitor::EscrowAccountsWatcher {
+    fn lookup(&self, signer: Address) -> EscrowLookup {
+        let snapshot = self.borrow();
+        if snapshot.signer_count() == 0 {
+            return EscrowLookup::Unavailable;
+        }
+        match snapshot.get_balance_for_signer(&signer) {
+            Ok(balance) => EscrowLookup::Balance(balance),
+            Err(_) => EscrowLookup::NotFound,
+        }
+    }
+}
+
+#[cfg(test)]
+mod test {
+    use thegraph_core::alloy::primitives::{address, U256};
+
+    use super::*;
+
+    const SIGNER: Address = address!("f39fd6e51aad88f6f4ce6ab8827279cfffb92266");
+
+    #[test]
+    fn empty_snapshot_is_unavailable() {
+        assert_eq!(
+            StaticEscrow::default().lookup(SIGNER),
+            EscrowLookup::Unavailable
+        );
+    }
+
+    #[test]
+    fn known_signer_returns_balance() {
+        let escrow = StaticEscrow([(SIGNER, U256::from(5))].into_iter().collect());
+        assert_eq!(escrow.lookup(SIGNER), EscrowLookup::Balance(U256::from(5)));
+    }
+
+    #[test]
+    fn populated_snapshot_without_signer_is_not_found() {
+        let other = Address::repeat_byte(0x11);
+        let escrow = StaticEscrow([(other, U256::from(5))].into_iter().collect());
+        assert_eq!(escrow.lookup(SIGNER), EscrowLookup::NotFound);
+    }
+}

crates/dips/src/lib.rs

@@ -50,6 +50,7 @@
 
 use std::sync::Arc;
 
+use escrow::{EscrowLookup, EscrowSource};
 use server::DipsServerContext;
 use thegraph_core::alloy::{
     core::primitives::Address,
@@ -61,6 +62,7 @@ use thegraph_core::alloy::{
 
 #[cfg(feature = "db")]
 pub mod database;
+pub mod escrow;
 pub mod inflight;
 pub mod ipfs;
 pub mod price;
@@ -200,6 +202,10 @@ pub enum DipsError {
     SenderNotTrusted { signer: Address },
     #[error("could not verify sender authorisation: {0}")]
     TrustVerificationUnavailable(String),
+    #[error("sender {signer} has insufficient escrow to send agreement proposals")]
+    InsufficientEscrow { signer: Address },
+    #[error("could not verify sender escrow: {0}")]
+    EscrowVerificationUnavailable(String),
 }
 
 #[cfg(feature = "rpc")]
@@ -285,6 +291,25 @@ pub(crate) fn try_extract_deployment_id(rca_bytes: &[u8]) -> Option<String> {
     Some(bytes32_to_ipfs_hash(&metadata.subgraphDeploymentId.0))
 }
 
+/// Authorize an untrusted sender by escrow: a resolved balance at or above
+/// `min_wei` passes; below or absent is InsufficientEscrow; a wholesale-empty
+/// snapshot is transient, so a funded sender isn't branded unfunded during an outage.
+fn verify_escrow(
+    escrow: &dyn EscrowSource,
+    signer: Address,
+    min_wei: U256,
+) -> Result<(), DipsError> {
+    match escrow.lookup(signer) {
+        EscrowLookup::Balance(balance) if balance >= min_wei => Ok(()),
+        EscrowLookup::Balance(_) | EscrowLookup::NotFound => {
+            Err(DipsError::InsufficientEscrow { signer })
+        }
+        EscrowLookup::Unavailable => Err(DipsError::EscrowVerificationUnavailable(
+            "escrow snapshot is empty".to_string(),
+        )),
+    }
+}
+
 /// Validate and create a RecurringCollectionAgreement.
 ///
 /// Performs validation:
@@ -310,17 +335,27 @@ pub async fn validate_and_create_rca(
         additional_networks,
         rca_domain,
         trusted_signers,
+        escrow_source,
+        min_escrow_wei,
     } = ctx.as_ref();
 
     // Decode SignedRCA
     let signed_rca = SignedRecurringCollectionAgreement::abi_decode(rca_bytes.as_ref())
         .map_err(|e| DipsError::AbiDecoding(e.to_string()))?;
 
     // Authenticate then authorize the sender: recover the EIP-712 signer, then
-    // require it to hold the on-chain agreement-manager role before doing any work.
+    // require it to be an on-chain agreement manager, or else a payer with escrow.
     let signer = signed_rca.recover_signer(rca_domain)?;
     tracing::debug!(%signer, "recovered RCA signer");
-    trusted_signers.verify_trusted(signer).await?;
+    match trusted_signers.verify_trusted(signer).await {
+        Ok(()) => {}
+        // Not a manager: fall back to an escrow check on the recovered signer
+        // rather than rejecting; a transient role error stays transient.
+        Err(DipsError::SenderNotTrusted { .. }) => {
+            verify_escrow(escrow_source.as_ref(), signer, *min_escrow_wei)?;
+        }
+        Err(transient) => return Err(transient),
+    }
 
     // Validate service provider
     signed_rca.validate(expected_service_provider)?;
@@ -466,6 +501,7 @@ mod test {
 
     use crate::{
         derive_agreement_id,
+        escrow::StaticEscrow,
         ipfs::{FailingIpfsFetcher, MockIpfsFetcher},
         price::PriceCalculator,
         rca_eip712_domain,
@@ -513,21 +549,16 @@ mod test {
             additional_networks: Arc::new(BTreeMap::new()),
             rca_domain: test_rca_domain(),
             trusted_signers: trusted_signers_for_test(),
+            escrow_source: Arc::new(StaticEscrow::default()),
+            min_escrow_wei: U256::ZERO,
         })
     }
 
-    #[tokio::test]
-    async fn test_validate_and_create_rca_untrusted_signer_rejected() {
-        let service_provider = Address::repeat_byte(0x11);
-        let rca = create_test_rca(
-            Address::repeat_byte(0x42),
-            service_provider,
-            U256::from(200),
-            U256::from(100),
-        );
-
-        // Trusted set excludes the test signer, so a valid signature is rejected.
-        let ctx = Arc::new(DipsServerContext {
+    /// A context whose trusted set is empty (so the recovered signer is never a
+    /// role holder), with a fixed escrow snapshot and minimum, to exercise C's
+    /// escrow fallback path.
+    fn untrusted_escrow_ctx(escrow: StaticEscrow, min_escrow_wei: U256) -> Arc<DipsServerContext> {
+        Arc::new(DipsServerContext {
             rca_store: Arc::new(InMemoryRcaStore::default()),
             ipfs_fetcher: Arc::new(MockIpfsFetcher::default()),
             price_calculator: Arc::new(PriceCalculator::new(
@@ -539,12 +570,97 @@ mod test {
             additional_networks: Arc::new(BTreeMap::new()),
             rca_domain: test_rca_domain(),
             trusted_signers: Arc::new(StaticTrustedSigners::default()),
-        });
-        let rca_bytes = rca_to_wire_bytes(rca);
+            escrow_source: Arc::new(escrow),
+            min_escrow_wei,
+        })
+    }
 
-        let result = super::validate_and_create_rca(ctx, &service_provider, rca_bytes).await;
+    #[tokio::test]
+    async fn untrusted_sender_with_sufficient_escrow_passes() {
+        let service_provider = Address::repeat_byte(0x11);
+        let rca = create_test_rca(
+            Address::repeat_byte(0x42),
+            service_provider,
+            U256::from(200),
+            U256::from(100),
+        );
+        // The recovered signer (test_signer) holds 2 wei; the minimum is 1.
+        let escrow = StaticEscrow(
+            [(test_signer().address(), U256::from(2))]
+                .into_iter()
+                .collect(),
+        );
+        let ctx = untrusted_escrow_ctx(escrow, U256::from(1));
+
+        let result =
+            super::validate_and_create_rca(ctx, &service_provider, rca_to_wire_bytes(rca)).await;
+
+        assert!(result.is_ok(), "got: {:?}", result);
+    }
+
+    #[tokio::test]
+    async fn untrusted_sender_below_minimum_is_insufficient() {
+        let service_provider = Address::repeat_byte(0x11);
+        let rca = create_test_rca(
+            Address::repeat_byte(0x42),
+            service_provider,
+            U256::from(200),
+            U256::from(100),
+        );
+        let escrow = StaticEscrow(
+            [(test_signer().address(), U256::from(1))]
+                .into_iter()
+                .collect(),
+        );
+        let ctx = untrusted_escrow_ctx(escrow, U256::from(5));
+
+        let result =
+            super::validate_and_create_rca(ctx, &service_provider, rca_to_wire_bytes(rca)).await;
+
+        assert!(matches!(result, Err(DipsError::InsufficientEscrow { .. })));
+    }
 
-        assert!(matches!(result, Err(DipsError::SenderNotTrusted { .. })));
+    #[tokio::test]
+    async fn untrusted_sender_absent_from_escrow_is_insufficient() {
+        let service_provider = Address::repeat_byte(0x11);
+        let rca = create_test_rca(
+            Address::repeat_byte(0x42),
+            service_provider,
+            U256::from(200),
+            U256::from(100),
+        );
+        // Snapshot has a different address, so it is populated but not the signer.
+        let escrow = StaticEscrow(
+            [(Address::repeat_byte(0xEE), U256::from(99))]
+                .into_iter()
+                .collect(),
+        );
+        let ctx = untrusted_escrow_ctx(escrow, U256::from(1));
+
+        let result =
+            super::validate_and_create_rca(ctx, &service_provider, rca_to_wire_bytes(rca)).await;
+
+        assert!(matches!(result, Err(DipsError::InsufficientEscrow { .. })));
+    }
+
+    #[tokio::test]
+    async fn untrusted_sender_with_empty_snapshot_is_transient() {
+        let service_provider = Address::repeat_byte(0x11);
+        let rca = create_test_rca(
+            Address::repeat_byte(0x42),
+            service_provider,
+            U256::from(200),
+            U256::from(100),
+        );
+        let ctx = untrusted_escrow_ctx(StaticEscrow::default(), U256::from(1));
+
+        let result =
+            super::validate_and_create_rca(ctx, &service_provider, rca_to_wire_bytes(rca)).await;
+
+        assert!(matches!(
+            result,
+            Err(DipsError::EscrowVerificationUnavailable(_))
+        ));
     }
 
     /// Sign an RCA with the fixed test key over the test domain and ABI-encode
@@ -891,6 +1007,8 @@ mod test {
             additional_networks: Arc::new(BTreeMap::new()),
             rca_domain: test_rca_domain(),
             trusted_signers: trusted_signers_for_test(),
+            escrow_source: Arc::new(StaticEscrow::default()),
+            min_escrow_wei: U256::ZERO,
         });
 
         let rca_bytes = rca_to_wire_bytes(rca);
@@ -1066,6 +1184,8 @@ mod test {
             additional_networks: Arc::new(BTreeMap::new()),
             rca_domain: test_rca_domain(),
             trusted_signers: trusted_signers_for_test(),
+            escrow_source: Arc::new(StaticEscrow::default()),
+            min_escrow_wei: U256::ZERO,
         });
 
         let rca_bytes = rca_to_wire_bytes(rca);
@@ -1102,6 +1222,8 @@ mod test {
             additional_networks: Arc::new(BTreeMap::new()),
             rca_domain: test_rca_domain(),
             trusted_signers: trusted_signers_for_test(),
+            escrow_source: Arc::new(StaticEscrow::default()),
+            min_escrow_wei: U256::ZERO,
         });
 
         let rca_bytes = rca_to_wire_bytes(rca);
@@ -1138,6 +1260,8 @@ mod test {
             additional_networks: Arc::new(BTreeMap::new()),
             rca_domain: test_rca_domain(),
             trusted_signers: trusted_signers_for_test(),
+            escrow_source: Arc::new(StaticEscrow::default()),
+            min_escrow_wei: U256::ZERO,
         });
 
         let rca_bytes = rca_to_wire_bytes(rca);