fix(pow): keep adaptive difficulty scoped to eventId, not pubkey

Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
Signed-off-by: Priyanshubhartistm <bhartipriyanshustm@gmail.com>

Author: Priyanshubhartistm

CONFIGURATION.md

@@ -162,13 +162,13 @@ The settings below are listed in alphabetical order by name. Please keep this ta
 | limits.event.eventId.minLeadingZeroBits     | Leading zero bits required on every incoming event for proof of work. Defaults to zero. Disabled when set to zero. Ignored on the client path while `limits.event.pow.enabled` is true (mirrored events from `static-mirroring-worker.ts` still enforce this static value). |
 | limits.event.kind.blacklist                 | List of event kinds to always reject. Leave empty to allow any. |
 | limits.event.kind.whitelist                 | List of event kinds to always allow. Leave empty to allow any. |
-| limits.event.pow.ceilingBits                | Maximum adaptive PoW difficulty, reached at 2x `targetEventsPerSecond` and beyond. |
-| limits.event.pow.enabled                    | Enables load-aware PoW difficulty scaling, applied to both eventId and pubkey checks, in place of the static `minLeadingZeroBits` values. Defaults to false. |
-| limits.event.pow.floorBits                  | Minimum adaptive PoW difficulty, used at or under `targetEventsPerSecond`. |
+| limits.event.pow.ceilingBits                | Maximum adaptive PoW difficulty, reached at approximately 2x `targetEventsPerSecond` and beyond. |
+| limits.event.pow.enabled                    | Enables load-aware PoW difficulty scaling on the eventId check only, in place of the static `eventId.minLeadingZeroBits` value. Does not affect `pubkey.minLeadingZeroBits`, which stays a static, non-adaptive knob regardless of this setting -- a pubkey requirement is a one-time offline identity cost, not a per-event load signal. Defaults to false. |
+| limits.event.pow.floorBits                  | Minimum adaptive PoW difficulty, used at or below approximately `targetEventsPerSecond`. With the default `floorBits: 0`, the load signal costs an attacker nothing to drive; set a non-zero floor if the gate should cost something even under light load. |
 | limits.event.pow.periodMs                   | EWMA half-life (ms) used to smooth the observed event rate. |
-| limits.event.pow.targetEventsPerSecond      | Event-rate threshold above which the adaptive difficulty starts climbing toward `ceilingBits`. |
+| limits.event.pow.targetEventsPerSecond      | Event-rate threshold (in real events/sec) above which the adaptive difficulty starts climbing toward `ceilingBits`. |
 | limits.event.pubkey.blacklist               | List of public keys to always reject. Public keys in this list will not be able to post to this relay. |
-| limits.event.pubkey.minLeadingZeroBits      | Leading zero bits required on the public key of incoming events for proof of work. Defaults to zero. Disabled when set to zero. Ignored on the client path while `limits.event.pow.enabled` is true (mirrored events from `static-mirroring-worker.ts` still enforce this static value). |
+| limits.event.pubkey.minLeadingZeroBits      | Leading zero bits required on the public key of incoming events for proof of work. Defaults to zero. Disabled when set to zero. Always enforced regardless of `limits.event.pow.enabled` -- adaptive PoW never applies to the pubkey check (see `limits.event.pow.enabled`). |
 | limits.event.pubkey.whitelist               | List of public keys to always allow. Only public keys in this list will be able to post to this relay. Use for private relays. |
 | limits.event.rateLimits[].kinds             | List of event kinds rate limited. Use `[min, max]` for ranges. Optional. |
 | limits.event.rateLimits[].period | Rate limiting period in milliseconds. For `sliding_window`: the time window during which requests are counted. For `ewma`: the half-life of the exponential decay — shorter values forget bursts faster, longer values are stricter on bursty clients. |

resources/default-settings.yaml

@@ -218,9 +218,10 @@ limits:
         whitelist: []
     eventId:
       minLeadingZeroBits: 0
-    # Adaptive PoW: scales the required difficulty (applied to both eventId
-    # and pubkey checks) with observed relay load instead of using a fixed
-    # minLeadingZeroBits value. Disabled by default.
+    # Adaptive PoW: scales the required difficulty on the eventId check with
+    # observed relay load instead of using a fixed minLeadingZeroBits value.
+    # Does not affect the pubkey check above -- that stays static regardless.
+    # Disabled by default.
     pow:
       enabled: false
       floorBits: 0

src/@types/settings.ts

