IPFS pinning strategie
Multi-provider pinning (Kubo + 2 extern) • pin-verificatie elke 24 uur • pin-flow bij publish • tier-based pin-aantal • status: ontwerp, nog geen code
Kerndefinitie: IPFS pinning is het proces om content permanent beschikbaar te houden door deze expliciet op te slaan bij meerdere providers. MAOS gebruikt een multi-provider strategie met eigen Kubo-node + minimaal 2 externe pinning-services. Elke 24 uur wordt geverifieerd of alle pinned CIDs nog beschikbaar zijn.
1. Architectuur-overzicht
┌─────────────────────────────────────────────────────────────┐
│ IPFS Pin Manager │
│ │
│ ┌──────────────────┐ ┌──────────────────┐ │
│ │ Pin Dispatcher │ │ Pin Verifier │ │
│ │ │ │ │ │
│ │ publish() │ │ verifyAll() │ │
│ │ pin() │ │ verifyPin() │ │
│ │ unpin() │ │ repairPin() │ │
│ └────────┬─────────┘ └────────┬─────────┘ │
│ │ │ │
│ ┌────────▼───────────────────────▼─────────┐ │
│ │ Pin Registry (database) │ │
│ │ cid, tier, providers[], lastVerified, │ │
│ │ status, pinCount, createdAt │ │
│ └────────┬───────────┬───────────┬─────────┘ │
│ │ │ │ │
│ ┌────────▼───┐ ┌─────▼─────┐ ┌──▼──────────┐ │
│ │ Kubo Primary│ │ Provider A│ │ Provider B │ │
│ │ (eigen) │ │ (extern) │ │ (extern) │ │
│ └────────────┘ └───────────┘ └─────────────┘ │
└─────────────────────────────────────────────────────────────┘
2. Multi-provider pinning
2.1 Provider-configuratie
| Provider | Type | Locatie | Rol |
| Kubo Primary | Eigen node | Hono-server | Primaire pin + serve. Volledige IPFS-node. |
| Kubo Replica | Eigen node | Backup-server | Replicatie van kritieke CIDs (tier-0, tier-1). |
| Provider A | Extern (Pinning Service API) | Cloud | Externe pin voor redundantie. |
| Provider B | Extern (Pinning Service API) | Cloud | Externe pin voor redundantie. |
2.2 Provider-selectie
pinDispatcher.selectProviders(tier, cid)
│
├── tier-0 (core)
│ └── [Kubo Primary, Provider A, Provider B] (3+ providers)
│
├── tier-1 (verified)
│ └── [Kubo Primary, Provider A] (2+ providers)
│
└── tier-2 (third-party)
└── [Provider A] (1+ provider, publisher verantwoordelijk)
3. Tier-based pin-aantal
| Tier | Min. providers | Providers | Verplicht | Herpin bij falen |
| Tier-0 (core) | 3+ | Kubo Primary + 2 extern | Ja, altijd | Onmiddellijk herpin bij alternatieve provider |
| Tier-1 (verified) | 2+ | Kubo Primary + 1 extern | Ja | Herpin bij alternatieve provider binnen 24 uur |
| Tier-2 (third-party) | 1+ | Minimaal 1 pinning-service | Ja (publisher verantwoordelijk) | Melding aan publisher |
REGEL: Tier-0 CIDs worden nooit ongepinnd. Bij falen van alle providers: nood-melding + onmiddellijke actie. Tier-1 CIDs worden herpinned binnen 24 uur. Tier-2 CIDs: melding aan publisher.
4. Pin-flow bij publish
Publisher: maos publish
│
├── 1. Vite-build → bundle + manifest.json
│
├── 2. Ed25519-sign over canonical JSON
│
├── 3. IPFS pin via Hono /api/ipfs/pin
│ │
│ ├── 3a. Pin bij Kubo Primary
│ │ POST http://kubo:5001/api/v0/pin
│ │ Body: { cid: "bafy...", name: "dapp-naam" }
│ │ └── Response: { cid, size, pinStatus }
│ │
│ ├── 3b. Pin bij Provider A (extern)
│ │ POST https://provider-a.example.com/api/v0/pin
│ │ Headers: { Authorization: "Bearer {token}" }
│ │ Body: { cid: "bafy...", name: "dapp-naam" }
│ │ └── Response: { requestId, status }
│ │
│ └── 3c. Pin bij Provider B (extern)
│ POST https://provider-b.example.com/api/v0/pin
│ Headers: { Authorization: "Bearer {token}" }
│ Body: { cid: "bafy...", name: "dapp-naam" }
│ └── Response: { requestId, status }
│
├── 4. Pin-registry bijwerken
│ {
│ cid: "bafy...",
│ tier: 2,
│ providers: [
│ { name: "kubo-primary", status: "pinned", lastVerified: "..." },
│ { name: "provider-a", status: "pinning", lastVerified: null },
│ { name: "provider-b", status: "pinning", lastVerified: null }
│ ],
│ pinCount: 3,
│ createdAt: "2025-01-15T10:30:00Z"
│ }
│
├── 5. Store-backend registratie
│ status: staged
│
└── 6. Auto-scan triggeren
4.1 Pin-statussen
| Status | Betekenis | Actie |
| pinned | CID beschikbaar bij provider | Geen actie |
| pinning | Pin-verzoek verstuurd, wacht op bevestiging | Poll status elke 30s |
| failed | Pin mislukt | Herpin of verwijder provider |
| unpinned | CID expliciet verwijderd | Geen actie (tenzij tier-0) |
5. Pin-verificatie (elke 24 uur)
5.1 Verificatie-flow
Pin Verifier (cron: elke 24 uur)
│
├── 1. Alle pinned CIDs ophalen uit registry
│ SELECT cid, tier, providers FROM pin_registry
│ WHERE status = 'pinned'
│
├── 2. Per CID: verificatie bij elke provider
│ │
│ ├── Provider A: GET /api/v0/pin/status?cid={cid}
│ │ └── Response: { status: "pinned" } → OK
│ │
│ ├── Provider B: GET /api/v0/pin/status?cid={cid}
│ │ └── Response: { status: "pinned" } → OK
│ │
│ └── Kubo Primary: GET /api/v0/pin/ls?arg={cid}
│ └── Response: { keys: { "bafy...": { type: "recursive" } } } → OK
│
├── 3. Resultaat per CID
│ │
│ ├── Alle providers OK → update lastVerified
│ │
│ ├── Eén provider faalt → herpin bij alternatieve provider
│ │ └── Bij tier-0: onmiddellijk + nood-melding
│ │
│ └── Meerdere providers falen → escalatie
│ ├── Tier-0: nood-melding + onmiddelijke actie
│ ├── Tier-1: herpin + melding aan admin
│ └── Tier-2: melding aan publisher
│
└── 4. Rapport genereren
├── Totaal geverifieerd: X CIDs
├── Geslaagd: X
├── Gefaald: X (met details)
└── Hersteld: X
5.2 Verificatie-interval
| Tier | Interval | Bij falen |
| Tier-0 | Elke 24 uur | Onmiddellijk herpin + nood-melding |
| Tier-1 | Elke 24 uur | Herpin binnen 24 uur + melding |
| Tier-2 | Elke 72 uur | Melding aan publisher |
6. Unpin-beleid
unpinRequest(cid, reason)
│
├── 1. Reden registreren
│ ├── "publisher-request" (publisher verwijdert DApp)
│ ├── "tier-downgrade" (van tier-1 naar tier-2)
│ ├── "security-issue" (malware gevonden)
│ └── "inactivity" (12+ maanden niet geopend)
│
├── 2. Per provider: unpin
│ │
│ ├── Kubo Primary: POST /api/v0/pin/rm?arg={cid}
│ ├── Provider A: DELETE /api/v0/pin/{cid}
│ └── Provider B: DELETE /api/v0/pin/{cid}
│
├── 3. Pin-registry bijwerken
│ status: unpinned
│
└── 4. Cache opschonen
├── Helia-lokaal: verwijder
└── SW-cache: verwijder
6.1 Unpin-regels
- Tier-0: Nooit ongepind, tenzij security-issue. Alleen op expliciet verzoek van admin.
- Tier-1: Na 12 maanden inactiviteit (niet geopend). Publisher wordt gewaarschuwd.
- Tier-2: Na 6 maanden inactiviteit. Publisher wordt gewaarschuwd. Na 3 maanden extra: automatisch unpin.
7. Pin-registry schema
pin_registry {
cid: string (primary key)
name: string
tier: integer (0|1|2)
version: string (semver)
minCore: string (semver)
publisherId: string
providers: jsonb [
{
name: string,
status: string (pinned|pinning|failed|unpinned),
lastVerified: timestamp,
pinCount: integer
}
]
pinCount: integer (totaal pinned bij providers)
lastVerified: timestamp
createdAt: timestamp
updatedAt: timestamp
status: string (active|unpinned|failed)
}
8. Acceptatiecriteria
| # | Criteria | Meting |
| AC-1 | Tier-0 CIDs zijn minimaal 3x gepind (Kubo + 2 extern) | Pin-registry controle |
| AC-2 | Tier-1 CIDs zijn minimaal 2x gepind (Kubo + 1 extern) | Pin-registry controle |
AC-3Pin-verificatie draait elke 24 uur voor tier-0/tier-1 | Cron-log controle |
| AC-4 | Bij provider-faal: herpin binnen 24 uur (tier-0: onmiddellijk) | Herpin-log + timing |
| AC-5 | Unpin van tier-0 vereist admin-expliciet verzoek | Test: automatisch unpin geweigerd |
| AC-6 | Pin-flow bij publish blokkeert niet (async pin + immediate staged) | Publish-timing < 5s |
| AC-7 | Pin-registry is consistent (geen dubbele pins, geen ontbrekende records) | Dagelijkse integriteits-check |
9. Risico's en aanbevelingen
| Risico | Impact | Aanbeveling |
| Alle providers falen gelijktijdig | hoog | Kubo Replica als derde backup. Nood-melding + handmatige actie. |
| Pin-verificatie mist een falende provider | middel | Elke 24 uur is kort genoeg. Bij tier-0: elke 6 uur optioneel. |
| Extern provider wijzigt API (breaking change) | middel | Pinning Service API (IPFS-standaard). Provider-specifieke adapters. |
| Te veel CIDs = hoge storage-kosten | middel | Tier-based pin-aantal + unpin-beleid voor inactieve CIDs. |
| Publish blokkeert op langzame pin | laag | Async pin: staged direct, pin op achtergrond. |
10. Verwijzingen naar verwante specs
- IPFS gateway — Verified-fetch, cache-strategie, geen publieke fallback
- Storage-net-recovery — OPFS-sync, IPFS private trustless gateways
- Core-vs-IPFS split — Release-train, minCore-check, per-CID DApps
- Store approval — Auto-scan, publish-flow
- DApp overzicht — Tiers, levenscyclus, manifest
- DApp manifest schema — JSON Schema, Ed25519, CID-verificatie
Volgende stap Na akkoord: Kubo-cluster opzetten + Pin Registry database + Pin Dispatcher implementeren + Pin Verifier cron-job + Provider-adapters (Pinning Service API).
11. Grillvragen
- Vraag 1: Moet de Pin Verifier ook een handmatige "force verify" optie bieden voor admins, of is de cron-jobs voldoende?
- Vraag 2: Hoe wordt het geval afgehandeld dat een extern provider de Pinning Service API niet ondersteunt: adapter schrijven, of provider weigeren?
- Vraag 3: Moet het unpin-beleid ook rekening houden met dependent DApps (een tier-1 DApp die afhankelijk is van een tier-2 bundle)?