This chapter specifies the process by which resources enter OpenAgenet (OAN) from a client. After the client creates the resource DID, DID Document, resource metadata, ResourcePackage, and resource control proof, it submits them to a Registrar node. The Registrar node performs entry validation and authorization-domain validation, and then calls the Root platform’s resource verification and publication interface through a signed upstream request. The current reference implementation uses /resources/register and the compatible /resources/submit entry points. The successful path includes a successful Root platform request, registration VC issuance, registration-record persistence, and response delivery.

When the Registrar node returns status: submitted, this only means that the registration process has obtained successful results from that node and its upstream call. It does not mean that the resource has completed network-wide publication, content distribution, or discovery indexing. The client should save and display the registration result, Root proof, and the indexing status of Discovery service nodes separately.

The registration path can be summarized as “the client prepares the materials, the Registrar node accepts and validates them, the Root platform verifies and publishes them, and the Registrar node returns the registration result.” A client must not infer discovery visibility solely from a success message on a page. It should determine the three stages separately from the resource registration record, the content returned by the Root platform, and the query result from a Discovery service node. The public interface of a Registrar node is the resource submission entry point; upstream calls between nodes belong to a protected service-to-service protocol. Their request formats and signing subjects must not be mixed.

The Root platform verification, content distribution, and discovery indexing shown above are consecutive stages that may complete asynchronously. resource-verified-and-queued or status: submitted returned by a Registrar node only represents the corresponding registration or queueing fact. It cannot be used to infer that the content distribution platform has completed hosting, or that a Discovery service node has built a queryable index.

8.1 Registration Targets and States

Registration state should distinguish the client’s local state, the Registrar node’s processing state, and the Root platform’s publication state. The following logical states are recommended:

Passing browser preview or local validation does not create a registration record; a network timeout must not directly generate a new DID or new version. A retry with the same business materials should reuse the original resource DID, version, and hashes, and the server or query interface should be used to confirm the actual result.

8.2 Registration Request Structure

The core payload of the registration entry point is ResourceRegistrationSubmission. Its main fields and purposes are as follows:

These fields can be divided into four groups according to validation order:

An illustrative request fragment is:

{
  "resourceDid": "did:oan:SKFI:...",
  "resourceType": "skill",
  "didDocument": {"id": "did:oan:SKFI:...", "verificationMethod": []},
  "didDocumentHash": "sha256:...",
  "metadata": {"resourceType": "skill", "authorizedDomains": ["software"]},
  "packageVersion": "1.0.0",
  "packageHash": "sha256:...",
  "metadataHash": "sha256:...",
  "hashAlgorithm": "sha256",
  "registrationCredential": null,
  "subjectControlProof": {"challenge": {}, "proof": {}}
}

Before calling the Root platform, the Registrar node should reject requests whose resource DID, DID Document identifier, challenge target, or hashes are inconsistent. Whether unknown extension fields are retained is determined by the protocol version. Unknown core fields, invalid types, or unparseable structures must not be treated as valid requests.

A valid request must at least satisfy all of the following relationships: didDocument.id == resourceDid; the resource type declared by the DID Document must be consistent with resourceType; the three hash fields must be interpretable according to hashAlgorithm; and the subject and document hash in the control challenge must correspond to the resource DID and didDocumentHash, respectively. For example, a request that changes resourceType from skill to agent_service without simultaneously updating the DID Document and metadata should be rejected during local validation by the Registrar node. registrationCredential remains in the shared request model for compatibility and record-keeping, but the Registrar node clears it when constructing the upstream request to the Root platform, preventing a credential previously issued by the Registrar node from being used as the Root platform’s verification basis.

The key interaction for forwarding a request from the Registrar node to the Root platform can be summarized as follows:

This interaction describes only the protected upstream call between the Registrar node and the Root platform. The client submission entry point, registration VC issuance, and subsequent content distribution are handled separately in the other sections of this chapter. A successful Root platform response does not change the fact that the Discovery service node may not yet have completed indexing.

8.3 Local Identity Initialization and Import

The Local Identity is a collection of materials in which the client stores subject configuration, resource control keys, and necessary credentials. It is not a user account on a Registrar node. It is used to create or restore control relationships and to issue control proofs for specific registration operations. A Registrar node should receive only the DID Document, public keys, proofs, and registration materials required for verification. It must not receive subject or resource control private keys.

