IPIP: On-Demand Pinning Based on DHT Provider Counts

src/ipips/ipip-0000.md

@@ -0,0 +1,148 @@
+---
+title: "IPIP-0000: On-Demand Pinning Based on DHT Provider Counts"
+date: 2026-03-25
+ipip: proposal
+editors:
+  - name: Cornelius Ihle
+    github: ihlec
+relatedIssues: []
+order: 0000
+tags: ['ipips']
+---
+
+## Summary
+
+Defines a mechanism for IPFS nodes to automatically pin content when DHT
+provider counts fall below a configurable replication target, and unpin when
+replication has recovered above target for a grace period.
+
+## Motivation
+
+IPFS content availability depends on at least one provider remaining online.
+Content hosted by a small number of nodes is fragile. 
+
+Node operators who want to help keep content alive must manually monitor
+provider counts and re-pin content when replication drops. This is tedious,
+error-prone, and doesn't scale. Conversely, nodes may continue pinning content
+that already has abundant providers elsewhere, wasting local storage that could
+serve under-replicated content instead.
+
+A standardized on-demand pinning mechanism would let community nodes act as an
+automatic safety net: pinning content that is at risk of disappearing, and
+releasing it once enough other providers exist. 
+
+## Detailed design
+
+This IPIP defines an on-demand pinning mechanism with three components: 
+
+- registry of monitored CID
+- background checker
+- pin/unpin behavior based on DHT provider counts
+
+### Registry
+
+Implementations maintain a persistent registry of CIDs to monitor. Each entry
+tracks:
+
+- The CID being monitored
+- Whether the implementation currently holds a pin for it
+- A timestamp for when providers were last observed above target (used for grace period tracking)
+- A creation timestamp (purely informational, no logic depends on the timestamp)
+
+Users add and remove CIDs from the registry explicitly. Adding a CID does not
+immediately pin it -- it registers it for monitoring.
+
+### Background checker
+
+A periodic loop evaluates every registered CID:
+
+1. Query the DHT for providers of the CID (excluding self)
+2. If providers < replication target and not currently pinned: recursively pin
+   the content
+3. If providers >= replication target and currently pinned: start the grace
+   period timer (if not already running)
+4. If grace period has elapsed: unpin the content
+5. If providers drop below target again while grace period is running: reset
+   the timer
+
+The checker skips CIDs that have a user-created pin (to avoid interfering with
+manual pin management). 
+The periodic query replaces the periodic re-provide and only adds overhead for actively pinnned CIDs (below replication target). 
+
+### Configuration parameters
+
+Implementations MUST support the following parameters (values are TBD):
+
+- **Replication target**: the desired number of providers (excluding self).
+  Recommended default: 5
+- **Check interval**: time between full evaluation cycles. Recommended
+  default: 10 minutes
+- **Unpin grace period**: how long providers must stay above target before
+  unpinning. Recommended default: 24 hours
+
+### Pin naming
+
+When the checker creates a pin, it SHOULD use a well-known name (e.g.,
+`"on-demand"`) to distinguish it from user-created pins. The checker MUST NOT
+unpin content whose pin name does not match, to avoid removing user pins.
+
+### Pinning scope
+
+The checker MUST use recursive pins. Direct pins do not preserve
+content availability since they do not protect linked blocks.
+
+## Design rationale
+
+The design favors simplicity: it relies entirely on existing DHT infrastructure
+for provider discovery and existing pin semantics for storage. No new wire
+protocols or peer coordination are introduced.
+
+The grace period mechanism prevents thrashing. Without it, a CID hovering near
+the replication target would be pinned and unpinned on every check cycle. A
+24-hour default gives enough time to confirm that new providers are stable.
+
+The pin naming convention lets the checker coexist with user pins. If a user
+manually pins a CID that is also registered for on-demand pinning, the checker
+will not interfere.
+
+### User benefit
+
+Nodes can contribute storage where it matters most. Instead of pinning content
+indefinitely regardless of how many other providers exist, on-demand pinning
+frees storage automatically when content is well-replicated, making room for
+content that actually needs help.
+
+On-demand pinning can be easily integrated into existing UI-flow.
+![UI-flow](https://github.com/user-attachments/assets/2cc1109a-1005-4a5c-b843-7821499c5f0e)
+
+### Compatibility
+
+This feature is purely additive. Nodes that do not implement on-demand pinning
+are unaffected. On-demand pinning nodes interact with the network using only
+existing DHT queries and standard pin operations -- no protocol changes are
+required.
+
+### Security
+
+DHT provider counts can be gamed. A Sybil attack could inflate provider counts
+by announcing many fake provider records, tricking nodes into unpinning content
+that is not actually well-replicated. Implementations SHOULD document this
+limitation. The grace period provides partial mitigation: an attacker would
+need to sustain fake provider records for the full grace duration.
+
+### Alternatives
+
+A dedicated replication protocol between cooperating nodes was considered. This
+would allow nodes to explicitly coordinate who pins what, avoiding redundant
+work. However, it would require a overlay network protocol, and peer discovery for
+replication partners -- dramatically increasing [complexity](https://github.com/gipplab/D-LOCKSS) or introducing [centralized components](https://github.com/gipplab/ipfs-archive-tracker). 
+The DHT-based approach reuses existing infrastructure and requires no coordination between nodes.
+
+## Test fixtures
+
+Not applicable. This IPIP defines node behavior, not content-addressed data
+formats.
+
+### Copyright
+
+Copyright and related rights waived via [CC0](https://creativecommons.org/publicdomain/zero/1.0/).