Naming API

Moera Naming API is based on JSON-RPC protocol.

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

Calls

put

Register or update the name. See 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, if the current generation of the name is updated - 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
int validFrom, if signingKey is not null, or the timestamp of the current key otherwise
byte[] previousDigest

getStatus

Get current status of the operation.

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

getCurrent

Get current information about the given generation of the name.

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

getCurrentForLatest

Get current information about the latest generation of the name.

Parameters:
String name
Returns:
RegisteredNameInfo - or null, if the name was never registered

isFree

Check if the given name is available for registration

Parameters:
String name
Returns:
boolean - true, if the name is free, false otherwise


Structures

OperationStatusInfo

Type Name Description
UUID operationId
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
int generation the generation of the name that was created or updated by the operation, if the operation succeeded

RegisteredNameInfo

Type Name Description
String name
int generation
boolean latest true if this is the latest generation of the name, false otherwise
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 deadline the moment in time when the name may become available for registration by anybody
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.


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 generation.not-next generation must be the next after the current one