@@ -93,13 +93,13 @@ export interface EventRetentionLimits {
 }
 
 export interface AdaptivePowSettings {
-  /** Enables load-aware difficulty scaling; replaces the eventId/pubkey minLeadingZeroBits checks while enabled. Defaults to false. */
+  /** Enables load-aware difficulty scaling on the eventId check, replacing eventId.minLeadingZeroBits while enabled. Does not affect the pubkey check -- pubkey.minLeadingZeroBits stays a static, non-adaptive knob. Defaults to false. */
   enabled: boolean
-  /** Minimum required difficulty, used at/under targetEventsPerSecond. */
+  /** Minimum required difficulty, used at or below approximately targetEventsPerSecond. */
   floorBits: number
-  /** Maximum required difficulty, reached at 2x targetEventsPerSecond and beyond. */
+  /** Maximum required difficulty, reached at approximately 2x targetEventsPerSecond and beyond. */
   ceilingBits: number
-  /** Event-rate threshold (same EWMA scale as limits.event.rateLimits) above which difficulty starts climbing. */
+  /** Event-rate threshold, in real events/sec, above which difficulty starts climbing toward ceilingBits. */
   targetEventsPerSecond: number
   /** EWMA half-life in ms used to smooth the observed event rate. */
   periodMs: number

src/handlers/event-message-handler.ts

@@ -132,10 +132,12 @@ export class EventMessageHandler implements IMessageHandler {
     }
 
     // Recorded here, not inside canAcceptEvent's PoW branch: only events that
-    // clear every admission check (PoW, blacklist, auth, NIP-05, dedup, ...)
-    // should count toward the load signal. Recording earlier would let cheap,
-    // easily-rejected spam (e.g. from rotating pubkeys) push the difficulty to
-    // ceiling for everyone without the attacker ever doing any real work.
+    // clear every admission check up to this point (PoW, blacklist, auth,
+    // NIP-05, ...) should count toward the load signal. Recording earlier
+    // would let cheap, easily-rejected spam (e.g. from rotating pubkeys) push
+    // the difficulty to ceiling for everyone without the attacker ever doing
+    // any real work. Note: a duplicate/no-op write still counts here, since
+    // dedup is decided later inside the event strategy's own execute().
     const powSettings = this.settings().limits?.event?.pow
     if (powSettings?.enabled) {
       recordAdaptivePowEvent(powSettings.periodMs)
@@ -209,31 +211,29 @@ export class EventMessageHandler implements IMessageHandler {
       return `rejected: created_at is more than ${limits.createdAt.maxNegativeDelta} seconds in the past`
     }
 
+    // Adaptive PoW applies to the eventId check only: a pubkey requirement is a
+    // one-time, offline identity cost, not a per-event load signal, so it can't
+    // respond to relay load the way an event id's mined-per-submission pow can.
+    // The static pubkey.minLeadingZeroBits knob is left untouched regardless of
+    // pow.enabled -- per maintainer direction on PR #756.
     if (limits.pow?.enabled) {
       const requiredBits = getAdaptivePowDifficulty(limits.pow)
 
       const pow = getEventProofOfWork(event.id)
       if (pow < requiredBits) {
         return `pow: difficulty ${pow}<${requiredBits}`
       }
-
-      const pubkeyPow = getPubkeyProofOfWork(event.pubkey)
-      if (pubkeyPow < requiredBits) {
-        return `pow: pubkey difficulty ${pubkeyPow}<${requiredBits}`
-      }
-    } else {
-      if (typeof limits.eventId?.minLeadingZeroBits !== 'undefined' && limits.eventId.minLeadingZeroBits > 0) {
-        const pow = getEventProofOfWork(event.id)
-        if (pow < limits.eventId.minLeadingZeroBits) {
-          return `pow: difficulty ${pow}<${limits.eventId.minLeadingZeroBits}`
-        }
+    } else if (typeof limits.eventId?.minLeadingZeroBits !== 'undefined' && limits.eventId.minLeadingZeroBits > 0) {
+      const pow = getEventProofOfWork(event.id)
+      if (pow < limits.eventId.minLeadingZeroBits) {
+        return `pow: difficulty ${pow}<${limits.eventId.minLeadingZeroBits}`
       }
+    }
 
-      if (typeof limits.pubkey?.minLeadingZeroBits !== 'undefined' && limits.pubkey.minLeadingZeroBits > 0) {
-        const pow = getPubkeyProofOfWork(event.pubkey)
-        if (pow < limits.pubkey.minLeadingZeroBits) {
-          return `pow: pubkey difficulty ${pow}<${limits.pubkey.minLeadingZeroBits}`
-        }
+    if (typeof limits.pubkey?.minLeadingZeroBits !== 'undefined' && limits.pubkey.minLeadingZeroBits > 0) {
+      const pow = getPubkeyProofOfWork(event.pubkey)
+      if (pow < limits.pubkey.minLeadingZeroBits) {
+        return `pow: pubkey difficulty ${pow}<${limits.pubkey.minLeadingZeroBits}`
       }
     }
 

src/utils/settings-config.ts

@@ -598,6 +598,9 @@ export const validateSettings = (settings: Settings): ValidationIssue[] => {
     if (!(pow.floorBits >= 0) || !(pow.floorBits <= pow.ceilingBits)) {
       issues.push({ path: 'limits.event.pow.floorBits', message: 'floorBits must be >= 0 and <= ceilingBits' })
     }
+    if (!(pow.ceilingBits <= 256)) {
+      issues.push({ path: 'limits.event.pow.ceilingBits', message: 'ceilingBits must be <= 256' })
+    }
     if (!(pow.periodMs > 0)) {
       issues.push({ path: 'limits.event.pow.periodMs', message: 'periodMs must be greater than 0' })
     }

test/unit/handlers/event-message-handler.spec.ts

@@ -575,7 +575,7 @@ describe('EventMessageHandler', () => {
             periodMs: 60000,
           }
           event.id = '00' + 'f'.repeat(62) // 8 leading zero bits
-          event.pubkey = '00001' + 'f'.repeat(59) // well above the floor
+          event.pubkey = '00001' + 'f'.repeat(59) // irrelevant here: pubkey.minLeadingZeroBits is unset
 
           expect((handler as any).canAcceptEvent(event)).to.be.undefined
         })
@@ -593,7 +593,7 @@ describe('EventMessageHandler', () => {
           expect((handler as any).canAcceptEvent(event)).to.equal('pow: difficulty 8<9')
         })
 
-        it('checks pubkey proof of work against the adaptive difficulty too', () => {
+        it('does not apply the adaptive difficulty to the pubkey check', () => {
           eventLimits.pow = {
             enabled: true,
             floorBits: 9,
@@ -602,9 +602,26 @@ describe('EventMessageHandler', () => {
             periodMs: 60000,
           }
           event.id = '0001' + 'f'.repeat(60) // sufficient eventId pow
-          event.pubkey = '00' + 'f'.repeat(62) // 8 leading zero bits, insufficient
+          event.pubkey = '00' + 'f'.repeat(62) // 8 leading zero bits -- below the adaptive floor of 9
 
-          expect((handler as any).canAcceptEvent(event)).to.equal('pow: pubkey difficulty 8<9')
+          // pubkey.minLeadingZeroBits is unset (0/disabled), so this must pass:
+          // adaptive PoW never gates the pubkey axis, only eventId.
+          expect((handler as any).canAcceptEvent(event)).to.be.undefined
+        })
+
+        it('still enforces the static pubkey.minLeadingZeroBits setting while adaptive pow is enabled', () => {
+          eventLimits.pubkey.minLeadingZeroBits = 16
+          eventLimits.pow = {
+            enabled: true,
+            floorBits: 0,
+            ceilingBits: 24,
+            targetEventsPerSecond: 100,
+            periodMs: 60000,
+          }
+          event.id = '0001' + 'f'.repeat(60) // sufficient eventId pow (floor is 0 anyway)
+          event.pubkey = '00' + 'f'.repeat(62) // 8 leading zero bits, insufficient against the static 16
+
+          expect((handler as any).canAcceptEvent(event)).to.equal('pow: pubkey difficulty 8<16')
         })
 
         it('scales the required difficulty up as the sustained recorded rate exceeds target', () => {
@@ -616,7 +633,7 @@ describe('EventMessageHandler', () => {
             periodMs: 60000,
           }
           event.id = '00' + 'f'.repeat(62) // 8 leading zero bits, passes only the floor
-          event.pubkey = '00001' + 'f'.repeat(59) // well above floor and the scaled-up ceiling used here
+          event.pubkey = '00001' + 'f'.repeat(59) // irrelevant here: pubkey.minLeadingZeroBits is unset
 
           // canAcceptEvent only reads the current difficulty -- it no longer records
           // load itself (that now happens in handleMessage, after full acceptance).
@@ -644,7 +661,7 @@ describe('EventMessageHandler', () => {
             periodMs: 60000,
           }
           event.id = '00' + 'f'.repeat(62) // 8 leading zero bits
-          event.pubkey = '00001' + 'f'.repeat(59) // well above the floor
+          event.pubkey = '00001' + 'f'.repeat(59) // irrelevant here: pubkey.minLeadingZeroBits is unset
 
           ;(handler as any).canAcceptEvent(event)
           ;(handler as any).canAcceptEvent(event)
@@ -653,7 +670,7 @@ describe('EventMessageHandler', () => {
           expect(getCurrentRate()).to.equal(0)
         })
 
-        it('ignores the static minLeadingZeroBits settings while adaptive pow is enabled', () => {
+        it('ignores the static eventId.minLeadingZeroBits setting while adaptive pow is enabled', () => {
           eventLimits.eventId.minLeadingZeroBits = 40
           eventLimits.pow = {
             enabled: true,

test/unit/utils/settings-config.spec.ts

@@ -131,6 +131,23 @@ describe('settings-config', () => {
       expect(issues.some((issue) => issue.path === 'limits.event.pow.floorBits')).to.equal(true)
     })
 
+    it('rejects a ceilingBits above 256', () => {
+      const settings = baseSettings()
+      settings.limits.event.pow.ceilingBits = 300
+
+      const issues = validateSettings(settings)
+      expect(issues.some((issue) => issue.path === 'limits.event.pow.ceilingBits')).to.equal(true)
+    })
+
+    it('accepts a ceilingBits of exactly 256', () => {
+      const settings = baseSettings()
+      settings.limits.event.pow.ceilingBits = 256
+      settings.limits.event.pow.floorBits = 0
+
+      const issues = validateSettings(settings)
+      expect(issues.some((issue) => issue.path === 'limits.event.pow.ceilingBits')).to.equal(false)
+    })
+
     it('rejects a non-positive periodMs', () => {
       const settings = baseSettings()
       settings.limits.event.pow.periodMs = 0