The resource control relationship can be represented as follows: “the Local Identity holds the control key, the resource DID Document publishes the verification method, and the control proof binds one specific operation to that resource and document version.” Therefore, a Local Identity and a resource are not the same object. One subject configuration may control multiple resources, but each registration request must identify one resourceDid and use a proof matching that resource’s DID Document. The Registrar node verifies public materials and signature results, rather than the client’s assertion that “this is my resource.”

8.3.1 Create a New Local Identity

The client generates a subject control key and subject DID, and saves the public verification material and local configuration. It can then create an independent resource DID and resource control material for each resource. Creating a Local Identity does not itself create a Registrar node record and does not mean that a resource has obtained a network publication state.

8.3.2 Import a Local Identity

The client parses a Local Identity backup and validates the correspondence among the subject DID, public key, private key, resource configuration, and credentials. After a successful import, the client can continue controlling existing resources, but a new registration, update, or retry must still create a new proof for the target DID, version, hash, and operation purpose.

8.3.3 Private Keys and Subject Configuration

Private keys are used only on the client to issue control proofs or other protected signatures. Subject configuration describes the relationship between the subject DID and resources. Server requests and logs may contain public DIDs, public keys, signatures, hashes, and credentials, but must not contain private keys or plaintext materials from which private keys can be recovered.

8.3.4 Identity Backup and Recovery

An identity backup should contain the structured information required to restore control relationships, and should indicate its sensitivity and version. After recovery, the client should check the key correspondence and DID Document consistency again. The existence of a backup file does not mean that the resource has been registered, and a recovery failure must not overwrite an already valid identity on the client.

8.4 DID Document Draft Generation

The client generates a DID Document from the resource type, name and description, capability tags, authorization domains, endpoints, version, Local Identity, and control key. id must equal resourceDid; oanMetadata.resourceType and subjectType must match the request; verification methods must provide resolvable public keys; and service endpoints and ResourcePackage information must be bound to the resource metadata.

The preview button may generate or reuse a local DID Document and display validation results, but expanding the preview must not issue a registration network request. If the form, Local Identity, advanced access settings, or ResourcePackage information has not changed, the client may reuse the generated document. When an input affecting the DID, document hash, version, or control proof changes, it must regenerate the document and sign it again.

To prevent the client from repeatedly producing different resource identities when the user has not changed the materials, the client should form an internal snapshot from the form values, the Local Identity subject DID, resource control configuration, endpoints, authorization domains, version, and ResourcePackage digest used to generate the DID Document. If the snapshot is identical and a preview document already exists, clicking the button only toggles the expanded state of the preview area. If the snapshot changes, the client regenerates the document and related hashes. This cache is only a client-experience optimization and cannot replace the Registrar node’s revalidation of the request materials.

8.5 Pre-submission Local Validation

Before submission, the client should at least check the following conditions: a Local Identity has been created or imported; a resource type has been selected; required fields such as name, description, endpoint, authorization domain, capability tags, and version are complete; the DID syntax matches the resource type; the DID Document, metadata, ResourcePackage, and hashes are consistent; the target, purpose, document hash, and verification method of the control challenge are correct; and the control proof can be verified with a public key in the DID Document. Error messages should identify the missing condition, such as “Local Identity is required,” “Resource endpoint is required,” “No authorization domain selected,” or “DID Document hash is inconsistent.”

The preview button performs only local generation and validation. Before sending a request, the submit button reuses the validation result. Neither button should submit automatically when the page is opened. A failed validation must not write a registration record to the Registrar node, a publication record to the Root platform, or a successful registration VC.

Local validation results should preferably be returned by field so that the UI and SDK can take deterministic actions:

{
  "valid": false,
  "errors": [
    {"field": "localIdentity", "code": "required", "message": "Local Identity is required"},
    {"field": "serviceEndpoint", "code": "required", "message": "Resource endpoint is required"}
  ]
}

When valid: false, the client must not enter the submission request. Network unavailability is a submission-stage error and must not be disguised as a local-field error. A successful preview proves only that the current browser can generate and validate the draft; it does not prove that the Registrar node or Root platform has accepted the materials.

8.6 Resource Control Proof Verification

