Logo Decentralized Social Network

Naming API

Moera Naming API is based on JSON-RPC protocol. Until the API is stabilized, it may be changed in various ways and backward compatibility is not guaranteed.

timestamp below is the number of seconds that passed since 01-01-1970 00:00:00 in UTC timezone.

Calls

put(name, generation, updatingKey, nodeUri, signingKey, validFrom, previousDigest, signature)

Register or update the name. See Architecture Overview for the detailed description of the algorithm.

Parameters:
String name – the name to be registered/updated. Required.
int generation – the name generation to be registered/updated. Required.
byte[] updatingKey – the public key for verifying signatures of further updates of the name. May be null – the current key is preserved in this case.
String nodeUri – URI of the REST API endpoint of the node to which the name is assigned. May be null – the current URI is preserved in this case.
byte[] signingKey – the public key of the name owner. May be null – the current key is preserved in this case.
timestamp validFrom – the moment in time the owner's key is valid from. May be null, if signingKey is also null.
byte[] previousDigest – the unique identifier as reported by a naming server of the current state of the name. Used to detect the situations when the name was changed by someone else between sending the request and processing it. May be null, if the name was never registered before.
byte[] signature – the signature, if required, null otherwise.
Returns:
UUID – identifier of the operation that was created
Fingerprint: read more
Type Value
String name
int generation
byte[] updatingKey, if not null, or the current key otherwise
String nodeUri, if not null, or the current URI otherwise
byte[] signingKey, if not null, or the current key otherwise
timestamp validFrom, if signingKey is not null, or the timestamp of the current key otherwise
byte[] previousDigest

getStatus(operationId)

Get current status of the operation.

Parameters:
UUID operationId
Returns:
OperationStatusInfo – the operation status or null, if the operation ID is unknown

getCurrent(name, generation)

Get current information about the given generation of the name.

Parameters:
String name
int generation
Returns:
RegisteredNameInfo – the information or null, if the name/generation is not found

getPast(name, generation, at)

Get past information about the given generation of the name.

Parameters:
String name
int generation
timestamp at – the moment in time the information is related to
Returns:
RegisteredNameInfo – the information or null, if the name/generation did not exist at the given moment

isFree(name, generation)

Check if the given name is available for registration.

Parameters:
String name
int generation
Returns:
booleantrue, if the name is free, false otherwise

getSimilar(name)

Find a name that is close to the given name.

Parameters:
String name
Returns:
RegisteredNameInfo – information about the name or null, if no name found that is close enough

getAllKeys(name, generation)

Get the whole history of signing keys for the given name.

Parameters:
String name
int generation
Returns:
SigningKeyInfo[]

getAll(at, page, size)

Get the list of all registered names at the given moment. The list is returned in pages, one per call.

Parameters:
timestamp at – the moment in time the information is related to
int page – number of the page to be returned (starting from 0)
int size – size of the page
Returns:
RegisteredNameInfo[]

getAllNewer(at, page, size)

Get the list of all names registered after the given moment. The list is returned in pages, one per call.

Parameters:
timestamp at – the moment in time the information is related to
int page – number of the page to be returned (starting from 0)
int size – size of the page
Returns:
RegisteredNameInfo[]


Structures

OperationStatusInfo

Type Name Description
UUID operationId
String name the name that was created or updated by the operation
int generation the generation of the name that was created or updated by the operation
OperationStatus status the current status of the operation
timestamp added when the operation was added
timestamp completed when the operation was completed
String errorCode the error code, if the operation have been failed
String errorMessage the human-readable error description, if the operation have been failed

RegisteredNameInfo

Type Name Description
String name
int generation
byte[] updatingKey the public key for verifying signatures of further updates of the name
String nodeUri URI of the REST API endpoint of the node to which the name is assigned. May be absent.
timestamp created when the name was created
byte[] signingKey the public key of the name owner. May be null.
timestamp validFrom the moment in time the owner's key is valid from. May be absent, if signingKey is also absent.
byte[] digest a unique identifier of the current state of the name. May be transaction ID of the latest transaction with this name in the blockchain, or a cryptographic digest of the current state.

SigningKeyInfo

Type Name Description
byte[] key the public key
timestamp validFrom the moment in time the key is valid from


Enums

OperationStatus

This enum is used to designate the operation status both by the naming server and by the node.

Value Description
WAITING operation is waiting to be sent to the naming server
ADDED operation was accepted by the naming server
STARTED the naming server started to proceed the operation
SUCCEEDED operation completed successfully
FAILED operation failed
UNKNOWN operation status is unknown


Error codes

Code Name Description
1 name.empty name is empty
2 name.too-long name is too long
3 name.forbidden-chars name contains forbidden characters
4 node-uri.too-long nodeUri is too long
5 updating-key.empty updatingKey is empty
6 updating-key.wrong-length updatingKey has wrong length
7 signing-key.wrong-length signingKey has wrong length
8 valid-from.empty validFrom is empty
9 valid-from.before-name-created validFrom is before name creation
10 valid-from.too-far-in-past validFrom is too far in the past
11 signature.too-long signature is too long
12 signature.failed signature check failed
13 crypto.failure crypto configuration exception occured
14 previous-digest.wrong-length previousDigest has wrong length
15 previous-digest.incorrect previousDigest differs from the current one
16 generation.not-same generation must be the same as the current one
17 page.incorrect page number is incorrect
18 size.incorrect size number is incorrect
19 size.too-large size is too large