API

Settings

Numerous settings are available when initialising the core API via Onz-JS. Please see the examples below.

The provision of settings is optional, therefore initialising without any arguments var ONZ = onz.api(); yields the defaults.

Example 1 Random node, testnet with port 10998

                                        
var options = {
    ssl: false, // Default false. Set to true to enable the https instead of http protocol.
    node: '', // Default randomNode. Insert a node without http or https protocol. Use ssl option in order to set http or https.
    randomPeer: true, // Default true. Onz-js automatically connects to a random peer to get onz blockchain information. Set to false to disable this behaviour.
    testnet: true, // Default false. Set to true to use the testnet. Set to false to use the mainnet.
    port: '10998', // Default 11000. Enter the port as the protocol http(s)://node:port - can be any string.
    bannedPeers: [], // Default empty. Array of peers that should not be connected to. Without http(s) or port.
};

var ONZ = onz.api(options);

Example 2 Restricted to localhost, port 11000, no SSL

                                        
var options = {
    ssl: false, // default false
    node: 'localhost', // write node without http:// or port
    randomPeer: false, // default true
    testnet: false, // default false
    port: '11000', // default 11000
    bannedPeers: [], // default empty

};

var ONZ = onz.api(options);

API Functions

getAccount

Example Get single account by address

                                        
onz.api().getAccount(accountAddress, callback);

listActiveDelegates

Example Get the first 5 active delegates

                                        
onz.api().listActiveDelegates(5, callback);

listStandbyDelegates

Example Get the first 6 standby delegates

                                        
onz.api().listStandbyDelegates(6, callback);

searchDelegateByUsername

Example Search for delegates by username

                                        
onz.api().searchDelegateByUsername('username', callback);

getBlock

Example Get a single block by id

                                        
onz.api().getBlock(blockId, callback);

listBlocks

Example Get a list of blocks

                                        
onz.api().listBlocks(amount, callback);

listForgedBlocks

Example List the forged blocks using a given public key

                                        
onz.api().listForgedBlocks(publicKey, callback);

getTransaction

Example Get a single transaction by id

                                        
onz.api().getTransaction(transactionId, callback);

listTransactions

Example List transactions for a given address

                                        
onz.api().listTransactions(address, limit, offset, callback);

Address: The Onz address for recipient and sender of the transactions.

Limit: The number of transactions to retrieve. Minimum: 1, Maximum: 1000.

Offset: The number of records to offset the query from, e.g. a given offset of 10 excludes the first 10 records from the yielded results.

listVotes

Example List votes placed by a given address

                                        
onz.api().listVotes(address, callback);

listVoters

Example List votes received by a given address

                                        
onz.api().listVoters(publicKey, callback);

listMultisignatureTransactions

Example Lists all pending multisignature transactions

                                        
onz.api().listMultisignatureTransactions(callback);

getMultisignatureTransaction

Example Lists a multisignature transaction by a given transaction ID

                                        
onz.api().getMultisignatureTransaction('transactionID', callback);

Network Functions

sendRequest

sendRequest gives full access to the Onz core API. It accepts any valid endpoint and parameters.

Example GET - Retreive the current block height

                                        

var onzBlockheight = onz.api().sendRequest('blocks/getHeight', function (data) {
    var str = JSON.stringify(data);
    document.getElementById('output').innerHTML = str;
});

Example POST - Open a new account

                                        
var onzNewAccount = onz.api().sendRequest('accounts/open', { secret: 'my secret passphrase' }, function (data) {
    var str = JSON.stringify(data);
    document.getElementById('output').innerHTML = str;
});

The provided secret is intercepted and never transmitted over the network.

getNethash

Example Get a unique hash for the currently selected network

                                        
var ONZ = onz.api().getNethash();
Returning 
                                        
{
    'Content-Type': 'application/json',
    'nethash': '463aeac28885fa5be9efc4d095900f622e3d9efac8c9317b7f1e8fe804d5a039',
    'broadhash': '463aeac28885fa5be9efc4d095900f622e3d9efac8c9317b7f1e8fe804d5a039',
    'os': 'onz-js-api',
    'version': '1.0.0',
    'minVersion': '>=0.5.0',
    'port': this.port
}

setNode

Example Set the currently selected node

                                        
var ONZ = onz.api().setNode('mynode.com');

Use ONZ.setNode(); without any arguments to automatically choose a new random node.

listPeers

Example Lists the peers configured for each network.

                                        
var ONZ = onz.api().listPeers();

Yields an object containing arrays of network categorised peers:

