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
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)