fix: resolve ipfs:// URIs to HTTP gateway for NFT images and metadata…

[holps-7]

Description

This PR resolves an issue where the Explorer fails to load NFT images and metadata that use the ipfs:// protocol scheme. Modern web browsers do not natively support the ipfs:// scheme, causing fetch and rendering failures for compressed and standard NFTs relying on it.

This change intercepts ipfs:// URIs in the getProxiedUri utility and converts them to use a public HTTP gateway (https://ipfs.io/ipfs/) before any proxy logic is evaluated.

Type of change

• Bug fix
• New feature
• Protocol integration
• Documentation update
• Other (please describe):

Screenshots

Before

After

Testing

• Added unit tests in utils.spec.ts to strictly verify IPFS rewritten structures (ipfs://{hash} and ipfs://ipfs/{hash}) under both proxy-enabled and proxy-disabled environments.
• Ran pnpm test locally to ensure all suites pass.
• Verified manually by running the Explorer locally (pnpm dev) and checking an NFT with an ipfs:// image URI (7rAhawfSxmqxjmSayjkLD44GoJA772R2QXBg174bobFW on devnet) to confirm it visually renders without console errors.

Related Issues

Fixes #807

Checklist

• My code follows the project's style guidelines
• I have added tests that prove my fix/feature works
• All tests pass locally and in CI
• I have updated documentation as needed
• I have run build:info script to update build information
• CI/CD checks pass
• I have included screenshots for protocol screens (if applicable)
• For security-related features, I have included links to related information

Additional Notes

We opted to fix this broadly at the getProxiedUri entry point rather than per-component, ensuring the HTTP gateway conversion cleanly applies to all metadata API fetchers and image rendering tools simultaneously.

[vercel]

@holps-7 is attempting to deploy a commit to the Solana Foundation Team on Vercel.

A member of the Team first needs to authorize it.

[greptile-apps]

Greptile Summary

Converts ipfs:// URIs to HTTP gateway URLs (https://ipfs.io/ipfs/) to enable NFT image and metadata loading in browsers, which don't natively support the IPFS protocol scheme. The implementation correctly handles both ipfs://{hash} and ipfs://ipfs/{hash} formats and preserves query parameters.

• Conversion happens before proxy logic evaluation, ensuring consistent behavior across all metadata/image fetching
• Test coverage validates both proxy-enabled and proxy-disabled environments
• Solution is implemented at the getProxiedUri utility level, applying the fix broadly across all NFT rendering components

Confidence Score: 5/5

• This PR is safe to merge with minimal risk
• The implementation is clean, well-tested, and addresses a legitimate browser compatibility issue. The logic correctly handles multiple IPFS URI formats, preserves query strings, and includes comprehensive test coverage for all scenarios.
• No files require special attention

Important Files Changed

Filename	Overview
app/features/metadata/utils.ts	Added IPFS protocol handling to convert ipfs:// URIs to HTTPS gateway URLs before proxy logic, properly handling both standard and prefixed formats
app/features/metadata/tests/utils.spec.ts	Added comprehensive test coverage for IPFS URI conversion with both proxy-enabled and proxy-disabled scenarios, covering standard and prefixed IPFS formats

Flowchart

%%{init: {'theme': 'neutral'}}%%
flowchart TD
    A[URI Input] --> B{Is Empty?}
    B -->|Yes| C[Return Empty String]
    B -->|No| D[Parse as URL]
    D --> E{Is IPFS Protocol?}
    E -->|Yes| F[Extract Path from Host + Pathname]
    F --> G{Starts with 'ipfs/'?}
    G -->|Yes| H[Remove 'ipfs/' Prefix]
    G -->|No| I[Keep Path As-Is]
    H --> J[Convert to HTTPS Gateway URL]
    I --> J
    J --> K{Is Proxy Enabled?}
    E -->|No| K
    K -->|No| L[Return URI]
    K -->|Yes| M{Is HTTP/HTTPS?}
    M -->|No| L
    M -->|Yes| N[Return Proxied URI]

Loading

_{Last reviewed commit: 0249fd3}

[holps-7]

hey @Woody4618 can you review this PR?

[rogaldh]

@holps-7 Could you, please, apply 'pnpm lint' and fix code style issues.

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Actions	Updated (UTC)
explorer	Error		Mar 25, 2026 10:19pm

[rogaldh]

Please check the test suite. Several tests failed

[holps-7]

Please check the test suite. Several tests failed

@rogaldh fixed this issue. the IPFS tests were using a fake CID that doesn't pass verifyCID. Updated to use a real CIDv0 and added a test for the malformed CID case.

[rogaldh]

Hi. To merge this feature, we have to improve the metadata proxy endpoint. After completing this, this PR could be merged.
Thank you for contribution.

fyi @Woody4618

[holps-7]

Hy @rogaldh what improvement are to be implemented for the proxy endpoint? if you can elaborate on this I can do it.