{
    official: [...],
    ssl: [...],
    testnet: [...],
    localhost: [...]

}

setSSL

Example Enable the SSL connecton protocol

                                        
var ONZ = onz.api().setSSL(true); // or false

setTestnet

Example Toggle between the testnet and mainnet

                                        
var ONZ = onz.api().setTestnet(true); // or false

Crypto

getKeys

Example Get a public and private keypair from a given secret

                                        
var keys = onz.crypto.getKeys('secret');
Returning 
                                        
{
    publicKey: '5d036a858ce89f844491762eb89e2bfbd50a4a0a0da658e4b2628b25b117ae09',
    privateKey: '2bb80d537b1da3e38bd30361aa855686bde0eacd7162fef6a2…44491762eb89e2bfbd50a4a0a0da658e4b2628b25b117ae09'
}

getAddress

Example Get the ONZ address from a given public key

                                        
var keys = onz.crypto.getAddress('5d036a858ce89f844491762eb89e2bfbd50a4a0a0da658e4b2628b25b117ae09');
Returning 
                                        
18160565574430594874Z

getBytes

Example Get the number of bytes for a transaction object

                                        
var transactionBytes = onz.crypto.getBytes(transactionObject);

getHash

Example Get the hash of a transaction object

                                        
var transactionHash = onz.crypto.getHash(transactionObject);

getId

Example Get the unique identifier of a transaction object

                                        
var transactionId = onz.crypto.getId(transactionObject);

getFee

Example Get the fees for a transaction object

                                        
var transactionFee = onz.crypto.getFee(transactionObject);

sign

Example Sign a transaction object using a given keypair

                                        
var transactionSignature = onz.crypto.sign(transactionObject, keypair);

secondSign

Example Add a second signature to a transaction object using a given keypair

                                        
var transactionSignature = onz.crypto.secondSign(transactionObject, keypair);

multiSign

Example Add a multisignature to a transaction object using a given keypair

                                        
var transactionSignature = onz.crypto.multiSign(transactionObject, keypair);

getKeys

Example Get a public and private keypair from a given secret

                                        
var keypair = onz.crypto.getKeys(secret);

verify

Example Verify the signature of transaction object

                                        
var verification = onz.crypto.verify(transactionObject);

verifySecondSignature

Example Verify the second signature of a transaction object

                                        
var verification = onz.crypto.verifySecondSignature(transactionObject);

fixedPoint

Example Convert a given floating point ONZ amount to an integer representation

                                        
var bigAmount = onz.crypto.fixedPoint(amount);

bufferToHex

Example Convert a buffer to a hex string

                                        
var hexString = onz.crypto.bufferToHex(buffer);

hexToBuffer

Example Convert a hex string to buffer

                                        
var buffer = onz.crypto.hexToBuffer(hexString);

useFirstEightBufferEntriesReversed

Example Cut the first 8 bytes of a given buffer and reverses them

Used to calculate unique identifiers.

                                        
var rawId = onz.crypto.useFirstEightBufferEntriesReversed(buffer);

signMessageWithSecret

Example Signs a message (not encrypted) using a plain message and a secret

                                        
var messageSignature = onz.crypto.signMessageWithSecret(message, secret);

printSignedMessage

Example Formats the given plain message, signed message and public key

                                        
var printSignedMessage = onz.crypto.printSignedMessage(message, signedMessage, publicKey);
                                        
                                    
                                        
-----BEGIN ONZ SIGNED MESSAGE-----
<message>
-----BEGIN SIGNATURE-----
<publicKey>
<signature>
-----END ONZ SIGNED MESSAGE-----

In order maintain formatting it is advised to wrap the resulting output within a pre tag.

signAndPrintMessage

Example Signs a message (not encrypted) using a plain message and a secret, then prints it

Combines the signMessageWithSecret and printSignedMessage functions.

                                        
var printSignedMessage = onz.crypto.printSignedMessage(message, secret);

verifyMessageWithPublicKey

Example Verify a signed message using a given public key

Returns null if invalid, or the original message if valid.

                                        
var verifySignedMessage = onz.crypto.verifyMessageWithPublicKey(signedMessage, publicKey);

encryptMessageWithSecret

Example Encrypts a message with the given secret and recipient PublicKey

Where message is a UTF-8 message, secret a passphrase and recipientPublicKey the publicKey in hex.

                                        
var encrypted = onz.crypto.encryptMessageWithSecret(message, secret, recipientPublicKey);
Returning 
                                        
{
    encryptedMessage: encryptedMessage(hex),
    nonce: nonce(hex)
}

