[Backend] Add Retry Logic and Fallback Provider to IPFS Service

[llinsss]

⚠️ This is a backend issue — work is done inside the backend/ folder

Description

backend/src/modules/blockchain/ipfs.service.ts uploads medical record hashes to IPFS via a single Kubo RPC client. If the IPFS node is unavailable, the upload throws immediately with no retry, causing the entire medical record sync to fail. There is also no fallback provider (e.g. Pinata, Web3.Storage) if the primary node is down.

Current State

• IPFSService.upload() — single try/catch, no retry
• IPFSService.retrieve() — single attempt, no fallback
• No health check for the IPFS node
• BlockchainSyncService calls IPFSService directly and propagates failures upward

What Needs to Be Built

1. Retry Logic with Exponential Backoff

async upload(data: string | Buffer, retries = 3): Promise<string> {
  for (let attempt = 1; attempt <= retries; attempt++) {
    try {
      return await this.primaryUpload(data);
    } catch (err) {
      if (attempt === retries) break;
      await sleep(500 * 2 ** attempt);
    }
  }
  return this.fallbackUpload(data); // Pinata fallback
}

2. Pinata Fallback Provider

• Add PINATA_API_KEY and PINATA_SECRET_KEY to blockchain.config.ts
• Implement fallbackUpload() using Pinata's REST API
• Log which provider was used for each upload

3. IPFS Node Health Check

GET /blockchain/ipfs/health

• Ping the IPFS node and return { status: 'ok' | 'degraded' | 'down', provider: 'kubo' | 'pinata' }
• Expose via ObservabilityController or a new BlockchainController

4. Retrieve Fallback

• On retrieve(cid), try primary node first, then Pinata gateway on failure

Acceptance Criteria

• Failed uploads retry up to 3 times with exponential backoff
• If all retries fail, upload falls back to Pinata
• GET /blockchain/ipfs/health returns current provider status
• Retrieve also falls back to Pinata gateway on primary failure
• Provider used is logged for each operation
• Unit tests mock both providers and verify fallback behaviour

Files to Modify

• backend/src/modules/blockchain/ipfs.service.ts
• backend/src/config/blockchain.config.ts (add Pinata config)
• backend/src/modules/blockchain/blockchain.module.ts (expose health endpoint)
• backend/src/modules/blockchain/ipfs.service.spec.ts (new)

Environment Variables Required

PINATA_API_KEY=
PINATA_SECRET_KEY=

Priority

High — IPFS failures currently break medical record blockchain sync entirely

Estimated Effort

2 days

[yosemite01]

@yosemite01 has applied to work on this issue as part of the Stellar Wave Program's 5th wave.

Hello Maintainer
I'll like to work on this Issue

ℹ️ Repo Maintainers: To accept this application, review their application or assign @yosemite01 to this issue.

[drips-wave]

Congratulations, @yosemite01! 🎉 Your application was accepted by the repo's maintainers, and the issue is due on June 2, 2026.

🧑‍💻 @yosemite01: Please resolve the issue such that the repo's maintainers have enough time to review your contribution before the due date. You'll earn Points for completing the issue on-time, which will make you eligible for a share of the Stellar Wave Program's reward pool.

Warning

When opening a PR, please link it to this issue to ensure it gets tracked accurately. Points are awarded when this issue is marked as completed by the maintainer.

🤠 Repo maintainers: Please keep an eye on the contributor's progress and review their work before the due date. You can manage this issue, including adjusting its complexity and points, here.

🌊 Happy Wave 🌊