ONT ID Contract API

ONT ID 2.0 Contract API Reference

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 and extends the definition and features on its basis.

Terminology and Pre-requisites

This document assumes a fair understanding of the ONT ID Specification v2.0.

Contract Implementation

ONT ID management features are implemented by the native contracts deployed on the Ontology blockchain.

ONT ID management contract address is 0x0000000000000000000000000000000000000003.

Data Structure

ONT ID management involves dealing with the following data structures:

  • Manager Group:

Group {
threshold // Member threshold, integer
members // Member array
}

Each element of the member array is a string. Based on whether the first 8 characters are did:ont:, it can be established whether the element is an ONT ID or a nested group. If the element is an ONT ID, it must be a registered, self-governed ONT ID.

  • Signer:

Signer {
id // Signer ONT ID
index // Signer public key index
}
  • Attributes:

Attribute {
key // Attribute key, byte string
type // Attribute type, byte string
value // Attribute value, byte string
}

API Definition

ONT ID Registration

Registering a self-governed ONT ID

Method name: regIDWithPublicKey

Parameters:

Sr. No.

Type

Description

0

Byte string

Respective ONT ID

1

Byte string

Owner public key

2

String

Public key access,all by default (optional) (new)

The method invocation needs to be signed using the private key that corresponds to the public key passed at the parameter. Upon successful registration, the provided public key will be linked to the respective ONT ID.

Trigger event: ("Register", ONT ID)

Register a proxy controlled ONT ID

Method name: regIDWithController

Parameters:

Sr. No.

Type

Description

0

Byte string

Respective ONT ID

1

Byte string

Proxy controller

2

Integer/Byte string

Public key serial no./serialized signer array

Parameter no. 1 can be an ONT ID, or a serialized manager group structure. The first 8 characters can be used to differentiate between the two.

The proxy controller needs to sign the action in order to invoke this method. If the controller is a single ONT ID, parameter no. 2 is the public key used to verify the signature; and if the parameter is a manager group, parameter no. 2 is a serialized array that contains the list of signers.

Trigger event: ("Register", ONT ID)

ONT ID Cancellation

Cancelling a self-governed ONT ID

Method name: revokeID

Parameters:

Sr. No.

Type

Description

0

Byte string

Respective ONT ID

1

Integer

Owner public key serial no.

Trigger event: ("Revoke", ONT ID)

Cancelling a proxy controlled ONT ID

Method name: revokeIDByController

Parameters:

Sr. No.

Type

Description

0

Byte string

Respective ONT ID

1

Integer/Byte string

Public key serial no./serialized signer array

Trigger event: ("Revoke", ONT ID)

Authorized Operations

Removing a controller

Method name: removeController

Parameters:

Sr. No.

Type

Description

0

Byte string

ONT ID

1

Integer

Owner public key serial no.

The invocation action for this method needs to be signed by the respective ONT ID owner. The signature is verified using the public key serial no. passed as parameter no. 1.

Trigger event: ("RemoveController", ONT ID)

Setting a recovery method

Method name: setRecovery

Parameters:

Sr. No.

Type

Description

0

Byte string

ONT ID

1

Byte string

Recoverer, serialized manager group array

2

Integer

Signature verification public key serial no.

The invocation action for this method needs to be signed by the respective ONT ID owner. The signature is verified using the public key serial no. passed as parameter no. 2.

Trigger event: ("Recovery", "set", ONT ID, JSON format recoverer details)

Update recoverer

Method name: updateRecovery

Parameters:

Sr. No.

Type

Description

0

Byte string

ONT ID

1

Byte string

New recoverer, serialized manager group array

2

Byte string

Serialized signer array

The invocation action for this method needs to be signed by the original recoverer.

Trigger event: ("Recovery", "update", ONT ID, JSON format new recoverer details)

Delete recoverer

Method name: removeRecovery

Parameters:

Sr. No.

Type

Description

0

Byte string

ONT ID

1

Integer

Signature verification public key serial no.

The invocation action for this method needs to be signed by the respective ONT ID owner. The signature is verified using the public key serial no. passed as parameter no. 1.

