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

ProviderTypeLocatieRol
Kubo PrimaryEigen nodeHono-serverPrimaire pin + serve. Volledige IPFS-node.
Kubo ReplicaEigen nodeBackup-serverReplicatie van kritieke CIDs (tier-0, tier-1).
Provider AExtern (Pinning Service API)CloudExterne pin voor redundantie.
Provider BExtern (Pinning Service API)CloudExterne 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

TierMin. providersProvidersVerplichtHerpin bij falen
Tier-0 (core)3+Kubo Primary + 2 externJa, altijdOnmiddellijk herpin bij alternatieve provider
Tier-1 (verified)2+Kubo Primary + 1 externJaHerpin bij alternatieve provider binnen 24 uur
Tier-2 (third-party)1+Minimaal 1 pinning-serviceJa (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

StatusBetekenisActie
pinnedCID beschikbaar bij providerGeen actie
pinningPin-verzoek verstuurd, wacht op bevestigingPoll status elke 30s
failedPin misluktHerpin of verwijder provider
unpinnedCID expliciet verwijderdGeen 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

TierIntervalBij falen
Tier-0Elke 24 uurOnmiddellijk herpin + nood-melding
Tier-1Elke 24 uurHerpin binnen 24 uur + melding
Tier-2Elke 72 uurMelding 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

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

AC-3
#CriteriaMeting
AC-1Tier-0 CIDs zijn minimaal 3x gepind (Kubo + 2 extern)Pin-registry controle
AC-2Tier-1 CIDs zijn minimaal 2x gepind (Kubo + 1 extern)Pin-registry controle
Pin-verificatie draait elke 24 uur voor tier-0/tier-1Cron-log controle
AC-4Bij provider-faal: herpin binnen 24 uur (tier-0: onmiddellijk)Herpin-log + timing
AC-5Unpin van tier-0 vereist admin-expliciet verzoekTest: automatisch unpin geweigerd
AC-6Pin-flow bij publish blokkeert niet (async pin + immediate staged)Publish-timing < 5s
AC-7Pin-registry is consistent (geen dubbele pins, geen ontbrekende records)Dagelijkse integriteits-check

9. Risico's en aanbevelingen

RisicoImpactAanbeveling
Alle providers falen gelijktijdighoogKubo Replica als derde backup. Nood-melding + handmatige actie.
Pin-verificatie mist een falende providermiddelElke 24 uur is kort genoeg. Bij tier-0: elke 6 uur optioneel.
Extern provider wijzigt API (breaking change)middelPinning Service API (IPFS-standaard). Provider-specifieke adapters.
Te veel CIDs = hoge storage-kostenmiddelTier-based pin-aantal + unpin-beleid voor inactieve CIDs.
Publish blokkeert op langzame pinlaagAsync pin: staged direct, pin op achtergrond.

10. Verwijzingen naar verwante specs

Volgende stap Na akkoord: Kubo-cluster opzetten + Pin Registry database + Pin Dispatcher implementeren + Pin Verifier cron-job + Provider-adapters (Pinning Service API).

11. Grillvragen