This chapter is the entry point for reading this technical manual. It is intended for resource providers, node operators, client and SDK developers, protocol implementers, integration developers, and technical personnel evaluating OpenAgenet (OAN). The manual covers resources such as Agent Services, Skills, MCP Servers, and Tool APIs, as well as supporting mechanisms including subject identities, resource DIDs, DID Documents, registration VCs, Root-verified ResourcePackages, content distribution, discovery indexing, and pre-call verification. Readers can use it as a guide from concepts to implementation: first read Chapters 1 through 4 to understand the goals, roles, architecture, and resource model, and then consult the identity, registration, publication, discovery, operations, and conformance chapters as needed.

The manual distinguishes four content statuses: design basis, which explains why a design was made; current system fact, which describes behavior demonstrated by existing code, interfaces, or deployments; reference implementation, which describes one implementation approach used by the OAN code repositories; and runtime evidence, which describes build, deployment, or smoke-test results from a particular environment at a particular time. Normative requirements are used only where interoperability, security, or data integrity must be preserved. A website display, example configuration, or result from one deployment must not be generalized into a mandatory capability for every node. When later chapters cite interfaces, code, or runtime data, they should state the evidence type and scope of applicability.

{
  "manual": "technical manual",
  "scope": ["resource identity", "registration", "trusted publication", "discovery", "governance"],
  "evidence_types": ["design", "current-fact", "reference-implementation", "runtime-evidence"],
  "status_rule": "Every conclusion should state its source, scope of applicability, and verification time"
}

This manual classifies its materials as design basis, normative rules, implementation evidence, and runtime evidence. Design basis explains goals and trade-offs; normative rules state interoperability baselines; implementation evidence explains how code realizes the rules; and runtime evidence states whether a particular environment works at a particular time. These four types of material may refer to one another, but one type must not substitute for another. During publication or review, record the manual version, referenced material versions, implementation commit, configuration version, test time, and applicable environment.

Revision History

Purpose and Scope

The manual covers the complete path from local preparation of a resource to its discovery and verification: the resource provider prepares the resource and local identity; the client submits the materials to a Registrar node; the Registrar node performs admission checks; the Root platform verifies and publishes the trusted ResourcePackage; the content distribution platform hosts retrievable materials; a Discovery node synchronizes and builds indexes; and the caller checks the DID, credentials, version, and governance status before connecting. The corresponding chapters explain the resource model, did:oan, DID Documents, ResourcePackages, VC/VP, signed messages, node authorization, semantic tags, public HTTP APIs, SDKs, the community Skill, lifecycle, operations, and conformance.

The manual does not prescribe which model or reasoning algorithm an agent must use internally, does not define all business logic of a business system, and does not replace external protocols such as A2A or MCP. Each chapter should state its applicable roles, inputs and outputs, responsible party, verifying party, state changes, exception handling, and retainable evidence. When a conclusion applies only to a reference implementation or a current deployment, its version, environment, and boundary should be stated.

Relationship to the OAN White Paper and Yellow Paper

The White Paper is the conceptual entry point for the project. It mainly explains why infrastructure for resource identity, trusted publication, and semantic discovery is needed for the Internet of Agents (IoA). The Yellow Paper focuses more on how the mechanisms work, explaining roles, data objects, trust boundaries, publication paths, authorization domains, state machines, security invariants, and reference verification methods. This manual organizes those materials into technical guidance that readers can consult and use, while adding implementation mappings, examples, operational boundaries, and verification paths.

Readers can start with the White Paper to understand “why,” use the Yellow Paper to understand “how the mechanisms are organized,” and then return to this manual to find “how to understand, integrate, implement, and verify” them. When different materials differ only in abstraction level, the manual should explain their relationship. When an actual conflict exists in fields, processes, or security boundaries, it should record the conflict location, impact, applicable version, and revision status rather than conceal it with vague wording.

During publication or review, record at least the specification version, referenced material versions, implementation commit, configuration version, test time, and applicable environment. When materials differ, first determine whether the difference is caused by abstraction level or is an actual conflict; only the latter should enter the conflict record and revision process.