Trigger event: ("Recovery", "remove", ONT ID, JSON format new recoverer details)

Public Key Operations

Owner adds public key

Method name: addKey

Parameters:

Sr. No.

Type

Description

0

Byte string

ONT ID

1

Byte string

Public key to be added

2

Byte string

Verification public key

3

Byte string

Public key controller, current ID by default (optional) (new)

The invocation action for this method needs to be signed by the respective ONT ID owner. The signature is verified using the public key passed as parameter no. 2. The verification public key must already be linked to this ONT ID.

Trigger event: ("PublicKey", "add", ONT ID, new public key, new public key serial no.)

Owner adds public key by index

Method name: addKeyByIndex

Parameters:

Sr. No.

Type

Description

0

Byte string

ONT ID

1

Byte string

Public key to be added

2

Integer

Signature verification public key serial no.

3

Byte string

Public key controller, current ID by default (optional) (new)

The invocation action for this method needs to be signed by the respective ONT ID owner. The signature is verified using the public key serial no. passed as parameter no. 2. The verification public key must already be linked to this ONT ID.

Trigger event: ("PublicKey", "add", ONT ID, new public key, public key serial no.)

Owner removes a public key

Method name: removeKey

Parameters:

Sr. No.

Type

Description

0

Byte string

ONT ID

1

Byte string

Public key to be removed

2

Byte string

Verification public key

The invocation action for this method needs to be signed by the respective ONT ID owner. The signature is verified using the public key passed as parameter no. 2. The verification public key must already be linked to this ONT ID.

Trigger event: ("PublicKey", "remove", ONT ID, public key to be removed, public key serial no.)

Owner removes public key using index

Method name: removeKeyByIndex

Parameters:

Sr. No.

Type

Description

0

Byte string

ONT ID

1

Byte string

Public key to be removed

2

Integer

Signature verification public key serial no.

The invocation action for this method needs to be signed by the respective ONT ID owner. The signature is verified using the public key serial no. passed as parameter no. 2. The verification public key must already be linked to this ONT ID.

Trigger event: ("PublicKey", "remove", ONT ID, public key to be removed, public key serial no.)

Controller adds public key

Method name: addKeyByController

Parameters:

Sr. No.

Type

Description

0

Byte string

ONT ID

1

Byte string

Public key to be added

2

Integer/Byte string

Public key serial no./serialized signer array

3

Byte string

Public key controller, current ID by default (optional) (new)

The proxy controller needs to sign the action in order to invoke this method. If the controller is a single ONT ID, parameter no. 2 is the public key used to verify the signature; and if the parameter is a manager group, parameter no. 2 is a serialized array that contains the list of signers.

Trigger event: ("PublicKey", "add", ONT ID, new public key, new public key serial no.)

Controller removes a public key

Method name: removeKeyByController

Parameters:

Sr. No.

Type

Description

0

Byte string

ONT ID

1

Integer

Serial no. of the public key to be removed

2

Integer/Byte string

Public key serial no./serialized signer array

The proxy controller needs to sign the action in order to invoke this method. If the controller is a single ONT ID, parameter no. 2 is the public key used to verify the signature; and if the parameter is a manager group, parameter no. 2 is a serialized array that contains the list of signers.

Trigger event: ("PublicKey", "remove", ONT ID, public key to be removed, public key serial no.)

Recoverer adds a public key

Method name: addKeyByRecovery

Parameters:

Sr. No.

Type

Description

0

Byte string

ONT ID

1

Byte string

Public key to be added

2

Byte string

Serialized signer array

3

Byte string

Public key controller, current ID by default (optional) (new)

The invocation action for this method needs to be signed by the recoverer.

Trigger event: ("PublicKey", "add", ONT ID, new public key, public key serial no.)

Recoverer removes a public key

Method name: removeKeyByRecovery

Parameters:

Sr. No.

Type

Description

0

Byte string

ONT ID

1

Integer

Serial no. of the public key to be removed

2

Byte string

Serialized signer array

The invocation action for this method needs to be signed by the recoverer.

Trigger event: ("PublicKey", "remove", ONT ID, Public key to be removed, public key serial no.)

