wayfinder.resolveUrl()

Resolve ar:// URLs to fully-qualified gateway URLs using the configured routing strategy without making a network request.

Syntax

const url = await wayfinder.resolveUrl({ originalUrl, logger })

Parameters

originalUrl (string): The ar:// URL to resolve to a full gateway URL
logger (Logger, optional): Custom logger for this operation. Defaults to wayfinder's logger

Returns

Type: Promise<URL>

Returns a fully-qualified URL object that points to the selected gateway.

Examples

Basic URL Resolution

import { Wayfinder, NetworkGatewaysProvider } from '@ar.io/wayfinder-core'
import { ARIO } from '@ar.io/sdk'

const wayfinder = new Wayfinder({
  gatewaysProvider: new NetworkGatewaysProvider({
    ario: ARIO.mainnet(),
  }),
})

// Resolve a transaction ID
const url = await wayfinder.resolveUrl({
  originalUrl: 'ar://ABC123...XYZ',
})
console.log('Resolved URL:', url.toString())
// Output: https://arweave.net/ABC123...XYZ

// Resolve an ArNS name
const arnsUrl = await wayfinder.resolveUrl({
  arnsName: 'ardrive',
})
console.log('ArNS URL:', arnsUrl.toString())
// Output: https://ardrive.arweave.net

//Resolve an Arweave txId
const txIdUrl = await wayfinder.resolveUrl({
  txId: 'ABC123...XYZ',
})
console.log('Arweave txId URL:', txIdUrl.toString())
// Output: https://arweave.net/ABC123...XYZ

Transaction ID Resolution

// Transaction IDs are resolved to sandboxed subdomains
const txUrl = await wayfinder.resolveUrl({
  txId: 'YTB0dGJURWpqQ25iS2NaY1RPSi1TOUQxMmd3cGRFaHUzV2hiWnVlZ2o5WT0',
})
console.log('Transaction URL:', txUrl.toString())
// Output: https://ytb0dgjuqwpqq25iy2naytpsi1tpuqxnz3dqrfaohuzwhiwnu5j9y.arweave.net

ArNS Name Resolution

// ArNS names resolve to subdomain format
const arnsUrl = await wayfinder.resolveUrl({
  arnsName: 'ardrive',
})
console.log('ArNS URL:', arnsUrl.toString())
// Output: https://ardrive.arweave.net

// ArNS with path
const arnsPathUrl = await wayfinder.resolveUrl({
  originalUrl: 'ar://ardrive/docs/getting-started.html',
})
console.log('ArNS Path URL:', arnsPathUrl.toString())
// Output: https://ardrive.arweave.net/docs/getting-started.html

Gateway Endpoint Resolution

// Gateway info endpoint
const infoUrl = await wayfinder.resolveUrl({
  originalUrl: 'ar:///info',
})
console.log('Info URL:', infoUrl.toString())
// Output: https://arweave.net/info

// GraphQL endpoint
const graphqlUrl = await wayfinder.resolveUrl({
  originalUrl: 'ar:///graphql',
})
console.log('GraphQL URL:', graphqlUrl.toString())
// Output: https://arweave.net/graphql

With Custom Logger

const customLogger = {
  debug: (msg, ...args) => console.debug(`[RESOLVE] ${msg}`, ...args),
  info: (msg, ...args) => console.info(`[RESOLVE] ${msg}`, ...args),
  warn: (msg, ...args) => console.warn(`[RESOLVE] ${msg}`, ...args),
  error: (msg, ...args) => console.error(`[RESOLVE] ${msg}`, ...args),
}

const url = await wayfinder.resolveUrl({
  originalUrl: 'ar://ardrive',
  logger: customLogger,
})

Batch URL Resolution

const urls = [
  'ar://ABC123...XYZ',
  'ar://ardrive',
  'ar://ardrive/docs',
  'ar:///info',
  'ar:///graphql',
]

// Resolve multiple URLs in parallel
const resolvedUrls = await Promise.all(
  urls.map((originalUrl) => wayfinder.resolveUrl({ originalUrl })),
)

urls.forEach((original, index) => {
  console.log(`${original} → ${resolvedUrls[index].toString()}`)
})

Using Different Routing Strategies

import {
  Wayfinder,
  NetworkGatewaysProvider,
  PreferredWithFallbackRoutingStrategy,
  FastestPingRoutingStrategy,
} from '@ar.io/wayfinder-core'
import { ARIO } from '@ar.io/sdk'

// Wayfinder with preferred gateway strategy
const wayfinder = new Wayfinder({
  gatewaysProvider: new NetworkGatewaysProvider({
    ario: ARIO.mainnet(),
  }),
  routingSettings: {
    strategy: new PreferredWithFallbackRoutingStrategy({
      preferredGateway: new URL('https://permagate.io'),
      fallbackStrategy: new FastestPingRoutingStrategy(),
    }),
  },
})

