@1001-digital/dweb-fetch

Fetch library for decentralized web protocols (IPFS, IPNS, Arweave, EIP-155 NFT references) with native protocol clients and verified content retrieval.

Usage

import { createDwebFetch } from '@1001-digital/dweb-fetch'

const dwebFetch = createDwebFetch()

// IPFS
const ipfsResponse = await dwebFetch('ipfs://bafyABC...')

// IPNS
const ipnsResponse = await dwebFetch('ipns://example.eth')

// Arweave
const arResponse = await dwebFetch('ar://txId123')

// HTTPS passthrough
const httpsResponse = await dwebFetch('https://example.com/data.json')

// EIP-155 NFT reference (requires config, see below)
const nftMetadata = await dwebFetch('eip155:1/erc721:0xBC4CA0EdA7647A8aB7C2061c2E118A18a936f13D/1234')

Configuration

const dwebFetch = createDwebFetch({
  ipfs: {
    gateways: ['https://my-gateway.io'],
    routers: ['https://my-router.io'],
    // 'verified' (default) — content-verified via @helia/verified-fetch, falls
    //   back to direct HTTPS to gateways on failure.
    // 'gateway' — direct HTTPS to gateways only. @helia/verified-fetch is never
    //   loaded, so libp2p/blockstore state is never instantiated. Cheaper and
    //   leaner; appropriate for high-volume server workloads that trust their
    //   configured gateways.
    mode: 'verified',
  },
  arweave: {
    // Custom static gateways (tried first by default)
    gateways: ['https://arweave.net', 'https://ar-io.dev'],
    // Routing strategy for network discovery fallback: 'random' | 'fastest' | 'balanced' | 'preferred'
    routingStrategy: 'fastest',
    // Disable network discovery fallback entirely
    useNetworkDiscovery: false,
  },
  eip155: {
    // JSON-RPC endpoints per chain ID
    rpcUrls: {
      1: 'https://eth-mainnet.g.alchemy.com/v2/YOUR_KEY',
      137: 'https://polygon-rpc.com',
    },
  },
})

Protocol Backends

• IPFS/IPNS — @helia/verified-fetch for content-verified retrieval, with a direct HTTPS gateway fallback. Set ipfs.mode: 'gateway' to skip Helia entirely and use direct HTTPS gateway fetches only — useful for high-volume server workloads where the Helia node's resident state is a cost you don't want to pay. @helia/verified-fetch is an optional peer dependency, so install it in consumers that need verified mode.
• Arweave — Static gateways first, falls back to @ar.io/wayfinder-core network discovery
• HTTP/HTTPS — Native fetch passthrough
• EIP-155 — Resolves NFT token URIs via JSON-RPC (tokenURI for ERC-721, uri for ERC-1155), then fetches the result through the appropriate handler above. Opt-in — only active when eip155 config is provided.

All backends are lazily initialized on first use. In ipfs.mode: 'gateway', @helia/verified-fetch is never imported.

API

createDwebFetch(config?): DwebFetch

Creates a fetch function that routes URLs to the appropriate protocol handler. Synchronous — backends initialize lazily on first fetch.

extractScheme(url): string | undefined

Extracts the URL scheme (e.g., 'ipfs', 'ar', 'https').

parseDwebUrl(url): ParsedDwebUrl | undefined

Parses a URL into scheme, raw URL, and path components.

parseEip155Uri(url): ParsedEip155Uri | undefined

Parses an EIP-155 URI (eip155:<chainId>/<standard>:<contract>/<tokenId>) into its components.

resolveEip155TokenUri(options): Promise<string>

Resolves the token metadata URI for a known EIP-155 NFT standard without fetching the metadata body:

import { resolveEip155TokenUri } from '@1001-digital/dweb-fetch'

const tokenUri = await resolveEip155TokenUri({
  chainId: 1,
  standard: 'erc721',
  contract: '0xBC4CA0EdA7647A8aB7C2061c2E118A18a936f13D',
  tokenId: '1234',
  rpcUrl: 'https://eth-mainnet.g.alchemy.com/v2/YOUR_KEY',
})

For ERC-1155, {id} placeholders are replaced with the lower-case, 64-character hex token ID required by the metadata URI spec.

Error Classes

• DwebFetchError — Base error for all fetch failures
• DwebUnsupportedProtocolError — Thrown for unknown URL schemes
• Eip155ResolutionError — Thrown when EIP-155 resolution fails (missing RPC config, empty tokenURI, etc.)