Verification Public Key Operations

Owner adds new verification public key

Method name: addNewAuthKey (new)

Parameters:

Sr. No.

Type

Description

0

Byte string

ONT ID

1

Byte string

Public key data

3

Integer

Signing public key serial no.

Public key data is as follows:

NewPublicKey {
PublicKey
Controller // Self ONT ID by default (optional)
}

A serial no. is automatically allocated to the public key upon successful addition.

Trigger event: ("AuthKey", "add", ONT ID, public key serial no.)

Recoverer adds new verification public key

Method name: addNewAuthKeyByRecovery (new)

Parameters:

Sr. No.

Type

Description

0

Byte string

ONT ID

1

Byte string

Public key data

3

Byte string

Serialized signer array

Public key data is as follows:

NewPublicKey {
PublicKey
Controller // Self ONT ID by default (optional)
}

A serial no. is automatically allocated to the public key upon successful addition.

Trigger event: ("AuthKey", "add", ONT ID, public key serial no.)

Controller adds new verification public key

Method name: addNewAuthKeyByController (new)

Parameters:

Sr. No.

Type

Description

0

Byte string

ONT ID

1

Byte string

Public key data

3

Integer/Byte string

Public key serial no./serialized signer array

Public key data is as follows:

NewPublicKey {
PublicKey
Controller // Self ONT ID by default (optional)
}

A serial no. is automatically allocated to the public key upon successful addition.

Trigger event: ("AuthKey", "add", ONT ID, public key serial no.)

Owner assigns new verification public key

Method name: addNewAuthKey (new)

Parameters:

Sr. No.

Type

Description

0

Byte string

ONT ID

2

Integer

Public key serial no.

3

Integer

Signing public key serial no.

Trigger event: ("AuthKey", "add", ONT ID, public key serial no.)

Recoverer assigns new verification public key

Method name: addNewAuthKeyByRecovery (new)

Parameters:

Sr. No.

Type

Description

0

Byte string

ONT ID

2

Integer

Public key serial no.

3

Byte string

Serialized signer array

Trigger event: ("AuthKey", "add", ONT ID, public key serial no.)

Controller assigns new verification public key

Method name: addNewAuthKeyByController (new)

Parameters:

Sr. No.

Type

Description

0

Byte string

ONT ID

2

Integer

Public key serial no.

3

Integer/Byte string

Public key serial no./serialized signer array

Trigger event: ("AuthKey", "add", ONT ID, public key serial no.)

Owner removes a verification public key

Method name: removeAuthKey (new)

Parameters:

Sr. No.

Type

Description

0

Byte string

ONT ID

1

Integer

Serial no. of public verification key to be removed

2

Integer

Signing public key serial no.

Trigger event: ("AuthKey", "remove", ONT ID, public key serial no.)

Recoverer removes a verification public key

Method name: removeAuthKeyByRecovery (new)

Parameters:

Sr. No.

Type

Description

0

Byte string

ONT ID

1

Integer

Serial no. of public verification key to be removed

2

Byte string

Serialized signer array

Trigger event: ("AuthKey", "remove", ONT ID, public key serial no.)

Owner removes a verification public key

Method name: removeAuthKeyByController (new)

Parameters:

Sr. No.

Type

Description

0

Byte string

ONT ID

1

Integer

Serial no. of public verification key to be removed

2

Integer/Byte string

Public key serial no./serialized signer array

Trigger event: ("AuthKey", "remove", ONT ID, public key serial no.)

Service Entry Point Operations

Add new service entry point

Method name: addService (new)

Parameters:

Sr. No.

Type

Description

0

Byte string

ONT ID

1

Byte string

Service label

2

Byte string

Service details

3

Integer

Signing public key serial no.

Trigger event: ("Service", "add", ONT ID, service label)

Update serive entry point

Method name: updateService (new)

Parameters:

Sr. No.

Type

Description

0

Byte string

ONT ID

1

Byte string

Service label

2

Byte string

Service details

3

Integer

Signing public key serial no.

Trigger event: ("Service", "update", ONT ID, service label)

Remove service entry point

Method name: removeService (new)