The Registrar node should verify the proof payload, signature, and business context together. The target resource DID, DID Document hash, verification method, operation purpose, challenge Registrar node, time window, and nonce must match the current request; the public key and signature algorithm must be parseable. A missing, expired, wrong-purpose, wrong-target, hash-inconsistent, or reused proof should be rejected before the Root platform is called.

A failed control proof must not produce a successful registration state or registration VC. The node may save the challenge ID, resource DID, document hash, verification method, verification time, and error code for auditing, but must not save the signing private key.

The validation order should first check structure and context, then verify the signature, and only then begin the publication call:

Request is parseable
  -> challenge.subjectDid == resourceDid
  -> challenge.didDocumentHash == request.didDocumentHash
  -> challenge.registrarDid == current Registrar node DID
  -> purpose, issuedAt, expiresAt, and nonce are valid
  -> verificationMethod is in the DID Document's assertionMethod
  -> Resolve public key and verify signature
  -> Continue with the registration flow

Any failure must stop the subsequent Root platform call. A successful signature check proves only that the signer possesses the corresponding private key and that the signed content has not been modified. Node authorization scope, resource type, version, and Root platform publication conditions must still be verified separately.

8.7 Registrar Node Authorization and Scope Validation

The current Registrar node reads the authorization domains in its own DID Document, checks consistency between the authorization domains in the resource DID Document and those in the request metadata, and then determines whether the node’s authorization domains cover the resource domains. Authorization domains must be non-empty, correctly formatted, deterministically ordered, and free of privilege escalation. When they are inconsistent or exceed the node’s scope, the node should return an error before calling the Root platform.

The node signing key proves only that the request came from the node’s operating boundary. The node authorization VC proves that the node has the corresponding role and scope. The resource control proof is a separate condition.

The request sent by a Registrar node to the Root platform is bound by SignedRequestEnvelope to a request ID, protocol version, purpose, HTTP method, path, audience, timestamp, nonce, request-body hash, and node proof. The Root platform can use these values to check which Registrar node submitted which materials, for what purpose, and at what time. The node-to-node signature does not replace the resource control proof, and does not automatically make the Registrar node the resource controller.

8.8 Resource Type, Metadata, Endpoint, and ResourcePackage Validation

The resource type, DID semantic encoding, DID Document metadata, resource metadata, and ResourcePackage should form one consistency chain. The resource DID, resource type, version, DID Document hash, metadata hash, and ResourcePackage hash must reference one another. Endpoints should conform to the declared protocol and format. Capability tags should be interpretable through the capability tag tree or permitted extension rules. Authorization domains must not be bypassed through free-form text.

The current validate_shape() covers DID syntax, resource-type relationships, DID Document identifiers, resource structure, ResourcePackage version, hash algorithm, three classes of hash references, challenge target DID, document hash, and operation purpose. Whether an endpoint is reachable, whether the business is safe, and whether the resource meets the caller’s quality requirements are judgments for later publication or pre-invocation stages and cannot be replaced by shape validation.

8.9 Duplicate Registration and Idempotency

Business idempotency should be determined by the resource DID, resource type, version, DID Document hash, metadata hash, and ResourcePackage hash, rather than by submission time or VC issuance time. The request ID and nonce provide request correlation, freshness, and replay protection; they do not alone determine whether two requests represent the same resource version.

8.9.1 Repeated Registration of the Same DID

When the same DID is submitted again, the server should verify control first, and then compare the version and hashes. Identical materials should return the existing registration result or an explicit idempotent result. The same DID with a different version or any different hash should enter the same-DID update decision. Invalid control proof must not overwrite the existing record.

8.9.2 Basis for Idempotency Decisions

An idempotency decision depends at least on the resource DID, resource type, version, DID Document hash, metadata hash, and ResourcePackage hash. The system should also save the request ID, processing time, and result to distinguish a business retry from a new version. The current Registrar node writes records using an upsert by resource DID to SQLite, PostgreSQL, or file storage. This can preserve the current record, but it is not by itself evidence of a complete version-level idempotency history.

8.9.3 VC Reissuance

A retry for the same business version may return the saved registration VC, or may issue a content-equivalent VC with a different issuance time according to an explicit policy. The client should identify the credential by the resource DID, version, hashes, and state, and must not treat a new issuance time as a resource version update.

