Skip to content

Commit c5e690a

Browse files
vasco-santosvasco-santos
committed
ipip: provider query parameter
1 parent c5fa792 commit c5e690a

File tree

1 file changed

+242
-0
lines changed

1 file changed

+242
-0
lines changed

‎IPIP/0504-provider-query-parameter.md‎

Lines changed: 242 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,242 @@
1+
---
2+
# IPIP number should match its pull request number. After you open a PR,
3+
# please update title and update the filename to `ipip0000`.
4+
title: "IPIP-0504: Provider Query Parameter"
5+
date: YYYY-MM-DD
6+
ipip: proposal
7+
editors:
8+
- name: Vasco Santos
9+
relatedIssues:
10+
- link to issue
11+
order: 0504
12+
tags: ['ipips']
13+
---
14+
15+
## Summary
16+
17+
A URI-based format for expressing content-addressed identifiers (such as IPFS CIDs) optionally augmented with one or more provider hints. This format aims to support a simple, unopinionated, transport-agnostic scheme to simplify data retrieval in content-addressable systems by introducing a clear, extensible, and broadly compatible URI format.
18+
19+
## Motivation
20+
21+
Content-addressable systems, such as IPFS, allow data to be identified by the hash of its contents (CID), enabling verifiable, immutable references. However, retrieving content typically relies on side content discovery systems (e.g. DHT, IPNI), even when a client MAY know one (or more) provider of the bytes. A provider in this context is any node, peer, gateway, or service that can serve content identified by a CID.
22+
23+
Existing solutions (e.g., magnet URIs, RASL) propose alternative ideas where provider hints are encoded next to the content identifier. Inspired by these solutions and focusing particularly on ergonomics, extensibility, and ease of adoption, this IPIP aims to augment an IPFS URI with a provider query parameter.
24+
25+
## Requirements, Goals, and Non-Goals
26+
27+
### Goals
28+
29+
| Goal | Description |
30+
| --------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
31+
| **Low-effort adoption** | Enable systems like IPFS (e.g., Kubo, Helia), gateways, etc., to adopt the format with minimal changes. Or even no changes by relying on current discovery systems. |
32+
| **Extensible hint system** | Support encoding multiple transport hints (e.g., HTTP, TCP), while extensible to support intermediary hops (e.g. IPNI, RASL), priorities/fallbacks, etc. |
33+
| **Preserve base compatibility** | Maintain compatibility with existing URI forms such as `ipfs://CID/...` and HTTP gateway URLs. |
34+
| **Ergonomic for CLI and sharing** | Should be human-editable, URL-query-based, no strict URL-encoding beyond what browsers or CLIs already handle. Easy to copy/paste, share, or edit by hand. |
35+
| **Publisher-driven** | Allow publishers to encode as much transport/discovery information as they want, with no requirement for intermediary systems. They can disappear, yet the link remains useful. |
36+
| **Fallback resilience** | URI should encode enough to allow clients to attempt various fallbacks or resolve via discovery (e.g., DHT, IPNI). |
37+
| **Self-descriptive** | May support optional encoding of content types to enable clients to understand how to interpret the content after verification. |
38+
| **Protocol-agnostic** | Must not be tied to HTTP-only systems. Other transport protocols, like the ones supported by libp2p, must be possible to use if encoded as hints. |
39+
| **Forward-compatible** | Format should support future expansions: new hint types, encodings, content representations, etc. |
40+
41+
### Non-Goals
42+
43+
| Non-Goal | Reason |
44+
| --------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------- |
45+
| **Replace existing `ipfs://` or HTTP gateway URLs** | This format builds upon and extends them; not a replacement. |
46+
| **Strictly define a resolution order** | Clients may choose how and in what order to try hints or fallback strategies. |
47+
| **Mandate use of a centralized service** | While some hints may include centralized endpoints (e.g., HTTP URLs), the URI format should support fully decentralized retrieval. |
48+
| **Guarantee live access** | A hint may point to an offline, censored or throttled node. The client may use other hints or its own discovery logic. |
49+
| **Act as a trust layer** | These URIs do not manage identity or trust directly—verification remains based on CID integrity. |
50+
51+
### Requirements
52+
53+
| Requirement | Reasoning |
54+
| ---------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------- |
55+
| **CID as core address** | Content addressing should always resolve to a CID. Provider hints decorate, not replace, this. |
56+
| **Multi-hint support** | Support multiple hints per URI, enabling clients to try multiple fetch paths if one fails. |
57+
| **Hinted provider must be optional** | Clients without support for hints must still be able to resolve using traditional discovery (DHT, IPNI, etc.), if the publisher set it up. |
58+
| **No required translation step** | Links should not require dynamic translation (e.g., via an origin-based redirector). Links are self-contained. |
59+
| **Minimal client assumptions** | Clients may safely ignore unknown hints and still function. This ensures progressive enhancement. |
60+
| **Composable with Gateway URLs** | Hints should not break Gateway-based access patterns. For example, users should be able to use URLs like `https://gw.io/ipfs/CID?provider=http...`. |
61+
| **Multiaddr-based hint syntax** | For transport-agnosticism, hints should leverage multiaddr representation. |
62+
| **No third-party resolution dependency** | Links should work standalone—resolution should not depend on reaching a third-party registry or lookup service. |
63+
| **No strict encoding rules** | Except for standard URI syntax, do not require opaque encodings. Hints should be human-readable when possible. |
64+
65+
## Detailed design
66+
67+
This section defines a URI format for expressing a content identifier (CID) along with optional provider hints that **guide clients** on how/where to fetch the associated content. The format is intended to be directly compatible with both IPFS Gateway URLs and `ipfs://` scheme URIs, while preserving flexibility and extensibility to also be compatible with other systems or upgrades.
68+
69+
Please note that the current format is not intended to fully specify all identified use cases or requirements. But focus on leaving the door open to more in depth specifications for specific cases.
70+
71+
### 📐 Format
72+
73+
The proposed URI format introduces a new optional query parameter `provider`, which may appear one or more times. Each `provider` value represents a content provider hint and is composed by a `multiaddr` string. The `provider` parameter is optional, and clients MAY ignore it.
74+
75+
The base format is:
76+
77+
```sh!
78+
[ipfs://<CID> | https://<gateway>/ipfs/<CID> | https://<CID>.ipfs.<gateway> ]?[provider=<multiaddr1>&provider=<multiaddr22>&...]
79+
```
80+
81+
### 🧠 Parsing
82+
83+
The CID is the core of a Provider-Hinted URI. Clients MUST extract the CID before evaluating any hints. The format is designed to be compatible with current IPFS like URIs, while explicitly defining how to locate the CID and interpret `provider` query parameters.
84+
85+
#### CID Extraction Rules
86+
87+
To ensure consistent parsing, clients MUST extract the CID using the following precedence rules:
88+
89+
**1. Multi-dotted Origin Format**
90+
91+
If the CID is encoded as a subdomain label (e.g., `https://<CID>.ipfs.<gateway>`):
92+
93+
- The CID MUST be the left-most label.
94+
- The label immediately following MUST be `ipfs`.
95+
- Any path MUST NOT also include a CID.
96+
97+
**Example:**
98+
✅ `https://bafy...ipfs.dweb.link`
99+
❌ `https://bafy...ipfs.dweb.link/ipfs/bafybogus` (ambiguous; reject)
100+
101+
**2. Path-Based Format**
102+
103+
If the CID is encoded in the path (e.g., `https://<gateway>/ipfs/<CID>`):
104+
105+
- The path MUST match the pattern `/ipfs/<CID>`, where `<CID>` is a valid content identifier.
106+
107+
**Example:**
108+
✅ `https://gateway.io/ipfs/bafy...`
109+
❌ `https://gateway.io/bafy...` (no `/ipfs/` marker)
110+
111+
**3. ipfs:// Scheme Format**
112+
113+
- The CID MUST immediately follow the scheme delimiter: `ipfs://<CID>`.
114+
- Additional path/query components MAY follow.
115+
116+
**Example:**
117+
✅ `ipfs://bafy...`
118+
119+
**4. Conflict Resolution**
120+
121+
If a CID is present in both a multi-dotted origin and in the path (even if they match), the URI MUST be rejected as ambiguous.
122+
123+
---
124+
125+
#### Query Parameter: `provider`
126+
127+
- Name: `provider`
128+
- Type: URI Query Parameter (repeating allowed)
129+
- Value: Multiaddr string (`?provider=multiaddr`).
130+
- Interpretation: Optional hint for how to fetch and locate the content identified by the CID
131+
132+
#### Query Parsing (`provider` Parameters)
133+
134+
Once a CID has been successfully extracted, clients MAY parse `provider` parameters from the query string. Each `provider` value represents a provider hint, encoded as a multiaddr string.
135+
136+
**1. Parsing Rules**
137+
138+
- The `provider` query parameter MAY appear multiple times.
139+
- Each `provider` parameter MUST be treated as an independent, optional provider hint.
140+
- Clients MAY ignore hints with invalid multiaddrs.
141+
142+
**2. Evaluate hints**
143+
144+
- Clients MAY:
145+
- Ignore all `provider` parameters (if unsupported).
146+
- Evaluate hints in order of appearance (left-to-right).
147+
- Evaluate hints in parallel.
148+
- Apply their own prioritization or fallback strategies. If all hints fail, clients SHOULD fall back to default discovery strategies (e.g., DHT/IPNI), if available. Or even rely on discovery strategies in parallel.
149+
150+
Note that the `multiaddr` string should point to the `origin` server where given CID is provided, and not include the actual CID in the Hint multiaddr as a subdomain/path.
151+
152+
---
153+
154+
#### Example Parsing Flows
155+
156+
**Input URI:**
157+
`https://bafy....ipfs.dweb.link/ipfs/bafy...?provider=/dns4/hash-stream-like-server.io/tcp/443/https`
158+
→ **REJECT** (CID appears in both hostname and path)
159+
160+
**Input URI:**
161+
`https://dweb.link/ipfs/bafy...?provider=/dns4/hash-stream-like-server.io/tcp/443/https&provider=/ip4/192.0.2.1/tcp/4001/ws`
162+
163+
→ Extract CID: `bafy...`
164+
→ Parse `provider` params:
165+
166+
1. `/dns4/hash-stream-like-server.io/tcp/443/https` using `http`
167+
2. `/ip4/192.0.2.1/tcp/4001/ws` using `libp2p`
168+
→ Attempt connections via hints or fall back to default resolution.
169+
170+
**Input URI:**
171+
`https://dweb.link/ipfs/bafy...?provider=/dns4/hash-stream-like-server.io/tcp/443/https`
172+
173+
→ Extract CID: `bafy...`
174+
→ Parse `provider` params:
175+
176+
1. `/dns4/hash-stream-like-server.io/tcp/443/https` using `http`
177+
→ Attempt connections via hints or fall back to default resolution.
178+
179+
---
180+
181+
### Client Behavior and potential Server Roles
182+
183+
In addition to guiding client-side resolution, provider hints can be interpreted by servers under certain circumstances. The semantics of hint placement influence visibility and use:
184+
185+
- If the `provider` parameter is included in the **query** (`?...`), it MAY be communicated to the server depending on the client parsing the parameter.
186+
- If the `provider` is encoded as a **fragment** (`#...`), it is only accessible to the client (browsers do not send fragments to the server).
187+
188+
This distinction allows URI publishers to tailor behavior:
189+
190+
- **Client-only mode:** Use a fragment (`#provider=...`) to ensure the server remains unaware of hint data. This is useful for privacy-preserving client apps or when hints are intended to guide only the client.
191+
- **Server-assisted mode:** Use query parameters (`?provider=...`) to allow the server to parse and act on provider hints. This may enable proxy behavior, similar to existing IPFS gateways like `ipfs.io` or `dweb.link`.
192+
193+
Publishers of such URIs should consider the **security profile** and **trust assumptions** of their environment when deciding how to encode hints.
194+
195+
This flexibility supports a spectrum of use cases—from fully local client-side fetch strategies to cooperative client-server resolution pipelines.
196+
197+
## Design rationale
198+
199+
TODO
200+
201+
The rationale fleshes out the specification by describing what motivated
202+
the design and why particular design decisions were made.
203+
204+
Provide evidence of rough consensus and working code within the community,
205+
and discuss important objections or concerns raised during discussion.
206+
207+
### User benefit
208+
209+
TODO
210+
211+
How will end users benefit from this work?
212+
213+
### Compatibility
214+
215+
TODO
216+
217+
Explain the upgrade considerations for existing implementations.
218+
219+
### Security
220+
221+
TODO
222+
223+
Explain the security implications/considerations relevant to the proposed change.
224+
225+
### Alternatives
226+
227+
TODO
228+
229+
Describe alternate designs that were considered and related work.
230+
231+
## Test fixtures
232+
233+
TODO
234+
235+
List relevant CIDs. Describe how implementations can use them to determine
236+
specification compliance. This section can be skipped if IPIP does not deal
237+
with the way IPFS handles content-addressed data, or the modified specification
238+
file already includes this information.
239+
240+
### Copyright
241+
242+
Copyright and related rights waived via [CC0](https://creativecommons.org/publicdomain/zero/1.0/).

0 commit comments

Comments
 (0)