Parameters:

Sr. No.

Type

Description

0

Byte string

ONT ID

1

Byte string

Service label

2

Byte string

Service details

3

Integer

Signing public key serial no.

Trigger event: ("Service", "remove", ONT ID, service label)

Context Operations

Adding custom context

Method name: addContext (new)

Parameters:

Sr. No.

Type

Description

0

Byte string

ONT ID

1

Array

Context list to be added

2

Integer

Signing public key serial no.

If a particular context in the list already exists for the respective ONT ID, it will be ignored.

Trigger event: ("Context", "add", ONT ID, context list to be added)

Removing custom context

Method name: removeContext (new)

Parameters:

Sr. No.

Type

Description

0

Byte string

ONT ID

1

Array

Context list to be removed

2

Integer

Signing public key serial no.

If a particular context in the list does not exist for the respective ONT ID, it will be ignored.

Trigger event: ("Context", "remove", ONT ID, context list to be removed)

Attribute Operations

Registering new ONT ID and adding attributes

Method name: regIDWithAttributes

Sr. No.

Type

Description

0

Byte string

ONT ID

1

Byte string

Owner public key

2

Attribute structure array

Attribute array

The invocation action for this method needs to be signed by the respective ONT ID owner. The signature is verified using the public key serial no. passed as parameter no. 1. The public key will be linked to the respective ONT ID upon successful registration, and the attributes passed using parameter no. 2 will be added to the ONT ID.

Trigger event: ("Register", ONT ID)

Owner adds attributes

Method name: addAttributes

Parameters:

Sr. No.

Type

Description

0

Byte string

ONT ID

1

Attribute structure array

Attribute array

2

Byte string

Verification public key

The invocation action for this method needs to be signed by the respective ONT ID owner. The signature is verified using the public key passed as parameter no. 2. The verification public key must already be linked to this ONT ID.

Trigger event: ("Attribute", "add", ONT ID, list of key-attribute pair to be added)

Owner adds attributes using index

Method name: addAttributesByIndex

Parameters:

Sr. No.

Type

Description

0

Byte string

ONT ID

1

Attribute structure array

Attribute array

2

Integer

Signature verification public key serial no.

The invocation action for this method needs to be signed by the respective ONT ID owner. The signature is verified using the public key serial no. passed as parameter no. 2. The verification public key must already be linked to this ONT ID.

Trigger event: ("Attribute", "add", ONT ID, list of key-attribute pair to be added)

Owner removes attributes

Method name: removeAttribute

Parameters:

Sr. No.

Type

Description

0

Byte string

ONT ID

1

Byte string

Keys for attributes to be removed

2

Byte string

Verification public key

The invocation action for this method needs to be signed by the respective ONT ID owner. The signature is verified using the public key passed as parameter no. 2. The verification public key must already be linked to this ONT ID.

Trigger event: ("Attribute", "remove", ONT ID, list of keys for attributes to be removed)

Owner removes attributes using index

Method name: removeAttributeByIndex

Parameters:

Sr. No.

Type

Description

0

Byte string

ONT ID

1

Byte string

Keys for attributes to be removed

2

Integer

Signature verification public key serial no.

The invocation action for this method needs to be signed by the respective ONT ID owner. The signature is verified using the public key serial no. passed as parameter no. 2. The verification public key must already be linked to this ONT ID.

Trigger event: ("Attribute", "remove", ONT ID, list of keys for attributes to be removed)

Controller adds attributes

Method name: addAttributesByController

Parameters:

Sr. No.

Type

Description

0

Byte string

ONT ID

1

Attribute structure array

Attribute array

2

Integer/Byte string

Public key serial no./serialized signer array

The proxy controller needs to sign the action in order to invoke this method. If the controller is a single ONT ID, parameter no. 2 is the public key used to verify the signature; and if the parameter is a manager group, parameter no. 2 is a serialized array that contains the list of signers.

Trigger event: ("Attribute", "add by controller", ONT ID, list of key-attribute pair to be added)

Controller removes attributes

Method name: removeAttributeByController

Parameters:

Sr. No.

Type

Description

0

Byte string

ONT ID

