# Method Specification for Ontology

## Abstract

ONT ID is Ontology's decentralized identity framework based on W3C Decentralized Identifiers (DIDs) specification using blockchain and cryptography technology, which can instantly identify and connect people, assets, things, and events. ONT ID offers the features of decentralization, self-management, privacy protection and ease of use. With ONT ID, the privacy and security of users' identity and data are fully protected and users can have complete control over their own identity and data.

The ONT ID specification conforms to [W3C DIDs specification](https://www.w3.org/TR/did-core/) and extends the definition and features on its basis.

## Conformance and Terminology

This specification assumes a fair degree of understanding of [W3C DIDs specification](https://www.w3.org/TR/did-core/).

The key words **MUST**, **MUST NOT**, **REQUIRED**, **SHALL**, **SHALL NOT**, **SHOULD**, **SHOULD NOT**, **RECOMMENDED**, **MAY**, and **OPTIONAL** in this document are to be interpreted as described in [IETF RFC 2119](https://www.ietf.org/rfc/rfc2119).

### ONT ID

Used to denote Ontology's blockchain technology and cryptography based decentralized identity framework. Also denotes the decentralized identifier allocated to entities that part of the decentralized Ontology network.

### SHA256

A part of the SHA-2 cryptographic hash family designed by the United States National Security Agency. First published in 2001.

### Base58

A popular encoding scheme commonly used in blockchain technology. Maintains readability while allowing for data compression and encoded verification.

### ABNF

An abbreviation for augmented Backus–Naur form. An ABNF specification is a set of derivation rules.

## ONT ID Format

### ONT ID Syntax

ONT ID is a URI conforming to [IETF RFC 3986](https://www.ietf.org/rfc/rfc3986) and **SHOULD** be generated by each entity itself.

ONT ID is generated in conformity with [W3C DIDs specification](https://www.w3.org/TR/did-core/)。

ONT ID is generated as described in ABNF as follows:

```
ontid        = "did:ont:" ontid-string
ontid-string = 1* idchar
idchar       = 1-9 / A-H / J-N / P-Z / a-k / m
```

"did:ont:" denotes that ONT ID is the decentralized identifier conforming to [W3C DIDs specification](https://www.w3.org/TR/did-core/) that is registered on the Ontology blockchain; `idchar` includes all the characters of the Base58 encoded character set.

`ontid-string` **MUST** be generated using the following method:

1. Generate a 20-byte random number.
2. Append 1-byte tag bits. Append 1-byte tag bits to the generated random number, i.e. data = VER || h;
3. Calculate 4-byte parity bits. Calculate the SHA256 hash of the data twice and take the first 4 bytes as parity bits, i.e. checksum = SHA256(SHA256(data))\[0:4];
4. Encode. Encode the above result to a Base58 encoded value, i.e. ontid-string = Base58(data || checksum).

In the above stated process, || represents the connector that connects the two adjoining byte strings. The recommended value of `VER` is 23.

Below is an example of an ONT ID:

```
did:ont:AderzAExYf7yiuHicVLKmooY51i2Cdzg72
```

### ONT ID URL Syntax

The ONT ID URL syntax follows the DID URL rules defined in [W3C DIDs specification](https://www.w3.org/TR/did-core/).

The ONT ID URL syntax is as follows.

```
ontid-url = "did:ont:"ontid-specific-id
          [ ";" param ] [ "/" path ]
          [ "?" query ] [ "#" fragment ]
```

For more information, see the rules about [param](https://w3c.github.io/did-core/#method-specific-did-url-parameters)，[path](https://w3c.github.io/did-core/#path)，[query](https://w3c.github.io/did-core/#query) and [fragment](https://w3c.github.io/did-core/#fragment) as defined in [W3C DIDs specification](https://www.w3.org/TR/did-core/).

## ONT ID Registration and Deactivation

ONT ID **MUST** be registered on the Ontology blockchain to be activated, and the same ONT ID **MUST NOT** be registered more than once.

Only the owner or delegate of the ONT ID can deactivate it.

When an ONT ID is deactivated, all the related data, including private keys, delegates, properties, and recovery person, will be deleted and only the identifier of the ONT ID will remain on the Ontology blockchain.

Deactivated ONT ID can no longer be used and cannot be reactivated for use.

## ONT ID Document

Each ONT ID will have a corresponding ONT ID Document.

ONT ID Document is a method of serializing ONT ID information expressed using [JSON-LD](https://www.w3.org/TR/json-ld/) as defined in [DID Documents](https://www.w3.org/TR/did-core/#did-documents) of the W3C DIDs specification.

Below is the structure of the ONT ID Document:

```javascript
{
  "@context": ["https://www.w3.org/ns/did/v1", "https://ontid.ont.io/did/v2"],
  "id": "did:ont:AderzAExYf7yiuHicVLKmooY51i2Cdzg72",
  "publicKey": [{...}],
  "authentication": [{...}],
  "controller": [{...}],
  "recovery": [{...}],
  "service": [{...}],
  "attribute": [{...}],
  "created": [{...}],
  "updated": [{...}],
  "proof": [{...}]
}
```

### Context

ONT ID Documents **MUST** include a `@context` property.

The value of the @context property **MUST** be one or more URIs, where the value of the first URI **MUST** be <https://www.w3.org/ns/did/v1> and the value of the second URI **MUST** be [https://ontid.ont.io/did/v2](https://ontid.ont.io/did/v1). For more information, see [W3C DIDs specification](https://w3c.github.io/did-core/#production-0).

Below is an example:

```javascript
{
  "@context": ["https://www.w3.org/ns/did/v1","https://ontid.ont.io/did/v2"]
}
```

In practice, the terms in the context provided by W3C and Ontology may not be able to meet users' demand. In this case, users need to define the context themselves and can use [embedded context](https://www.w3.org/TR/json-ld/#dfn-embedded-context) for extensions.

For example, users need to append a property to an ONT ID, create the corresponding context for the type value of the property and publish the context to an URI accessible to all users. This is represented in the ONT ID Document as follows:

```javascript
{
  "attribute": [
    {
      "@context": {
        "some-type": "uri-of-the-context",
      },
      "id": "did:ont:some-ont-id#some-attribute",
      "type": "some-type",
      "value": "some-value"
    },
  ]
}
```

### Identifiers

ONT ID Documents **MUST** include an `id` property to specify the ONT ID identifier linked to the Document.

The value of id **MUST** be a valid ONT ID.

```javascript
{
  "id": "did:ont:AderzAExYf7yiuHicVLKmooY51i2Cdzg72"
}
```

### Public Keys

An ONT ID Document **MUST** include a `publicKey` property to specify a set of public keys linked to that ONT ID.

Public and private key pairs can be used for the self-management, authorization, and verification of ONT ID. An ONT ID can be linked to multiple public and private key pairs and one pair of public and private keys can also be used to manage multiple ONT IDs.

When an ONT ID is registered on the Ontology blockchain, it **SHOULD** be bound to the public key of the ONT ID owner. The owner should keep the matching private key safely.

Every public key object linked to the `publicKey` property **SHOULD** include the fields `id`, `type`, `controller` and `encoding`.

Each linked public key has its own identifier specified using the field `id`. Each bound public key is numbered starting from 1 according to the linking order. The format of "id" is

```
did:ont:some-ont-id#keys-{index}
```

`{index}` is the serial number of the public key.

Bound public keys can be revoked. Revoked public keys cannot be reactivated, but still possess the original serial numbers.

The value of the `type` field represents the corresponding cryptographic algorithm of the public key. Ontology supports an array of international standard cryptographic algorithms, such as **ECDSA**, **EdDSA** and **SM2** signature.

The value of the `controller` field, which identifies the controller of the corresponding private key, **MUST** be a valid ONT ID, denoting that the public key is controlled by this ONT ID.

The `encoding` key is the corresponding encoding format of the public key and the value is the result value of the public key using that encoding format. The encoding formats that Ontology supports include `publicKeyPem`, `publicKeyHex` and `publicKeybase58`.

Below is a specific example of the `PublicKey` property:

```javascript
{
  "publicKey": [
    {
      "id": "did:ont:AderzAExYf7yiuHicVLKmooY51i2Cdzg72#keys-1",
      "type": "EcdsaSecp256r1VerificationKey2019",
      "controller": "did:ont:AderzAExYf7yiuHicVLKmooY51i2Cdzg72",
      "publicKeyHex": "02a545599850544b4c0a222d594be5d59cf298f5a3fd90bff1c8caa095205901f2"
    }
  ]
}
```

### Authentication

ONT ID Documents use an **OPTIONAL** `authentication` property to specify verification methods.

ONT ID allows users to add the authentication property to denote that the holder of that ONT ID has authorized a set of verification methods for identification.

This part is derived from [W3C DIDs specification](https://www.w3.org/TR/did-core/#services).

Below is an example:

```javascript
{
  ...
  "authentication": [
    "did:ont:AderzAExYf7yiuHicVLKmooY51i2Cdzg72#keys-1",
    {
      "id": "did:ont:AderzAExYf7yiuHicVLKmooY51i2Cdzg72#keys-2",
      "type": "EEcdsaSecp256r1VerificationKey2019",
      "controller": "did:ont:AderzAExYf7yiuHicVLKmooY51i2Cdzg72",
      "publicKeyBaseHex": "03a835599850544b4c0a222d594be5d59cf298f5a3fd90bff1c8caa064523745f3"
    }
  ],
}
```

### Delegation

In an ONT ID Document, an **OPTIONAL** `controller` property is used to designate a delegate.

An ONT ID can be delegated to and controlled by other ONT IDs. A designated delegate **MUST** be specified when registering the ONT ID on the Ontology blockchain.

The ONT ID of the delegate has the authorization of registration and deactivation of the delegated ONT ID, and can modify properties `publicKey` and `authentication` of the delegated ONT ID.

It is worth noting that an ONT ID Document can assign `controller` without designating `authentication`.

The ONT ID of the delegate **MUST** be self-managed.

The delegate can be an ONT ID or a management group consisted of multiple ONT IDs. The management group can set complex threshold control logic to meet different security requirements. For example, set a management group of n ONT IDs and specify that the group can only perform an operation with the signature of at least m(<=n) ONT IDs. The setting is expressed as follows:

```javascript
{
  "threshold": "m",
  "members": ["ID1", "ID2", ... , "IDn"]
}
```

Then, define the control logic of the recursive combination, meaning that group members can either be ONT ID, or a nested management group, as shown below:

```javascript
{
  "threshold": "m1",
  "members": [
    "ID1",
    {
      "threshold": "m2",
      "members": ["ID2", ...]
    },
    ...
  ]
}
```

Below is a specific example representing that either `did:ont:AderzAExYf7yiuHicVLKmooY51i2Cdzg72`, or `did:ont:AXjJnU1TJViks4KUGQruiXwkKznwVpz7Z9` and `did:ont:AKwf6DvKFSBxhsmhjGCvJgaxHvCEQmpZZv` together can act as a delegate.

```javascript
"controller:" [
  {
    "threshold": 1,
    "members": [
      "did:ont:AderzAExYf7yiuHicVLKmooY51i2Cdzg72",
      {
        "threshold": 2,
        "members": ["did:ont:AXjJnU1TJViks4KUGQruiXwkKznwVpz7Z9", "did:ont:AKwf6DvKFSBxhsmhjGCvJgaxHvCEQmpZZv"]
      },
      ...
    ]
  }
]，
```

When performing operations on the delegated ONT ID, the ONT ID of the delegate(s) need to provide valid digital signatures conforming to the control logic.

The delegate can link public keys for the delegated ONT ID by setting `publicKey` property, and can also set `authentication` property, thus turning it into self-management mode. A self-managed ONT ID cannot be switched to delegated mode.

### Recovery Mechanism

ONT ID Documents use an **OPTIONAL** `recovery` property to designate the recovery party.

In the event that the owner of the ONT ID lost the private key, the recovery person can help the owner to reset the private key. The recovery person can add and delete public keys from `authentication` of that ONT ID and update the settings for the recovery person.

Only a self-managed ONT ID can designate other ONT IDs as the recovery party.

The recovery person can use the method of group management, the rules of which are the same as the management group of delegate. The recovery person needs to provide valid digital signatures in conformity with the control logic to perform any operation.

Below is a specific example, representing that either one of `ont:AXjJnU1TJViks4KUGQruiXwkKznwVpz7Z9` and `did:ont:AKwf6DvKFSBxhsmhjGCvJgaxHvCEQmpZZv` can perform the recovery operation.

```javascript
"recovery": [
  {
    "threshold": 1,
    "members": ["did:ont:AXjJnU1TJViks4KUGQruiXwkKznwVpz7Z9", "did:ont:AKwf6DvKFSBxhsmhjGCvJgaxHvCEQmpZZv"]
  }
]，
```

### Service Information

ONT ID Documents use an **optional** `service` to specify the service property.

ONT ID allows entities to add services to specify the information of a service related to that ONT ID, including types of service and service endpoints.

This part is derived from [W3C DIDs specification](https://www.w3.org/TR/did-core/#services).

Below is a specific example:

```javascript
{
  ...
  "service": [
    {
      "id": "did:ont:AderzAExYf7yiuHicVLKmooY51i2Cdzg72#some-service",
      "type": "SomeServiceType",
      "serviceEndpint": "Some URL"
    }
  ]
}
```

### Additional Properties

ONT ID Documents include an **OPTIONAL** `attribute` to link a set of ONT ID-related properties.

The owner or delegate of the ONT ID can add, modify or delete additional properties.

Each property **MUST** include the fields of `key`, `value`, and `type`.

* `key` as the identifier of the property,
* `type` denotes the type of the property,
* `value` is the content of the property.

`attribute` can include 100 properties at most.

There is a limit on the length of the property's field. The maximum lengths of the `key`, `value`, and `type` fields are 80 bytes, 64 bytes, and 512K bytes respectively.

For example, `did:ont:AderzAExYf7yiuHicVLKmooY51i2Cdzg72` contains a property:

```
key: "some-attribute"
type: "some-type"
value: "some-value"
```

The property is then expressed in the ONT ID Document as follows:

```javascript
{
  "id": "did:ont:AderzAExYf7yiuHicVLKmooY51i2Cdzg72",
  "attribute" : [
    {
      "key": "some-attribute",
      "type": "some-type",
      "value": "some-value"
    },
  ]
}
```

The types and the specific content of the additional properties are not covered in this specification and should be defined by the application layer.

Below is a specific example:

```javascript
{
  "attribute": [
    {
      "key": "age",
      "type": "number",
      "value": 18
    },
  ]
}
```

### Created

ONT ID Documents **SHOULD** include a `created` property to specify the time of creation.

This part is derived from [W3C DIDs specification](https://www.w3.org/TR/did-core/#services).

Below is a specific example:

```javascript
{
  "created": "2018-06-30T12:00:00Z"
}
```

### Updated

ONT ID Documents **SHOULD** include an `updated` property to specify a timestamp of the most recent change.

This part is derived from [W3C DIDs specification](https://www.w3.org/TR/did-core/#services).

Below is a specific example:

```javascript
{
  "updated": "2019-06-30T12:00:00Z"
}
```

### Proof of Integrity

ONT ID Documents **MAY** include a `proof` property to prove the integrity of that ONT ID Document.

This part is derived from [W3C DIDs specification](https://www.w3.org/TR/did-core/#services).

Below is a specific example:

```javascript
{
  "proof": {
    "type": "LinkedDataSignature2015",
    "created": "2020-02-02T02:02:02Z",
    "creator": "did:ont:AderzAExYf7yiuHicVLKmooY51i2Cdzg72#keys-1",
    "signatureValue": "QNB13Y7Q9...1tzjn4w=="
  }
}
```

As of now, the `proof` property has not been fully implemented yet.

## Appendix

Below is a simple example of an ONT ID Document:

```javascript
{
  "@context": ["https://www.w3.org/ns/did/v1", "https://ontid.ont.io/did/v2"],
  "id": "did:ont:AderzAExYf7yiuHicVLKmooY51i2Cdzg72",
  "publicKey": [
    {
      "id": "did:ont:AderzAExYf7yiuHicVLKmooY51i2Cdzg72#keys-1",
      "type": "EcdsaSecp256r1VerificationKey2019",
      "controller": "did:ont:AderzAExYf7yiuHicVLKmooY51i2Cdzg72",
      "publicKeyHex": "02a545599850544b4c0a222d594be5d59cf298f5a3fd90bff1c8caa095205901f2"
    }
  ],
    "authentication": [
    "did:ont:AderzAExYf7yiuHicVLKmooY51i2Cdzg72#keys-1"
  ]
}
```

## References

**\[W3C-DID]**\
Decentralized Identifiers (DIDs) v1.0. W3C. Mar 2020. Working Draft. URL: <https://www.w3.org/TR/did-core/>

**\[RFC2119]**\
Key words for use in RFCs to Indicate Requirement Levels. S. Bradner. IETF. March 1997. Best Current Practice. URL: <https://tools.ietf.org/html/rfc2119>

**\[RFC3986]**\
Uniform Resource Identifier (URI): Generic Syntax. T. Berners-Lee; R. Fielding; L. Masinter. IETF. JANUARY 2005. Standards Track. URL: <https://tools.ietf.org/html/rfc3986>

**\[BASE58]**\
The Base58 Encoding Scheme. Manu Sporny. IETF. December 2019. Internet-Draft. URL: <https://tools.ietf.org/html/draft-msporny-base58>

## ONT ID Contract API

Please follow the link below for the contract API reference.

{% content-ref url="../../../developer-tools/api/ont-id-contract-api" %}
[ont-id-contract-api](https://docs.ont.io/developer-tools/api/ont-id-contract-api)
{% endcontent-ref %}