Proposal: Hierarchical Region Gating via TX Duty Cycle

[khagele]

Problem

MeshCore networks are vulnerable to disruption from intentional spammers, misconfigured nodes, or high-traffic events. See https://mc-spamdetector.nl/incidents?status=all&type=all&hours=0 for recent events on the NL mesh. For the Dutch mesh a volunteer group (NOC) is monitoring and trying to coordinate the mesh through such events.

Current mitigation relies on in-person triangulation and activation of the regional social clusters. When mitigation of such disruptive events using adjustments to the repeater configuration is possible, this either requires local repeater admin access or that the mesh is still functional enough to send/receive commands to the repeater remotely. During such events, the mesh is both not functional and at the same time wired access to repeaters is not easily obtained locally. To make the mesh more resilient to high-traffic events, this gate mechanism based on regions is proposed for discussion.

Proposed Mechanism

Repeaters autonomously gate inter-region traffic based on locally measured TX duty cycle. Each repeater has a configured region list, where order defines priority:

nl-ge-nij (local cluster, highest priority)
 └─ nl-ge
    └─ nl
      └─ eu

When TX duty cycle exceeds a configurable threshold T1, the repeater progressively drops traffic from the back of the list forward:

1. Duty cycle > T1 → stop forwarding eu traffic
2. Still above threshold → stop forwarding nl traffic
3. Still above threshold → stop forwarding nl-ge traffic
4. Last nl-ge-nij cluster always protected

Recovery
As duty cycle drops below T_recover (where T_recover < T1), the repeater re-enables regions from the innermost outward, one step at a time. The gap between T1 and T_recover provides hysteresis, preventing rapid oscillation. One known risk: when an event ends, repeaters independently observe the drop at roughly the same time and begin re-enabling simultaneously, potentially causing a brief surge of traffic that re-triggers gating. A small randomised per-repeater recovery delay (e.g. 0-30s jitter per step) would reduce this risk.

TX duty cycle
TX duty cycle is a locally observable metric. Each repeater acts independently based on its own radio behaviour, preserving the decentralised nature of the mesh.

Failure behaviour
Under sustained disruption, the mesh degrades gracefully: each repeater converges on its smallest sustainable local cluster. The network self-partitions into isolated but functional local cells rather than collapsing entirely. Once disruption subsides, the mesh recovers outward, restoring broader connectivity step by step.

Notes

• Requires hierarchy in the regions configuration
• Thresholds, TX duty cycle window length, and hysteresis values are parameters to be defined
• This mechanism protects other regions (ie "the broader mesh") from a local event. It does not protect a local cluster from a local source.

Path Forward

This proposal has been shared in the Dutch MeshCore communities, both on the mesh and in Telegram, and is refined based on feedback. Next steps: continue refining the pitch based on broader discussion. If this is considered a viable proposal (since I'm not developing myself and rather not want to introduce AI code I don't understand) gather volunteers to develop and implement as a custom firmware feature to test on an observed mesh segment, gather duty cycle needed parameters data, and submit a PR if results support it.

[titusn]

Your proposal has elements of the circuit breaker pattern (see Release It, Nygard 2018) in it. This is a good pattern and it would be worth looking into what this means for router implementation as you suggest, but also be how the protocol can implement a proper retry with backoff (see same ref) mechanism for calling devices to reduce network flooding.

Apart from that, I would suggest adding an extra protected layer for admins, so they always get reserved airtime to connect to a node. One could think of creating a private "region" with a random generated name as the lowest fallback level or reserving a small part of the duty cycle for messages with a specific key. This needs to be investigated.

[LennertVA]

Elegant and useful - but if I read it correctly, it depends on having one single hierarchical chain of regions. This is not guaranteed; a repeater can have multiple regions on the same level (which is what is looked into here in CZ now). How would this proposal handle such a case?

It would add a nice extra dimension to #1502 - this proposal for protecting the network from general overload, the other for rate limiting the impact one individual sender can cause on the network.

[fizzyfuzzle]

@khagele After I saw your document, I really liked the idea, so I implemented a POC to test in my firmware.

Basically I created some methods in the RegionMap class, to Enable or Disable regions on a certain 'depth' of the hierarchy:

  uint8_t getMaxDepth(uint8_t indent, const RegionEntry* parent) {
    uint8_t maxDepth = indent;
    uint16_t parentId = parent ? parent->id : 0;

    for (int i = 0; i < num_regions; ++i) {
      const RegionEntry* r = &regions[i];
      if (r->id == 0) continue;
      if (r->parent == parentId) {
        int childDepth = getMaxDepth(indent + 1, r);
        if (childDepth > maxDepth) maxDepth = childDepth;
      }
    }
    return maxDepth;
  }

  void limit(uint8_t indent, const RegionEntry* parent, uint8_t depth, bool enable) {
    uint16_t parentId = parent ? parent->id : 0;

    // skip wildcard
    if (depth == 0) return;

    for (int i = 0; i < num_regions; ++i) {
      RegionEntry* r = &regions[i];
      if (r->id == 0) continue;
      if (r->parent == parentId) {
        int childDepth = indent + 1;
        if (childDepth == depth) {
          if (enable) r->flags &= (uint8_t)~REGION_DENY_FLOOD;
          else        r->flags |= (uint8_t)REGION_DENY_FLOOD;
        } else if (childDepth < depth) {
          limit(childDepth, r, depth, enable);
        }
      }
    }
  }

So with this you can do something like:

  // update dutycycle regions limits
  if (millisHasNowPassed(duty_cycle_limits_next_update)) {
    float duty_cycle = 1.0f / (1.0f + getAirtimeBudgetFactor());
    float max_budget = getDutyCycleWindowMs() * duty_cycle;
    float duty_cycle_perc = (1.0f - getRemainingTxBudget() / max_budget) * 100.0f;
    uint8_t maxDepth = region_map.getMaxDepth(0, nullptr);

    if (duty_cycle_limits_depth < maxDepth - 1 && duty_cycle_perc > duty_cycle_limits_threshold) {
      duty_cycle_limits_depth++;
      region_map.limit(0, nullptr, duty_cycle_limits_depth, false);
    } else if (duty_cycle_limits_depth && duty_cycle_perc < duty_cycle_limits_threshold * 0.99f) {
      region_map.limit(0, nullptr, duty_cycle_limits_depth, true);
      duty_cycle_limits_depth--;
    }
    duty_cycle_limits_next_update = futureMillis(duty_cycle_limits_interval*1000);
  }

So every interval it will check if the dutycycle is above or beyond a certain threshold level and enable or disable the following 'depth' of regions hierarchy. It will stop 1 level before the 'leafs', so the smallest regions in the hierarchy will always stay enabled.

The 'cool' thing with this is, you can also see the enabled/disabled status of the regions in the 'Manage Regions' section of remote admin in the app 🤓

Hope it can help someone 🤓