1

Byte string

Keys for attributes to be removed

2

Integer/Byte string

Public key serial no./serialized signer array

The proxy controller needs to sign the action in order to invoke this method. If the controller is a single ONT ID, parameter no. 2 is the public key used to verify the signature; and if the parameter is a manager group, parameter no. 2 is a serialized array that contains the list of signers.

Trigger event: ("Attribute", "remove by controller", ONT ID, keys for attributes to be removed)

Verification Methods

Signature verification

Method name: VerifySignature

Parameters:

Sr. No.

Type

Description

0

Byte string

ONT ID

1

Integer

Public key serial no.

The transaction invoked by the method must contain the verified signature. The verification public key serial no. is passed as the parameter no. 1.

Response: True/False

Verifying controller signature

Method name: VerifyController

Parameters:

Sr. No.

Type

Description

0

Byte string

ONT ID

1

Integer/signer structure array

Verification public key serial no./Signer list

If the controller is a single ONT ID, parameter 1 array contains a single element. If it is a manager group, the multiple signers need to be specified in the form of an array.

The transaction invoked by the method must contain the verified signature. If the controller is single ONT ID, the verification public key serial no. is passed as the parameter no. 2. If it is a manager group, parameter no. 2 is an array that contains signers.

Response: True/False

Query Interface

Querying ONT ID Document

Method name: getDocumentJson (new)

Parameters:

Sr. No.

Type

Description

0

byte array

Query ONT ID

Response: Document data corresponding to queried ONT ID. The data is of JSON-LD format.

For specific details on ONT ID Document please refer to ONT ID Specification v2.0.

Query public keys linked to an ONT ID

Method name: getPublicKeysJson

Parameters:

Sr. No.

Type

Description

0

byte array

Query ONT ID

Response: Serialized public key list. Contains the currently valid public keys.

Query key state

Method name: getKeyState

Parameters:

Sr. No.

Type

Description

0

byte array

Query ONT ID

1

int

Public key serial no.

Response: State of the public key with the passed serial no. ("not exist", "in use", "revoked")

Query ONT ID attributes

Method name: getAttributesJson

Parameters:

Sr. No.

Type

Description

0

byte array

Query ONT ID

Response: Serialized attribute list for specied ONT ID.

Query ONT ID services

Method name: getServiceJson (new)

Parameters:

Sr. No.

Type

Description

0

byte array

Query ONT ID

1

byte array

Service label

Response: Service details for the specified ONT ID in JSON format.

Query ONT ID controllers

Method name: getControllerJson (new)

Parameters:

Sr. No.

Type

Description

0

byte array

Query ONT ID

Response: Controller related data for the passed ONT ID.

Deprecated Methods

The following methods are now deprecated, but are still part of the interface in order to prevent legacy data compatibility issues.

  • addRecovery

  • changeRecovery

  • getDDO

Storage Description

All the data is stored within the contract, and the storage keys are prefixed with the contract address. For convenient reference, the storage keys below are listed without the prefixes.

Legend:

  • + connects the front and back byte string

  • ID represents the ONT ID

Storage Content

Key

Value

Description

Registration token

ID

0x01

Serves as the token that marks the existence of a ONT ID

Public key

ID+0x01

Public key list

Records the public keys linked to the ONT ID, including the ones that have been cancelled

Attributes

ID+0x02

Attribute list

Stores ONT ID attributes in the form of linked list, facilitating removal operation

Recoverer

ID+0x03

Manager group structure entity

Stored structure is the same as the interface input

Controller

ID+0x04

ONT ID

Manager group structure entity

Service

ID+0x05

Service list

Stores ONT ID services in the form of linked list, facilitating removal operation

Creation time

ID+0x06

Block generation time

Time of block generation by encapsulating the transactions

Modify time

ID+0x07

Block generation time

Time of block generation by encapsulating the transactions

Proof

ID+0x08

Proof

Context

ID+0x09

Content list

Stores custom context in the form of an array

Version no.

0x00

0x01

Indicates the current contract storage version, used to deal with incompatibilities, current value is set to 1

References

[ONT-ID] ONT ID Specification v2.0