Discovery Flow
Discovery is the read side of OAN. It helps users, SDKs, and agents find resources that match a need, but it does not replace Root proof or client verification. A correct Discovery result is not just a nice search card; it is a candidate linked to verifiable package evidence.
Discovery can be simple or sophisticated. It may support resource-type filters, capability tags, protocol hints, authorized-domain constraints, keyword search, semantic ranking, or explanation fields. Those retrieval features improve usefulness, but they operate over Root-verified package indexes.
This is the key product promise: Discovery improves selection without becoming the source of truth. A Discovery node can rank, filter, and explain; it cannot turn an unaccepted package into a trusted OAN resource. That boundary is what lets OAN support advanced search while keeping the evidence chain reviewable.
What Discovery Indexes
Discovery indexes the public resource surface that Root has accepted and published. This can include DID Document metadata, resource type, descriptions, examples, service bindings, protocol fields, capability tags, authorized domains, package references, lifecycle state, and proof references.
It should not index arbitrary unverified claims as trusted OAN resources. A Discovery node can crawl or cache supporting data if its implementation needs to, but the candidates it returns as OAN resources should be traceable to Root-accepted package facts.
This matters because the same resource may have attractive external material: a GitHub README, a marketplace description, a website, or a protocol manifest. Discovery may use references that were included in the accepted package, but it should be clear which fields are accepted OAN facts and which fields are external supporting material. The returned candidate should not blur those categories.
Query Inputs
A Discovery query can contain several kinds of intent:
| Input | Example | Role |
|---|---|---|
| Natural language query | “Find a skill that reviews API security.” | Main intent for semantic or text search. |
| Resource type | skill, mcp_server, tool_api, agent_service |
Narrows the expected resource form. |
| Capability tags | security-review, code-analysis |
Helps filter or rank by declared capability. |
| Protocol | mcp, https, package-based skill |
Helps match integration expectations. |
| Domain filter | technology |
Narrows by authorized-domain scope when allowed. |
| Limit | 10 |
Controls response size, not trust semantics. |
The website’s Discovery page intentionally keeps the form simple. It should let users describe what they need, optionally constrain type and protocol, add capability tags as chips, and inspect returned evidence without becoming a protocol console.
The form is therefore a bridge between natural language and structured trust. The query text expresses intent. Resource type and protocol express integration shape. Capability tags express expected function. Domain filters express governance scope where the endpoint supports them. None of those inputs replace verification of the returned candidates.
Candidate Construction
Discovery builds candidates from verified package records. It applies domain visibility rules, filters by resource type or protocol where requested, ranks by relevance, and attaches enough evidence for downstream verification.
A useful candidate should help answer:
- What resource is this?
- Which DID identifies it?
- What type of resource is it?
- Why did it match the query?
- Which domains and tags are associated with it?
- What package or Root proof supports it?
- How would a client continue to verify and use it?
If a result cannot answer those questions, it may be a search result, but it is not a strong OAN Discovery result.
The most useful candidates are also actionable. For a developer, the candidate should point to the next integration step. For a user, it should show enough explanation to choose among alternatives. For an SDK, it should contain enough identifiers and proof references to fetch or verify package material without scraping the website.
Signed Discovery Responses
Discovery should sign response material so clients can verify where the answer came from and whether it is fresh enough for use. A signed response is not a substitute for Root proof; it is an additional layer. The client can verify the Discovery node’s authorization, the response signature, the candidate package proof, and the candidate lifecycle.
This layered evidence is what makes OAN Discovery different from a general web search box. Discovery is not saying “I found something on the internet.” It is saying “I found these Root-verifiable resources in my authorized index, and here is the evidence chain.”
Freshness matters. A signed response from a Discovery node should be evaluated with its timestamp, nonce, or response freshness policy. A valid old answer may not be safe to use if the resource lifecycle or node authorization changed after it was produced.
Authorization During Discovery
Discovery nodes have their own authorizedDomains. A node should not expose resources outside its scope. Root distribution can reduce mistakes by notifying only matching Discovery nodes, but Discovery should still enforce scope locally when synchronizing and serving.
This is important for third-party operation. A specialized Discovery node can serve a domain community without claiming all-domain authority. An official full-scope Discovery node can expose the general public set. Clients can choose endpoints according to trust and coverage.
Authorized-domain enforcement also makes Discovery behavior predictable. A resource in a domain that a node does not cover should not appear there, even if the node has downloaded package data or a semantic index would rank it highly. Trust filtering comes before ranking.
Discovery Is Not Invocation
A Discovery result is a candidate. The next step depends on resource type. A Skill may need package fetch and installation. An MCP Server may require a connection handshake. A Tool/API may require API authentication and schema validation. An Agent Service may require signed invocation or another protocol-specific flow.
OAN helps the consumer decide whether the candidate is worth using and how to verify it. It does not remove the need for runtime authorization, access control, sandboxing, rate limits, user approval, or domain-specific safety checks.
This is why Discovery should be described as “trusted discovery” rather than “trusted execution.” OAN reduces uncertainty before first contact. The resource’s own protocol and the consumer’s own environment still control what happens after contact begins.