Returns an object with the encrypted message and a nonce. Both are necessary in order to decrypt the message.

decryptMessageWithSecret

Example Decrypts a message with secret, senderPublicKey and the nonce of the message

Where encrypted message is the hex format of the encrypted message, nonce also hex. The secret as the passphrase of the recipient and the sender publicKey in hex.

                                        
var encrypted = onz.crypto.decryptMessageWithSecret(encryptedMessage, nonce, secret, senderPublicKey);
Returning 
                                        
Original Message

If successfull, returns the plain text of the senders message.

getPrivateAndPublicKeyFromSecret

Example Get a hex representation of a keypair from a given secret

                                        
var keypair = onz.crypto.getPrivateAndPublicKeyFromSecret(secret);
Returning 
                                        
{
    publicKey: publicKey(hex),
    privateKey: privateKey(hex)
}

getRawPrivateAndPublicKeyFromSecret

Example Get a raw byte representation of a keypair from a given secret

                                        
var keypairBytes = onz.crypto.getRawPrivateAndPublicKeyFromSecret(secret);
Returning 
                                        
{
    publicKey: publicKey(bytes),
    privateKey: privateKey(bytes)
}

getAddressFromPublicKey

Example Get the address from a given public key

                                        
var address = onz.crypto.getAddressFromPublicKey(publicKeyHex);

getSha256Hash

Example Get the sha256 hash from a given string

                                        
var sha256Hash = onz.crypto.getSha256Hash(string);

Transactions

Create Transaction

Example Create a signed "balance transfer" transaction object

                                        
var amount      = 1000 * Math.pow(10, 8); // 100000000000
var transaction = onz.transaction.createTransaction('1859190791819301L', amount, 'passphrase', 'secondPassphrase');
Returning 
                                        
{
    type: 0, // Transaction type. 0 = Normal transaction.
    amount: 100000000000, // The amount to send expressed as an integer value.
    asset: {}, // Transaction asset, dependent on tx type.
    fee: 100000000, // 0.1 ONZ expressed as an integer value.
    id: '500224999259823996', // Transaction ID.
    recipientId: '1859190791819301L', // Recipient ID.
    senderPublicKey: '56e106a1d4a53dbe22cac52fefd8fc4123cfb4ee482f8f25a4fc72eb459b38a5', // Sender's public key.
    signSignature: '03fdd33bed30270b97e77ada44764cc8628f6ad3bbd84718571695262a5a18baa37bd76a62dd25bc21beacd61eaf2c63af0cf34edb0d191d225f4974cd3aa509', // Sender's second passphrase signature.
    signature: '9419ca3cf11ed2e3fa4c63bc9a4dc18b5001648e74522bc0f22bda46a188e462da4785e5c71a43cfc0486af08d447b9340ba8b93258c4c7f50798060fff2d709', // Transaction signature.
    timestamp: 27953413 // Based on UTC time of genesis since epoch.
}

Create Vote

Example Create a signed "delegate vote" transaction object

                                        
var transaction = onz.vote.createVote('secret', ['+58199578191950019299181920120128129'], 'secondSecret');

Create Dapp

Example Create a signed "dapp registration" transaction object

                                        
var options = {
    category: 0,
    name: 'Onz Guestbook',
    description: 'The official Onz guestbook',
    tags: 'guestbook message sidechain',
    type: 0,
    link: 'https://github.com/MaxKK/guestbookDapp/archive/master.zip',
    icon: 'https://raw.githubusercontent.com/MaxKK/guestbookDapp/master/icon.png'
};

var transaction = onz.dapp.createDapp('secret', 'secondSecret', options);

Create Delegate

Example Create a signed "delegate registration" transaction object

                                        
var transaction = onz.delegate.createDelegate('secret', 'username', 'secondSecret');

Create Second Signature

Example Create a signed "second signature registration" transaction object

                                        
var transaction = onz.signature.createTransaction('secret', 'secondSecret');

Create Multisignature Account

Example Create a signed "multisignature account" transaction object

                                        
var secret = 'myprivatesecret';
var secondSecret = '';
var keysgroup = ['+publicKey1', '+publicKey2']; // Add publicKeys for multisignature.
var lifetime = 20; // Time in hours until transactions will be invalid.
var min = 2; // Minimum signatures so that a transaction is valid.
var transaction = onz.multisignature.createMultisignature(secret, secondSecret, keysgroup, lifetime, min);

Sign Multisignature Transaction

Example Sign a multisignature transaction object

                                        
var signature = onz.multisignature.signTransaction(transaction, secret);