Relationship to the did:oan Method Specification

The did:oan method materials define the method-specific DID syntax, method-specific identifiers, DID Document structure, verification methods, public-key representation, service endpoints, resolution behavior, and boundaries for control proofs. The related chapters of this manual do not reinvent those method rules. Instead, they explain how OAN uses them: how clients generate and store local keys, how resource controllers prove control, how Registrar nodes validate DID Documents, how the Root platform associates resource versions with trusted publication records, how Discovery nodes build verifiable indexes, and how callers resolve and verify signatures before connecting.

A minimal status decision can be represented as follows:

DID Document valid
    -> Resource control proof valid
    -> Accepted by Registrar node
    -> Published by Root platform
    -> Indexed by Discovery node
    -> Caller completes version, governance, and local permission checks

The steps above are not different names for one “usable” state. A DID Document that is valid in syntax, structure, and signature does not mean that the resource has been accepted by a Registrar node, published by the Root platform, indexed by a Discovery node, or granted permission for use. A Root publication fact cannot replace the caller’s checks of the DID Document, VC, endpoint, version, governance status, and local business permissions. Later chapters should explain how these states connect through fields, processes, and status transitions.

Relationship to Implementation Repositories and Deployment Materials

Implementation mappings in this manual help readers answer “where is this capability implemented, how can it be verified, and what are its current boundaries”; they are not themselves conformance proofs. Shared data structures, serialization, hashing, and cryptographic behavior should first be checked against oan-protocol-common; Root platform publication, governance status, and publication proofs against oan-root-services; registration admission and registration credentials against oan-registrar-node; synchronization, indexing, semantic retrieval, and discovery responses against oan-discovery-node; projection of on-chain governance events into runtime authorization read models against oan-trust-indexer; and client integration against oan-sdk-ts and the community Skill. README files, schemas, route handlers, tests, configuration examples, and deployment scripts provide different kinds of evidence, and their purpose should be stated when cited.

mapping:
  manual_section: "Chapter 8 Registration Protocol"
  repository: "oan-registrar-node"
  evidence: "Route handlers, request validation, integration tests"
  status: "Implemented with test evidence"
  checked_at: "YYYY-MM-DD"
  boundary: "The target environment's exact commit and deployment configuration prevail"

Each mapping should record at least the manual section, repository and module or file, corresponding version, implementation status, verification method, and known deviation. Implementation status should distinguish implemented with test evidence, implemented with insufficient evidence, partially implemented, and design-only. Deployment materials should also record environment variables, external services, databases, key boundaries, build artifacts, startup order, and post-deployment smoke tests. Addresses, node counts, and runtime metrics from the official environment are runtime evidence and should not be written as mandatory conditions for every environment.

Normative Language and Conformance Terms

This manual uses RFC-style keywords to indicate degrees of obligation: MUST corresponds to “must,” MUST NOT to “must not,” SHOULD to “should,” SHOULD NOT to “normally should not,” and MAY to “may.” These words are used only for confirmed interoperability, security, data-integrity, or conformance requirements. When describing current code behavior, deployment status, or operational advice, use more precise wording such as “current implementation,” “normally,” “recommended,” or “may.”

Conformance judgments should target a specific role and configuration profile rather than making a broad judgment about OAN as a whole. The capability boundaries of resource providers, Registrar nodes, the Root platform, the content distribution platform, Discovery nodes, the off-chain trust indexer, resolvers, and SDKs are not identical. Each test or runtime check should state its fixed input, prerequisite configuration, execution steps, expected output, failure impact, and evidence-retention method. Passing tests in a reference implementation does not mean that every third-party implementation is inherently conformant, and normal operation of the official deployment does not mean that the protocol covers every environment.

• [ ] This item states whether it is a normative requirement, reference implementation behavior, current deployment fact, or a capability not yet implemented.
• [ ] A verifiable source, version, or commit is provided.
• [ ] Evidence for resource registration, Root publication, discovery indexing, and pre-call verification is distinguished.
• [ ] The impact and handling of a deviation or implementation failure are stated.

References