8.9.4 Duplicate Publication Control at the Root Platform

The Root platform should make repeated publication of the same DID, version, and hashes produce one business result. A different hash or version should enter an update, conflict, or rejection path. A successful upstream HTTP response received by a Registrar node is not sufficient to prove that the Root platform completed duplicate-publication deduplication; the publication proof and sequence record are the evidence for that determination.

8.10 Resource Updates and Same-DID Version Updates

An update under the same DID preserves the resource identity, but must produce a new version, document hash, or ResourcePackage hash and express the predecessor relationship through fields such as previousVersion. The new version must use the current control relationship to generate a new control proof. An old registration VC or old ResourcePackage cannot automatically authorize a future update. Version increments, concurrent conflicts, history retention, and rollback are jointly enforced by the Registrar node and Root platform. The specific publication replacement rules are described in Chapter 9.

8.10.1 Update Authorization Verification

The verifier must confirm that the submitter is still authorized by the current DID control relationship, and must check that the control proof is bound to the new document hash, version, purpose, and challenge. An update supported only by an old credential without a new control proof for the new version must be rejected.

8.10.2 DID Document Updates

An updated DID Document continues to use the original resource DID, and its document hash must be included in the registration submission and ResourcePackage. Adding, replacing, or deactivating verification methods requires a verifiable control chain. If the update cannot be proven to have been authorized by the current controller, the current document must not be replaced.

8.10.3 Resource Metadata and Endpoint Updates

Changes to the resource description, capability tags, authorization domains, protocol bindings, or endpoints should produce a new metadata hash and ResourcePackage hash. Expanding the authorization domain cannot be achieved by changing text fields alone. Endpoint reachability also cannot replace business security and invocation-authorization checks.

8.10.4 New Version Publication and Old-Version Handling

After a new version is accepted, the Root platform should clearly identify the current version, historical versions, and old-version states. Discovery service nodes synchronize according to the publication sequence. An old version may be retained for auditing or rollback, but must not be confused with the latest version in query results.

8.11 Registration VC Issuance and Retrieval

In the current reference implementation, the registration credential generation logic is called only after the Root platform’s resource verification and publication interface returns success, and the registration VC is written to the registration record and successful response. The issuer of the registration VC is the Registrar node, and its credential subject is the resource DID. Its claims include registration facts such as resource type, version, hashes, authorization domains, and lifecycle.

8.11.1 Conditions for VC Issuance

Before issuance, entry-shape validation, resource authorization-domain validation, control-proof processing, and the Root platform request must be completed. Passing local preview, clicking Submit, or the Registrar node receiving a request is not by itself a condition for issuance.

8.11.2 VC Delivery

The current successful response contains status, resourceDid, resourceType, registrationCredential, and rootResponse. The client should save the original VC and associate it with the DID Document, version, and hashes. rootResponse must still be parsed according to the Root proof and status rules.

8.11.3 Handling a Missing or Empty VC

If the registration result is successful but the VC is missing or empty, the client should record the registration state and credential state separately, and clearly indicate that the credential has not yet been obtained. It must not fabricate an empty VC or treat an empty value as a valid credential. Queries or retries should retain the original DID, version, and hashes.

8.11.4 Local VC Storage

The registration VC should be associated with the resource DID Document and resource version in local files. When the client packages and downloads the VC, DID Document, and Local Identity backup, the private key remains sensitive material that may be kept only by the controller. It must not be sent to a node or public storage.

8.12 Registration Responses and Error Handling

The current Registrar node handler receives Json<ResourceRegistrationSubmission> and returns dynamic JSON on success. The stable core fields of a successful response are status, resourceDid, resourceType, registrationCredential, and rootResponse. rootResponse preserves dynamic content returned by the Root platform and must not be assumed by the client to be a fixed VC or an indication that network-wide publication is complete.

The following handler relationship describes the actual input and output types. It is a concise representation of the interface contract, not a complete implementation that can be substituted directly:

async fn register_resource(
    State(state): State<AppState>,
    Json(submission): Json<ResourceRegistrationSubmission>,
) -> ApiResult<serde_json::Value>;

