Skip to content

refactor: schema 4 with extensible systems and APIs #4

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 6 commits into from
Jul 30, 2025
Merged

refactor: schema 4 with extensible systems and APIs #4

Show file tree
Hide file tree
Changes from 1 commit
Commits
Show all changes
6 commits
Select commit Hold shift + click to select a range
437dbdd
refactor: schema 4 with extensible systems/apis
lidel Jul 28, 2025
6f83bc3
chore: remove DNS system
lidel Jul 29, 2025
d811a45
chore: merge IPNS system into AminoDHT for now
lidel Jul 29, 2025
9746ad1
chore: remove Profiles from JSON
lidel Jul 29, 2025
753001e
docs: description of Example system
lidel Jul 29, 2025
eec90be
docs: cleanup system type examples
lidel Jul 30, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
135 changes: 110 additions & 25 deletions autoconfig.json
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,34 +1,119 @@
{
"AutoConfigVersion": 2025072301,
"AutoConfigSchema": 3,
"Bootstrap": [
"/dnsaddr/bootstrap.libp2p.io/p2p/QmNnooDu7bfjPFoTZYxMNLWUQJyrVwtbZg5gBMjTezGAJN",
"/dnsaddr/bootstrap.libp2p.io/p2p/QmQCU2EcMqAqQPR2i9bChDtGNJchTbq5TbXJJ16u19uLTa",
"/dnsaddr/bootstrap.libp2p.io/p2p/QmbLHAnMoJPWSCR5Zhtx6BHJX9KiKNN6tpvbUcqanj75Nb",
"/dnsaddr/bootstrap.libp2p.io/p2p/QmcZf59bWwK5XFi76CZX8cbJ4BhTzzA3gU1ZjYZcYW3dwt",
"/dnsaddr/va1.bootstrap.libp2p.io/p2p/12D3KooWKnDdG3iXw9eTFijk3EWSunZcFi54Zka4wmtqtt6rPxc8",
"/ip4/104.131.131.82/tcp/4001/p2p/QmaCpDMGvV2BGHeYERUEnRQAwe3N8SzbUtfsmvsqQLuvuJ",
"/ip4/104.131.131.82/udp/4001/quic-v1/p2p/QmaCpDMGvV2BGHeYERUEnRQAwe3N8SzbUtfsmvsqQLuvuJ"
],
"AutoConfigVersion": 2025072801,
"AutoConfigSchema": 4,
"CacheTTL": 86400,
"SystemRegistry": {
"AminoDHT": {
Copy link

@aschmahmann aschmahmann Jul 29, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

As I think I've flagged elsewhere (but putting here so we can find it in the future since this PR is likely to merge into master rather than #1) requiring just names for the AminoDHT might make it harder for some kinds of custom DHT configuration. However, this use case seems sufficiently esoteric that we can probably wait for a user request before bumping the config version to handle it.

"URL": "https://github.com/ipfs/specs/pull/497",
"Description": "Public DHT swarm that implements the IPFS Kademlia DHT specification under protocol identifier /ipfs/kad/1.0.0",
"NativeConfig": {
"Bootstrap": [
"/dnsaddr/bootstrap.libp2p.io/p2p/QmNnooDu7bfjPFoTZYxMNLWUQJyrVwtbZg5gBMjTezGAJN",
"/dnsaddr/bootstrap.libp2p.io/p2p/QmQCU2EcMqAqQPR2i9bChDtGNJchTbq5TbXJJ16u19uLTa",
"/dnsaddr/bootstrap.libp2p.io/p2p/QmbLHAnMoJPWSCR5Zhtx6BHJX9KiKNN6tpvbUcqanj75Nb",
"/dnsaddr/bootstrap.libp2p.io/p2p/QmcZf59bWwK5XFi76CZX8cbJ4BhTzzA3gU1ZjYZcYW3dwt",
"/dnsaddr/va1.bootstrap.libp2p.io/p2p/12D3KooWKnDdG3iXw9eTFijk3EWSunZcFi54Zka4wmtqtt6rPxc8",
"/ip4/104.131.131.82/tcp/4001/p2p/QmaCpDMGvV2BGHeYERUEnRQAwe3N8SzbUtfsmvsqQLuvuJ",
"/ip4/104.131.131.82/udp/4001/quic-v1/p2p/QmaCpDMGvV2BGHeYERUEnRQAwe3N8SzbUtfsmvsqQLuvuJ"
]
},
"DelegatedConfig": {
"Read": [
"/routing/v1/providers",
"/routing/v1/peers",
"/routing/v1/ipns"
],
"Write": []
}
},
"IPNI": {
"URL": "https://cid.contact",
"Description": "Network Indexer - content routing database for large storage providers",
"DelegatedConfig": {
"Read": [
"/routing/v1/providers"
],
"Write": []
}
},
"IPNS": {
Copy link

@aschmahmann aschmahmann Jul 29, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

IPNS as a system name seems awkward. We don't have a "providers" system or a "peers" system these are just endpoints on the delegated routing endpoint.

The only thing that really comes to mind is defining IPNS as using AminoDHT and perhaps down the road other systems like IPNI, or IPNS over PubSub (and the associated systems that handle provider records) but this seems like overkill at the moment.

What do we gain from this system being here compared to something like one of:

  • Requiring the implementers to know that for IPNS they can leverage the systems they have natively, use delegation, or layer something like IPNS over PubSub on top of the provider record systems (or delegations) they have
  • Adding to the system registry the types of methods supported (even if there's no delegation option for them)

Copy link
Contributor Author

@lidel lidel Jul 29, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Ack. Right now its just DHT.

Simplified in d811a45: merged "IPNS" into "AminoDHT" for now. It should be acceptable, given how public good delegated-ipfs.dev/routing/v1/ipns works.

"URL": "https://specs.ipfs.tech/ipns/ipns-record/",
"Description": "InterPlanetary Name System - signed mutable records that point to CIDs with optional metadata",
"DelegatedConfig": {
"Read": [
"/routing/v1/ipns"
],
"Write": [
"/routing/v1/ipns"
]
}
},
"DNS": {
"URL": "https://datatracker.ietf.org/doc/html/rfc8484",
"Description": "DNS over HTTPS (DoH) - protocol for performing DNS resolution via the HTTPS protocol",
"DelegatedConfig": {
"Read": [
"/dns-query"
],
"Write": []
}
},
"Example": {
Copy link

@aschmahmann aschmahmann Jul 29, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

It's a shame JSON doesn't have a good way to add comments, but for clarity here IIUC the idea is meant to force implementers to gracefully handle systems they can't understand / don't know what to do with since the delegated endpoints aren't understood. Right?

Copy link
Contributor Author

@lidel lidel Jul 29, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Yes. Clarified that in SystemRegistry.Example.Description (753001e)

"URL": "https://example.com",
"Description": "Example routing system demonstrating extensibility. Clients should ignore unknown APIs they don't recognize",
"DelegatedConfig": {
"Read": [
"/example/v0/read"
],
"Write": [
"/example/v0/write"
]
}
}
},
"DNSResolvers": {
"eth.": [
"https://dns.eth.limo/dns-query",
"https://dns.eth.link/dns-query"
]
},
"DelegatedRouters": {
"mainnet-for-nodes-with-dht": [
"https://cid.contact/routing/v1/providers"
],
"mainnet-for-nodes-without-dht": [
"https://delegated-ipfs.dev/routing/v1/providers",
"https://delegated-ipfs.dev/routing/v1/peers",
"https://delegated-ipfs.dev/routing/v1/ipns"
]
"DelegatedEndpoints": {
"https://cid.contact": {
"Systems": ["IPNI"],
"Read": [
"/routing/v1/providers"
],
"Write": []
},
"https://delegated-ipfs.dev": {
"Systems": ["AminoDHT", "IPNI", "IPNS", "DNS"],
"Read": [
"/routing/v1/providers",
"/routing/v1/peers",
"/routing/v1/ipns",
"/dns-query"
],
"Write": [
"/routing/v1/ipns"
]
},
"https://example.com": {
"Systems": ["Example"],
"Read": [
"/example/v0/read"
],
"Write": [
"/example/v0/write"
]
}
},
"DelegatedPublishers": {
"mainnet-for-ipns-publishers-with-http": [
"https://delegated-ipfs.dev/routing/v1/ipns"
]
"Profiles": {
Copy link

@aschmahmann aschmahmann Jul 29, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Who are the "profiles" here meant to be seen by / interacted with that it's abstracting complexity? For example:

  1. End users where the implementers have given them flexibility to choose their profile
  2. Implementers who want an easy way to figure out what to enable / disable for their implementation

e.g. does the browser profile really want to be here vs in some defaults file chosen by the implementers and that can be different whether the platform is nodejs vs browser?

FWIW I do like the concept of the profiles and suggestions for implementers my question is if this seems like it'll be valuable to implementers spec'd in the file vs as some prose next to it / on the website.

Copy link
Contributor Author

@lidel lidel Jul 29, 2025 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

In my mind it was always closer to (2) – implementers. In places like Kubo, end user would never use these, but have something that implementers created.

To make this more clear, I've removed Profiles from JSON and instead put dome docs in index.html (9746ad1). We can refine examples in HTML later.

"browser": {
"PreferDelegated": ["AminoDHT", "IPNI", "IPNS", "DNS"]
},
"daemon": {
"PreferNative": ["AminoDHT", "IPNS", "DNS"],
Copy link

@aschmahmann aschmahmann Jul 29, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

DNS seems a little awkward here in how it plays interplays with the DNS resolvers

Copy link
Contributor Author

@lidel lidel Jul 29, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This way Kubo can ignore https://delegated-ipfs.dev/dns-query because it has own native DNS from OS, and still apply DNSResolvers for special TLDs.

We could remove it from autoconfig, but then Verified Fetch and inbrowser.link will have to hardcode https://delegated-ipfs.dev/dns-query or https://1.1.1.1/dns-query as the default resolver for ICANN TLDs.

Copy link
Contributor Author

@lidel lidel Jul 29, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

For the sake of simplicity, I will remove DNS system.
Implementations will have to hardcode their own "defualt DNS resolver".

Copy link
Contributor Author

@lidel lidel Jul 29, 2025 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Removed: 6f83bc3

"PreferDelegated": ["IPNI"]
Copy link

@aschmahmann aschmahmann Jul 29, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I suppose it doesn't matter either way, but does it really prefer delegated, or is there just not really a native option today (yes, there's a custom API but not with a ton of added value) so we'd be forced to fallback to delegated anyway.

Copy link
Contributor Author

@lidel lidel Jul 29, 2025 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Good question.

IPNI's "native" is HTTP as well, so its mostly semantics?

The way I understand it, everyone is free to adopt IPNI's "native" APIs which (afak) are https://cid.contact/cid/ and https://cid.contact/multihash/. For example, lassie uses /multihash one 🤷

But for IPFS clients its more cost-effective to use /routing/v1 rather than use custom HTTP query code that is specific to IPNI without any benefit in doing so. Thus, recommend "delegated" /routing/v1.

}
}
}
}
Loading