const url = await wayfinder.resolveUrl({
  originalUrl: 'ar://ardrive',
})
console.log('Preferred gateway URL:', url.toString())
// Output: https://ardrive.permagate.io

Handling Resolution Errors

try {
  const url = await wayfinder.resolveUrl({
    originalUrl: 'ar://invalid-name',
  })
  console.log('Resolved:', url.toString())
} catch (error) {
  if (error.name === 'RoutingError') {
    console.error('Failed to select gateway:', error.message)
  } else if (error.name === 'NetworkError') {
    console.error('Network connectivity issue:', error.message)
  } else {
    console.error('Resolution failed:', error.message)
  }
}

URL Format Support

The resolveUrl() method supports various ar:// URL formats:

Transaction IDs (43 characters)

// Resolves to sandboxed subdomain
await wayfinder.resolveUrl({
  originalUrl:
    'ar://YTB0dGJURWpqQ25iS2NaY1RPSi1TOUQxMmd3cGRFaHUzV2hiWnVlZ2o5WT0',
})
// → https://ytb0dgjuqwpqq25iy2naytpsi1tpuqxnz3dqrfaohuzwhiwnu5j9y.arweave.net

ArNS Names (1-51 characters, alphanumeric + hyphens/underscores)

// Resolves to ArNS subdomain
await wayfinder.resolveUrl({
  arnsName: 'my-app',
})
// → https://my-app.arweave.net

// With path
await wayfinder.resolveUrl({
  originalUrl: 'ar://my-app/api/data.json',
})
// → https://my-app.arweave.net/api/data.json

Gateway Endpoints

// Gateway info
await wayfinder.resolveUrl({
  originalUrl: 'ar:///info',
})
// → https://arweave.net/info

// Price endpoint
await wayfinder.resolveUrl({
  originalUrl: 'ar:///price/1024',
})
// → https://arweave.net/price/1024

Comparison with request()

Method	Network Request	Verification	Use Case
`resolveUrl()`	❌ No	❌ No	Get gateway URL for manual requests
`request()`	✅ Yes	✅ Optional	Fetch and optionally verify data

When to use resolveUrl()

URL preview: Show users which gateway will be used
Manual fetch: You want to use your own fetch implementation
URL sharing: Generate shareable gateway URLs
Caching: Pre-resolve URLs for caching strategies

When to use request()

Data fetching: You want to fetch and consume the data
Verification: You want automatic data verification
Event monitoring: You want routing and verification events

Example: Manual Fetch with resolveUrl()

// Resolve URL first, then make manual request
const resolvedUrl = await wayfinder.resolveUrl({
  originalUrl: 'ar://ardrive',
})

// Make manual fetch with custom options
const response = await fetch(resolvedUrl, {
  headers: {
    Accept: 'text/html',
    'User-Agent': 'MyApp/1.0',
  },
  timeout: 10000,
})

const html = await response.text()
console.log('Fetched HTML:', html.length, 'bytes')

Performance Considerations

Gateway Selection: resolveUrl() triggers gateway selection, which may involve network requests to test gateway availability
Caching: Results are not cached between calls - consider caching resolved URLs if making multiple requests
Concurrent Calls: Multiple resolveUrl() calls may use the same gateway selection process

Integration Examples

With React

import { useState, useEffect } from 'react'

function ArweaveLink({ arUrl, children }) {
  const [resolvedUrl, setResolvedUrl] = useState(null)
  const [loading, setLoading] = useState(true)

  useEffect(() => {
    wayfinder
      .resolveUrl({ originalUrl: arUrl })
      .then((url) => {
        setResolvedUrl(url.toString())
        setLoading(false)
      })
      .catch((error) => {
        console.error('Failed to resolve URL:', error)
        setLoading(false)
      })
  }, [arUrl])

  if (loading) return <span>Resolving...</span>
  if (!resolvedUrl) return <span>Failed to resolve</span>

  return (
    <a href={resolvedUrl} target="_blank" rel="noopener noreferrer">
      {children}
    </a>
  )
}

With URL Shortening

async function createShortUrl(arUrl) {
  try {
    const resolvedUrl = await wayfinder.resolveUrl({
      originalUrl: arUrl,
    })

    // Use your URL shortening service
    const shortUrl = await shortener.create(resolvedUrl.toString())
    return shortUrl
  } catch (error) {
    console.error('Failed to create short URL:', error)
    throw error
  }
}

Next Steps

After resolving URLs:

Make requests: Use the resolved URL with fetch() or other HTTP clients
Cache results: Store resolved URLs to avoid repeated gateway selection
Monitor performance: Track resolution times and gateway selection patterns
Handle errors: Implement proper error handling for resolution failures