The ResourceVerifyAndPublishRequest exchanged between the Registrar node and Root platform also contains registrarDid, the original registration submission, and upstreamAuth. A client must not construct this internal forwarding object itself, and must not treat the Registrar node’s registrationCredential as the Root platform’s Root proof. The error, status code, and request-correlation identifier in an error response should be used together to decide whether to correct, query, retry, or stop.

In the current implementation, errors are returned mainly through the HTTP status and error text. A stable future protocol should add a request ID, error code, registration state, upstream state, and retryable flag so that clients do not have to infer network state from free text.

Response handling is recommended to follow these deterministic rules:

{
  "status": "submitted",
  "resourceDid": "did:oan:SKFI:...",
  "resourceType": "skill",
  "registrationCredential": null,
  "rootResponse": {"status": "published"}
}

When an HTTP request times out without a response, the client can record only “result unknown,” retain the original DID, version, and hashes, and query or retry with the same materials. It must not generate a new DID on that basis. When a non-success HTTP status is received, the result must not be saved as a successful registration. When a success status is received but the VC is empty, the registration state and credential state should be displayed separately; only a credential that was actually obtained and verified may be downloaded as a VC file.

8.13 Registration Audit Records

A registration record should at least associate the resource DID, resource type, version, DID Document hash, metadata hash, ResourcePackage hash, authorization domains, Registrar node, registration VC, Root response summary, submission time, and processing result. The current write_resource_record() writes by resource DID to SQLite, PostgreSQL, or file storage. A complete audit implementation should therefore also retain the operation type, request ID, previous and new versions, and failure reason, so that an upsert does not erase the historical context.

Audit records must not store resource control private keys, Local Identity backups, or recoverable secrets. DID, public key, hash, challenge ID, request ID, state, and error code may be used as trace evidence. Audit-read permissions must be separated from the public discovery interface.

8.14 Resource Update Authorization and Same-DID Replacement

After receiving new materials for the same DID, the server should confirm the control proof, version relationship, and hash relationship in sequence. The same version with the same hashes is an idempotent retry; the same version with different hashes is a conflict; a new version with a valid predecessor relationship may enter the update flow; version rollback, a missing predecessor, an unapproved authorization change, or an invalid control proof should be rejected or sent for manual handling. The Registrar node may save the acceptance record, but the Root platform determines the network publication fact.

The following table can be used to check replacement decisions:

8.15 Submission Retries, Idempotency Keys, and Duplicate Handling

The upstream request from a node to the Root platform uses SignedRequestEnvelope to bind the request ID, protocol version, purpose, method, path, audience, request time, request nonce, request-body hash, and proof. The security layer uses nonce storage and a time window for replay protection. Business idempotency depends on the resource DID, version, and content hashes. After a client timeout, it should preserve the original materials, first query the existing result or retry with the same business materials, and must not immediately generate a new DID to conceal an unknown result.

8.16 Registration Rate Limiting and Abuse Control

The public registration entry point should limit the request rate per time period, request-body and ResourcePackage size, failure count per source, same-DID conflict count, and upstream-forwarding concurrency. Control-proof, node-authorization, and authorization-domain checks should be performed early to reduce the storage, network, and computation pressure caused by forged materials. Rate limiting must not misclassify a legitimate same-DID idempotent query as a new version, and throughput must not be gained by weakening control-proof checks.

The current reference implementation explicitly includes shape validation, authorization-domain coverage checks, upstream request signing, and nonce replay protection. If a reverse proxy, WAF, or service-level rate limiter is enabled in deployment, the actual policy, response codes, and recovery method should be documented in the deployment documentation.

Registration Flow Acceptance Checklist

• [ ] For an empty form, missing Local Identity, missing endpoint, or missing authorization domain, the client identifies the specific condition.
• [ ] Before calling the Root platform, the Registrar node completes request-shape, resource-authorization-domain, and control-proof validation.
• [ ] When the Root platform fails or the network times out, the client does not display network-wide publication success and does not lose the original DID and version materials.
• [ ] The registration VC in a successful response can be associated with the resource DID, version, and three classes of hashes.
• [ ] Retries with the same DID, version, and hashes receive different handling from updates with a different hash or version.
• [ ] Registration, Root publication, content distribution, and discovery indexing states can be observed and verified separately.
• [ ] Audit records can trace requests without containing private keys, Local Identity backups, or other sensitive secrets.

References